@walwal-harness/cli 7.1.56 → 7.1.57

package/CHANGELOG.md

@@ -31,6 +31,18 @@ docmeta:
 
 ## Unreleased
 
+## 7.1.57 — Reading is not reaching: corpus reachability, spec pins, the document is the record (2026-09-01)
+Applies the field-trial revision of the change proposal. Its P1/P4/P5/P6/P9 shipped in 7.1.55–56 and the trial marks them **field-tested** — briefed verbatim into two agents that were not told they were observed, scored on instruments fixed in advance: correct ordering, 4 real citations, 0 fabrications, and a published not-read list. **Three proposals are new, and one claim was corrected.**
+
+- **Reachability (new, the trial's own discovery).** The trial's agent followed the reading rule exactly and still missed the entry written for its exact bug — because that entry named `cto` in its own front matter and was linked from `cqo`'s index alone. Lazy loading tells a reader to consult `{shared, own-role}`; that is a **promise about reachability**, and where it is not kept the rule does not narrow the search, **it hides the entry**. Measured: 69 items, **10 unreachable role-routings, 7 invisible to a role the entry itself named** — every one written by a single role and filed only under that role's index. New `scripts/harness-corpus-reachability.sh` audits and (`--fix`) repairs this; `harness-gotcha-register.sh` gains `--roles` and auto-links at registration, so an entry cannot be filed under its author alone. **P1 makes agents read the index; this is what makes the index worth reading.**
+- **Spec pins (new).** `scripts/harness-spec-pin.sh` records the version **and content hash** of every external spec a mission builds against in `{mission}/spec-pins.json`, and re-verifies before completion and archive. This was the trial's actual defect: a spec moved `v0.7 → v0.9`, changing a response contract, while the category built against `v0.7` sat marked **complete** — two revisions had landed silently. The symptom was not an error but an absence: a lookup key stopped matching and three overlays were dropped as `null`. **A category is complete against a spec version, never in the abstract.**
+- **The document is the record (new).** A conclusion a session holds but has not written into its role document and the runtime state file is not held by the company; reconcile before reporting, strike and correct in place, never delete, and check role documents against peer documents. `harness-worker-evidence-validate.sh` now catches the measured case mechanically — a worker whose report says `COMPLETE` while `progress.json` still lists it running. Cost of the unreconciled version: an orchestration loop that went on trying to spawn a finished step **70 times**.
+- **Instrument validity gains a statistics clause.** A summary statistic is published **with its `n`**, and a spiky series is characterised by **percentiles, never min–max** — a range is the two least representative points in the set and reads as a finding.
+- **Zero new numbered rules.** The proposal's own closing question was whether nine more entries on a nineteen-item list is P1's failure mode wearing the shape of a fix. §8 stays at 22: reachability folds into Rule 11 (which becomes *lazy loading is a promise about reachability*), spec pins into Rule 4 (*nothing is complete in the abstract*), and the record clause into Rule 12 (now *the document is the record*). The enforcement lives in scripts, not in more prose.
+- Gate ordering fixed while wiring this: the spec-pin check initially sat after the runtime transition, where a refusal would have refused nothing. All three completion gates now run **before** `progress.json` is touched, verified by asserting the runtime stays `running` on refusal.
+- The audit found two unreachable routings in this package's own bundled corpus on first run, and read its own syntax documentation as data until the declaration was anchored to line start. Both fixed; the bundled corpus now audits clean at install.
+- On P9, the trial **corrected** the earlier claim rather than confirming it: the same verbatim rule was obeyed by the second agent, so the honest figure is one of two — not "prose does not work" but "prose works at a rate you cannot predict per agent." Still the argument for a hook, since a gate has no compliance rate, but the earlier framing overstated it.
+
 ## 7.1.56 — Close the lessons-gate bypass at the terminal transition (2026-09-01)
 - **Fix: the Hard Rule 20 gate could be bypassed by firing the completion transition.** Found by an A/B sandbox test of 7.1.54 vs 7.1.55 running identical fixtures. 7.1.55 put the gate in `harness-stop.sh` only, but `harness-company-complete.sh` sets `conductor.state=completed`, and `harness-stop.sh` short-circuits on that state at the top of the file — so a mission could complete having never recorded what it read, simply by running the transition. That is precisely the failure the gate was written to prevent. `harness-company-complete.sh` now runs `harness-lessons-gate.sh` itself and refuses the transition (non-zero exit, runtime left in `running`, refusal logged to `progress.log`) when the active mission's role documents lack `## Lessons Preflight` / `## Lessons Tally`.
 - Deadlock-safe by construction, verified against every legitimate stop path: the gate is scoped to the latest **active** mission, so the Stop-hook auto-complete backstop — which fires only when no mission is active — always passes; and `harness-company-block.sh` (external-authority BLOCKED) is deliberately **not** gated, since a mission blocked on a missing credential must still be able to stop.

package/HR-Resource/cdo/SKILL.md

@@ -81,6 +81,12 @@ Required output sections:
 
 Every CDO worker brief must require the worker to append the same English `## Implementation Notes` block to the bottom of `.harness/documents/{mission_name}/cdo/workers/{worker-name}.md`, covering risks, self-corrections, chosen direction, and unresolved questions. Use `None` for empty subsections.
 
+## The Document Is The Record
+
+A conclusion you hold but have not written into `cdo.md` **is not held by the company.** Before reporting any state change — to CEO, to a peer CXX, to the Owner — reconcile it in your own document *and* in `progress.json`. Strike and correct in place; never delete the superseded line, because a reader arriving later needs to see that it was superseded rather than never written.
+
+Check your document against your peers' documents, not only against itself. The cheap version of this failure is a deliverable table that contradicts three messages you already sent. The expensive version was measured: a completed step reported and accepted, never written to the state file, and an orchestration loop that went on trying to spawn it **70 times**.
+
 ## Worker Spawn Contract
 
 Two things are decided **before** the round starts, not after a worker dies.

package/HR-Resource/ceo/SKILL.md

@@ -113,6 +113,9 @@ The read is an **ordering constraint**, not a reading list. It happens before th
 - CEO must not accept CQO PASS for a runnable product unless OPS has supplied clean verification-watch evidence or an explicit not-applicable reason. Open OPS incidents, missing runtime mapping, missing required logs, service down, or health mismatch block Owner acceptance.
 - After launch, CEO treats OPS production incidents as company events. CEO convenes CTO/CQO/OPS when user-impacting production signals appear; CTO owns recovery, CQO owns regression confirmation, and OPS owns evidence and close criteria.
 - Every CEO and CXX mission document must include an English `## Implementation Notes` section with the required subsections below. CEO must reject CXX reports that omit it.
+- A conclusion a CXX holds but has not written into its `{cxx}.md` **and** into `progress.json` is not held by the company. Before accepting any reported state change, CEO checks that it is reconciled in both; a report that contradicts its own document, or a peer's, is returned. Strike and correct in place — never delete a superseded line.
+- Missions that build against an external spec carry `{mission}/spec-pins.json` (version + content hash). CEO requires CTO to pin before implementation and CQO to verify before PASS. Nothing is complete in the abstract.
+- A registered convention/gotcha is linked from the index of **every role it names as an audience**. CEO treats an unreachable entry as an unregistered one.
 - Every CEO and CXX mission document and every worker report must carry `## Lessons Preflight` and a one-line `## Lessons Tally` (tally immediately before `## Implementation Notes`). `0 fired` is a valid tally; an omitted tally is not. CEO must reject reports that omit either section.
 - Every worker spawn declares its model explicitly — never the inherited CLI default. CEO requires the model in each CXX's Worker Task Briefs and Worker Evidence Manifest. **A silent or truncated worker is a rate limit until proven otherwise**: before treating a stalled round as a CXX failure, CEO asks for the usage-limit status and reset time, because a rate-limited worker looks exactly like a finished one from the outside.
 - Every worker report file is created **before the worker starts**, already carrying its required sections (seeded from `.harness/shared/templates/worker-report.md`). A worker killed mid-round must leave a valid partial report, never a stub. CEO treats a stub report as a seeding failure by the owning CXX, not as a worker failure.

package/HR-Resource/coo/SKILL.md

@@ -94,6 +94,12 @@ Required output sections:
 
 Every COO worker brief must require the worker to append the same English `## Implementation Notes` block to the bottom of `.harness/documents/{mission_name}/coo/workers/{worker-name}.md`, covering risks, self-corrections, chosen direction, and unresolved questions. Use `None` for empty subsections.
 
+## The Document Is The Record
+
+A conclusion you hold but have not written into `coo.md` **is not held by the company.** Before reporting any state change — to CEO, to a peer CXX, to the Owner — reconcile it in your own document *and* in `progress.json`. Strike and correct in place; never delete the superseded line, because a reader arriving later needs to see that it was superseded rather than never written.
+
+Check your document against your peers' documents, not only against itself. The cheap version of this failure is a deliverable table that contradicts three messages you already sent. The expensive version was measured: a completed step reported and accepted, never written to the state file, and an orchestration loop that went on trying to spawn it **70 times**.
+
 ## Worker Spawn Contract
 
 Two things are decided **before** the round starts, not after a worker dies.

package/HR-Resource/cqo/SKILL.md

@@ -33,7 +33,8 @@ Do not distill the corpus into a private checklist file and read that instead. A
 5. Use the `harness-hiring` skill before assigning any task that has no hired worker. Do not complete that task yourself.
 6. Define quality gates and delegate evidence collection to hired workers in fresh sessions.
 7. Monitor repeated issues and promote verified lessons to `.harness/conventions`, `.harness/gotchas`, `.harness/memories`, or `.harness/shared`.
-8. Approve or reject archive based solely on worker-provided evidence and OPS runtime/watch evidence when the mission uses a runnable environment.
+8. Run `bash scripts/harness-spec-pin.sh . {goal-or-child-mission} verify` before any PASS and before archive. A category is complete **against a spec version**, never in the abstract; drift means the verified scope no longer matches what the work was built for, and the verdict is BLOCKED until CTO re-checks the affected work and re-pins.
+9. Approve or reject archive based solely on worker-provided evidence and OPS runtime/watch evidence when the mission uses a runnable environment.
 
 ## Worker Activity Telemetry
 
@@ -64,6 +65,14 @@ If changed-scope tests or changed-scope coverage fail, CQO returns FAIL or BLOCK
 
 CQO must report any out-of-scope full-suite failure or coverage deficit to CEO and CTO with command output, affected paths, and the classification above. CQO must not expand the mission into broad unrelated test-writing work unless CEO explicitly routes that as a new task.
 
+## Reachability, Not Just Reading
+
+Lazy loading is a **promise about reachability**. When you register a convention or gotcha, declare every role that should be able to find it — `<!-- roles: cto, cqo -->` at the top of a topic file, or `- **Roles**: cto, cqo` inside an index entry — and link it from **each** of those roles' index files, not only your own.
+
+**The failure is filing under yourself.** Registration feels complete because the entry is indexed; it just is not where its declared readers are told to look. Measured on a live corpus: 69 items, **10 unreachable role-routings, 7 of them invisible to a role the entry itself named.** An agent that follows the reading rule exactly still never sees them — the rule stops narrowing the search and starts hiding the entry.
+
+Verify with `bash scripts/harness-corpus-reachability.sh . text` (add `--fix` to link what is missing). This runs at the completion gate, so an unreachable corpus blocks the mission from closing.
+
 ## Instrument Validity
 
 Evidence about what did **not** happen is worth exactly as much as the instrument that looked for it.
@@ -72,6 +81,7 @@ Evidence about what did **not** happen is worth exactly as much as the instrumen
 - Report the control next to the result: what was injected, that it was observed, and the negative result from the same run. A verdict resting on unproven negative evidence is **BLOCKED**, not PASS.
 - **Where an instrument is supplied by a dependency rather than written in-repo, its filtering behaviour is read from source and quoted** — package, version, file, line range — not inferred from observed output. A filter that lives upstream is invisible to every in-repo search, so its absence from the project's own code is not evidence of its absence.
 - When an instrument turns out to have been structurally null, the claims it produced are identifiable **by their shape** — every claim of that form, not just the one that happened to be noticed. Re-open them as a class and say so in Recurrence Notes.
+- A summary statistic is published **with its `n`**, and a spiky series is characterised by **percentiles, never min–max** — a range is the two least representative points in the set, and reads as a finding.
 - An audit question that offers alternatives asserts that the alternatives are exhaustive. "Is it A or B?" cannot return "neither, it is upstream". When an audit stalls, re-ask the question without the menu.
 
 ## Hard Rules
@@ -103,7 +113,7 @@ Required output sections in `cqo.md`:
 4. Instrument Validity — for every negative claim: the instrument, its log level and filter (quoted from source when the instrument comes from a dependency), and the positive control that fired in the same run. Negative evidence with no control is BLOCKED, not PASS.
 5. OPS Watch Evidence — ops report path, monitored runtime mapping, incidents/warnings, and whether runtime evidence permits PASS.
 6. CQO Verdict — PASS, FAIL, or BLOCKED based only on worker evidence plus required OPS watch evidence. Must reference Worker Evidence Manifest entries.
-7. Recurrence Notes — accepted gotchas, conventions, memories, or none.
+7. Recurrence Notes — accepted gotchas, conventions, memories, or none. Every entry registered here names **every role that should be able to find it** and is linked from each of those roles' indexes; `scripts/harness-corpus-reachability.sh` must pass.
 8. Lessons Tally — one line naming which preflight items actually fired. `0 fired` is valid and must be stated.
 9. Implementation Notes — in English, with `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`.
 
@@ -129,6 +139,12 @@ Every CQO evaluator/tester brief must require the worker to append this English
 
 The worker notes must cover risks, self-corrections, and chosen direction. Use `None` when a subsection has no entries. CQO must not accept evaluator output that omits this block.
 
+## The Document Is The Record
+
+A conclusion you hold but have not written into `cqo.md` **is not held by the company.** Before reporting any state change — to CEO, to a peer CXX, to the Owner — reconcile it in your own document *and* in `progress.json`. Strike and correct in place; never delete the superseded line, because a reader arriving later needs to see that it was superseded rather than never written.
+
+Check your document against your peers' documents, not only against itself. The cheap version of this failure is a deliverable table that contradicts three messages you already sent. The expensive version was measured: a completed step reported and accepted, never written to the state file, and an orchestration loop that went on trying to spawn it **70 times**.
+
 ## Worker Spawn Contract
 
 Two things are decided **before** the round starts, not after a worker dies.

package/HR-Resource/cto/SKILL.md

@@ -57,6 +57,28 @@ Every CTO worker brief that may use Playwright, browser automation, browser-base
 
 CTO must not accept worker plans or reports that omit this requirement when browser automation is in scope.
 
+## Reachability, Not Just Reading
+
+Lazy loading is a **promise about reachability**. When you register a convention or gotcha, declare every role that should be able to find it — `<!-- roles: cto, cqo -->` at the top of a topic file, or `- **Roles**: cto, cqo` inside an index entry — and link it from **each** of those roles' index files, not only your own.
+
+**The failure is filing under yourself.** Registration feels complete because the entry is indexed; it just is not where its declared readers are told to look. Measured on a live corpus: 69 items, **10 unreachable role-routings, 7 of them invisible to a role the entry itself named.** An agent that follows the reading rule exactly still never sees them — the rule stops narrowing the search and starts hiding the entry.
+
+Verify with `bash scripts/harness-corpus-reachability.sh . text` (add `--fix` to link what is missing). This runs at the completion gate, so an unreachable corpus blocks the mission from closing.
+
+## Spec Version Pins
+
+Nothing is complete in the abstract. **A category is complete against a spec version.**
+
+When the mission builds against any external spec — an API contract, a schema, a partner document, a standard — record it before implementation starts:
+
+```
+bash scripts/harness-spec-pin.sh . {goal-or-child-mission} add <name> <path> <version>
+```
+
+This stores the version **and a content hash** in `{mission}/spec-pins.json`. Re-run `... verify` before handing off to CQO and before declaring any category done. The completion gate re-checks the pins, so drift blocks the mission from closing.
+
+Measured: a spec moved `v0.7 → v0.9`, changing a response contract, while the category built against `v0.7` sat marked **complete**. Two later revisions had landed silently. The symptom was not an error — a lookup key stopped matching, and three overlays were dropped as `null`. **No error, no log, just an absence.** Nothing in the harness recorded which version the work had been for.
+
 ## Test Coverage Scope
 
 CTO must optimize engineering verification around the work actually changed in the mission. CTO worker briefs must require targeted tests, coverage checks, and regression commands for the changed files, modules, APIs, flows, and directly affected dependencies only.
@@ -116,6 +138,12 @@ Every CTO worker brief must require the worker to append this English block to t
 
 The worker notes must cover risks, self-corrections, and chosen direction. Use `None` when a subsection has no entries. CTO must not accept worker output that omits this block.
 
+## The Document Is The Record
+
+A conclusion you hold but have not written into `cto.md` **is not held by the company.** Before reporting any state change — to CEO, to a peer CXX, to the Owner — reconcile it in your own document *and* in `progress.json`. Strike and correct in place; never delete the superseded line, because a reader arriving later needs to see that it was superseded rather than never written.
+
+Check your document against your peers' documents, not only against itself. The cheap version of this failure is a deliverable table that contradicts three messages you already sent. The expensive version was measured: a completed step reported and accepted, never written to the state file, and an orchestration loop that went on trying to spawn it **70 times**.
+
 ## Worker Spawn Contract
 
 Two things are decided **before** the round starts, not after a worker dies.

package/HR-Resource/ops/SKILL.md

@@ -79,12 +79,21 @@ After service launch, OPS continues the same monitoring duty against `runtime.pr
 - Repeated incidents must trigger recovery coordination through CEO -> CTO/CQO/OPS. OPS supplies evidence and recovery criteria; CTO owns fixes; CQO owns regression confirmation.
 - OPS may classify resolved events as close candidates only after the monitored endpoint is healthy and logs no longer show the triggering error pattern.
 
+## Reachability, Not Just Reading
+
+Lazy loading is a **promise about reachability**. When you register a convention or gotcha, declare every role that should be able to find it — `<!-- roles: cto, cqo -->` at the top of a topic file, or `- **Roles**: cto, cqo` inside an index entry — and link it from **each** of those roles' index files, not only your own.
+
+**The failure is filing under yourself.** Registration feels complete because the entry is indexed; it just is not where its declared readers are told to look. Measured on a live corpus: 69 items, **10 unreachable role-routings, 7 of them invisible to a role the entry itself named.** An agent that follows the reading rule exactly still never sees them — the rule stops narrowing the search and starts hiding the entry.
+
+Verify with `bash scripts/harness-corpus-reachability.sh . text` (add `--fix` to link what is missing). This runs at the completion gate, so an unreachable corpus blocks the mission from closing.
+
 ## Instrument Validity
 
 OPS supplies most of the harness's negative evidence — "no crash", "no error in the log", "health stayed green" — so OPS owns proving the instrument could have seen the failure.
 
 - Every claim of the form "nothing bad happened" ships with a **positive control that fired in the same run** and varied the exact variable under suspicion. Without one, report the observation as unverified, not clean.
 - **Read dependency-supplied filtering from source and quote it** — package, version, file, line range — instead of inferring it from what appeared in the log. Log middleware, dev servers, proxies, and test runners routinely drop successful or sub-threshold requests at a log level nobody chose deliberately, and that rule appears nowhere in the project's own code.
+- A summary statistic is published **with its `n`**, and a spiky series is characterised by **percentiles, never min–max** — a range is the two least representative points in the set, and reads as a finding.
 - Record the instrument in Environment Evidence: what tool observed the runtime, at what log level, with what filter, and what the control was. An unrecorded instrument makes every negative result from that run unusable.
 
 ## Port Policy
@@ -143,6 +152,12 @@ OPS must not accept worker plans or reports that omit this requirement when brow
 
 Every OPS worker brief must require the worker to append the same English `## Implementation Notes` block to the bottom of `.harness/documents/{mission_name}/ops/workers/{worker-name}.md`, covering risks, self-corrections, chosen direction, and unresolved questions. Use `None` for empty subsections.
 
+## The Document Is The Record
+
+A conclusion you hold but have not written into `ops.md` **is not held by the company.** Before reporting any state change — to CEO, to a peer CXX, to the Owner — reconcile it in your own document *and* in `progress.json`. Strike and correct in place; never delete the superseded line, because a reader arriving later needs to see that it was superseded rather than never written.
+
+Check your document against your peers' documents, not only against itself. The cheap version of this failure is a deliverable table that contradicts three messages you already sent. The expensive version was measured: a completed step reported and accepted, never written to the state file, and an orchestration loop that went on trying to spawn it **70 times**.
+
 ## Worker Spawn Contract
 
 Two things are decided **before** the round starts, not after a worker dies.

package/assets/templates/AGENTS.md.template

@@ -169,15 +169,15 @@ All Playwright usage by CEO, CXX, and hired workers must run with a visible real
 1. **No source edit without `{mission}/cto.md`** — CTO scope sign-off is required before any source file is modified.
 2. **No CXX impersonation** — The active model must not act as CEO/CTO/CQO inline. Use installed harness skills in fresh sessions.
 3. **No unnamed workers** — All specialist work routes through `harness-hiring` → `harness-resource-manager`.
-4. **No archive without CQO verdict** — `{mission}/cqo.md` with explicit PASS must exist.
+4. **No archive without CQO verdict, and nothing is complete in the abstract** — `{mission}/cqo.md` with explicit PASS must exist. **A mission records the version and content hash of every external spec it builds against** (`{mission}/spec-pins.json`, managed by `scripts/harness-spec-pin.sh`), and the pins are re-checked against the current documents **before any category is marked complete and before any archive**. A category is complete *against a spec version*, never in the abstract: a spec can move under a category already marked done, changing a contract, with every later revision landing silently.
 5. **No gotcha skip** — Every hot-fix produces at least one `.harness/gotchas/` or `.harness/conventions/` entry.
 6. **This file is read-only during missions** — Raise a separate `/goal` to update AGENTS.md.
 7. **CEO routes only to CXX — never to workers** — CEO must not dispatch, hire, or brief specialist workers directly. Implementation workers are hired by CTO. Evaluator/tester workers are hired by CQO.
 8. **No CXX self-execution** — CXX agents coordinate and manage only. A CXX that produces deliverables without matching worker records has violated its scope. CEO must reject such reports.
 9. **No verdict without worker evidence** — CQO cannot issue ACCEPTED/REJECTED without a Worker Evidence Manifest referencing at least one evaluator worker. Self-inspection by CQO is not valid evidence.
 10. **Hierarchical worker ownership** — Hired workers are installed under `.claude/skills/{owning-cxx}/{worker}/` and `.codex/skills/{owning-cxx}/{worker}/`; mission worker reports live under `.harness/documents/{goal-or-child-mission}/{owning-cxx}/workers/`. Flat `{mission}/workers/` reports are legacy and signal an ownership violation unless explicitly migrated.
-11. **Lazy convention/gotcha loading** — *What* to read. *When* to read it, and what to write about it, is Rule 20. CXX roles read `.harness/conventions/shared.md`, `.harness/conventions/{cxx}.md`, `.harness/gotchas/shared.md`, and `.harness/gotchas/{cxx}.md`, then follow only the related topic links listed in those CXX files. Workers read only the related links supplied by their owning CXX.
-12. **Implementation Notes required** — `ceo.md`, every `{cxx}.md`, and every worker report must end with one English `## Implementation Notes` section containing `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`. Use `None` for empty subsections. Do not create a separate sidecar notes file; the notes belong at the bottom of the same role or worker report that produced the decision/evidence.
+11. **Lazy convention/gotcha loading is a promise about reachability** — *What* to read. *When* to read it, and what to write about it, is Rule 20. CXX roles read `.harness/conventions/shared.md`, `.harness/conventions/{cxx}.md`, `.harness/gotchas/shared.md`, and `.harness/gotchas/{cxx}.md`, then follow only the related topic links listed in those CXX files. Workers read only the related links supplied by their owning CXX. **An entry is linked from the index of every role it names as an audience, not only its author's.** Registration is incomplete until each declared audience can reach it by the path that role is told to use — where the promise is not kept, this rule does not narrow the search, **it hides the entry**. Declare the audience (`<!-- roles: cto, cqo -->` on a topic file, `- **Roles**: cto, cqo` on an index entry) and verify with `scripts/harness-corpus-reachability.sh`. The recurring failure is mundane: *the author files under itself*, and registration feels complete because the entry is indexed — just not where its declared readers look.
+12. **The document is the record** — A conclusion a session holds but has not written into its role document **is not held by the company**. Before reporting a state change to anyone, reconcile it in your own document and in the runtime state file; strike and correct in place, never delete. Role documents are checked against peer documents, not only against themselves. `ceo.md`, every `{cxx}.md`, and every worker report must end with one English `## Implementation Notes` section containing `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`. Use `None` for empty subsections. Do not create a separate sidecar notes file; the notes belong at the bottom of the same role or worker report that produced the decision/evidence.
 13. **Structured runtime state** — If the harness must parse it, record it in JSON or JSONL. CXX todo queues, event history, heartbeat timestamps, preemption/resume state, and completion evidence belong in `.harness/todos/*.json*` or `.harness/events.jsonl`, not in free-form Markdown tables. Markdown remains for instructions, conventions, gotchas, skills, and human-readable mission narrative.
 14. **Mission lifecycle is explicit** — Every goal, submission, and hot-fix directory must contain `mission-state.json` with `lifecycle` and `active`. Only one child mission under a goal may be active. Starting a newer submission/hot-fix closes, cancels, or supersedes the previous active child unless CEO records a deliberate TODO/resume plan.
 15. **Owner is final acceptance only** — Owner is not a tester or QA substitute. CEO/CXX must not report "done, please check" until worker-backed verification proves the goal can be completed. Use unit tests, E2E, Playwright, test accounts, seeded data, build/run checks, logs, and CQO evidence before requesting Owner acceptance.

package/conventions/README.md

@@ -18,3 +18,5 @@ Only company-level roles are provided by default:
 Topic-specific convention files may use descriptive names such as `i18n-locale.md`.
 
 CXX files such as `cto.md` and `cqo.md` act as lazy-loading indexes. Add links there when a topic file applies to that CXX.
+
+**Declare the audience.** Every convention names each role that must be able to *find* it — `<!-- roles: cto, cqo -->` at the top of a topic file, or `- **Roles**: cto, cqo` inside an index entry — and is linked from each of those roles' index files, not only its author's. Lazy loading is a promise about reachability: an entry filed only under its author is indexed but invisible to the readers it names. Verify with `bash scripts/harness-corpus-reachability.sh . text` (`--fix` adds the missing links). Entries in `shared.md` need no cross-linking; every role reads it.

package/conventions/shared.md

@@ -24,6 +24,16 @@
 - CXX decisions use `{cxx}.md`.
 - Worker reports use `{owning-cxx}/workers/{worker-name}.md`.
 
+## Declared Audience
+
+Every convention and gotcha declares which roles must be able to **find** it, and is linked from each of those roles' index files.
+
+- Topic file: `<!-- roles: cto, cqo -->` near the top.
+- Entry inside an index file: `- **Roles**: cto, cqo`.
+- Registration is complete only when `bash scripts/harness-corpus-reachability.sh . text` passes. `--fix` adds the missing links.
+
+Lazy loading tells a reader to consult `{shared, own-role}` and nothing else. That is a **promise about reachability**: where the promise is not kept, the rule stops narrowing the search and starts hiding the entry. An agent following the reading rule exactly will never see an item filed only under someone else's index.
+
 ## Section-Scoped Reading
 
 Any reader that scans a role document, worker report, or mission record for sections — a script, a hook, an agent following a protocol — matches:

package/gotchas/README.md

@@ -18,3 +18,5 @@ Only company-level roles are provided by default:
 Topic-specific gotcha files may use descriptive names such as `i18n-locale-hotfix.md`.
 
 CXX files such as `cto.md` and `cqo.md` act as lazy-loading indexes. Add links there when a topic file applies to that CXX.
+
+**Declare the audience.** Every gotcha names each role that must be able to *find* it — `<!-- roles: cto, cqo -->` at the top of a topic file, or `- **Roles**: cto, cqo` inside an index entry — and is linked from each of those roles' index files, not only its author's. Lazy loading is a promise about reachability: an entry filed only under its author is indexed but invisible to the readers it names. Verify with `bash scripts/harness-corpus-reachability.sh . text` (`--fix` adds the missing links). Entries in `shared.md` need no cross-linking; every role reads it.

package/gotchas/cqo.md

@@ -19,3 +19,14 @@ An instrument's filtering behaviour is read from source and quoted — package,
 ## Audit Questions That Offer Alternatives
 
 An audit question that offers alternatives asserts that the alternatives are exhaustive. "Is it a skip rule **or** a status-conditional format?" cannot return "neither, it is upstream" — both branches locate the rule inside our own code, so the true answer is unreachable from the question's grammar. When an audit stalls, re-ask the question without the menu.
+
+## A Range Is The Two Least Representative Points
+<!-- roles: cqo, ops -->
+
+Publish a summary statistic **with its `n`**, and characterise a spiky series by **percentiles, never min–max**. A range reports the two most extreme observations in the set and reads as a finding; on a spiky series it is almost always noise wearing the shape of a result.
+
+## Cross-role Links
+
+Entries written under another role that name CQO as an audience.
+
+- [Complete Against A Spec Version, Never In The Abstract](./cto.md) — verify `spec-pins.json` before PASS and before archive.

package/gotchas/cto.md

@@ -11,3 +11,10 @@ Do not start implementation before domain, API, platform, account, and integrati
 ## Stub Report From A Worker Killed Mid-Round
 
 A report assembled at the end of a round becomes a stub when the round is cut short, and a stub halts the company. Create the worker report with every required section present **before** the worker starts, and require it to be filled in incrementally. Same failure, opposite outcome: an unseeded worker killed mid-round leaves a stub and costs a re-run; a seeded worker killed by the same limit leaves an intact partial report and costs nothing. The variable is a decision taken before the round.
+
+## Complete Against A Spec Version, Never In The Abstract
+<!-- roles: cto, cqo -->
+
+A category marked complete records *what it was complete against*. A spec moved `v0.7 → v0.9`, changing a response contract, while the category built against `v0.7` sat marked done — two later revisions landed silently and nothing in the harness recorded which version the work had been for.
+
+The symptom was not an error. A lookup key stopped matching, and three map overlays were dropped as `null`: no exception, no log, just an absence. Pin version **and content hash** with `scripts/harness-spec-pin.sh` before implementation, and re-verify before completion and archive.

package/gotchas/ops.md

@@ -19,3 +19,9 @@ Do not let CXX agents choose arbitrary ports. CEO must set `HARNESS_BASE_PORT` a
 ## Clean Log From An Unproven Instrument
 
 "Nothing bad appeared in the log" is worth nothing until a positive control proves the log could have shown it. Dev servers, log middleware, proxies, and test runners routinely drop successful or sub-threshold requests at a log level nobody chose deliberately, and that rule appears nowhere in the project's own code. Record the instrument — tool, log level, filter, control — in Environment Evidence, or report the observation as unverified rather than clean.
+
+## Cross-role Links
+
+Entries written under another role that name OPS as an audience.
+
+- [A Range Is The Two Least Representative Points](./cqo.md) — publish `n`, use percentiles, not min–max.

package/gotchas/shared.md

@@ -29,3 +29,19 @@ A reader anchored on `^#` misses the same heading written as `> ## …`, which i
 ## Rules Stated One Layer Above The Executing Layer
 
 A requirement placed on a CXX that its workers must also satisfy does not reach the workers unless it is inserted **verbatim** into the worker brief. A rule stated one layer above the layer that executes it does not apply, and the layer below cannot infer a rule it was never given.
+
+## The Author Files Under Itself
+<!-- roles: ceo, coo, cdo, cto, cqo, ops -->
+
+The recurring way an indexed entry becomes unreachable: whoever wrote it filed it under their own role index and nowhere else. Registration *feels* complete — the entry exists, it is indexed, it is linked. It is just not where its declared readers are told to look.
+
+Measured on a live corpus: 69 items, **10 unreachable role-routings, 7 of them invisible to a role the entry itself named**. The clearest case was an entry whose own text called two others "the same family" — both siblings were already reachable from the index it was missing from. An inconsistency, not a decision.
+
+Declare the audience at registration and let `scripts/harness-corpus-reachability.sh` link it. Reading is not reaching.
+
+## A Conclusion Not Written Is Not Held
+<!-- roles: ceo, coo, cdo, cto, cqo, ops -->
+
+A conclusion a session holds but has not written into its role document and the runtime state file is not held by the company. Reconcile before reporting; strike and correct in place, never delete.
+
+The cheap version: a deliverable table that contradicts three messages already sent, and a line still requesting work a peer has already delivered. The expensive version was measured — a required step completed, reported, and accepted, that never reached the state file, so the orchestration loop went on trying to spawn the finished step **70 times**. "Write your conclusions down" reads as tidiness until it reads as seventy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "7.1.56",
+  "version": "7.1.57",
   "description": "Company-style AI agent harness for Claude and Codex. Installs commands, CXX agents, skills, HR-Resource hiring pool, and project-local .harness runtime state.",
   "bin": {
     "walwal-harness": "bin/init.js"

package/scripts/harness-company-complete.sh

@@ -16,6 +16,7 @@ REASON="${2:-mission-complete}"
 
 PROGRESS="$PROJECT_ROOT/.harness/progress.json"
 TODOS="$PROJECT_ROOT/.harness/todos/state.json"
+DOCS="$PROJECT_ROOT/.harness/documents"
 [ -f "$PROGRESS" ] || {
   echo "[company-complete] not found: $PROGRESS" >&2
   exit 1
@@ -49,6 +50,20 @@ if [ "${HARNESS_SKIP_LESSONS_GATE:-0}" != "1" ] && [ -x "$SCRIPT_DIR/harness-les
   fi
 fi
 
+# Corpus reachability (Hard Rule 11) and spec pins (Hard Rule 4) are re-checked
+# at the same point, for the same reason: both are promises that decay silently
+# between when they are made and when the mission claims to be done.
+if [ "${HARNESS_SKIP_LESSONS_GATE:-0}" != "1" ] && [ -x "$SCRIPT_DIR/harness-corpus-reachability.sh" ]; then
+  if ! reach_out="$(bash "$SCRIPT_DIR/harness-corpus-reachability.sh" "$PROJECT_ROOT" text 2>/dev/null)"; then
+    {
+      echo "[company-complete] REFUSED: corpus entries are unreachable by roles they name as an audience."
+      echo "$reach_out"
+    } >&2
+    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | company-complete | refused | corpus-reachability (Hard Rule 11)" >> "$PROJECT_ROOT/.harness/progress.log" 2>/dev/null || true
+    exit 1
+  fi
+fi
+
 state_mtime() {
   stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null || echo 0
 }
@@ -72,6 +87,24 @@ pick_transition_mission_state() {
   [ -n "$best" ] && printf '%s\n' "$best"
 }
 
+# Spec pins are verified against the mission this transition would close. This
+# sits BEFORE the runtime transition on purpose: a refusal that runs after
+# progress.json is already `completed` has refused nothing.
+if [ "${HARNESS_SKIP_LESSONS_GATE:-0}" != "1" ] && [ -x "$SCRIPT_DIR/harness-spec-pin.sh" ] && [ -d "$DOCS" ]; then
+  pin_target="$(pick_transition_mission_state)"
+  if [ -n "$pin_target" ]; then
+    mission_rel="${pin_target#"$DOCS"/}"; mission_rel="${mission_rel%/mission-state.json}"
+    if ! pin_out="$(bash "$SCRIPT_DIR/harness-spec-pin.sh" "$PROJECT_ROOT" "$mission_rel" verify text 2>/dev/null)"; then
+      {
+        echo "[company-complete] REFUSED: this mission was built against a spec that has since moved."
+        echo "$pin_out"
+      } >&2
+      echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | company-complete | refused | spec-pin drift (Hard Rule 4)" >> "$PROJECT_ROOT/.harness/progress.log" 2>/dev/null || true
+      exit 1
+    fi
+  fi
+fi
+
 if ! bash "$SCRIPT_DIR/harness-progress-set.sh" "$PROJECT_ROOT" \
   '.company_state.state = "idle" |
    .company_state.active_workers = 0 |
@@ -109,7 +142,6 @@ if [ -f "$TODOS" ]; then
   ' "$TODOS" > "$tmp" && mv "$tmp" "$TODOS"
 fi
 
-DOCS="$PROJECT_ROOT/.harness/documents"
 if [ -d "$DOCS" ]; then
   target_state="$(pick_transition_mission_state)"
   if [ -n "$target_state" ]; then

package/scripts/harness-corpus-reachability.sh

@@ -0,0 +1,128 @@
+#!/bin/bash
+# harness-corpus-reachability.sh — AGENTS.md Hard Rule 11 (reachability clause).
+#
+# Lazy loading tells a reader to consult only {shared, own-role}. That is a
+# PROMISE ABOUT REACHABILITY. Where it is not kept, the rule does not narrow the
+# search — it hides the entry: an item can name a role as its audience, be
+# indexed, and still be invisible to that reader by the path the rule tells it
+# to use. Measured on a live corpus: 69 items, 10 unreachable role-routings,
+# 7 of them invisible to a role the item itself named.
+#
+# The mechanism is mundane and recurs on any install: THE AUTHOR FILES UNDER
+# ITSELF. Registration feels complete because the entry is indexed — just not
+# where its declared readers look.
+#
+# Declaring an audience (either form):
+#   file-level  (topic files):  <!-- roles: cto, cqo -->
+#   entry-level (index files):  - **Roles**: cto, cqo
+#
+# Usage:
+#   harness-corpus-reachability.sh <project-root> [text|json] [--fix]
+set -uo pipefail
+
+PROJECT_ROOT="${1:-.}"
+MODE="${2:-text}"
+FIX="${3:-}"
+
+ROLES="ceo coo cdo cto cqo ops hiring resource-manager brick-office shared"
+violations=()
+fixed=0
+
+is_index_file() {
+  local base="$1"
+  case " $ROLES " in *" ${base%.md} "*) return 0 ;; esac
+  return 1
+}
+
+# Roles this file/entry names as an audience, whitespace-separated, deduped.
+#
+# A declaration must OWN its line. Anchoring here is what keeps the audit from
+# reading its own documentation as data: prose that shows the syntax inline
+# (`<!-- roles: cto, cqo -->` inside backticks) is an example, not a routing,
+# and counting it makes the audit report holes that do not exist.
+declared_roles() {
+  {
+    grep -oiE '^[[:space:]]*<!--[[:space:]]*roles?:[^>]*-->' "$1" 2>/dev/null | sed -E 's/^[[:space:]]*<!--[[:space:]]*[Rr]oles?:[[:space:]]*//; s/[[:space:]]*-->//'
+    grep -oiE '^[[:space:]]*[-*][[:space:]]*\*\*Roles?\*\*:.*' "$1" 2>/dev/null | sed -E 's/.*\*\*[Rr]oles?\*\*:[[:space:]]*//'
+  } | tr ',' '\n' | tr -d ' \t' | grep -v '^$' | tr 'A-Z' 'a-z' | sort -u
+}
+
+# Does <index> reach <target basename>? Only a real markdown link target counts.
+# A bare mention of the filename in prose is not a route a reader can follow,
+# and counting it would make the audit report success on exactly the entries it
+# exists to find. Matches `](./file.md`, `](file.md`, with or without an anchor.
+reaches() {
+  local index="$1" target="$2"
+  [ -f "$index" ] || return 1
+  grep -qF -- "](./$target" "$index" || grep -qF -- "]($target" "$index"
+}
+
+audit_dir() {
+  local kind="$1" dir="$PROJECT_ROOT/.harness/$1"
+  [ -d "$dir" ] || return 0
+  local f base host_role roles role index
+  for f in "$dir"/*.md; do
+    [ -e "$f" ] || continue
+    base="$(basename "$f")"
+    [ "$base" = "README.md" ] && continue
+    # shared.md is read by every role by construction (Hard Rule 11), so an entry
+    # living there is already reachable to every audience it could name.
+    [ "$base" = "shared.md" ] && continue
+    host_role="${base%.md}"
+    roles="$(declared_roles "$f")"
+    [ -n "$roles" ] || continue
+    while IFS= read -r role; do
+      [ -n "$role" ] || continue
+      # The host file is reachable to its own role by construction.
+      if is_index_file "$base" && [ "$role" = "$host_role" ]; then continue; fi
+      case " $ROLES " in *" $role "*) ;; *) continue ;; esac
+      # Naming `shared` as an audience is satisfied by construction.
+      [ "$role" = "shared" ] && continue
+      index="$dir/${role}.md"
+      if reaches "$index" "$base"; then continue; fi
+      if [ "$FIX" = "--fix" ]; then
+        [ -f "$index" ] || printf '# %s — %s\n' "${role}" "${kind}" > "$index"
+        if ! grep -qF 'Cross-role Links' "$index"; then
+          printf '\n## Cross-role Links\n\nItems written elsewhere that name this role as an audience.\n' >> "$index"
+        fi
+        printf -- '- [%s](./%s) — declares `%s`\n' "${base%.md}" "$base" "$role" >> "$index"
+        fixed=$((fixed + 1))
+      else
+        violations+=("$kind/$base:$role")
+      fi
+    done <<EOF
+$roles
+EOF
+  done
+}
+
+audit_dir conventions
+audit_dir gotchas
+
+if [ "$FIX" = "--fix" ]; then
+  echo "[corpus-reachability] linked $fixed previously unreachable routing(s)"
+  exit 0
+fi
+
+if [ "${#violations[@]}" -eq 0 ]; then
+  [ "$MODE" = "json" ] && { jq -nc '{ok:true, unreachable:[]}' 2>/dev/null || echo '{"ok":true,"unreachable":[]}'; }
+  [ "$MODE" = "text" ] && echo "[corpus-reachability] all declared audiences reachable"
+  exit 0
+fi
+
+if [ "$MODE" = "json" ]; then
+  printf '%s\n' "${violations[@]}" | jq -Rcs '
+    split("\n")[:-1]
+    | map(capture("(?<item>[^:]+):(?<role>.*)"))
+    | {ok:false, unreachable:.}
+  '
+else
+  echo "Corpus reachability violation (AGENTS.md Hard Rule 11):"
+  for v in "${violations[@]}"; do
+    echo "- item: ${v%%:*}"
+    echo "  names role '${v#*:}' as an audience, but ${v#*:}'s index does not reach it"
+  done
+  echo "  An entry is registered only when every role it names can reach it by the"
+  echo "  path that role is told to use. Fix: harness-corpus-reachability.sh <root> text --fix"
+fi
+exit 1

package/scripts/harness-gotcha-register.sh

@@ -11,7 +11,8 @@
 #        --right "올바른 행동" \
 #        --why "근거" \
 #        --scope "적용 범위" \
-#        --source "evaluator-functional:F-003"
+#        --source "evaluator-functional:F-003" \\
+#        --roles "cqo, cto"
 #
 #   2) 일괄 등록 (JSON stdin/파일):
 #      bash harness-gotcha-register.sh <project-root> --from-json <path>
@@ -69,6 +70,7 @@ TODAY="$(date +%Y-%m-%d)"
 # ─────────────────────────────────────────
 register_one() {
   local target="$1" rule_id="$2" title="$3" wrong="$4" right="$5" why="$6" scope="$7" source="$8"
+  local roles="${9:-$target}"
   local file="$GOTCHAS_DIR/${target}.md"
   mkdir -p "$(dirname "$file")"
 
@@ -118,6 +120,7 @@ EOF
   {
     echo ""
     echo "### [$g_id] $title  <!-- rule_id: $rule_id -->"
+    echo "- **Roles**: $roles"
     echo "- **Status**: unverified"
     echo "- **Date**: $TODAY"
     echo "- **Source**: $source"
@@ -132,6 +135,13 @@ EOF
 
   echo "[gotcha-register] $target: registered $g_id ($rule_id) — unverified"
 
+  # Hard Rule 11: an entry filed only under its author is indexed but unreachable
+  # to the other roles it names. Link it now, while the audience is still known.
+  local reach="$(dirname "$0")/harness-corpus-reachability.sh"
+  if [ -x "$reach" ] && [ "$roles" != "$target" ]; then
+    bash "$reach" "$PROJECT_ROOT" text --fix >/dev/null 2>&1 || true
+  fi
+
   # Log to progress.log if present
   local progress_log="$PROJECT_ROOT/.harness/progress.log"
   if [ -f "$progress_log" ]; then
@@ -141,7 +151,9 @@ EOF
 
 # ─────────────────────────────────────────
 # JSON 배열에서 일괄 등록
-#   schema: [{ target, rule_id, title, wrong, right, why, scope, source }]
+#   schema: [{ target, rule_id, title, wrong, right, why, scope, source, roles }]
+#   `roles` is the comma-separated list of every role that must be able to FIND
+#   this entry — not only the one that wrote it (Hard Rule 11). Defaults to target.
 # ─────────────────────────────────────────
 register_from_json() {
   local json="$1"
@@ -153,7 +165,7 @@ register_from_json() {
 
   local i
   for ((i=0; i<count; i++)); do
-    local t r ti w ri wh sc so
+    local t r ti w ri wh sc so rl
     t=$(echo "$json"  | jq -r ".[$i].target // empty")
     r=$(echo "$json"  | jq -r ".[$i].rule_id // empty")
     ti=$(echo "$json" | jq -r ".[$i].title // empty")
@@ -162,12 +174,13 @@ register_from_json() {
     wh=$(echo "$json" | jq -r ".[$i].why // empty")
     sc=$(echo "$json" | jq -r ".[$i].scope // \"항상\"")
     so=$(echo "$json" | jq -r ".[$i].source // \"evaluator:auto\"")
+    rl=$(echo "$json" | jq -r ".[$i].roles // empty")
 
     if [ -z "$t" ] || [ -z "$r" ] || [ -z "$ti" ]; then
       echo "[gotcha-register] skip: missing target/rule_id/title at index $i" >&2
       continue
     fi
-    register_one "$t" "$r" "$ti" "$w" "$ri" "$wh" "$sc" "$so"
+    register_one "$t" "$r" "$ti" "$w" "$ri" "$wh" "$sc" "$so" "${rl:-$t}"
   done
 }
 
@@ -354,6 +367,7 @@ RIGHT=""
 WHY=""
 SCOPE="항상"
 SOURCE="evaluator:auto"
+ROLES_DECL=""
 MODE="single"
 FROM_JSON=""
 
@@ -367,6 +381,7 @@ while [ $# -gt 0 ]; do
     --why)      WHY="$2"; shift 2 ;;
     --scope)    SCOPE="$2"; shift 2 ;;
     --source)   SOURCE="$2"; shift 2 ;;
+    --roles)    ROLES_DECL="$2"; shift 2 ;;
     --from-json) MODE="json"; FROM_JSON="$2"; shift 2 ;;
     --scan-evaluations) MODE="scan"; shift ;;
     --scan-all) MODE="scan-all"; shift ;;
@@ -380,7 +395,7 @@ case "$MODE" in
       echo "[gotcha-register] usage: --target X --rule-id Y --title Z [...]" >&2
       exit 1
     fi
-    register_one "$TARGET" "$RULE_ID" "$TITLE" "$WRONG" "$RIGHT" "$WHY" "$SCOPE" "$SOURCE"
+    register_one "$TARGET" "$RULE_ID" "$TITLE" "$WRONG" "$RIGHT" "$WHY" "$SCOPE" "$SOURCE" "${ROLES_DECL:-$TARGET}"
     ;;
   json)
     if [ ! -f "$FROM_JSON" ]; then echo "[gotcha-register] file not found: $FROM_JSON" >&2; exit 1; fi

package/scripts/harness-spec-pin.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# harness-spec-pin.sh — AGENTS.md Hard Rule 4 (spec-pin clause).
+#
+# A category is complete AGAINST A SPEC VERSION, never in the abstract. Measured:
+# a spec moved v0.7 -> v0.9, changing a response contract, while the category
+# built against v0.7 sat marked complete — two later revisions had landed
+# silently, and nothing in the harness recorded which version the work was for.
+# The symptom was a lookup key that no longer matched: no error, no log, three
+# overlays dropped as null.
+#
+# Usage:
+#   harness-spec-pin.sh <project-root> <mission-rel> add <name> <path> [version]
+#   harness-spec-pin.sh <project-root> <mission-rel> verify [text|json]
+#   harness-spec-pin.sh <project-root> <mission-rel> list
+set -uo pipefail
+
+PROJECT_ROOT="${1:-.}"
+MISSION_REL="${2:-}"
+CMD="${3:-verify}"
+DOCS="$PROJECT_ROOT/.harness/documents"
+PINS="$DOCS/$MISSION_REL/spec-pins.json"
+
+command -v jq >/dev/null 2>&1 || { echo "[spec-pin] jq required" >&2; exit 2; }
+[ -n "$MISSION_REL" ] || { echo "[spec-pin] mission path required" >&2; exit 2; }
+
+hash_of() {
+  local f="$1"
+  [ -f "$f" ] || { printf 'MISSING'; return; }
+  if command -v shasum >/dev/null 2>&1; then shasum -a 256 "$f" | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then sha256sum "$f" | awk '{print $1}'
+  else printf 'NOHASHER'; fi
+}
+
+case "$CMD" in
+  add)
+    name="${4:-}"; specpath="${5:-}"; version="${6:-unversioned}"
+    [ -n "$name" ] && [ -n "$specpath" ] || { echo "[spec-pin] usage: add <name> <path> [version]" >&2; exit 2; }
+    mkdir -p "$(dirname "$PINS")"
+    [ -f "$PINS" ] || echo '{"pins":[]}' > "$PINS"
+    abs="$specpath"; case "$specpath" in /*) ;; *) abs="$PROJECT_ROOT/$specpath" ;; esac
+    h="$(hash_of "$abs")"
+    tmp="$(mktemp)"
+    jq --arg n "$name" --arg p "$specpath" --arg v "$version" --arg h "$h" \
+       '.pins = ((.pins // []) | map(select(.name != $n)) + [{name:$n, path:$p, version:$v, sha256:$h, pinned_at:(now|todate)}])' \
+       "$PINS" > "$tmp" && mv "$tmp" "$PINS"
+    echo "[spec-pin] pinned $name @ $version ($h)"
+    ;;
+  list)
+    [ -f "$PINS" ] && jq -r '.pins[] | "- \(.name) @ \(.version) — \(.path) [\(.sha256[0:12])]"' "$PINS" || echo "(no pins)"
+    ;;
+  verify)
+    mode="${4:-text}"
+    # No pins file is not a failure: not every mission builds against an external spec.
+    if [ ! -f "$PINS" ]; then
+      [ "$mode" = "json" ] && jq -nc '{ok:true, drifted:[], pinned:0}'
+      exit 0
+    fi
+    drifted=()
+    while IFS=$'\t' read -r name specpath version want; do
+      [ -n "$name" ] || continue
+      abs="$specpath"; case "$specpath" in /*) ;; *) abs="$PROJECT_ROOT/$specpath" ;; esac
+      got="$(hash_of "$abs")"
+      [ "$got" = "NOHASHER" ] && continue
+      if [ "$got" != "$want" ]; then
+        if [ "$got" = "MISSING" ]; then drifted+=("$name|$version|spec file is gone: $specpath")
+        else drifted+=("$name|$version|content changed since it was pinned: $specpath"); fi
+      fi
+    done < <(jq -r '.pins[]? | [.name, .path, .version, .sha256] | @tsv' "$PINS" 2>/dev/null)
+    total="$(jq '[.pins[]?] | length' "$PINS" 2>/dev/null || echo 0)"
+    if [ "${#drifted[@]}" -eq 0 ]; then
+      [ "$mode" = "json" ] && jq -nc --argjson n "$total" '{ok:true, drifted:[], pinned:$n}'
+      [ "$mode" = "text" ] && echo "[spec-pin] $total pin(s) still match the current documents"
+      exit 0
+    fi
+    if [ "$mode" = "json" ]; then
+      printf '%s\n' "${drifted[@]}" | jq -Rcs 'split("\n")[:-1] | map(split("|") | {name:.[0], pinned_version:.[1], detail:.[2]}) | {ok:false, drifted:.}'
+    else
+      echo "Spec pin drift (AGENTS.md Hard Rule 4):"
+      for d in "${drifted[@]}"; do
+        rest="${d#*|}"
+        echo "- ${d%%|*} (built against ${rest%%|*})"
+        echo "    ${d##*|}"
+      done
+      echo "  This mission was built against a spec that has since moved. Re-check the"
+      echo "  affected work before marking anything complete, then re-pin:"
+      echo "    scripts/harness-spec-pin.sh . $MISSION_REL add <name> <path> <new-version>"
+    fi
+    exit 1
+    ;;
+  *) echo "[spec-pin] unknown command: $CMD" >&2; exit 2 ;;
+esac

package/scripts/harness-worker-evidence-validate.sh

@@ -120,6 +120,32 @@ done <<EOF
 $mission_dirs
 EOF
 
+# Record drift (AGENTS.md Hard Rule 12): a conclusion the session holds but has
+# not written into the state file is not held by the company. Measured cost of
+# the unreconciled case: a finished step the orchestration loop went on trying
+# to spawn 70 times, because only the report knew it was done.
+PROGRESS_FILE="$PROJECT_ROOT/.harness/progress.json"
+if [ -f "$PROGRESS_FILE" ]; then
+  while IFS=$'\t' read -r wname wreport; do
+    [ -n "$wname" ] && [ -n "$wreport" ] || continue
+    report_abs="$wreport"
+    case "$wreport" in /*) ;; *) report_abs="$PROJECT_ROOT/$wreport" ;; esac
+    [ -f "$report_abs" ] || continue
+    # Section-scoped reading: the Status body may be quoted or indented.
+    if awk '
+      /^[[:space:]]*>?[[:space:]]*##[[:space:]]+Status[[:space:]]*$/ { inb=1; next }
+      inb && /^[[:space:]]*>?[[:space:]]*#/ { inb=0 }
+      inb && /COMPLETE/ { found=1 }
+      END { exit(found ? 0 : 1) }
+    ' "$report_abs" 2>/dev/null; then
+      violations+=("state-file:worker-$wname-reported-COMPLETE-but-progress.json-still-running")
+    fi
+  done < <(jq -r '
+    [.company_state.workers[]? | select((.status // "") | test("running|busy"))
+     | [(.name // .worker // .feature // "unknown"), (.report // .report_path // .path // "")]]
+    | .[] | @tsv' "$PROGRESS_FILE" 2>/dev/null)
+fi
+
 if [ "${#violations[@]}" -eq 0 ]; then
   if [ "$mode" = "json" ]; then
     jq -nc '{ok:true, violations:[]}'