@tech-leads-club/harness-toolkit 0.2.1

package/docs/decisions/ad-043.md

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

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

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

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

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

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

package/docs/decisions/ad-049.md

@@ -0,0 +1,66 @@
+---
+type: Decision
+title: "AD-049 — An empty synced file says which of four reasons made it empty"
+description: "An operator reported that the harness never updates its lessons file. It was being rewritten every session with the same sentence — \"No active project lessons yet.\" — because lessons were switched off. That sentence covered four different situations: off, on-but-nothing-repeated, candidates-not-promoted, and active-but-withheld. Each now names itself."
+tags: [decision, lessons, visibility]
+timestamp: "2026-08-05"
+---
+
+# AD-049 — An empty synced file says which of four reasons made it empty
+
+- **status**: active
+- **date**: 2026-08-05
+
+## Decision
+
+1. **`emptySyncReason` names the reason** the synced markdown has no lessons in it, from the store and the config.
+2. **Four distinct reasons**, asserted distinct by a test: the capability is off; on with an empty store; candidates
+   recorded but none promoted; active but withheld.
+3. **The switched-off reason names the config field and the route to change it** — the init skill, not the file.
+4. **`renderLessonsMarkdown` takes the whole config** rather than one number from it, because the reason needs
+   `enabled` and `promoteHitCount` too.
+5. **The docs name `.specs/LESSONS.md` as belonging to the `/sdd` skill**, so the two files stop being compared.
+
+## Why
+
+The report: "uma coisa que eu percebi é que ele não tá atualizando nunca esse arquivo, mas atualiza o `.specs` do
+tlc." Followed by "mandei um init all default".
+
+Both halves are informative.
+
+`intelligence.lessons.enabled` defaults to **false**, and an all-defaults init leaves it off. With
+`syncRulesFile` on, `gardenAndPersistLessons` rewrote the file at every session end — with the same empty text,
+forever. From the outside that is indistinguishable from a file nothing writes, which is exactly how it was
+reported.
+
+And the sentence could not have told him anything, because it was the same sentence for four situations. Reaching a
+non-empty file requires all of: the capability on, the **same** gate failure repeating inside one session
+(`hits >= 2`), and the resulting candidate promoted across `promoteHitCount` distinct sessions — `rankLessonsForSync`
+filters on `status === "active"`. Three hurdles, one message.
+
+The other half of the report is a naming collision the harness does not own. `.specs/LESSONS.md` is the `/sdd`
+skill's own lessons layer. Seeing one update and the other not is reasonable evidence that the second is broken,
+and the answer is documentation rather than code: the harness must not couple to another tool's files, and AD-035
+already refused to read a project's documentation at all.
+
+## Trade-offs
+
+**Four strings to keep true.** A fifth state — say, every lesson quarantined — falls through to the original
+sentence. The test asserts the four are distinct, not that the set is complete.
+
+**The reason is computed on every sync.** It reads the store that was just gardened and does no extra I/O.
+
+**It says "ask the agent to run the harness-init skill" rather than naming a command.** There is no CLI to toggle a
+capability, because `tlc harness` mutations are the operator's from a terminal ([/decisions/ad-022.md](/decisions/ad-022.md)) and the init skill is the
+sanctioned interactive route. A line pointing at a command that does not exist would be the AD-047 defect again.
+
+## Not decided here
+
+- **Whether the file should be written at all when lessons are off.** It is, and it says so. Not writing it would
+  leave `syncRulesFile: true` silently doing nothing, which is the same defect one layer down.
+- **Surfacing the off state in `doctor`.** `checkLessonHealth` is silent when the capability is off, deliberately —
+  a row about a disabled feature is noise on every healthy run ([/decisions/ad-034.md](/decisions/ad-034.md)). The synced file is the place an operator
+  who enabled `syncRulesFile` is already looking.
+- **Whether `promoteHitCount: 2` is the right default** for a capability whose first visible output needs two
+  sessions. It is the recurrence threshold AD-038 argued for; the interaction with time-to-first-output is not
+  measured.