v7.3.0 — Required Context contract + effort-metrics kit (token tracking, typed YAML schemas, --minimal tiers)

Summary

The largest kit release to date. Three themes: dispatch context becomes a contract (the falcon skill now declares what a worker must read), effort becomes measurable (a full forecast → track → calibrate loop ships in the kit), and session state becomes typed (JSON Schemas + YAML replace freeform markdown for every kit artifact). Driven by 11 decision records grounded in a month of field-deployment transcript data (377 sessions).

Changes

Required Context contract (falcon skill v7.3.0)

Problem: Workers guessed which context files mattered for a bead. Misses surfaced as wrong-assumption implementations; steering had no visibility into what a worker actually read.

Solution: Dispatch files now carry required_context[] (steering populates it at Step 2 from the bead's ## Required Context section); the worker loads those files at new Lifecycle Step 2b before writing intent, and reports any unlisted_context_reads[] in its return. /wrapup absorbs unlisted reads as doc-gap enhancement entries — so the contract self-improves.

Files changed:

• .claude/skills/falcon/PROTOCOL.md — Step 2 population logic; Worker Lifecycle Step 2b
• .claude/skills/falcon/REFERENCE.md — dispatch yaml + worker return contract fields
• .claude/docs/work-item-templates.md — ## Required Context section (hard-bind for cynefin complicated/complex beads)

Token tracking + effort metrics (new infrastructure)

Problem: Effort Forecasts on work items were never compared against reality — no actuals existed, so forecasts couldn't calibrate.

Solution: A complete measurement loop: scripts/token-tracking.py (stdlib-only Python 3, zero dependencies — no jq) bookmarks transcript line offsets and sums per-phase token/turn actuals per bead, with cross-session resume, orphan recovery, and a --coordinate mode for multi-bead planning cost. /leroy starts tracking at claim; /wrapup Task 3c flushes segments to metrics.jsonl (validated by schemas/metrics.schema.json); scripts/velocity-report.py reports forecast accuracy by cynefin domain, size, and phase.

Files changed:

• .claude/scripts/token-tracking.py — the tracker (new)
• .claude/scripts/velocity-report.py — analysis reader (new)
• .claude/metrics.jsonl — committed-by-default data file (new, empty)
• .claude/docs/metrics-schema.md + .claude/schemas/metrics.schema.json — record contract (new)

5-phase Effort Forecast contract + bead linter

Problem: Forecasts and actuals used inconsistent phase vocabularies (3-phase forecasts vs 5-phase actuals produce 3–25× false-overrun signals), and nothing enforced bead quality before triage:ready.

Solution: One strict phase model — plan / discover / implement / test / fix (+ coordinate) — across templates, tracker, and metrics. New scripts/check-bead-contract.py (CONTRACTS_VERSION 1.2) lints beads in 6 modes with severity-by-tier: HARD failures only for triage:ready items and structural defects, SOFT for backlog/triaged so capture stays frictionless. docs/lint-integration.md ships pre-push hook, CI step, and /wrapup integration recipes.

Files changed:

• .claude/scripts/check-bead-contract.py (new), .claude/docs/lint-integration.md (new)
• .claude/docs/work-item-templates.md — 5-phase Effort Forecast with full-shape and clear-chore examples

Typed YAML artifacts + JSON Schema validation

Problem: enhancements.md and standards-history.md were write-only freeform files — categories collided, entries had no lifecycle, and nothing validated handoff.yaml/changelog.yaml shapes.

Solution: Five JSON Schemas (draft 2020-12) under .claude/schemas/; enhancements.yaml (typed entries: 6 kinds, per-kind state machines) and standards-history.yaml (slug-keyed rules, ID-bearing firings, renumber-safe section_ref) replace the markdown forms. Every YAML artifact carries a # yaml-language-server: $schema= header for live editor validation. Markdown docs remain as human references that cite the schemas as the contract.

Files changed:

• .claude/schemas/{handoff,changelog,enhancements,standards-history,metrics}.schema.json (new)
• .claude/enhancements.yaml, .claude/standards-history.yaml (new; legacy .md forms removed)
• .claude/docs/{enhancements,standards-history}-schema.md (new); handoff/changelog schema docs cross-referenced

/wrapup 2.4.0 → 2.13.2 — tier detection + --minimal

Problem: Every wrapup ran the full ritual regardless of session size; measured field-deployment data showed low-frequency tasks burning 300–500k tokens of ceremony in sessions where they produced nothing.

Solution: Tier Detection pre-check gates synthesis tasks on actual session shape; --minimal runs verify + commit + handoff only (typo fixes, checkpoints) with auto-fallback to the full ritual when substantive markers are detected; Task 9 defaults to a focused self-reflection retro (interactive 6-question mode behind --feedback); new Task 9b verification sweep consolidates three look-around tasks into one; Task 3c (token-tracking flush) runs unconditionally — calibration data is never skipped. Measured: ~30% median wrapup savings, ~73% on qualifying --minimal sessions.

/leroy 2.4.1 → 2.9.0 + navigator-recon 1.2.0 → 1.5.0 — startup tiers

Problem: Session startup cost the same whether resuming a known bead or planning fresh multi-bead work (~9M eff-tokens median).

Solution: --minimal continuation mode (skips health checks, history, and specialist routing; single corpus fetch — ~50% savings), --skip-health flag, cynefin-gated specialist routing (clear beads present their own body as the plan; saves ~250k tokens on ~35% of claims), session tracker schema v3 with per-bead phase tracking starts, and navigator-recon's Required Context parsing + enhancements alerts with empty-state suppression.

Session infrastructure: hooks + statusline ship in the kit

Problem: Session ID and transcript path (needed by token tracking) had no reliable in-context source; statusline lived at an inconsistent path.

Solution: hooks/session-start.sh injects session ID + transcript path at SessionStart; hooks/statusline.sh moves to the hooks directory; settings.json ships with both registered. Convention: hooks/ = Claude-Code-auto-fired, scripts/ = workflow/user/CI-invoked.

README rewrite

Full front-door rewrite: architecture overview, three install paths, autopilot quick starts, cost model with measured medians, and a "What this distribution contains" inventory.

Schema / API Changes

All additive — no breaking changes for existing dispatches:

• Dispatch yaml: new required_context[] field (nullable; absent = v7.2.x behavior)
• Worker return contract: new per-bead unlisted_context_reads[]
• New metrics.jsonl record contract (schema_version: 1, two record_type discriminators)
• /leroy session tracker JSON bumped to schema v3 (worked_beads object form)
• Legacy enhancements.md / standards-history.md removed in favor of typed YAML (see Upgrading)

Files Changed

Area	Files	Description
Falcon skill	PROTOCOL.md, REFERENCE.md, SKILL.md, changelog.md	Required Context contract; v7.3.0
Commands	commands/wrapup.md (2.13.2), commands/leroy.md (2.9.0)	Tier detection, --minimal, token-tracking integration
Agents	agents/navigator/navigator-recon.md (1.5.0)	Required Context parsing, §9 alerts, continuation mode
Scripts	token-tracking.py, velocity-report.py, check-bead-contract.py	Measurement + lint infrastructure (all new)
Schemas	5 × *.schema.json	Typed artifact contracts (all new)
Hooks	session-start.sh, statusline.sh, settings.json	Session identity injection; path consistency
Docs	metrics-schema.md, enhancements-schema.md, standards-history-schema.md, lint-integration.md, work-item-templates.md	Contracts + recipes
Root	README.md, .gitignore, metrics.jsonl	Front-door rewrite; tracking-state ignores; data stub

Verification

• Secret scan (gitleaks) + pattern sweep clean on the published tree
• All 5 JSON Schemas parse; all YAML artifacts validate against their schemas
• Install smoke test from the published tree: settings.json valid, skill loads, all three scripts execute, session-start hook emits session ID + transcript
• token-tracking.py covered by a 43-case black-box regression suite (happy path, error guardrails, resume/compaction banking, orphan recovery, coordinate mode) — maintained in the development repo

Upgrading from v7.2.x

1. Re-vendor .claude/ (or cherry-pick areas from the Files Changed table)
2. enhancements.md / standards-history.md → typed YAML: archive the old files and start fresh (no migration script; hand-port any entries you still need)
3. If you had a local statusline pointing at .claude/statusline.sh, update the path to .claude/hooks/statusline.sh (shipped settings.json already points there)
4. metrics.jsonl is committed by default; uncomment the .gitignore line if you'd rather keep metrics per-developer-private
5. Existing dispatch files keep working — required_context[] is additive