Skip to content

Commit 1c77aed

Browse files
claudeclaude
committed
docs(handover): add HANDOVER-INDEX.md navigation map
Closes Audit-A new-doc gap #5: docs/handover/ has grown to 13 files (L1/L2/L3 prompts, S4/S5 runbooks, suggest CLI, theorem metadata) without a current map. This index groups them by type (prompt / runbook / plan / state), notes pre-conditions, and cross-references ROADMAP stage IDs to the handover artefact that drives each. https://claude.ai/code/session_01YPqu7gti4azBach6ZvpRFJ
1 parent 8eeed79 commit 1c77aed

1 file changed

Lines changed: 92 additions & 0 deletions

File tree

‎docs/handover/HANDOVER-INDEX.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
<!-- SPDX-License-Identifier: MPL-2.0 -->
2+
<!-- SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> -->
3+
4+
# Handover Index
5+
6+
**Status**: canonical map of the `docs/handover/` suite. Last revised: 2026-05-26.
7+
8+
Each file in this directory is either:
9+
- a **prompt** — a self-contained brief for the next agent to execute a named
10+
workstream, OR
11+
- a **runbook** — an operational guide for a now-live workstream, OR
12+
- a **plan** — a multi-sprint coordination document, OR
13+
- a **state log** — running notes from prior sessions.
14+
15+
Read this index first to know which file is which.
16+
17+
## Active prompts (next agent picks one to execute)
18+
19+
| File | Workstream | Pre-condition | Effort |
20+
|---|---|---|---|
21+
| [`L1-CAPNPROTO-PROMPT.md`](L1-CAPNPROTO-PROMPT.md) | Stage 5a — Cap'n Proto IPC | L3 hand-off green ≥ 7 days | ~2 sprints |
22+
| [`L2-CHAPEL-PROMPT.md`](L2-CHAPEL-PROMPT.md) | Stage 5b — Chapel L2.2+ (speculative search, corpus-parallel, multi-locale) | L1 landed | ~4 sprints |
23+
| [`L3-LIVE-PROVER-CI-PROMPT.md`](L3-LIVE-PROVER-CI-PROMPT.md) | Stage 5d — Tier-4 live-CI provisioning | Tier-1 main CI green ≥ 7 days | ~1 sprint |
24+
| [`PHASE-3-PROMPT.md`](PHASE-3-PROMPT.md) | Modal + real-algebraic backends (Wave-2 follow-on) | Wave-2 done | ~1 sprint |
25+
| [`SUGGEST-CLI-PROMPT.md`](SUGGEST-CLI-PROMPT.md) | `suggest` verb implementation | None | ~3 days |
26+
27+
## Active runbooks (live workstream is in production)
28+
29+
| File | What it covers |
30+
|---|---|
31+
| [`S4-LOOP-CLOSURE-RUNBOOK.md`](S4-LOOP-CLOSURE-RUNBOOK.md) | VeriSim learning-loop end-to-end test (`just test-s4-loop`) and operational verification |
32+
| [`S5-VERIFICATION-RUNBOOK.md`](S5-VERIFICATION-RUNBOOK.md) | Trained-GNN-weights verification flow: `just train-cpu` → `/gnn/health` → `just eval` |
33+
34+
## Plans (multi-sprint coordination)
35+
36+
| File | Scope |
37+
|---|---|
38+
| [`PRODUCTION-WIRING-PLAN.md`](PRODUCTION-WIRING-PLAN.md) | Three-tier (L1 Cap'n Proto / L2 Chapel / L3 live CI) production-wiring plan. L1 prompt is the executable derivative. |
39+
40+
## Deferred-work trackers
41+
42+
| File | Tracks |
43+
|---|---|
44+
| [`THEOREM-METADATA-MIGRATION.md`](THEOREM-METADATA-MIGRATION.md) | Future migration of 8 parser-site structural meta-tags out of `Theorem.aspects` into a dedicated `TheoremKind` field. Boundary filter contains the damage; this is hygiene. |
45+
46+
## State & navigation
47+
48+
| File | What it is |
49+
|---|---|
50+
| [`TODO.md`](TODO.md) | Living backlog. Single source of truth for "what's next" between sprints. P0–P4 priority bands. |
51+
| [`STATE.md`](STATE.md) | Running human-readable state log. Complement to `.machine_readable/6a2/STATE.a2ml`. |
52+
| [`README.md`](README.md) | Original handover suite intro (older; kept for orientation). |
53+
54+
## Warmup material
55+
56+
| File | Audience |
57+
|---|---|
58+
| [`llm-warmup-dev.md`](llm-warmup-dev.md) | LLM session warmup for contributors |
59+
| [`llm-warmup-user.md`](llm-warmup-user.md) | LLM session warmup for end-users |
60+
61+
## Execution order (when starting a fresh sprint)
62+
63+
1. Read `STATE.md` (or `STATE.a2ml`) for the current sprint state.
64+
2. Read `TODO.md` for the prioritised backlog.
65+
3. Pick the next-up prompt from "Active prompts" whose pre-condition is met.
66+
4. Execute the prompt; cite this index in commits if you reorder priorities.
67+
5. When a prompt is "consumed" by completion, retire it into the git-history
68+
archive — do not leave consumed prompts alongside active ones.
69+
70+
## Stage cross-reference
71+
72+
Maps `docs/ROADMAP.md` stage IDs to the handover artefact that drives each:
73+
74+
| Stage | Drives | Artefact |
75+
|---|---|---|
76+
| 2a/2c | GNN training + eval | `S5-VERIFICATION-RUNBOOK.md` |
77+
| 3a/3b | Verisim read paths | `S4-LOOP-CLOSURE-RUNBOOK.md` (done) |
78+
| 3c | Outcome emission wiring | Stage-3c plan in chat history (no dedicated handover yet — to be written when work begins) |
79+
| 4c/4d | `suggest_tactics` GNN ranking | `SUGGEST-CLI-PROMPT.md` |
80+
| 5a | Cap'n Proto IPC | `L1-CAPNPROTO-PROMPT.md` |
81+
| 5b | Chapel L2.2+ | `L2-CHAPEL-PROMPT.md` |
82+
| 5d | Tier-4 live CI | `L3-LIVE-PROVER-CI-PROMPT.md` |
83+
84+
## When this index goes stale
85+
86+
Update conditions:
87+
- A prompt is completed → move it to a `archive/` subdirectory or delete and note in this file.
88+
- A new prompt is added → add a row to the appropriate section.
89+
- A stage status changes in `docs/ROADMAP.md` → update the cross-reference table.
90+
91+
Quick check: `ls docs/handover/*.md | wc -l` should match the number of rows
92+
across all tables above. As of 2026-05-26, this file accounts for 13 entries.

0 commit comments

Comments
 (0)