refactor: keep comments focused on contracts and constraints

.cargo/config.toml

@@ -1,14 +1,3 @@
-# The Module is the only crate here that builds for wasm32-unknown-unknown, and its Runtime Script
-# Host pulls piccolo -> ahash -> getrandom 0.3, which has NO backend on that target and refuses to
-# compile without one. getrandom 0.3 selects its backend by cfg, not by Cargo feature, so this file
-# is the only place the choice can live.
-#
-# "custom" means the Module supplies the implementation itself — see `runtime_script::fixed_entropy`
-# for the function and for why it is a fixed stream. The alternative, getrandom's `wasm_js` backend
-# (what the Runtime Script Prototype used to get a compile), emits wasm-bindgen imports that a SpacetimeDB host
-# cannot resolve, so a module built that way fails to instantiate.
-#
-# A `RUSTFLAGS` environment variable overrides this table wholesale. That failure is loud (getrandom
-# stops compiling), never silent.
+# SpacetimeDB cannot resolve wasm-bindgen imports; use the Module's custom entropy backend.
 [target.wasm32-unknown-unknown]
 rustflags = ['--cfg', 'getrandom_backend="custom"']

.claude/skills/fan-out/SKILL.md

@@ -52,8 +52,12 @@ Match model to ticket difficulty: the strongest tier for the tracer and the inte
 Work the **frontier** — the tickets whose blockers are all done:
 
 1. Run the tracer first, alone, and integrate it.
-2. Spawn one agent per unblocked ticket, concurrently, each in its own worktree so they cannot collide. Brief each agent to read the folder's `README.md` plus its own ticket file, then `/implement` it.
-3. Integrate the parallel branches, then run the integration ticket serially on the combined result.
+2. Spawn one agent per unblocked ticket, concurrently, each in its own worktree so they cannot collide.
+   Brief each agent to read its checkout's `AGENTS.md`, the folder's `README.md` and its own ticket,
+   then `/implement` it. Require the
+   [comment-review result](../../../CODING_STANDARDS.md#comment-review) in its handoff.
+3. Integrate the parallel branches, then run the integration ticket serially on the combined result,
+   including its comment review.
 
 If the harness cannot spawn agents, work the frontier yourself in the same order.
 

.claude/skills/file-pr/SKILL.md

@@ -9,6 +9,9 @@ metadata:
 
 Before filing, check whether a PR for this branch already exists. Review the diff locally against `origin/main` to make sure its contents match the goal.
 
+Complete the [comment review](../../../CODING_STANDARDS.md#comment-review) on that final diff and
+include its scope and result under verification in the PR description.
+
 PR titles usually become commit messages, so follow the repository's title conventions. Look at recently merged PRs and Git history for examples. Prefer a concise, human-readable title that explains why the change matters:
 
 BAD

.claude/skills/orchestrate-backlog/AGENT-BRIEFING.md

@@ -9,8 +9,11 @@ Lines to carry in every implementer dispatch prompt. The orchestrator pastes wha
 
 ## Verification
 
+- Read `AGENTS.md` in your checkout. Complete the
+  [comment review](../../../CODING_STANDARDS.md#comment-review) and include its scope and result in
+  your handoff.
 - Before excepting any failing test, confirm it fails identically on the unmodified base commit; report it as pre-existing with that evidence.
-- Format touched files individually (`rustfmt <file>` and inspect the diff). Repo-wide formatting rewrites ~75 files of pre-existing drift.
+- Format the files you change and run the formatting check in `docs/testing.md`.
 - Zero new clippy warnings in touched files; wasm check for module changes.
 
 ## Scope discipline

.claude/skills/pr-review/SKILL.md

@@ -48,6 +48,8 @@ changed lines. It must assess both the Spec and repository standards, and return
 - Concrete failure cases with file locations and supporting evidence. Separate demonstrated
   defects from hypotheses that need a check.
 - The smallest checks that could settle disputed behavior or missing coverage.
+- The [comment-review result](../../../CODING_STANDARDS.md#comment-review), with its scope and file
+  locations for findings.
 - Whether it is confident the outcome is complete, what supports that judgment, and what could
   still make the solution wrong. A clean diff or passing unit suite alone does not establish this.
 

.claude/skills/verify-lyracore/drive-benilla.sh

@@ -1,13 +1,4 @@
 #!/usr/bin/env bash
-# Run one scripted Benilla session against a LyraCore Realm and keep its evidence.
-#
-#   BENILLA_DIR=<benilla checkout> WOW_DATA=<1.12.1 Data dir> \
-#   WOW_USER=TEST WOW_PASS=test123 WOW_CHAR=Tester \
-#   WOW_PROBE_CHAT='.tele goldshire' WOW_PROBE_LUA='ProbeLog(GetZoneText())' \
-#     .claude/skills/verify-lyracore/drive-benilla.sh [exit-after-secs]
-#
-# Every other WOW_* variable passes through to Benilla. Output: $EVIDENCE (default
-# /tmp/lyracore-verify/<UTC stamp>) gets benilla.log, probe.log and shot.png. Exit code is Benilla's.
 set -uo pipefail
 
 : "${BENILLA_DIR:?set BENILLA_DIR to a Benilla checkout}"
@@ -16,7 +7,7 @@ secs=${1:-60}
 out=${EVIDENCE:-/tmp/lyracore-verify/$(date -u +%Y%m%dT%H%M%SZ)}
 mkdir -p "$out"
 
-# BENILLA_HOME keeps the run off the operator's own benilla-config (settings, saved variables).
+# BENILLA_HOME isolates this run from the Operator's saved settings.
 scratch=$(mktemp -d)
 trap 'rm -rf "$scratch"' EXIT
 

.github/ISSUE_TEMPLATE/config.yml

@@ -1,6 +1,3 @@
-# Blank issues stay enabled on purpose: the maintainers file most of the queue themselves, in the
-# expected/actual/how it shows/fix direction shape CONTRIBUTING.md describes, and the forms are
-# aimed at people reporting from the outside.
 blank_issues_enabled: true
 contact_links:
   - name: Troubleshooting guide

.github/PULL_REQUEST_TEMPLATE.md

@@ -41,6 +41,7 @@ In `.github/workflows/runtime-scripts.yml`, when the change reaches `datascripts
 
 Other checks:
 
+- [ ] Comment review per `CODING_STANDARDS.md#comment-review`: state the scope and result.
 - [ ] Module or schema changes: a plain `spacetime publish` against your local stack migrates cleanly (**never** `publish -c`)
 - [ ] `shellcheck --severity=warning` on any shell script you changed
 - [ ] Markdown links you added resolve

.github/workflows/module-durable.yml

@@ -1,8 +1,5 @@
 name: Module durable tests and Gateway bindings
 
-# Durable tests start private SpacetimeDB instances and publish the Module with test fixtures.
-# The Rust workflow's --lib run does not execute these ignored integration tests.
-
 on:
   pull_request:
   push:
@@ -16,7 +13,6 @@ permissions:
   contents: read
 
 jobs:
-  # Balance measured target durations, reserving time for each job's builds and Gateway checks.
   durable:
     runs-on: ubuntu-latest
     timeout-minutes: 30
@@ -40,16 +36,10 @@ jobs:
         if: matrix.shard != 2
         run: ./lyracore bindings
 
-      # Build failures report before any fixture starts. Each test process asks Cargo for the
-      # current artifact, caches its bytes, and publishes private copies through --bin-path.
       - name: Build the module wasm
         run: cargo build --release --target wasm32-unknown-unknown -p lyracore-module --features=debug_reducers,package_test_fixture
 
-      # Each test owns a whole database process, so the thread cap is a memory bound, not a CPU one.
-      #
-      # Deadmines fixtures need the separately installed Package's reducers.
-      # `lethal_floor`'s ranged phase races the module's own cast-event sweep and health regen, and
-      # is flaky on `main` with or without this change.
+      # Each test owns a standalone process; the thread limit bounds memory use.
       - name: Run the durable suite, shard ${{ matrix.shard }} of 3
         run: |
           mapfile -t targets < <(python3 scripts/durable-test-targets.py "${{ matrix.shard }}")
@@ -84,7 +74,6 @@ jobs:
         if: matrix.shard == 0
         run: cargo test --locked -p lyracore-gateway --bin lyracore-gateway benilla_durable_ -- --ignored --test-threads=1
 
-      # No Package registers a client command here, so the Module's fixture command carries it.
       - name: Run the cross-Shard command transport tests
         if: matrix.shard == 1
         run: cargo test -p lyracore-gateway --bin lyracore-gateway stdb::subscriptions::party_command_durable_tests -- --ignored --test-threads=1

.github/workflows/rust.yml

@@ -1,12 +1,5 @@
 name: Rust
 
-# The Rust gates from docs/danger-zones.md, verbatim, plus the wasm compile that only the
-# deploy-time preflight covered before. Nothing here needs a SpacetimeDB node: the module tests that
-# do are integration tests, and `--lib` leaves them out.
-#
-# rustup reads rust-toolchain.toml and installs the pinned toolchain, rustfmt, clippy and the
-# wasm32-unknown-unknown target on the first cargo call, so nothing here repeats the version.
-
 on:
   pull_request:
   push:
@@ -27,8 +20,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Check formatting
         run: cargo fmt --all -- --check
-      # The SpacetimeDB build aborts on a print-family macro anywhere in Module source, even in a
-      # comment or a test. Use `writeln!(std::io::stderr(), ...)` for a test diagnostic.
+      # SpacetimeDB scans comments and test code for forbidden print macros.
       - name: Check for print macros in Module source
         run: |
           roots=(module/src)
@@ -58,7 +50,6 @@ jobs:
       - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
       - uses: ./.github/actions/setup-spacetime
       - run: ./lyracore bindings
-      # Share compiled dependencies while keeping each crate's result separate.
       - run: cargo test -p lyracore-importer
       - run: cargo test -p lyracore-module --lib --features=debug_reducers
       - run: cargo test -p lyracore-module --test build_script
@@ -74,16 +65,13 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
-      # `lyracore publish` builds this feature set. A default-feature check would omit published reducers.
       - run: cargo check --target wasm32-unknown-unknown -p lyracore-module --features=debug_reducers
 
-  # A Core change that breaks an official Package fails here, before the Package's next publish.
   official-packages:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      # A paired packages PR uses the same branch name; build against it when it exists.
       - id: packages-ref
         timeout-minutes: 2
         env:

.gitignore

@@ -1,67 +1,40 @@
 /target
 **/*.rs.bk
 
-# Local lifecycle state, logs, generated Gateway bindings, process ownership locks, and tool caches: the `lyracore`
-# CLI (.lyracore/cli/<rev>/) and the wire harness (.lyracore/wire-harness/<sha>/, #246 — a checkout
-# of LyraCoreProject/wire-harness plus its own target/, which is why this must stay ignored).
 /.lyracore/
 
-# Operator-pulled third-party data (cmangos classic-db) + generated bundles — NEVER committed (licensing firewall)
 /.import/
 
-# Blizzard client data — extracted DBCs / MPQ archives are COPYRIGHTED and MUST NEVER be committed.
-# The importer parses the operator's own client MPQs IN MEMORY and emits only derived game_* values;
-# this is a backstop in case a stray extract is ever written to the tree (the code never writes one).
+# Client archives and extracted game data must stay local.
 **/*.dbc
 **/*.MPQ
 **/*.mpq
 DBFilesClient/
 
-# Runtime logs (gateway/wine stderr captured by the wow-mcp harness) — never committed.
 gateway/gateway-stderr.log
 *-stderr.log
 
-# Stray `cargo doc` output at repo root.
 /doc/
 
-# Heap-profiling output from the `dhat-heap` feature (work-item 292, Runbook C).
 dhat-heap.json
 __pycache__/
 
-# cargo-mutants report output. Regenerated on every run, so it is never committed. This repository
-# carries no mutants configuration file; the maintainers run cargo-mutants from their own repository.
 /mutants.out/
 /mutants.out.old/
 .scratch/
 
-# Research notes stay local.
 /docs/research/
 /docs/verification/*-research.md
 
-# Agent-created Git worktrees are local execution state, not repository content.
 /.claude/worktrees/
 
-# Local fan-out briefs are agent execution state, not repository content.
 /.claude/tickets/
 
-# The Datascript toolchain's Bun project. `package.json`, `bun.lock`, `tsconfig.json` and the
-# Datascripts under `src/` ARE committed — the pin and the code are repository content.
-#
-# `generated/` is not: it is a ~400-file, 2 MB projection of the Module wasm that
-# `lyracore packages build` reproduces from `spacetime generate --lang typescript` on every run.
-# Committing it would put a large mechanical diff in every schema change and, worse, create a
-# second source of truth that can disagree with the Module. The Module is the schema's authority.
-#
-# `generated/base-snapshot.json` rides the same rule for a second reason: the importer derives it
-# from the OPERATOR's own client data (`--spell-snapshot`). It carries only mapped `game_*` values,
-# never client bytes, but it is the operator's own derived data and stays on the operator's machine.
 /datascripts/generated/
 /datascripts/node_modules/
 /datascripts/runtime-scripts/node_modules/
 
-# Installed Packages are local to this checkout. Reference Packages live in the collection.
 /packages/*
 !/packages/README.md
 
-# Generated Package output stays local. The collection may commit Script Artifacts, never Deltas.
 /packages/*/data/.generated/

AGENTS.md

@@ -9,8 +9,9 @@ We build complex things as simply as possible, and we look for ways to remove co
 - Boy scout rule: fix defects in code you already change. Exceptions: a fix that spreads to other
   files, or that changes behaviour the user must weigh. Name those in one line and carry on. Fix
   everything else, even when it feels too big. That feeling reads high.
-- Legacy code carries essay comments and issue references. Match its naming and idiom, not its
-  comment density.
+- Apply [the comment policy](CODING_STANDARDS.md#comments-and-documentation) when writing or reviewing
+  source, tests, scripts and configuration. Complete its
+  [comment review](CODING_STANDARDS.md#comment-review) before handoff.
 
 ## Words
 
@@ -32,6 +33,8 @@ We build complex things as simply as possible, and we look for ways to remove co
   ownership up front. Choose each subagent's model and effort for its subtask: a cheaper model for
   scoped work, the top tier for hard design, concurrency or adversarial review. The spawning agent
   owns that choice.
+- Require implementation and review subagents to read `AGENTS.md` in their checkout and return the
+  comment-review result. Review the combined diff after integrating parallel work.
 - Touch production or a live database only when the user tells you to or confirms it. Before you
   touch anything adjacent to one, name it.
 

CODING_STANDARDS.md

@@ -107,13 +107,45 @@ Use this order when two good practices compete:
 
 ## Comments and documentation
 
-- Comments explain why a constraint exists, what an interface promises, or which non-obvious protocol
-  fact controls the code. Let names and types explain ordinary mechanics.
-- Keep interface comments concise but complete about invariants, ordering, failure modes, and important
-  performance characteristics.
-- Do not put issue numbers in code comments. Record durable reasoning in the comment or an ADR so it
-  remains understandable without tracker history.
-- Update or remove nearby comments and docs when behavior changes. Stale explanation is a defect.
+- Write code without explanatory comments by default. Let names, types and tests carry ordinary
+  mechanics. This applies to source, tests, scripts, configuration and documentation comments such
+  as Rust's `///` and `//!`.
+- Keep concise interface contracts where names and types leave caller obligations, return values or
+  failure behavior unclear. Keep non-obvious local technical facts: opcodes, packet layouts, regexes,
+  units, constants, compatibility quirks, and safety, atomicity or ordering constraints.
+- Use one short line within the normal line width. Put longer contracts and reasoning in the relevant
+  document and leave a short pointer beside the interface. A pointer names the document and when to
+  read it. Preserve these pointers when removing nearby explanation; do not flatten an essay onto one
+  line or split it into adjacent one-line comments.
+- Preserve comments that tools consume, including script metadata, lint directives and editor type
+  annotations. Preserve interpreter directives, required attribution and generated-file notices.
+  These follow the format their consumer requires, including multiple lines when necessary.
+- Remove narration, section dividers, commented-out code, tracker history and descriptions that repeat
+  the adjacent code. Record work still needed in the tracker.
+- Keep durable design reasoning that needs more than one line in the relevant existing document or
+  an ADR. Check it against the code before moving it; deletion is appropriate for stale or redundant
+  explanation. Standalone documentation remains part of the project.
+- Change generated comments through their generator when we own it. Leave third-party generated
+  output alone. Comment-like text in strings and test fixtures is data; preserve its meaning.
+- Update or remove a retained comment when behavior changes. Review exceptions for their technical
+  content, not merely their length. Apply this policy equally to human and agent contributions.
+
+### Comment review
+
+Before handing off changes or completing a review:
+
+- Inspect the final diff with surrounding code, including new files. Review added and changed comments
+  and retained comments whose code changed in source, tests, scripts and configuration.
+- Match each reviewed comment to a policy exception and check its claim against the implementation.
+  Check that documentation pointers resolve. Remove narration even when it fits on one line.
+- Check removed comments for lost contracts, safety constraints, tool annotations and documentation
+  pointers. Preserve required meaning in code, a permitted comment or a linked document.
+- Repeat the review for subsequent edits. In the handoff, state the scope checked and whether it
+  passed, has findings with file locations, or does not apply because no source, tests, scripts or
+  configuration changed. Cite retained or relocated contracts when they need reviewer judgment.
+
+Formatting and tests do not establish that a comment is necessary or true; report this review
+separately from those checks.
 
 ## Completion and review
 

CONTRIBUTING.md

@@ -13,6 +13,11 @@ Three documents are required reading:
 2. [`CODING_STANDARDS.md`](CODING_STANDARDS.md): how new and changed code is written.
 3. [`CORE_TERMS.md`](CORE_TERMS.md): the terms the code, the comments and the reviews use.
 
+Human and agent contributions follow the same
+[comment policy](CODING_STANDARDS.md#comments-and-documentation). Code has no explanatory comments by
+default; the policy defines which contracts, technical facts, documentation pointers and tool
+annotations belong beside it.
+
 Look everything else up when a change needs it:
 
 - [`docs/quickstart.md`](docs/quickstart.md): from a clone to a connected client.