LOCAL-2026-05-11-3 — Repo as canonical store: P0 + P1 shipped · session

Summary

Continued from LOCAL-2026-05-11-2 (plan ratification). Two adjacent phases of the repo-as-canonical-store-flip workstream landed in one session: P0 (the shared frontmatter library + JSON schemas + non-blocking pre-commit validator) and P1 (the consolidated operator/session-ID resolver). Both are foundational — every subsequent phase of the flip workstream depends on what shipped today. 60/60 tests green, two independent reviews PASS with zero findings. Parallel session shipped P11e (about-page brief) into the vault workstream concurrently — no merge conflicts despite both terminals working in tandem.

What I Did

P0 (Phase 0) — shared frontmatter library + validation:

579f556 — test(frontmatter): RED-state tests committed first, proving they actually fail without an implementation.
60c0917 — feat(frontmatter): scripts/lib/frontmatter.py — stdlib YAML subset with read(), write() (flow-style canonical), and content_hash() (the LF-normalised SHA-256 reference Plan 2's worker will import).
7d761c3 — chore: untrack __pycache__ recursively (an early-commit pycache slipped past the existing gitignore pattern).
6044ab3 — feat(validate): 5 draft-07 JSON schemas (session, workstream, plan, adr, learning) + scripts/validate_frontmatter.py — a stdlib mini-validator supporting only the subset actually used (type / required / properties / enum / const / pattern / items / additionalProperties), with JSON-pointer error paths and --strict flag.
f16828e — feat(hooks): scripts/hooks/pre-commit (warn-only during dogfooding, single-line swap to promote to blocking on 2026-05-18) + scripts/setup.sh Step 5 to install it.
fe567a0 — workstream: P0 [x] + What's Next pointing to P1.

P1 (Phase 1) — consolidated session resolver:

2b6ad0c — feat(session): .claude/operators.yaml (RT for Roman with 3 emails; SK for Sergei with 1) + scripts/session.py (subcommands whoami + claim; resolution chain --email → $OPERATOR → $CLAUDE_USER_EMAIL → git config user.email → halt-with-paste-able-template; O_CREAT | O_EXCL atomic retry 1..99 writing a claim stub so /resume's missing-frontmatter sweep can skip abandoned claims; mtime-busted JSON cache at .claude/state/operator.cache; iCloud / FileProvider path detection with warn-only semantics; hand-rolled YAML parser with 1-indexed line numbers on malformed input) + 21 tests (including a real 20-process subprocess race that asserts 20 distinct stdouts AND 20 files on disk) + CLAUDE.md "iCloud / FileProvider warning" subsection + .gitignore .claude/state/* patterns.
d65963b — workstream: P1 [x] + What's Next pointing to P2.

Decisions Made

TDD with separate RED commit (P0). Tests committed BEFORE implementation, then the impl commit makes them GREEN. Cost: one extra commit. Value: the test file proves it actually loads + asserts against absent symbols (ModuleNotFoundError), so the GREEN state isn't theatre. Worth it for non-trivial contracts (parser semantics, canonical hash).
No fake-TDD for P1. The P1 sub-agent built tests + implementation in one pass — committing them atomically is more honest than splitting after the fact. Alternative considered: ask the agent to write tests in one call, then impl in a second. Rejected — wasted token round-trip and the commit history wouldn't actually show RED→GREEN since both arrived at once.
Hand-rolled YAML parser stays in scripts/session.py, NOT in scripts/lib/frontmatter.py. Frontmatter library remains scoped to flat mappings (the only shape every markdown file uses). .claude/operators.yaml's nested-list-of-mappings shape lives where it's consumed. Avoids dragging the frontmatter library into more YAML surface than it needs to support.
Cache file is JSON, not YAML. json.load is safe-by-construction (no code execution). mtime check (float(cached_mtime) == operators_path.stat().st_mtime) is precise — caught by the test that does os.utime with a future timestamp.
additionalProperties: true on all 5 schemas. Legacy keys (notion_session_id_note, filename_note, session_id, date_started, notion_page_id: pending-reconcile) must pass through during the Phase 8 backfill grace period. We're catching drift, not enforcing closed shapes.
Pre-commit hook warn-only until 2026-05-18 then promoted to blocking. Single-line swap (exit 0 → exit $rc). Date hard-coded in the hook script's header.
Parallel sub-agent coordination — write only; main thread commits centrally. Agents produce files; I commit. No race on the post-commit auto-push hook; clean git history with one commit per logical unit instead of three interleaved.
Anthropic /security-review over a custom Agent dispatch for security audit. Purpose-built skill correctly excluded the 5 LOW/MEDIUM defence-in-depth flags from the general-purpose audit. Better signal-to-noise.

For Future Me

/build repo-as-canonical-store-flip starts at P2 next session — scripts/hooks/session_state.py (PostToolUse hook). Two non-negotiable design constraints: (a) fcntl.flock(LOCK_EX) + unique per-invocation tmp filenames (PID + ns timestamp) + orphan tmp sweep (>1h). Atomic-rename alone is INSUFFICIENT — this was the FAIL-1 finding from the original council review and the workstream calls it out as the load-bearing test gate. (b) Canonical-key aggregation: every mcp__notion_offplan__* tool name flattens into tool_calls_breakdown.mcp__notion_offplan (the falsifiable architecture invariant). Hook must NEVER block the agent loop — wrap everything in try/except, log to .claude/state/hook-errors.log, exit 0 unconditionally. Register in committed .claude/settings.json (NOT .local.json) so Sergei gets the hook on git pull. Tests: 50-parallel race → tool_calls_count == 50 exactly AND aggregation test → 3× mcp__notion_offplan__API-post-page → canonical counter = 3 AND methods breakdown shows the long name = 3.
Mirror the 20-process subprocess race pattern from P1's atomic-create test for the 50-parallel hook race. Real subprocess.Popen, not threads — OS-level concurrency is what we're testing.
Pre-commit hook auto-installs only via bash scripts/setup.sh — Sergei needs to re-run setup after pulling. Mention this in the very next session's handoff if it hasn't surfaced.
Phase 8 backfill scope is now concrete: 97 files — 24 plans + 19 workstreams + 38 sessions + 16 ADRs. Zero non-kind violations anywhere in the four trees today. Backfill is purely mechanical: add kind: + external_id: (filename-derived for sessions to preserve the CONV-30 trinity).
The parallel session shipped P11e (about-page) into workstreams/repo-as-canonical-store-vault.md (commit f7a534f). Reference if the about-page surfaces in a later /resume.
Dogfooded the schema. This session note has kind: session + external_id: session/LOCAL-2026-05-11-3 set; scripts/validate_frontmatter.py docs/sessions/LOCAL-2026-05-11-3.md exits 0 cleanly. Future sessions should follow the same shape (it's also what Phase 5 of the plan locks in).
iTerm tab title — I forgot to rename the tab this session. Next session, do that early so parallel terminals stay distinguishable.

Learnings

Sub-agent parallelism with strict "write only — main thread commits" rule works smoothly for 3-5 agents at a time. Wall-time savings: ~3.5 min for P0's three deliverables (schemas / validator / hook) where serial would have been 10-15 min. Context window stayed lean — context % barely moved across the whole session. Replicate this pattern for any future multi-deliverable phase where the deliverables don't depend on each other's internals (only on agreed interfaces).
Anthropic's /security-review skill is purpose-built for "concrete vulns in pending changes" and correctly produced zero false positives on tightly-scoped Python code. Worth using preferentially for security passes over a generic Agent dispatch, which would emit defence-in-depth noise. The skill's harness rules (env vars trusted, race conditions only if concretely problematic, etc.) are well-calibrated for developer tooling. Now know there's a tier system: /review (PR-only), /audit (generic quality), /security-review (vuln-focused) — pick by surface.
Hand-rolled stdlib YAML parsers are surprisingly viable when scoped narrowly. The frontmatter parser (flat-only, single-line) is ~150 lines; the operators.yaml parser (nested list-of-mappings) inside session.py is ~80. Combined, less code than depending on PyYAML and trying to lock its version. Stdlib-only mandate paid off — zero pip install footprint for the entire flip workstream.

Open Questions

Pre-commit hook promotion criteria for 2026-05-18 [OPEN] — should the swap from warn-only to blocking be purely date-based, or wait for "no warnings observed for N days"? Defer to closer to the date. The promotion is a one-line edit anyway.
Phase 8 backfill: should it touch docs/sessions/done/? [OPEN] — probably skip done sessions (terminal state; not load-bearing for /resume). Worth a sentence in Phase 8's plan body when we get there.

Resume Prompt

Start /build repo-as-canonical-store-flip at P2 — scripts/hooks/session_state.py (PostToolUse hook, per-session JSON state at .claude/state/session-<id>.json). Non-negotiables: fcntl.flock(LOCK_EX) + unique per-invocation tmp filenames (PID + ns timestamp) + orphan tmp sweep (>1h); canonical-key aggregation flattening every mcp__notion_offplan__* into tool_calls_breakdown.mcp__notion_offplan. Hook must NEVER block the agent loop — wrap in try/except, log to .claude/state/hook-errors.log, exit 0 unconditionally. Register in committed .claude/settings.json (NOT .local.json) so Sergei gets the hook on git pull. Tests: 50-parallel race → tool_calls_count == 50; aggregation test → 3× mcp__notion_offplan__API-post-page → canonical counter = 3 AND methods breakdown = 3. Mirror the 20-process subprocess race pattern from P1's atomic-create test. Confidence: H. Estimate: 1-2 hours.

Watch out for: PostToolUse hook concurrency model is undocumented by Anthropic — the plan assumes parallel and hardens with flock; works regardless. The hook timeout in .claude/settings.json should be 3s. Cold-start ~150-300ms is acceptable; if profiling shows the agent loop lagging later, a bash + jq rewrite is the documented fallback.

After P2 lands, pull main to pick up any parallel-session work (vault workstream + P11e about-page may have additional commits), then proceed to P3 (/handoff rewrite — Notion-silent).