@tech-leads-club/harness-toolkit 0.2.1 → 0.2.4

package/docs/decisions/ad-065.md

@@ -1,81 +0,0 @@
----
-type: Decision
-title: "AD-065 — The obs bus has a contract, and the gate checks both sides of it"
-description: "Seven defects in one week shared one shape: a consumer reading where the producer does not write. Each became a decision record and the pattern never became an object, so it was rediscovered by hand seven times. A kind consumed and never emitted now fails the gate, and so does a consumer reading a plane its kinds never land on."
-tags: [decision, observability, contracts, gates]
-timestamp: "2026-08-12"
----
-
-# AD-065 — The obs bus has a contract, and the gate checks both sides of it
-
-- **status**: active
-- **date**: 2026-08-12
-
-## Decision
-
-1. **A kind a consumer counts and no producer emits fails the gate.**
-2. **A consumer declares its kinds and its planes**, and a kind landing on a plane the consumer does not read
-   fails. The plane comes from `resolveObsLevel` — the real function — so a change to the plane rules cannot
-   leave the check stale.
-3. **A kind emitted and read by nothing is reported, not failed.** It costs a write per event and may be a rail
-   half-built; that is the operator's judgement.
-4. **No registry file.** Emit sites are read from the source and consumers declare their own sets, so there is
-   nothing to keep in step.
-
-## Why
-
-**One pattern, seven instances, never materialised.** A consumer reading where the producer does not write:
-`gate.outcome` and `policy.deny` consumed by the report and emitted by nothing
-([/decisions/ad-027.md](/decisions/ad-027.md)); `format.enabled` in the catalog and read by no entrypoint
-([/decisions/ad-033.md](/decisions/ad-033.md)); `progressiveHandoff` written and never read; the idle-turn
-counter reading the signal plane while its kinds land on debug ([/decisions/ad-059.md](/decisions/ad-059.md));
-`latestSessionId` ordering UUIDs by name; the comment gate diffing against `HEAD` after the turn had committed
-([/decisions/ad-058.md](/decisions/ad-058.md)); the rollup summing a snapshot
-([/decisions/ad-064.md](/decisions/ad-064.md)).
-
-Every one was recorded. None of it stopped the next. Recording a fact is not the same as materialising the
-pattern, and this repository already has two proofs that materialising works —
-[/decisions/ad-041.md](/decisions/ad-041.md) made a union member read and never written a build failure, and
-`check-screens.ts` did the same for a screen outside the standard.
-
-**The practice transfers; the implementation does not exist.** Event-driven work treats a contract as a build
-gate rather than as documentation — validate the producer's record, verify the consumer against it, fail the
-pipeline on a mismatch. Orphan detection is the mirror: enumerate what is declared, check for references, attach
-a cost to what nothing uses. Searching found no tooling that does either statically for an in-process bus, so
-the pattern is borrowed and the code is ours.
-
-**`ObsKind` was a schema, not a contract.** A closed union says which kinds exist. It does not say who emits
-one, who reads it, or **which plane it lands on** — and the plane is exactly what the idle-turn rail got wrong.
-`resolveObsLevel` decides it deterministically from the kind, which is what makes the check possible without a
-runtime.
-
-## Trade-offs
-
-**It catches three of the seven.** The dead-kind class and the plane mismatch. It does nothing for the two
-diff-base defects or the two aggregation defects, and saying otherwise would be the false coverage this exists
-to remove. Those need a relation this cannot enumerate mechanically yet.
-
-**The consumer list is hand-maintained.** One entry today. A consumer that never registers is invisible to the
-check — the same shape as the defect it guards against, one level up. It is small enough to see in review and
-large enough to be worth saying out loud.
-
-**Emit sites are found by matching `kind:` literals.** A kind assembled at runtime would read as unemitted and
-fail a consumer that reads it. Nothing does that today, and the failure is loud rather than silent.
-
-**The orphan list found a defect on its first honest run.** Registering the session rollup and `why` took it
-from thirteen to five, and two of the five were real: `policy.observe` and `cost.session_alert` were emitted and
-read by nothing. Observation mode exists to produce a reading an operator acts on
-([/decisions/ad-027.md](/decisions/ad-027.md)) and no command showed one — the rail recorded into a plane
-nobody read. Both are now decisions in `why`, and three lifecycle kinds remain unread, which is fine and stated.
-
-**An inline consumer cannot have a plane mismatch**, and the contract says so rather than passing it silently.
-The rollup is fed at `recordObs` time, before plane routing; `why` and the activity counter read plane files.
-Marking the difference is what separates "checked and fine" from "not checked".
-
-## Not decided here
-
-- **`generation.end`, `session.end` and `subagent.end`.** Emitted, read by nothing. They are lifecycle markers
-  and may stay that way; the report names them so it is a decision rather than an oversight.
-- **Validating attributes per kind.** The payload half of a contract, and a much larger change. The rollup reads
-  `attrs.permission`, `attrs.rule` and others with no declaration that a producer sets them.
-- **A runtime check.** This is a build gate; a hook has no budget for it.

package/docs/decisions/ad-066.md

@@ -1,111 +0,0 @@
----
-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

@@ -1,64 +0,0 @@
----
-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

@@ -1,79 +0,0 @@
----
-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

@@ -1,74 +0,0 @@
----
-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

@@ -1,86 +0,0 @@
----
-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

@@ -1,93 +0,0 @@
----
-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.