# Changelog

## 2026-07-31 (a) - session ledger: multi-session coordination + the story that survives, cross-platform

Ships the RUN_STATE capability three features already depended on (build-workflow shard ids +
stageTimes, housekeep's active-run guard, METRICS "once RUN_STATE lands") and closes the
multi-session blind spot: concurrent Claude Code sessions on one checkout each believed they
were the single writer, and a session's plan/purpose/pending/decisions died with its
conversation. ONE zero-dependency Node implementation behind Claude Code hooks - identical on
Windows, macOS, and Linux (the manifest-hasher doctrine: no twin scripts to drift; thin guard
launchers only). Opt-in and feature-detected end to end: hooks not wired, or node absent, and
nothing changes.

### What landed
- **`templates/session-ledger.js`** - NEW, the single implementation. Subcommands mapped to hook
  events: `start` (SessionStart: create/reopen the per-session `docs/runs/RUN_STATE.<sid>.json`
  shard - sharded like METRICS, zero contention; the runs dir self-gitignores; closed shards
  auto-prune past retention - and inject a bounded orientation: STATUS top block, other
  ACTIVE/stale sessions + their claims, open approval-inbox decisions, the last session's
  handoff); `heartbeat` (UserPromptSubmit: silent liveness + ask capture; prints ONLY when a NEW
  foreign write-claim appears - once); `heartbeat --debounce` (PostToolUse on write tools:
  liveness during long autonomous turns; instant no-op under 60 s); `turn` (Stop, every turn:
  turn ledger + atomic `docs/STATUS.md` regeneration + the story gate - blocks AT MOST ONCE per
  session (Law 11), never when `stop_hook_active` is set, and only when real work signals exist
  with no journal narrative); `precompact` (snapshot asks before compaction compresses them);
  `close` (SessionEnd: mechanical envelope - asks, diff, boards touched, HEAD movement - appended
  to `docs/journal/<date>-session-<sid>.md`, so the skeleton survives a storyless close);
  `status` (standalone/CI); `stage <name> start|end` (real `stageTimes` for METRICS `durMin`);
  `claim <scope...>` (Law 3 made visible). STATUS is DERIVED - marker census re-counted from
  board rows, inbox + metrics-shard counts, sessions - stamped with the HEAD it was derived at,
  written atomically (rename + EPERM retry); a hook failure is never allowed to break the session
  it serves (every non-selftest path exits 0).
- **`templates/session-hook.sh` + `session-hook.ps1`** - guard launchers ONLY (no ledger logic -
  governance-asserted): exit 0 when node is absent; the .ps1 relays hook stdin via a temp file
  (5.1-safe). **`templates/settings.session.example.json`** - all six hook events wired
  (Windows form; the POSIX one-liner swap is documented). **`templates/SESSION_SETUP.md`** -
  event table, wiring per OS, bindings (`.claude/session-ledger.config.json`), claims, stage
  timing, stated limits (worktrees per-checkout; narrative quality is the model's duty).
- **`tools/SessionLedger.Tests.ps1`** - NEW kit-gate suite (auto-discovered): delegates to the
  script's built-in `selftest` (git-fixture sandbox proving shard lifecycle, orientation,
  heartbeat + debounce, the one-shot gate incl. `stop_hook_active`, conflict-warn-once, stage
  times, envelope, STATUS census, atomic-write hygiene); SKIPs cleanly when node is absent.
- **`skills/progress-reporting`** - the depth x kind contract gains **kind `session`**: the
  end-of-session story (purpose/ask - plan - done-with-evidence - Pending - Decisions to give -
  Handoff) filed into the SAME journal file the Stop gate names and the envelope lands in; no
  reports-index line; fixed headings so the ledger's orientation can excerpt Pending/Handoff.
- **Integration:** CONSTITUTION session-ledger paragraph (claims make Law 3 checkable; stale
  heartbeats expire; the journal joins the memory set); CLAUDE.master session-ledger bindings
  bullet; construct-help reads shards/journal/STATUS (an ACTIVE foreign claim LEADS the report; a
  `(no story)` close surfaces under Decisions; a stale STATUS stamp is flagged) with the standard
  degradation verdict; build-workflow step 7 stage-timing bracket; METRICS_README's two
  "once RUN_STATE lands" clauses resolved; **housekeep.ps1 `RunStateGlob` fixed** from
  `docs/APPROVAL_INBOX/` (a location nothing ever wrote - the guard could never trip) to
  `docs/runs/`; BOOTSTRAP prereq + tree + opt-in hooks row; SPECIALIZE optional-capability
  section + glossary row; README + SKILLS catalog rows.
- **Installer/cleanup parity + governance:** both bootstraps install the five templates + the
  test suite (chmod +x on the POSIX launcher), seed `docs/journal/`; both cleanups remove them
  (`docs/journal` joins the empty-dir pass). Governance.Tests gains the session-ledger
  inventory, the F0 install/cleanup assertions, the launcher no-twin-logic guards, the
  RunStateGlob alignment check, and the session-kind registration checks.
- **Known gap, named not hidden:** cleanup parity for the (g)-era housekeep/metrics/governance
  tool files predates this release and remains open (the deferred reliability bundle's F11);
  this release adds cleanup lines only for its own files.

## 2026-07-30 (a) - progress-reporting: findings that outlive their session

**New skill (`skills/progress-reporting/`)**
- Dated, immutable progress snapshots: the 11-section structure, the depth x kind contract,
  and 10 discipline invariants each stated with its rationale.
- `REPORT_TEMPLATE.md` ships the skeleton with every project value as a placeholder.

**New command (`commands/progress-report.md`)**
- Thin dispatcher: orient -> Part A -> optional Part B fan-out -> file one snapshot plus one
  index line -> recommend the next action.
- Writes exactly one artifact. Proposes board rows and files none, so single-writer holds.

**completeness-sweep Part A: six checks -> eleven**
- A7 measured tests (a copied count drifts as fast as a fabricated one) - A8 corpus ground
  truth (a directory of ignored build residue is not a built unit) - A9 graph freshness -
  A10 metrics written (an empty store makes the retry-graduation trigger inert) - A11 kit and
  contracts drift.
- A9/A10/A11 degrade to 'n/a - not configured in CLAUDE.md' rather than failing: four commands
  share this skill, and not every project binds those capabilities.
- construct-help gains the same five as C7-C11.

**CONSTITUTION sections 9 and 10**
- A phase-exit gate files a snapshot as its evidence artifact; a transition approved with no
  snapshot is a self-attestation (Law 6).
- Dated snapshots named as the fifth memory companion beside the trio and metrics.
- Wiring gate hardening GRADUATED from a project override into kit source (generic): a mutating
  CTA must prove a write-path round-trip with VALUE IDENTITY (the value read back is the value
  the user entered, not merely that something persisted); no mutating command may be dispatched
  with a hard-coded fixture, placeholder literal, or freshly-minted identifier in a field the UI
  appears to capture; and the affordance ledger extends beyond controls to DISPLAYED VALUES,
  because a fabricated value with no control behind it is invisible to a control-only ledger.

**Verify-KitInstall: declared overrides were reported STALE (blocking fix)**
- The manifest hashes the INSTALLED file, so a declared override still matches the manifest and
  fell through to the OK/STALE branch - leaving the override test unreachable. Every declared
  divergence printed "kit source moved ahead - re-bootstrap", whose remedy (-Force) would have
  overwritten the very divergences the ledger exists to protect. The override test now runs
  FIRST, ahead of every other classification.

**Governance.Tests: the degradation assertion split three ways**
- One file-wide match for 'not configured in CLAUDE.md' let any single check's degradation
  clause be deleted while its two siblings kept the gate green. Now asserted per check, within
  each check's own section, with a message naming the check that lost its clause.

**Motivation**
- Two projects on this kit independently grew the same missing artifact, and two of the five
  new checks caught real gaps during scoping: a code graph four days behind the newest merge,
  and a metrics store never written after 22 sweeps.

## 2026-07-22 (r) - completeness-sweep: gates that can see an absence; boards proved, not trusted

A project reported "Reconstruction 37/37 ✅" for eight days across two phase gates while **ten screens were
missing an authored prototype branch entirely** (a whole create-modal body, a document artifact, an evidence
pane, two detail views, two run-detail branches, a signed-state variant, a composer flow, a settings flow).
Every gate passed. None could have failed: the phase-2 gate samples the **default render**, and an
unreproduced conditional renders as a perfectly clean page — build-clean, stylesheet-applied,
computed-styles-match, values-not-literals, interactivity-works all hold on a screen that is missing a modal.
The miss was found by a human noticing that the tester's manual listed incomplete work no board tracked.

Two blind spots, both structural, both now closed:

- **A gate that samples the default render cannot see a branch that was never written.**
- **A dashboard that re-prints a board faithfully re-prints its errors** — and is most confident exactly when
  it is most wrong.

- **New skill.** `skills/completeness-sweep/SKILL.md` (pristine + installed). Two depths, one question.
  **Part A — board integrity:** six cheap mechanical checks that independently re-derive every number a
  tracker asserts (C1 arithmetic · C2 corpus-vs-registry, including the **route-less surfaces** a
  route-counting registry cannot see · C3 **branch coverage** · C4 marker census · C5 staleness of derived
  prose · C6 backlog charter). **Part B — corpus completeness:** the four-class taxonomy (reconstruction gap /
  wiring gap / data-seam / design gap) gated by the **prototype-anchor entry test**, so each finding routes to
  the board that owns it — misfiling a reconstruction gap as a design gap commissions a redesign that
  overwrites the contract (Law 1). Also names the two honesty defects that outrank severity ordering (an input
  captured then silently dropped; a real write over unmarked fixture data), the write-findings-never-fix rule,
  and the Law-6 gate-amendment loop.

- **`CONSTITUTION.md` §9 — the root fix (root + kit managed pair).** The **reconstruction gate** gains a
  **state-coverage** clause: the screen's design source is enumerated for every conditional branch and the
  state key driving it, and the reconstruction reproduces one branch per key or justifies it out of scope; the
  **branch ledger** — not the screenshot — is what the orchestrator gates the registry flip on. A new standing
  caveat, **"what a gate cannot see"**, applies to all gates: each is a *sample*, blind to whatever it does not
  enumerate; a defect surfacing inside a passed gate's stated scope is **the gate's defect**, amended in the
  same pass (Law 6); completeness is proved against the corpus, never the trackers.

- **`CONSTITUTION.md` §10.** New rule — **derived state expires; rows do not.** Roll-ups, totals, working sets
  and "next / blocked" prose are the part no sweep re-reads, so they rot while their rows stay correct:
  recompute from rows at every integration, keep row + derived edits atomic, date-stamp status prose.

- **`agents/screen-reconstructor.md`.** New pre-build step — enumerate the source's state keys, discard
  logic-only and out-of-surface keys with line evidence, build one branch per in-scope key. The branch ledger
  joins the fidelity gate and the structured report contract; an unbuilt, unjustified key is a **Blocked**.

- **`commands/reconstruct.md`.** The orchestrator now gates the `✅` flip on the ledger and **spot-checks it
  against the source** (the agent's own enumeration is the thing under test), recording the key count in the
  registry note so a later sweep can re-check cheaply.

- **`commands/construct-help.md`.** Promoted from "report the boards" to "**audit the boards, then report**".
  New **§0 Board integrity** runs Part A's six checks *before* the five report sections; a tripped check
  **leads** the report, and the recommended next action becomes closing that gap rather than advancing a phase
  — *a phase gate evaluated against a board known to be wrong is not a gate.* Phase-2 detection now additionally
  requires clean branch coverage. New invariant: never present a board number you did not re-derive or mark
  unverified. Also learns the **build-backlog** board (design-already-exists work) alongside the design backlog,
  and surfaces honesty defects into "Decisions to be made". Still strictly read-only.

- **Docs.** `SKILLS.md` + `README.md` register the new skill. No bootstrap change — skills install by directory
  glob and commands by file glob, so `completeness-sweep` installs with no script edit.

## 2026-07-06 (q) - /design-sync: full-executor prototype-drift remediation command

The `design-sync` agent (drift triage → routed re-sync plan) had no command to dispatch it, present its
plan, and execute that plan as single writer — the orchestration role `/journey-audit` plays for
`journey-auditor` and `/edge-audit` for `edge-auditor`. The advisory brain existed; the motor did not.
This adds it. `/design-sync <all | ModuleCode… | route… | plan-file>` dispatches the agent(s), presents the
NEW/MODIFIED/REMOVED/UNCHANGED drift table at ONE checkpoint, then as single writer executes the whole routed
plan — cosmetic/structural nudges through the reconstructor's **re-sync mode** (wiring preserved),
contract-affecting changes through `spec-architect` + dependent-workflow re-enrich (+ `module-wirer` where the
contract surface moved), NEW screens through `reconstruct-sweep`, REMOVED screens to a **human decision** —
and closes with a post-execution `/journey-audit` over the flagged journeys (drift is not adopted until the
continuity ledgers are green). Full executor, not read-only: the drift-remediation sibling of `/build-workflow`,
distinct from the read-only `/design-help` / `/design-full-sweep` sweeps.

- **New command.** `commands/design-sync.md` (pristine + installed). Thin router + single writer; reuses the
  `design-sync` agent, the reconstruction command's re-sync mode, `spec-architect`, `module-wirer`, and
  `/journey-audit` unchanged. Concurrency ≤ the wave cap; never runs beside an active `/build-workflow` /
  `/build-wave` (both single-write the registries). REMOVED screens and `Contracts`-surface changes are
  human-gated by construction; no auto-delete.
- **Docs.** `CONSTITUTION.md §7` "Prototype drift" now names `/design-sync` as the execution wrapper (root +
  kit, byte-identical managed pair); the `README.md` commands list and the project `CLAUDE.md`
  agent-roster + reference-map are updated.
- **No new tooling / no bootstrap change** — commands install by glob; no agent, skill, or hook added.

## 2026-07-06 (p) - /design-full-sweep: composite three-altitude prototype audit

A new standalone command that unifies the three prototype-honesty sweeps behind one module-scoped
entry point. It fans out `spec-researcher` (triage), `journey-auditor`, and `edge-auditor` READ-ONLY,
merges their findings across all three altitudes — screen existence, between-screen continuity,
within-screen affordance honesty — into one severity-ranked per-module report, and as single writer
files backlog rows + design-sync handoffs at a single checkpoint. Prototype micro-edits are DEFERRED
to `/journey-audit` and `/edge-audit` (the report names the follow-up command per finding). Thin
router: re-implements no audit logic, dispatching the same advisory agents the individual sweeps use.

- **New command.** `commands/design-full-sweep.md` (pristine + installed). Usage
  `/design-full-sweep <ModuleCode… | all>`. Read-then-file only; single writer; concurrency ≤ the wave cap.
- **No new tooling / no bootstrap change** — commands install by glob; the command reuses the existing
  agents, the `journey-continuity-audit`/`dead-edge-audit`/`design-prompt-authoring` skills, and the
  design-backlog + design-sync + interaction-registry mechanisms unchanged.

## 2026-07-06 (o) - durable-identity guard: restart-safe server-assigned IDs across the build stack

Closes a class of "green suite, latent bug" the verification stack was structurally blind to: a
**process-static / in-memory counter minting a server-assigned identifier** (record/order/invoice/claim
no.). It resets to its seed on every app restart and knows nothing of persisted
values, so the first mint after a restart re-issues an already-saved value → duplicate-key on the unique
index. It passed EVERY test — unit on EF InMemory (no unique index/sequence), integration on
Testcontainers (fresh DB, one process lifetime), e2e (one running instance) — because the failure only
appears at the seam BETWEEN two process lifetimes sharing one durable database, a dimension no test
exercised. Generic method improvement; agents + the .NET detector pack.

- **Reviewer FAIL rule (§5 persistence boundary).** Every server-assigned business identifier must come
  from a durable, atomic, restart-safe source (a SQL `SEQUENCE` via an injected allocator port, or an
  identity column), never a process-static/`Interlocked` counter or `MAX(col)+1`; the generated range
  starts strictly above every seeded value; a "TODO: replace with a real sequence" in a persistence path
  is a FAIL, not a comment.
- **test-engineer — the missing test dimensions.** (1) Persistence-invariant NEGATIVE path: every unique
  index / sequence / check constraint / concurrency token / FK gets a RealSql test that makes it FIRE (a
  constraint never exercised to failure is decorative; InMemory enforces none). (2) RESTART-SIMULATION:
  anything minting durable state gets a test that disposes the allocator/context, re-creates it against
  the SAME migrated DB, and mints again → assert monotonic + no collision. New known-trap: EF InMemory is
  a false friend for persistence invariants, and a fresh-DB Testcontainers test cannot see a restart-reset
  defect.
- **backend-builder — prevention at birth.** Source durable IDs from a SQL `SEQUENCE` (`HasSequence` in
  the model — the signal migration-engineer migrates) behind an injected `I<X>Allocator`; keep it behind
  an interface so InMemory unit tests fake it and a RealSql test proves the sequence + restart-safety.
- **.NET detector pack.** `Test-StaticIdentityCounter` — flags a `static` numeric field mutated by
  `Interlocked` (a process-static counter) and a load-bearing "SELECT NEXT VALUE FOR"/"resets on restart"
  persistence TODO. WARN-level heuristic; poison + no-false-positive self-tests added.

Pristine kept fully generic (leak-free). Manifest graduated for the edited `.claude/agents` files; one
detector + two fixtures added to `scripts/preflight/dotnet-pack/`.

## 2026-07-06 (n) - create-vs-edit initial-state contract: the phantom-prefill guard across the audit stack

Closes a taxonomy gap surfaced in the field: a **create/new/register/add form that opens pre-filled
with a sample record** passed every existing check. The "show mock data at full fidelity" convention +
1:1 reconstruction propagate a phantom-prefilled create form from prototype → build, and no layer
encoded the **create-vs-edit initial-state contract** — a create form's true initial state is *blank*;
the failure is the **inverse** of context-loss (context present that must be absent) and renders
identically to a valid edit form, so pixel / handler / visual-1:1 checks all pass it. Generic method
improvement; skills + agents + the .NET detector pack.

- **The contract — `formMode`.** `contract-sidecar` gains `formMode: create|edit|view|none` — the single
  field every downstream check keys off. `create` opens empty (placeholders + system-proposed defaults
  only, never a record-identifying value; the mock-data convention is exempted for a create form's field
  VALUES); `edit` opens bound to the carried subject.
- **Prototype audit — the phantom-prefill tell.** `dead-edge-audit` (Step-1 tells + the taxonomy law) and
  `edge-auditor` gain a `phantom-prefill` tell; `journey-continuity-audit` (Phase 2 + CONSOLE_PROMPT) and
  `journey-auditor` gain the create-form-opens-empty check (the inverse of Phase-0 `WRONG` context-loss).
- **Build gate — 1:1 is overridden for create-form values.** `screen-reconstructor` reproduces layout/
  placeholders 1:1 but initializes a `create` model empty (never copies the prototype's sample values);
  `reviewer` adds a create-vs-edit FAIL criterion (read the form model's default values).
- **.NET detector pack.** `Test-PhantomPrefillCreateForm` — flags a `*Form`/`*Model` create class with a
  record-identifying (PII-named) string property defaulted to a non-empty literal. The PII set omits
  system-proposed values (proposed id, Country, Status, dates, dropdown defaults) so those never
  false-positive; WARN-level heuristic; poison + no-false-positive self-tests added.

Pristine kept fully generic (leak-free); the live install binds prototype/form idioms via `CLAUDE.md` at
runtime. Manifest graduated for the edited `.claude/{skills,agents}` files; one detector + two fixtures
added to `scripts/preflight/dotnet-pack/`.

## 2026-07-06 (m) - design-builder: globally-competitive design bar + self-critique loop + safety-keystone

Raises the ceiling of the in-repo design lane after a side-by-side (a console-lane render read
richer than the in-repo `design-builder` output for the SAME brief and model — a process gap,
not a model gap). Generic method improvement; agents/design-builder.md only.

- **The bar — globally-competitive design.** New section: aspire to the market-leading product in
  the project's domain (feature-parity north-star per `CLAUDE.md §1`) for workflow completeness,
  plus cross-industry craft exemplars (Linear, Stripe) and the project's own design-system
  templates — as IA / density / hierarchy / craft PRINCIPLES only, never a license to import
  another product's visual style or classes (Law 1; vocabulary stays closed, grep-verified).
- **Two-axis reference anchoring.** Vocabulary from the nearest same-module sibling; IA/density from
  the richest same-*archetype* screen in the corpus — a thin sibling no longer caps ambition.
- **Safety-keystone + decision-support rail.** Author step now elevates the fail-closed safety/
  compliance action as the visual keystone (own card + Required chip + dedicated CTA) and adds a
  live confirmation/summary rail where the archetype warrants one.
- **Self-critique → revise loop (≥1 pass).** New design step: score the draft render against an
  excellence rubric (safety-hierarchy · live-confirmation · decision-rail · density · states ·
  micro-copy) and revise before the sign-off shot — the iteration the console canvas gives for free.
  Structured report gains a `Design self-critique` attestation line.

Pristine kept fully generic (leak-free); the live install binds specifics via `CLAUDE.md` at
runtime. Manifest graduated for `.claude/agents/design-builder.md`; no tool files added.

## 2026-07-06 (l) - Verify-KitInstall honours -ProjectRoot/-KitSource (dot-source param clobber)

Governance defect in tools/Verify-KitInstall.ps1. Line 29 dot-sources New-KitManifest.ps1 for the
single-hasher/mapping implementation. New-KitManifest.ps1 carries its own `param([string]$ProjectRoot='.',
[string]$KitSource='',...)` block, and under PS 5.1 dot-source semantics that param block re-executes in
the caller's scope, re-initializing $ProjectRoot to '.' and $KitSource to '' - silently discarding the
values bound from the command line before Get-InstallFindings consumes them. Verify therefore always
audited the current working directory and never received a kit source, so STALE/CONFLICT detection was
dead. The bug was masked whenever cwd already equalled the intended target (the `cd project; Verify`
usage and the kit-gate self-test, which is why the gate stayed green), and bit only when -ProjectRoot
differed from cwd. Its worst consequence: bootstrap.ps1's -Force pre-upgrade drift check runs
`Verify-KitInstall.ps1 -ProjectRoot $Target -Strict` from a Start-Process whose cwd is the kit folder,
not $Target; Verify audited the kit folder (no manifest -> exit 0 -> "no drift"), so -Force proceeded to
clobber locally-modified managed files - defeating the very safety gate it exists to enforce.

- tools/Verify-KitInstall.ps1: capture $ProjectRoot/$KitSource into locals immediately before the
  dot-source and restore them immediately after (PS 5.1-safe; plain assignments only). -ProjectRoot and
  -KitSource are now honoured from any working directory; the -Force drift check STOPs on real drift.

No tool files added (bootstrap F0 guard unaffected); Manifest.Tests.ps1 is unaffected (it calls
Get-InstallFindings with explicit -Root/-Kit). Suites remain auto-discovered (8).

## 2026-07-06 (k) - F12 router alignment + preflight PS 5.1 git hardening

One release, three items landed together (letter-locked as a single (k) entry).

### F12: the construct-* router commands surface + dispatch the design loop

Alignment-audit finding F12, same class as F0 (a real capability the entry-point surface never
routes to). Examination of release (j) confirmed commands/construct-help.md contained zero
references to the design loop: it read the reconstruction backlog and the design-sync plan but
NOT the design-backlog board, its Backlogs section had no design-backlog line, and its
next-action menu could only ever recommend /construct-run or an approval-inbox file - so
"Needs Design" rows filed by /journey-audit, /edge-audit, /design-help, and sweep Checkpoint 1s
accumulated invisibly until a phase-5 sweep hit the missing screen reactively.
commands/construct-run.md had the same blindness (its phase table delegates only to
/reconstruct, spec-architect + spec-hardening, /build-workflow, /build-wave, test-engineer).
Everywhere else in the kit the lane is wired correctly (20+ cross-references verified:
CONSTITUTION.md, README zero-knowledge path, journey-continuity-audit + dead-edge-audit +
design-prompt-authoring skills, DESIGN_BACKLOG/DESIGN_PROMPTS templates, design-sync agent) -
the gap was exactly and only the two construct-* routers.

- commands/construct-help.md: (1) Sources-to-read now includes the design-backlog board + its
  design-prompts companion (paths per CLAUDE.md); (2) section 4 Backlogs gains a "Design
  backlog" line (count + Must-have subset + suggested lane; explicitly distinguished from the
  reconstruction backlog and from drift); (3) the next-action alternatives now derive
  "Design the next backlog screens (in-repo lane)" -> /design-build next|must-have via the
  design-builder agent when scaffold-conforming rows exist, and point console-lane rows at the
  design-prompts board how-to + /promote-design. Still read-only; still hands off all writing.
- commands/construct-run.md: a pre-routing rule after the phase table ("a unit with no
  prototype source is not a phase-2 unit" -> route through /design-build or console +
  /promote-design first; the dispatcher never designs screens), and the delegate-never-
  duplicate invariant now names the design loop's engines.
- tools/Governance.Tests.ps1: F12 regression guard (mirrors the F0 pattern) - asserts
  construct-help.md references design-builder, /design-build, and /promote-design, and
  construct-run.md references /design-build and /promote-design. The gap cannot silently
  return.

No tool files added (bootstrap F0 guard unaffected); suites remain auto-discovered (8).
The reliability bundle previously planned as (k) (A1 RUN_STATE + resume, F11 cleanup parity,
CONSTITUTION_NOTE fold-in, windows-latest CI) re-letters to (l) unchanged in scope.
Verification in the delivery container was by independent re-implementation (no PowerShell
there); this release is STAGED until tools/Kit.Tests.ps1 prints KIT GATE: PASS on the
user's Windows host.

### Hotfix 3: PS 5.1 native-git terminating-error crash in the preflight detectors

Third finding from the Windows validation run. On a host where the kit is NOT checked out as a
git repository, `tools/Kit.Tests.ps1` reported KIT GATE: FAIL (7 of 8 green); the `preflight
-SelfTestOnly` suite crashed before rendering a verdict. Root cause: the generic detectors invoke
native git (`git -C $Path ls-files`, `git check-ignore`) as `& git ... 2>$null`. Under
`$ErrorActionPreference='Stop'` Windows PowerShell 5.1 promotes a native command's stderr
(git prints `fatal: not a git repository` outside a work tree) to a TERMINATING NativeCommandError
even with `2>$null` - so the whole harness threw instead of degrading, where PS 7 would have
returned empty and continued. A second, latent occurrence of the same construct sat in
Test-IgnoreShadowsSource (two git calls) - it would have crashed the full real-tree scan on the
next line.

Fixed by elimination, not negotiation:
- Get-CompressedAssetPaths: new helper feeding Test-TrackedCompressedAssets. Runs git with the
  error preference localised to SilentlyContinue and branches on `$LASTEXITCODE`; when $Path is a
  real git work tree the git branch runs and output is byte-identical to before (tracked-only
  semantics preserved). When there is no git repo it falls back to a filesystem walk emitting
  repo-relative forward-slash paths, so the detector functions host-independently and the caller's
  `-Exclude` regex filters identically.
- Test-IsGitWorkTree: new 5.1-safe probe; Test-IgnoreShadowsSource now returns no findings outside
  a work tree (nothing can be gitignore-shadowed without git), which also removes both
  terminating-error sites.

No test expectations, fixtures, or manifest values changed; the selftest still asserts its poison
fixture is flagged (now via the filesystem fallback on this non-git host) and the real-tree
`-Exclude '(^|/)selftests/'` still filters it. Re-run expectation: KIT GATE: PASS (8 suite(s) green).

### Selftest hardening: TrackedCompressedAsset verdict decoupled from host git state

Audit of the merged tree found hotfix 3 covered two of three host states. The selftest called
`Test-TrackedCompressedAssets -Path $root` and asserted the poison fixture is flagged; in a git
work tree where the fixture exists but is NOT yet tracked (the kit's own documented first-run
flow: bootstrap into a project, run the gate BEFORE the first commit), `git ls-files` succeeds
with exit 0 and an EMPTY set - so the filesystem fallback never fires, zero hits, and the
selftest reports "did not flag its poison fixture": the same red gate in a third disguise, with
a message that reads as a broken detector instead of an uncommitted file. Reproduced with real
git: untracked fixture -> exit 0 / 0 output lines; after commit -> fixture listed.

The defect was architectural: the selftest asserted host git STATE, not detector LOGIC. Fixed:
- `Get-CompressedAssetPaths` and `Test-TrackedCompressedAssets` gain `[switch]$NoGit`, which
  forces the filesystem walk unconditionally (threaded through as `-NoGit:$NoGit`).
- The selftest now calls `Test-TrackedCompressedAssets -Path $st -NoGit` - deterministic in
  all three host states (fixture committed / untracked / non-repo) and scoped to `selftests/`
  instead of walking the whole tree. The real-tree scan keeps tracked-only git semantics
  unchanged.
- `tools/Governance.Tests.ps1` gains two guards: changelog version-heading uniqueness (one
  letter = exactly one heading; this entry merges the two prior (k) headings), and an
  assertion that the preflight selftest passes `-NoGit`.

## 2026-07-05 (j) - hotfix 2: PS 5.1 Sort-Object metadata failure in the metrics readers

Second finding from the phase-1 Windows validation run (7 of 8 suites green after hotfix (i);
Metrics.Tests failed with MetadataError/ParentContainsErrorRecordException at the Pareto call).
Root cause: Get-GateFailureCounts and Get-RetryLeaderboard sorted with mixed-direction
calculated-property hashtables (@{ E = {...}; Descending = ... }, @{...}) - a construct
Windows PowerShell 5.1's Sort-Object metadata processing rejects at call time. Tree-wide grep
confirmed these two lines were the only occurrences of the construct in the kit (every suite
that passed uses primitive sorts only), and the leaderboard twin was latent - it would have
failed on the next line after any Pareto-only fix. Fixed both by elimination rather than
negotiation: a single ascending composite sort key ('{0:D10}|{1}' -f (1000000000 - count),
name) - count descending via inversion, name-ascending tie-break - byte-identical ordering
semantics (Metrics.Tests assertions unchanged), maximally primitive construct. Re-run
expectation: KIT GATE: PASS (8 suite(s) green).

## 2026-07-05 (i) - hotfix: two PS 5.1-only defects found by the first real Windows run of the kit gate

The first execution of tools/Kit.Tests.ps1 on Windows PowerShell 5.1 (validation phase 1) reported
FAIL (exit ) for all 8 suites while every suite's own verdict line was green. Root causes, both
invisible to structural verification and reproducible only on a real PS host:

- Kit.Tests.ps1 (runner): Start-Process -PassThru without caching the process handle leaves
  .ExitCode $null after the child exits on PS 5.1, so green suites read as FAIL with a blank
  code. Fixed: $null = $p.Handle immediately after spawn, a parameterless WaitForExit() flush
  after the timed wait, an explicit guard that treats an unreadable exit code as FAIL (never
  silently green), and the $args automatic-variable shadowing renamed to $psArgs.
- Show-Metrics.ps1 (production path, P0): Read-MetricsLines typed its filter as [datetime]
  $SinceUtc; PS 5.1 rejects binding $null to a typed datetime with a
  ParameterArgumentTransformationError. Since the main block passes $sinceUtc = $null whenever
  -Since is omitted, EVERY default invocation of Show-Metrics.ps1 crashed on PS 5.1 - the
  fixture suite caught a real tool defect by proxy. Fixed: the parameter is untyped with a $null
  default and normalized to [datetime] internally once; Metrics.Tests.ps1 now omits the
  parameter in the no-filter case so the test exercises the exact production path.

No schema, contract, or behavior changes otherwise. Re-run gate expectation:
KIT GATE: PASS (8 suite(s) green) on both powershell 5.1 and pwsh 7.

## 2026-07-05 (h) - docs release: zero-knowledge onboarding + Constitution V2 tour in README

Two README sections, no behavioral change. (1) "Bootstrapping a brand-new solution - the
zero-knowledge path": five numbered steps (bootstrap -> kit gate -> /agents -> prompt -> confirm)
plus THE ALIGNMENT PROMPT - a copy-paste single-writer session brief that proves the install
(Verify-KitInstall + Kit.Tests verdict lines pasted as evidence), inventories the stack and the
Prototype/ design sources read-only, binds every <...> placeholder in the seeded CLAUDE.md
(batched ask-then-write, never silent guessing), seeds SCREEN_REGISTRY/WORKFLOW_REGISTRY from the
prototype inventory, and hands back with assumptions + next step. Explicitly forbids editing
KIT_MANIFEST.json or kit machinery (hash-tracked). (2) "Understanding the Constitution in 10
minutes": the CONSTITUTION_NOTE tour refreshed for V2 - end-to-end flow (phase 4 now commits the
initial contracts snapshot), the twelve laws with V2 annotations (law 6 recursion via the kit
gate; law 8 contracts-surface enforcement; law 12 memory QUARTET with the >40% x3-waves
graduation trigger), the sweep diagram with the contracts-surface gate + METRICS/snapshot
closure, the NEW framework-governance loop diagram (version lock, kit gate, manifest classes,
drift-check-before-force), five human touchpoints, and the updated through-line.

## 2026-07-05 (g) - sprint 1.5: one framework - versioned, self-gating, manifest-verified installs

Consolidates the kit into a SINGLE distribution tree and turns its own laws inward. Three
mechanisms. (1) One tree, one version: KIT_VERSION (yyyy.MM.dd-<letter>, letter = top changelog
entry, asserted mechanically); the housekeeping addon is folded in as first-class kit files
(templates/housekeep.ps1 -> .claude/hooks/, commands/housekeep.md, settings example); upgrades
are now commit series, never side-car zips. (2) THE KIT GATE (Law 6, recursively):
tools/Kit.Tests.ps1 discovers and runs every *.Tests.ps1 suite - in CHILD processes, because
suites exit 0/1 by convention and an in-process exit would kill the runner - plus the preflight
harness self-tests via the new -SelfTestOnly switch (self-tests without scanning the kit tree as
if it were a project); one verdict line; no release without KIT GATE: PASS. (3) Provenance at
birth for INSTALLATIONS: bootstrap writes .claude/KIT_MANIFEST.json as its LAST act - kit version
+ a normalized SHA-256 per installed kit file (spec text-crlf-bom-v1: BOM stripped, CR dropped,
so autocrlf and PS 5.1 editors can never fake drift; the single hash implementation lives in
New-KitManifest.ps1 and everything else dot-sources it - no second hasher to drift, and
bootstrap.sh DELEGATES to it rather than growing a bash twin). Verify-KitInstall.ps1 is
design-sync for installs: OK / MODIFIED / OVERRIDE (declared in .claude/KIT_OVERRIDES.txt - every
audit declares its exclusions) / MISSING / STALE / CONFLICT, with seeded files (CLAUDE.md,
settings, verify hooks, boards) recorded but NEVER flagged - the alarm-fatigue fix that keeps the
tool alive. Report-only by default (Law 11); -Strict for CI; -Force re-bootstrap runs the drift
check FIRST so upgrading never silently destroys the evidence.

ALSO FIXES a live install defect found by this consolidation's alignment audit: both bootstraps
enumerate tools per-file, so the (f) tools (Show-Metrics, Update-ContractsSnapshot, tests,
fixtures) would never have installed into projects. Both bootstraps now install the full tool
set, the housekeep hook, METRICS_README, and docs/metrics/ - and Governance.Tests.ps1 asserts
bootstrap completeness for every shipped tool so this defect class cannot recur.

### What landed
- KIT_VERSION (2026.07.05-g) + Governance.Tests.ps1 (version<->changelog alignment, critical-file
  inventory, detector/registration greps, bootstrap-completeness assertions).
- tools/Kit.Tests.ps1 (child-process suite runner, 300s timeout, output tail on FAIL, -List).
- preflight.ps1 + Invoke-StackChecks: -SelfTestOnly (anti-no-op checks only; real-tree skipped).
- tools/New-KitManifest.ps1 (normalization/hash/mapping/class SINGLE implementation; atomic write)
  + tools/Verify-KitInstall.ps1 (classification engine, -KitSource for STALE/CONFLICT, -Strict,
  -Json) + commands/kit-verify.md (orchestrator wrapper; IT appends the adhoc METRICS line - the
  tool never writes metrics, single-writer preserved).
- tools/Manifest.Tests.ps1 + manifest-fixture-{lf,crlfbom}.txt: hash parity to the frozen spec
  constant, mapping table, and a synthetic end-to-end drill planting MODIFIED / OVERRIDE /
  MISSING / LOCAL / SEEDED / STALE and asserting every classification.
- Housekeeping addon folded in: templates/housekeep.ps1, commands/housekeep.md,
  templates/settings.housekeep.example.json; installed by both bootstraps.
- bootstrap.ps1/.sh: full tool-set install (F0 fix), docs/metrics/, pre-upgrade drift check on
  -Force (-SkipDriftCheck escape), manifest generation LAST, new Done-tips (kit gate + verify).
- METRICS_README: reserved kit-verify event row. README: governance section + version line.
  BOOTSTRAP.md: manifest & verify section + tree. CLAUDE.master: governance bindings bullet.


## 2026-07-05 (f) - sprint 1, days 1-2: quantitative memory (C1) + the contracts-surface gate (A3)

Lands the first two UPGRADE_PLAN v3 items. C1 gives the kit its QUANTITATIVE memory - the
qualitative trio (INSIGHTS/LESSONS/PROGRESS) becomes a quartet: one append-only JSONL line per
sweep/wave/park/flake, written ONLY by the orchestrator at integration, SHARDED per run so
concurrent sessions never tear a file. The gate-failure Pareto turns "refine prompts when a run
misbehaves" (PROMPT_TEMPLATES paragraph I) into a ranked backlog, and Law 12 gains a quantitative
graduation trigger (>40% of retries x 3 waves -> the agent's skill earns a trap entry). A3 makes
Law 8's "append-only Contracts" ENFORCED rather than reviewed, twice: an ArchitectureTests
snapshot asserting approved SUBSET-OF generated (pinned generator options, EOL-normalized - the
two classic snapshot killers), and an edit-time preflight detector that flags any '-' line in the
snapshot's git diff as a HARD finding. Deprecation stays cheap ([Obsolete] + V2 = an addition);
physical removal is a foundation-gated HUMAN event through the approval inbox - the gate is
absolute for agents, governed for humans. Both items are feature-detected: no metrics dir / no
snapshot => the kit behaves exactly as before.

### What landed
- **`templates/METRICS_README.md`** - NEW: the v1 event schema (sweep/wave/gate/park/flake/
  housekeep + reserved retry/design-gate), the sharding rule, the single-writer generation
  contract, the freeze rule (v1 frozen for 3 waves), the graduation trigger.
- **`tools/Show-Metrics.ps1`** - NEW reader (5.1-safe, dot-sourceable): summary roll-up, stage-
  duration medians, gate-failure Pareto (deterministic tie-break by name), retry leaderboard
  (sweep-line retries only - the standalone retry event is reserved, never double-counted),
  -Since window, -Json, tolerant of a torn tail line (skips + reports malformed count).
- **`tools/Metrics.Tests.ps1` + `tools/metrics.fixture.jsonl`** - NEW self-tests: a planted
  distribution (10 sweeps, a standalone gate event proving both Pareto sources sum, a tie
  proving deterministic ordering, exact medians, 1 malformed line proving skip-not-hide).
- **`templates/ContractsSurfaceTests.cs.template`** - NEW: PublicApiGenerator snapshot test,
  approved SUBSET-OF generated, pinned options, EOL-normalized, env-gated UPDATE mode,
  failure message cites every missing line verbatim.
- **`tools/Update-ContractsSnapshot.ps1`** - NEW, ORCHESTRATOR-ONLY: refuses on a locally
  edited snapshot (protects a pending foundation-gate decision), regenerates via the env-gated
  test path, prints the delta with removals called out loudly, stages for the integration
  commit. Once per sweep at integration; once per WAVE at closure.
- **`dotnet-pack/Detectors.Dotnet.psm1`** - Test-ContractsSurfaceRewrite (HARD; -DiffText
  injection for self-tests; feature-detected on snapshot presence) + Test-ContractsModifiedSource
  (WARN; a modified existing Contracts .cs is worth a look, never a block); registered in
  Invoke-StackChecks phase 1 (poison + clean-append self-tests) and phase 2 (real tree).
  Fixtures: `selftests/contracts/{bad-mutation,good-append}.diff.txt`; standalone
  `tools/ContractsSurface.Tests.ps1` with dual path resolution (kit-source / installed).
- **Integration edits:** build-workflow step 7 + build-wave closure items 7-8 (METRICS line +
  snapshot regen, both single-writer); backend-builder hard rule (never edit the snapshot) +
  gate cite; reviewer paragraph-2 automatic-FAIL citation; wave-reviewer scope note (mechanical
  rewrites caught upstream; wave audit = SEMANTIC duplication); PROMPT_TEMPLATES paragraph F
  (foundation commits the initial snapshot on a green tree); progress.ps1 -Stats; CONSTITUTION
  paragraph 3 + paragraph 10; CLAUDE.master bindings; SPECIALIZE glossary; BOOTSTRAP/README.


## 2026-07-05 (e) - the dead-edge audit (prototype affordance honesty · the fourth quadrant)

Graduates the per-module "no button that lies" field lesson into the kit, filling the audit
matrix's empty cell: affordance scope on the PROTOTYPE side (journey-auditor covers journey
scope; interaction-auditor covers built affordances). The lenses are orthogonal: journey audits
classify DESTINATIONS; this classifies HANDLER BEHAVIOR - a toast-only "Approve" that never
navigates is invisible to an edge ledger yet strands a lifecycle. Carries the meta-lesson as
law: AN AUDIT IS ONLY AS COMPLETE AS ITS TAXONOMY - every run declares buckets AND exclusions;
re-runs inherit prior exclusions (how "Add X" ships dead through a "closed" journey-scoped
audit).

### What landed
- **`skills/dead-edge-audit/`** - NEW shipped skill: mechanical tells (toast-only, no-handler,
  placeholder, disabled-without-reason, cross-screen dishonesty); the TWO-AXIS classification
  (behavior disposition x remediation class: lifecycle step / creation entry / cross-nav /
  utility / accepted fire-and-forget); the additive fix grammar (status-override maps,
  session-list creation, context-carry nav, shared utilities, the global-scope collision trap);
  the **section "Accepted toasts" exceptions ledger** in the interaction registry (verify, never
  re-litigate); the routing table; + **`CONSOLE_PROMPT.md`** (the fillable design-tool venue).
- **`agents/edge-auditor.md`** - NEW (16th agent, opus): ONE module per dispatch; advisory;
  taxonomy declared in the report header; ledger re-verification (a broken justification IS a
  finding); registry-aware routing (unbuilt | BUILT -> design-sync | graduated -> forward-only).
- **`commands/edge-audit.md`** - NEW orchestrator: parallel per-module dispatch; approval STOP
  with accepted-toast candidates surfaced separately (accepting a toast is a product decision);
  single-writer fixes with provenance refresh + sidecar updates; ledger maintenance; closure
  proved by re-running the tells; --buckets exclusions become registered debt.
- **Prevention at birth:** `design-builder` hard rule + the Global preamble output contract now
  forbid toast-only lifecycle/creation CTAs in new screens (deferral = Marked-stub or declared
  `notify-sim`); the sidecar `effect` enum gains `notify-sim`. The audit's steady state is
  verifying the ledger, not harvesting debt.
- **Neighbor pairings:** `journey-auditor` Phase-0 now FLAGS handler-dead tells and cross-files
  them to /edge-audit (a lying handler is affordance scope unless it also strands the journey);
  `interaction-auditor` adopts the remediation-class axis + reads the shared exceptions ledger
  (an accepted prototype toast reconstructed as Marked-stub/notify-sim never resurfaces as
  Unmarked-stub).
- **Portability hardening (full-session genericness audit):** neutralized two domain-tinted
  examples that had leaked from the reference project (design-builder splice example;
  journey CONSOLE_PROMPT fill examples); the shipped `templates/INTERACTION_REGISTRY.md` now
  contains the **section "Accepted toasts"** the dead-edge machinery references (it was cited
  but not shipped); React idioms in the dead-edge CONSOLE_PROMPT are labeled stack examples;
  backlog-id parsing phrased per the board's ID scheme; CLAUDE.master gains the parallel
  dispatch-cap binding and the registry default path. Binding-coverage cross-check: every
  "per CLAUDE.md" reference in session files resolves to a master-template binding.
- **`PROMPT_TEMPLATES.md paragraph L`**, CONSTITUTION quadrant + roster + opus routing,
  CLAUDE.master dead-edge bindings (project tells, shared utilities, context-carry pattern,
  accepted-toast policy), SKILLS/README/BOOTSTRAP catalogs.

## 2026-07-05 (d) - the adoption pairing (design-sync <-> journey-auditor)

Extends the journey pairing to DRIFT ADOPTION. design-sync sees screens; journeys live in edges
- and each drift class maps to an edge-failure mode it could not see: MODIFIED can silently flip
an edge OK -> DEAD-END/WRONG (a redesign drops or retargets a CTA), NEW can orphan (unspliced
edges), REMOVED severs every inbound edge. The coupling is deliberately asymmetric to the builder
pairing and preserves the strict boundary (design-sync never walks a journey; journey-auditor
never diffs provenance): design-sync only FLAGS scope; the orchestrator gates adoption on a
post-execution continuity check.

### What landed
- **`agents/design-sync.md`** - new "Journey impact - you FLAG scope, you never audit it"
  section: per drifted screen, resolve journey membership by sidecar `journeys` LOOKUP (spec/
  registry fallback); mark `edge-touching: yes` on MODIFIED rows whose diff touches CTAs/links/
  row-clicks; enumerate inbound-edge count + files for every REMOVED row (a 6-inbound-edge
  removal is a different human decision than an orphan). Output template gains a per-screen
  `journeys:` line and the plan gains step 5: "post-execution continuity delta check ->
  /journey-audit over [journeys]".
- **`commands/journey-audit.md`** - new scope form: a design-sync PLAN FILE resolves to its
  flagged journeys' union - the drift-adoption delta check - with the run-AFTER-execution rule
  (auditing mid-execution reports half-applied edges as false gaps).
- **`commands/promote-design.md` step 4b** - a console delivery batch is a journey event:
  resolve delivered screens' journeys from their sidecars, re-run the Phase-0 edge ledger (no
  orphans - a missing upstream repoint becomes the orchestrator's wiring todo or design-sync's
  when the upstream is built; context key carried; zero new dead/legacy/wrong edges); 3+
  screens on one journey or amber -> full journey-auditor dispatch. Boards flip only on green.
- **`skills/journey-continuity-audit/SKILL.md`** - "after drift adoption" added to when-to-run;
  the adoption-pairing section documents the one gate now shared by all three adoption paths
  (/design-build 6b, /promote-design 4b, design-sync plan step 5).
- **`CONSTITUTION.md §6`** - the prototype-drift paragraph now ends adoption with the
  continuity delta check.

## 2026-07-05 (c) - the journey splice (design-builder <-> journey-auditor pairing)

Closes the loop between designing new screens and journey continuity. A new screen is an EDGE
INSERTION into a journey graph, but the design lane only enforced per-screen invariants: the
builder never saw the journey slice around its insertion point (feed-forward gap), nothing
re-traced the journey after integration (feed-back gap), and audit GAP rows lost file/route/key
precision on their way into briefs (fidelity gap). All three are now wired.

### What landed
- **Feed-forward — the journey splice packet.** `/design-build` assembles it per row (from the
  originating `/journey-audit` GAP report, else the workflow step chain): journey id, inbound
  edge (upstream file + CTA + current state), outbound edge (downstream route + context key),
  continuity-ledger excerpt. `design-builder` gains splice duties: match both edges, carry the
  subject's identity through, stamp `journeys` in the sidecar, and report the upstream repoint
  (never edit it — Law 3). A packet-less dispatch must be declared, never silent.
- **Feed-back — the continuity delta check (`/design-build` step 6b).** Per affected journey,
  re-run the audit's Phase-0 edge ledger (grep-cheap) — the GAP's inbound edge must flip to OK,
  the outbound edge must be OK, zero new dead/legacy/wrong edges; 3+ screens on one journey or
  any amber -> re-dispatch `journey-auditor` for the full trace. **Boards flip only on green.**
  Integration also applies the upstream repoint (drift-routed to `design-sync` when the upstream
  screen is built) and refreshes touched sources' provenance hashes.
- **Fidelity — GAP fields travel verbatim.** `/journey-audit` files missing-screen rows carrying
  GAP-nn + splice fields; `design-prompt-authoring` lifts them into the NEW **Journey-splice
  block in PROMPT_TEMPLATES §J** (never paraphrasing file/route/key names); the sidecar schema
  gains `journeys: ["J-..."]` so future audits build Phase-0 ledgers from sidecars instead of
  re-tracing.
- `CONSTITUTION.md §6` closing-the-design-loop paragraph + the `journey-continuity-audit`
  routing table document the pairing.

## 2026-07-05 (b) - journey-continuity audit (the third continuity layer · phase-1 gate)

Graduates the "workflow-continuity audit" field lesson into the kit: screens designed one at a
time accumulate gaps that live BETWEEN screens — missing pick-before-work queues, dead / legacy /
context-losing edges, absent handoff receivers, missing states/exceptions/artifact trails — and
no per-screen review (invariants) or per-affordance audit (`interaction-auditor`) can see them.
One method, two venues (design-tool session and in-repo), single-sourced. Genericness
re-verified by the leak-grep gate.

### What landed
- **`skills/journey-continuity-audit/`** — NEW shipped skill: `SKILL.md` (the 5-phase method —
  mechanical route/edge ledgers with `OK | DEAD-END | LEGACY | WRONG` classification → role×journey
  trace → expanded gap catalog → report-then-STOP → additive fill; the GAP-row/severity contract;
  the continuity ledger; the fix-routing table) + **`CONSOLE_PROMPT.md`** (the full fillable
  prompt to paste into a Claude Design session — the single source both venues share).
- **`agents/journey-auditor.md`** — NEW (15th agent, opus): traces ONE journey through the
  prototype per the skill; advisory (writes only its report); registry-aware routing on every gap
  row (`unbuilt | BUILT ✅ → design-sync | graduated → forward-only`); strict boundaries vs
  `interaction-auditor` (built UI), `design-sync` (drift), `spec-researcher` (market parity).
- **`commands/journey-audit.md`** — NEW orchestrator: `golden | all | J-id… | module` scopes,
  parallel per-journey dispatch, cross-journey merge/dedupe, approval STOP, single-writer fix
  routing (backlog rows + `design-prompt-authoring` briefs · unbuilt micro-edits with provenance
  refresh · design-sync handoffs · forward-only items), closure re-trace, and the explicit
  **phase-1 gate verdict** (`PASS/FAIL: zero S1 on golden journeys`).
- **`PROMPT_TEMPLATES.md §K`** — the console-venue pointer + gap-row contract + gate rule.
- **`CONSTITUTION.md`** — the phase-1 gate now requires the audit clean of S1s (lifecycle table);
  §6 roster row + the three-layer continuity-stack paragraph; opus routing updated.
- Catalogs: `SKILLS.md` row, README + BOOTSTRAP trees.

## 2026-07-05 - the streamlined design loop (in-repo lane · atomic ingest · contract-at-birth · graduation)

Removes the design↔dev round-trip waste for mid-flight net-new screens. Diagnosis: with the
same model on both sides, the design tool's marginal value is the interactive canvas, not
generation — yet every backlog screen paid for (a) double generation (console JSX, then a
reconstructor re-deriving the same screen), (b) drift triage over deltas the pipeline itself
created, and (c) manual courier work (copy/paste, zip, place, wire, tri-board status flips —
the exact place board-vs-reality drift kept creeping in). This release routes each screen by
one question — *does it need human canvas iteration?* — and makes the contract a first-class
artifact captured once, at birth. Genericness re-verified by the leak-grep gate.

### What landed
- **`agents/design-builder.md`** — NEW (14th agent, opus). The in-repo design lane: authors ONE
  net-new prototype screen from its design-prompts brief (scaffold-conforming rows only; refuses
  console-lane work with `Rerouted`), closed vocabulary (grep-verified against the prototype),
  isolated sandbox render + sign-off screenshot, contract sidecar + provenance hash at birth;
  never wires or flips (Law 3) — returns exact proposed wiring lines.
- **`commands/design-build.md`** — NEW orchestrator: resolve `☐` rows (missing brief → fire
  `design-prompt-authoring`), lane-route, claim, parallel dispatch, **human sign-off checkpoint
  on the render** (designer sign-off preserved, on-the-loop), single-writer integrate (wire +
  provenance-at-birth registry row + board flips), optional `--and-reconstruct` fused
  reconstruction (the sidecar is the reconstructor's completeness checklist).
- **`commands/promote-design.md`** + **`workflows/promote-design.js`** — NEW: atomic ingest of an
  *expected* console delivery. The zero-dependency helper (dry-run default, idempotent)
  classifies `NEW | IDENTICAL | OVERWRITE | UNEXPECTED`, hashes, sidecar-checks, and inserts
  entry-point include lines modeled on the last existing anchor; OVERWRITEs are never applied —
  they are drift, routed to `design-sync`; resolver edits are emitted as todos for the
  single-writer orchestrator. Expected deliveries never trigger a drift sweep again.
- **`skills/contract-sidecar/SKILL.md`** — NEW: the `<screen-file>.uimap.json` schema + producer
  /consumer duties. Contract captured when the generating model still holds it; downstream
  agents **validate instead of re-derive** (`spec-architect` lifts it as the UIMAP first draft +
  backfills legacy screens as a by-product; `screen-reconstructor` gates completeness on it;
  `design-sync` classifies contract-affecting drift by sidecar diff). Render still wins (Law 1).
- **`templates/DESIGN_BACKLOG.md` + `templates/DESIGN_PROMPTS.md`** — NEW board templates
  (previously referenced by `/design-help` + `design-prompt-authoring` but never shipped);
  seeded to `docs/` by both bootstraps, recognized by both cleanups. The prompts board's
  Global-preamble output contract now requires the sidecar from the console lane too.
- **`CONSTITUTION.md`** — §2 "Two design lanes" doctrine; §4 **provenance at birth** (pipeline-born
  screens exit drift triage) + **contract graduation** (wired + reviewer-PASSed ⇒ the live UI is
  the contract, the prototype source freezes and exits drift-sweep scope; redesigns become
  briefed preserve-wiring events); §5 "contract at birth (sidecar-first)"; §6 roster + the
  closing-the-design-loop paragraph.
- **`agents/design-sync.md`** — explicit out-of-scope rules (pipeline-born hash-fresh screens,
  graduated screens, in-flight expected deliveries) + sidecar-diff-first classification. Its
  remit shrinks to what it should be: changes made *outside* the pipeline.
- **`agents/screen-reconstructor.md` / `agents/spec-architect.md`** — sidecar consumption rules.
- **`PROMPT_TEMPLATES.md §J`** — one brief, two lanes; sidecar added to the output contract; the
  manual five-step after-delivery list replaced by the two commands.
- **`templates/CLAUDE.master.md §2`** — the design-loop bindings block (board paths, file
  pattern, wiring anchors, sidecar convention, the lane-routing rule, sign-off policy,
  graduation opt-outs); **`SPECIALIZE.md`** glossary row; **`SKILLS.md`** catalog rows;
  README/BOOTSTRAP trees; all four install/rollback manifests.
- **FIX — the installer now actually runs on Linux/macOS:** `bootstrap.sh` and `cleanup.sh`
  shipped with CRLF line endings, so `#!/usr/bin/env bash\r` failed at the shebang on any
  POSIX system. Both are normalized to LF (+x) and syntax-checked; the full install →
  user-edit → rollback round-trip is verified (pristine files removed, modified files kept,
  no orphan directories).

## 2026-06-28 - code-discovery graph (graph-first discovery, optional capability)

Graduates the source project's **graph-first code discovery** into the kit. The audit/spec
and build subagents now reach for a code-discovery graph MCP (`codebase-memory-mcp`) **before**
Grep/Glob for structural questions — who calls X, what a module exposes, which modules
emit/consume an event, the cross-module contract surface, UI-affordance→handler matching, and
Law-2 boundary checks — at a fraction of a grep sweep's token cost. Shipped as an **optional
capability**, not a kit dependency: with no graph configured the `mcp__codebase-memory-mcp__*`
tools are simply absent and every agent falls back to Grep/Glob with no loss of behaviour.
Genericness re-verified by the leak-grep gate — the only project value (the graph project id)
is a `<graph-project-id>` placeholder bound from `CLAUDE.md §0`.

### What landed
- **10 agents** (`agents/`) — `backend-builder`, `module-wirer`, `crosscutting-weaver`,
  `test-engineer`, `spec-architect`, `spec-researcher`, `design-sync`, `reviewer`,
  `interaction-auditor`, `wave-reviewer` — each gains the **read** graph tools in `tools:`
  frontmatter (`search_graph`/`trace_path`/`query_graph`/`get_code_snippet`/`get_architecture`/
  `get_graph_schema`/`detect_changes`/`search_code`) and a role-tailored, optional
  "Graph-first discovery" paragraph. `migration-engineer`, `seed-builder`, and
  `screen-reconstructor` are deliberately **excluded** (narrow scope / visual fidelity needs no
  code discovery). **No agent gets the index-mutating tools** (`index_repository`/`delete_project`)
  — re-indexing is the orchestrator's single-writer duty (Law 3).
- **`templates/CLAUDE.master.md §0`** — new optional "Code discovery is graph-first" bullet:
  orient→locate→read procedure, read-only/single-writer freshness rule, scope/exclusions, the
  rendered-prototype-still-wins caveat, and the who-may-query roster. Carries a `<!-- delete if
  not used -->` note and the `<graph-project-id>` placeholder.
- **`CONSTITUTION.md §6`** — roster `Tools` column annotated `+ graph(read)` for the 10 agents;
  a new "Graph-first discovery (optional)" paragraph documents the capability, the who-gets-it
  split, the exclusions, and the orchestrator-only re-index duty.
- **`SPECIALIZE.md`** — `<graph-project-id>` added to the placeholder glossary (bound from
  `CLAUDE.md §0`) + an "Optional capability — code-discovery graph" note explaining graceful
  degradation and the index-mutating-tools exclusion.
- **`SKILLS.md`** — the MCP-layer row now names the code-discovery graph as the recommended
  optional MCP.
- **`templates/cbmignore`** — NEW generic ignore template (gitignore syntax) seeded to the repo
  root as `.cbmignore`; scopes the graph to `src/`/`tests/` and excludes the prototype tree +
  kit source. Installed by both bootstraps and recognized by both cleanups; `BOOTSTRAP.md`
  prereqs + "what it creates" tree updated with the optional MCP and the new root file.

## 2026-06-27 - design-prompt-authoring skill (backlog → ready-to-send briefs)

Closes the gap between filing a design-backlog row and having a ready-to-send design-tool
brief for it. The §J prompt was specified as a sub-step of `/design-help` (step 4.4) but
under-delivered in practice — rows got filed, briefs did not. This makes the brief a
first-class **successive output of every backlog row**, owned by whoever files the row, and
keeps it strictly separate from drift triage (`design-sync` re-syncs an existing prototype
source; this authors a brief for a source that does not exist yet — inverse directions).
Genericness re-verified by the leak-grep gate (zero project/domain hits in any touched file).

### What landed
- **`skills/design-prompt-authoring/SKILL.md`** — NEW. Turns each `☐` design-backlog row
  into a filled §J brief in a **design-prompts companion board** (default `DESIGN_PROMPTS.md`,
  a sibling of the backlog) with a **Global preamble** (design-system law, scaffolds,
  prohibitions, continuity invariants, output contract) authored once and prepended to every
  per-row block. Installed automatically by bootstrap's `skills/*/` loop — no manifest edit.
- **`PROMPT_TEMPLATES.md §J`** — points at the companion board + the skill + the
  Global-preamble structure; frames the brief as a successive output, not an ad-hoc fill.
- **`commands/design-help.md`** — step 4.4 now emits via the skill into the companion board
  and leaves a pointer in the backlog's §Pending prompts (no duplicated briefs); step-5
  summary updated.
- **`commands/build-workflow.md` · `commands/build-wave.md`** — Checkpoint-1 backlog-append
  emits each filed row's brief via the skill (batched in a wave).
- **`SKILLS.md`** — catalogs the skill (ships-with-the-kit) + a command→skill map line.
- **`agents/design-sync.md`** — boundary note: a net-new screen with no prototype source is a
  design-backlog item (briefed by the new skill), never a drift/re-sync item.

## 2026-06-23 - parallelism + command currency sync

Resyncs the kit with method improvements that landed in the source project after the
currency harvest: completes the parallelism tooling, adds the lifecycle commands, and
folds two functional-fidelity detectors into the optional stack pack. Genericness was
re-verified by the two-pass leak-grep gate (zero hits in any touched file) and every
shipped self-test passes under Windows PowerShell 5.1.

### What landed

**Parallelism tooling now complete (`tools/`)**
- `Verify-WaveDisjoint.ps1` -- NEW. The pre-fan-out **wave-disjointness verifier** (the
  Phase 0 hard gate of `/build-wave`). It dot-sources `Compute-WaveSchedule.ps1`, so the
  conflict rule can never drift between planning and verifying; reports any span that
  WIDENED past its `spans.json` baseline. Exit 0 = disjoint, 1 = conflict, 2 = bad args.
- `Compute-WaveSchedule.ps1` -- **status-aware rendering**. `Select-ActiveSpans` /
  `Select-CompletedSpans` drop `status: "done"` spans from the schedule and list them
  under a "Completed (excluded)" section; a done span counts as a satisfied dependency.
  Output filename stays generic (`WAVE_PLAN.md`).
- `Verify-WaveDisjoint.Tests.ps1` + `RenderFilter.Tests.ps1` -- NEW self-tests (reuse the
  alpha/beta/gamma `spans.fixture.json`; assert no rule drift + the active/done partition).
- `PARALLELISM.md` -- documents the optional `status` field and a "wave disjointness
  verifier" section with the exit-code contract.

**Lifecycle commands harvested (`commands/`)**
- `reconstruct.md` -- NEW. Phase-2 screen-reconstruction orchestrator (was project-only).
  Genericized: binds the shared-primitive directory, design-system prefix/stylesheet, and
  reconstruction-workflow doc from `CLAUDE.md` -- no `cm-*` / project paths.
- `construct-help.md` + `construct-run.md` -- NEW. Read-only lifecycle dashboard and
  phase-aware dispatcher. Genericized (drift module-code lists, journey IDs, and screen
  counts replaced with `CLAUDE.md`-bound or neutral references).
- `build-wave.md` -- Phase 0 now invokes the shipped `.claude/tools/Verify-WaveDisjoint.ps1`
  with a concrete exit-code gate (was a hand-waved "the project defines the verifier").
- `build-workflow.md` -- step 4 gains a **preflight-gate** bullet (where the opt-in gate is
  wired) and a **file-scope check** (re-derive each agent's scope from `git diff --stat`,
  never its prose report).

**Functional-fidelity detectors (`scripts/preflight/dotnet-pack/`)**
- `Test-StubSaveHandler` -- flags a mutation-named handler whose body only toasts/navigates
  (no command dispatch / persistence). WARN-level.
- `Test-SingletonDetailRoute` -- flags an entity-detail page with no `{route param}` that
  binds identity from a static `*Data` singleton (every selection opens the same record).
  WARN-level; the identity-field list was genericized to domain-neutral fields.
- Both wired into `Invoke-StackChecks` as advisory (never fail the gate) with anti-no-op
  poison fixtures **and** clean false-positive fixtures (`bad/good-stub-save.razor`,
  `bad/good-singleton-detail.razor`).

**Installer / cleanup parity**
- `bootstrap.{ps1,sh}` install the three new `tools/` files; `cleanup.{ps1,sh}` recognize
  them. The new commands and dotnet-pack selftests are picked up automatically by the
  existing `commands/*.md` glob and the recursive `scripts/preflight` tree copy.
- `BOOTSTRAP.md` "what it creates" tree lists the new tools and the full command set.
- Verified: fresh `bootstrap` into a temp dir installs everything and is idempotent; the
  installed parallelism tests + preflight pass; `cleanup` dry-run = 73 to remove, 0 kept.

## 2026-06-23 - affordance closure

Adds the **screen-scope completeness check** to the build sweep. A sweep wires a
workflow's *path*; a screen accumulates affordances from many paths and from
visual-only reconstruction, so off-path / reconstruction-era buttons, links,
CTAs, and shortcuts become silent stubs that pass every per-path gate.

### What landed
- **`agents/interaction-auditor.md`** -- read-only auditor (Opus). Enumerates every
  interactive affordance on a screen set (static spine + optional rendered crawl),
  classifies each `Wired | Marked-stub | Unmarked-stub | Mis-wired | Dead-end |
  Design-gap`, reconciles vs the UIMAP's `action→effect`, and risk-tags every gap.
  Two modes: in-sweep (touched screens) and standalone backlog (whole UI).
- **`commands/build-workflow.md`** -- new "Interaction closure" gate folded into the
  quality-gate step (EBGRI preserved): orchestrator auto-remediates low-risk +
  trivially-constructable rows, asks the human (choices) on medium/high-risk rows,
  and is single writer of an `INTERACTION_REGISTRY` board. Routing-table row added.
- **`CONSTITUTION.md`** -- §6 roster row + an "affordance closure" paragraph; §9
  wiring gate + Definition of Done now require a complete affordance ledger (zero
  unmarked stubs / mis-wired seams; deferrals ticketed). Makes the `functional
  fidelity` invariant enforceable at **screen** scope, not just **path** scope.
- **`templates/INTERACTION_REGISTRY.md`** -- generic affordance-closure board (a
  generation contract + legend + an empty scoped scaffold). Seeded into `docs/`
  alongside `SCREEN_REGISTRY` and `WORKFLOW_REGISTRY` and wired through both
  installers (`bootstrap.ps1`/`.sh`) and both cleanup scripts; the `BOOTSTRAP.md`
  "what it creates" tree lists it. The installer also auto-discovers the new agent
  (recursive `agents/` install).

## 2026-06-22 - currency harvest

This release graduates a set of project-proven capabilities into the generic kit.
Genericness was enforced by a two-pass leak-grep gate (hard token check + project
coupling check) run to zero before shipping.

### What landed

**Generic agent trap-cards**
- Trap-card blocks added to six build-phase agents (backend-builder,
  migration-engineer, seed-builder, module-wirer, test-engineer, reviewer),
  plus a gateless-CTA check wired into the spec-hardening skill.
- spec-hardening skill updated with a gateless-CTA detector step.

**Verification-gate generic core (`scripts/preflight/`)**
- `preflight.ps1` -- core harness (self-testing, EBGRI model, -Fast mode, exit codes).
- `Detectors.psm1` -- four generic detectors: NonHexGuid, StrayBuildDirs,
  TrackedCompressedAssets, IgnoreShadowsSource (new in this release).
- `selftests/` -- poison fixtures and anti-no-op self-test guard for each generic detector.
- README documenting the detector contract and how to add project detectors.

**Optional .NET/EF/Razor/CSS detector pack (`scripts/preflight/dotnet-pack/`)**
- `Detectors.Dotnet.psm1` -- five stack detectors: CssCommentBalance, RazorStringParam
  (@bind fix included -- lookbehind prevents false positives on @bind-Value), OwnedInclude,
  EnsureCreatedInIntegration, SensitiveInText (opt-in redaction guard -- off by default;
  enable by dropping `redaction.patterns.txt`).
- `selftests/` -- poison fixtures for each dotnet detector.
- `MigrateAllSeedAll.pattern.md` -- integration-gate pattern doc (genericized).
- README documenting the pack, the @bind fix, and the redaction opt-in.

**Parallelism wave scheduler (`tools/`)**
- `Compute-WaveSchedule.ps1` -- deterministic graph-coloring wave scheduler; dot-source
  or -Render mode (writes `docs/WAVE_PLAN.md`).
- `Schedule.Tests.ps1` -- standalone self-tests (6 invariants over 6 spans; prints PASS).
- `spans.fixture.json` -- 6-span test fixture.
- `PARALLELISM.md` -- how to mine spans.json from WORKFLOW_REGISTRY.md and run the scheduler.

**Opt-in notify capability (`templates/notify.ps1`, `templates/NOTIFY_SETUP.md`)**
- `notify.ps1` -- turn-end notification hook template (opt-in; configure per NOTIFY_SETUP.md).
- `NOTIFY_SETUP.md` -- setup guide seeded into `docs/NOTIFY_SETUP.md` on bootstrap.

**Opt-in preflight hooks (`templates/oncodeedit.ps1`, `templates/settings.preflight.example.json`)**
- `oncodeedit.ps1` -- edit-time gate (PostToolUse hook; fires on Edit/Write/MultiEdit).
- `settings.preflight.example.json` -- example settings with both preflight hooks wired.

**Engine-agnostic graduation skill (`skills/graduation/SKILL.md`)**
- Lift duplicated UI markup into a verified-fidelity reusable primitive.
- Generic by design: binds component naming, design-system prefix, and primitive home
  directory from the project `CLAUDE.md`.

**PowerShell 5.1 portability**
- All harvested `.ps1` scripts are ASCII-only and Windows PowerShell 5.1-safe.
- BOOTSTRAP.md prereq updated to accept `powershell` (5.1) alongside `pwsh` (7+).

**Installer and cleanup parity**
- `bootstrap.ps1` and `bootstrap.sh`: recursive `Copy-Tree`/`copy_tree` helper added;
  all new files wired with `Copy-IfMissing`/`copy` and `Copy-Doc`/`copy_doc`.
- `cleanup.ps1` and `cleanup.sh`: all new files wired with `Handle`/`handle`; empty
  preflight subdirectory list added (deepest first) to the empty-dir cleanup pass.
- Idempotent: re-running bootstrap skips already-installed files.

**Doc cleanups (genericness)**
- PARALLELISM.md: example id changed from project module code to neutral `WF-XX-01`;
  dangling project-spec citation removed and rephrased generically; output filename
  changed from `PARALLELISM_PLAN.md` to `WAVE_PLAN.md`.
- MigrateAllSeedAll.pattern.md: dangling project-spec citation genericized.
- graduation/SKILL.md: description threshold changed from "N screens" to "two or more screens".
- scripts/preflight/README.md and dotnet-pack/README.md: run-command examples updated
  to show the installed path (`.claude/hooks/preflight/preflight.ps1`).
- BOOTSTRAP.md: prereq, "what it creates" tree, and opt-in section updated to present tense.