@gordon.gan/specflow 1.4.6-beta → 1.7.0-beta

package/dist/core/approval/types.d.ts

@@ -11,23 +11,85 @@ export interface ApprovalBatching {
     readonly pages_per_call: number;
     readonly capabilities_per_call: number;
 }
+export type ApprovalRepoRole = 'platform' | 'web' | 'worker' | 'hub' | 'other';
+export type ApprovalDocumentMode = 'unified' | 'per_repo';
+export interface ApprovalMultiRepoEntry {
+    readonly id: string;
+    readonly label: string;
+    readonly role?: ApprovalRepoRole;
+    readonly change: string;
+    readonly root_hint?: string;
+}
+export interface ApprovalOutputRef {
+    readonly repo: string;
+    readonly change: string;
+    readonly path: string;
+}
+export interface ApprovalMultiRepoBundle {
+    readonly enabled?: boolean;
+    readonly playbook?: string;
+    readonly output?: string;
+    readonly readonly?: boolean;
+}
+export interface ApprovalMultiRepo {
+    readonly enabled: boolean;
+    readonly document_mode?: ApprovalDocumentMode;
+    readonly primary_repo?: string;
+    readonly repos: readonly ApprovalMultiRepoEntry[];
+    readonly outputs?: {
+        readonly unified?: ApprovalOutputRef;
+        readonly per_repo?: readonly ApprovalOutputRef[];
+    };
+    readonly bundle?: ApprovalMultiRepoBundle;
+}
+export interface ApprovalFeatureSlice {
+    readonly id: string;
+    readonly repos?: readonly string[];
+    readonly interfaces?: readonly string[];
+    readonly pages?: readonly string[];
+    readonly design_points?: readonly string[];
+    readonly parts: readonly string[];
+}
+export interface ApprovalAcpReview {
+    readonly enabled?: boolean;
+    readonly required_pass?: boolean;
+}
+export interface ApprovalAcpBlock {
+    readonly pipeline?: 'acp/v1' | 'acp/v2';
+    readonly context_budget_tokens?: number;
+    readonly output_budget_tokens?: number;
+    readonly feature_slices?: readonly ApprovalFeatureSlice[];
+    readonly review?: ApprovalAcpReview;
+}
 export interface ApprovalTableRef {
     readonly id: string;
     readonly name: string;
     readonly action: string;
     readonly part: string;
+    readonly repo?: string;
+}
+export interface ApprovalInterfaceFrozen {
+    readonly rpc?: string;
+    readonly http_path?: string;
+    readonly status_enum?: readonly string[];
 }
 export interface ApprovalInterfaceRef {
     readonly id: string;
     readonly short: string;
     readonly change: string;
     readonly part: string;
+    readonly repo?: string;
+    readonly layers?: readonly string[];
+    readonly pairs_with?: string;
+    readonly feature_slice?: string;
+    readonly frozen?: ApprovalInterfaceFrozen;
 }
 export interface ApprovalPageRef {
     readonly id: string;
     readonly route: string;
     readonly apis: readonly string[];
     readonly part: string;
+    readonly repo?: string;
 }
 export interface ApprovalCapabilityRef {
     readonly id: string;
@@ -57,6 +119,8 @@ export interface ApprovalIndex {
     readonly capabilities: readonly ApprovalCapabilityRef[];
     readonly batching: ApprovalBatching;
     readonly conventions: ApprovalConventionsResolved;
+    readonly multi_repo?: ApprovalMultiRepo;
+    readonly acp?: ApprovalAcpBlock;
     readonly meta?: {
         readonly language?: string;
         readonly tech_stack?: string;
@@ -84,6 +148,73 @@ export interface ApprovalDiagnostic {
     readonly message: string;
     readonly part?: string;
 }
+export interface ApprovalReviewFinding {
+    readonly id: string;
+    readonly severity: 'critical' | 'important' | 'minor';
+    readonly category: string;
+    readonly message: string;
+    readonly part?: string;
+    readonly status: 'open' | 'fixed' | 'waived';
+    readonly waiver_reason?: string;
+}
+export interface ApprovalReviewResult {
+    readonly schema: 'specflow.approval.review/v1';
+    readonly change: string;
+    readonly reviewed_at: string;
+    readonly reviewer: 'ai' | 'human';
+    readonly findings: readonly ApprovalReviewFinding[];
+    readonly verdict: 'pass' | 'fail' | 'pass_with_waivers';
+    readonly summary?: string;
+    readonly part_hashes?: readonly {
+        readonly id: string;
+        readonly sha256: string;
+    }[];
+}
+export interface ApprovalReviewPacket {
+    readonly schema: 'specflow.approval.review-packet/v1';
+    readonly change: string;
+    readonly generated_at: string;
+    readonly index_summary: {
+        readonly interfaces: number;
+        readonly pages: number;
+        readonly tables: number;
+        readonly parts: number;
+    };
+    readonly lint_diagnostics: readonly ApprovalDiagnostic[];
+    readonly parts: readonly {
+        readonly id: string;
+        readonly sha256: string;
+        readonly bytes: number;
+    }[];
+    readonly checklist: readonly string[];
+    readonly instructions: string;
+}
+export interface ApprovalPlaybookSource {
+    readonly repo: string;
+    readonly change: string;
+    readonly include_parts?: 'all' | readonly string[];
+    readonly root?: string;
+}
+export interface ApprovalPlaybook {
+    readonly schema: 'specflow.approval.playbook/v1';
+    readonly change: string;
+    readonly title: string;
+    readonly primary_repo: string;
+    readonly sources: readonly ApprovalPlaybookSource[];
+    readonly overlay?: readonly string[];
+    readonly assemble: {
+        readonly inject_headers?: boolean;
+        readonly dedupe_appendix?: boolean;
+        readonly output: string;
+        readonly readonly?: boolean;
+    };
+}
+export interface ApprovalBundleResult {
+    readonly ok: boolean;
+    readonly outputPath?: string;
+    readonly diagnostics: readonly ApprovalDiagnostic[];
+    readonly markdown?: string;
+}
 export interface ApprovalAssembleResult {
     readonly markdown?: string;
     readonly outputPath?: string;

package/dist/integrations/shared/capability-evidence.js

@@ -12,6 +12,8 @@ const MARKER_RULES = [
     { id: 'sub.approval.no_phase_change', skill: 'approval', includes: ['does NOT advance phase', 'phase stays `refined`'] },
     { id: 'sub.approval.code_grounding', skill: 'approval', includes: ['Code Grounding', 'Pass 6'] },
     { id: 'sub.approval.design_quality', skill: 'approval', includes: ['Design Quality Assessment', 'Over-Engineering'] },
+    { id: 'sub.approval.acp_finalize', skill: 'approval', includes: ['specflow approval finalize', 'Stage 12f'] },
+    { id: 'sub.approval.ai_review', skill: 'approval', includes: ['12e AI Review', 'part_hashes'] },
     { id: 'sub.apply.phase_a', skill: 'apply', includes: ['## Phase A: Task Rewrite'] },
     { id: 'sub.apply.phase_b', skill: 'apply', includes: ['## Phase B: Subagent TDD Execution'] },
     { id: 'sub.apply.gap_detection', skill: 'apply', includes: ['Gap Detection'] },

package/dist/integrations/shared/parity-manifest.js

@@ -18,6 +18,8 @@ export const CAPABILITY_MANIFEST = [
     { id: 'sub.approval.no_phase_change', commandId: 'approval', level: 'sub-capability', required: true },
     { id: 'sub.approval.code_grounding', commandId: 'approval', level: 'sub-capability', required: true },
     { id: 'sub.approval.design_quality', commandId: 'approval', level: 'sub-capability', required: true },
+    { id: 'sub.approval.acp_finalize', commandId: 'approval', level: 'sub-capability', required: true },
+    { id: 'sub.approval.ai_review', commandId: 'approval', level: 'sub-capability', required: true },
     { id: 'sub.apply.phase_a', commandId: 'apply', level: 'sub-capability', required: true },
     { id: 'sub.apply.phase_b', commandId: 'apply', level: 'sub-capability', required: true },
     { id: 'sub.apply.gap_detection', commandId: 'apply', level: 'sub-capability', required: true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.4.6-beta",
+  "version": "1.7.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,104 @@
+# 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`.
+
+---
+
+## 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/api-guidance.md

@@ -0,0 +1,179 @@
+# Approval · API / RPC / OpenAPI Guidance
+
+> Used by `/specflow:approval` before drafting **§4.5 接口设计** (after
+> `project-conventions-guidance.md` `topic=api`).
+>
+> **目的**:产出**可生成**的接口契约(非 narrative stub),并避免 **Worker 面 HTTP** 与 **平台内部 RPC**
+> 混写导致某一侧被省略。
+>
+> **优先级**:项目约定 + 现网 proto/OpenAPI **>** 本路由 **>** LLM。
+
+---
+
+## 0. When to run
+
+| 条件 | 必须执行 |
+|------|----------|
+| 本迭代有 **新增** HTTP 路径或 gRPC | 全文 §1–§4 |
+| 本迭代 **修改/行为扩展** 对外或 Worker 契约 | §1 分层 + §2 锁名 + §3 变更 delta |
+| 仅 **不变·本迭代消费** 既有 RPC/HTTP | §1 分层 + §4 完整骨架(字段/示例/错误);禁止一句带过 |
+| 三仓/多仓合订 | §1 **每层每面一个 `In`**,禁止用「内部调用」合并条目 |
+
+Announce after Read:
+
+```text
+API guidance: layering=<n surfaces> | proto=<path|draft in §4.5> | worker_openapi=<path|must draft>
+```
+
+---
+
+## 1. 接口分层 — 禁止混层 (fixes B2)
+
+一条业务链路上常有 **多个契约面**,每一面在 §4.5 清单中必须是 **独立 `In`**,各自完整展开:
+
+| 层 | 典型调用方 → 被调方 | 协议形态 | 清单命名示例 | 常见错误 |
+|----|---------------------|----------|--------------|----------|
+| L1 控制台/北向 | Web → Gateway | HTTP `/api/v1/...` | I1 调试启动 | 把字段只写在 design,§4.5 无表 |
+| L2 Worker 边车 HTTP | Worker → Gateway | HTTP `/internal/v1/...` + work 鉴权头 | I4 逐步上报 | **只写路径,无 OpenAPI schema** |
+| L3 平台编排 RPC | Gateway/调度 → 本服务 logic | gRPC + `google.api.http` | I4 对应 RPC(与 L2 同编号或 I4a/I4b 成对) | 写「暂定 RPC,HTTP 冻结」—— **禁止** |
+| L4 平台东向 RPC | 调度 → result/testcase/… | gRPC `client/<svc>/` | I6/I7 确保壳/写入逐步 | **用一句「内部调用 I7」代替 I4 的 RPC 详设** |
+
+### 1.1 硬规则
+
+1. **L2 与 L3 成对**:新增 Worker HTTP 路径时,**必须**同时写清:
+   - L2:HTTP method/path、必填头、request/response JSON 字段表、失败示例
+   - L3:冻结 RPC 全名、`message` 字段号、`option (google.api.http)`、Gateway 注册点
+2. **L4 不得 stub**:列入清单的东向 RPC(即使 proto 已存在)仍须 **§4.5.2 完整骨架**;
+   可标注「与现网 proto 一致」但**必须**贴字段表 + 成功/失败示例 + 错误表。
+3. **禁止**在 L2 小节写满 HTTP,再在 L4 用「经 client/result 调 I7」一行替代 I7 详设。
+4. **调用关系图**须显式画出 L2→L3→L4,例如:
+   `Worker --L2 HTTP--> Gateway --L3 RPC--> Scheduler --L4 RPC--> Result`
+
+### 1.2 三仓合订
+
+| 仓 | 负责的层 | §4.5 须写 |
+|----|----------|-----------|
+| talos | L3/L4 + Gateway 注册 | proto 草案 + 注册文件/函数 |
+| talos-worker | L2 | OpenAPI path + schema + 鉴权头示例 |
+| talos-web | L1 | HTTP 消费 + TS 类型(§4.6 交叉引用 `In`) |
+
+合订文档 **禁止**只写 talos 侧 L4 而 Worker OpenAPI 写「apply 时补」。
+
+---
+
+## 2. RPC / 服务名冻结 (fixes A1)
+
+### 2.1 禁止用语 (硬)
+
+下列写法 **一律禁止**出现在 §4.5 / §2 决策 / §4.8:
+
+- `暂定` / `TBD` / `实现时命名` / `实现时与 OpenAPI 对齐`
+- `如 SubmitXxx` / `例如 scheduler.SubmitXxx`
+- `RPC 名以实现为准`
+
+未锁名 → 视为 **BLOCKED**,不得标 READY;须 `[待 refine 澄清: RPC 名]` 或写入锁定名。
+
+### 2.2 必须输出
+
+| 项 | 格式 |
+|----|------|
+| 服务 | `package` 名,如 `scheduler` |
+| RPC | **冻结**全名,如 `scheduler.SubmitStepResult`(无「如」) |
+| HTTP | method + 完整 path(可含 `{job_id}`) |
+| proto 文件 | 相对路径,如 `proto/scheduler/scheduler.proto` |
+
+决策表新增行时使用 **Proposed → Accepted** 仅当 RPC 名已在 §4.5 冻结。
+
+---
+
+## 3. 可生成契约包 (fixes A2)
+
+对 **新增** 或 **修改 HTTP 绑定** 的 RPC,§4.5 **必须**含 **「Proto / OpenAPI 契约包」** 块(可用 `**Proto 草案**` 加粗标签,非标题):
+
+### 3.1 Proto 最小集
+
+```protobuf
+// 文件: proto/<svc>/<svc>.proto
+rpc SubmitStepResult(SubmitStepResultReq) returns (SubmitStepResultResp) {
+  option (google.api.http) = {
+    post: "/internal/v1/tasks/{job_id}/step-results"
+    body: "*"
+  };
+}
+message SubmitStepResultReq {
+  int32 schema_version = 1;
+  string request_id = 2;
+  // … 每个字段必须有号与类型
+}
+message SubmitStepResultResp {
+  int32 schema_version = 1;
+  string request_id = 2;
+  bool accepted = 3;
+  bool replayed = 4;
+}
+```
+
+要求:
+
+- 每个字段 **字段号 + 类型 + json_name**(若与 snake 不同)
+- `google.api.http` **完整** post/get/path/body
+- enum/status **闭合**,禁止「等」;与现网 ingest 白名单对齐(例:逐步 ingest 仅四终态)
+
+### 3.2 Gateway 注册 (硬)
+
+必须写明 **其一**:
+
+- 「与 `ReportProgress` / `SubmitResult` **同一**注册点:`<文件路径>` 函数 `<Name>`」
+- 或「ProtoSets 清单 `<path>` 新增 `<proto>` 条目」
+
+禁止只写「网关 ProtoSet 含新绑定」。
+
+### 3.3 Worker OpenAPI 交叉引用
+
+- 路径必须在 `talos-worker/contracts/v1/http.openapi.yaml`(或项目约定路径)**给出 schema 草案**
+- 必填头须与现网 progress/result **同构列出**:
+  `Idempotency-Key`, `Authorization-date`, `Authorization: TALOS-WORK-1:...`, `Content-Type`, `Accept`
+- HTTP 请求示例 **必须含上述头**,不得只有 JSON body
+
+### 3.4 错误映射
+
+| 条件 | gRPC `codes.*` | HTTP | 禁止 |
+|------|----------------|------|------|
+| 租约无效 | `FailedPrecondition` 或项目约定 **唯一**值 | **唯一** 403 或 409 | `403/409(与 progress 同类)` |
+
+---
+
+## 4. §4.5 逐接口最低深度 (含不变)
+
+每个 `In` **必须**含 generate.md §4.5.2 全部加粗块;额外:
+
+| 变更类型 | 额外要求 |
+|----------|----------|
+| 新增 L2+L3 | §3 契约包 + Gateway 注册 + Worker OpenAPI 指针 |
+| 修改 | 字段号/changelog + 兼容缺省 |
+| 不变·本迭代消费 | 从现网 proto/OpenAPI **摘录**字段表+示例;标注源路径;仍须失败示例 |
+| 不变·协议不变 | 同上;禁止「详见 OpenAPI」无正文 |
+
+---
+
+## 5. 自检 (生成后必过)
+
+- [ ] 清单中每个契约面有独立 `In`,无 L2/L4 混写 stub
+- [ ] 无「暂定/如/实现时」RPC 措辞
+- [ ] 新增 RPC 有 proto 字段号 + http option + 注册点
+- [ ] Worker HTTP 示例含完整 work 鉴权头
+- [ ] status/enum 闭合,与 ingest/现网校验一致
+- [ ] 错误表无「或」「同类映射」模糊语
+- [ ] L4 东向 RPC 非一句话 stub
+
+---
+
+## 6. 与 database / frontend guidance 对称
+
+| 包 | 路由 | 章节 |
+|----|------|------|
+| database | `database-guidance.md` | §4.4 |
+| frontend | `frontend-guidance.md` | §4.6 |
+| **api** | **本文件** | **§4.5** |
+
+`project-conventions-guidance.md` `topic=api` 解决「项目禁令与风格」;本文件解决「可生成契约与分层」。