docs: prepare 2.0.0 (changelog, upgrade guide, quickstart check)

[stackbilt-admin]

Docs-only prep for 2.0.0. No version bump, tag, publish or release.

Changelog restructuring

## [Unreleased] keeps its heading and is now organized as a Breaking: lead, then ### Added, ### Changed and ### Fixed. Each user-visible change has one bullet, with nested sub-bullets where it needs them. The section goes from about 6,560 words to about 4,990.

• Amending entries are folded into the final behaviour: feat(hook): pre-commit tidies only staged vendor files (#318 4/6) #356 and hook: doctor gate blocks commits on bloat in files that aren't part of the commit #357 into one hook bullet, feat(adf)!: compile and tidy read the vendor mode record (#318 2/6) #352/feat(adf): doctor, score and bootstrap read the vendor mode record (#318 3/6) #353/feat(adf): compile preserves retained sections (#318 5/6) #358/feat(adf): rename legacy agents.md safely (#318 6/6) #359 into the compile/check/tidy/restore bullets, and bug(adf compile): refuses to overwrite the vendor files bootstrap just generated, requiring --force on first compile #295 into adf compile: preserve retained sections instead of only refusing on them #303 (retained block) and adf: no repo records whether vendor files are compiled or pointers, so compile --check and tidy disagree forever #318 (--mode compiled). The duplicate ### Changed heading is gone.
• The Breaking lead is now written against 1.9.3. The old lead described the unreleased bug(adf compile): refuses to overwrite the vendor files bootstrap just generated, requiring --force on first compile #295 state ("compile no longer replaces pointers"). I checked with npx @stackbilt/cli@1.9.3: 1.9.3 refused pointers and converted them only with --force. The real break is that --force no longer converts a pointer, and --target all --write now skips pointers with exit 0 (1.9.3 exited 1). The lead also covers bootstrap --force and the hook reinstall, and links the upgrade guide.
• Added three entries that were in git log v1.9.3..HEAD but missing from the changelog: bug: emit AGENTS.md (uppercase) — lowercase agents.md is not the convention and breaks on case-sensitive filesystems #297/fix(bootstrap): emit AGENTS.md instead of lowercase agents.md #301 (bootstrap writes AGENTS.md), bug(bootstrap): commits local telemetry and writes a machine-absolute path into .mcp.json #298/fix(bootstrap): gitignore telemetry and drop absolute path from .mcp.json #304 (telemetry gitignore and relative --ai-dir in .mcp.json), and chore(deps): patch advisories failing supply-chain:check #337 (supply-chain pins).
• refused-retained and retained-divergent never shipped in a release. They are now noted once as interim values from unreleased builds.

Claim checklist

Before rewriting, I extracted every distinct user-visible claim into a checklist (175 entries) and ticked each one against the rewrite:

• 153 covered as written.
• 6 folded into the final behaviour (superseded by a later PR in the same release).
• 4 added from the git log.
• 12 dropped on purpose:
  • Internal names: removeManifestBullet, POINTER_MARKERS/CHARTER_OWNED_MARKERS, completePhase.
  • Series narrative: "in this part no command acts on the record", "doctor/score unchanged until later parts", "adf: no repo records whether vendor files are compiled or pointers, so compile --check and tidy disagree forever #318 filed separately".
  • Statements a later PR in this release made false: "record problems only reported by vendor status" (doctor reports them now), and bootstrap --force fans out to several destructive operations and is advised as a routine remedy #305's "the flag itself is unchanged" (adf: no repo records whether vendor files are compiled or pointers, so compile --check and tidy disagree forever #318 changed bootstrap --force).
  • A few rationale clauses.

A check of 112 key tokens (statuses, flags, JSON fields, message text, numbers) against the new section found all of them. Status values and message strings were checked against adf-compile.ts, adf-tidy.ts, adf-vendor.ts, doctor.ts and hook.ts. For example, (replaced charter pointer stub) and git checkout -- are no longer in the code, so the final wording uses (mode: pointer -> compiled) and adf vendor restore.

Upgrade guide

New docs/upgrading-to-2.0.md, linked from the CHANGELOG Breaking lead and both READMEs. It covers:

• six copy-paste upgrade steps;
• --mode compiled and adf vendor set <file> compiled;
• adf vendor init and adf vendor status;
• reinstalling the pre-commit and commit-msg hooks;
• a table of the new doctor INFO/WARN rows and their fixes;
• rename-legacy;
• the retained block and the one-time retained-unfenced/retained-ambiguous reports;
• bootstrap --force;
• why score may rise;
• JSON and exit-code changes.

Other doc fixes:

• Root README: the "commit trailer normalization" row was stale (the hook is now a gate). Added rows for adf vendor status and the upgrade guide.
• packages/cli/README.md and docs/cli-reference.md: the migrate file list now says AGENTS.md (or legacy agents.md) instead of only agents.md.

Quickstart and upgrade-path results

I ran everything in throwaway repos under the session scratchpad, using the built binary in place of npx.

• Root README quickstart (score, bootstrap --yes, compile --target all --write --mode compiled): all steps exit 0. Four files report Written … (mode: pointer -> compiled), and compile --target all --check exits 0. doctor --ci reports WARN (gate enforcement) until bootstrap's printed next steps (hook install --pre-commit, --commit-msg) are run. After that it reports PASS, and a commit with a trailer goes through both hooks.
• CLI README quickstart (also the re-render compile --target all --write and adf vendor status): same results. Modes are recorded compiled, --check exits 0, and doctor reports PASS after the hooks.
• Upgrade from 1.9.3: I ran npx -y @stackbilt/cli@1.9.3 bootstrap --yes and committed with the 1.9.3 hooks in two variants. In the pointer variant, CLAUDE.md is a pointer with a hand-added ## Environment. In the compiled variant, the files were converted with 1.9.3's compile --write --force and ## Environment was appended. Then I followed the guide with the new build, packed and installed as the devDependency.
  • New doctor before upgrading: exit 1, from the existing gate-enforcement WARN now naming the old commit-msg hook. The new rows are INFO only: pre-commit hook, telemetry tracking, adf vendor mode inferred, and legacy-tracked.
  • The compiled variant reported [stale] … outside the retained block once. One --write fixed it (kept ## Environment).
  • Both variants ended with a clean tree, doctor --ci PASS, and compile --check exit 0.
  • My first draft of the guide said git add .ai/manifest.adf, and that left AGENTS.md (title rewritten by rename-legacy), the re-compiled CLAUDE.md and package.json uncommitted. The guide now says to start from a clean tree, untrack telemetry, and run git add -u. I re-ran both variants from scratch with the corrected guide.

Code issues found

1. Fixed by fix(hook): scope the doctor gate in verify:adf repos #365: the hook: doctor gate blocks commits on bloat in files that aren't part of the commit #357 scoped gate did not run in repos with a verify:adf script.
2. Fixed by fix(hook): scope the doctor gate in verify:adf repos #365: the hook ran pnpm by name.
3. Root charter --help lists charter doctor [--adf-only] only, without --ci, --format, --staged or --tidy-skipped. charter adf --help's tidy line shows [--print-paths] but does not describe it.

Review follow-up (7aca621)

An adversarial review asked for changes. Applied in 7aca621:

• The upgrade block now has seven steps:
  • step 2 untracks the telemetry log and replaces an absolute --ai-dir in .mcp.json;
  • the commit line inside the block carries the trailer;
  • step 4 states that re-running the hook installs is required.
• The CHANGELOG bug(bootstrap): commits local telemetry and writes a machine-absolute path into .mcp.json #298 entry records bootstrap's warning about a tracked .mcp.json that pins an absolute --ai-dir.
• "Exit codes that changed" gains the compile --check change for pointers (exit 1 in 1.9.3, pointer-ok exit 0 now). The two new-flag usage errors are moved out of that list.
• The doctor JSON row lists adf vendor mode as a new check.
• The rename-legacy follow-up git add is conditional.
• The @stackbilt/git trailer-parser change (trailers: parseTrailersFromMessage accepts a whitespace-only trailer value #340) is noted in the CHANGELOG and the guide.

I re-ran the guide's code block literally on two fresh 1.9.3 repos (pointer and compiled). Both end with a clean tree, a commit, doctor --ci PASS, --check exit 0, .mcp.json using .ai, and no tracked telemetry.

Final hook wording after #365 (59e087e)

This branch is rebased onto main @ 1e2268e. The CHANGELOG hook bullet, the upgrade guide's hook section and packages/cli/README.md now describe #365:

• The scoped charter doctor --staged gate runs first in every repo.
• Next comes verify:adf, run with pnpm, yarn or npm according to the lockfile and what is installed, or adf evidence when there is no such script.
• Inside the hook, verify:adf's doctor reports bloat as INFO (adf vendor bloat (checked by pre-commit hook)). Run by hand or in CI, it checks every vendor file.
• The CHANGELOG explains the CHARTER_HOOK_SCOPED_DOCTOR token and the notice the hook prints when it cannot write the token file.
• pre-commit hook INFO rows now cover hooks from the first hook: doctor gate blocks commits on bloat in files that aren't part of the commit #357 fix.
• The guide notes Yarn Plug'n'Play (hook: pre-commit gate fails under Yarn Plug'n'Play (npx charter can't resolve the PnP binary) #366) as a known limitation.
• No pnpm run verify:adf-only wording is left in current docs. The remaining mentions describe old hooks or old releases.

Tests

pnpm build and pnpm run verify:adf pass. pnpm test (after the rebase) gives 1446 passed and 3 failed, exactly the known Windows-only failures (bootstrap #307 fixture, context-refresh "captures git signals", serve-context "returns existing snapshot").

Release steps left for the operator

1. Bump versions to 2.0.0 (all packages/*/package.json).
2. Rename ## [Unreleased] to ## [2.0.0] - <date>.
3. Tag v2.0.0.
4. Publish to npm.
5. Create the GitHub release (the changelog's Breaking lead and the upgrade-guide link work as release notes).

🤖 Generated with Claude Code