create-ccc-tutor 0.1.0

package/template/.harness/skills/next/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: next
+description: Inspect the current workflow state and suggest the next CCC-MAGI command. Use when the user doesn't know which skill to invoke next, or wants a sanity check on workflow progress. Reads constitution.md + spec_dir + git state; does NOT auto-invoke any other skill. Trigger when the user invokes /next OR says any of these (any language; match by intent, not exact wording) — English "what's next", "where am I", "next step", "what should I do", "what now", "I'm lost", "which skill should I run"; 中文「下一步干嘛」「下一步该跑啥」「接下来咋办」「接下来呢」「现在该做啥」「现在该跑哪个 skill」「我该跑啥」「我迷路了」「下一步推荐」; 日本語「次は何」「次どうする」「次のステップ」; 한국어「다음 뭐 해야」「다음 단계」「뭘 해야 돼」; or similar workflow-disambiguation intent in any locale.
+allowed-tools: Read, Bash(test:*), Bash(ls:*), Bash(git rev-parse:*), Bash(git status:*), Bash(git branch:*), Bash(grep:*), Bash(find:*)
+argument-hint: <optional feature name>
+---
+
+# /next
+
+Inspect the current state of the project and the active feature, then **suggest** the next CCC-MAGI command to run. This skill is a wayfinder — it never auto-invokes another skill, never modifies any file. Decision authority stays with the user.
+
+> *Companion to the 9-stage workflow + 13 skills. The harness intentionally requires explicit confirmation at every stage; `/next` reduces the cognitive cost of figuring out which stage you're at without erasing the discipline.*
+
+## Language Awareness
+
+This skill's instructions are in English. When you talk to the user (presenting state, the recommendation, asking clarifying questions), use the user's OS locale language. See `CLAUDE.md § Language Awareness`. File paths, slot names, JSON keys, and skill names (`/feature-draft`, etc.) stay in English regardless of locale.
+
+## What this skill produces
+
+A single human-readable status block in the user's locale that:
+
+1. States the detected feature and inferred workflow stage.
+2. Lists the filesystem signals it read.
+3. Recommends the next command (or asks for disambiguation if state is ambiguous).
+4. Surfaces alternative commands the user might pick instead.
+
+**This skill writes nothing to disk.** It is read-only.
+
+---
+
+## Step 0 — Pre-flight: is CCC-MAGI configured?
+
+Check `.harness/state/install.json` exists:
+
+```bash
+test -f .harness/state/install.json
+```
+
+If it does NOT exist, print exactly:
+
+```
+❌ CCC-MAGI is not configured for this project (no .harness/state/install.json).
+
+Next: run /init to configure.
+```
+
+Then halt the skill. Do not proceed to later steps.
+
+---
+
+## Step 1 — Resolve current feature
+
+If `$ARGUMENTS` is non-empty, use that string (trimmed) as the feature name and skip auto-detection.
+
+Otherwise, auto-detect in priority order:
+
+1. **Git branch name.** Run `git rev-parse --abbrev-ref HEAD 2>/dev/null`. If the branch matches one of these patterns, extract `<name>`:
+   - `feat/<name>-...` or `feat/<name>` (no trailing dash)
+   - `fix/<name>-...` or `fix/<name>`
+   - `audit/<name>-...` or `audit/<name>`
+
+2. **Most recently modified spec file.** Look in `${spec_dir}` (resolved at Step 2) for `<feature>.md` files (exclude `<feature>-plan.md` and `<feature>-implementation.md`). Pick the one with the newest modification time as the candidate feature.
+
+3. **Ask the user.** If neither yields a feature, list any `<feature>.md` files found in `${spec_dir}` and ask:
+
+   ```
+   I couldn't auto-detect which feature you're working on.
+
+   Either:
+     - Tell me the feature name (I'll inspect its state)
+     - Or list active features: I see <list of <name>.md files in spec_dir>
+
+   Wait for user response before continuing.
+   ```
+
+   Wait for the user's reply. Do not guess.
+
+---
+
+## Step 2 — Read constitution.md to find directories
+
+Read `constitution.md` to extract slot values:
+
+- `spec_dir` — feature spec directory. Default fallback: `docs/features/`.
+- `implementation_dir` — implementation notes directory. Default fallback: `docs/features/`.
+- `backend_db_type` — used in Step 3 to decide whether to check for a schema doc.
+
+If `constitution.md` is missing or unreadable, fall back to the defaults above and note the fallback in the final report.
+
+---
+
+## Step 3 — Inspect filesystem state for the feature
+
+Compute these state booleans for the resolved feature. Use the resolved directory values from Step 2.
+
+- `SPEC_EXISTS` — `test -f "${spec_dir}${feature}.md"`
+- `SPEC_FINALIZED` — only if `SPEC_EXISTS`: `grep -q "FINALIZED" "${spec_dir}${feature}.md"`
+- `IMPL_EXISTS` — `test -f "${implementation_dir}${feature}-implementation.md"`
+- `PLAN_EXISTS` — `test -f "${spec_dir}${feature}-plan.md"`
+- `BACKEND_PROJECT` — `backend_db_type` slot is non-empty and not `none`
+- `SCHEMA_DOC_EXISTS` — heuristic: `test -f "${implementation_dir}${feature}-schema.md"` OR any file matching `${implementation_dir}${feature}-schema*.md`. If uncertain after these checks, treat as `false` and note the uncertainty in the report rather than guessing.
+- `GIT_HAS_CHANGES` — `git status --porcelain` returns at least one line.
+- `STATE_AUDITS_EXIST` — `test -d .harness/state/auditor-approvals` AND `ls .harness/state/auditor-approvals/${feature}-*.json 2>/dev/null` returns ≥1 entry.
+- `CHECKPOINT_EXISTS` — `test -f .harness/state/workflow-checkpoints/${feature}.json`
+- `CHECKPOINT_DATA` — if `CHECKPOINT_EXISTS`: parse with `jq '.current_stage, .stages_completed, .stages_skipped, .last_activity_at, .stage_in_progress'` for state cross-check.
+
+If any check errors out (e.g., directories don't exist yet), treat the corresponding boolean as `false` and continue.
+
+### Step 3a — Cross-check filesystem state vs checkpoint (MAGI Archivist)
+
+If `CHECKPOINT_EXISTS`, the checkpoint is the **canonical truth** for workflow state. Filesystem booleans serve as drift detection:
+
+- If checkpoint says `current_stage = 5` but `SPEC_EXISTS = false` → drift; surface to CEO ("Checkpoint expects spec at `${spec_dir}${feature}.md` but it's missing. Suggest /pickup to inspect, or /feature-draft to restart").
+- If checkpoint says `stages_skipped: [3]` and reason is "no backend" → skip Stage 3 in the recommendation.
+- If checkpoint's `stage_in_progress.files_done_list` is non-empty → the user is mid-Stage-5; suggest `/pickup` instead of `/implement` (resume picks up at the right file).
+- If `last_activity_at` is > 7 days ago → add a flag: "Last activity 8 days ago — `/pickup` for context recall recommended."
+
+Without checkpoint, fall back to pure filesystem inference (existing logic below).
+
+---
+
+## Step 4 — Determine workflow stage + recommended next command
+
+Apply this state machine in priority order. The first matching branch wins.
+
+```
+IF NOT SPEC_EXISTS:
+  → Stage: 0 (pre-Stage 1)
+  → Suggest: /feature-draft ${feature}
+  → Reason: "No spec file yet at ${spec_dir}${feature}.md."
+
+ELIF SPEC_EXISTS AND NOT SPEC_FINALIZED:
+  → Stage: 1 done, Stage 2 pending
+  → Suggest: /spec-finalize ${feature}
+  → Reason: "Spec exists but not FINALIZED. Run /spec-finalize to lock it in."
+
+ELIF SPEC_FINALIZED AND BACKEND_PROJECT AND NOT SCHEMA_DOC_EXISTS:
+  → Stage: 2 done, Stage 3 pending
+  → Suggest: /db-schema ${feature}
+  → Reason: "Spec finalized; backend project but no schema design yet. Run /db-schema (or skip if no DB change)."
+
+ELIF SPEC_FINALIZED AND NOT PLAN_EXISTS:
+  → Stage: 3 done (or skipped), Stage 4 pending
+  → Suggest: /execution-plan ${feature}
+  → Reason: "Spec ready. Time to write the per-file execution plan."
+
+ELIF PLAN_EXISTS AND NOT GIT_HAS_CHANGES:
+  → Stage: 4 done, Stage 5 not started
+  → Suggest: /implement ${feature}
+  → Reason: "Plan exists but no code changes yet. Run /implement to start coding."
+
+ELIF PLAN_EXISTS AND GIT_HAS_CHANGES:
+  → Stage: 5 in progress
+  → Suggest: /test-fix OR continue /implement ${feature}
+  → Reason: "Code changes detected. Either continue /implement or move to /test-fix when implementation is done."
+
+ELIF GIT_HAS_CHANGES AND NOT PLAN_EXISTS:
+  → Lane: stability-fix or trivial-change (no Stage 4 plan needed)
+  → Suggest: /test-fix (if test_required) then /commit
+  → Reason: "Changes detected without a plan file. This looks like a trivial-change or stability-fix lane. Run /test-fix (if test_required) then /commit when ready."
+
+ELIF NOT GIT_HAS_CHANGES AND PLAN_EXISTS:
+  → Stage: 6 / 7 done; plan file expected to be deleted at Stage 8 (commit)
+  → Suggest: /commit
+  → Reason: "Looks like all stages done. Run /commit to ship + clean up the plan file."
+
+ELSE:
+  → Idle state
+  → Suggest: /feature-draft <new-feature>  OR  /audit-spec <existing-feature>
+  → Reason: "No active work detected. Either start a new feature or audit an existing one."
+```
+
+If the detected state matches multiple branches in confusing ways (e.g., plan exists AND a different feature has uncommitted changes), default to **surfacing the ambiguity** to the user rather than picking one — see Step 5.
+
+---
+
+## Step 5 — Present the recommendation
+
+Print a structured report in the user's locale. Use this shape (translate the prose; keep skill names, file paths, and slot names verbatim):
+
+```
+📍 Current state for feature: <feature>
+
+Stage: <stage number / name>
+Workflow lane: <inferred lane — full / stability-fix / trivial — or "ambiguous, ask">
+
+Detected state:
+  ✓/✗ Spec exists (${spec_dir}${feature}.md)
+  ✓/✗ Spec FINALIZED
+  ✓/✗ Implementation notes (${implementation_dir}${feature}-implementation.md)
+  ✓/✗ Plan file (${spec_dir}${feature}-plan.md)
+  ✓/✗ Git uncommitted changes
+  ✓/✗ Auditor approvals on file
+
+▶ Recommended next: <command>
+
+Reason: <one-sentence explanation>
+
+You can also (NL-first — just tell me in plain words; slash forms shown in parens only as fallback):
+  - Switch features: name the other feature (e.g., "看 X 这个 feature")
+  - Start something new: tell me what to build (e.g., "做个 X 功能")
+  - Audit an existing feature: ask me to check it (e.g., "审一下 X")
+  - See full workflow stages: see CLAUDE.md § Workflow
+```
+
+After printing, **wait for the user to respond** (Spec-Kit discipline). Do NOT auto-invoke the recommended command. The user has to type the command explicitly themselves.
+
+If the state was ambiguous, replace the `▶ Recommended next` line with:
+
+```
+▶ Ambiguous — please clarify:
+  <enumerate the candidate next commands and which signal points to each>
+```
+
+…and wait for the user's pick.
+
+---
+
+## Rules / Anti-patterns
+
+- **NEVER auto-invoke another skill** — `/next` only suggests; the user must explicitly type the recommended command.
+- **NEVER modify any file** — read-only inspection. No writes to `.harness/state/`, no edits to constitution.md or spec files.
+- **NEVER run `git commit` or `git push`** — out of scope.
+- **NEVER guess a feature name from prose** — only the explicit `$ARGUMENTS`, the git branch pattern, or the most-recently-modified spec file are authoritative. If none yield a feature, ask the user.
+- **NEVER translate file paths, slot names, or skill names** — those stay in English regardless of locale.
+- **Surface ambiguity rather than picking arbitrarily** — if multiple features look active or the state doesn't match a single branch cleanly, ask the user instead of guessing.
+
+---
+
+## Trust contract
+
+- This skill writes to **zero files**. It is strictly read-only.
+- It reads at most: `constitution.md`, `.harness/state/install.json`, files in `${spec_dir}` and `${implementation_dir}`, and runs read-only git commands (`rev-parse`, `status`, `branch`).
+- The user always types the next command themselves — `/next` is a wayfinder, not an autopilot.
+
+---
+
+## Completion criteria
+
+`/next` is complete when:
+
+- Step 0 has run (CCC-MAGI presence verified, or skill halted with the install message).
+- Step 1 has resolved a feature name (either from `$ARGUMENTS`, auto-detection, or a user response).
+- Steps 2–4 have computed state and selected a recommendation (or flagged ambiguity).
+- Step 5 has displayed the report to the user and the skill has stopped without invoking any other command.

package/template/.harness/skills/offload/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: offload
+description: |
+  Spawn a fresh-context subagent to complete a discrete sub-task and return a 1-2K summary. Use when budget pressure (~75%) makes finishing the current sub-task in the main thread risky, but you don't need full session handoff yet.
+
+  Trigger when:
+  - Budget-monitor 75% menu surfaces "[2] /offload <task>"
+  - User says "把这个交给 subagent / 找个新 context 做 X / spawn agent for X / offload X"
+  - You (AI) recognize the main thread context is full but a discrete next sub-task has clean boundaries
+allowed-tools: Task, Read, Bash(git status:*)
+argument-hint: <task description>
+---
+
+# /offload
+
+Subagent isolation as a budget-pressure release valve. Instead of forcing a full session handoff at 75%, you spawn an isolated-context subagent that does a discrete sub-task and returns just its summary. The main thread context grows by ~1-2K tokens instead of by the sub-task's full execution trace.
+
+## When this is the right answer
+
+- Context is ~70-85% and a clean sub-task is next (refactor a file, write a set of tests, search for a pattern across the codebase, generate a script)
+- The sub-task has **clear inputs and clear outputs** — easily described in ≤300 chars
+- You don't need ongoing dialogue with the user inside the sub-task
+
+## When this is NOT the right answer
+
+- Context >95% → use `/handoff` instead (offload only delays the inevitable)
+- Sub-task requires user judgment partway through → can't be isolated
+- Sub-task is "improve the whole codebase" → too vague; subagent will burn budget without a clear stop condition
+- The work would only cost ~1K tokens anyway → just do it inline
+
+## How it works
+
+You invoke the Task tool with a carefully-scoped prompt. The subagent runs in its own 200K context window, returns a single message back. From the main thread's perspective, the cost is:
+- ~500 tokens of subagent prompt
+- ~500-2000 tokens of subagent return summary
+
+Total main-thread overhead: typically 1-3K tokens vs. the 10-30K the task would have cost inline.
+
+## Step 1 — Scope the sub-task
+
+Before invoking, you (the AI) write a tight sub-task prompt:
+
+```
+Task: <one-sentence description>
+
+Inputs:
+- <relevant file paths>
+- <constraints>
+
+Outputs:
+- <what the subagent should return>
+- <format expectations>
+
+Constraints:
+- Stay focused on this sub-task only
+- Don't open Explore agents recursively
+- Report in ≤500 words
+```
+
+Ask the user to confirm the scope before invoking (in CEO's locale):
+
+```
+─── Offload Plan ─────────────────────────────────
+
+  Sub-task: <description>
+  
+  Inputs:
+    - <list>
+  
+  Subagent will return:
+    - <list>
+  
+  Expected main-thread overhead: ~1-3K tokens
+  Subagent type: general-purpose
+
+Confirm?
+  [1] Spawn subagent
+  [2] Edit scope
+  [3] Cancel (do task inline instead)
+```
+
+## Step 2 — Invoke
+
+On `[1]`:
+
+Use the Task tool with:
+- `subagent_type: "general-purpose"` (default) OR a specific type if the project has one matching the sub-task (e.g., `test-fixer` for test work, `backend-reviewer` for backend audits)
+- A self-contained `prompt` that gives the subagent enough context — it CANNOT see your conversation history
+- `description` short summary (3-5 words)
+
+CRITICAL: the prompt must be self-contained. The subagent has no access to:
+- Conversation history
+- TodoWrite state
+- Open files in your main session
+
+So bake in: file paths to read, the specific objective, the success criteria, and any project conventions the subagent needs to know.
+
+## Step 3 — Report back to CEO
+
+Once the subagent returns, summarize in CEO's locale:
+
+```
+✓ Offload complete
+
+  Sub-task: <description>
+  Subagent verdict: <PASS / CONCERNS / FAIL>
+  
+  Summary:
+    <subagent's return summary, paraphrased to ≤200 chars>
+  
+  Files modified by subagent:
+    <list, or "none">
+  
+  Main thread overhead: ~<N>K tokens
+  
+  Next: continue with <next planned action>
+```
+
+## Trust contract
+
+- This skill spawns ONE subagent. Multiple offloads in a single turn defeat the purpose.
+- The subagent runs without user oversight — only invoke when the scope is clear-cut and the risk is bounded.
+- Subagent failures (subagent returns "couldn't do X") are surfaced to CEO; you don't silently retry.
+
+## When you should auto-invoke vs. ask the CEO
+
+- **Auto-invoke** if the user explicitly said `/offload <task>` (clear intent)
+- **Ask first** if budget-monitor 75% menu fired and you're proposing offload — show the Step 1 scope plan
+- **Don't auto-invoke** mid-task without budget pressure — that's just using a subagent for no reason
+
+## Completion criteria
+
+- Subagent invoked, returned a result, user has seen the Step 3 summary, OR
+- Subagent failed or was cancelled at Step 1; control returned to main thread; alternative plan stated

package/template/.harness/skills/pickup/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: pickup
+description: |
+  Resume an in-progress feature from where you left off (across sessions, devices, days). Reads `.harness/state/workflow-checkpoints/<feature>.json` and restores: which stage you were at, which artifacts exist, what files were already implemented, what audit verdicts have been issued, and what CEO decisions were made.
+  
+  Trigger when the user:
+  - Invokes `/pickup` (no args = resume current git-branch's feature; with feature name = resume that one)
+  - Says "continue where I left off" / "继续上次的进度" / "前回の続きから" / "이어서 작업"
+  - Says "what was I doing on user-login?" / "user-login 我做到哪了？"
+  - Reopens Claude on a branch that matches an existing checkpoint (SessionStart hook auto-surfaces this)
+argument-hint: [<feature-slug>] [--list] [--force-restart]
+---
+
+# /pickup
+
+> *Operational basis: Stage 7 of `CLAUDE.md § Workflow` (CEO smoke test) and Stage 8 (commit) presume a coherent workflow state. When a session is interrupted between stages, `/pickup` reconstructs that state.*
+
+> **MAGI position**: This skill is operated by **MAGI Archivist** (per `AGENTS.md § MAGI System`). Archivist's job is to recall and announce prior state, then hand control back to MAGI Core for the next stage.
+
+## When to use
+
+Three common entry points:
+
+1. **Cross-day continuation** — you stopped Friday at Stage 5 (3/8 files done), come back Monday. `/pickup` picks up exactly there.
+2. **Cross-device continuation** — you started on laptop, finish on desktop. Both have the same git branch + checkpoint file (if committed) or separate checkpoint files (if gitignored, which is the default).
+3. **Session timeout / compaction loss** — context window filled up, conversation compacted. `/pickup` reloads the structural state without re-paraphrasing every prior decision.
+
+## What it produces
+
+Standard output (in user's locale):
+
+```
+─── MAGI Archivist · Resume Report ─────────────────────────────
+
+📂 Feature: user-login
+   Branch: feature/user-login
+   Mode: new-feature (full lane)
+   
+   Started:        2026-05-25 14:00
+   Last activity:  2026-05-26 18:30  (16 hours ago)
+   
+   ─── Progress ───────────────────────────────────
+   ✅ Stage 1 — spec drafted        (docs/features/user-login.md, sha 4f7a)
+   ✅ Stage 2 — spec finalized      (MAGI Verdict: PASS, risk=3)
+   ⏭️  Stage 3 — db schema           (skipped: no backend)
+   ✅ Stage 4 — execution plan      (docs/features/user-login-plan.md)
+                                     (MAGI Verdict: CONCERNS, risk=6)
+                                     ↳ CEO accepted, added index before commit
+   ⏳ Stage 5 — implementing        (3 of 8 files done)
+       ✓ src/auth/types.ts
+       ✓ src/auth/session.ts
+       ✓ src/auth/login.ts
+       ▢ src/auth/middleware.ts     ← next
+       ▢ src/auth/index.ts
+       ▢ tests/auth/login.test.ts
+       ▢ tests/auth/session.test.ts
+       ▢ src/routes/auth.ts
+   ⬜ Stage 6 — test-fix             (pending)
+   ⬜ Stage 7 — CEO smoke            (pending — CEO required for this)
+   ⬜ Stage 8 — commit               (pending)
+   
+   ─── Recent decisions (from decision-log.md, 3 most recent) ───
+   • 2026-05-26 15:00 — CEO: "accept index on session_id"
+   • 2026-05-26 14:50 — MAGI Verdict: CONCERNS — session_id needs index
+   • 2026-05-25 14:05 — CEO: "edge case #3 (race condition) is in scope"
+
+What now? (NL-first — just tell me in plain words; slash forms in parens are optional fallback)
+   [1] Continue from where you left off — Stage 5, src/auth/middleware.ts (recommended)
+   [2] Re-validate Stage 4 first — re-run the cross-model auditor
+   [3] See full checkpoint detail
+   [4] Abandon this feature — mark dead, archive checkpoint  (/abandon user-login)
+   [5] Switch to a different feature — just name it
+> 
+```
+
+## How to invoke
+
+### No args — resume current branch's feature
+```
+/pickup
+```
+- Reads current git branch (e.g., `feature/user-login`)
+- Strips prefix `feature/` → feature slug `user-login`
+- Reads `.harness/state/workflow-checkpoints/user-login.json`
+- Surfaces the report above
+- If no checkpoint exists for this branch → tells user (NL-first): *"No checkpoint for user-login. You can either tell me what new feature to start, or ask me to list other in-progress features (slash fallback: `/feature-draft <name>` or `/pickup --list`)."*
+
+### Explicit feature name
+```
+/pickup user-login
+```
+- Reads `.harness/state/workflow-checkpoints/user-login.json` regardless of current branch
+- If user is on a different branch, asks: *"Switch to feature/user-login first? [Y/n]"*
+
+### List all in-progress
+```
+/pickup --list
+```
+Outputs:
+```
+In-progress features:
+   ● user-login          Stage 5  (16h ago)  ← current branch
+   ○ notifications       Stage 2  (3 days ago)
+   ○ billing             Stage 1  (5 days ago)
+   ○ admin-dashboard     Stage 6  (1 day ago)  ⚠️ test-fix iter 3/3, escalate
+```
+
+### Force restart from current stage
+```
+/pickup --force-restart
+```
+- Re-loads the checkpoint but invalidates the "in-progress" state of the current stage
+- Useful when you want to redo Stage 5 from scratch (e.g., wholesale plan change)
+- Does NOT reset prior stages' artifacts — those are kept
+
+## Checkpoint schema (for reference; auto-written by stage skills)
+
+Path: `.harness/state/workflow-checkpoints/<feature-slug>.json`
+
+```json
+{
+  "schema_version": 1,
+  "feature": "user-login",
+  "feature_slug": "user-login",
+  "branch": "feature/user-login",
+  "started_at": "2026-05-25T14:00:00Z",
+  "last_activity_at": "2026-05-26T18:30:00Z",
+  "mode": "new-feature",                    // or "audit"
+  "lane": "full",                            // or "stability-fix" / "trivial"
+  "current_stage": 5,
+  "stages_completed": [1, 2, 4],
+  "stages_skipped": [3],
+  "stages_skipped_reasons": {"3": "no backend"},
+  "artifacts": {
+    "spec":           {"path": "docs/features/user-login.md", "sha256": "4f7a...", "exists": true},
+    "implementation": {"path": "docs/features/user-login-implementation.md", "sha256": "8c11...", "exists": true},
+    "plan":           {"path": "docs/features/user-login-plan.md", "sha256": "2bb0...", "exists": true},
+    "schema":         null
+  },
+  "audits": [
+    {"stage": 2, "verdict": "PASS",     "risk": 3, "at": "2026-05-25T14:30:00Z"},
+    {"stage": 4, "verdict": "CONCERNS", "risk": 6, "at": "2026-05-26T14:50:00Z"}
+  ],
+  "stage_in_progress": {
+    "stage_number": 5,
+    "files_total": 8,
+    "files_done_list":      ["src/auth/types.ts", "src/auth/session.ts", "src/auth/login.ts"],
+    "files_remaining_list": ["src/auth/middleware.ts", "src/auth/index.ts", "tests/auth/login.test.ts", "tests/auth/session.test.ts", "src/routes/auth.ts"],
+    "last_action": "Wrote src/auth/login.ts (87 lines)",
+    "resume_hint": "Continue /implement from src/auth/middleware.ts (5 files remaining)"
+  },
+  "decisions": [
+    {"at": "2026-05-25T14:05:00Z", "stage": 1, "by": "CEO", "decision": "edge-case #3 (race condition) is in scope"},
+    {"at": "2026-05-26T14:50:00Z", "stage": 4, "by": "MAGI Verdict", "decision": "CONCERNS — session_id needs index"},
+    {"at": "2026-05-26T15:00:00Z", "stage": 4, "by": "CEO", "decision": "accept index addition before commit"}
+  ],
+  "session_chain": [
+    {"session_id": "abc-123", "started": "2026-05-25T14:00:00Z", "ended": "2026-05-25T15:30:00Z"},
+    {"session_id": "def-456", "started": "2026-05-26T14:00:00Z", "ended": "2026-05-26T18:30:00Z"}
+  ]
+}
+```
+
+## How checkpoints get written (built into stage skills)
+
+Each stage skill writes/updates the checkpoint at its END:
+
+| Stage skill | What it writes |
+|---|---|
+| `/feature-draft <name>` | Creates checkpoint. `current_stage = 1`, artifact.spec recorded |
+| `/audit-spec <name>` | Creates or updates. `current_stage = 1` (audit mode) |
+| `/spec-finalize <name>` | `current_stage = 2`, audit verdict appended |
+| `/db-schema <name>` | `current_stage = 3`, audit verdict appended. Skipped → `stages_skipped += [3]` |
+| `/execution-plan <name>` | `current_stage = 4`, audit verdict appended, artifact.plan recorded |
+| `/implement <name>` | `current_stage = 5`. **Updates `stage_in_progress.files_done_list` after every Edit/Write tool use** (via PostToolUse hook) |
+| `/test-fix` | `current_stage = 6`, audit verdict appended |
+| `/commit <name>` | `current_stage = 8`, all stages marked complete, then checkpoint moved to `.harness/state/workflow-checkpoints/_archived/<feature>-<timestamp>.json` |
+
+If you implement a new stage skill, follow the same pattern (see `/implement` for the reference implementation of mid-stage progress tracking).
+
+## How the welcome-back UX works
+
+The SessionStart hook (`outcome/scripts/checkpoint-recall.sh` wired in `.claude/settings.json`) runs every time Claude Code opens:
+
+1. Reads current git branch (`git symbolic-ref HEAD`)
+2. Strips `feature/` / `feat/` / `fix/` prefix → feature slug
+3. Tests for `.harness/state/workflow-checkpoints/<slug>.json` — if exists, reads it
+4. Injects `additionalContext` to Claude: *"There's an in-progress feature `user-login` at Stage 5 (3/8 files done). The user may want to /pickup; surface it on first interaction."*
+5. Claude (acting as MAGI Core) greets the user with the resume offer at first response
+
+This is the same pattern Continue.dev uses with `HistoryManager.loadLastSession()` but feature-scoped instead of session-scoped.
+
+## What this skill does NOT do
+
+- **Doesn't roll back code** — if you have uncommitted changes that conflict with the checkpoint's expected state (e.g., you manually deleted a file the checkpoint says is done), `/pickup` warns but doesn't auto-fix. You decide.
+- **Doesn't re-run MAGI Verdict automatically** — even if `last_activity_at` is months ago, prior verdicts still stand. Run `/audit-spec` to re-validate if you need a fresh judgment.
+- **Doesn't handle multi-developer conflict** — checkpoint is gitignored, so two devs on the same feature have independent checkpoints. Git branch is the conflict resolution mechanism, not the checkpoint.
+- **Doesn't replace `/next`** — `/next` is the workflow status inspector (which command should I run next?). `/pickup` is the state restoration mechanism (what was I doing?). Both are complementary.
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| "No checkpoint for current branch" | You're on a non-feature branch (e.g., `main`) or this feature was started without going through the standard skills | Start the feature via `/feature-draft <name>` to create a checkpoint |
+| "Checkpoint references missing file `<path>`" | An artifact was manually deleted | Either restore the file from git or use `/feature-draft <name> --reset` to redo Stage 1 |
+| "Multiple checkpoints found, ambiguous" | Branch name doesn't cleanly map to feature slug | Use explicit form: `/pickup <feature-slug>` |
+| "Checkpoint schema version mismatch" | You upgraded CCC-MAGI to a newer schema | The harness offers `/pickup --migrate-checkpoint` to upgrade old checkpoints |
+
+## Completion criteria
+
+- Checkpoint read successfully → MAGI Archivist surfaces full report
+- User picks a continuation option → control hands to the appropriate stage skill (e.g., `/implement` for Stage 5 continuation)
+- If no checkpoint exists → tell the user clearly + suggest `/feature-draft <name>` to start one