create-ccc-tutor 0.1.0

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

@@ -0,0 +1,159 @@
+---
+name: recall
+description: |
+  Fetch a recall/archive memory entry by id, feature, tag, or deep query. Companion to the manifest-mode memory-recall hook — the manifest only injects index lines; this skill pulls full bodies on demand.
+
+  Trigger when:
+  - User explicitly references prior context: "上次 / 之前 / 上回 / before / previously / we decided / 之前我们定的"
+  - Current task's feature exactly matches a manifest entry's feature
+  - User says "查一下半年前 / search history / older / archive" → use --deep
+  - User invokes /recall <id>, /recall <feature|tag>, /recall --deep <query>
+
+  HARD CAPS per session (CLAUDE.md § Memory Calling Rules):
+  - ≤ 3 body fetches from Tier 2 (recall)
+  - ≤ 1 deep search from Tier 3 (archive)
+  - Do NOT fetch "for completeness". One trigger = one fetch.
+allowed-tools: Bash(jq:*), Bash(grep:*), Bash(ls:*), Bash(cat:*), Bash(wc:*), Read
+argument-hint: <id> | <feature|tag> | --deep <query>
+---
+
+# /recall
+
+Just-in-time memory retrieval. The SessionStart hook only shows you the **manifest** (one index line per entry). When you need a body, you call this skill explicitly.
+
+## When to call (HARD rules)
+
+Per `CLAUDE.md § Memory Calling Rules`, you may call `/recall` only when **one** of these is true:
+
+1. **User explicit reference**: words like "之前 / 上次 / 上回 / before / previously / we decided / 之前定的"
+2. **Feature exact match**: current task's feature tag matches a manifest entry's feature
+3. **Focus overlap**: a manifest entry's `focus="..."` indicates a prior decision relevant to the action you're about to take
+
+You may **not** call `/recall` because:
+- "It might be useful"
+- "For completeness"
+- "Multiple manifest entries look interesting"
+
+Hard caps: ≤ 3 recall-body fetches and ≤ 1 archive deep search per session.
+
+## Usage
+
+### Form 1: by id (most common)
+
+```
+/recall SS-2026053001
+/recall OBS-2026052901
+```
+
+Reads `.harness/memory/sessions/recall/snapshots.jsonl` or `observations.jsonl`, locates the entry whose `id` matches, prints the full body (pretty-printed JSON).
+
+```bash
+# Internal:
+jq -c "select(.id == \"$ID\")" .harness/memory/sessions/recall/*.jsonl
+```
+
+### Form 2: by feature or tag
+
+```
+/recall auth
+/recall rls
+```
+
+Lists all manifest lines in recall whose `feature == auth` OR `tags` includes `auth` (or `rls`). Output format is the same one-line manifest. User picks one, then calls `/recall <id>`.
+
+### Form 3: deep search (archive tier)
+
+```
+/recall --deep auth
+/recall --deep "rate limit"
+```
+
+Greps across `.harness/memory/sessions/archive/*.jsonl` for matching entries. Output: manifest lines, oldest visible. **Hard cap: 1 per session.**
+
+```bash
+# Internal:
+grep -l "$QUERY" .harness/memory/sessions/archive/*.jsonl | xargs -I{} jq -r '
+  "[" + .id + "] feature=" + (.feature // "general") + " kind=" + .kind + " date=" + (.ts[0:10]) + " focus=\"" + (.focus // .summary // "")[0:80] + "\""
+' {}
+```
+
+## Output format
+
+For `/recall <id>` (body fetch):
+```
+─── Recall: SS-2026053001 ──────────────────────────────
+
+ts:         2026-05-30T18:30:00Z
+kind:       session-snapshot
+feature:    auth
+focus:      Resolve OTP race condition in middleware
+next_intent:Implement advisory lock in src/auth/middleware.ts
+
+decisions:
+  - [d-001] WHEN form submits with code, THE SYSTEM SHALL validate before navigation
+
+open_problems:
+  - [p-001] Concurrent submissions cause double-charge (blocked_by: need DB advisory lock)
+
+files_touched:
+  - src/auth/middleware.ts (added validation hook)
+
+prev_session_id: SS-2026052801
+source: handoff
+
+─── 1/3 recall fetches used this session ───────────────
+```
+
+For `/recall <feature|tag>` (search recall):
+```
+Matching entries in recall tier:
+
+[SS-2026053001] feature=auth kind=session-snapshot date=2026-05-30 focus="OTP race condition"
+[DEC-2026052801] feature=auth kind=decision date=2026-05-28 focus="Use Supabase RLS not middleware"
+[OBS-2026052501] feature=auth kind=observation date=2026-05-25 focus="JWT expiry causes silent logout"
+
+To read the body: /recall <id>
+```
+
+For `/recall --deep <query>` (archive):
+```
+Matching entries in archive tier:
+
+[2026-03] OBS-2026031501  feature=auth focus="Old token format deprecated"
+[2026-02] DEC-2026021001  feature=auth focus="Switch from sessions to JWT"
+
+To read the body: /recall <id>  (note: archived; fetch returns from archive)
+
+─── Archive deep-search used this session (1/1) ──────
+```
+
+## Counter tracking
+
+This skill is best-effort about cap enforcement. Maintain `.harness/state/_recall-count-<session-id>` (a 2-line file: `body_fetches:N` and `deep_searches:M`). Increment on each call. If exceeded, refuse:
+
+```
+⚠️ Recall cap reached this session (3/3 body fetches).
+   Per CLAUDE.md § Memory Calling Rules, no more recall fetches this session.
+   If this is genuinely critical, ask the user to confirm an override.
+```
+
+## Path resolution
+
+Always use `${CLAUDE_PROJECT_DIR:-$(pwd)}` for paths. Files live at:
+- `.harness/memory/sessions/recall/observations.jsonl`
+- `.harness/memory/sessions/recall/snapshots.jsonl`
+- `.harness/memory/sessions/archive/<YYYY-MM>.jsonl`
+
+## Trust contract
+
+- Read-only. Never writes to memory files.
+- Never re-summarizes or translates body content — prints `decisions`, `open_problems`, `files_touched`, `next_intent`, `focus` **verbatim** as written in the jsonl entry. The recall body is a forensic record; translating it later breaks the "AI quote vs original" audit trail (same id, different language = trust broken).
+- Only the structural wrapper (header line "─── Recall: <id> ───", field labels like "decisions:", footer like "X/3 fetches used") translates to the user's OS locale.
+- If the body was originally written in a non-English language (e.g., CEO's locale at handoff time), present it in that original language — do not normalize to user's current locale.
+- Never silently fetches when caps are exceeded.
+
+## Completion criteria
+
+- Body fetched and printed in the format above, OR
+- No matching entry found → tell the user, suggest `/recall --deep` if Tier 2 came up empty, OR
+- Cap reached → refuse with explanation.

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

@@ -0,0 +1,205 @@
+---
+name: remember
+description: Append an observation, decision, or failure to .harness/memory/observations.jsonl for future Claude Code sessions to recall. Reads $ARGUMENTS as the summary text; asks the user to clarify kind / feature / details if missing. Trigger when the user invokes /remember, says "remember this", "note for later", "save this decision", "记一下", "记到 memory", or similar intent.
+allowed-tools: Bash(git rev-parse:*), Bash(git branch:*), Bash(git status:*), Bash(echo:*), Bash(mkdir:*), Bash(date:*), Bash(jq:*), Bash(cat:*), Read, Edit
+argument-hint: <summary text>
+---
+
+# /remember
+
+Manually capture a decision, failure, or observation into the project's memory layer so future Claude Code sessions can recall it.
+
+> *Companion to the automatic capture path (`PreCompaction` hook). This skill is the user-curated entry point — what the human explicitly wants persisted, not what an LLM guesses is important.*
+
+## Language Awareness
+
+This skill's instructions are in English. When you talk to the user (proposing values, confirming the entry), use the user's OS locale language. See `CLAUDE.md § Language Awareness`. The JSON written to `observations.jsonl` defaults to English unless the user explicitly enters non-English content; do not translate user-entered strings.
+
+## What this skill produces
+
+A single new line appended to `.harness/memory/observations.jsonl`:
+
+```json
+{"ts":"2026-05-22T14:00:00Z","kind":"decision","summary":"<one-line, ≤200 chars>","details":"<optional longer text>","feature":"<name or null>","files":["..."],"tags":["..."],"source":"manual"}
+```
+
+If `.harness/memory/` or `observations.jsonl` doesn't exist, this skill creates them.
+
+---
+
+## Step 0 — Parse `$ARGUMENTS`
+
+Treat `$ARGUMENTS` as the proposed `summary` text. If `$ARGUMENTS` is empty, ask the user:
+
+```
+What do you want to remember?
+(One sentence, ≤200 chars. Examples:
+ - "Use Supabase RLS, not middleware — middleware p99 was 800ms"
+ - "Google Vision API too expensive at our scale; use local model"
+ - "FlashList is 5x faster than FlatList here")
+```
+
+**Wait for user response before continuing.**
+
+If the user-provided summary exceeds 200 chars, propose splitting: keep the first ≤200 chars in `summary`, move the rest into `details`. Ask the user to confirm or rewrite.
+
+---
+
+## Step 1 — Auto-extract `feature` from current git branch
+
+Use the same logic as `.harness/scripts/memory-recall.sh`:
+
+```bash
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+```
+
+Then derive `FEATURE`:
+
+- If `BRANCH` matches `feat/<name>-*` or `fix/<name>-*` → `<name>` is everything between the prefix and the first dash (or the whole rest if no dash).
+- Else if `BRANCH` matches `<name>/...` → `<name>` is the segment before the first slash.
+- Else `FEATURE=""` (will be written as `null` in JSON).
+
+Example: branch `feat/auth-rls-migration` → `FEATURE=auth`.
+Example: branch `main` → `FEATURE=""`.
+
+---
+
+## Step 2 — Propose `kind` based on summary phrasing
+
+Heuristic (case-insensitive):
+
+| Phrase pattern in summary | Proposed kind |
+|---------------------------|---------------|
+| starts with "use X", "we use", "switch to", "chose", "decided" | `decision` |
+| contains "didn't work", "failed", "broke", "too expensive", "too slow", "regression" | `failure` |
+| anything else (general note, perf comparison, gotcha) | `observation` |
+
+Don't over-engineer this — if it's ambiguous, default to `observation`.
+
+---
+
+## Step 3 — Auto-propose `files`
+
+Run `git status --short` in the project root. Take the first 3 modified/staged paths as the proposed `files` array. If `git status` is empty, propose `[]`.
+
+---
+
+## Step 4 — Propose `tags`
+
+Pick 1-3 short tags from the summary's key nouns. Examples:
+
+- "Use Supabase RLS, not middleware" → `["auth", "rls", "supabase"]`
+- "FlashList is 5x faster than FlatList here" → `["perf", "list-rendering"]`
+
+If you can't infer meaningful tags, propose `[]`.
+
+---
+
+## Step 5 — Propose `details` (optional)
+
+If the summary is self-explanatory (e.g., "FlashList is 5x faster than FlatList here"), propose `details=""`. Otherwise propose a short rationale line that adds context the summary couldn't fit (e.g., the "why" or the measurement).
+
+---
+
+## Step 6 — Confirm the proposed entry with the user
+
+**Path resolution**: use `${CLAUDE_PROJECT_DIR:-$(pwd)}` (not raw `$CLAUDE_PROJECT_DIR`) for all filesystem paths in this skill — the env var may be empty in some Bash subshell contexts.
+
+Display the full proposed JSON entry in the user's locale, formatted for human reading:
+
+```
+About to append this entry to .harness/memory/observations.jsonl:
+
+  ts       : <ISO 8601 UTC of now>
+  kind     : decision
+  summary  : Use Supabase RLS, not middleware — middleware p99 was 800ms
+  details  : (empty)
+  feature  : auth
+  files    : ["src/auth.ts", "supabase/migrations/0042_rls.sql"]
+  tags     : ["auth", "rls", "supabase"]
+  source   : manual
+
+Looks right?
+  [1] Yes, append it
+  [2] Edit one or more fields
+  [3] Cancel
+```
+
+**Wait for user response before continuing.**
+
+If `[2]`, ask which field(s) to edit, accept new values, re-show the confirmation. Loop until `[1]` or `[3]`.
+
+If `[3]`, abort silently — write nothing.
+
+---
+
+## Step 7 — Append to observations.jsonl
+
+On `[1]`:
+
+1. Ensure the directory exists:
+
+   ```bash
+   mkdir -p "${CLAUDE_PROJECT_DIR:-$(pwd)}/.harness/memory"
+   ```
+
+2. Compute the ISO 8601 UTC timestamp:
+
+   ```bash
+   TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+   ```
+
+3. Build the JSON line. Prefer `jq -c -n` to avoid quoting bugs:
+
+   ```bash
+   ENTRY=$(jq -c -n \
+     --arg ts "$TS" \
+     --arg kind "$KIND" \
+     --arg summary "$SUMMARY" \
+     --arg details "$DETAILS" \
+     --arg feature "$FEATURE" \
+     --argjson files "$FILES_JSON" \
+     --argjson tags "$TAGS_JSON" \
+     '{ts:$ts, kind:$kind, summary:$summary, details:$details, feature:(if $feature=="" then null else $feature end), files:$files, tags:$tags, source:"manual"}')
+   ```
+
+4. Append:
+
+   ```bash
+   echo "$ENTRY" >> "${CLAUDE_PROJECT_DIR:-$(pwd)}/.harness/memory/observations.jsonl"
+   ```
+
+5. Confirm to the user (in their locale):
+
+   ```
+   ✓ Remembered at <TS>.
+     File: .harness/memory/observations.jsonl (now <N> entries)
+   ```
+
+---
+
+## Trust contract
+
+- This skill writes to **exactly one file**: `.harness/memory/observations.jsonl`.
+- It never reads, modifies, or deletes any other project file.
+- The entry is always `source: "manual"` (auto-capture entries use `source: "session"`).
+- If the user cancels at Step 6, nothing is written.
+- If `jq` is missing, surface the error and abort — do not fall back to hand-rolled JSON (quoting bugs would corrupt the file).
+
+---
+
+## Anti-patterns the skill blocks
+
+- **Writing without user confirmation** → always show the JSON and wait for `[1]`.
+- **Translating user-entered summary/details into English** → write what the user typed, verbatim.
+- **Inferring `feature` from the summary text** → only the git branch is authoritative; if branch doesn't yield a feature, ask the user or use `null`.
+- **Setting `source: "session"`** → this skill is the manual path; auto-capture is a separate mechanism.
+
+---
+
+## Completion criteria
+
+`/remember` is complete when:
+
+- Either a single new line has been appended to `observations.jsonl` and the user has seen the confirmation message, **or**
+- The user explicitly cancelled at Step 6 (nothing written).

package/template/.harness/skills/spec-finalize/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: spec-finalize
+description: This skill should be used at stage 2 of the feature workflow, after stage 1 has landed a CEO-confirmed plain-language spec (via /feature-draft for a new feature or /audit-spec for an existing one). It verifies the two-file model is in shape, every scenario is classified, the spec is plain-language end-to-end, marks the CEO spec FINALIZED, and runs a different-model auditor cross-check focused on integration consistency. Use this always to close stage 2 — spec errors caught here cost much less than spec errors caught during implementation. Trigger when the user invokes /spec-finalize, says "finalize the spec", "mark spec as ready", "stage 2 done", or moves from spec discussion to schema design (or to execution-plan if no backend).
+argument-hint: [feature-name]
+---
+
+# /spec-finalize
+
+Drive Stage 2 of the feature workflow: confirm Stage 1's output is in shape, mark the CEO spec finalized, and run a final cross-model pass.
+
+Stage 1 already did the heavy lifting (paraphrase + edge-case sweep + {{auditor_model}} review; in audit mode also code reading + delta reconciliation). Stage 2 is largely a formality that prevents premature finalization — it catches sloppy hand-offs from Stage 1.
+
+## Authoritative sources
+
+1. `{{spec_dir}}<feature>.md` — the CEO spec from Stage 1
+2. `{{implementation_dir}}<feature>-implementation.md` — the manager-domain notes (when present)
+3. `constitution.md` § 5 (Spec and reality stay in sync) — why this stage exists
+4. `.harness/scripts/auditor-gate.sh` — the cross-check gate
+5. Root `CLAUDE.md` — two-file model, lane definitions
+6. `AGENTS.md` (root) — the auditor's standing context
+
+## Invocation
+
+- Typical: `/spec-finalize <feature-name>` (e.g., `/spec-finalize auth`)
+- `$ARGUMENTS` identifies the feature; reads `{{spec_dir}}$ARGUMENTS.md`
+
+If `$ARGUMENTS` is missing, identify the active feature from context (most recently created/edited spec under `{{spec_dir}}`). If you cannot confidently identify it, ask explicitly.
+
+## Step 1 — Two-file shape check
+
+Read both:
+
+- `{{spec_dir}}<feature>.md` (must exist; this is the CEO spec)
+- `{{implementation_dir}}<feature>-implementation.md` (may or may not exist)
+
+Confirm the CEO spec has all required sections per the spec template:
+
+- Status
+- What this feature is for
+- Happy path
+- Edge-case behavior
+- Who can use this
+- External dependencies
+- Deferred / unresolved
+- Out of scope
+- Decision history
+- Audit-mode delta section (populated only for audits, empty for new-feature mode)
+
+Then confirm:
+
+1. The CEO spec does **not** carry a `## Open questions` section with unanswered numbered items.
+2. The implementation file, when present, references the CEO spec at the top (`**Spec:** {{spec_dir}}<feature>.md`).
+
+If shape is wrong, halt and surface the issue:
+
+- Missing section → ask the user to fill it
+- Open questions remain → halt; CEO answers, then re-invoke
+- CEO spec contains an `#### Automated test ID` block or any `scenario-X-Y — <path>` test-mapping line → halt; the test-ID index is manager-domain and belongs in the implementation file's "Scenario → automated test map" section
+- Implementation file missing for a complex feature → recommend producing one (not blocking; CEO can override)
+
+**Manager-file functional requirements**: When the manager file has a "Functional requirements" section, ensure each requirement uses EARS notation per `CLAUDE.md § Two-file feature spec model > EARS notation`. The primary pattern is `WHEN [trigger] THE SYSTEM SHALL [response]`. Other variants (Ubiquitous / Unwanted / State-driven / Optional) are available — see CLAUDE.md for the full table.
+
+If existing functional requirements in the file are in prose form, do NOT rewrite them aggressively. Surface to the user: "The manager file has N prose-style functional requirements. Convert them to EARS now (recommended for testability), or leave as-is (acceptable for legacy)?" Wait for user response before continuing.
+
+## Step 2 — Plain-language and classification check
+
+Skim the CEO spec for tech-term creep. Categorical bans per Constitution + CLAUDE.md "Two-file feature spec model":
+
+- Library / framework names
+- Code identifiers (hook / function / store / state names)
+- File paths
+- Backend identifiers (RPC / function / table / column names)
+- Framework jargon (router / navigation API names, lifecycle terms)
+- SDK error type names
+- HTTP status codes as primary verbs
+- Test file paths and test descriptions (e.g., `scenario-3-X — <path>/*.test.* > describe > test name`)
+- Query key constants, payload shapes (JSON field lists), migration timestamps
+
+Surface every match to the CEO with a plain-language replacement suggestion. The CEO confirms the rewrite or rejects ("this term is fine to keep — users see it in the UI"). Don't silently rewrite. Test-ID matches are NOT optional — they relocate to the implementation file's "Scenario → automated test map" section, no CEO confirmation needed.
+
+Confirm every scenario in the Edge-case section has a `Classification` line — `[Required automated test]` or `[Smoke test only]`. If any classification is missing, halt and ask the CEO to classify.
+
+## Step 3 — Mark the CEO spec FINALIZED
+
+When shape is right, plain language is clean, and every scenario is classified, surface the proposed change to the user:
+
+```
+Proposing to replace the spec's Status line with:
+
+  ## Status: FINALIZED <YYYY-MM-DD>
+
+This marks Stage 2 closure (auditable). The auditor cross-check at Step 4 follows.
+
+Approve?
+  [a] approve
+  [b] cancel (return to drafting)
+```
+
+**Wait for user response before continuing.**
+
+On approval, replace the Status line with `## Status: FINALIZED <YYYY-MM-DD>` (today's date in ISO format) and write the file back. The FINALIZED line makes Stage 2 closure auditable.
+
+## Step 4 — Auditor final cross-check
+
+Invoke the gate:
+
+```bash
+bash .harness/scripts/auditor-gate.sh review <feature> 2 \
+  "Review this finalized two-file feature spec. Stage 1 already ran an edge-case round with auditor external review (and in audit mode, an as-built reading and delta reconciliation). Stage 2's job is the final cross-check on the integrated artifact. Look for: spec-internal contradictions between sections (a happy path that contradicts an edge-case behavior, an external-dependency note that contradicts a scenario classification); plain-language hygiene gaps (tech terms that slipped through); scenario classification anomalies (something marked [Smoke test only] that is clearly data-correctness or security-sensitive and should be [Required automated test]); CEO-spec / implementation-notes inconsistency (a routing rule in the implementation file that doesn't match a scenario in the CEO spec); missing scenarios that subsequent Stage 5 implementers would have to invent unilaterally. Do NOT flag: writing style, section ordering, suggestions to extend scope beyond declared, opinions on technical architecture, anything that would have been caught at Stage 1 (we're past that round)." \
+  {{spec_dir}}<feature>.md
+```
+
+Read the gate's exit code:
+
+- **Exit 0 (PASS / CONCERNS / WAIVED)** — surface `✓ Stage 2 complete: spec FINALIZED; auditor cross-check advanced.` Mention any advisory items. For CONCERNS, also surface the logged warning path (`.harness/audits/concerns-*.json`) and remind the CEO to review before commit. For WAIVED, surface the `waiver_reason`. Recommend the next step (`/db-schema <feature>` if the spec implies data-layer work AND `backend_db_type` is configured, otherwise `/execution-plan <feature>`).
+- **Exit 2 (FAIL)** — see Step 5.
+- **Exit 1 (script error / Universal Core WAIVED rejected / missing waiver_reason / legacy verdict)** — surface stderr, halt.
+
+## Step 5 — On FAIL
+
+Blocking findings indicate Stage 1 left gaps a reasonable implementer could not resolve unilaterally.
+
+1. Surface every blocking item from the auditor verbatim to the CEO.
+2. **Roll back the FINALIZED line.** Replace `## Status: FINALIZED <date>` with `## Status: DRAFT <YYYY-MM-DD> (pending stage-2 fixes)`. The spec is not finalized after all; the rollback prevents stale-status drift.
+3. Append the blocking findings to a `## Open questions` section as new numbered items, prefixed with `(from stage-2 auditor review)`. The CEO answers, the spec is updated, the user re-invokes `/spec-finalize`.
+4. Halt. No silent advance.
+
+This routes auditor findings back through the same loop the CEO used during Stage 1. The shape stays uniform: there is no separate "auditor feedback resolution" stage.
+
+## Trust contract
+
+- **Auditor is unconditional.** Skill cannot skip the cross-check because "the spec looks fine." (Per Constitution § 1.)
+- **Verdict is parsed deterministically from the gate's exit code.** No prose interpretation. The four verdicts are `PASS` (advance silently), `CONCERNS` (advance with logged warning at `.harness/audits/concerns-*.json` for CEO commit-time review), `FAIL` (halt), and `WAIVED` (CEO override only; rejected by the gate if any blocking item cites Universal Core).
+- **No silent finalize.** If the auditor returns FAIL, the FINALIZED line comes off — the spec does not retain a stale status.
+- **Plain-language audit is enforced at Stage 2** (Step 2). Tech terms in the CEO file are caught here, not at smoke time.
+- **Implementation file is optional** — its absence is acceptable for simple features; its presence is checked only for cross-consistency with the CEO spec.
+
+## Completion criteria
+
+Stage 2 is complete when:
+
+- The two-file shape is correct (CEO spec present and well-formed; implementation file present when warranted)
+- Every scenario in the Edge-case section is classified (`[Required automated test]` / `[Smoke test only]`)
+- The CEO spec is plain language end-to-end
+- `## Status: FINALIZED <date>` is present at the top of the CEO spec
+- `.harness/scripts/auditor-gate.sh` returned exit 0 (`PASS`, `CONCERNS`, or `WAIVED`)
+- `.harness/state/auditor-approvals/<feature>-stage2.json` exists with a non-FAIL `verdict`
+
+Next step: `/db-schema <feature>` (if the spec implies data-layer work AND `backend_db_type` is configured) or `/execution-plan <feature>`.
+
+---
+
+## Checkpoint + decision-log integration (MAGI Archivist)
+
+After Status: FINALIZED is set and the auditor-gate passes:
+
+```bash
+.harness/scripts/checkpoint-write.sh \
+  --feature <feature-slug> \
+  --stage 3 \
+  --stage-complete 2 \
+  --append-audit "$(jq -c '{stage:2, verdict, risk:.risk_score, at:now|todate}' .harness/state/auditor-approvals/<feature>-stage2.json)"
+
+# If MAGI Verdict returned CONCERNS and CEO chose to advance anyway:
+.harness/scripts/decision-log-append.sh \
+  --feature <feature-slug> --stage 2 --by "CEO" \
+  --decision "advance despite CONCERNS verdict" \
+  --evidence ".harness/audits/concerns-<feature>-stage2-<ts>.json"
+```
+
+---
+
+## Final message to CEO (natural-language, not slash-command)
+
+After Stage 2 completes (Status: FINALIZED + auditor PASS/CONCERNS/WAIVED), display (in CEO's OS locale):
+
+```
+✅ Stage 2 完成 — <feature> 的需求已锁定
+   状态: FINALIZED
+   MAGI Verdict: <PASS/CONCERNS/WAIVED>, risk = N
+
+接下来可以：
+  👉 「继续」/「下一步」  — 我决定走 Stage 3 (设计数据库) 还是 Stage 4 (执行计划)
+                          - 如果这个功能涉及数据存储 → 我走 /db-schema
+                          - 如果只改前端/逻辑 → 我直接走 /execution-plan
+  👉 「先看 verdict」     — 我把 MAGI Verdict 的发现念给你听
+  👉 「先停一下」         — 我等你
+  👉 「放弃」             — 不做这个功能了
+
+(直接告诉我你想干嘛 — 我帮你判断走哪一支)
+```
+
+Decision logic for "继续":
+- If feature spec mentions data persistence / schema / migration AND `backend_db_type` is configured → invoke `/db-schema <feature>` silently
+- Else → invoke `/execution-plan <feature>` directly
+- Surface your decision to CEO: *"这个功能涉及数据库，我先做 Stage 3 (设计 schema)"* — let them override if you guessed wrong.