[M055] Top-Level Docs Accuracy Pass

[keithah]

Roadmap source: kodiai-roadmap.md

• Phase: Phase 2 — Truthful Planning Surface
• Milestone: M055

Slice M055/S01 — README + CHANGELOG alignment

What this is

README.md states "30 milestones shipped (v0.1 through v0.30)." The actual shipped count per .gsd/milestones/ + PROJECT.md is well above 50; CHANGELOG.md is up to date through v0.30 (2026-04-19) / M052. The README's featureset list also predates M045–M047's contributor-experience redesign and M052's Slack webhook relay.

Acceptance criteria

• README milestone count matches the most recent completed milestone.
• README feature list mentions: contributor experience contract (M045), contributor tier calibration (M046/M047), manual rereview contract (M051), Slack webhook relay (M052).
• Nightly workflows (.github/workflows/nightly-issue-sync.yml, nightly-reaction-sync.yml) are described in README — what they do, what they sync, what happens on failure.
• CHANGELOG has a short entry for each M053+ milestone as they ship (this slice adds a template section).

Files to touch

• README.md, CHANGELOG.md.

Verify contract

• Command: bun run verify:m055:s01
• Script: scripts/verify-m055-s01.ts
• Check IDs: readme_milestone_count_current, readme_mentions_recent_features, readme_documents_nightly_workflows.
• Status codes: m055_s01_ok, m055_s01_stale_count, m055_s01_missing_feature_mention.

Slice M055/S02 — LICENSE and CONTRIBUTING expansion

What this is

The repo has CONTRIBUTING.md, CHANGELOG.md, and README.md but no LICENSE file. Usage rights are legally ambiguous. CONTRIBUTING.md is 99 lines and covers the test suite + PR process, but does not cover: migration .down.sql requirement, .gsd/ planning structure, milestone/slice naming convention, verify-script contract, or the "every slice summary must reference its verify script" rule.

Acceptance criteria

• LICENSE file exists at repo root. Decide: Apache-2.0, MIT, or Business Source License? Record the choice in a DECISIONS.md entry (D-M055-01).
• CONTRIBUTING.md gains sections for: GSD v2 planning layout (.gsd/), milestone folder convention (link to M051 as exemplar), verify script contract, migration rules (up + down required, CI-gated), test-writing expectations (every new src/ file ships with a .test.ts sibling unless justified).
• package.json gains an "engines" constraint — see M058/S02 which will close the same gap from the CI side. This slice just writes the contributor expectation.

Files to touch

• LICENSE — create.
• CONTRIBUTING.md — expand.
• .gsd/DECISIONS.md — append D-M055-01 (license choice rationale).

Verify contract

• Command: bun run verify:m055:s02
• Script: scripts/verify-m055-s02.ts
• Check IDs: license_file_present, contributing_covers_gsd_v2, contributing_covers_migration_rules, contributing_covers_verify_contract.
• Status codes: m055_s02_ok, m055_s02_missing_license, m055_s02_missing_section.

Slice M055/S03 — docs/ runbook audit

What this is

docs/ exists but has not been inventoried against current operational surfaces. Things likely missing: deploy rollback runbook (what do you do when a migration without .down.sql needs to be reverted?), key rotation for GITHUB_PRIVATE_KEY / ANTHROPIC_API_KEY, Slack webhook relay operational guidance (M052 added the runbook but may not cover failure modes), ACA job debugging (how to inspect a failed job's result.json).

Acceptance criteria

• docs/ is inventoried in a single docs/INDEX.md listing every doc and its purpose.
• At minimum the following runbooks exist (new or updated): docs/runbooks/deploy-rollback.md, docs/runbooks/key-rotation.md, docs/runbooks/aca-job-debugging.md, docs/runbooks/nightly-sync-failures.md.
• Each runbook references at least one structured log tag, one command, and the owning milestone or decision.
• Any command mentioned in a runbook actually exists in package.json or scripts/.

Files to touch

• docs/INDEX.md, docs/runbooks/*.md.

Verify contract

• Command: bun run verify:m055:s03
• Script: scripts/verify-m055-s03.ts
• Check IDs: docs_index_present, required_runbooks_present, runbook_commands_resolve.
• Status codes: m055_s03_ok, m055_s03_missing_runbook, m055_s03_broken_command_reference.

---

Phase 3 — Code Safety Net

Theme: Close the test and rollback gaps that would bite on a bad deploy. Harden CI so these gaps can't silently reappear.

Sequencing rationale: M056 first because schema rollbacks unblock operational safety for everything else. M057 second because test coverage gaps will reveal themselves as CI churn once we land M058's broadened matrix. M058 last because the CI changes only pay off after coverage is actually there to run.

Milestone	Title	Slices
M056	Migration Rollback Completeness	S01, S02, S03
M057	Core Handler & Webhook Test Backfill	S01, S02, S03, S04
M058	CI Workflow Hardening	S01, S02, S03

[keithah]

Prioritization note:

• Parallelizable docs pass.
• Do not block runtime or safety-net work on this.
• Best timing: after [M054] GSD v2 Planning Artifact Repair #93 starts, and in parallel with [M056] Migration Rollback Completeness #95/[M057] Core Handler & Webhook Test Backfill #96/[M058] CI Workflow Hardening #97 once those are in motion.