@gordon.gan/specflow 1.5.0-beta → 1.8.0-beta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.5.0-beta",
+  "version": "1.8.0-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [
@@ -58,6 +58,7 @@
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "js-yaml": "^4.1.0",
+    "marked": "^15.0.12",
     "zod": "^3.24.4"
   },
   "devDependencies": {

package/prompts/approval/acp-pipeline.md

@@ -0,0 +1,106 @@
+# Approval · ACP Pipeline (Approval Compiler Pipeline)
+
+> Router for `/specflow:approval` **Stage 12** when `acp.pipeline=acp/v2` (recommended for non-lightweight changes).
+> Legacy segmented flow remains valid; ACP adds **lint**, **AI review**, and **bundle** gates.
+
+---
+
+## Pipeline (hard order)
+
+```text
+Phase 1  Analyze     → analysis.json + IR planner (chat gate)
+Phase 2  IR Freeze   → index.yaml (+ interfaces[].frozen, feature_slices, acp.review)
+Phase 3  Skeleton    → parts 01–03, 04-detail-core, 06/09/10
+Phase 4  Slot Map    → batched parts 04.4–04.9 (vertical slice first)
+Phase 5  AI Review    → Stage 12e in-session (prompts/approval/ai-review.md) — **inside /specflow-approval**
+Phase 6  finalize      → specflow approval finalize <change> [--bundle] [--render]
+Phase 7  render        → specflow approval render <change> [--input] [--output]
+
+**Preferred**: one `finalize` after Map + AI review. Subcommands (`lint`, `assemble`, …) are for CI/debug only.
+```
+
+**Never** skip Phase 6a–6b with LLM paste. **Never** write `approval-unified.md` by hand when bundle is enabled.
+
+---
+
+## index.yaml ACP block
+
+```yaml
+acp:
+  pipeline: acp/v2
+  context_budget_tokens: 40000
+  output_budget_tokens: 8000
+  feature_slices:
+    - id: step-reporting
+      parts: [04.5-api-worker, 04.5-api-east, 04-detail-core]
+      interfaces: [I13, I14, I16, I17]
+  review:
+    enabled: true
+    required_pass: true
+```
+
+## interfaces[].frozen (IR freeze before Map)
+
+```yaml
+interfaces:
+  - id: I14
+    short: SubmitStepResult
+    change: scenario-job-compile
+    part: 04.5-api-worker
+    pairs_with: I13
+    layers: [L3]
+    frozen:
+      rpc: scheduler.Scheduler.SubmitStepResult
+      http_path: POST /internal/v1/tasks/{job_id}/step-results
+      status_enum: [passed, failed, skipped, error]
+```
+
+---
+
+## Multi-repo default
+
+- **True source**: `per_repo` — each repo `approval/` + `approval.md`
+- **Read-only view**: `approval bundle` from `approval-playbook.yaml`
+- Do **not** LLM-unify three repos into one primary `approval/parts`
+
+See `multi-repo-guidance.md` + `templates/approval-playbook.yaml` (+ example `templates/approval-playbook-talos-scenario-job-compile.yaml`).
+
+**Orchestration**: multi-repo mode A uses **Stage 1c** subagent parallel dispatch (`multi-repo-spoke-subagent.md`) — not a single-repo `finalize` across repos.
+
+---
+
+## Context packet (Map batch)
+
+Read only:
+
+1. `index.yaml` subset for this batch (ids + frozen fields)
+2. `analysis.json` verdicts (not full Pass essays)
+3. design/spec **snippets** for batch entities
+4. 1–2 anchor files for this batch
+5. guidance router (path only, not full paste)
+
+Do **not** reload entire four-artifact sets each batch.
+
+---
+
+## CLI reference
+
+| Command | Purpose |
+|---------|---------|
+| `approval render` | MD → standalone HTML (tables, GFM, mermaid via CDN) |
+| `approval finalize` | **Preferred** — full lint → review-check → check → assemble → bundle |
+| `approval lint` | Cross-part consistency (CI / debug) |
+| `approval review-pack` | Emit `review-packet.json` (debug; finalize auto-runs when needed) |
+| `approval review-check` | Validate `review-result.json` (debug) |
+| `approval check` | Part presence + lazy stub (debug) |
+| `approval assemble` | Deterministic Reduce (debug) |
+| `approval bundle` | Multi-repo readonly merge (debug; finalize can auto-run) |
+
+---
+
+## Related guidance
+
+- `segmented-generation.md` — Map anti-lazy L1–L10
+- `ai-review.md` — Stage 12e AI approval/revision
+- `runtime-guidance.md` — optional async/lease/cancel (when in scope)
+- `api-guidance.md` — optional multi-layer API contracts (when api_in_scope)

package/prompts/approval/ai-review.md

@@ -0,0 +1,145 @@
+# Approval · Stage 12e AI Review (审批 / 修订)
+
+> Runs **after** Map parts written, **before** `specflow approval finalize` completes.
+> Purpose: catch **long-document / multi-part semantic drift** that mechanical lint cannot judge; **revise parts in place**.
+
+**Scope**: checks apply to **any** segmented approval — not tied to a specific product, repo, or domain.
+Use `index.yaml` + `analysis.json` as the contract; do not inject checks from unrelated case studies.
+
+---
+
+## 0. Trigger
+
+Run when **any**:
+
+- `acp.review.enabled=true` in `index.yaml` (default for non-lightweight)
+- User asks for AI 审批 / 方案审查 / 一致性检查
+- `specflow approval finalize` paused at `review-required`
+
+---
+
+## 1. Prep (hard)
+
+```bash
+specflow approval finalize <change>   # pauses + writes review-packet.json if needed
+```
+
+Read:
+
+- `approval/review-packet.json` (checklist + lint diagnostics)
+- `approval/index.yaml` (inventory, design_points, frozen fields, parts_order)
+- `approval/analysis.json` (Pass verdicts — gaps to close)
+- **All** `approval/parts/*.md` in `parts_order`
+
+Optional domain packs (only when design **actually** touches that topic):
+
+- `runtime-guidance.md` — async job / lease / retry / cancel semantics
+- `api-guidance.md` — multi-layer API contracts
+- `frontend-guidance.md` — §4.6 depth
+
+---
+
+## 2. Review dimensions (long-document generic)
+
+These target **failure modes of long, batched documents** — inconsistency across parts written at different times.
+
+| ID | Category | Check (generic) |
+|----|----------|-----------------|
+| R1 | **Cross-part naming** | Same entity (service, table, interface, page, enum) uses **one** canonical name/id across §2, §4, diagrams, and `index.yaml`. No 「暂定 / 实现时 / 如 Xxx / TBD」 for listed inventory ids. |
+| R2 | **Decision traceability** | Each `decisions[]` / §2 row appears in §4 with concrete behavior — not only repeated in summary. |
+| R3 | **Inventory ↔ body** | Every `tables[]` / `interfaces[]` / `pages[]` / `design_points[]` entry in index has **substantive** content in its assigned `part`. No orphan ids; no body content for ids missing from index. |
+| R4 | **Depth parity** | Parts in the same `feature_slices` or batch have **comparable** depth. No pattern of one part fully detailed while sibling parts are one-line stubs. |
+| R5 | **Cross-reference integrity** | Internal refs use stable ids (`§4.5 I2`, `P3`, `Page·列表`, `T1`) — not bare 「详见 design/tasks」. Ref targets exist and match. |
+| R6 | **Diagram ↔ prose** | Sequence / flow diagrams agree with adjacent prose (actors, message names, order, error branches). |
+| R7 | **Contract completeness** | Each listed interface/page-api has minimum skeleton from Part E (fields, success example, **failure example**, error table) — depth scaled to `api_in_scope` / `ui_in_scope`. |
+| R8 | **Enum / state closure** | Status, enum, and terminal-state sets are **explicit and closed** wherever the doc defines them — no 「等」 or open-ended lists unless explicitly extensible by design. |
+| R9 | **Unclosed branches** | Every **mentioned** branch (retry, cancel, timeout, idempotency, rollback, concurrency) has a documented outcome — or is flagged `[待 refine 澄清: …]` with owner. Do **not** assume domain-specific branches (e.g. lease reclaim) unless design/analysis mentions them. |
+| R10 | **UI ↔ API alignment** | When `ui_in_scope`: §4.6 field names, types, and api refs align with §4.5 / `pages[].apis`. |
+| R11 | **Multi-repo parity** | When `multi_repo.enabled`: each repo slice in scope has proportionate depth; no 「主仓详、他仓 stub」 unless explicitly out of scope. |
+| R12 | **Stub purge** | No `TODO` / `待补充` / `此处省略` / placeholder-only sections in parts slated for assemble. |
+| R13 | **Verdict coherence** | §9 implementability / readiness matches §4 depth — no READY alongside unexplained NEEDS REFINEMENT or contradictory gates. |
+
+**Not in default scope**: product-specific rules (talos lease wipe, ingest whitelist, L2/L3 layering) — load the matching guidance pack **only** when the change design requires it.
+
+---
+
+## 3. Revision rules (hard)
+
+1. **Edit `approval/parts/*.md` only** — never edit assembled `approval.md` directly
+2. **Update `index.yaml` first** when changing frozen ids, rpc names, or inventory
+3. Each finding → fix in named `part` OR waive (`minor` only) with `waiver_reason`
+4. Re-run:
+
+```bash
+specflow approval finalize <change>
+```
+
+---
+
+## 4. Write review-result.json
+
+Path: `approval/review-result.json`
+
+```json
+{
+  "schema": "specflow.approval.review/v1",
+  "change": "<change-name>",
+  "reviewed_at": "2026-08-26T12:00:00Z",
+  "reviewer": "ai",
+  "verdict": "pass",
+  "summary": "Fixed cross-part naming for I3; expanded P2 error path in 04-detail-core",
+  "part_hashes": [
+    { "id": "04.5-api", "sha256": "<sha256-after-fixes>" },
+    { "id": "04-detail-core", "sha256": "<sha256-after-fixes>" }
+  ],
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "critical",
+      "category": "cross_part_naming",
+      "message": "I3 RPC name differs between §2 and 04.5-api",
+      "part": "04.5-api",
+      "status": "fixed"
+    },
+    {
+      "id": "F2",
+      "severity": "important",
+      "category": "unclosed_branch",
+      "message": "Retry path mentioned in §4.3 but no terminal outcome",
+      "part": "04-detail-core",
+      "status": "fixed"
+    }
+  ]
+}
+```
+
+| verdict | When |
+|---------|------|
+| `pass` | All findings `fixed`; strict lint pass; **`part_hashes` match current parts** |
+| `pass_with_waivers` | Only `minor` waived with `waiver_reason` |
+| `fail` | Any `critical` / `important` still `open` |
+
+**Waive policy**: only `minor` may be waived; critical/important must fix or escalate to user.
+
+**part_hashes (required when `acp.review.enabled`)**: After fixing parts, run `specflow approval review-hashes <change> --json` and copy the array into `review-result.json`. `review-check` fails if parts change after review without updating review-result.
+
+---
+
+## 5. User gate
+
+When a finding requires a **product/architecture choice** the artifacts do not resolve:
+
+```text
+[待用户确认] <topic>: options A / B / C — record choice as new decision + update affected parts
+```
+
+Stop finalize until user chooses; do not invent policy.
+
+---
+
+## 6. Announce
+
+```text
+AI Review: findings=<n> fixed=<n> waived=<n> verdict=pass|fail
+Next: specflow approval finalize <change>
+```

package/prompts/approval/generate.md

@@ -1412,7 +1412,8 @@ When `approval/index.yaml` has `mode: segmented` (default for non-trivial §4),
 2. **Gate** — user confirms index inventory + optional chapters + mode
 3. **12b Map Append** — batched `04.4*` / `04.5*` / `04.6*` / `04.7–04.9`
 4. **12c Optional** — `05*` / `07` / `08` only when opted in
-5. **12d CLI Reduce** — `specflow approval check` then `specflow approval assemble --force`
+5. **12e AI Review** — fix parts; write `review-result.json` with `part_hashes` (see `ai-review.md`)
+6. **12f Finalize** — `specflow approval finalize <change>` (lint → review-check → check → assemble → bundle)
 
 **Reduce 禁止 LLM** — never stitch parts in chat or paste from memory.
 
@@ -1420,7 +1421,7 @@ When `approval/index.yaml` has `mode: segmented` (default for non-trivial §4),
 
 | # | Forbidden | Required |
 |---|-----------|----------|
-| L1 | One-shot full `approval.md` when `mode=segmented` | Write parts; CLI assemble |
+| L1 | One-shot full `approval.md` when `mode=segmented` | Write parts; `specflow approval finalize` |
 | L2 | Empty part, `< 20` chars, placeholder-only | Full section per Part E |
 | L3 | `TODO` / `待补充` / `此处省略` / bare `TBD` | Concrete text or `[待 refine 澄清: <元素>]` |
 | L4 | `详见 design/tasks` without §/In/Page id | Cross-ref `§4.5 I2` / `Page·列表` / `P1` |
@@ -1431,7 +1432,7 @@ When `approval/index.yaml` has `mode: segmented` (default for non-trivial §4),
 | L7 | Skip IDE skills/rules scan for §4.6 | `frontend-guidance.md` §3 before Map |
 | L8 | Paste skill/rule bodies verbatim | Readable Chinese + path in §4.6.1 |
 | L9 | Foreign `## N.` headings in parts | `###`/`####` only; CLI injects chapter headers |
-| L10 | Mark done without `specflow approval check` passing | Fix diagnostics; then assemble |
+| L10 | Mark done without finalize passing | Fix diagnostics; run `specflow approval finalize` |
 
 CLI lazy validation mirrors L2–L3 (`lazy_part_content` on assemble/check).
 
@@ -1475,24 +1476,121 @@ User natural language, workset, or cross-repo design → `multi_repo.enabled=tru
 
 ### G.2 User gates (hard, before Stage 12a)
 
-1. **Document mode**: `unified` (一份合订) **or** `per_repo` (多份分仓).
-2. If **unified**: **主仓** `primary_repo` — only this repo holds `approval/` + final `approval.md`.
-3. Record in `index.yaml`; do not assemble until both answered.
+1. **Document mode**: **A** bundle (per_repo + CLI bundle, recommended) **or** **B** per_repo only **or** **C** legacy unified LLM merge (discourage).
+2. If **A or C**: **主仓** `primary_repo` — playbook/bundle or unified workspace path.
+3. Record in `index.yaml`; set `acp.pipeline: acp/v2`; do not assemble until answered.
 
-### G.3 Unified 合订
+### G.3 Bundle 合订视图 (recommended)
+
+- Each repo: own `approval/` + `specflow approval assemble <repo.change>`.
+- Primary repo: `approval-playbook.yaml` + `specflow approval bundle <primary.change>`.
+- Output: `approval-unified.md` (readonly concatenation, no LLM merge).
+
+### G.4 Legacy unified LLM 合订 (discouraged)
 
 - Read **every** repo's four artifacts + anchors.
 - `index.change` **should equal** primary repo's change name.
 - Header lists all repos; §2.3 / 附录 B per-repo tables.
 - CLI: `specflow approval assemble <primary.change>` from **primary** planning root.
 
-### G.4 Per-repo 分仓
+### G.5 Per-repo 分仓
 
 - Separate `approval/` (or monolithic `approval.md`) **in each repo**.
 - Each document scoped to that repo only; cross-ref sibling paths.
 - Separate assemble per repo.
 
-### G.5 Inventory
+### G.6 Inventory
 
 Recommend `repo` on `tables[]` / `interfaces[]` / `pages[]` entries for unified mode traceability.
 
+### G.7 主仓一键 · Subagent 并行 (mode A)
+
+> Router: `prompts/approval/multi-repo-spoke-subagent.md` · Orchestrator: `skills/specflow-approval/SKILL.md` **Stage 1c**
+
+When user starts `/specflow:approval` from **primary** repo and chose **A (bundle)**:
+
+1. Primary writes `approval-playbook.yaml`; spoke indexes set `bundle.enabled: false`.
+2. **Parallel** Task subagents per non-primary repo → full spoke Map + 12e + `finalize` (no `--bundle`).
+3. Primary **wait gate** — all spokes `finalize_ok`.
+4. Primary Map + finalize + `finalize --bundle --workspace-root <primary.planning_root>`.
+
+**Anti-lazy (multi-repo)**: no unified LLM merge when mode A chosen; no stub spoke parts (`见 design.md` rows without decision text); each spoke needs `analysis.json` + `review-result.json` when `acp.review.enabled`.
+
+---
+
+## Part H: ACP Pipeline (Approval Compiler Pipeline)
+
+> Router: `prompts/approval/acp-pipeline.md` · AI review: `prompts/approval/ai-review.md`
+
+### H.1 When to use
+
+| Signal | Action |
+|--------|--------|
+| Segmented mode (`approval/parts/`) | **Always** run ACP Verify before assemble |
+| Multi-repo bundle | per_repo assemble → `approval bundle` |
+| Long doc / cross-part inconsistency risk | Enable `acp.review` (Stage 12e) |
+
+### H.2 Pipeline stages
+
+```text
+Analyze (Pass 1–7) → IR Freeze (index.yaml + interfaces[].frozen)
+→ Map (batched parts) → lint → review-pack → AI Review (12e) → review-check
+→ check → assemble → bundle (optional)
+```
+
+### H.3 index.yaml `acp` block
+
+```yaml
+acp:
+  pipeline: acp/v2
+  review:
+    enabled: true
+    required_pass: true   # assemble --require-review gates on this
+```
+
+Also freeze RPC names in `interfaces[].frozen` before Map batches.
+
+### H.4 CLI
+
+**Preferred (skill default)**:
+
+```bash
+specflow approval finalize <change> [--bundle] [--workspace-root <root>]
+```
+
+| Command | Purpose |
+|---------|---------|
+| `specflow approval review-hashes <change> [--json]` | Emit `part_hashes[]` for `review-result.json` |
+| `specflow approval finalize <change>` | One-shot: lint → review-check → check → assemble → bundle |
+| `specflow approval lint <change> [--strict]` | Debug / CI: cross-part consistency |
+| `specflow approval review-pack <change>` | Debug: generate review packet |
+| `specflow approval review-check <change>` | Debug: validate review-result |
+| `specflow approval check <change>` | Debug: parts/index validation |
+| `specflow approval assemble <change> [--require-review]` | Debug: merge parts only |
+| `specflow approval bundle <change>` | Debug: multi-repo readonly merge |
+
+### H.5 Stage 12e AI Review (mandatory when `acp.review.enabled`)
+
+Runs **inside `/specflow-approval`** — not as separate user steps:
+
+1. `specflow approval finalize <change>` — pauses with `review-packet.json` if needed
+2. Agent reads `prompts/approval/ai-review.md` + parts; fixes parts; writes `review-result.json`
+3. Re-run `specflow approval finalize <change>`
+
+AI review targets **long-document failure modes**: cross-part naming drift, inventory/body mismatch, depth imbalance across batches, unclosed branches, diagram/prose divergence, §4.6/§4.5 misalignment — not product-specific case rules.
+
+Optional domain packs (`runtime-guidance.md`, `api-guidance.md`) apply **only when** design/analysis mentions those topics.
+
+### H.6 Render (MD → HTML)
+
+```bash
+specflow approval render <change> [--input approval.md] [--output approval.html]
+specflow approval finalize <change> --render   # optional: render after finalize
+```
+
+Standalone HTML with embedded CSS; Mermaid diagrams load from CDN when present.
+
+### H.7 Playbook bundle (multi-repo)
+
+Template: `templates/approval-playbook.yaml`. Lists per-repo `approval.md` paths; `bundle` concatenates with repo headers — **no LLM merge**.
+

package/prompts/approval/multi-repo-guidance.md

@@ -69,25 +69,61 @@ multi_repo:
 ```text
 本需求跨 N 个仓库,审批技术文档如何产出?
 
-A) 一份合订文档 (unified) — 单份 approval.md,含各仓决策/接口/前端/Worker 切片
-B) 多份分仓文档 (per_repo) — 每个仓库各自一份 approval.md,仅写本仓范围
+A) 一份合订视图 (bundle) — 各仓 per_repo 真源 + CLI bundle 只读合订 (**推荐**)
+B) 多份分仓 (per_repo) — 每仓各自 approval.md（默认 Map 模式）
+C) 一份 LLM 合订 (legacy unified) — 仅当用户明确要求且无 bundle；不推荐
 
-请选择 A 或 B。
+请选择 A、B 或 C。
 ```
 
-### 2.1 Unified（一份合订）
+### 2.1 Bundle（推荐 — A）
 
-再询问:
+**真源**: 各仓 **per_repo** `approval.md` + `approval/parts/`（ACP Map 分片）。
 
-```text
-合订文档存放在哪个主仓?(approval.md 与 approval/ 工作区写在该仓 change 目录下)
+**只读合订**: 主仓 `approval-playbook.yaml` + `specflow approval bundle <primary.change>` → `approval-unified.md`（**无 LLM 合并**）。
+
+再询问主仓:
 
+```text
+合订 playbook 与 bundle 输出存放在哪个主仓?
 1) talos (平台)
 2) talos-web (控制台)
-3) talos-worker (Worker)
 …
+```
+
+**硬规则**:
+
+- `multi_repo.document_mode: per_repo`
+- `multi_repo.bundle.enabled: true`
+- `multi_repo.primary_repo: <id>` — playbook 与 bundle 输出路径
+- 各仓独立 Stage 12 + assemble；**全部 assemble 通过后** 在主仓执行 bundle
+- `acp.pipeline: acp/v2` 写入 `index.yaml`
 
-请选主仓 id。
+```yaml
+multi_repo:
+  document_mode: per_repo
+  primary_repo: talos
+  bundle:
+    enabled: true
+    output: approval-unified.md
+outputs:
+  per_repo: [ …各仓路径… ]
+  bundle:
+    repo: talos
+    change: scenario-job-compile
+    path: specflow/changes/scenario-job-compile/approval-unified.md
+```
+
+### 2.2 Per-repo only（B）
+
+见 §2.3；`bundle.enabled: false`。
+
+### 2.3 Legacy unified LLM 合订（C — 不推荐）
+
+仅在用户 **明确要求** 且拒绝 bundle 时使用。再询问主仓:
+
+```text
+合订文档存放在哪个主仓?(approval.md 与 approval/ 工作区写在该仓 change 目录下)
 ```
 
 **硬规则**:
@@ -112,7 +148,7 @@ outputs:
     path: specflow/changes/scenario-job-compile/approval.md
 ```
 
-### 2.2 Per-repo（多份分仓）
+### 2.4 Per-repo（B 详情）
 
 **硬规则**:
 
@@ -200,3 +236,28 @@ interfaces:
 ## 7. 与单仓关系
 
 `multi_repo.enabled=false` 时忽略本章;`change` 字段为当前规划根 change,行为与旧版一致。
+
+---
+
+## 8. 主仓一键 · Subagent 并行 (mode A/B)
+
+> Router: `prompts/approval/multi-repo-spoke-subagent.md` · Orchestrator: `skills/specflow-approval/SKILL.md` **Stage 1c**
+
+当用户在 **主仓** 发起 `/specflow:approval` 且已选 **A (bundle)** 或 **B (per_repo)**:
+
+| 角色 | 职责 |
+|------|------|
+| **主 Agent（主仓）** | intake、playbook、scope 拆分、闭环 Pass 1–11、主仓 Map、等待子仓、主仓 finalize、bundle |
+| **Subagent × 子仓** | 各子仓独立 `approval/` → Map → 12e → `finalize <spoke.change>`（**禁止** `--bundle`） |
+
+**硬顺序**:
+
+1. 主仓写好 `approval-playbook.yaml` + `multi_repo.repos[].root_hint`
+2. **并行**派发子仓 subagent（web / worker / …）
+3. **等待**全部 `finalize_ok: true`
+4. 主仓 Map + finalize
+5. 主仓 `finalize --bundle --workspace-root <主仓规划根>`
+
+**禁止**: 仅在主仓 unified 合订而不拆仓；子仓未 finalize 就 bundle；让用户手动 cd 子仓跑 CLI（除非 subagent 不可用）。
+
+**从 unified 迁移**: 将 `04.6-ui`、Worker L2 接口等 **搬迁** 到对应子仓 parts；主仓留 cross-ref + 平台/L3 正文。示例 playbook: `templates/approval-playbook-talos-scenario-job-compile.yaml`。

package/prompts/approval/multi-repo-spoke-subagent.md

@@ -0,0 +1,94 @@
+# Approval · Multi-Repo Spoke Subagent Brief
+
+> **Invoked by** primary `/specflow:approval` orchestrator via **Task** subagent (one per non-primary repo).
+> Primary repo Map/Review/Finalize stays on the **orchestrator** unless user explicitly runs approval from a spoke root.
+
+---
+
+## Mission
+
+Run **full ACP approval for ONE spoke repo only** — Index → Map → Stage 12e AI Review → `specflow approval finalize <spoke.change>` — scoped to that repo's four artifacts and **only** entities assigned to this repo in the shared playbook / primary `index.yaml`.
+
+**Do NOT** write into the primary repo. **Do NOT** LLM-merge cross-repo content into one file.
+
+**Spoke index rule**: only **`primary_repo`** sets `multi_repo.bundle.enabled: true` + hosts `approval-playbook.yaml`. Spoke repos set `bundle.enabled: false` — they **never** run `--bundle`.
+
+---
+
+## Inputs (primary must pass all)
+
+| Field | Example |
+|-------|---------|
+| `repo_id` | `talos-web` |
+| `planning_root` | `/Users/gankang/TALOS-WORK/talos-web` |
+| `change` | `web-scenario-cases` |
+| `role` | `web` |
+| `primary_change` | `scenario-job-compile` |
+| `primary_repo_id` | `talos` |
+| `workset_root` | `/Users/gankang/TALOS-WORK` |
+| `scope` | Which parts/capabilities/interfaces/pages belong to this spoke (from playbook or primary index) |
+| `cross_ref_policy` | Cross-repo refs: `见 talos approval §4.5 I8` — never duplicate platform DDL/RPC bodies |
+
+Read before writing:
+
+1. `specflow/changes/<change>/` four artifacts (phase must be `refined`)
+2. `prompts/approval/generate.md` (Part E/F), `acp-pipeline.md`, `ai-review.md`
+3. Role packs: `frontend-guidance.md` (web), `api-guidance.md` (worker), etc.
+4. Primary `approval/index.yaml` `multi_repo.repos[]` entry for this repo
+
+---
+
+## Hard scope rules
+
+| Role | Own in approval/parts | Cross-ref only (do not copy bodies) |
+|------|----------------------|-------------------------------------|
+| `platform` | compile, scheduler RPC/L4, DDL, gateway, ingest | Worker L2 HTTP, console pages |
+| `web` | §4.6 UI, web APIs (I5/I6), nav/routes | Platform scheduler/result RPC details |
+| `worker` | L2 Worker HTTP (I7/I9), executor logic, Pack | Platform L3 SubmitStepResult, Web UI |
+
+Each spoke document is **standalone per repo**: `01-intro` … `10-signoff` with **repo-scoped** §1–§3 and detailed §4 batches for that repo only.
+
+---
+
+## Execution order (spoke)
+
+```text
+cd <planning_root>
+→ Write approval/index.yaml (multi_repo.enabled=false OR spoke-local block only)
+→ Write approval/analysis.json (Passes scoped to this repo)
+→ 12a skeleton parts
+→ 12b Map batches (repo scope only)
+→ 12e: specflow approval finalize <change>  # may pause → review-packet
+→ Fix parts; write review-result.json + part_hashes (specflow approval review-hashes --json)
+→ specflow approval finalize <change>       # must exit ok
+```
+
+**Never** run `--bundle` on a spoke. Bundle is **primary only**, after all spokes report success.
+
+---
+
+## Return payload to orchestrator (required)
+
+Report in final message:
+
+```yaml
+repo_id: talos-web
+change: web-scenario-cases
+finalize_ok: true
+output_path: specflow/changes/web-scenario-cases/approval.md
+review_result: specflow/changes/web-scenario-cases/approval/review-result.json
+lint_errors: []
+blocked: false
+notes: ""
+```
+
+If `finalize_ok: false`, set `blocked: true` and paste diagnostics — orchestrator **must not** bundle.
+
+---
+
+## Anti-patterns
+
+- Writing `04.6-ui` into platform repo when web spoke exists
+- Running bundle from spoke cwd
+- Skipping finalize and pasting assembled markdown
+- Unified LLM merge (mode C) when mode A was chosen