Auto-migrate legacy context logs during scaffold sync

[ssheld]

Summary

• auto-migrate recognized legacy agent-vault/context-log.md layouts before syncing the stricter tracked hook
• warn and no-op on missing or unrecognized layouts instead of guessing
• add regression coverage and a real legacy fixture for the migration path

Verification

• bash -n scripts/update-project.sh scripts/test-session-metadata-hook.sh scaffold/agent-vault/_assets/hooks/pre-commit
• ./scripts/test-session-metadata-hook.sh
• ./scripts/check-policy-mirrors.sh
• git diff --check

Fixes #84

[ssheld]

🤖 Review by Claude Opus 4.6 · via Claude Code
Formal review state unavailable: self-review limitation

No findings above the confidence threshold.

I traced through the classifier, migration logic, and test scenarios in detail. This is a solid implementation of the agreed plan from #84.

Classifier verification (classify_context_log_layout):

• missing: file doesn't exist → no-op. ✓
• current: ## Current Snapshot before ## Entries, and either no entry headings exist, or they come after ## Entries, or historical wrappers are present (already migrated). ✓
• legacy-known: entry headings (including at least one em-dash heading) appear before ## Current Snapshot, which appears before ## Entries, no historical wrappers. ✓
• unknown: everything else → warning + no-op. ✓

The em-dash requirement for legacy-known is the right conservative choice — it limits auto-migration to the specific known scaffold-emitted pattern. Repos with only regular-hyphen entries before the snapshot get the unknown warning, which is safer than guessing.

Date consistency in migration (migrate_legacy_context_log_if_needed):

• Frontmatter last_updated: $today ✓
• Current Snapshot Last updated: $today ✓
• Migration entry timestamp: $now_local (whose date portion = $today) ✓

All three derive from date calls at script startup (lines 148-149). The validator will see matching dates. Verified that the end-to-end test (run_hook_expect_success after staging the migrated file) would catch any mismatch.

Migration placement (line 851):
migrate_legacy_context_log_if_needed runs after managed docs are synced but before _assets/hooks/pre-commit is synced. This matches the plan discussion — the context-log is validator-compatible before the stricter hook arrives on disk. ✓

Scaffold hook fix (line 242-243):
Removes the dead empty agent-vault/context-log.md) case branch from the scaffold's pre-commit. This was already validated in the generated CritterCam repo (PR ssheld/critter-cam#194); now the scaffold source matches. ✓

Test coverage (4 new scenarios):

1. missing — file deleted before sync → no migration output, no warning. ✓
2. legacy-known dry-run — file unchanged, output shows what would happen. ✓
3. legacy-known real migration — file restructured, all historical sections present, then a substantive staged change passes the hook end-to-end. ✓ (This is the critical test.)
4. unknown — unrecognized layout left unchanged, skip + warning messages verified. ✓

Test fixture (scripts/test-fixtures/context-log/legacy-known.md):
Modeled on the real pre-migration CritterCam layout: em-dash entry heading before ## Current Snapshot, snapshot and entries at the bottom, regular-hyphen entry under ## Entries. The fixture's hardcoded last_updated: 2026-03-25 doesn't affect the test because the migration overwrites frontmatter with the runtime $today.

Minor observations (sub-threshold):

• If a legacy context-log lacks the # Context Log heading entirely, prefix_start_line defaults to 1 and the frontmatter would be captured into ## Legacy Unindexed Entries alongside the entry content (cosmetic duplication, since migration writes fresh frontmatter). Unlikely for scaffold-generated files since the heading has always been present.
• today and now_local are computed once at script startup. A sync that crosses midnight would produce a stale date in the migration entry. Negligible for a script that completes in seconds.

Strengths

• Directly implements the plan agreed in #84, including all six feedback points from the discussion (migration-before-hook-sync, four-bucket classifier, concrete legacy-known heuristics, single-source date, warning + no-op for unknown, real fixture data).
• The replace_file_from_tmp helper reuses existing safety infrastructure (validate_write_path, assert_not_symlink, backup semantics, dry-run support) rather than reimplementing it.
• The end-to-end test (migrate → stage substantive change → hook passes) is the most valuable test case and exercises the full integration path.

Merge Recommendation

Approve

Top Risks

• Legacy repos that used only regular-hyphen entries before the snapshot (no em-dashes) will get the unknown warning instead of auto-migration. This is the correct conservative behavior, but could generate support questions from repos that expect auto-migration. The warning message includes clear remediation steps.
• The migration is one-way: once the file is restructured, re-running update-project.sh classifies it as current and skips it. The backup in agent-vault/context/updates/<timestamp>/ is the recovery path.

Suggested Additional Tests

• None — the four scenarios cover missing, current (implicit via freshly bootstrapped repos in existing tests), legacy-known (real + dry-run), and unknown.