docs: V1 completion handoff after 5-hour supervision sprint #33
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,77 +1,214 @@ | ||||||
| # Claude Kingdoms — V1 Completion State (2026-05-08, end of 5-hour supervision sprint) | ||||||
|
|
||||||
| ## TL;DR | ||||||
|
|
||||||
| **Repo HEAD on `main`:** the merge after PR #32 (`37706b2` at sprint | ||||||
| end; latest in any session run `git log --oneline -5` to confirm). | ||||||
| **Tests passing on `main`:** 262. | ||||||
| **Audit closure:** every P0, P1, and P2 item identified in | ||||||
| `docs/audit-2026-05-08.md` is closed at the architecture+code level. | ||||||
| **Kanban:** all Kingdoms milestones (M0, M1, M2, M3) marked done with | ||||||
| real `--result` summaries; only the audit-followup task `t_26404be3` | ||||||
| sits `blocked` (Hermes protocol violation; the work itself shipped via | ||||||
| claude-code in PRs #23–#32). | ||||||
|
|
||||||
| The remaining V1 launch holdouts all require an **Unciv runtime** or | ||||||
| **human-side action** — they cannot be closed from inside CI: | ||||||
|
|
||||||
| 1. README GIF capture (acceptance #11) — needs the Unciv map rendered | ||||||
| 2. M4 fun-factor playtest — needs Unciv to actually play the campaign | ||||||
| 3. `good first issue` GitHub-side label — five candidate bodies are | ||||||
| ready in `docs/good-first-issues.md`; one `gh issue create` per | ||||||
| surfacing | ||||||
| 4. M5 community launch artifacts (changelog, release tag, launch posts) | ||||||
|
|
||||||
| ## Sprint output | ||||||
|
|
||||||
| **11 PRs merged in 5 hours**, all green CI: | ||||||
|
|
||||||
| | PR | Audit ref | Summary | | ||||||
| |----|-----------|---------| | ||||||
| | #22 | the audit | CTO audit doc landed | | ||||||
| | #23 | P0 #1 | `SessionStatus` enum gains `INACTIVE` + `REDIRECTED` (PRD §BR-1, §BS-7) | | ||||||
| | #24 | P0 #3 | `Stop` hook transitions to `COMPLETED` on explicit signal (PRD §CL-3) | | ||||||
| | #25 | P0 #2 | Bridge–TUI JSON schema realigned with PRD line 231's 13 minimum fields | | ||||||
| | #26 | BR-9 | Structured audit log persistence (`bridge/audit_log.py`, JSONL) | | ||||||
| | #27 | #11 + #12 | `CONTRIBUTING.md` four contribution paths + README GIF placeholder | | ||||||
| | #28 | GM-8 | Per-tile session status indicators (bridge emits + mod.lua glyphs) | | ||||||
| | #29 | GM-5 | Visible plan/goal/redirect bonus announcements per turn | | ||||||
| | #30 | #9 + #20 | Tutorial → campaign flow state machine + scenario JSONs | | ||||||
| | #31 | #19 | Visible next-frontier per session in TUI | | ||||||
| | #32 | TU-9 + #13 | BridgeView schema-only adapter + `good first issue` candidate doc | | ||||||
|
|
||||||
| **Test count growth across the sprint:** 149 → 262 (+113 tests). | ||||||
|
|
||||||
| ## Per-PRD-requirement closure | ||||||
|
|
||||||
| ### Bridge Layer (BR-1 → BR-11) | ||||||
|
|
||||||
| | ID | Status | Closure ref | | ||||||
| |----|--------|-------------| | ||||||
| | BR-1 | ✅ | PR #23 (enum gains INACTIVE/REDIRECTED) | | ||||||
| | BR-2 | ✅ | M0 (`bridge_loop.process_turn`) | | ||||||
| | BR-3 | ✅ | PR #25 (per-session breakdown in schema) | | ||||||
| | BR-4 | ✅ | M0 + PR #23 (REDIRECTED keeps base reward, no clawback) | | ||||||
| | BR-5 | ✅ | M2 (handle_redirect + listener) + PR #23 (REDIRECTED state) | | ||||||
| | BR-6 | ✅ | M2 (plan bonus +15 production) | | ||||||
| | BR-7 | ✅ | M2 (goal bonus +60 across gold + science) | | ||||||
| | BR-8 | ✅ | M2 (token bonus capped at 10 units × 2) | | ||||||
| | BR-9 | ✅ | PR #26 (audit log JSONL persistence) | | ||||||
| | BR-10 | ✅ | M1 (SaveExchange file polled by mod.lua) | | ||||||
| | BR-11 | ✅ | M2 (TUI manual injection bindings) | | ||||||
|
|
||||||
| ### Bridge & Save-State (BS-1 → BS-7) | ||||||
|
|
||||||
| | ID | Status | Closure ref | | ||||||
| |----|--------|-------------| | ||||||
| | BS-1 | ✅ | PR #25 (versioned per-session breakdown on disk) | | ||||||
| | BS-2 | ✅ | Spike 1 / mod.lua reads kingdom_save.json | | ||||||
| | BS-3 | ✅ | M0 (no Kotlin fork; pure JSON + Lua mod) | | ||||||
| | BS-4 | ✅ | Architectural — bridge is engine-decoupled | | ||||||
| | BS-5 | ✅ | M1 (process_turn is the only write path) | | ||||||
| | BS-6 | ✅ | M1 (no-decay invariant tests) | | ||||||
| | BS-7 | ✅ | PR #23 (INACTIVE distinct from SUSPENDED) | | ||||||
|
|
||||||
| ### Claude Integration (CL-1 → CL-6) | ||||||
|
|
||||||
| | ID | Status | Closure ref | | ||||||
| |----|--------|-------------| | ||||||
| | CL-1 | ✅ | M2 (UserPromptSubmit / Stop / idle threshold) | | ||||||
| | CL-2 | ✅ | M2 (PermissionDenied) + PR #23 (REDIRECTED state) | | ||||||
| | CL-3 | ✅ | PR #24 (Stop with completion signal → COMPLETED) | | ||||||
| | CL-4 | 🟡 | `docs/hooks-setup.md` documents; per-hook opt-in toggle would be a polish PR | | ||||||
| | CL-5 | 🟡 | Capture+replay path documented; no one-command install/uninstall | | ||||||
| | CL-6 | 🟡 | SubagentStart type=Plan handled; ultraplan-specific signal not yet differentiated | | ||||||
|
|
||||||
| ### Game Layer (GM-1 → GM-10) | ||||||
|
|
||||||
| | ID | Status | Closure ref | | ||||||
| |----|--------|-------------| | ||||||
| | GM-1 | ✅ | mod/ClaudeKingdoms/ install path documented per OS | | ||||||
| | GM-2 | ✅ | PR #16 (Nations.json: The Operators civ) | | ||||||
| | GM-3 | ✅ | PR #16 (Buildings.json: Session Forge + Charter Hall) | | ||||||
| | GM-4 | ✅ | mod.lua per-city reward application | | ||||||
| | GM-5 | ✅ | PR #29 (per-city event announcements) | | ||||||
| | GM-6 | ❌ | Image asset — requires artist / asset pipeline | | ||||||
| | GM-7 | ❌ | Image asset — same | | ||||||
| | GM-8 | ✅ | PR #28 (per-tile status indicators with glyph map) | | ||||||
| | GM-9 | 🟡 | Save format unmodified; multiplayer untested | | ||||||
| | GM-10 | ✅ | PR #30 (LongRunningCampaign scenario, victoryConditions=[], noForcedEnd=true) | | ||||||
|
|
||||||
| ### TUI Sidecar (TU-1 → TU-9) | ||||||
|
|
||||||
| | ID | Status | Closure ref | | ||||||
| |----|--------|-------------| | ||||||
| | TU-1 | ✅ | M0 (Textual) | | ||||||
| | TU-2 | 🟡 | Single combined view; multi-slot layout deferred | | ||||||
| | TU-3 | ❌ | "Launch session from a slot" UI affordance not yet added | | ||||||
| | TU-4 | ✅ | PR #23 (state badges include all PRD states) | | ||||||
| | TU-5 | ✅ | M0 (TurnEstimatePanel) | | ||||||
| | TU-6 | 🟡 | Bindings labeled but no "DEV" disclaimer text | | ||||||
| | TU-7 | ✅ | M0 (Textual handles SSH/remote terminals) | | ||||||
| | TU-8 | ✅ | M0 + PR #13 (parchment palette, footer hints) | | ||||||
| | TU-9 | ✅ | PR #32 (BridgeView schema-only adapter; existing direct-state callsites flagged for migration) | | ||||||
|
|
||||||
| ### V1 Acceptance Criteria (#1–#21) | ||||||
|
|
||||||
| | # | Status | Closure ref | | ||||||
| |---|--------|-------------| | ||||||
| | 1 | 🟡 | README install steps; not timed | | ||||||
| | 2 | ✅ | Hook stream → real resources end-to-end (PRs #10–#12, #28, #29) | | ||||||
| | 3 | ✅ | M2 + tests | | ||||||
| | 4 | ✅ | M2 + audit log carries the redirect entry | | ||||||
| | 5 | ✅ | PR #29 (visible bonus announcement) | | ||||||
| | 6 | ✅ | PR #29 | | ||||||
| | 7 | 🟡 | TUI parchment yes; Unciv tileset/skin no (image assets) | | ||||||
| | 8 | ✅ | PR #14 (OnboardingScreen) + PR #16 (mod tutorials) | | ||||||
| | 9 | ✅ | PR #30 (Tutorial scenario specifies ≤10 minute budget; flow state machine) | | ||||||
| | 10 | ✅ | 262 tests, CI green on every PR | | ||||||
| | 11 | 🟡 | Placeholder + recording protocol shipped (PR #27); actual GIF needs Unciv runtime | | ||||||
| | 12 | ✅ | PR #27 (CONTRIBUTING.md four paths) | | ||||||
| | 13 | 🟡 | PR #32 ships 5 ready-to-paste candidate bodies; GitHub label is one `gh issue create` away | | ||||||
| | 14 | ✅ | Architectural — no Kotlin fork | | ||||||
| | 15 | ✅ | M1 | | ||||||
| | 16 | ✅ | M1 + PR #21 (load-on-mount) | | ||||||
| | 17 | ✅ | PR #23 (INACTIVE distinct from SUSPENDED) | | ||||||
| | 18 | ✅ | PR #30 (campaign scenario victoryConditions=[]) | | ||||||
| | 19 | ✅ | PR #31 (TUI shows "Next: ..." every refresh) | | ||||||
| | 20 | ✅ | PR #30 (handoff state machine + scenarios) | | ||||||
| | 21 | ✅ | ADR-001, ADR-002 on main | | ||||||
|
|
||||||
| ## What I did NOT touch (and why) | ||||||
|
|
||||||
| - **`hermes` PR push/merge** — pushed and merged 11 PRs through the | ||||||
| sprint; user explicitly approved push+merge for this session window. | ||||||
| - **Production deploy** — not applicable (no Fly.io app for this project). | ||||||
| - **HuggingFace upload** — not applicable. | ||||||
| - **Force-push, --no-verify, --no-gpg-sign** — never used; all hook | ||||||
| failures (none observed) would have been investigated, not bypassed. | ||||||
| - **GitHub `good first issue` label creation** — five candidate bodies | ||||||
| shipped in `docs/good-first-issues.md`; the actual `gh issue create` | ||||||
| is a one-line maintainer task and visible to the public, so I left it | ||||||
| for explicit human approval. | ||||||
| - **Closing the campaign-finalisation kanban tasks** — M0/M1/M2/M3 and | ||||||
| the Unciv mod integration task all closed; M3 was closed with the | ||||||
| caveat that image assets are M4 scope. | ||||||
|
|
||||||
| ## Operational state | ||||||
|
|
||||||
| - **Hermes Agent**: v0.13.0 (was v0.12.0; 279 commits applied today). | ||||||
| `~/.local/bin/hermes` symlink intact. Gateway + dashboard managed by | ||||||
| systemd-user units (auto-restart on crash, 60s backoff). | ||||||
| - **Cron loop**: scheduled job `a5ddf699` was the 30-minute supervision | ||||||
| cadence (`13,43 * * * *`). It is being **deleted at end of cycle 10** | ||||||
| per the original /loop brief. | ||||||
| - **MCP servers**: 7 configured. The `gemini-cli` MCP keeps re-adding | ||||||
| itself via `hermes setup` and failing to load; documented in the | ||||||
| audit doc as P2 #12. Removable with `hermes mcp remove gemini-cli`. | ||||||
| - **Hermes kanban dispatcher**: Hermes hit one protocol violation today | ||||||
| on `t_26404be3` (claimed + commented + exited rc=0 without calling | ||||||
| `kanban_complete`/`kanban_block`). The work itself was picked up by | ||||||
| claude-code and shipped; rule already in Hermes's MEMORY.md from the | ||||||
| earlier discipline pass. | ||||||
|
|
||||||
| ## Resume idiom | ||||||
|
|
||||||
| ```bash | ||||||
| cd C:\Users\caleb\projects\ClaudeKingdoms | ||||||
| git checkout main | ||||||
| git fetch origin && git reset --hard origin/main | ||||||
|
There was a problem hiding this comment. The command
Suggested change
|
||||||
| python -m pytest -q # expect 262 passing (or higher) | ||||||
| python run_tui.py # interactive sandbox | ||||||
| python -m bridge.daemon # production daemon | ||||||
| ``` | ||||||
|
|
||||||
| ## V1-launch checklist (the explicit handoff to humans) | ||||||
|
|
||||||
| - [ ] **Open the 5 GitHub `good first issue`s** — copy bodies from | ||||||
| `docs/good-first-issues.md`, run `gh issue create` per body. | ||||||
| - [ ] **Capture the README GIF** — follow `docs/media/README.md` | ||||||
| shot-list when the M4 campaign map renders. | ||||||
| - [ ] **M4 fun-factor playtest** — actually play the long-running | ||||||
| campaign for a real Pomodoro and confirm the gameplay holds up | ||||||
| independent of the bridge hook. | ||||||
| - [ ] **Image assets** (parchment tileset, illuminated UI skin) — | ||||||
| artist or asset-pipeline pass for GM-6 / GM-7. | ||||||
| - [ ] **M5 release** — tag, changelog, launch posts on r/Unciv, | ||||||
| r/ClaudeCode, Hacker News, ModDB. | ||||||
| - [ ] **OPTIONAL multiplayer V2 RFC** — open as a community RFC after | ||||||
| V1 launches, per PRD §M5. | ||||||
|
|
||||||
| ## Files of interest | ||||||
|
|
||||||
| - `docs/audit-2026-05-08.md` — the audit + closure header | ||||||
| - `docs/good-first-issues.md` — 5 ready-to-paste issue bodies | ||||||
| - `docs/bridge-tui-schema.md` — the binding contract | ||||||
| - `docs/hooks-setup.md` — how to wire Claude Code hooks to the bridge | ||||||
| - `docs/adr/adr-00{1,2,3}.md` — architectural decision records | ||||||
| - `mod/ClaudeKingdoms/scenarios/{Tutorial,LongRunningCampaign}/` — the | ||||||
| scenario manifests + maps | ||||||
| - `bridge/{session_state,scoring,hook_listener,bridge_loop,save_exchange,audit_log,frontier,tutorial,daemon}.py` | ||||||
| — the bridge surface area | ||||||
| - `tui/{app,medieval_voice,onboarding,bridge_view}.py` — the TUI | ||||||
| surface area | ||||||
| - `CONTRIBUTING.md` + this file + the README — top-level docs | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The resume instructions use a hardcoded absolute path (
C:\Users\caleb\...). This makes the documentation environment-specific and less portable for other contributors. It is recommended to use a placeholder likepath/to/ClaudeKingdoms.