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

package/docs/decisions/ad-042.md

@@ -1,82 +0,0 @@
----
-type: Decision
-title: "AD-042 — The suite gets an empty runtime home, and one renderer renders a lesson"
-description: "Two defects the previous change shipped, both found by running it rather than by any check. `TLC_HOME` was deliberately left alone in the hermetic setup, which was safe only while nothing machine-wide lived under it — the global lesson tier does, so a test reading `allLessons` read whichever lessons the developer had promoted. And `support.ts` carried a copy of the lesson renderer, so the tier added to the core block never reached the text a model receives."
-tags: [decision, testing, lessons, hermetic]
-timestamp: "2026-08-04"
----
-
-# AD-042 — The suite gets an empty runtime home, and one renderer renders a lesson
-
-- **status**: active
-- **date**: 2026-08-04
-
-## Decision
-
-1. **`tools/test-env.mjs` points `TLC_HOME` at a fresh empty temp directory.** Redirected, not deleted — deleting
-   it would send every test at the developer's real `~/.tlc/harness`, which is the opposite of hermetic.
-2. **A test that needs the real runtime says so.** `e2e-consistency.test.ts` drives the actual launcher and CLI, so
-   it passes `TLC_HOME: repoRoot` explicitly.
-3. **`renderLessonLine` in `src/entrypoints/support.ts` delegates to the core renderer**, exposed on the facade as
-   `coreFacade.lesson.renderLessonBlock`. The copy is deleted.
-4. **An end-to-end test asserts the tier appears in the text the hook returns**, not only in the core block.
-
-## Why the runtime home had to change
-
-`TLC_HOME` was excluded from the hermetic setup on an explicit rationale, written in
-`tools/test-env.names.mjs`: it names *which runtime*, not which project, CI sets it deliberately, and the suite
-exercises it.
-
-That was true, and it stopped being sufficient the moment something machine-wide lived under it. AD-040 put the
-global lesson tier at `<runtime home>/state/lessons.json`. From then on, any test calling `allLessons` without
-pinning a home read whichever lessons the operator of that machine happened to have promoted.
-
-The failure profile is what makes this worth a decision record: **green on a fresh machine, green in CI, green on
-mine at commit time** — because my global store was empty — and red minutes later, when I promoted five lessons
-into it. The gate ran three times and passed three times before the store had contents. Nothing about the change
-was wrong; the test's assumption was, and the assumption only became visible once the feature was used.
-
-`obs.globalSpool` ([/decisions/ad-018.md](/decisions/ad-018.md)) had already put a file under the runtime home and did not expose this, because no test
-asserts a count over the spool. The lesson store is read by `allLessons`, which almost every lesson test calls.
-
-## Why one renderer
-
-`support.ts` carried `renderLessonLine`, a duplicate of `renderLessonBlock`, with a comment explaining the choice:
-the core's version is presentation-only and was not on the facade, so reaching into core internals was avoided by
-copying it.
-
-The copy is the one the model actually receives. So `[gate/status/tier]` — added in AD-040 precisely so a turn can
-tell that a lesson was written about a different repository — rendered in `lessons list` and in nothing an agent
-ever saw. Two derivations of one string is the same defect as a consumer without a producer, pointed sideways: both
-halves work, and the one that matters is the one nobody checked.
-
-Exposing it on the facade is the sanctioned route ([/decisions/ad-004.md](/decisions/ad-004.md)). "Presentation does not belong in core" was the right
-instinct applied to the wrong thing — the block's shape *is* a core contract, because ranking, budgeting and the
-synced markdown all depend on its length.
-
-## How both were found
-
-By running the thing and reading the output — the practice AD-034 records, not a mechanism. `check-wiring` ([/decisions/ad-041.md](/decisions/ad-041.md))
-catches a declared member nothing writes; neither of these is that shape. Stated plainly: after this change the
-harness mechanically refuses one defect family, and the other two found here still depend on someone exercising the
-feature and reading what comes out.
-
-## Trade-offs
-
-**Every test now pays a `mkdtemp` at startup.** One syscall per test process, twice per gate run.
-
-**A test that silently depended on the ambient runtime home now fails.** Three did, all in the E2E file, and all
-three were better off stating the dependency. A future test that needs the real runtime will fail loudly rather
-than pass for an ambient reason.
-
-**The temp home is not cleaned up.** The OS reclaims `TMPDIR`; a directory per test process with nothing in it is
-cheaper to leak than to track.
-
-## Not decided here
-
-- **Whether CI should keep setting `TLC_HOME` to the workspace.** It still does, and the setup module now overrides
-  it for the suite while `check-dist-fresh` and the CLI steps still read it.
-- **A mechanical check that a test does not read machine state.** It would need to know which paths are
-  machine-wide; the hermetic setup covers the two that exist.
-- **Auditing every other machine-wide read for the same assumption.** The runtime home is now empty for the suite,
-  which covers the class rather than the instances.

package/docs/decisions/ad-043.md

@@ -1,79 +0,0 @@
----
-type: Decision
-title: "AD-043 — A standing rule is pinned, not ranked, and the budget says what it dropped"
-description: "The operator's own rule was written, stored, correct and never delivered. Three causes, each invisible on its own: an authored lesson carried `priority: 0.8` on a 70..100 scale, so it contributed 0.004 where a seed contributes 0.45; the char budget fits about two blocks while `maxInjectSession` promises five, silently; and ranking is the wrong mechanism for an instruction the operator did not want ranked."
-tags: [decision, lessons, ranking, visibility]
-timestamp: "2026-08-04"
----
-
-# AD-043 — A standing rule is pinned, not ranked
-
-- **status**: active
-- **date**: 2026-08-04
-
-## Decision
-
-1. **`priority: 0.8` on an authored lesson becomes `80`.** Every other producer uses 70..100 and `relevanceScore`
-   divides by 200. The old value was written as if priority were the 0..1 scale `confidence` uses.
-2. **A lesson can be pinned.** `tlc harness lessons add --pin` sets `pinned: true`; pinned lessons are placed before
-   every scored lesson, in store order.
-3. **Pinning changes order, not eligibility.** Staleness, the validity window, mode filtering and the char budget
-   all still bind on a pinned lesson.
-4. **`selectLessons` returns `omitted`**, and the injected block names it when it is non-zero.
-5. **The note is silent when nothing was dropped.**
-6. **`lessons list` marks a pinned lesson `PINNED`.**
-
-## Why, and how the three causes hid each other
-
-The intent was one rule: never declare work done without an end-to-end run pasted into the reply. It was written
-to the global tier, stored correctly, and `lessons list` showed it active. It never reached a turn.
-
-Running `selectLessons` against another repository and printing what came out gave the answer in one line — the
-rule was absent and two core seeds were present. Then three separate causes had to be peeled apart:
-
-**The priority scale.** `buildAuthoredLesson` set `priority: 0.8`. `relevanceScore` adds `priority / 200`, so an
-authored lesson contributed **0.004** where `core:gate:stagnation` contributes 0.5. Combined with confidence 0.8
-against 1, and no decay on core, every authored lesson sat at the bottom of every ranking. Shipped in AD-035 and
-invisible for as long as nobody looked at an ordered list — the observed scores, 0.203 and 0.305 against 0.700,
-match the arithmetic exactly.
-
-**The silent budget.** `maxInjectSession` defaults to 5, `maxCharsSession` to 900, and a rendered block is four
-lines. Two fit. So the count promised five, delivered two, and nothing anywhere said so. That is the same defect
-family as a config value nothing reads, pointed the other way: a config value that reads as a promise the
-mechanism cannot keep.
-
-**Ranking as the wrong mechanism.** Fixing the scale was not enough, and the correct response was not to keep
-raising numbers until the rule won. Ranking exists for lessons the harness *inferred* from failures — it weighs
-recurrence, decay and gate match, all of which are estimates. An instruction the operator wrote deliberately has
-no recurrence to accumulate and is not an estimate. Making it compete on score was a category error.
-
-## Why pinning is bounded rather than absolute
-
-A pinned lesson still obeys the char budget. The alternative — pinned content bypassing the budget — would let a
-handful of pins consume the whole session context and make the budget a suggestion.
-
-The worst case is therefore an operator pinning more than fits, and the omission note is what makes that visible
-instead of silent. Staleness and validity still apply, because a pinned rule that names a renamed file is exactly
-as wrong as an unpinned one.
-
-## Trade-offs
-
-**A pinned lesson displaces a higher-scoring one.** That is the point, and it is the operator's explicit choice.
-
-**Nothing caps how many lessons can be pinned.** A cap would need a number nobody can justify. The budget already
-bounds delivery, and `lessons list` shows every `PINNED` row.
-
-**The priority fix changes the ranking of every authored lesson already on disk.** They move up, which is what the
-0..100 scale always meant.
-
-**The omission note costs a line whenever the budget binds.** With the default 900-char budget and any real store,
-that is most turns — which is honest: it says the budget is the binding constraint, and raising `maxCharsSession`
-is the operator's call.
-
-## Not decided here
-
-- **Raising the default `maxCharsSession`.** It is per-project config, and a default that spends more context by
-  itself is a decision for whoever installs the harness.
-- **`lessons pin <id>` / `unpin <id>`.** Today pinning is set when the lesson is written; rewriting the same
-  instruction updates it in place, which covers the case.
-- **Whether core seeds should ever be pinnable.** They ship immutable, so there is nowhere to record it.

package/docs/decisions/ad-044.md

@@ -1,61 +0,0 @@
----
-type: Decision
-title: "AD-044 — Only an injection a gate could grade can be unproven"
-description: "The effectiveness reading counted session-start injections, which nothing ever grades — a lesson whose gate is `any` is not even eligible on a retry. So a healthy pinned standing rule reported `unproven` forever and `doctor` warned about it on every run, in every repository on the machine. A separate `gradeableCount` is incremented where the pending credit is written."
-tags: [decision, lessons, measurement, visibility]
-timestamp: "2026-08-04"
----
-
-# AD-044 — Only an injection a gate could grade can be unproven
-
-- **status**: active
-- **date**: 2026-08-04
-
-## Decision
-
-1. **`gradeableCount` counts injections a later gate run can grade** — incremented where the pending credit is
-   written, so the counter and the credit cannot disagree.
-2. **`unproven` means `gradeableCount > 0` and nothing graded yet.** It no longer reads `injectedCount`.
-3. **A lesson injected only at session start reads `session-only`**, rendered as
-   `session-only (injected 12x, never for a gate)`. It is not a warning.
-4. **`doctor` says "1 lesson has been injected … nothing shows it helped"** with real agreement, instead of
-   "1 lesson have been injected … nothing shows it help".
-
-## Why
-
-`injectedCount` is incremented for every injection, in both modes. Only the retry path writes a pending credit,
-because only there is there a gate whose next run can decide. So a session-start injection can never be graded.
-
-The two facts combine badly for exactly the case AD-043 just made possible. A pinned standing rule is written
-with gate `any`; `allowedForMode` on a retry requires `failedGate === gate`, so an `any` lesson is **never
-eligible on a retry**. It is injected at every session start, `injectedCount` climbs, `gradeableCount` stays at
-zero, and the old reading called that `unproven` — forever, in every repository on the machine, as a `doctor`
-warning.
-
-That is an alarm firing on a healthy install, which AD-034 named as its own defect family: a warning the reader
-learns to skip takes the next real one with it. The measurement was also simply wrong — the lesson is not
-unproven, it is unprovable by this mechanism, and those are different claims.
-
-## How it was found
-
-By running `tlc harness doctor` from a second repository after pinning the rule, and reading the output. The
-grammar defect was in the same line.
-
-## Trade-offs
-
-**A third reading to explain.** `not-injected`, `session-only`, `unproven`, `helped`, `neutral`. The alternative
-is one reading that is wrong for the most common case.
-
-**`session-only` is not actionable.** Deliberately: it states that this lesson's usefulness cannot be measured by
-the current mechanism, which is information, not a task.
-
-**Records written before this field read `gradeableCount: 0`**, so an already-graded lesson keeps its `helped` or
-`neutral` reading and an ungraded one drops from `unproven` to `session-only` until it is next injected for a
-gate. No migration; the reading self-corrects.
-
-## Not decided here
-
-- **Grading session-start injections.** It would need a notion of "the session went well", which the harness does
-  not have. Recorded in AD-039 and still true.
-- **Making an `any` lesson eligible on a retry.** It would be boosted by gates it was never about, which is the
-  reason AD-035 chose a neutral gate in the first place.

package/docs/decisions/ad-045.md

@@ -1,94 +0,0 @@
----
-type: Decision
-title: "AD-045 — A gate verdict is reused when the content hash of its inputs did not change"
-description: "A read-only question in a repository with uncommitted work re-ran the whole suite, because the trigger read the state of the tree rather than what the turn did. The verdict is now keyed on a content hash of the command and the files, which is the monorepo-tooling rule: same inputs, replay the result. Making a reused failure advisory instead of blocking was tried and rejected — the suite showed it silences the stagnation rail."
-tags: [decision, gate, cost, caching]
-timestamp: "2026-08-05"
----
-
-# AD-045 — A gate verdict is reused when its inputs did not change
-
-- **status**: active
-- **date**: 2026-08-05
-
-## Decision
-
-1. **`computeInputsHash` keys a verdict** on the gate command plus each file's repository-relative path, size and
-   **contents**.
-2. **A matching hash reuses the verdict** and the command does not execute.
-3. **Contents, not mtime.** A `touch`, a branch switch restoring identical bytes, or a clock that moved all change
-   mtime without changing anything the gate reads.
-4. **An unreadable input or a cap overrun is incomplete, and incomplete is never a hit.** Unknown means run.
-5. **An incomplete hash is not recorded either.** It hashes over the subset it could read, which collides with the
-   hash of that subset alone.
-6. **The gate name is compared as well as the hash**, in a function with its own test, because end to end the
-   check is unfalsifiable while the command is part of the key.
-7. **A reused verdict changes nothing but execution.** It still blocks on failure, still advances the fingerprint,
-   still grades lessons.
-8. **`gate.outcome` carries `reused`,** and the session report counts reused verdicts in their own column and adds
-   no time for them.
-
-## Why
-
-`stop.ts` decided whether to run the gates from `listChangedRepoFiles` — `git diff HEAD`, `--cached`,
-`ls-files --others`. That is the state of the tree. With any uncommitted work present, **every** turn re-ran the
-suite, including turns that changed nothing.
-
-The report: a colleague asked "check the tasks and status" in a repository mid-feature. The agent answered, the
-stop hook ran the suite, returned `BLOCKED: test failed`, and the agent abandoned the question to fix tests nobody
-had asked about. The same mechanism is the likely cause of the earlier "more than thirty minutes running jest"
-report, which was diagnosed as a slow machine and measured as hook latency. It was not the machine, and that
-earlier conclusion is wrong.
-
-The 2026 stop-hook pattern acts only when code was modified, detected from the turn's own tool calls. The
-monorepo-tooling rule keys a task result on a content hash of its inputs and replays on a match. This takes the
-second: a hash covers a turn that wrote nothing *and* a turn that wrote through a shell command, which
-transcript-scanning does not.
-
-## The divergence that stays
-
-The published guidance is that the hook should detect and decide, not perform the validation — keep it under ten
-seconds and let the agent run the suite when it acts on the block reason.
-
-This harness does the opposite deliberately. If the agent executes the verification, it can skip it or misreport
-it, and the whole thesis is that the verdict is not the model's to give. The cost of that choice is what the
-colleague paid; the cache is how it stops being paid for questions rather than for work.
-
-## What was tried and rejected
-
-A reused **failure** was going to be advisory — surfaced as context rather than blocking — on the reasoning that
-blocking on a failure the turn did not cause hijacks the operator's question.
-
-The suite refused it. Four existing tests failed, and the reason is structural: with the advisory in place a
-reused failure never reaches `failGate`, so `trackFingerprint` never runs, so the **stagnation rail stops firing
-exactly in the case it exists for** — an agent that changes nothing and stops again. An agent could escape a grind
-loop by doing nothing.
-
-The discriminator that would make it safe is "was the operator asking, or was the agent told to fix this" — and
-the stop payload does not carry it. `handoff.last_gate_result` and the loop counter are both proxies that break on
-one provider or the other. So the advisory is not shipped, and the cost fix stands on its own: the suite does not
-re-run, which is the part that was expensive.
-
-No published source discusses replaying a cached **failure** at all; every example demonstrates a cache hit on a
-passing task. That gap is real and this decision does not close it.
-
-## Trade-offs
-
-**Hashing costs a read per changed file per stop.** Bounded at 400 files and 12 MB; over either, the result is
-incomplete and the gate runs. A hash of a few files is orders of magnitude cheaper than the command it replaces.
-
-**A verdict can be stale in a way the hash cannot see.** An external input — a database, a network service, an
-environment variable, the clock — can change without any file changing. Turborepo has the same exposure and
-handles it by declaring inputs; here the changed-file set is the declaration, and a gate depending on the world
-outside it will reuse a verdict that no longer holds.
-
-**One artifact per repository, not per gate.** `readLastGate` returns the most recent artifact of any gate, so a
-lint run overwrites the test verdict and the next test stop re-runs. Correct but weaker than it could be; a
-per-gate artifact is a bigger change to a file other things read.
-
-## Not decided here
-
-- **Advisory for a reused failure.** Above. It needs a signal the harness does not have.
-- **A per-gate artifact**, which would let lint and test both stay cached across a turn.
-- **Declaring extra inputs** — a lock file, a config file, an environment variable — so a gate that depends on more
-  than the changed files can say so.

package/docs/decisions/ad-046.md

@@ -1,111 +0,0 @@
----
-type: Decision
-title: "AD-046 — The runtime path is an artifact, and update never touches what it does not own"
-description: "`tlc harness update` failed for a colleague because the harness itself had dirtied the checkout: update rebuilt `dist/` in place, and Bun and esbuild produce different bytes for the same source. The message then named the wrong cause, offered a remedy that runs the command that just failed, and told the operator to `git reset --hard` a path that on a contributor's machine is a symlink to their own repository. Ownership now decides what update may write."
-tags: [decision, update, install, safety]
-timestamp: "2026-08-05"
----
-
-# AD-046 — The runtime path is an artifact
-
-- **status**: active
-- **date**: 2026-08-05
-
-## Decision
-
-1. **`classifyRuntimePath` names what the runtime path is**: `managed` (a checkout the installer created),
-   `linked` (a symlink to someone's clone), `unmanaged` (no `.git`), `absent`.
-2. **The symlink test comes first**, decided by the path and never by its contents. A linked clone has a `.git`
-   too, so testing for that first would classify a contributor's repository as the harness's own.
-3. **A managed artifact is moved with `git reset --hard`**, not a fast-forward merge. It is the harness's own, so a
-   local change in it is not the operator's work and not a conflict for them to resolve.
-4. **A linked path receives no git command at all** — not fetch, not merge, not reset. Update refreshes only what
-   is machine-local (CLI link, skill link, provider hooks) and exits zero.
-5. **`update` builds only when a bundle is missing.** `dist/` is committed and the gate keeps it matching `src/`,
-   so the pulled revision already carries the right bundles.
-6. **Every message that named a remedy the harness does not perform is deleted.**
-7. **`doctor` reports the path kind** as one `ok` row for both supported kinds.
-
-## Why
-
-Five defects, each measured.
-
-**The harness created the dirt.** `update` ran `bin/tlc-build`, which rebuilds `dist/` inside the checkout.
-`tlc-build` uses Bun when present and esbuild otherwise. Measured on the same source:
-
-```
-bun 1.3.14     → 223,390 bytes
-esbuild 0.28.1 → 228,018 bytes
-```
-
-Any toolchain differing from the one that produced the committed bundles leaves the checkout permanently dirty, so
-**every later update fails to fast-forward**. That is every user, not an unlucky one.
-
-**The diagnosis was wrong.** Git reported uncommitted local modifications; the message said "the runtime checkout
-has commits that upstream does not". Two different situations, and the operator was sent looking for commits that
-did not exist.
-
-**One of the two remedies did not exist.** "Re-run the installer, which replaces the checkout" — `install.sh` runs
-`git -C "$DEST" pull --ff-only`, the command that had just failed. It replaces nothing.
-
-**The safety judgement was inverted.** It warned that `reset --hard` "throws work away". What it would have
-discarded was build output the harness generated.
-
-**And the remedy was destructive.** `install.sh` links `$DEST` to the clone it was run from, so on a contributor's
-machine `~/.tlc/harness` **is a symlink to their working repository**. Verified on the author's machine while
-diagnosing this. The printed `git reset --hard` would have destroyed uncommitted work. The colleague who reported
-it was safe only because he had installed with the curl one-liner — by install method, not by design.
-
-## The standard this adopts
-
-The named smell is conflating a **package artifact** — replaceable, nobody edits it — with a **working tree**, which
-assumes a human resolves conflicts. The published fixes, in order of strength: do not track generated files in the
-install path; revert them before pulling; or replace the pull with a versioned release download and an atomic swap,
-which is what rustup, nvm and deno do.
-
-This change adopts the principle those all rest on — **the install path is an artifact the tool owns, and the
-updater never touches anything it does not own** — without the release machinery. `git` stays the transport; what
-changes is that the checkout is now genuinely disposable, because nothing is written into it that upstream does not
-already ship.
-
-## What the demo and CI each caught, after the tests were green
-
-**The demo, before pushing.** `resolveHarnessRoot` calls `realpathSync`, and the first version classified that
-resolved path — so a linked clone read as `managed` and `update` ran `git fetch` inside a contributor's repository.
-Sixteen unit tests passed through it, because they called the classifier directly with the path they meant. Only
-driving the real command against a real linked install showed it. Classification now takes the **configured** home.
-
-**macOS CI, after pushing.** The fix for that came with a second condition: treat "the path resolves elsewhere" as
-linked too, to catch a symlinked ancestor — justified in a comment with macOS as the example. macOS is what refuted
-it. `/var` is a symlink to `/private/var`, so every path under the system temp directory resolves elsewhere, and a
-**managed** checkout classified as `linked`: updates would have stopped silently on the platform the reporter uses.
-Only the last hop decides now, which is the one thing `install.sh` actually creates, and a regression test asserts
-that a managed checkout under a symlinked ancestor stays managed.
-
-Both belong here because the shape repeats: a guess about the filesystem, argued from an example, and only a real
-platform can settle it.
-
-## Trade-offs
-
-**A hard reset discards local commits at a managed runtime path silently.** That is the point: it is not a place to
-develop. Anyone developing there has a `linked` install, which is never touched.
-
-**No rollback.** A versioned-directory layout would make reverting a symlink flip. Deferred below.
-
-**`state/` and `config.json` still live inside the artifact.** They are gitignored, so a reset cannot remove them —
-asserted by a test rather than trusted, because the whole model rests on it.
-
-**Building only when a bundle is missing trusts the committed `dist/`.** If upstream ever shipped a stale bundle, a
-Node-fallback user would run stale code until a bundle went missing. `check-dist-fresh` in the gate is what makes
-that impossible by construction, and it is a repository invariant rather than a runtime one.
-
-## Not decided here
-
-- **Versioned artifact directories with an atomic swap** (`~/.tlc/versions/<rev>`, `harness → versions/…`). The full
-  form of the standard, and it buys rollback. It needs release artifacts in CI, checksum verification, junctions on
-  Windows, and a migration for every existing install.
-- **Moving `state/` and `config.json` out of the artifact.** The right end state — user data should not live inside
-  a disposable directory — but it is a data migration, and every moved file is a chance to lose an operator's global
-  lessons or obs history. It gets its own change, with a verified migration.
-- **Making the build deterministic** by pinning one bundler. It would let `dist/` be rebuilt anywhere without dirt,
-  but pinning Bun breaks the esbuild fallback that exists for machines without Bun ([/decisions/ad-012.md](/decisions/ad-012.md)).

package/docs/decisions/ad-047.md

@@ -1,96 +0,0 @@
----
-type: Decision
-title: "AD-047 — An instruction is not an affordance, and a refusal names the route that works"
-description: "The bootstrap told the agent to read `.tlc/harness/state/handoff.json`, a path the floor guards, and the obvious command — `test -f … && head -c 2000 …` — was refused with advice about writing policy. Three layers disagreed: the instruction asked for something the runtime denies, and the denial could not be planned around. The instruction now names `tlc harness handoff`, `test` and `[` join the proven readers, and each refusal carries the remedy for its own case."
-tags: [decision, floor, affordance, agent-experience]
-timestamp: "2026-08-05"
----
-
-# AD-047 — An instruction is not an affordance
-
-- **status**: active
-- **date**: 2026-08-05
-
-## Decision
-
-1. **`tlc harness handoff [--json]`** is the sanctioned way to read handoff state. Nothing has to reach into the
-   protected path.
-2. **Every instruction naming the handoff names the command**, not the file — session start, session end, and the
-   operator bootstrap. The path still appears, as *where state lands*, never as the route.
-3. **`test` and `[` join the proven readers.** They evaluate a predicate and produce an exit code; neither can write
-   a file, which makes them strictly safer than `echo`, already on the list.
-4. **A policy-surface refusal carries the remedy for its own case.** A read refusal says how to read; a write
-   refusal says who may write.
-5. **Allowlisting a verb does not allowlist a redirect.** `test -f x > config.json` is still denied by the redirect
-   rule.
-
-## Why
-
-A colleague's agent was told, by the harness, to read the handoff. It ran the natural command:
-
-```
-test -f /…/.tlc/harness/state/handoff.json && head -c 2000 …
-```
-
-`head` is a proven reader. `test` was not on the list, so the segment was denied — and the denial ended with the
-sentence every policy-surface refusal ended with:
-
-> Set a gate command with `tlc harness gate test-command` or `gate lint-command`, and run policy changes from your
-> own terminal rather than from inside this session.
-
-That is advice about *writing* policy, handed to an agent trying to *read* a file the harness had just pointed it
-at. The operator's report was exact: "ele diz pra usar o handoff, mas tem comandos que não são permitidos — aí
-confunde o agente."
-
-Three layers had drifted apart: the instruction text, the set of permitted verbs, and the refusal.
-
-## What the research changed
-
-The 2026 literature on agent tool use names both halves of this.
-
-The authorization work frames the general rule as **existence is not permission** — a tool being callable is not the
-same as it being authorized, and prompt text is not a boundary. The inverse is the case here: **an instruction is
-not an affordance.** Telling a model to do something is not the same as granting it, and the fix is to stop exposing
-a route the runtime will refuse.
-
-The recommended handling of the refusal itself is to *make the deny legible*: return structured, self-describing
-refusals the model can plan around, rather than opaque ones. Work on tool documentation
-(OpaqueToolsBench / ToolObserver) reaches the same place from the documentation side — descriptions are
-load-bearing infrastructure and must cover failure modes, not only the happy path, because a model cannot predict
-what a stateful environment will do.
-
-Without that research this would have been fixed by adding `test` to the allowlist and stopping. The allowlist gap
-is the smallest of the three defects; the refusal giving unrelated advice, and the harness pointing at a path it
-guards, are the ones that confused the agent.
-
-## Why `test` was missing, and why adding it is not a loosening
-
-The allowlist is deliberately an allowlist: the ways a shell can write are unbounded — `python3 -c`, `perl -pi`,
-`ex`, any interpreter — so enumerating writers guarantees a hole, and enumerating readers puts an unknown verb on
-the deny side without anyone predicting it. `awk` and `sort` are excluded on purpose, because `awk '{print > f}'`
-and `sort -o f` write a file the head verb never reveals.
-
-`test` and `[` have no such form. There is no flag, no redirect of their own, no output beyond an exit code. Their
-absence was an incomplete list rather than a decision.
-
-## Trade-offs
-
-**Two remedies to keep true instead of one.** A branch that denies without passing a remedy falls back to the write
-advice, which is right for the write cases and wrong for a read case somebody adds later. The sensor covers the
-distinction in both directions.
-
-**`tlc harness handoff` is another surface to keep honest.** It reads the same file the hooks read, through the
-facade, so it cannot report something different from what a hook sees.
-
-**The bootstrap line is longer.** It now carries the command and the path, because the path is still where state
-lands and an operator looking for the file should find it.
-
-## Not decided here
-
-- **Whether the floor should refuse `tlc harness handoff` mid-session.** It reads and writes nothing, so it is not
-  in `MUTATING_SUBCOMMANDS`.
-- **Auditing every other instruction the harness emits against what the floor permits.** This one was found by a
-  report. A mechanical check — every path named in injected prose is one the floor allows a proven reader on —
-  would catch the class, and is not built.
-- **`--json` shape stability.** The report is a projection over the handoff file, and the handoff schema is
-  versioned; the projection is not.

package/docs/decisions/ad-048.md

@@ -1,85 +0,0 @@
----
-type: Decision
-title: "AD-048 — A broken updater cannot deliver its own fix, so the installer is the recovery route"
-description: "AD-046 fixed `tlc harness update`, and the fix could not reach anyone who needed it: the new code lives in the revision the broken updater cannot fetch. A colleague updated, got the old message from his stale CLI, and typed `--force`, which was accepted in silence and did nothing. The installer now recovers a managed checkout with a hard reset — the one route that does not run through the installed CLI — and `update` says what `--force` is not."
-tags: [decision, update, install, delivery]
-timestamp: "2026-08-05"
----
-
-# AD-048 — A broken updater cannot deliver its own fix
-
-- **status**: active
-- **date**: 2026-08-05
-
-## Decision
-
-1. **`install.sh` and `install.ps1` recover a managed checkout** with `fetch` + `reset --hard origin/main`, rather
-   than `pull --ff-only`.
-2. **Neither installer runs git against a linked runtime.** `[[ -L "$DEST" ]]` on Unix and `LinkType` on Windows are
-   checked *before* the `.git` test, because `[[ -d "$DEST/.git" ]]` follows a symlink and would have matched a
-   contributor's clone.
-3. **`update` validates its flags.** `--force` is answered with what it is not and what to do instead; any other
-   unknown flag is named.
-4. **The README and the diagnose runbook name the one-liner as the recovery**, because it is the only route
-   independent of the installed CLI.
-
-## Why
-
-AD-046 was correct and undeliverable.
-
-`tlc harness update` runs from the installed runtime. The fix for `update` is in a revision that `update` has to
-fetch and fast-forward to — and the bug being fixed is precisely that the fast-forward aborts. So every install that
-had ever rebuilt `dist/` with a different bundler was stuck at its current revision, and the new code could not
-arrive.
-
-The report shows it exactly. A colleague ran `tlc harness update --force` and got:
-
-```
-Updating 297b623..b453d8b
-error: Your local changes to the following files would be overwritten by merge:
-        dist/…  (17 bundles)
-update: fast-forward failed (origin/main) — the runtime checkout has commits that upstream does not.
-  or re-run the installer from the README, which replaces the checkout
-```
-
-Three separate things are visible in that output:
-
-- **The message is one this repository no longer contains.** `ffFailureMessage` was deleted in AD-046. He was
-  running the old CLI, which is the proof that the fix had not landed and could not.
-- **`--force` was swallowed.** `route` filtered flags for every other command and not for `update`, so a flag that
-  does not exist was accepted without a word. He had every reason to read the unchanged failure as a refusal to
-  force.
-- **The remedy it offered still did not work.** "Re-run the installer, which replaces the checkout" —
-  `install.sh` ran `git pull --ff-only`, the same command that had just aborted. AD-046 deleted that sentence from
-  the CLI and left the installer as it was, so the sentence stopped being printed without becoming true.
-
-## What this says about the shape of the change
-
-A self-updating tool needs a recovery path that does not run through the thing being updated. `curl | bash` is that
-path here: it is fetched fresh from upstream every time, so it carries the current logic regardless of what is
-installed. That makes the installer, not the CLI, the place where "get me to a known-good state" has to work.
-
-The same reasoning is why the deferred versioned-artifact layout in AD-046 matters more than it looked: with
-`~/.tlc/versions/<rev>` and a symlink swap, recovery is a link flip and there is nothing to reconcile. This change
-does not build that; it makes the route that exists actually work.
-
-## Trade-offs
-
-**The installer now discards local changes at a managed runtime path.** That is the ownership model of AD-046
-applied where recovery happens. `config.json` and `state/` are gitignored, so a reset cannot reach them — asserted
-by a test that writes both and checks they survive, because the whole recovery rests on it.
-
-**Existing installs need one manual step.** There is no way around it: the code that would do it for them cannot be
-delivered by the mechanism that is broken. The step is the documented install one-liner.
-
-**`--force` is refused rather than implemented.** A managed runtime is already hard-reset, and a linked clone must
-never be written to, so there is nothing left for a force flag to mean. Refusing it with that explanation is more
-honest than accepting it as a synonym.
-
-## Not decided here
-
-- **Versioned artifact directories with an atomic swap.** Still the full form, still deferred, and this decision is
-  the second argument for it.
-- **A check that the CLI and the installer agree.** They now implement the same ownership rule in TypeScript and in
-  bash and PowerShell, three times. Nothing enforces that they stay in agreement.
-- **Telling an operator their runtime is behind.** `update --check` reports it, and nothing surfaces it unprompted.