@tech-leads-club/harness-toolkit 0.2.1

package/docs/decisions/ad-066.md

@@ -0,0 +1,111 @@
+---
+type: Decision
+title: "AD-066 — Uninstall reads the artefact, and the plan is the confirmation"
+description: "The harness merges eleven hook groups into a settings.json that also holds the operator's permissions, sandbox and env, and offered no way out. The established answer is a receipt written at install time; that record would desync on the first npm upgrade or hand-edit, and every artefact this installer creates already names itself."
+tags: [decision, install, safety, operator]
+timestamp: "2026-08-12"
+---
+
+# AD-066 — Uninstall reads the artefact, and the plan is the confirmation
+
+- **status**: active
+- **date**: 2026-08-12
+
+## Decision
+
+1. **Ownership is read from the artefact, never from a record.** No manifest is written at install time and none
+   is required at uninstall time.
+2. **A shared file is un-merged, never deleted.** `settings.json` keeps every key and every foreign hook group;
+   an event left with no groups loses its key rather than keeping an empty array.
+3. **A symlinked runtime home is unlinked and never followed.**
+4. **The split install already draws is the split uninstall honours.** `RUNTIME_PAYLOAD` goes, `OPERATOR_OWNED`
+   stays, and `--purge` is a separate word that `--yes` never implies.
+5. **The plan is the confirmation and there is no prompt.** Without `--yes` the command prints the full plan and
+   changes nothing.
+6. **The npm global package and per-project `.tlc/` are reported, not removed.**
+
+## Why
+
+**The exit was hand-editing a file most operators should not hand-edit.** `~/.claude/settings.json` carries
+`permissions`, `sandbox`, `env` and `statusLine` next to our hook groups. Reverting the install meant finding
+eleven groups in that file by eye. An install with no exit is one people try on one machine and never a second.
+
+**The established pattern is a receipt, and it is the wrong one here.** CMake's `install_manifest.txt` is the
+minimal form; package managers write the same record into a local store, and the schema people converge on
+carries the path, a content hash, a `pre_existed` flag and the artefact type. The sharpest statement of the case
+comes from a project that **rejected** an uninstall command outright: never infer ownership, because a bulk
+command guessing which files are safe to remove will eventually guess wrong, and `--yes` turns that guess into a
+recursive delete.
+
+That objection is right about inference and does not describe this installer. Every artefact here names itself —
+a hook group whose command *is* the launcher path, a symlink resolving inside the runtime home, a `hooks.json`
+carrying the marker `isCursorWired` already checks. Matching an exact launcher path is not a heuristic. And a
+receipt would be **strictly worse**, because the install routes are npm, git clone and a symlink to a working
+checkout: three ways for a written record to desync from the disk on the first `npm i -g`, `git reset --hard` or
+hand-edit. `isHarnessGroup` cannot desync — it reads what is there.
+
+So the receipt's findings are adopted and its mechanism is not. `pre_existed` becomes "this group does not carry
+the marker". "Skip a modified file" becomes "never follow a link into a checkout". "Remove a directory only when
+empty" becomes the `OPERATOR_OWNED` split, which
+[/decisions/ad-056.md](/decisions/ad-056.md) had already drawn for the installer.
+
+**The symlinked home is the reason this is careful rather than a one-liner.** `~/.tlc/harness` is a link to the
+contributor's working clone on every development machine, including the one this was written on. `rm -rf`
+follows it and deletes the repository. `install.sh` refuses to touch a symlinked runtime for exactly this reason
+([/decisions/ad-046.md](/decisions/ad-046.md)), and the uninstall inherits the refusal: `unlinkSync`, never
+`rmSync` recursive.
+
+**No prompt, because the operator reaching for this may have no terminal.** A confirmation prompt needs a TTY and
+assumes an interactive session; the person undoing an install is as likely to be in CI, or in a shell the harness
+itself has made unpleasant. Printing the plan and requiring `--yes` gives the same protection, works headless,
+and leaves the plan in the log of whatever ran it.
+
+**The npm package is reported rather than removed** because a global prefix owned by root needs `sudo`, and an
+`npm uninstall` failing halfway through a teardown leaves a worse state than one that never started. Per-project
+`.tlc/` is reported for a different reason: finding them means walking the operator's disk, which is a larger
+risk than the residue.
+
+## Trade-offs
+
+**Running it found a defect the tests would not have.** On the machine it was written on,
+`~/.claude/skills/harness-init` pointed at a `/tmp` install deleted weeks earlier. Under a target-based ownership
+rule that dangling link reads as "not ours" and survives every uninstall forever. So the two link families now
+answer to different rules: `tlc` on PATH is a name anybody may own and keeps the target test; `skills/harness-init`
+is a path only this installer writes, so its **location** is the identification. Two rules is worse than one, and
+leaving residue that carries our name is worse than two rules.
+
+**A file that does not parse is left alone and reported.** The un-merge cannot preserve what it cannot read, and
+the alternative — rewriting from a template — is precisely the data loss this exists to avoid. The operator gets
+the path and the parse error.
+
+**Two CI failures paid for the cross-platform rules, and both were the same mistake.** macOS: `realpathSync`
+throws on a path whose tail is absent, so a dangling link fell back to its literal text and was compared against
+a home that had been resolved — and the OS temp directory there sits under `/var`, a symlink to `/private/var`.
+Windows: ownership was decided with `target.startsWith(`${root}/`)`, and that platform separates with `\`. In
+both cases the harness's own artefact read as somebody else's and survived. One rule now: resolve both sides the
+same way, and compare with `relative` rather than a string prefix. The path API is a parameter, so the win32
+rules are asserted from any machine.
+
+**And `install.ps1` does not write what `install.sh` writes.** It resolves the home from `USERPROFILE`, copies
+`tlc.cmd` instead of linking it, and places one skill junction at `~/.tlc/skills/harness-init` rather than one
+per provider directory. Reading the POSIX layout on Windows finds none of it and reports a clean machine, which
+is the worst answer an uninstaller can give. A regular file is now identified by the launcher marker its one
+command line carries, the same way every other artefact identifies itself.
+
+**An artefact the operator renamed is invisible.** Ownership read from the artefact means an artefact that no
+longer identifies itself is not ours to remove. This is the honest cost of decision 1, and it is quieter than a
+receipt's failure mode, which is deleting something that has since become somebody else's.
+
+**A partly-applied run leaves a mixed state, and that is why every step is idempotent.** A second run resumes
+from wherever the first stopped and reports nothing to do once there is nothing left — including a link left
+dangling by a payload removal that ran before it.
+
+## Not decided here
+
+- **Removing the harness from repositories.** `.tlc/` exists in every project it ran in. Searching for them is
+  the risk; the plan names the one-line removal instead.
+- **Whether the Windows launcher copy is a bug.** `install.ps1` copies `bin\tlc.cmd` into the bin directory, and
+  that file resolves the launcher as `%~dp0tlc-exec.mjs` — relative to itself, where no launcher sits. The
+  uninstall removes the copy correctly; whether the install should have linked it is a separate question.
+- **A `tlc harness reinstall`.** The one-liner already does it, and a verb that means "uninstall then install"
+  would need to decide what happens when the first half fails.

package/docs/decisions/ad-067.md

@@ -0,0 +1,64 @@
+---
+type: Decision
+title: "AD-067 — A reserved file that cannot be retired is rendered, and the gate holds it there"
+description: "docs/log.md is a reserved file of the OKF v0.1 bundle, so it cannot be deleted as a duplicate. Hand-maintained, it had drifted to 19 of 66 decision records. It is now rendered from the same files the changelog reads, with a gate step that fails on drift."
+tags: [decision, docs, gates]
+timestamp: "2026-08-12"
+---
+
+# AD-067 — A reserved file that cannot be retired is rendered, and the gate holds it there
+
+- **status**: active
+- **date**: 2026-08-12
+
+## Decision
+
+1. **`docs/log.md` is generated**, from the same `docs/decisions/` files the changelog reads.
+2. **A fourteenth gate step**, `render-log.ts --check`, fails on drift.
+3. **A record with no `timestamp` is dropped, never filed under a guessed date.**
+4. **Days newest first, records within a day in id order** — because AD-064 was taken before AD-065, and
+   reading them the other way round inverts the reasoning.
+
+## Why
+
+**It had drifted to 19 of 66 and nobody noticed.** The log stopped at AD-017 with AD-051 and AD-052 grafted on
+afterwards. Forty-seven records were missing, so a document describing itself as "the chronological record"
+was 71% incomplete — worse than absent, because it reads as complete.
+
+**Retiring it was the first answer and it was wrong.** The log duplicates `CHANGELOG.md`, which is already
+rendered from the same records precisely so nobody maintains it by hand
+([/decisions/ad-055.md](/decisions/ad-055.md)) — so deletion looked obvious. Reading
+`tools/check-docs-bundle.ts` before acting found `RESERVED_FILES = new Set(["index.md", "log.md"])`:
+`log.md` is a reserved file of the OKF v0.1 format this bundle adopted
+([/decisions/ad-013.md](/decisions/ad-013.md)), with its own validation rule requiring ISO 8601 headings.
+Deleting it would have left the bundle claiming a format it no longer follows.
+
+**So the duplication is the constraint, not the defect.** The format requires two views of the same records:
+`log.md` by date, `decisions/index.md` by number, and `CHANGELOG.md` by release. Three hand-maintained views
+is three things to forget. Three rendered views is one source and no memory.
+
+**The gate step is what makes it true tomorrow.** `render-capabilities --check` and `render-changelog --check`
+already exist for exactly this, and both have caught staleness in this repository. A generated file with no
+check is a hand-maintained file with extra steps.
+
+## Trade-offs
+
+**The log lost its prose.** The old entries carried narrative — what was measured, what was rejected — that a
+title cannot. That narrative is in the decision record itself, which the entry links to, and the alternative
+was 47 entries of narrative invented by whoever noticed the gap.
+
+**`DecisionSummary` grew a field.** `timestamp` is now read alongside `title` and `migration`. It is optional,
+so the changelog and the update digest are unaffected, and the reader was already parsing the frontmatter this
+field lives in.
+
+**Fourteen gate steps is a lot of steps.** Each one exists because something drifted while nobody was looking,
+and the whole set runs in under thirty seconds. The number is a symptom of the checks being cheap, not of the
+gate being heavy.
+
+## Not decided here
+
+- **Whether `CHANGELOG.md` should move into the bundle.** It sits at the repository root because npm and GitHub
+  both look for it there, and a bundle-relative link cannot reach it. The log now names it in prose.
+- **Rendering `decisions/index.md` as well.** It is the third view of the same records and the only one still
+  hand-maintained. It was complete at 66 of 66 when this was written, so there is no evidence of drift to act
+  on yet.

package/docs/decisions/ad-068.md

@@ -0,0 +1,79 @@
+---
+type: Decision
+title: "AD-068 — A directory decides what ships, and dist is derived from disk in both directions"
+description: "A hand-maintained array named four development-only checks while ten qualified, so six that validate only this repository were bundled and copied into every install. The exclusion is now a directory, the payload copy honours it, and a bundle whose source is gone is pruned rather than shipped forever."
+tags: [decision, packaging, boundaries, build]
+timestamp: "2026-08-13"
+---
+
+# AD-068 — A directory decides what ships, and dist is derived from disk in both directions
+
+- **status**: active
+- **date**: 2026-08-13
+
+## Decision
+
+1. **`tools/dev/` is the declaration.** Every check that validates this repository's own architecture, docs or
+   conventions lives there, and the build reads one directory level, so nothing under it can become a bundle.
+2. **The payload copy honours the same boundary.** `installRuntime` filters `tools/dev` and `tools/__test__`, and
+   the published `files` list excludes them.
+3. **The clone route is deliberately different.** A checkout is the repository; a contributor needs these.
+4. **A bundle whose source no longer exists is pruned by the build.**
+
+## Why
+
+**The array named four and ten qualified.** `bin/tlc-build` carried
+`DEV_ONLY=(check-boundaries check-docs-bundle check-dist-fresh render-capabilities)`. Measured against the
+repository as it stood: `check-wiring`, `check-screens`, `check-obs-contract`, `check-suppressions`,
+`render-changelog`, `render-log` and `eval-skill-triggers` were all bundled into `dist/` and copied into every
+install. Each validates something a user's project does not have — our module boundaries, our screen contract,
+our observability kinds, our decision records.
+
+**And the file says why that shape fails, two lines above it:**
+
+> Derived from disk, never hardcoded: a fixed list silently stops building a new entrypoint, and the missing
+> bundle only surfaces when a hook fires in production.
+
+The principle was stated and then not applied to the exclusion. This is the same shape as every defect
+[/decisions/ad-065.md](/decisions/ad-065.md) collected — a consumer that does not grow when the producer does —
+with the list playing the consumer.
+
+**Source ships too, and that was the larger half.** Excluding a bundle is not enough: `RUNTIME_PAYLOAD` copies
+`tools` wholesale and the npm `files` list published it, so the TypeScript source arrived intact. With Bun
+present the launcher resolves an entry straight from source, so `tlc-exec render-log` on a user's machine would
+have rewritten files inside their runtime home.
+
+**A directory cannot be forgotten.** A new checker either sits in `tools/dev/` and never ships, or sits in
+`tools/` and does. There is no third state and nothing to remember, which is what separates this from the array
+it replaces.
+
+**dist only ever grew.** The build derived what to *compile* from disk and never what to *remove*, so a bundle
+whose source moved stayed on disk, stayed committed, and stayed shipped — invisible to `check-dist-fresh`,
+because an unchanged file produces no diff. Pruning made the move visible: seven bundles left, 31 to 24.
+
+## Trade-offs
+
+**Two directories now mean two things by their names.** `tools/` is the product, `tools/dev/` is the repository,
+and the difference is only obvious once you know. The alternative was a marker inside each file, which is a
+convention a reader can violate silently; a path is checked by the build every time.
+
+**The tests stay flat in `tools/__test__/`.** They now reach across into `../dev/`, which is slightly worse to
+read than co-location. The gate's glob is flat by design, and a second glob is a second thing to keep in step —
+the exact failure being fixed.
+
+**Pruning deletes files the operator did not ask to delete.** It is bounded to `dist/*.mjs`, which the build owns
+entirely and rewrites on every run, and it names each file as it goes.
+
+**A contributor's clone still has everything, so the boundary is untested there.** The sensor covers the two
+product routes — the payload copy and the published file list — because those are the ones a user receives.
+
+## Not decided here
+
+- **Whether `eval-skill-triggers` should exist.** Nothing invokes it: not the gate, not CI, not a document. It
+  has a test, so it is exercised but not used. It moved to `tools/dev/` as the conservative placement; whether it
+  earns its place is a separate question.
+- **Whether `docs/` should be filtered too.** The runtime payload copies our decision records so
+  `tlc harness update` can tell an operator what changed in the harness. That is the product's own release notes,
+  not a convention imposed on anyone, and it stays.
+- **A check that fails when a shipped tool imports from `tools/dev`.** `tsc` catches the broken path today
+  because the directories differ; a rename could reintroduce the coupling without a type error.

package/docs/decisions/ad-069.md

@@ -0,0 +1,74 @@
+---
+type: Decision
+title: "AD-069 — A decision record declares its shape, and cites by link so a move cannot break it"
+description: "Sixty-seven records, all claiming to be current, with the body shape held only by habit and the citation form 96% consistent. The shape is now checked, the older twenty are a ratchet that may only fall, and a bare parenthesised id fails wherever a link is the convention."
+tags: [decision, docs, gates]
+timestamp: "2026-08-13"
+---
+
+# AD-069 — A decision record declares its shape, and cites by link so a move cannot break it
+
+- **status**: active
+
+## Decision
+
+1. **Four headings are required**: `## Decision`, a heading beginning `## Why`, `## Trade-offs`, and
+   `## Not decided here`. Bespoke sections between them stay free-form.
+2. **The older twenty are a ratchet**, not an exemption. The count off the current shape starts at 20 and the
+   gate fails if it rises **or** if it falls without the recorded budget following.
+3. **A record is cited by link**, in documentation, in comments, and in test names.
+4. **`status` is a closed set**, and it must agree with the folder the record sits in.
+5. **The rule has no exemption list.** Its own examples are written so they do not match.
+
+## Why
+
+**The shape was a boundary, not a habit, and nothing knew it.** Measured: AD-021 through AD-067 carry all four
+headings without exception; AD-001 through AD-020 use `## Applies to` and `## Consequences` instead. The format
+changed once and held for forty-seven records. Held by nothing, though — the next record written under time
+pressure would have dropped `## Trade-offs` and started a second boundary nobody noticed.
+
+**`## Trade-offs` and `## Not decided here` are the two that get dropped, and the two that pay.** A record
+without them reads as a decision with no cost and no open edges, which is the reading that makes somebody
+re-litigate it six weeks later. This session alone, `## Not decided here` is where the Windows launcher question,
+the per-record token accounting and the unused `eval-skill-triggers` went — each one a thing a reader would
+otherwise assume was settled.
+
+**A bare id is a citation only a reader who already knows can check.** The repository stood at 355 bundle-relative
+links against 15 bare `(AD-NNN)` forms. A link survives a file move, `check-docs-bundle` resolves it, and a
+reader can follow it; the bare form does none of that. Fifteen was small enough to fix in one pass and large
+enough to keep growing — and the pass found twenty more inside the records themselves, which the first
+measurement had missed by only looking at `docs/*.md`.
+
+**The ratchet fails downward too.** A budget that only refuses to rise is one nobody ever turns: migrating a
+record improves the number and nothing records that it happened. Failing when the count *falls* makes the
+migration a two-line change — the record and the budget — and keeps the number honest.
+
+**Backfilling the twenty would have meant inventing them.** Their trade-offs were either never written or are
+now unknowable. A checker that allow-listed them by number would go stale the first time one was migrated, and
+would hide the twenty-first. The count is the honest form.
+
+## Trade-offs
+
+**A ratchet at twenty is a number in a file that has to be maintained.** It is one integer, the gate names the
+new value when it is wrong, and the alternative — twenty invented rationales — is worse in a way that cannot be
+detected later.
+
+**The Why rule matches by prefix, so `## Whyever` would pass.** Requiring the bare word would have forced
+`## Why the runtime home had to change` down to `## Why`, which is worse prose in a record whose whole value is
+prose. The looser rule buys better writing at the cost of a hole nobody has a reason to walk through.
+
+**None of this reaches anyone using the harness.** It is a convention of this repository, checked by a tool in
+`tools/dev/` that is never packaged ([/decisions/ad-068.md](/decisions/ad-068.md)). It makes the corpus cheaper
+to read for whoever maintains the product, which reaches a user slowly and indirectly, or not at all.
+
+**Two of the four `(AD-NNN)` forms this converted were inside test names**, where the linked form is long and
+reads badly in a test report. The consistency was judged worth more than the line length, and the rule covers
+tests precisely because that is where a convention erodes first.
+
+## Not decided here
+
+- **Whether the older twenty should be migrated at all.** The ratchet permits it and nothing requires it.
+  Whoever has the context for one may lower the number; nobody should do all twenty in one pass.
+- **Whether `## Not decided here` should be required to be non-empty.** A heading with nothing under it
+  satisfies the checker today. Judging the content is a semantic question a gate cannot answer.
+- **Applying the citation rule to `.specs/`.** That tree is gitignored and outside the documentation bundle.

package/docs/decisions/ad-070.md

@@ -0,0 +1,86 @@
+---
+type: Decision
+title: "AD-070 — A comment has to read for somebody who was not in the session"
+description: "The comment gate asked whether a comment declares a reason. It could not ask whether the reason means anything to a reader at HEAD, which is the comment a model actually writes — change narration, a decision number only the session saw, an argument aimed at a reviewer. A third mode asks that question, and the rule set was cut on measured false positives before it shipped."
+tags: [decision, comment-policy, rails]
+timestamp: "2026-08-13"
+---
+
+# AD-070 — A comment has to read for somebody who was not in the session
+
+- **status**: active
+
+## Decision
+
+1. **A third mode, `resolvable`**, off by default and never implied: `declared` plus one further question — can
+   a reader at HEAD, with no transcript of the session, resolve every reference and check every claim?
+2. **Five classes** are refused: change narration, dead citations, review vantage, reviewer-addressed
+   justification, and control-flow narration.
+3. **Prose, never syntax.** Nothing here parses a language.
+4. **One comment, one finding.** A block that trips three rules reports once, and a comment already refused for
+   having no declared reason is not refused twice.
+5. **The refusal asks for a restatement, not a deletion.**
+
+## Why
+
+**The rail could not see the comment a model actually writes.** `declared` accepts anything carrying `why:`,
+`hazard:` or `invariant:`, and `strict` accepts nothing. Neither can tell these apart:
+
+```
+// why: this used to read HEAD, which a committing turn moves past
+// why: without the guard, a bare `*` reads as a block continuation
+```
+
+Both declare a reason. The first is only checkable by somebody who saw the previous version; the second is
+checkable by anybody, forever. The whole difference is vantage, and no marker carries it.
+
+**The distinguishing question is a single one**, which is what makes it implementable: *could a reader at HEAD
+resolve every reference and check every claim?* A counterfactual passes because the reader can construct it. A
+past-tense claim about the code fails because the repository no longer holds the evidence.
+
+**The restatement is the fix, not deletion.** Almost every unresolvable comment carries a true, durable fact
+wrapped in the session's vantage. `this used to emit one finding per line, so one failing test arrived as three`
+becomes `one finding per matched line makes a single failing test arrive as three` — same fact, no transcript
+required. Telling the model to delete would throw away the reason along with the framing, so the message names
+the restatement and only then permits deletion.
+
+**Prose keeps it language-agnostic.** The syntax catalog exists because a delimiter per language is fragile and
+does not scale ([/decisions/ad-058.md](/decisions/ad-058.md)). Resolvability is a property of the sentence, not
+of the language, so a new language costs nothing.
+
+## Trade-offs
+
+**One phrase was measured out of the rule set before it shipped.** `no longer` was in the first draft. Run
+against this repository's 1,077 comment blocks it matched four times, and every one described *runtime* state —
+a lock owner that no longer exists, a lesson ref that no longer resolves, a path a future refactor would leave
+behind. Zero described the repository's own history. Four wrong and none right is a phrase that teaches an
+operator to switch the rail off ([/decisions/ad-034.md](/decisions/ad-034.md)), so it went.
+
+**This repository would not pass its own new mode.** After that cut, 61 of 1,077 blocks still match — 5.7%, 55
+of them `used to`. Sampling them, they are true positives: each carries a durable fact wrapped in history, and
+each could be restated. The mode is off here, and saying so is more honest than weakening a correct rule until
+the author's own code passes.
+
+**Precision was chosen over recall everywhere.** Hedges, version stamps and untranslated fragments are all
+recognisable leakage and none is matched, because none can be matched without also catching prose that is fine.
+The rail catches less than a careful reader would.
+
+**A regex is a blunt instrument for a semantic property.** `this is safe` is refused even when the sentence goes
+on to state a real invariant. The refusal names the phrase, so the fix is one edit, and the alternative — a model
+call per comment — is not something a stop hook has the latency budget for
+([/decisions/ad-012.md](/decisions/ad-012.md)).
+
+**A fourth mode is a fourth thing to explain.** The catalog's `asks` now offers three words rather than two, and
+the operator prose the model reads is longer in this mode than in the others. The modes are ordered by strictness
+and each is a superset of the last, which is the only arrangement that keeps three explainable.
+
+## Not decided here
+
+- **Whether `resolvable` should become the default.** It would change behaviour for every project that enabled
+  `comments`, and a capability changes nothing by default when it arrives.
+- **Applying the same test to commit messages, plans or handoff prose.** The same leakage appears there and the
+  detector is not coupled to comments, but each surface needs its own calibration run before it can block.
+- **Whether this repository should adopt the mode on itself.** It would mean restating 61 passages, and doing
+  that well needs the context of whoever wrote each one.
+- **Hedges and planning residue.** `probably fine for now` is real leakage. Every pattern for it also matched
+  honest uncertainty, so it stays out until one exists that does not.

package/docs/decisions/ad-071.md

@@ -0,0 +1,93 @@
+---
+type: Decision
+title: "AD-071 — The turn's added lines are checked against the code the project already has"
+description: "Nothing watched for the agent writing something the codebase already contained. A line-run comparison over the turn's diff answers it without parsing a language, and three exclusions — comments, dependency declarations, pure data — were each added because a calibration run said so. It found a real duplication in this repository on its first honest pass."
+tags: [decision, duplication, rails]
+timestamp: "2026-08-13"
+---
+
+# AD-071 — The turn's added lines are checked against the code the project already has
+
+- **status**: active
+
+## Decision
+
+1. **A rail, off by default**, that blocks the stop when this turn added a run of `minRun` lines or more that
+   already exists elsewhere in the project, naming both sites.
+2. **Diff-scoped** against the sha the turn started from, like the comment gate. A run already duplicated before
+   the turn is not this turn's to answer for.
+3. **Lines, never syntax.** Nothing parses a language.
+4. **Three exclusions**, each added because a calibration run demanded it: comments, dependency declarations, and
+   runs that are not operational enough to be logic.
+5. **Bounded and honest about it**: 2,000 files and 8 MB, and the scan reports when a bound was reached.
+
+## Why
+
+**Nothing was watching for the copy.** The harness had rails for narration, for evidence, for shell safety and
+for the plan — and none for the failure an operator meets weeks later as two implementations of the same thing
+drifting apart. The second copy is where the drift starts, and the second copy is exactly what a diff-scoped rail
+can see.
+
+**Three calibration runs shaped the rule, and each one changed it.**
+
+| Run | Reported | What the top of the list was | What changed |
+| --- | --- | --- | --- |
+| first | 0 at every window | — | the index kept one site per run, so a run compared equal to itself |
+| second | 137 at six lines | every import block in the repository | dependency declarations excluded |
+| third | 116 | re-export lists, config literals, type bodies, fixtures | a run must be operational in the majority of its lines |
+| fourth | 13 | two entrypoints building the same policy input | shipped |
+
+The first run is the one worth naming: **zero findings looked like a clean repository and was a defect.** One
+site per run meant the project index pointed at the very lines the turn had added, so every duplication compared
+equal to itself and vanished. A rail that reports nothing is indistinguishable from a rail that has nothing to
+report, which is why the calibration was run at four window lengths rather than one — four zeroes in a row is
+not a property of a codebase.
+
+**It found a real one immediately.** `subagent-start.ts` and `tool-before.ts` each assembled the same twelve-field
+input for `evaluateSubagentSpawn`, identical apart from indentation. A new field in `policy.subagents` had to be
+remembered in both — the shape [/decisions/ad-065.md](/decisions/ad-065.md) collected seven times, a consumer
+that stops growing with its producer. It is now one function.
+
+**Data is not logic, and repeated shape is what data is for.** A type's fields, a config literal and a re-export
+list all repeat by design. Requiring a call, an assignment, a branch or a return in the majority of a run's lines
+is what separates "these two do the same thing" from "these two describe the same thing", without asking what
+language it is.
+
+**Renaming makes it a different run, deliberately.** Normalisation collapses whitespace and a trailing comma —
+the two things a paste changes without changing the code — and nothing else. Matching through renames would
+report every similarly shaped function, which is the noise that ends a rail's life.
+
+## Trade-offs
+
+**It reads the repository on every stop.** `git ls-files` plus a read of each file is the honest way to answer
+"does this exist anywhere", and hook latency is a product property ([/decisions/ad-012.md](/decisions/ad-012.md)).
+The bounds are what keep a large repository from paying for it, and the scan says when it stopped early, because
+a partial scan reporting nothing reads exactly like a clean one.
+
+**Six lines is a judgement, not a discovery.** At four the matches were punctuation and import blocks; at ten
+almost nothing survived. Six is where a match started being worth reading in *this* repository, and it is a
+config field precisely because another project's answer will differ.
+
+**Duplicated logic in tests is reported like any other.** Eleven of the thirteen remaining findings here are test
+setup, and reasonable people call that acceptable. The rail does not know the difference, and inventing a
+test-directory exemption would carve out the place duplication accumulates fastest.
+
+**A copy that was renamed is invisible.** The rail catches the paste, not the paraphrase. Catching the paraphrase
+needs a parser per language, which is the cost this design exists to avoid
+([/decisions/ad-058.md](/decisions/ad-058.md)).
+
+**Two exclusions are vocabulary, not grammar.** `import`, `require`, `use`, `#include` and their siblings open a
+dependency declaration in most languages but not in all, and a language that spells it differently will have its
+import blocks reported. The failure is loud and the fix is one word in a list.
+
+## Not decided here
+
+- **Whether to run the rail in observation mode first.** The harness supports recording a rail's findings without
+  blocking, and this one has a first-run false-positive history that argues for it. It ships off, so an operator
+  who wants the reading before the block can already have it.
+- **Sharing the scan with the comment gate.** Both read the turn's added lines and both walk the project; today
+  each does its own. Merging them is a latency win and a coupling, and neither has been measured.
+- **A cache keyed on the tree hash.** The index is rebuilt every stop. `git ls-files` plus a bounded read was
+  fast enough here to not need one, and a stale cache would report a duplication against code that has moved.
+- **Whether the eleven test findings in this repository should be fixed.** They are real; whether shared setup is
+  worth the coupling is a judgement per test file.

package/docs/decisions/ad-072.md

@@ -0,0 +1,82 @@
+---
+type: Decision
+title: "AD-072 — A record can leave the corpus, and removing is a change worth recording"
+description: "Seventy-one records, every one active and every one about adding something. A record now has a folder it can leave by, value rather than volume decides what leaves, and the doctrine that makes a removal arguable — a test is not the specification, and a decision record is not authority for current behaviour — is written down."
+tags: [decision, docs, process]
+timestamp: "2026-08-13"
+---
+
+# AD-072 — A record can leave the corpus, and removing is a change worth recording
+
+- **status**: active
+
+## Decision
+
+1. **`docs/decisions/archived/` exists**, and `- **status**: archived` goes with it. The checker requires the
+   folder and the status to agree.
+2. **An archived record keeps its row** in `CHANGELOG.md` and `docs/log.md`. Only the decisions index separates
+   active from archived.
+3. **Value decides, never volume.** A record stays active while its alternatives, its ownership boundary, its
+   negative guarantee, its security rule, or its condition for reintroduction would still change what somebody
+   does. There is no target count and no quota.
+4. **Two doctrines are written down**: a test that pins behaviour nothing load-bearing depends on is evidence
+   *for* removal; and a decision record is not authority for current behaviour either.
+
+## Why
+
+**Seventy-one records, seventy-one active, and not one about removing.** The corpus is append-only in both
+senses: nothing leaves, and nothing that arrives is a subtraction. That is not because nothing was removed —
+`format.enabled` went ([/decisions/ad-033.md](/decisions/ad-033.md)), `progressiveHandoff` went — but because a
+removal had no obvious place to be recorded, so it was a footnote inside whatever addition replaced it.
+
+**An index that only grows stops being read.** Every record claims to be current, so a reader cannot tell a rule
+that still binds from one whose subject no longer exists. The cost is paid on every read and never recovered.
+[/decisions/ad-067.md](/decisions/ad-067.md) noted the same shape from the other side: fourteen gate steps, each
+added because something drifted, none ever removed. It is fifteen now.
+
+**Volume is the wrong criterion, and it is the tempting one.** A rule of "archive anything over N months" or
+"keep the corpus under N records" produces motion without judgement, and the records it removes are the ones
+nobody defended rather than the ones nobody needs. The listed properties are the ones that actually guide a later
+change; a record with none of them has done its work.
+
+**An archived record still shipped.** The changelog answers "what landed in this release" and the log answers
+"what was decided when" — neither question changes when a decision stops guiding future work. Only the index
+answers "what binds now", so only the index distinguishes.
+
+**Two doctrines, because both were assumed and both are wrong.** A test pinning behaviour is routinely read as
+proof the behaviour is required; it is proof somebody once wrote it down. And this repository has treated its own
+decision records as authority — [/decisions/ad-065.md](/decisions/ad-065.md) assumed the record described the
+code. When code and record disagree, finding out which is wrong is the work, and neither one wins by default.
+
+## Trade-offs
+
+**Nothing has been archived yet.** The mechanism exists, the rule is written and a test proves an archived record
+keeps its rows and links correctly, but no real record has moved. Judging seventy-one against the rule is work
+that needs the context of whoever wrote each one, and doing it in one pass to prove the folder works would be the
+quota this decision refuses.
+
+**The status and the folder are two facts that must agree**, and the checker enforces it rather than deriving one
+from the other. Deriving would have been fewer moving parts; a record whose frontmatter says `active` while it
+sits in `archived/` is a real mistake somebody will make, and a silent derivation would hide it.
+
+**`DecisionSummary` grew a `path` field.** The readers previously rebuilt a record's link from its id, which
+stops working the moment a record lives in a subdirectory. Every caller now carries the real path, and four test
+fixtures had to be updated to match.
+
+**A removal doctrine in `CONTRIBUTING.md` is prose, not a gate.** Nothing checks that a candidate was judged
+against it. The mechanical half already exists — `check-wiring` and `check-obs-contract` report what nothing
+reads — and those stay reports rather than failures precisely because the judgement is a person's.
+
+**None of this reaches anyone using the harness.** It is this repository's own convention, checked from
+`tools/dev/` and never packaged ([/decisions/ad-068.md](/decisions/ad-068.md)).
+
+## Not decided here
+
+- **Which records should be archived.** Deliberately. The rule is written; applying it is a pass somebody makes
+  with the context.
+- **Whether an archived record should be frozen against edits.** Git already holds the history, and a hash
+  manifest is machinery for a corpus far larger than seventy-one.
+- **Deleting a record.** Archiving is a `git mv` away from reversible; deletion is not, and nothing needs it.
+- **A `class` on each record** — feature, fix, simplification. It would make "how much of this corpus is
+  subtraction" answerable mechanically. It is also seventy-one records to classify, and the question can wait
+  until there is more than zero to count.