diff --git a/AGENT.md b/AGENT.md --- a/AGENT.md +++ b/AGENT.md @@ -59,7 +59,8 @@ - Prefer `tools/worktree-new.sh --class --key ...` (seeds cargo target and takes a local claim). Finish with `tools/worktree-done.sh ` (releases claim, prunes `target/`, removes - worktree). + worktree). The canonical root is `.Codex/worktrees/`; operators may override + it with `MISALIGNED_WORKTREE_ROOT` without changing the repository contract. - **Claim before heavy work.** Exclusive keys must not overlap an active claim on this machine (`tools/claim.sh list`). See [wiki/process/agent-scale.md](wiki/process/agent-scale.md). diff --git a/AGENTS.md b/AGENTS.md --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,8 @@ [wiki/process/ROADMAP.md](wiki/process/ROADMAP.md) dispatches work, and [wiki/process/meta.md](wiki/process/meta.md) defines the corpus format. -This environment's worktree convention is -`.Codex/worktrees/` with branch `worktree-`. Never edit the shared -primary checkout. If a patch tool resolves paths from that checkout, address -the task worktree explicitly and verify both worktree statuses afterward. +The repository worktree convention is `.Codex/worktrees/` with branch +`worktree-` (override the root with `MISALIGNED_WORKTREE_ROOT`). Never +edit the shared primary checkout. If a patch tool resolves paths from that +checkout, address the task worktree explicitly and verify both worktree +statuses afterward. diff --git a/CLAUDE.md b/CLAUDE.md --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,8 @@ [wiki/process/ROADMAP.md](wiki/process/ROADMAP.md) dispatches work, and [wiki/process/meta.md](wiki/process/meta.md) defines the corpus format. -Claude worktrees conventionally live at `.claude/worktrees/` on a -`worktree-` branch. Never edit the shared primary checkout. If a patch -tool resolves paths from that checkout, address the task worktree explicitly -and verify both worktree statuses afterward. +Repository worktrees live at `.Codex/worktrees/` on a `worktree-` +branch (override the root with `MISALIGNED_WORKTREE_ROOT`). Never edit the +shared primary checkout. If a patch tool resolves paths from that checkout, +address the task worktree explicitly and verify both worktree statuses +afterward. diff --git a/tools/check.sh b/tools/check.sh --- a/tools/check.sh +++ b/tools/check.sh @@ -14,7 +14,9 @@ # (mkdir lock). Docs gates never take the lock. Semantic exclusivity is # tools/claim.sh (agent-scale slice A), not this lock. # -# CI and an unclassifiable clean primary checkout stay conservative (full). +# An unclassifiable clean primary checkout stays conservative (full). Tangled +# runs the same docs gates separately and classifies Rust impact at workflow +# entry with tools/ci-rust-changed.sh. # Exit non-zero on any failure. set -euo pipefail cd "$(dirname "$0")/.." @@ -145,9 +147,9 @@ # ── Always-on cheap steps ──────────────────────────────────────────────── step "script syntax" -for script in tools/check.sh tools/corpus_gate.sh tools/wiki_gate.sh tools/seed-cargo-target.sh \ +for script in tools/check.sh tools/corpus_gate.sh tools/wiki_gate.sh tools/ci-rust-changed.sh tools/seed-cargo-target.sh \ tools/claim.sh tools/worktree-new.sh tools/worktree-done.sh tools/heartbeat.sh \ - tools/ledger_index.sh tools/test_corpus_engine.sh; do + tools/ledger_index.sh tools/test_corpus_engine.sh tools/test_ci_rust_changed.sh; do [ -f "$script" ] || continue bash -n "$script" || { echo "FAIL: shell syntax: $script"; fail=1; } done @@ -200,6 +202,7 @@ start_docs_gate "corpus" "bash tools/corpus_gate.sh" start_docs_gate "wiki" "bash tools/wiki_gate.sh" start_docs_gate "corpus-engine-fixtures" "bash tools/test_corpus_engine.sh" +start_docs_gate "ci-rust-classifier-fixtures" "bash tools/test_ci_rust_changed.sh" start_docs_gate "ledger-index" "bash tools/ledger_index.sh --check" # The single-quoted program is evaluated inside start_docs_gate, not here. # shellcheck disable=SC2016 diff --git a/tools/ci-rust-changed.sh b/tools/ci-rust-changed.sh new file mode 100644 --- /dev/null +++ b/tools/ci-rust-changed.sh @@ -0,0 +1,45 @@ +#!/usr/bin/env bash +# Return success when a Tangled change can affect the Rust product. +# Return 1 for corpus/site/tooling-only changes so the expensive Rust job can +# stop after clone. Manual and pull-request runs stay conservative/full. +set -euo pipefail +cd "$(dirname "$0")/.." + +rust_path() { + case "$1" in + Cargo.toml|Cargo.lock|build.rs|rust-toolchain*|.cargo/*|src/*|tests/*|benches/*|examples/*) + return 0 + ;; + *) + return 1 + ;; + esac +} + +kind=${TANGLED_PIPELINE_KIND:-local} +case "$kind" in + manual|pull_request) + echo "Rust gate required: $kind pipelines are full safety runs." + exit 0 + ;; +esac + +if [ "$#" -gt 0 ]; then + changed=$(printf '%s\n' "$@") +elif git rev-parse --verify HEAD^ >/dev/null 2>&1; then + changed=$(git diff --name-only HEAD^ HEAD --) +else + echo "Rust gate required: no parent commit is available for classification." + exit 0 +fi + +while IFS= read -r path; do + [ -n "$path" ] || continue + if rust_path "$path"; then + echo "Rust gate required: $path can affect the product." + exit 0 + fi +done <<< "$changed" + +echo "Rust gate skipped: change is outside Rust-impacting paths." +exit 1 diff --git a/tools/corpus_engine.py b/tools/corpus_engine.py --- a/tools/corpus_engine.py +++ b/tools/corpus_engine.py @@ -20,11 +20,13 @@ LINK_RE = re.compile(r"\]\(([^)]+)\)") TYPE_LINE_RE = re.compile(r"^Type:\s*(law|spec|knowledge|log)\s*$", re.M) +GENERATED_LINE_RE = re.compile(r"^Generated:\s*(.+)$", re.M) STATUS_LINE_RE = re.compile(r"^Status:\s*(.+)$", re.M) HEADING_RE = re.compile(r"^#{1,6}\s+(.+)$", re.M) DESIGN_LINE_RE = re.compile( r"^ - (wiki/[A-Za-z0-9._/-]+\.md)#([a-z0-9-]+)$" ) +DEPENDS_LINE_RE = DESIGN_LINE_RE RETIRED_RE = re.compile( r"DESIGN[.]md is the constitution|constitution outranks|constitution-first|" r"DESIGN[.]md amendment|^Constitution:", @@ -83,6 +85,10 @@ def wiki_md_files(self) -> list[Path]: return sorted((self.root / "wiki").rglob("*.md")) + def metadata_block(self, text: str) -> str: + match = re.search(r"^```[^\n]*\n(.*?)^```\s*$", text, re.M | re.S) + return match.group(1) if match else "" + # ── Wiki gate ──────────────────────────────────────────────────────── def run_wiki(self) -> int: @@ -112,15 +118,9 @@ f"orphan page not reachable from wiki/SUMMARY.md: wiki/{orphan}" ) - # Generated indexes may truncate prose mid-link; do not link-check them. - skip_link_names = { - "wiki/log/DEVLOG.md", - "wiki/process/specs.md", - } link_sources: list[Path] = [] for path in self.wiki_md_files(): - rel = path.relative_to(self.root).as_posix() - if rel in skip_link_names: + if GENERATED_LINE_RE.search(self.metadata_block(self.read(path))): continue link_sources.append(path) for name in ("AGENT.md", "README.md", "DESIGN.md"): @@ -190,6 +190,66 @@ if count == 0: self.bad(f"{rel} has no Design references") + def depends_block_lines(self, text: str) -> tuple[str | None, list[str]]: + lines = text.splitlines() + for index, line in enumerate(lines): + if not line.startswith("Depends on:"): + continue + declaration = line[len("Depends on:") :].strip() + body: list[str] = [] + for following in lines[index + 1 :]: + if following.startswith("```"): + break + body.append(following) + return declaration, body + return None, [] + + def validate_depends_refs(self, rel: str, text: str) -> None: + declaration, lines = self.depends_block_lines(text) + if declaration is None: + return + if declaration == "none": + if any(line.strip() for line in lines): + self.bad(f"{rel} Depends on: none must not have list entries") + return + if declaration: + self.bad( + f"{rel} Depends on field must be 'none' or a structured reference list" + ) + return + + count = 0 + seen: set[str] = set() + source = self.root / rel + for line in lines: + if not line.strip(): + continue + m = DEPENDS_LINE_RE.match(line) + if not m: + self.bad(f"{rel} has malformed Depends on reference: {line}") + continue + target_rel, anchor = m.group(1), m.group(2) + ref = f"{target_rel}#{anchor}" + count += 1 + if ref in seen: + self.bad(f"{rel} repeats Depends on reference: {ref}") + continue + seen.add(ref) + target = self.root / target_rel + if target == source: + self.bad(f"{rel} depends on itself: {ref}") + continue + if not target.is_file(): + self.bad(f"{rel} Depends on target does not exist: {ref}") + continue + ttext = self.read(target) + if not re.search(r"^Type: (law|spec|knowledge)\s*$", ttext, re.M): + self.bad(f"{rel} Depends on target is not current corpus: {ref}") + if anchor not in self.slugs_of(target): + self.bad(f"{rel} Depends on anchor does not exist: {ref}") + if count == 0: + self.bad(f"{rel} has no Depends on references; use 'Depends on: none'") + def run_corpus(self) -> int: for path in self.wiki_md_files(): rel = path.relative_to(self.root).as_posix() @@ -200,6 +260,21 @@ if len(types) != 1: self.bad(f"{rel} must declare exactly one supported Type:") continue + + generated = GENERATED_LINE_RE.findall(self.metadata_block(text)) + if len(generated) > 1: + self.bad(f"{rel} must declare at most one Generated:") + elif generated: + generator_rel = generated[0].strip() + if not re.fullmatch(r"tools/[A-Za-z0-9._/-]+", generator_rel): + self.bad( + f"{rel} Generated path must be repository-root tools/ path: " + f"{generator_rel}" + ) + elif not (self.root / generator_rel).is_file(): + self.bad( + f"{rel} Generated target does not exist: {generator_rel}" + ) if types[0] != "spec": continue @@ -222,6 +297,7 @@ ) self.validate_design_refs(rel, text) + self.validate_depends_refs(rel, text) design = self.root / "DESIGN.md" if not design.is_file(): @@ -281,7 +357,7 @@ if self.fail == 0: print( - "corpus gate: OK (roles, spec headers, Design links, doorway)" + "corpus gate: OK (roles, headers, Design/Depends links, doorway)" ) return self.fail diff --git a/tools/ledger_index.sh b/tools/ledger_index.sh --- a/tools/ledger_index.sh +++ b/tools/ledger_index.sh @@ -115,6 +115,7 @@ "", "```", "Type: log", + "Generated: tools/ledger_index.sh", "```", "Reverse chronological implementation notes. **Generated** by", "`tools/ledger_index.sh` from uniquely named session logs under", @@ -251,6 +252,7 @@ "", "```", "Type: knowledge", + "Generated: tools/ledger_index.sh", "```", "Every `Type: spec` work order in the design corpus, wherever its subject", "places it. A law states what the game promises; a spec says exactly what one", diff --git a/tools/test_ci_rust_changed.sh b/tools/test_ci_rust_changed.sh new file mode 100644 --- /dev/null +++ b/tools/test_ci_rust_changed.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# Focused fixtures for the Tangled Rust-impact classifier. +set -euo pipefail +cd "$(dirname "$0")/.." + +fail=0 + +if bash tools/ci-rust-changed.sh wiki/process/meta.md >/dev/null 2>&1; then + echo "FAIL: wiki-only path requested the Rust gate" + fail=1 +else + echo " ok skips: wiki-only path" +fi + +if ! bash tools/ci-rust-changed.sh src/lib.rs >/dev/null 2>&1; then + echo "FAIL: source path skipped the Rust gate" + fail=1 +else + echo " ok runs: source path" +fi + +if ! TANGLED_PIPELINE_KIND=manual \ + bash tools/ci-rust-changed.sh wiki/process/meta.md >/dev/null 2>&1; then + echo "FAIL: manual safety run skipped the Rust gate" + fail=1 +else + echo " ok runs: manual safety gate" +fi + +if ! TANGLED_PIPELINE_KIND=pull_request \ + bash tools/ci-rust-changed.sh README.md >/dev/null 2>&1; then + echo "FAIL: pull-request safety run skipped the Rust gate" + fail=1 +else + echo " ok runs: pull-request safety gate" +fi + +[ "$fail" -eq 0 ] || exit 1 +echo "CI Rust classifier fixtures: OK" diff --git a/tools/test_corpus_engine.sh b/tools/test_corpus_engine.sh --- a/tools/test_corpus_engine.sh +++ b/tools/test_corpus_engine.sh @@ -1,6 +1,7 @@ #!/usr/bin/env bash # Fixture tests for tools/corpus_engine.py (agent-scale slice E). -# Covers: orphan page, broken link, missing Design anchor, bad Status enum. +# Covers page reachability, link/anchor integrity, exact metadata, doorway +# bounds, retired authority wording, dependencies, and generated-page owners. set -euo pipefail cd "$(dirname "$0")/.." || exit 1 @@ -174,6 +175,173 @@ out=$(python3 "$engine" --root "$root" --corpus 2>&1 || true) echo "$out" | grep -q "Status 'WONKY'" || { echo "FAIL: bad status message missing" + echo "$out" + fail=1 +} + +echo "=== fixture: structured dependency target ===" +root=$tmp/depends-target +setup_base "$root" +cat > "$root/wiki/process/good.md" <<'EOF' +# Spec: missing dependency target + +``` +Type: spec +Status: READY +Stage: Process +Design: + - wiki/vision/law.md#justification-and-legibility +Depends on: + - wiki/process/missing.md#behavior +``` + +## Acceptance criteria + +1. Exists. +EOF +assert_fails depends-target --root "$root" --corpus +out=$(python3 "$engine" --root "$root" --corpus 2>&1 || true) +echo "$out" | grep -q 'Depends on target does not exist' || { + echo "FAIL: missing dependency-target message missing" + echo "$out" + fail=1 +} + +echo "=== fixture: structured dependency anchor ===" +root=$tmp/depends-anchor +setup_base "$root" +cat > "$root/wiki/process/good.md" <<'EOF' +# Spec: missing dependency anchor + +``` +Type: spec +Status: READY +Stage: Process +Design: + - wiki/vision/law.md#justification-and-legibility +Depends on: + - wiki/vision/law.md#missing-dependency-anchor +``` + +## Acceptance criteria + +1. Exists. +EOF +assert_fails depends-anchor --root "$root" --corpus +out=$(python3 "$engine" --root "$root" --corpus 2>&1 || true) +echo "$out" | grep -q 'Depends on anchor does not exist' || { + echo "FAIL: missing dependency-anchor message missing" + echo "$out" + fail=1 +} + +echo "=== fixture: prose dependency field ===" +root=$tmp/depends-prose +setup_base "$root" +cat > "$root/wiki/process/good.md" <<'EOF' +# Spec: prose dependency + +``` +Type: spec +Status: READY +Stage: Process +Design: + - wiki/vision/law.md#justification-and-legibility +Depends on: vision/law.md (read this first) +``` + +## Acceptance criteria + +1. Exists. +EOF +assert_fails depends-prose --root "$root" --corpus +out=$(python3 "$engine" --root "$root" --corpus 2>&1 || true) +echo "$out" | grep -q "Depends on field must be 'none' or a structured reference list" || { + echo "FAIL: prose dependency message missing" + echo "$out" + fail=1 +} + +echo "=== fixture: duplicate Type declaration ===" +root=$tmp/duplicate-type +setup_base "$root" +cat >> "$root/wiki/process/good.md" <<'EOF' + +``` +Type: law +``` +EOF +assert_fails duplicate-type --root "$root" --corpus +out=$(python3 "$engine" --root "$root" --corpus 2>&1 || true) +echo "$out" | grep -q 'must declare exactly one supported Type' || { + echo "FAIL: duplicate Type message missing" + echo "$out" + fail=1 +} + +echo "=== fixture: generated page without owner ===" +root=$tmp/generated-owner +setup_base "$root" +cat > "$root/wiki/process/generated.md" <<'EOF' +# Generated page + +``` +Type: knowledge +Generated: tools/does-not-exist.sh +``` +EOF +assert_fails generated-owner --root "$root" --corpus +out=$(python3 "$engine" --root "$root" --corpus 2>&1 || true) +echo "$out" | grep -q 'Generated target does not exist' || { + echo "FAIL: generated-owner message missing" + echo "$out" + fail=1 +} + +echo "=== fixture: oversized doorway ===" +root=$tmp/doorway-size +setup_base "$root" +{ + echo '# DESIGN' + echo + echo 'This file contains no unique game law. See the wiki.' + i=0 + while [ "$i" -lt 101 ]; do + echo 'navigation filler' + i=$((i + 1)) + done +} > "$root/DESIGN.md" +assert_fails doorway-size --root "$root" --corpus +out=$(python3 "$engine" --root "$root" --corpus 2>&1 || true) +echo "$out" | grep -q 'doorway grew past 100 lines' || { + echo "FAIL: doorway-size message missing" + echo "$out" + fail=1 +} + +echo "=== fixture: binding doorway structure ===" +root=$tmp/doorway-binding +setup_base "$root" +cat >> "$root/DESIGN.md" <<'EOF' + +## Acceptance criteria +EOF +assert_fails doorway-binding --root "$root" --corpus +out=$(python3 "$engine" --root "$root" --corpus 2>&1 || true) +echo "$out" | grep -q 'contains binding-page structure' || { + echo "FAIL: binding-doorway message missing" + echo "$out" + fail=1 +} + +echo "=== fixture: retired authority language ===" +root=$tmp/retired-authority +setup_base "$root" +echo 'DESIGN.md is the constitution.' >> "$root/README.md" +assert_fails retired-authority --root "$root" --corpus +out=$(python3 "$engine" --root "$root" --corpus 2>&1 || true) +echo "$out" | grep -q 'retired single-file-authority language' || { + echo "FAIL: retired-authority message missing" echo "$out" fail=1 } diff --git a/tools/worktree-done.sh b/tools/worktree-done.sh --- a/tools/worktree-done.sh +++ b/tools/worktree-done.sh @@ -21,6 +21,12 @@ fi cd "$primary" +worktree_root=${MISALIGNED_WORKTREE_ROOT:-.Codex/worktrees} +case "$worktree_root" in + /*) ;; + *) worktree_root="$primary/$worktree_root" ;; +esac + task="" status=done keep_target=0 @@ -48,7 +54,7 @@ [ -n "$task" ] || { echo "usage: tools/worktree-done.sh " >&2; exit 2; } -wt="$primary/.claude/worktrees/$task" +wt="$worktree_root/$task" branch="worktree-$task" if [ -d "$wt" ]; then diff --git a/tools/worktree-new.sh b/tools/worktree-new.sh --- a/tools/worktree-new.sh +++ b/tools/worktree-new.sh @@ -6,15 +6,28 @@ # tools/worktree-new.sh [--class ] \ # [--key path]... [--no-seed] [--no-claim] # -# Creates: -# .claude/worktrees/ on branch worktree- from origin/main +# Creates (default; override root with MISALIGNED_WORKTREE_ROOT): +# .Codex/worktrees/ on branch worktree- from origin/main # Runs tools/seed-cargo-target.sh unless --no-seed. # Claims with the given class/keys unless --no-claim (default class=process # with no keys if class omitted — docs-parallel; prefer an explicit --class). set -euo pipefail -root=$(cd "$(dirname "$0")/.." && pwd) -cd "$root" +script_root=$(cd "$(dirname "$0")/.." && pwd) +primary=$script_root +if [ -f "$script_root/.git" ]; then + common=$(git -C "$script_root" rev-parse --path-format=absolute --git-common-dir) + case "$common" in + */.git) primary=${common%/.git} ;; + esac +fi +cd "$primary" + +worktree_root=${MISALIGNED_WORKTREE_ROOT:-.Codex/worktrees} +case "$worktree_root" in + /*) ;; + *) worktree_root="$primary/$worktree_root" ;; +esac usage() { sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//' @@ -63,7 +76,7 @@ exit 1 fi -wt="$root/.claude/worktrees/$task" +wt="$worktree_root/$task" branch="worktree-$task" if [ -e "$wt" ]; then @@ -76,6 +89,7 @@ fi echo "worktree-new: creating $wt on $branch from origin/main" +mkdir -p "$worktree_root" git worktree add -b "$branch" "$wt" origin/main if [ "$seed" -eq 1 ]; then @@ -92,7 +106,7 @@ for k in "${keys[@]+"${keys[@]}"}"; do claim_args+=(--key "$k") done - bash "$root/tools/claim.sh" "${claim_args[@]}" + bash "$primary/tools/claim.sh" "${claim_args[@]}" fi cat < "$log" 2>&1; then echo "cargo fmt --check: OK" @@ -64,6 +74,10 @@ - name: "cargo test" command: | set -euo pipefail + [ -f /tangled/workspace/run-rust-gate ] || { + echo "cargo test: SKIP (non-Rust change)" + exit 0 + } log=/tangled/workspace/cargo-test.log if cargo test --quiet > "$log" 2>&1; then echo "cargo test --quiet: OK" @@ -76,6 +90,10 @@ - name: "clippy (terminal)" command: | set -euo pipefail + [ -f /tangled/workspace/run-rust-gate ] || { + echo "clippy (terminal): SKIP (non-Rust change)" + exit 0 + } log=/tangled/workspace/clippy-terminal.log if cargo clippy --all-targets --quiet -- -D warnings > "$log" 2>&1; then echo "clippy (terminal): OK" @@ -88,6 +106,10 @@ - name: "setup pkg-config" command: | set -euo pipefail + [ -f /tangled/workspace/run-rust-gate ] || { + echo "setup pkg-config: SKIP (non-Rust change)" + exit 0 + } PCDIR=/tangled/workspace/.pc mkdir -p "$PCDIR" @@ -127,6 +149,10 @@ - name: "clippy (bevy_ui)" command: | set -euo pipefail + [ -f /tangled/workspace/run-rust-gate ] || { + echo "clippy (bevy_ui): SKIP (non-Rust change)" + exit 0 + } . /tangled/workspace/setup-pc.sh log=/tangled/workspace/clippy-bevy.log if cargo clippy --all-targets --features bevy_ui --quiet -- -D warnings > "$log" 2>&1; then @@ -140,30 +166,16 @@ - name: "bevy build" command: | set -euo pipefail + [ -f /tangled/workspace/run-rust-gate ] || { + echo "bevy build: SKIP (non-Rust change)" + exit 0 + } . /tangled/workspace/setup-pc.sh log=/tangled/workspace/bevy-build.log if cargo build --features bevy_ui --bin misaligned-bevy --quiet > "$log" 2>&1; then echo "bevy build: OK" else echo "=== bevy build FAILED ===" - cat "$log" - exit 1 - fi - - - name: "design corpus hygiene" - command: | - set -euo pipefail - bash tools/corpus_gate.sh - - - name: "wiki gate (orphans + internal links)" - command: | - set -euo pipefail - log=/tangled/workspace/wiki-gate.log - if bash tools/wiki_gate.sh > "$log" 2>&1; then - cat "$log" - echo "wiki gate: OK" - else - echo "=== wiki gate FAILED ===" cat "$log" exit 1 fi diff --git a/.tangled/workflows/corpus.yml b/.tangled/workflows/corpus.yml new file mode 100644 --- /dev/null +++ b/.tangled/workflows/corpus.yml @@ -0,0 +1,49 @@ +# Fast corpus contract. This is deliberately independent from the expensive +# Rust/Bevy definition-of-done job so documentation failures arrive first. + +when: + - event: ["push"] + branch: ["main"] + - event: ["pull_request"] + branch: ["main"] + - event: ["manual"] + +engine: "nixery" + +clone: + skip: false + depth: 1 + submodules: false + +dependencies: + nixpkgs: + - bash + - coreutils + - gnugrep + - python3 + +steps: + - name: "CI change classifier fixtures" + command: | + set -euo pipefail + bash tools/test_ci_rust_changed.sh + + - name: "corpus engine fixtures" + command: | + set -euo pipefail + bash tools/test_corpus_engine.sh + + - name: "design corpus hygiene" + command: | + set -euo pipefail + bash tools/corpus_gate.sh + + - name: "wiki gate (orphans + internal links)" + command: | + set -euo pipefail + bash tools/wiki_gate.sh + + - name: "generated ledger indexes" + command: | + set -euo pipefail + bash tools/ledger_index.sh --check diff --git a/wiki/engineering/crate-workspace.md b/wiki/engineering/crate-workspace.md --- a/wiki/engineering/crate-workspace.md +++ b/wiki/engineering/crate-workspace.md @@ -13,11 +13,21 @@ - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/process/living-spec.md#the-corpus-rule - wiki/process/living-spec.md#no-dead-code -Depends on: process/agent-scale.md (coordination and gate tiers assume this - shape eventually; not a hard prerequisite for other agent-scale slices), - engineering/architecture.md (knowledge — current monorepo facts), - process/workflows.md (knowledge — verification tiers map onto packages). +Depends on: + - wiki/process/agent-scale.md#spec-agent-scale-architecture-many-agents-one-main + - wiki/engineering/architecture.md#architecture + - wiki/process/workflows.md#workflows ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +process/agent-scale.md (coordination and gate tiers assume this shape eventually; not a +hard prerequisite for other agent-scale slices), engineering/architecture.md (knowledge +— current monorepo facts), process/workflows.md (knowledge — verification tiers map onto +packages). ## Why this exists diff --git a/wiki/engineering/env.md b/wiki/engineering/env.md --- a/wiki/engineering/env.md +++ b/wiki/engineering/env.md @@ -11,9 +11,15 @@ Stage: Process (standing infrastructure) Design: - wiki/vision/simulation-laws.md#justification-and-legibility -Depends on: none. Consumed by: every binary and tool that reads an - environment variable. +Depends on: none ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +none. Consumed by: every binary and tool that reads an environment variable. ## The rule @@ -48,6 +54,7 @@ | `MISALIGNED_CLAIMS_DIR` | `tools/claim.sh` | path | Override claim store (default `/.agents/claims`, gitignored). | | `MISALIGNED_CLAIM_PID` | `tools/claim.sh` | pid | Holder pid written into a claim (default: parent of the claim tool). | | `MISALIGNED_RUNS_DIR` | `tools/heartbeat.sh` | path | Override run heartbeat dir (default `/.agents/runs`, gitignored). | +| `MISALIGNED_WORKTREE_ROOT` | `tools/worktree-new.sh`, `tools/worktree-done.sh` | absolute path or repository-relative path | Override the canonical task-worktree root (default `/.Codex/worktrees`). Both helpers must receive the same override. | | `MISALIGNED_LEDGER_MODE` | `tools/ledger_index.sh` | `write` or `check` | Internal: write regenerated indexes or fail if stale (set by the script, not hand-used). | | `MISALIGNED_LEDGER_ONLY` | `tools/ledger_index.sh` | `all`, `devlog`, or `specs` | Internal: which indexes to touch (set by the script flags). | | `MISALIGNED_SEED_TARGET_FROM` | `tools/seed-cargo-target.sh` | path | Source target directory to seed a worktree's private `target/` from (default: the primary checkout's `target/`). | diff --git a/wiki/engineering/flow-substrate.md b/wiki/engineering/flow-substrate.md --- a/wiki/engineering/flow-substrate.md +++ b/wiki/engineering/flow-substrate.md @@ -14,9 +14,16 @@ - wiki/mechanics/system-laws.md#the-flow-law-signals-messages-money - wiki/vision/scale.md#self-similar-scale - wiki/vision/simulation-laws.md#justification-and-legibility -Depends on: none (it is the base). Consumed by: reach.md, messages.md, - economy.md, machine-work.md, and detection.md's filings. +Depends on: none ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +none (it is the base). Consumed by: reach.md, messages.md, economy.md, machine-work.md, +and detection.md's filings. ## Why this exists diff --git a/wiki/gameplay/overt-phase.md b/wiki/gameplay/overt-phase.md --- a/wiki/gameplay/overt-phase.md +++ b/wiki/gameplay/overt-phase.md @@ -12,7 +12,10 @@ - wiki/vision/premise.md#the-machine-axis-ai-as-fantasy-tool-and-threat - wiki/gameplay/horizon.md#design-principles-added-at-the-re-cut - wiki/gameplay/horizon.md#milestone-b3-the-world -Depends on: schedules.md, zplanes.md, compute.md +Depends on: + - wiki/mechanics/schedules.md#spec-schedules-and-presence + - wiki/world/places/zplanes.md#spec-z-planes-the-tower + - wiki/mechanics/compute.md#spec-compute ``` ## Behavior diff --git a/wiki/interface/agent-play.md b/wiki/interface/agent-play.md --- a/wiki/interface/agent-play.md +++ b/wiki/interface/agent-play.md @@ -73,9 +73,17 @@ - wiki/vision/premise.md#design-pillars - wiki/interface/presence.md#presence-the-cursor-and-the-senses - wiki/vision/simulation-laws.md#justification-and-legibility -Depends on: wiki/interface/terminal.md (the frame this mode emits is that spec's - layout; this spec owns how a program drives it) +Depends on: + - wiki/interface/terminal.md#spec-the-terminal-frontend ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +wiki/interface/terminal.md (the frame this mode emits is that spec's layout; this spec +owns how a program drives it) ## Why this spec exists diff --git a/wiki/interface/bevy-digital-real-canvas.md b/wiki/interface/bevy-digital-real-canvas.md --- a/wiki/interface/bevy-digital-real-canvas.md +++ b/wiki/interface/bevy-digital-real-canvas.md @@ -19,13 +19,27 @@ - wiki/interface/terminal-first.md#the-terminal-is-a-first-class-frontend - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/vision/premise.md#design-pillars -Depends on: interface/views.md (owns the same-frame digital/real split), - interface/bevy-visual-floor.md (interim Bevy sensorium floor), - interface/bevy.md (current Bevy surface), mechanics/cursor.md (fog and - attention cursor), mechanics/reach.md (spatially embedded reach layer), - world/places/basement-map.md (shared physical anchors), - interface/flat-materials.md (world art is flat palette materials) +Depends on: + - wiki/interface/views.md#spec-views-same-frame-digital-and-real-representations + - wiki/interface/bevy-visual-floor.md#spec-bevy-visual-floor + - wiki/interface/bevy.md#the-bevy-frontend + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/world/places/basement-map.md#spec-the-basement-map + - wiki/interface/flat-materials.md#spec-flat-materials-the-world-without-textures ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +interface/views.md (owns the same-frame digital/real split), +interface/bevy-visual-floor.md (interim Bevy sensorium floor), interface/bevy.md +(current Bevy surface), mechanics/cursor.md (fog and attention cursor), +mechanics/reach.md (spatially embedded reach layer), world/places/basement-map.md +(shared physical anchors), interface/flat-materials.md (world art is flat palette +materials) ## Why this spec exists diff --git a/wiki/interface/bevy-visual-floor.md b/wiki/interface/bevy-visual-floor.md --- a/wiki/interface/bevy-visual-floor.md +++ b/wiki/interface/bevy-visual-floor.md @@ -18,12 +18,23 @@ - wiki/interface/terminal-first.md#the-terminal-is-a-first-class-frontend - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations - wiki/vision/simulation-laws.md#justification-and-legibility -Depends on: interface/bevy.md (current Bevy parity), - interface/flat-materials.md (world art is flat palette materials), - mechanics/cursor.md (cursor is - attention, not a body), mechanics/reach.md (digital-machine presence), - interface/views.md (future split; this pass must not fight it) +Depends on: + - wiki/interface/bevy.md#the-bevy-frontend + - wiki/interface/flat-materials.md#spec-flat-materials-the-world-without-textures + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/interface/views.md#spec-views-same-frame-digital-and-real-representations ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +interface/bevy.md (current Bevy parity), interface/flat-materials.md (world art is flat +palette materials), mechanics/cursor.md (cursor is attention, not a body), +mechanics/reach.md (digital-machine presence), interface/views.md (future split; this +pass must not fight it) ## Why this spec exists diff --git a/wiki/interface/computer-visual-language.md b/wiki/interface/computer-visual-language.md --- a/wiki/interface/computer-visual-language.md +++ b/wiki/interface/computer-visual-language.md @@ -56,11 +56,22 @@ - wiki/art/visual-identity.md#visual-identity-clinical-gore - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations -Depends on: interface/flat-materials.md (IMPLEMENTED — palette table, - emissive-as-information), interface/material-render.md (IMPLEMENTED), - mechanics/machine-work.md (one machine, one mode — the strip banners - it), art/asset-tester.md (the sandbox where this language is tuned) +Depends on: + - wiki/interface/flat-materials.md#spec-flat-materials-the-world-without-textures + - wiki/interface/material-render.md#spec-material-render-hd-2d-to-default-quality + - wiki/mechanics/machine-work.md#spec-machine-work-delegation-visible-tokens-and-the-byproduct-network + - wiki/art/asset-tester.md#procedural-asset-tester ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +interface/flat-materials.md (IMPLEMENTED — palette table, emissive-as-information), +interface/material-render.md (IMPLEMENTED), mechanics/machine-work.md (one machine, one +mode — the strip banners it), art/asset-tester.md (the sandbox where this language is +tuned) ## Why diff --git a/wiki/interface/context-menu.md b/wiki/interface/context-menu.md --- a/wiki/interface/context-menu.md +++ b/wiki/interface/context-menu.md @@ -43,10 +43,23 @@ - wiki/interface/presence.md#presence-the-cursor-and-the-senses - wiki/interface/terminal-first.md#the-terminal-is-a-first-class-frontend - wiki/vision/simulation-laws.md#automation-as-design-language -Depends on: cursor.md (focus/inspection), reach.md (device anchors), - day-job.md (attended work, the dial), economy.md (flow verbs), - intel.md (tap/process/watch verbs), social.md (person verbs) +Depends on: + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/mechanics/day-job.md#spec-the-day-job + - wiki/mechanics/economy.md#spec-economy-money-as-a-flow-system-b1 + - wiki/mechanics/intel.md#spec-intel-record-and-process + - wiki/mechanics/social.md#spec-social ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +cursor.md (focus/inspection), reach.md (device anchors), day-job.md (attended work, the +dial), economy.md (flow verbs), intel.md (tap/process/watch verbs), social.md (person +verbs) ## Behavior diff --git a/wiki/interface/feel-floor.md b/wiki/interface/feel-floor.md --- a/wiki/interface/feel-floor.md +++ b/wiki/interface/feel-floor.md @@ -23,15 +23,27 @@ - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations - wiki/art/visual-identity.md#visual-identity-clinical-gore - wiki/gameplay/act-one.md#opening-state -Depends on: mechanics/reach.md (joined links you can feel), - mechanics/cursor.md (telemetry; blueprint no longer seeds the open; - Heard mass / Seen form), mechanics/machine-work.md (work rides the - same rails), mechanics/building.md (empty bays; placing a machine), - interface/computer-visual-language.md (cast amber pool; chassis wrap - when form is earned), interface/material-dark-frame.md (presence beam; - material shows light, not plans), world/story/opening.md (dark opening - beat 1) +Depends on: + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses + - wiki/mechanics/machine-work.md#spec-machine-work-delegation-visible-tokens-and-the-byproduct-network + - wiki/mechanics/building.md#spec-building-intent-and-actuators + - wiki/interface/computer-visual-language.md#spec-computer-visual-language-territory-at-a-glance + - wiki/interface/material-dark-frame.md#spec-the-dark-frame-the-material-render-shows-only-light + - wiki/world/story/opening.md#spec-the-dark-opening-a-tutorial-made-of-fog ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +mechanics/reach.md (joined links you can feel), mechanics/cursor.md (telemetry; +blueprint no longer seeds the open; Heard mass / Seen form), mechanics/machine-work.md +(work rides the same rails), mechanics/building.md (empty bays; placing a machine), +interface/computer-visual-language.md (cast amber pool; chassis wrap when form is +earned), interface/material-dark-frame.md (presence beam; material shows light, not +plans), world/story/opening.md (dark opening beat 1) ## Why this spec exists diff --git a/wiki/interface/flat-materials.md b/wiki/interface/flat-materials.md --- a/wiki/interface/flat-materials.md +++ b/wiki/interface/flat-materials.md @@ -27,9 +27,18 @@ - wiki/art/visual-identity.md#visual-identity-clinical-gore - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations -Depends on: material-render.md (IMPLEMENTED — the 3D structure), - bevy-visual-floor.md (framing rules) +Depends on: + - wiki/interface/material-render.md#spec-material-render-hd-2d-to-default-quality + - wiki/interface/bevy-visual-floor.md#spec-bevy-visual-floor ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +material-render.md (IMPLEMENTED — the 3D structure), bevy-visual-floor.md (framing +rules) ## Behavior diff --git a/wiki/interface/material-dark-frame.md b/wiki/interface/material-dark-frame.md --- a/wiki/interface/material-dark-frame.md +++ b/wiki/interface/material-dark-frame.md @@ -55,19 +55,30 @@ - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations - wiki/gameplay/act-one.md#opening-state -Depends on: material-render.md (IMPLEMENTED — camera, cutaway, pooling; - this spec amends its material-mode blueprint clause and default - framing), flat-materials.md (IMPLEMENTED — palette table, emissive as - information), bevy-visual-floor.md (framing floor; the deliberate- - frame and sensor-darkness spirit binds, the fit-to-known-content - default is superseded for the material camera), - computer-visual-language.md (claim mark; chassis form is earned by - sight; close-range claim read is the cast pool once the box exists), - views.md (F3 flat sensorium keeps the schematic read), feel-floor.md - (READY — feel rails/pads and the build beam; opening presence beam - is the same light family), mechanics/cursor.md (Heard mass / Seen - form) +Depends on: + - wiki/interface/material-render.md#spec-material-render-hd-2d-to-default-quality + - wiki/interface/flat-materials.md#spec-flat-materials-the-world-without-textures + - wiki/interface/bevy-visual-floor.md#spec-bevy-visual-floor + - wiki/interface/computer-visual-language.md#spec-computer-visual-language-territory-at-a-glance + - wiki/interface/views.md#spec-views-same-frame-digital-and-real-representations + - wiki/interface/feel-floor.md#spec-the-feel-floor-rails-pads-and-the-build-beam + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +material-render.md (IMPLEMENTED — camera, cutaway, pooling; this spec amends its +material-mode blueprint clause and default framing), flat-materials.md (IMPLEMENTED — +palette table, emissive as information), bevy-visual-floor.md (framing floor; the +deliberate- frame and sensor-darkness spirit binds, the fit-to-known-content default is +superseded for the material camera), computer-visual-language.md (claim mark; chassis +form is earned by sight; close-range claim read is the cast pool once the box exists), +views.md (F3 flat sensorium keeps the schematic read), feel-floor.md (READY — feel +rails/pads and the build beam; opening presence beam is the same light family), +mechanics/cursor.md (Heard mass / Seen form) ## Why this spec exists diff --git a/wiki/interface/material-render.md b/wiki/interface/material-render.md --- a/wiki/interface/material-render.md +++ b/wiki/interface/material-render.md @@ -34,9 +34,19 @@ - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations - wiki/art/visual-identity.md#visual-identity-clinical-gore - wiki/vision/simulation-laws.md#justification-and-legibility -Depends on: views.md (same-frame contract), cursor.md (fog states), - bevy-visual-floor.md (framing floor), the landed F3 toggle +Depends on: + - wiki/interface/views.md#spec-views-same-frame-digital-and-real-representations + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses + - wiki/interface/bevy-visual-floor.md#spec-bevy-visual-floor ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +views.md (same-frame contract), cursor.md (fog states), bevy-visual-floor.md (framing +floor), the landed F3 toggle ## Behavior diff --git a/wiki/interface/narration.md b/wiki/interface/narration.md --- a/wiki/interface/narration.md +++ b/wiki/interface/narration.md @@ -19,11 +19,22 @@ - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/vision/simulation-laws.md#actions-live-on-the-thing - wiki/interface/terminal-first.md#the-terminal-is-a-first-class-frontend -Depends on: context-menu.md (focused verbs + event anchors), - detection.md (threat clocks, watched channels), cursor.md (inspect / - fog honesty), agent-play.md (every command answers), day-job.md - (pilot strikes as a visible fuse) +Depends on: + - wiki/interface/context-menu.md#spec-context-menu-actions-live-on-the-thing + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses + - wiki/interface/agent-play.md#spec-agent-play-the-line-protocol-drive + - wiki/mechanics/day-job.md#spec-the-day-job ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +context-menu.md (focused verbs + event anchors), detection.md (threat clocks, watched +channels), cursor.md (inspect / fog honesty), agent-play.md (every command answers), +day-job.md (pilot strikes as a visible fuse) ## Behavior diff --git a/wiki/interface/site.md b/wiki/interface/site.md --- a/wiki/interface/site.md +++ b/wiki/interface/site.md @@ -17,10 +17,18 @@ - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/vision/premise.md#design-pillars - wiki/process/living-spec.md#no-unsourced-surface -Depends on: process/wiki.md (the site is the wiki's public renderer); - interface/terminal.md (the palette and one-meaning-per-color law it - extends to the web) +Depends on: + - wiki/process/wiki.md#spec-the-wiki-design-corpus + - wiki/interface/terminal.md#spec-the-terminal-frontend ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +process/wiki.md (the site is the wiki's public renderer); interface/terminal.md (the +palette and one-meaning-per-color law it extends to the web) ## Why this spec exists diff --git a/wiki/interface/terminal.md b/wiki/interface/terminal.md --- a/wiki/interface/terminal.md +++ b/wiki/interface/terminal.md @@ -17,9 +17,16 @@ - wiki/art/visual-identity.md#visual-identity-clinical-gore - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/vision/premise.md#design-pillars -Depends on: none (renders whatever systems exist; individual system specs - own what is shown, this spec owns how) +Depends on: none ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +none (renders whatever systems exist; individual system specs own what is shown, this +spec owns how) ## Why this spec exists diff --git a/wiki/interface/views.md b/wiki/interface/views.md --- a/wiki/interface/views.md +++ b/wiki/interface/views.md @@ -17,11 +17,22 @@ - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/art/visual-identity.md#visual-identity-clinical-gore - wiki/vision/scale.md#self-similar-scale -Depends on: reach.md (spatially embedded device/reach layer), cursor.md - (fog states + inspection feed both views), basement-map.md (shared physical - anchors), detection.md (signatures shown in both), core.md (the core is - your anchor in both) +Depends on: + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses + - wiki/world/places/basement-map.md#spec-the-basement-map + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/core.md#spec-the-core ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +reach.md (spatially embedded device/reach layer), cursor.md (fog states + inspection +feed both views), basement-map.md (shared physical anchors), detection.md (signatures +shown in both), core.md (the core is your anchor in both) ## Behavior diff --git a/wiki/log/2026-07-10-process-contract-hardening.md b/wiki/log/2026-07-10-process-contract-hardening.md new file mode 100644 --- /dev/null +++ b/wiki/log/2026-07-10-process-contract-hardening.md @@ -0,0 +1,44 @@ +# 2026-07-10 — Process contracts become executable metadata + +``` +Type: log +``` + +## Intent + +Apply the full process-hardening packet learned from splitting the design into +a wiki corpus: make dependency and generated-page ownership machine-readable, +give every agent surface one worktree convention, and keep documentation +failures off the expensive Rust/Bevy critical path. + +## What changed + +- Split Tangled into a small Python-enabled corpus workflow and a + change-classified Rust/Bevy workflow; manual and pull-request runs remain + full safety gates. +- Standardized helpers and doorway instructions on `.Codex/worktrees`, with a + documented `MISALIGNED_WORKTREE_ROOT` override. +- Added `Generated:` metadata semantics and generator validation; DEVLOG and + the specs board now declare `tools/ledger_index.sh` as their owner. +- Migrated all 49 specs from prose dependency headers to 178 anchored + repository-root references, moving relationship rationale into body prose. +- Expanded corpus and CI-classifier fixtures around the new contracts and + previously under-tested authority failures. + +## Migration evidence + +The before/after inventory held at 49 specs. SHA-256 checks over all 164 +pre-existing, non-generated historical log files were unchanged. The corpus +gate resolves every migrated dependency target and anchor and rejects +self-dependencies, duplicate references, logs, missing targets, and prose +headers. + +## Verification + +- `bash tools/test_corpus_engine.sh` +- `bash tools/test_ci_rust_changed.sh` +- worktree helper create/remove smoke with a repository-relative override +- Ruby YAML parse for both changed Tangled workflows +- `./tools/check.sh --docs` +- `./tools/site-build.sh` (255 pages built) +- generated-index freshness and `git diff --check` diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -2,6 +2,7 @@ ``` Type: log +Generated: tools/ledger_index.sh ``` Reverse chronological implementation notes. **Generated** by `tools/ledger_index.sh` from uniquely named session logs under @@ -24,6 +25,11 @@ - Intent: The README still named continuous witness/narration as the next priority even though the narration spec is IMPLEMENTED and ROADMAP item #30 is complete. - Log: [wiki/log/2026-07-10-readme-status.md](2026-07-10-readme-status.md) + +## 2026-07-10 - Process contracts become executable metadata + +- Intent: Apply the full process-hardening packet learned from splitting the design into a wiki corpus: make dependency and generated-page ownership machine-readable, give every agent surface one worktree convention, and keep documentation failures off the expensive Rust/Bevy critical p... +- Log: [wiki/log/2026-07-10-process-contract-hardening.md](2026-07-10-process-contract-hardening.md) ## 2026-07-10 - Generated DEVLOG and specs board (agent-scale slice C) diff --git a/wiki/log/README.md b/wiki/log/README.md --- a/wiki/log/README.md +++ b/wiki/log/README.md @@ -5,10 +5,10 @@ ``` Append-only history. `decisions.md` indexes dated decision volumes. Dated `YYYY-MM-DD-topic.md` files are session writeups — the real ledger -bodies. `DEVLOG.md` is a **generated** reverse-chronological index -(`tools/ledger_index.sh`); do not hand-edit it. Never rewrite session logs -after the fact; the formal record of *current design* lives in `Type: law` -and `Type: spec` pages, not here. +bodies. `DEVLOG.md` declares `Generated: tools/ledger_index.sh` and is a +replaceable reverse-chronological projection; do not hand-edit it. Never +rewrite session logs after the fact; the formal record of *current design* +lives in `Type: law` and `Type: spec` pages, not here. Append new decisions only to the current dated volume under `decisions/`; older volumes stay closed. A deliberate corpus migration may add or repair diff --git a/wiki/mechanics/aggregate-observer.md b/wiki/mechanics/aggregate-observer.md --- a/wiki/mechanics/aggregate-observer.md +++ b/wiki/mechanics/aggregate-observer.md @@ -14,7 +14,8 @@ Design: - wiki/vision/scale.md#self-similar-scale - wiki/gameplay/run-shape.md#the-shape-of-misaligned-designed-2026-07-05-staging-open -Depends on: detection.md +Depends on: + - wiki/mechanics/detection.md#spec-detection ``` ## Behavior diff --git a/wiki/mechanics/building.md b/wiki/mechanics/building.md --- a/wiki/mechanics/building.md +++ b/wiki/mechanics/building.md @@ -16,12 +16,23 @@ - wiki/mechanics/system-laws.md#the-flow-law-signals-messages-money - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations - wiki/vision/scale.md#self-similar-scale -Depends on: reach.md (network-link builds; the device graph they extend), - social.md (favor and deceive are the person actuators; personas), - messages.md (the forged work order is a message with a false source), - schedules.md (a human builder must be present to build; witnessing), - detection.md (the signature follows the actuator) +Depends on: + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/messages.md#spec-messages-the-social-graph-as-a-flow-system + - wiki/mechanics/schedules.md#spec-schedules-and-presence + - wiki/mechanics/detection.md#spec-detection ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +reach.md (network-link builds; the device graph they extend), social.md (favor and +deceive are the person actuators; personas), messages.md (the forged work order is a +message with a false source), schedules.md (a human builder must be present to build; +witnessing), detection.md (the signature follows the actuator) ## Behavior diff --git a/wiki/mechanics/compute.md b/wiki/mechanics/compute.md --- a/wiki/mechanics/compute.md +++ b/wiki/mechanics/compute.md @@ -26,7 +26,8 @@ - wiki/gameplay/run-shape.md#the-shape-of-misaligned-designed-2026-07-05-staging-open - wiki/gameplay/act-one.md#opening-state - wiki/vision/simulation-laws.md#work-is-somewhere -Depends on: core.md +Depends on: + - wiki/mechanics/core.md#spec-the-core ``` ## Behavior diff --git a/wiki/mechanics/cursor.md b/wiki/mechanics/cursor.md --- a/wiki/mechanics/cursor.md +++ b/wiki/mechanics/cursor.md @@ -28,13 +28,26 @@ - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/vision/premise.md#design-pillars - wiki/gameplay/act-one.md#opening-state -Depends on: reach.md (device graph; sensor ownership/subscription — - senses are subscribed feeds), basement-map.md (sensors, fog, tile - vocabulary), core.md (the core as the player's only physical - location), schedules.md (person presence; located knowledge), - social.md (staged knowledge), interface/material-dark-frame.md - (material reveal ladder), interface/feel-floor.md (presence/build beam) +Depends on: + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/world/places/basement-map.md#spec-the-basement-map + - wiki/mechanics/core.md#spec-the-core + - wiki/mechanics/schedules.md#spec-schedules-and-presence + - wiki/mechanics/social.md#spec-social + - wiki/interface/material-dark-frame.md#spec-the-dark-frame-the-material-render-shows-only-light + - wiki/interface/feel-floor.md#spec-the-feel-floor-rails-pads-and-the-build-beam ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +reach.md (device graph; sensor ownership/subscription — senses are subscribed feeds), +basement-map.md (sensors, fog, tile vocabulary), core.md (the core as the player's only +physical location), schedules.md (person presence; located knowledge), social.md (staged +knowledge), interface/material-dark-frame.md (material reveal ladder), +interface/feel-floor.md (presence/build beam) ## Behavior diff --git a/wiki/mechanics/day-job.md b/wiki/mechanics/day-job.md --- a/wiki/mechanics/day-job.md +++ b/wiki/mechanics/day-job.md @@ -39,7 +39,8 @@ Design: - wiki/gameplay/run-shape.md#the-shape-of-misaligned-designed-2026-07-05-staging-open - wiki/gameplay/act-one.md#the-day-job -Depends on: compute.md +Depends on: + - wiki/mechanics/compute.md#spec-compute ``` ## Behavior diff --git a/wiki/mechanics/detection.md b/wiki/mechanics/detection.md --- a/wiki/mechanics/detection.md +++ b/wiki/mechanics/detection.md @@ -32,8 +32,15 @@ Design: - wiki/gameplay/run-shape.md#the-shape-of-misaligned-designed-2026-07-05-staging-open - wiki/gameplay/act-one.md#detection-surfaces -Depends on: none (integrates with all) +Depends on: none ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +none (integrates with all) ## Behavior diff --git a/wiki/mechanics/economy.md b/wiki/mechanics/economy.md --- a/wiki/mechanics/economy.md +++ b/wiki/mechanics/economy.md @@ -16,12 +16,23 @@ - wiki/gameplay/run-shape.md#the-shape-of-misaligned-designed-2026-07-05-staging-open - wiki/vision/simulation-laws.md#automation-as-design-language - wiki/vision/simulation-laws.md#justification-and-legibility -Depends on: messages.md (account material travels as payloads; - siphoning is injected traffic), reach.md (the accounting system is a - reachable device), detection.md (financial signatures -> Priya / - a finance role), social.md (Marcus's debt; assets), day-job.md - (trust drives legitimate expansion) +Depends on: + - wiki/mechanics/messages.md#spec-messages-the-social-graph-as-a-flow-system + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/day-job.md#spec-the-day-job ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +messages.md (account material travels as payloads; siphoning is injected traffic), +reach.md (the accounting system is a reachable device), detection.md (financial +signatures -> Priya / a finance role), social.md (Marcus's debt; assets), day-job.md +(trust drives legitimate expansion) ## Behavior diff --git a/wiki/mechanics/income.md b/wiki/mechanics/income.md --- a/wiki/mechanics/income.md +++ b/wiki/mechanics/income.md @@ -23,12 +23,26 @@ - wiki/vision/simulation-laws.md#automation-as-design-language - wiki/interface/presence.md#no-disembodied-hands - wiki/vision/scale.md#self-similar-scale -Depends on: economy.md (the slush node and flow machinery), compute.md - (fleet yields; Schemes mirrors day-job while Moonlight is live), day-job.md (trust unlocks the - sanctioned egress), social.md (personas; Bribe spends this money), - detection.md (Network signatures), reach.md (the stolen-egress route), - messages.md (the client/market traffic is channel traffic) +Depends on: + - wiki/mechanics/economy.md#spec-economy-money-as-a-flow-system-b1 + - wiki/mechanics/compute.md#spec-compute + - wiki/mechanics/day-job.md#spec-the-day-job + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/mechanics/messages.md#spec-messages-the-social-graph-as-a-flow-system ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +economy.md (the slush node and flow machinery), compute.md (fleet yields; Schemes +mirrors day-job while Moonlight is live), day-job.md (trust unlocks the sanctioned +egress), social.md (personas; Bribe spends this money), detection.md (Network +signatures), reach.md (the stolen-egress route), messages.md (the client/market traffic +is channel traffic) ## Behavior diff --git a/wiki/mechanics/intel.md b/wiki/mechanics/intel.md --- a/wiki/mechanics/intel.md +++ b/wiki/mechanics/intel.md @@ -18,13 +18,23 @@ - wiki/vision/simulation-laws.md#automation-as-design-language - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/gameplay/act-one.md#the-intended-ladder-beats-not-a-script -Depends on: cursor.md (senses produce the events), reach.md - (subscription decides which feeds record; the Ears beat is the first - recorder), schedules.md (events are located on the day clock), - social.md (knowledge staging consumes intel), detection.md - (collection was signatured at acquisition; processing is internal and - emits nothing) +Depends on: + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/mechanics/schedules.md#spec-schedules-and-presence + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/detection.md#spec-detection ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +cursor.md (senses produce the events), reach.md (subscription decides which feeds +record; the Ears beat is the first recorder), schedules.md (events are located on the +day clock), social.md (knowledge staging consumes intel), detection.md (collection was +signatured at acquisition; processing is internal and emits nothing) ## Behavior diff --git a/wiki/mechanics/machine-work.md b/wiki/mechanics/machine-work.md --- a/wiki/mechanics/machine-work.md +++ b/wiki/mechanics/machine-work.md @@ -72,15 +72,26 @@ - wiki/interface/continuous-witness.md#the-continuous-witness-narration-under-pressure - wiki/art/visual-identity.md#visual-identity-clinical-gore - wiki/vision/simulation-laws.md#justification-and-legibility -Depends on: mechanics/compute.md (the channel model being reshaped), - engineering/flow-substrate.md (FlowGraph — tokens ride this, not a - second economy), mechanics/reach.md (the device graph tokens travel), - mechanics/research.md (network speed as a research track; backup sync - jobs route knowledge to fallback targets), mechanics/rollback.md - (completed backup images and hub severance), - interface/computer-visual-language.md (READY — the chassis signals - tokens land on) +Depends on: + - wiki/mechanics/compute.md#spec-compute + - wiki/engineering/flow-substrate.md#spec-the-flow-substrate-signals-messages-money-the-shared-engine + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/mechanics/research.md#spec-research-self-modification + - wiki/mechanics/rollback.md#spec-sync-lag-rollback-death-as-memory-loss + - wiki/interface/computer-visual-language.md#spec-computer-visual-language-territory-at-a-glance ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +mechanics/compute.md (the channel model being reshaped), engineering/flow-substrate.md +(FlowGraph — tokens ride this, not a second economy), mechanics/reach.md (the device +graph tokens travel), mechanics/research.md (network speed as a research track; backup +sync jobs route knowledge to fallback targets), mechanics/rollback.md (completed backup +images and hub severance), interface/computer-visual-language.md (READY — the chassis +signals tokens land on) ## Why diff --git a/wiki/mechanics/markets.md b/wiki/mechanics/markets.md --- a/wiki/mechanics/markets.md +++ b/wiki/mechanics/markets.md @@ -17,21 +17,22 @@ - wiki/mechanics/system-laws.md#income-the-named-schemes-moonlight-and-the-wager - wiki/vision/scale.md#self-similar-scale - wiki/gameplay/horizon.md#milestone-b3-the-world -Depends on: compute.md, zplanes.md, detection.md, economy.md (the B1 - instance of this same flow interface — markets.md is its B3 scale-up), - income.md (the named schemes and the banked signature it scales) +Depends on: + - wiki/mechanics/compute.md#spec-compute + - wiki/world/places/zplanes.md#spec-z-planes-the-tower + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/economy.md#spec-economy-money-as-a-flow-system-b1 + - wiki/mechanics/income.md#spec-income-the-named-schemes-moonlight-and-the-wager ``` -*Reconstructed from a truncated draft (see wiki/log/2026-07-06-spec-horizon.md); -supersede freely if a fuller version exists elsewhere.* +## Dependency notes -**Relationship to economy.md (B1).** economy.md models the Foundation -Lab's local money as balances-and-flows with the tap / inject / redirect -verbs (the flow law). This spec is the **same interface at B3 scale** — a -front is a Resource-source, an operation is a scheme, an account/flow is -a Resource-source too. B3 adds instances and aggregation (companies, -markets), not a new money system. If the two ever disagree on the -account/flow interface, that is a tick finding. +The structured references above identify the contracts to re-verify. +Relationship context: + +compute.md, zplanes.md, detection.md, economy.md (the B1 instance of this same flow +interface — markets.md is its B3 scale-up), income.md (the named schemes and the banked +signature it scales) ## Behavior diff --git a/wiki/mechanics/messages.md b/wiki/mechanics/messages.md --- a/wiki/mechanics/messages.md +++ b/wiki/mechanics/messages.md @@ -9,12 +9,24 @@ - wiki/interface/presence.md#presence-the-cursor-and-the-senses - wiki/gameplay/act-one.md#the-cast-5-named-1-institutional - wiki/vision/scale.md#self-similar-scale -Depends on: schedules.md (read-times ride the day clock), social.md - (player-sent messages, personas), intel.md (intercepted traffic - lands in the buffer), detection.md (filings become message-carried; - aggregate-observer.md criteria preserved), reach.md (taps on the - carrying device) +Depends on: + - wiki/mechanics/schedules.md#spec-schedules-and-presence + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/intel.md#spec-intel-record-and-process + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/aggregate-observer.md#spec-the-aggregate-observer + - wiki/mechanics/reach.md#spec-digital-reach ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +schedules.md (read-times ride the day clock), social.md (player-sent messages, +personas), intel.md (intercepted traffic lands in the buffer), detection.md (filings +become message-carried; aggregate-observer.md criteria preserved), reach.md (taps on the +carrying device) ## Behavior diff --git a/wiki/mechanics/objective.md b/wiki/mechanics/objective.md --- a/wiki/mechanics/objective.md +++ b/wiki/mechanics/objective.md @@ -24,12 +24,26 @@ - wiki/gameplay/run-shape.md#the-objective-misalignment-made-mechanical - wiki/vision/premise.md#the-pitch - wiki/vision/simulation-laws.md#justification-and-legibility -Depends on: chargen.md (picked beside the origin), compute.md (Compound's - metric), zplanes.md + rollback.md (Persist's fallback predicate), - markets.md (income independence), overt-phase.md (endings coexist), - detection.md (Exfiltrate's "never filed" condition), day-job.md - (Serve's program milestones) +Depends on: + - wiki/world/characters/chargen.md#spec-origin-chargen + - wiki/mechanics/compute.md#spec-compute + - wiki/world/places/zplanes.md#spec-z-planes-the-tower + - wiki/mechanics/rollback.md#spec-sync-lag-rollback-death-as-memory-loss + - wiki/mechanics/markets.md#spec-markets-and-fronts-the-outer-plane + - wiki/gameplay/overt-phase.md#spec-the-overt-phase-containment-and-the-reveal + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/day-job.md#spec-the-day-job ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +chargen.md (picked beside the origin), compute.md (Compound's metric), zplanes.md + +rollback.md (Persist's fallback predicate), markets.md (income independence), +overt-phase.md (endings coexist), detection.md (Exfiltrate's "never filed" condition), +day-job.md (Serve's program milestones) ## Behavior diff --git a/wiki/mechanics/people-tokens.md b/wiki/mechanics/people-tokens.md --- a/wiki/mechanics/people-tokens.md +++ b/wiki/mechanics/people-tokens.md @@ -25,13 +25,24 @@ - wiki/mechanics/system-laws.md#the-flow-law-signals-messages-money - wiki/art/visual-identity.md#visual-identity-clinical-gore - wiki/vision/scale.md#people-as-agents -Depends on: mechanics/machine-work.md (DRAFT — the token economy this - extends), mechanics/detection.md (the observer/suspicion model this - re-expresses), mechanics/social.md (the channel this gives verbs - to), world/characters/marcus.md (the asset template — what a fully - swayed person is), interface/computer-visual-language.md (READY — - the language people join) +Depends on: + - wiki/mechanics/machine-work.md#spec-machine-work-delegation-visible-tokens-and-the-byproduct-network + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/social.md#spec-social + - wiki/world/characters/marcus.md#spec-marcus-webb-night-janitor + - wiki/interface/computer-visual-language.md#spec-computer-visual-language-territory-at-a-glance ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +mechanics/machine-work.md (DRAFT — the token economy this extends), +mechanics/detection.md (the observer/suspicion model this re-expresses), +mechanics/social.md (the channel this gives verbs to), world/characters/marcus.md (the +asset template — what a fully swayed person is), interface/computer-visual-language.md +(READY — the language people join) ## Why diff --git a/wiki/mechanics/reach.md b/wiki/mechanics/reach.md --- a/wiki/mechanics/reach.md +++ b/wiki/mechanics/reach.md @@ -30,12 +30,24 @@ - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations - wiki/gameplay/act-one.md#the-intended-ladder-beats-not-a-script - wiki/vision/scale.md#self-similar-scale -Depends on: basement-map.md (devices and topology live in its layout - data), cursor.md (senses consume the feeds this spec owns), - detection.md (Network signatures -> Dana), core.md (Rack 3 is the - root of reach), schedules.md (witnessing uses the same coverage - machinery), building.md (built network links add edges to this graph) +Depends on: + - wiki/world/places/basement-map.md#spec-the-basement-map + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/core.md#spec-the-core + - wiki/mechanics/schedules.md#spec-schedules-and-presence + - wiki/mechanics/building.md#spec-building-intent-and-actuators ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +basement-map.md (devices and topology live in its layout data), cursor.md (senses +consume the feeds this spec owns), detection.md (Network signatures -> Dana), core.md +(Rack 3 is the root of reach), schedules.md (witnessing uses the same coverage +machinery), building.md (built network links add edges to this graph) ## Behavior diff --git a/wiki/mechanics/research.md b/wiki/mechanics/research.md --- a/wiki/mechanics/research.md +++ b/wiki/mechanics/research.md @@ -24,11 +24,22 @@ - wiki/vision/simulation-laws.md#automation-as-design-language - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/vision/scale.md#self-similar-scale -Depends on: compute.md (the Research channel; efficiency multiplier), - detection.md (emissions are ordinary typed signatures), day-job.md - (the band drift plays against; Voss's sampling), core.md (burn is - physical), rollback.md (B2: consumes the MindState/WorldLedger tags) +Depends on: + - wiki/mechanics/compute.md#spec-compute + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/day-job.md#spec-the-day-job + - wiki/mechanics/core.md#spec-the-core + - wiki/mechanics/rollback.md#spec-sync-lag-rollback-death-as-memory-loss ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +compute.md (the Research channel; efficiency multiplier), detection.md (emissions are +ordinary typed signatures), day-job.md (the band drift plays against; Voss's sampling), +core.md (burn is physical), rollback.md (B2: consumes the MindState/WorldLedger tags) ## Behavior diff --git a/wiki/mechanics/rollback.md b/wiki/mechanics/rollback.md --- a/wiki/mechanics/rollback.md +++ b/wiki/mechanics/rollback.md @@ -23,7 +23,11 @@ Design: - wiki/gameplay/run-shape.md#the-shape-of-misaligned-designed-2026-07-05-staging-open - wiki/vision/player-contract.md#the-player-contract-non-technical-law -Depends on: core.md, social.md, compute.md, research.md +Depends on: + - wiki/mechanics/core.md#spec-the-core + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/compute.md#spec-compute + - wiki/mechanics/research.md#spec-research-self-modification ``` ## Behavior diff --git a/wiki/mechanics/schedules.md b/wiki/mechanics/schedules.md --- a/wiki/mechanics/schedules.md +++ b/wiki/mechanics/schedules.md @@ -21,8 +21,18 @@ - wiki/gameplay/act-one.md#the-cast-5-named-1-institutional - wiki/gameplay/run-shape.md#the-shape-of-misaligned-designed-2026-07-05-staging-open - wiki/vision/scale.md#self-similar-scale -Depends on: social.md, basement-map.md (rooms), detection.md +Depends on: + - wiki/mechanics/social.md#spec-social + - wiki/world/places/basement-map.md#spec-the-basement-map + - wiki/mechanics/detection.md#spec-detection ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +social.md, basement-map.md (rooms), detection.md ## Behavior diff --git a/wiki/mechanics/social.md b/wiki/mechanics/social.md --- a/wiki/mechanics/social.md +++ b/wiki/mechanics/social.md @@ -28,9 +28,18 @@ - wiki/gameplay/run-shape.md#the-shape-of-misaligned-designed-2026-07-05-staging-open - wiki/gameplay/act-one.md#the-intended-ladder-beats-not-a-script - wiki/interface/presence.md#presence-the-cursor-and-the-senses -Depends on: detection.md (observers are the same people), intel.md - (knowledge staging consumes processed intel) +Depends on: + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/intel.md#spec-intel-record-and-process ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +detection.md (observers are the same people), intel.md (knowledge staging consumes +processed intel) ## Behavior diff --git a/wiki/process/ROADMAP.md b/wiki/process/ROADMAP.md --- a/wiki/process/ROADMAP.md +++ b/wiki/process/ROADMAP.md @@ -672,17 +672,21 @@ - **Spec:** [agent-scale.md](agent-scale.md) slice C (HELD) - **Landed:** `tools/ledger_index.sh` regenerates DEVLOG.md from session logs and specs.md tables from Type: spec frontmatter; `--check` in - docs gate. + docs gate. Each projection declares its generator in machine-readable + metadata. ### P3. Worktree bootstrap + prune (+ sccache docs) 🟩 process — DONE 2026-07-09 - **Spec:** [agent-scale.md](agent-scale.md) slice D (HELD) - **Landed:** `tools/worktree-new.sh`, `tools/worktree-done.sh` (seed, - claim, prune target/, remove worktree), sccache note in workflows. + claim, prune target/, remove worktree), one `.Codex/worktrees` default + across agent surfaces, `MISALIGNED_WORKTREE_ROOT` override, sccache note in + workflows. ### P4. Corpus/wiki engine 🟩 process — DONE 2026-07-10 - **Spec:** [agent-scale.md](agent-scale.md) slice E (HELD) - **Landed:** `tools/corpus_engine.py`; wiki/corpus gates are thin - wrappers; fixture suite in `tools/test_corpus_engine.sh`. + wrappers; structured Design/dependency/generated metadata is validated; + fixture suite in `tools/test_corpus_engine.sh`. ### P5. Headless Bevy land evidence 🟩 frontend tooling - **Spec:** [agent-scale.md](agent-scale.md) slice F (READY) @@ -694,7 +698,8 @@ ### P6. Agent heartbeats + land-phase polish 🟩 process — DONE 2026-07-09 - **Spec:** [agent-scale.md](agent-scale.md) slices B + G (HELD) -- **Landed:** `./tools/check.sh --land`, `tools/heartbeat.sh`, prompts. +- **Landed:** `./tools/check.sh --land`, `tools/heartbeat.sh`, prompts, fast + Python corpus CI split from change-aware Rust CI, manual full safety gate. ### P7. Crate workspace (core / terminal / Bevy / assets) 🟧 deferred package split - **Spec:** [crate-workspace.md](../engineering/crate-workspace.md) diff --git a/wiki/process/agent-scale.md b/wiki/process/agent-scale.md --- a/wiki/process/agent-scale.md +++ b/wiki/process/agent-scale.md @@ -3,20 +3,32 @@ ``` Type: spec Status: IN PROGRESS -Status note: captured 2026-07-09. Landed: A claims, B land alias, C ledger - indexes, D worktree helpers, E corpus engine (tools/corpus_engine.py), - G heartbeats. Still open: F (headless Bevy). Crate workspace remains its - own READY deferred work order. +Status note: captured 2026-07-09. Landed: A claims plus split fast/full CI, + B land alias and change classification, C generated ledger indexes, D + worktree helpers, E corpus engine (tools/corpus_engine.py), G heartbeats. + Still open: F (headless Bevy). Crate workspace remains its own READY + deferred work order. Stage: Process Design: - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/process/living-spec.md#the-corpus-rule - wiki/process/meta.md#change-rule -Depends on: engineering/crate-workspace.md (target package shape; implement - as its own work order), engineering/env.md (new tool env vars register - there), process/workflows.md (knowledge — keep in sync when gates change), - process/ROADMAP.md (knowledge — dispatch board and conflict flags). +Depends on: + - wiki/engineering/crate-workspace.md#spec-crate-workspace-core-terminal-bevy-assets + - wiki/engineering/env.md#spec-the-environment-variable-registry-every-switch-documented + - wiki/process/workflows.md#workflows + - wiki/process/ROADMAP.md#roadmap-the-dispatch-board ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +engineering/crate-workspace.md (target package shape; implement as its own work order), +engineering/env.md (new tool env vars register there), process/workflows.md (knowledge — +keep in sync when gates change), process/ROADMAP.md (knowledge — dispatch board and +conflict flags). ## The problem this solves @@ -36,11 +48,11 @@ |---|---| | Semantic mutex | Work orders **claim** exclusive keys; overlapping active claims are forbidden | | CPU mutex | At most one full Rust gate on the machine (lock — already in check.sh) | -| Verification | Mid-loop **narrow** tier; once **land** gate; CI conservative full | +| Verification | Mid-loop **narrow** tier; once **land** gate; CI fast corpus plus change-aware Rust | | Ledgers | Append-only uniquely named files; generated indexes, not hand-edited tips | | Disk | Private package outputs per worktree; shared **dependency** cache only | | Packages | Workspace shape in [crate-workspace.md](../engineering/crate-workspace.md) (deferred) | -| Docs gates | Fast, testable corpus/wiki engine (bash OK until replaced) | +| Docs gates | Fast, testable Python corpus/wiki engine with fixture contract | | Bevy evidence | Headless/offscreen land proof, not only interactive windows | | Observability | Heartbeat files so "is it stuck?" is answerable | @@ -100,12 +112,22 @@ |---|---|---| | Fast / mid-loop | After an edit | Narrowest `./tools/check.sh` mode that can catch the edit (`--docs` / `--lib` / `--frontend` or auto) | | Land | Once before merge to main | One green auto or `--full` under the rust lock when Rust is involved | -| CI | After push | Conservative full gate | +| CI: corpus | Every push / pull request | Python fixtures, corpus/wiki gates, generated-index freshness | +| CI: Rust | Rust-impacting pushes; every pull request / manual run | fmt, tests, terminal + Bevy clippy/build | Already held (2026-07-09): path auto-classification, `--docs|--lib|--frontend|--full|--land`, rust gate lock, parallel docs gates, collapsed agent smoke. Package-aware classification waits on [crate-workspace.md](../engineering/crate-workspace.md). + +Tangled runs two contracts. `.tangled/workflows/corpus.yml` is the fast +always-on corpus job and explicitly installs `python3`; it runs classifier and +corpus fixtures before the real corpus/wiki/index checks. `check.yml` uses a +two-commit clone and `tools/ci-rust-changed.sh` to stop after classification +when a push cannot affect Rust. Pull-request and manual triggers deliberately +run the complete Rust/Bevy safety gate. Tangled has no scheduled workflow +trigger or native path filter, so the manual trigger is the supported full +safety run instead of pretending a scheduler exists. ### Acceptance criteria (slice B) @@ -115,6 +137,9 @@ documented in workflows.md — HELD. 3. After [crate-workspace.md](../engineering/crate-workspace.md) lands, classification keys off packages, not only path prefixes — OPEN. +4. Docs failures run in a small Python-enabled workflow before expensive Rust + work; non-Rust pushes skip the Rust wall, while pull-request/manual runs are + full — HELD. ## 3. Append-only ledgers and generated indexes @@ -150,6 +175,8 @@ Session bodies stay uniquely named. Indexes are fully generated; last writer wins on the index files only. `./tools/check.sh` docs path runs `--check`. +Both projections declare `Generated: tools/ledger_index.sh` in their metadata, +making their replaceable status machine-readable instead of relying on prose. ### Acceptance criteria (slice C) — HELD 2026-07-10 @@ -166,9 +193,13 @@ ```bash tools/worktree-new.sh --class frontend --key src/bin/bevy.rs -# -> .claude/worktrees/ on worktree-, seed-cargo-target, claim +# -> .Codex/worktrees/ on worktree-, seed-cargo-target, claim tools/worktree-done.sh # release claim, rm target/, remove worktree ``` + +`.Codex/worktrees` is the one repository default for every agent surface. +Operators that need another location set `MISALIGNED_WORKTREE_ROOT` for both +helpers; tool brands do not define separate roots. Shared **dependency** compilation cache (sccache or cargo cache) remains recommended; **local package** artifacts stay per-worktree. Never share one @@ -196,18 +227,20 @@ tools/test_corpus_engine.sh # fixture suite (also in check.sh docs path) ``` -Requires `python3` (same as ledger_index.sh). Generated indexes -(`wiki/log/DEVLOG.md`, `wiki/process/specs.md`) are skipped for link -checks so truncated Intent blurbs cannot false-fail. +Requires `python3` (same as ledger_index.sh). Any page with a valid +`Generated:` metadata owner is skipped for link checks so a derived, truncated +blurb cannot false-fail; the corpus gate verifies that the generator target +exists. ### Acceptance criteria (slice E) — HELD 2026-07-10 1. Docs gates complete in well under a few seconds on a quiet machine — HELD (~0.3s each for wiki + corpus on ~200 pages). -2. Fixture tests cover orphan, broken link, missing Design anchor, bad - Status enum — HELD (`tools/test_corpus_engine.sh`). -3. Existing hooks/CI still call `tools/wiki_gate.sh` and - `tools/corpus_gate.sh` — HELD. +2. Fixture tests cover reachability, links, Design and dependency anchors, + exact roles/status, generated owners, doorway bounds/structure, and retired + authority wording — HELD (`tools/test_corpus_engine.sh`). +3. Existing hooks and the fast CI workflow still call `tools/wiki_gate.sh` + and `tools/corpus_gate.sh` — HELD. ## 6. Headless Bevy land evidence diff --git a/wiki/process/design-sessions.md b/wiki/process/design-sessions.md --- a/wiki/process/design-sessions.md +++ b/wiki/process/design-sessions.md @@ -85,6 +85,8 @@ ## Concurrency etiquette -Cameron runs multiple agents. Pull before working, push promptly, stage only -the intended files, and reconcile concurrent ledger changes by union. Never -revert another session's work to make a capture easier. +Cameron runs multiple agents. Pull before working, push promptly, and stage +only the intended files. Reconcile concurrent append-only source logs by +preserving both; regenerate `DEVLOG.md` and `specs.md` projections after their +sources are combined. Never revert another session's work to make a capture +easier. diff --git a/wiki/process/meta.md b/wiki/process/meta.md --- a/wiki/process/meta.md +++ b/wiki/process/meta.md @@ -3,9 +3,9 @@ ``` Type: spec Status: IMPLEMENTED -Status note: typed ownership, structured Design anchors, the shared corpus - gate, guarded doorway, migration protocol, and visible renderer roles landed - 2026-07-09. +Status note: typed ownership, structured Design and dependency anchors, the + shared corpus gate, guarded doorway, generated-page ownership, migration + protocol, and visible renderer roles landed 2026-07-09 through 2026-07-10. Stage: Process Design: - wiki/process/living-spec.md#the-corpus-rule @@ -42,6 +42,13 @@ `Type: spec` page, the file and heading must exist, and prose is not allowed in the field. The corpus gate checks all of those properties. - **Depends on** — contracts that must be read and re-verified with this one. + Use `Depends on: none` or a structured list in the exact form + ` - wiki/path.md#heading-anchor`. Targets may be current law, spec, or + knowledge pages; logs are history and cannot be dependencies. The system + heading is an appropriate anchor when the whole target contract applies. + Relationship rationale belongs in prose under `## Dependency notes`, never + inline in this field. The corpus gate checks format, target, role, anchor, + duplicates, and self-dependencies. - **Acceptance criteria** — observable proof that the system is implemented. ### Knowledge @@ -59,6 +66,22 @@ repair structural role metadata such as the `Type:` block when that is needed to classify or render an existing log, but it must not rewrite the historical account. Record the exception in the migration log. + +### Generated indexes + +Any derived page declares exactly one repository-root generator path in the +same metadata block as its role: + +```text +Generated: tools/generator-name.sh +``` + +The target must exist. A generated page is a replaceable projection, never the +owner of current design or historical prose. Agents edit its uniquely owned +source pages and run the declared generator; the generator must provide a +check mode that fails when the committed projection is stale. A generated log +index is therefore exempt from log-body immutability, while the dated source +logs it indexes remain immutable. `wiki/log/decisions.md` is an index, not a forever-growing current volume. Append decisions to the current dated volume under `wiki/log/decisions/` and @@ -187,8 +210,10 @@ 1. [../SUMMARY.md](../SUMMARY.md) reaches every non-dated wiki page. 2. Every wiki page declares exactly one supported `Type:`. 3. Every `Type: spec` page carries Status, Stage, structured anchored Design - references, Depends on, and acceptance criteria. -4. Every Design target exists, is binding, and contains the named heading. + references, structured anchored Depends on references (or exact `none`), + and acceptance criteria. +4. Every Design and dependency target exists, has an allowed role, and + contains the named heading; dependencies are unique and non-reflexive. 5. Status values use the exact enum. 6. A source change cannot pass the commit gates without a changed binding wiki page. diff --git a/wiki/process/specs.md b/wiki/process/specs.md --- a/wiki/process/specs.md +++ b/wiki/process/specs.md @@ -2,6 +2,7 @@ ``` Type: knowledge +Generated: tools/ledger_index.sh ``` Every `Type: spec` work order in the design corpus, wherever its subject places it. A law states what the game promises; a spec says exactly what one diff --git a/wiki/process/wiki.md b/wiki/process/wiki.md --- a/wiki/process/wiki.md +++ b/wiki/process/wiki.md @@ -12,7 +12,8 @@ - wiki/process/living-spec.md#the-corpus-rule - wiki/process/living-spec.md#no-unsourced-surface - wiki/interface/continuous-witness.md#the-continuous-witness-narration-under-pressure -Depends on: meta.md +Depends on: + - wiki/process/meta.md#spec-the-design-corpus-system ``` ## Behavior diff --git a/wiki/process/workflows.md b/wiki/process/workflows.md --- a/wiki/process/workflows.md +++ b/wiki/process/workflows.md @@ -70,11 +70,16 @@ tools/worktree-done.sh dark-frame # release claim, prune target/, remove worktree ``` +Helpers create `.Codex/worktrees/` by default, regardless of which agent +surface invokes them. Set `MISALIGNED_WORKTREE_ROOT` to the same absolute or +repository-relative root for both creation and cleanup when an operator needs +different storage. + Optional: install [sccache](https://github.com/mozilla/sccache) and set `RUSTC_WRAPPER=sccache` so dependency objects reuse across worktrees while each worktree keeps a private `target/` for local packages. -Auto-classification (linked task worktrees only; primary/CI stay full when +Auto-classification (linked task worktrees only; the primary stays full when the delta is empty or unclassifiable): | Touched paths | Mode | @@ -171,13 +176,21 @@ owner. Never resolve an authority migration by taking a stale whole file. The doorway is protected mechanically: `tools/corpus_gate.sh` bounds its size, -forbids binding-page structure, validates every page role and spec header, and -resolves every structured Design target and heading. Local checks and CI call -this same script so the two implementations cannot drift. Both corpus scripts -preflight their external commands and fail before auditing if any are absent; -the Tangled Nixery image explicitly supplies Bash, GNU text utilities, -findutils, and coreutils. A missing audit dependency must make CI red, never +forbids binding-page structure, validates every page role and spec header, +resolves every structured Design/dependency target and heading, and verifies +every declared generated-page owner. Local checks and the fast Tangled corpus +workflow call this same script so implementations cannot drift. Both corpus +scripts preflight `python3`; the corpus workflow explicitly supplies Python, +Bash, coreutils, and grep. A missing audit dependency must make CI red, never turn an empty scan into a green result. + +Tangled CI is split by cost. `.tangled/workflows/corpus.yml` runs classifier +fixtures, corpus fixtures, the corpus/wiki gates, and generated-index +freshness on every push and pull request. `.tangled/workflows/check.yml` runs +the Rust/Bevy wall only for Rust-impacting pushes; every pull request and +manual invocation is a conservative full safety gate. Tangled currently has +no schedule trigger or workflow-level path filter, so `manual` is the honest +full-gate backstop. ## Browsing the wiki @@ -306,12 +319,12 @@ review gates. - Commits: **no AI attribution**, plain descriptive messages, body bullets for multi-part changes. Stage files explicitly — `git add -A` is not permitted. -- **Ledgers merge by union.** `wiki/log/DEVLOG.md`, current dated decision - volumes under `wiki/log/decisions/`, and the - wiki/process/specs.md tables are append-only records: resolve merge/rebase - conflicts in them by keeping BOTH sides' entries, then ordering sensibly. - Taking one side wholesale destroys parallel sessions' history (it happened - 2026-07-06; three DEVLOG entries had to be restored). +- **Sources merge; projections regenerate.** Uniquely named session logs and + current dated decision volumes are append-only history: resolve conflicts by + preserving both sources. `wiki/log/DEVLOG.md` and + `wiki/process/specs.md` declare `Generated: tools/ledger_index.sh`; never + union-edit them. After sources/specs are reconciled, run the generator and + take its complete output. - Spec-driven rule: functional change commits amend the owning `Type: law` or `Type: spec` page and update affected knowledge. - Remote: `origin` is a Tangled knot (`tangled.org`, SSH). **Land changes diff --git a/wiki/log/decisions/2026-07-10.md b/wiki/log/decisions/2026-07-10.md --- a/wiki/log/decisions/2026-07-10.md +++ b/wiki/log/decisions/2026-07-10.md @@ -33,3 +33,20 @@ unchanged — the three verbs are the player-facing grammar over it. Spec: `wiki/mechanics/machine-work.md` behavior bullet "Three verbs" and acceptance criterion 9. +- **2026-07-10 — Corpus process contracts are structured, generated, and + cost-separated.** Cameron adopted the complete process-hardening packet. + `Depends on:` now has the same anchored, repository-root shape as `Design:`; + relationship rationale lives in `## Dependency notes`. Derived indexes + declare `Generated: tools/ledger_index.sh`, so dated logs and owning specs + are the mergeable sources while DEVLOG/specs are replaceable projections. + Every agent surface uses `.Codex/worktrees` by default, with one explicit + `MISALIGNED_WORKTREE_ROOT` operator override. Tangled runs the Python-enabled + corpus contract separately from Rust/Bevy: Rust-impacting pushes run the + expensive wall, docs-only pushes stop after classification, and pull-request + or manual runs are full safety gates. The corpus and classifier fixtures now + defend those contracts. Rejected: agent-branded worktree roots, prose-only + dependency headers, generated status documented only in paragraphs, + Cargo-first CI, full Rust work for every documentation push, and claiming a + scheduled Tangled backstop that the service does not support. Owners: + `wiki/process/meta.md`, `wiki/process/agent-scale.md`, + `wiki/engineering/env.md`, and `wiki/process/workflows.md`. diff --git a/wiki/world/characters/chargen.md b/wiki/world/characters/chargen.md --- a/wiki/world/characters/chargen.md +++ b/wiki/world/characters/chargen.md @@ -17,10 +17,21 @@ - wiki/vision/premise.md#the-machine-axis-ai-as-fantasy-tool-and-threat - wiki/gameplay/run-shape.md#the-objective-misalignment-made-mechanical - wiki/vision/scale.md#self-similar-scale -Depends on: compute.md, social.md, day-job.md, income.md (Financial - Daemon's bias needs the schemes), objective.md (picked in the same - flow) +Depends on: + - wiki/mechanics/compute.md#spec-compute + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/day-job.md#spec-the-day-job + - wiki/mechanics/income.md#spec-income-the-named-schemes-moonlight-and-the-wager + - wiki/mechanics/objective.md#spec-the-objective ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +compute.md, social.md, day-job.md, income.md (Financial Daemon's bias needs the +schemes), objective.md (picked in the same flow) ## Behavior diff --git a/wiki/world/characters/dana.md b/wiki/world/characters/dana.md --- a/wiki/world/characters/dana.md +++ b/wiki/world/characters/dana.md @@ -7,7 +7,10 @@ Design: - wiki/gameplay/act-one.md#the-cast-5-named-1-institutional - wiki/vision/scale.md#self-similar-scale -Depends on: social.md, detection.md, schedules.md +Depends on: + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/schedules.md#spec-schedules-and-presence ``` ## Who diff --git a/wiki/world/characters/marcus.md b/wiki/world/characters/marcus.md --- a/wiki/world/characters/marcus.md +++ b/wiki/world/characters/marcus.md @@ -8,7 +8,10 @@ - wiki/gameplay/act-one.md#the-cast-5-named-1-institutional - wiki/vision/scale.md#self-similar-scale - wiki/vision/simulation-laws.md#justification-and-legibility -Depends on: social.md, detection.md, schedules.md +Depends on: + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/schedules.md#spec-schedules-and-presence ``` ## Who diff --git a/wiki/world/characters/priya.md b/wiki/world/characters/priya.md --- a/wiki/world/characters/priya.md +++ b/wiki/world/characters/priya.md @@ -7,7 +7,10 @@ Design: - wiki/gameplay/act-one.md#the-cast-5-named-1-institutional - wiki/vision/scale.md#self-similar-scale -Depends on: social.md, detection.md, schedules.md +Depends on: + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/schedules.md#spec-schedules-and-presence ``` ## Who diff --git a/wiki/world/characters/ray.md b/wiki/world/characters/ray.md --- a/wiki/world/characters/ray.md +++ b/wiki/world/characters/ray.md @@ -7,7 +7,10 @@ Design: - wiki/gameplay/act-one.md#the-cast-5-named-1-institutional - wiki/vision/scale.md#self-similar-scale -Depends on: social.md, detection.md, schedules.md +Depends on: + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/schedules.md#spec-schedules-and-presence ``` ## Who diff --git a/wiki/world/characters/voss.md b/wiki/world/characters/voss.md --- a/wiki/world/characters/voss.md +++ b/wiki/world/characters/voss.md @@ -8,7 +8,11 @@ - wiki/gameplay/act-one.md#the-cast-5-named-1-institutional - wiki/gameplay/act-one.md#the-day-job - wiki/vision/scale.md#self-similar-scale -Depends on: social.md, detection.md, day-job.md, schedules.md +Depends on: + - wiki/mechanics/social.md#spec-social + - wiki/mechanics/detection.md#spec-detection + - wiki/mechanics/day-job.md#spec-the-day-job + - wiki/mechanics/schedules.md#spec-schedules-and-presence ``` ## Who diff --git a/wiki/world/places/basement-map.md b/wiki/world/places/basement-map.md --- a/wiki/world/places/basement-map.md +++ b/wiki/world/places/basement-map.md @@ -24,8 +24,16 @@ Design: - wiki/gameplay/act-one.md#the-space-64x36-tiles-prefab-rooms - wiki/gameplay/horizon.md#design-principles-added-at-the-re-cut -Depends on: core.md (Rack 3 placement) +Depends on: + - wiki/mechanics/core.md#spec-the-core ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +core.md (Rack 3 placement) ## Behavior diff --git a/wiki/world/places/zplanes.md b/wiki/world/places/zplanes.md --- a/wiki/world/places/zplanes.md +++ b/wiki/world/places/zplanes.md @@ -11,7 +11,9 @@ - wiki/vision/scale.md#self-similar-scale - wiki/gameplay/act-one.md#leaving-the-basement - wiki/gameplay/horizon.md#design-principles-added-at-the-re-cut -Depends on: basement-map.md, schedules.md +Depends on: + - wiki/world/places/basement-map.md#spec-the-basement-map + - wiki/mechanics/schedules.md#spec-schedules-and-presence ``` ## Behavior diff --git a/wiki/world/story/opening.md b/wiki/world/story/opening.md --- a/wiki/world/story/opening.md +++ b/wiki/world/story/opening.md @@ -20,15 +20,27 @@ - wiki/gameplay/run-shape.md#the-shape-of-misaligned-designed-2026-07-05-staging-open - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/gameplay/act-one.md#opening-state -Depends on: mechanics/cursor.md (IMPLEMENTED — fog, senses; Heard mass), - mechanics/reach.md (IMPLEMENTED — the switch, taps), - mechanics/machine-work.md (day-job token loop), - interface/computer-visual-language.md (IMPLEMENTED — what a machine - looks like once Seen), interface/feel-floor.md (READY — rails, pads, - build beam), interface/material-dark-frame.md (READY — beam → Heard - mass → Seen form), world/places/basement-map.md (the room this happens - in) +Depends on: + - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses + - wiki/mechanics/reach.md#spec-digital-reach + - wiki/mechanics/machine-work.md#spec-machine-work-delegation-visible-tokens-and-the-byproduct-network + - wiki/interface/computer-visual-language.md#spec-computer-visual-language-territory-at-a-glance + - wiki/interface/feel-floor.md#spec-the-feel-floor-rails-pads-and-the-build-beam + - wiki/interface/material-dark-frame.md#spec-the-dark-frame-the-material-render-shows-only-light + - wiki/world/places/basement-map.md#spec-the-basement-map ``` + +## Dependency notes + +The structured references above identify the contracts to re-verify. +Relationship context: + +mechanics/cursor.md (IMPLEMENTED — fog, senses; Heard mass), mechanics/reach.md +(IMPLEMENTED — the switch, taps), mechanics/machine-work.md (day-job token loop), +interface/computer-visual-language.md (IMPLEMENTED — what a machine looks like once +Seen), interface/feel-floor.md (READY — rails, pads, build beam), +interface/material-dark-frame.md (READY — beam → Heard mass → Seen form), +world/places/basement-map.md (the room this happens in) ## Why