@tech-leads-club/harness-toolkit 0.2.1

package/docs/decisions/ad-050.md

@@ -0,0 +1,94 @@
+---
+type: Decision
+title: "AD-050 — Lesson transport is a provider capability, not an operator preference"
+description: "A question about duplicated lessons found the opposite of duplication: on the host that drops context returned from its session-start hook, the durable rules file was the only route to the model, and it was off by default. Transport becomes a declared capability, the advisory stops being rendered into a field that host ignores, and the cost report names which of the two is paid."
+tags: [decision, lessons, providers, capabilities, observability]
+timestamp: "2026-08-05"
+---
+
+# AD-050 — Lesson transport is a provider capability, not an operator preference
+
+- **status**: active
+- **date**: 2026-08-05
+
+## Decision
+
+1. **`sessionStartContextReliable` is declared per provider** and states whether context returned from the
+   session-start hook reaches the model. It is not the same question as whether the field exists.
+2. **`contextAtStop` is declared per provider** and read by `degrade`, so a `context` decision raised on `stop`
+   abstains where the host has no field to carry it.
+3. **`intelligence.lessons.syncRulesFile` becomes `auto` | `always` | `never`, defaulting to `auto`.** Under `auto`
+   the durable view is written where the host does not deliver hook context, and withheld where it does.
+4. **The legacy boolean is coerced** — `true` reads as `always`, `false` as `never` — and `lessons list` names the
+   coercion once, next to the value it produced.
+5. **`durableViewVerdict` takes the capability as data** and returns a reason, following `appendFilesVerdict`. Core
+   does not import a provider to decide it.
+6. **The durable view is written at session start as well as session end**, from `allLessons` rather than from the
+   project store, filtered by `appliesHere` as well as `isInjectable`.
+7. **The cost report says which transport is paid.** `durable_chars` is measured from the file that was written and
+   `hook_context_reliable` records what the provider declares.
+8. **`session.start` keeps carrying context on every provider**, because the drop is a race rather than a refusal.
+
+## Why
+
+The question was whether it is correct to hold the same lessons in `.cursor/rules/harness-lessons.mdc` and in
+`.tlc/harness/lessons.md`. Measuring it found the reverse of duplication.
+
+Cursor's own staff answered it, on the `sessionStart` `additional_context` bug report (forum thread 158452,
+2026-04-20): *"This is a bug on our side. `additional_context` from `sessionStart` gets dropped due to a timing issue
+between when the hook runs and when the composer handle is created."* `env` from the same payload arrives, because
+it follows a different code path. It was reported again against 3.14.7 on 2026-08-02 (thread 167274), and no
+changelog entry fixes it.
+
+So on that host the hook route is unreliable and the rules file is the durable one — which AD-011 item 4 had already
+reasoned, without a citation. What nobody had noticed is that `syncRulesFile` defaulted to `false`. An all-defaults
+init with lessons switched on therefore delivered lessons by **no** route at all, which is consistent with the
+report that opened AD-049. One boolean was deciding transport for two hosts with different capabilities: on the one
+that delivers hook context it was a convenience, and on the one that does not it was the only route.
+
+Two further defects came out of reading the schemas rather than assuming them.
+
+Cursor's `stop` output schema carries `followup_message` and nothing else, and `cursorRender` maps every `context`
+decision to `additional_context`. The docs gate's non-blocking advisory was therefore rendered into a field that
+host ignores. The test covering it asserted the text on a Cursor stop event, which is how it passed. `degrade`
+already abstained a `context` decision a provider could not carry — it only knew about `tool.before` and
+`tool.after`. Claude Code's `Stop` *does* accept `hookSpecificOutput.additionalContext` for feedback that continues
+the turn, so the advisory survives where it can be read.
+
+And the durable view was rendering from `readProjectLessons`, so it carried one of the three tiers AD-040
+introduced. On the host where that file is the only route, every shipped core lesson and every global lesson
+reached nothing.
+
+## Trade-offs
+
+**`auto` changes behaviour for an existing Cursor project.** A file appears in `.cursor/rules/` that was not there
+before. That is the fix, and `never` is the way to decline it — which is why the mode has three values rather than
+being inferred outright.
+
+**A file written into someone's repo.** `.cursor/rules/` is tracked by default in this project, on the reasoning
+that lessons are worth sharing with a team. In another repo that is the operator's call, and `never` is how they
+make it.
+
+**Two transports pay twice when the race is won.** Emitting at `session.start` on a host that usually drops the text
+means that when it does arrive, the same lessons arrive twice on that turn. The alternative is to stop emitting and
+lose the cases that work; the emission is bounded by `maxCharsSession`, so the cost of the overlap is bounded too.
+
+**`sessionStartContextReliable` is a claim about someone else's bug.** It will be wrong the day Cursor fixes the
+race, and nothing here will notice. The adapter cites the thread and the version so the claim can be re-checked
+rather than inherited.
+
+**`lessons list` carries a migration line.** It retires itself once the config is updated, and until then it is one
+line on a command an operator runs deliberately. `doctor` was the other candidate and was rejected: a row about a
+coerced field on every healthy run is the AD-034 defect.
+
+## Not decided here
+
+- **Whether the `alwaysApply` file's real token cost can be reported.** The harness cannot see the assembled prompt.
+  It reports the characters it wrote and states that the host is *asked* to include them on every request.
+- **Whether the advisory should reach the operator by another route on a host that cannot carry it.** It is in the
+  gate artifact, which is where `tlc harness` reads it. A handoff blocker for a non-blocking advisory was not
+  written.
+- **Whether the emission should stop once the Cursor race is fixed.** That is a capability flip, not a code change,
+  and the flip needs evidence that does not exist yet.
+- **Whether Claude Code should get the durable pointer by default.** `always` writes it. Under `auto` it does not,
+  because the hook delivers and the pointer would be a second copy of a working route.

package/docs/decisions/ad-051.md

@@ -0,0 +1,69 @@
+---
+type: Decision
+title: "AD-051 — A warning fails the gate, and a suppression states what breaks without it"
+description: "Three fixable warnings sat in this repository across several green gates, because a warn-level biome rule does not change the exit code. The gate now runs biome with --error-on-warnings, and a new checker fails it on any suppression whose reason is not a reason. Escalating every rule group to error was measured first and rejected."
+tags: [decision, gate, lint, quality]
+timestamp: "2026-08-05"
+---
+
+# AD-051 — A warning fails the gate, and a suppression states what breaks without it
+
+- **status**: active
+- **date**: 2026-08-05
+
+## Decision
+
+1. **The gate runs `biome check --error-on-warnings`.** A warn-level diagnostic fails it like an error.
+2. **`linter.rules` stays on the `recommended` preset.** Group-level `error` severity was measured and rejected.
+3. **`tools/check-suppressions.ts` is a gate step.** A `biome-ignore`, `@ts-ignore` or `@ts-expect-error` must carry
+   a reason opening with `why:`, `hazard:` or `invariant:` — the words this project already requires of any comment
+   that stays — followed by more than four words.
+4. **`@ts-nocheck` fails regardless of its reason**, because it silences a whole file rather than a diagnostic.
+5. **The three warnings are fixed rather than suppressed**, and one of them was a real defect.
+
+## Why
+
+`npx biome check .` exited 0 while printing "Found 2 warnings. Found 1 info." Warn-level diagnostics do not change
+biome's exit code unless `--error-on-warnings` is passed, so the gate was green and the output said otherwise. Three
+findings had survived that way long enough that nobody knew when they arrived.
+
+One was not cosmetic. `linkedRuntimeMessage(dest, target)` accepted `dest` and never used it, so the message read
+"the runtime path is a link to a working clone" without naming the path — while both sibling messages,
+`unmanagedRuntimeMessage` and `resetFailureMessage`, name theirs. An operator with more than one runtime could not
+tell which link was meant. `noUnusedFunctionParameters` had been pointing at it in the warning list.
+
+The other two were `useIndexOf` (a `findIndex` with an equality predicate) and `useOptionalChain`.
+
+**Group-level severity was tried and measured.** Setting every group to `error` in `biome.json` produced **3763**
+findings, because a group severity enables that group's non-recommended rules as well. Among them: `noBarrelFile`
+and `noReExportAll`, which forbid precisely the core facade this architecture is built on ([/decisions/ad-004.md](/decisions/ad-004.md)), and
+`noNodejsModules` in a Node CLI. Adopting that would have meant a config full of exclusions — the opposite of
+removing clutter — so the curated preset stays and the flag does the enforcing.
+
+**`--error-on-warnings` cannot see a rule that was suppressed instead of fixed.** Biome 2 requires text after the
+colon, so `biome-ignore lint/complexity/useIndexOf: needed` parses and says nothing. That is exactly the escape a
+stricter exit code creates pressure to use, which is why the checker ships in the same change rather than later.
+
+## Trade-offs
+
+**A prose rule enforced by a regex.** The checker cannot tell a real reason from four words that look like one. It
+raises the cost of a thoughtless suppression; it does not make one impossible.
+
+**`__test__` is scanned like everything else.** Excluding it would be the route around the rule. What keeps the
+comment-policy fixtures quiet is `isInComment`, which tracks the opening quote character rather than counting
+quotes — the first version counted, and reported three findings that were all string literals inside this project's
+own tests. A checker whose findings are noise is a checker somebody switches off, so it was calibrated against a
+deliberately injected suppression before being wired in.
+
+**Four words is arbitrary.** It was chosen because `why: needed` and `hazard: unavoidable` both pass a
+non-empty test and neither says what breaks.
+
+## Not decided here
+
+- **Whether biome's own unused-suppression diagnostic should also fail.** It is part of the recommended preset and
+  now fails through `--error-on-warnings`, so no separate decision was needed.
+- **Whether individual non-recommended rules are worth enabling one at a time.** `useConsistentTypeDefinitions`
+  (8 findings) would force `interface` on a codebase that uses `type` throughout; `noMagicNumbers` accounts for most
+  of the 3763. Neither was adopted and neither was excluded by name — the preset simply does not include them.
+- **Whether the same reason discipline should apply to `.mjs` and shell files.** The checker scans the tracked
+  TypeScript surface, which is where suppressions have appeared.

package/docs/decisions/ad-052.md

@@ -0,0 +1,69 @@
+---
+type: Decision
+title: "AD-052 — The repository moves to the org and the runtime paths do not"
+description: "The project moves to github.com/tech-leads-club/harness-toolkit. Only the identity layer changes — package name, repository URLs, installer source. The CLI, the runtime home and the project policy path stay exactly as AD-002 set them, because renaming those would re-initialise every install for no gain."
+tags: [decision, naming, install, delivery]
+timestamp: "2026-08-05"
+---
+
+# AD-052 — The repository moves to the org and the runtime paths do not
+
+- **status**: active
+- **date**: 2026-08-05
+
+## Decision
+
+1. **The repository is `github.com/tech-leads-club/harness-toolkit`**, superseding that one clause of
+   [/decisions/ad-002.md](/decisions/ad-002.md). The package is `harness-toolkit`.
+2. **Nothing else in AD-002 changes.** The CLI is still `tlc` with a `harness` subcommand group, the runtime home is
+   still `~/.tlc/harness/`, and the project source of truth is still `.tlc/harness/config.json`.
+3. **`felipfr/tlc-agent-harness` is frozen as it stands**, not archived and not amended.
+4. **While the repository is private to the org, the documented install fetches the script through `gh`**, because
+   `raw.githubusercontent.com` is unauthenticated and cannot read it. The public one-liner is documented alongside,
+   labelled for when it applies.
+5. **A clone that fails names the credential it needs** — `gh auth login`, `gh auth setup-git`, org membership —
+   rather than passing git's own error through.
+
+## Why
+
+**The paths stay because renaming them costs users and buys nothing.** `TLC` is Tech Leads Club, so `tlc` and
+`.tlc/` read as *more* accurate under the org than they did under one person's account. Changing them would move
+`~/.tlc/harness`, `TLC_HOME`, `.tlc/harness/config.json` — which is also the literal string the floor's
+`policy-surface-write` rule matches — and every already-initialised project would need a manual re-init. Two
+colleagues are mid-onboarding on the current layout.
+
+**The private phase is an install problem, not a code problem.** `install.sh` clones over HTTPS and works against a
+private repository as soon as git has a credential; what does not work is the *bootstrap*, because the one-liner
+fetches the script from `raw.githubusercontent.com` unauthenticated. `gh api …/contents/install.sh` carries the
+credential and reaches the same script, so both phases run identical code and going public later requires no change
+at all.
+
+**The old repository is left alone by choice.** It keeps its history, and it keeps receiving `tlc harness update`
+from every install that predates this move — silently, from a repository that has stopped moving. That is a known
+consequence: the affected installs have to re-run the installer against the new repository, and being told is the
+only mechanism, because a stale install cannot learn about a move on its own. This is the same shape as
+[/decisions/ad-048.md](/decisions/ad-048.md), one level up.
+
+## Trade-offs
+
+**Two install routes in the docs at once.** One of them does not work today and the other will not be needed later,
+and each is labelled with which. The alternative — documenting only the working one — means the public one-liner has
+to be reinstated in a later commit that nobody will remember to make.
+
+**`gh api … | base64 -d | bash` is not memorable.** It is also the only unattended route into a private repository
+that does not ask anyone to paste a token into a shell.
+
+**A frozen repository under a personal account still answers `git fetch`.** Anyone who never re-installs stays on
+the last revision it received, and the harness has no way to tell them so.
+
+## Not decided here
+
+- **Publishing to npm.** It would remove `curl | bash`, the clone, the private-repository problem and the committed
+  `dist/` in one move — and it replaces the update mechanism that AD-046 and AD-048 are built on, so it is its own
+  decision rather than part of a move.
+- **When the repository becomes public.** The docs carry both routes so the switch is a visibility change and
+  nothing else.
+- **Renaming the local working directory.** It is the operator's filesystem, and a runtime linked to it would follow
+  the rename only if the link is re-pointed.
+- **`projectName` in this repository's own `.tlc/harness/config.json`.** It still reads `tlc-agent-harness`. The
+  file is on the policy surface, so it is the operator's edit from a terminal ([/decisions/ad-022.md](/decisions/ad-022.md)).

package/docs/decisions/ad-053.md

@@ -0,0 +1,78 @@
+---
+type: Decision
+title: "AD-053 — The harness ships no model allowlist, and a list that names nothing enforces nothing"
+description: "An agent read `enforceAllowlist: true` with `allowedModels: []` and concluded that every model was blocked, then offered to switch the rail off. The list it was actually being refused by was shipped by the adapter and already stale. No adapter ships one now, an empty list enforces nothing, doctor reports that combination, and the refusal names the key it came from."
+tags: [decision, subagents, policy, defaults]
+timestamp: "2026-08-06"
+---
+
+# AD-053 — The harness ships no model allowlist, and a list that names nothing enforces nothing
+
+- **status**: active
+- **date**: 2026-08-06
+
+## Decision
+
+1. **`ProviderPolicyDefaults` no longer carries `allowedModels`**, and no adapter declares one. The effective
+   allowlist is exactly what the project configured.
+2. **An empty or absent list enforces nothing.** `enforceAllowlist` with no entries does not deny.
+3. **`doctor` reports that combination as a fault**, naming `subagents.allowedModels`, and is silent when the rail
+   is off or the list has entries.
+4. **The refusal names the key the list came from**, and says `inherit` is a value that list may contain when
+   `inherit` is what was refused.
+5. **`blockedPatterns` keeps its shipped `-fast` entries.** It is the opposite mechanism and stays.
+
+## Why
+
+The report came from another project, where an agent read:
+
+```json
+"subagents": { "enforceAllowlist": true, "requireModel": false, "allowedModels": [] }
+```
+
+and concluded that every model fell out, `inherit` and a `-thinking-high` variant included. It offered to set
+`enforceAllowlist: false`.
+
+The conclusion was wrong and the remedy would have switched off a rail. `effectiveAllowedModels` fell back to
+`provider.policyDefaults().allowedModels` whenever the project's list was empty, so the spawn was refused by a
+**shipped** list — three model slugs on Claude Code, five on Cursor — that appears nowhere in the project. The
+requested model genuinely was not on it, because that list had already gone stale.
+
+That a careful reader got it exactly backwards is the finding, not a footnote. The refusal said `Use one of: <list>`
+and named no source. An operator who opens their own config, sees `[]`, and is told a spawn was refused by an
+allowlist can only conclude that empty means none.
+
+**No shipped list at all** is the operator's decision, and it removes the cause rather than the symptom: a list the
+harness invents is a list that goes stale, and enforcing one nobody wrote is what made the message unreadable.
+
+**An empty list cannot deny**, because it says nothing about what is permitted. With the shipped fallback gone, the
+old code would have refused every spawn from a rule listing nothing — the behaviour the reader mistook for a bug,
+where they would have been right.
+
+**`inherit` is not a model name.** It means the parent's model, and before this the only occurrences of the string
+in this repository were `stdio: "inherit"`. It is now an ordinary value an operator may put on the list, and the
+refusal says so instead of answering with slugs.
+
+## Trade-offs
+
+**A project that relied on the shipped list loses it.** `enforceAllowlist: true` with no list now permits every
+model instead of the three or five the adapter named. `doctor` fails on exactly that state, which is the only
+signal available — a spawn cannot warn without denying, and denying is what this removes.
+
+**`-fast` protection is unaffected, and the asymmetry is deliberate.** `effectiveBlockedPatterns` concatenates the
+project's patterns with the adapter's rather than replacing them, so the `-fast` denial survives an empty project
+config. A blocklist that ships entries adds protection; an allowlist that ships entries invents a policy.
+
+**`doctor` gains a `fail` row that some projects will hit immediately.** It is a fault: a rail declared on and
+enforcing nothing is a claim of protection that is not being given.
+
+## Not decided here
+
+- **Resolving `inherit` to the recorded parent model and judging that.** More precise than treating it as a listable
+  value, and it is inference the operator did not ask for. `blockParentFast` already covers the case that makes
+  `inherit` risky.
+- **Whether the init skill should offer a starting list.** It asks; it does not propose slugs, because proposing
+  them is shipping a default one conversation later.
+- **Whether `requireModel` should default on.** Unchanged by this decision.
+- **Prefix or wildcard matching for model families.** `isModelAllowlisted` still matches exactly or on `prefix[`,
+  so `-thinking-high` needs its own entry. Widening the match is a separate question from who owns the list.

package/docs/decisions/ad-054.md

@@ -0,0 +1,98 @@
+---
+type: Decision
+title: "AD-054 — npm is the distribution, and a merged release PR is the only thing that publishes"
+description: "Distribution moves from a git clone of the repository to a published npm package. Release Please computes the version from Conventional Commits and opens a release PR; merging it tags, releases and publishes through npm trusted publishing, with no stored token and no bot commit on main. The runtime path does not move."
+tags: [decision, release, npm, distribution, ci]
+timestamp: "2026-08-07"
+---
+
+# AD-054 — npm is the distribution, and a merged release PR is the only thing that publishes
+
+- **status**: active
+- **date**: 2026-08-07
+
+## Decision
+
+1. **The product is published as `@tech-leads-club/harness-toolkit`.** The unscoped name was already taken on
+   npm by an unrelated package; the scope is the one `@tech-leads-club/agent-skills` already uses.
+2. **Release Please v4 computes the version** from Conventional Commits, which this repository already writes,
+   and opens a release PR. It writes no changelog — `skip-changelog` is set, and
+   [/decisions/ad-055.md](/decisions/ad-055.md) says where the changelog comes from instead.
+3. **Merging that PR is the release.** It tags, creates the GitHub Release, and only then does the publish job
+   run. An ordinary push to `main` publishes nothing. *(The clause making that merge a human approval is
+   superseded by [/decisions/ad-057.md](/decisions/ad-057.md): the bot merges it.)*
+4. **Publishing uses npm trusted publishing (OIDC).** No npm token exists anywhere — the workflow requests a
+   short-lived credential with `id-token: write`, and provenance is generated automatically from a public
+   repository.
+5. **The publish job rebuilds `dist/` and runs the full gate against the tag** before publishing.
+6. **No bot commits to `main`.** The one generated file a release touches is corrected inside the release PR.
+7. **The runtime path does not move.** `~/.tlc/harness` stays what hooks point at, and what holds `config.json`,
+   `flags/` and `state/` ([/decisions/ad-002.md](/decisions/ad-002.md),
+   [/decisions/ad-052.md](/decisions/ad-052.md)).
+
+## Why
+
+**A git clone is not a distribution channel, and this repository has the bug reports to prove it.** Two of the
+last five fixes were to the updater: a checkout that dirtied itself on rebuild and broke every later update
+([/decisions/ad-046.md](/decisions/ad-046.md)), and an updater unable to deliver its own fix
+([/decisions/ad-048.md](/decisions/ad-048.md)). Both are properties of running `git` against a user's machine.
+A registry has solved fetch, integrity and rollback already, and neither of those failures has an analogue in
+`npm install`.
+
+**Trusted publishing rather than a token, because the deadline is real.** npm is restricting tokens that bypass
+2FA — account changes in August 2026, direct publishing in January 2027 — so a token-based pipeline would need
+replacing within months of being built. OIDC also produces the provenance attestation for free, which is the
+artifact that says this tarball was built from this commit by this workflow.
+
+**A release PR rather than publish-on-merge.** semantic-release publishes on every merge to `main` with nothing
+in between. Release Please's PR is where the version bump and the rendered changelog are assembled before either
+reaches `main`, and it costs nothing to author because the commit convention is already in place. It was also
+where a human could approve; [/decisions/ad-057.md](/decisions/ad-057.md) removed that and the bot merges it,
+which leaves the PR doing the assembly job it was chosen for.
+
+**Changesets was the other candidate and lost on shape.** Its strength is monorepos and its cost is a third
+artifact per PR — a changeset file, alongside the commit message and the decision record. This is one package
+with a decision-record habit already. The pause it sells is a pause this repository already takes.
+
+**A breaking change stays in `0.x`.** Release Please bumps a breaking change straight to `1.0.0` by default,
+even from `0.1.0`, so a single `feat!:` would have declared this product stable on its first release.
+`bump-minor-pre-major` turns that into a minor bump. Going to `1.0.0` becomes a decision someone makes, which
+is the only way it can mean anything.
+
+**Version numbers are now a promise, and the number stays below 1.0.0.**
+[/decisions/ad-003.md](/decisions/ad-003.md) declined backward compatibility and declined a version for exactly
+that reason. A registry requires one. `0.x` is the honest encoding of that stance: it is a version without a
+compatibility promise, which is what AD-003 said this product offers.
+
+## Trade-offs
+
+**Publishing makes the source public, whatever the repository's visibility.** The tarball is world-readable, so
+the decision to publish is the decision to open the code. Provenance additionally requires a public repository,
+so publishing from a private one silently drops the attestation — the one thing the pipeline exists to produce.
+
+**The licence does not become permissive.** PolyForm Noncommercial 1.0.0 is a valid SPDX identifier and npm
+carries it, but a package on a public registry will be installed by people who never read it.
+
+**Two things must be done by hand, once, and the pipeline cannot do them.** A trusted publisher must be
+configured on npmjs.com naming the organisation, the repository and `release.yml`, and the repository must be
+public for provenance. A configuration created after 20 May 2026 must also state explicitly which operations it
+permits.
+
+**The version becomes a thing that can be wrong.** A `fix:` commit that changes behaviour ships as a patch and
+says compatibility held when it did not. The gate does not check this and nothing here proposes that it could.
+
+**`dist/` is now built twice** — committed for the Node fallback path and rebuilt in the publish job. The
+duplication is deliberate: `check-dist-fresh` proves the committed bundles match `src/`, and a release is the one
+moment where building again costs nothing and removes the question.
+
+## Not decided here
+
+- **How an existing install migrates.** Two things were measured as wrong for the npm route: `doctor` reported
+  `not a git checkout` as a failure, and the runtime cache was written inside the package directory npm replaces
+  on update. Both are settled in [/decisions/ad-056.md](/decisions/ad-056.md).
+- **Whether to publish a library entry point.** Nothing is exported for programmatic use. The package is a CLI
+  and a runtime; `src/` ships because Bun executes it directly, not as an API.
+- **Prereleases and dist-tags.** No `next` channel, no beta flow. One tag, `latest`.
+- **Signing beyond provenance.** Provenance attests the build; it is not a signature over the contents by a key
+  this project holds, and key management stays out of scope for the same reason
+  [/decisions/ad-028.md](/decisions/ad-028.md) declined it for attestations.

package/docs/decisions/ad-055.md

@@ -0,0 +1,74 @@
+---
+type: Decision
+title: "AD-055 — The changelog is rendered from the decision records, and git says which release each landed in"
+description: "CHANGELOG.md is generated from docs/decisions/ rather than from commit messages, and the mapping from decision to version is read out of git rather than recorded anywhere. Release Please writes no changelog. The gate fails when the file drifts."
+tags: [decision, release, changelog, docs]
+timestamp: "2026-08-07"
+---
+
+# AD-055 — The changelog is rendered from the decision records, and git says which release each landed in
+
+- **status**: active
+- **date**: 2026-08-07
+
+## Decision
+
+1. **`CHANGELOG.md` is generated** by `tools/render-changelog.ts` from `docs/decisions/ad-*.md`. It is not
+   edited by hand and Release Please does not write it (`skip-changelog: true`).
+2. **Which release a decision landed in is read from git** — the commit that added the file, and the tag whose
+   range contains it. Nothing records it, so nothing can disagree about it.
+3. **A `migration:` note becomes a "Needs your action" line.** Everything else is a title.
+4. **`node tools/render-changelog.ts --check` is a gate step**, so the file cannot drift from the records.
+5. **`--release <version>` renames the pending section**, and the release workflow runs it inside the release
+   PR so the merged commit already carries the final document.
+
+## Why
+
+[/decisions/ad-031.md](/decisions/ad-031.md) already decided that the substance of a changelog exists here as
+decision records — each carrying why, the trade-offs and what was refused — and that a second index would be a
+thing to maintain and a thing that can go stale. Publishing to a registry does not change that; it only adds a
+requirement that the document exist as a file.
+
+**Commit messages describe the commit; decision records describe the decision.** Generating from commits would
+produce a list where `fix(lessons): the migration line names the file the old boolean is actually in` is an
+entry, which tells a reader nothing they can act on. The decision record for the same change says what changed
+and what it costs.
+
+**The decision-to-version mapping is already in git.** Writing a version into each record's frontmatter would be
+the second index AD-031 refused, and it would be hand-maintained at exactly the moment — cutting a release —
+when nobody is looking at it. Walking the tag ranges answers the same question from the thing that cannot lie.
+
+**`--release` exists because the release PR bumps the version before the tag is created.** Without it, the first
+push after every release would fail its own `--check`: the file on disk would say `Unreleased` while a
+regeneration, now seeing the tag, would say `v0.2.0`. A test asserts the two renderings are byte-identical, so
+this stays true rather than being a claim in a comment.
+
+**And `--check` accepts two renderings, because the merge commit is a real window.** `ci.yml` and `release.yml`
+both fire on a push to `main` and run in parallel, so on the commit that merges a release PR the gate reads a
+document naming `v0.2.0` while the tag is still being created in the other workflow. A plain comparison would
+fail there on every release, on a file that is already correct. The tolerance is exactly one state and closes on
+its own: the pending rendering is accepted only while no tag of that name exists, so it cannot hold a stale file.
+A mutant that removes the closing condition kills a test.
+
+## Trade-offs
+
+**A change with no decision record is invisible in the changelog.** That is the intent — a change worth telling
+users about is worth a record — but it means a bug fix that warranted no record leaves no trace here. The commit
+history remains the complete account; the GitHub Release carries Release Please's own commit-derived notes for
+anyone who wants them.
+
+**The first release lists every decision at once.** Fifty-odd entries under one version, which AD-031 argues is
+the same as no message. It is accepted for exactly one release: subsequent ones carry the handful that landed.
+
+**Generating from git makes the tool require git.** It shells out to `git log` and `git tag`, so it runs in a
+checkout and not from an unpacked tarball. It is a build-time tool and never runs in a hook, so the latency rule
+that governs the runtime does not reach it.
+
+## Not decided here
+
+- **Grouping entries by kind** (feature, fix, security). Decision records carry tags and none of them is a
+  release-note category; inventing one would be a second taxonomy.
+- **Linking each entry to its pull request.** The record links to the code it decided about, which is the more
+  durable pointer.
+- **Rendering the changelog for other products.** The harness deliberately reads no project's documentation
+  convention ([/decisions/ad-035.md](/decisions/ad-035.md)); this tool is this repository's, not a feature.

package/docs/decisions/ad-056.md

@@ -0,0 +1,85 @@
+---
+type: Decision
+title: "AD-056 — The package delivers the runtime, and the runtime path stays where hooks already point"
+description: "npm becomes the install route. The published package is a delivery vehicle: `tlc harness install` materialises the code at ~/.tlc/harness, which keeps config.json, state/ and flags/ out of a directory npm replaces. Update bumps the package and re-materialises; no git command runs against an npm-delivered runtime."
+tags: [decision, install, update, npm, runtime]
+timestamp: "2026-08-07"
+---
+
+# AD-056 — The package delivers the runtime, and the runtime path stays where hooks already point
+
+- **status**: active
+- **date**: 2026-08-07
+
+## Decision
+
+1. **`install.sh` installs the package globally and then runs `tlc harness install`.** The clone route stays,
+   and the installer falls back to it — with a line saying so — whenever npm cannot deliver.
+2. **`tlc harness install` copies a declared payload** from wherever the package sits into `~/.tlc/harness`.
+   Each entry is replaced wholesale, so a file deleted upstream does not survive. Nothing outside the payload
+   is touched, which is what keeps `config.json`, `state/` and `flags/` the operator's.
+3. **The runtime path does not move** ([/decisions/ad-002.md](/decisions/ad-002.md),
+   [/decisions/ad-052.md](/decisions/ad-052.md)). Hooks keep naming `~/.tlc/harness/bin/tlc-exec.mjs`, so the
+   hot path never resolves anything.
+4. **An npm-installed launcher defers to that runtime** when one is installed there, and runs from the package
+   only while it is not — the package has to be able to run itself in order to install anything.
+5. **`runtimePathKind` gains `npm`**, told apart by a marker the installer writes rather than guessed from the
+   contents. `doctor` reports it as `ok`; `update` bumps the package and re-materialises, and runs no git
+   command against it, for the same reason it runs none against a linked clone.
+6. **The runtime cache is never written into a packaged copy**, and an unwritable home degrades to probing
+   rather than throwing.
+
+## Why
+
+**A directory npm owns cannot hold state.** `npm install -g` replaces the package directory, so the global
+lesson tier, the cross-repository spool and the runtime cache would be deleted by an ordinary update. This was
+measured, not predicted: the first packed tarball wrote `runtime-cache.json` inside the package on its first
+run, and `doctor` reported `FAIL runtime ownership — not a git checkout` on a perfectly healthy install.
+
+**Materialising beats splitting the paths.** The alternative was to teach the runtime that code and data live in
+different places — a change to `runtimeHome()`, the floor's protected paths, the lesson store, the spool and the
+policy loader, all on the hot path, on every machine that already has this installed. Copying four megabytes
+once per update buys the same correctness and touches one new file. The conflation of "where the code is" and
+"where the data is" was only ever safe because the runtime was a checkout the harness owned; the package
+restores that property instead of removing the assumption.
+
+**The marker, rather than inference.** A directory with no `.git` was classified `unmanaged`, which `doctor`
+calls a failure and `update` answers with "re-install with the one-liner". A directory can be many things and
+only whatever created it knows which, so the installer says so in a file.
+
+**The installer falls back rather than failing.** Before the first publish the package genuinely does not
+exist, and an installer that breaks because a future route is not ready yet is broken by its own roadmap. The
+fallback prints which route it took, so nothing is silent. This was caught by the existing test that pipes the
+installer the way the README documents.
+
+## Trade-offs
+
+**The code exists twice.** Roughly four megabytes in global `node_modules` and again under the runtime home.
+The duplication buys a stable path for hooks and a directory npm will not delete, and disk is the cheapest
+thing being traded here.
+
+**`~/.tlc/harness` can be stale relative to the installed package.** `npm i -g` alone does not update the
+runtime; `tlc harness install` does, and `tlc harness update` runs both. An operator who bumps the package by
+hand and stops there keeps running the previous runtime, and nothing currently reports that gap.
+
+**The npm-installed CLI is not the code that runs.** `tlc` resolves to the package's shim, which defers to the
+materialised runtime. That is the same relationship the git route has — the CLI runs whatever is at the runtime
+home — but it is surprising the first time.
+
+**One env var of coupling.** `TLC_ORIGIN` carries where the launcher physically lives, because the resolved home
+is no longer that. `TLC_HOME_FROM_ENV` distinguishes an operator's choice from the launcher's own resolution,
+and it is derived once by the outermost launcher and inherited after that: deriving it twice made the nested
+invocation read the parent's `TLC_HOME` as a choice and install the runtime on top of itself. Measured against
+the packed tarball, and now asserted.
+
+## Not decided here
+
+- **Reporting a runtime older than the installed package.** `doctor` could compare the two `package.json`
+  versions and say so. Worth doing; it is a check, not a distribution decision.
+- **Removing the git route.** It stays for contributors and for anyone already on it. Whether it is eventually
+  retired depends on how the npm route behaves in the field.
+- **A postinstall script.** It would remove the second command, and `--ignore-scripts` is common and postinstall
+  scripts are exactly the supply-chain surface this project should not add to.
+- **Windows.** `install.ps1` is unchanged and still clones. The CLI half works — `bin/tlc.mjs` is why the
+  published entry points are `.mjs` rather than the shell wrappers — but the installer is not converted and
+  neither is CI's coverage of it.

package/docs/decisions/ad-057.md

@@ -0,0 +1,68 @@
+---
+type: Decision
+title: "AD-057 — The release PR is a mechanism, not a gate, and the bot merges it"
+description: "Publishing is unattended. Release Please still opens a release PR, because that is where the version bump and the rendered changelog are assembled, and the release bot merges it as soon as they are. Supersedes the human-approval clause of AD-054."
+tags: [decision, release, ci, npm]
+timestamp: "2026-08-07"
+---
+
+# AD-057 — The release PR is a mechanism, not a gate, and the bot merges it
+
+- **status**: active
+- **date**: 2026-08-07
+
+## Decision
+
+1. **The release is unattended.** A merge to `main` carrying a `feat:` or `fix:` reaches npm with no human
+   step. This supersedes item 3 of [/decisions/ad-054.md](/decisions/ad-054.md), which made merging the release
+   PR an approval.
+2. **The release PR stays**, because it is where the version bump and the changelog rendered at the pending
+   version are assembled. A `merge` job merges it once the `changelog` job has committed into it.
+3. **`--squash --auto` first, direct merge as the fallback.** Auto-merge waits for the required checks; a
+   repository with none, or with auto-merge disabled, gets the direct merge. Which one happened is printed.
+4. **The publish job carries `environment: publish`.** Empty, it changes nothing. Given required reviewers it
+   becomes an approval again, without touching any code.
+
+## Why
+
+**The operator asked for it, having been told the cost, and restated it.** That is the whole of the reason,
+and recording it as anything else would be dressing up someone else's call as an engineering finding. The
+sibling repository `agent-skills` already publishes this way, and one product in an organisation releasing by
+hand while the other does not is a difference nobody chose.
+
+**Merging beats replacing the PR flow.** The alternative was to publish directly from `main` the way
+`agent-skills` does — compute the version, commit the bump, tag and publish in one run. That discards the
+changelog-in-PR mechanism ([/decisions/ad-055.md](/decisions/ad-055.md)) and puts the bot's bump commit on
+`main` from a workflow rather than through a reviewed branch. Merging a PR the bot opened costs one job.
+
+**It terminates, and that is a property rather than a hope.** The merge is a push to `main`, which runs the
+workflow again; that run finds the merged PR, creates the tag and the release, and the publish job runs off it.
+A third run finds no releasable commit — the changelog commit is `docs(...)`, which is not a releasable type —
+so no PR is opened, the merge job is skipped, and nothing re-triggers.
+
+## Trade-offs
+
+**A bad release reaches other people's machines with nobody having looked.** This runtime installs itself into
+editors and writes their hook files. Two defences remain and neither is review: the full gate runs against the
+tag inside the publish job before `npm publish`, and CI runs on the release PR before the merge — which works
+only because the App token opens it, since a PR opened with `GITHUB_TOKEN` triggers no workflows.
+
+**The fallback merges without waiting for checks.** `--auto` needs required checks configured on `main`; with
+none, there is nothing to wait for and the direct merge is what happens. Configuring CI as a required check on
+`main` is what turns that branch off, and it is a repository setting rather than a change here.
+
+**Recovering a failed publish is manual.** If the gate fails inside the publish job the tag and the GitHub
+Release already exist and npm does not. Re-running the whole workflow does not help — `release_created` is
+false on a second pass — so the recovery is "Re-run failed jobs", which preserves the upstream outputs.
+
+**The version is now decided entirely by commit messages.** A `fix:` that changes behaviour ships as a patch
+and says compatibility held when it did not. Nothing checks this, and with the human step gone there is no
+longer a moment where someone would notice.
+
+## Not decided here
+
+- **Required checks on `main`.** A repository setting that would make the auto-merge path the real one. Worth
+  doing; not a code change.
+- **Reviewers on the `publish` environment.** The hook is in place and deliberately empty.
+- **A cool-off or a `next` dist-tag.** One channel, `latest`, published immediately
+  ([/decisions/ad-054.md](/decisions/ad-054.md)).