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

package/README.md

@@ -126,7 +126,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 以 npm / package.json 为准（当前 1.4.6-beta）
+specflow --version   # 以 npm / package.json 为准（当前 1.5.0-beta）
 specflow --help
 ```
 

package/dist/core/approval/assemble.js

@@ -31,6 +31,11 @@ const LAZY_PATTERNS = [
     /TBD\s*[。.]?$/,
     /(?:^|\n)\s*\.{3}\s*(?:\n|$)/,
     /(?:^|\n)\s*(?:同上|同前)\s*[。.]?\s*(?:\n|$)/,
+    /实现时(?:命名|对齐)/,
+    /(?:RPC|rpc).*暂定/,
+    /暂定\s*[`']?\w+[`']?/,
+    /\b如\s+[A-Z]\w*(?:Result|Request|Response)/,
+    /内部(?:经|调用)\s*I\d+[^.\n]{0,40}(?:一行|代替|省略)/,
 ];
 const MIN_PART_BYTES = {
     '04.4': 200,
@@ -102,8 +107,21 @@ function buildDocumentHeader(index) {
     const stack = meta.tech_stack ?? 'unknown';
     const projectMode = meta.project_mode ?? 'brownfield';
     const modeNote = index.mode === 'segmented' ? 'segmented+assemble' : 'monolithic';
+    let multiRepoBlock = '';
+    const mr = index.multi_repo;
+    if (mr?.enabled && mr.repos.length >= 2) {
+        const mode = mr.document_mode ?? 'pending';
+        const primary = mr.primary_repo ?? '—';
+        const repoLines = mr.repos
+            .map((r) => `- ${r.label} \`${r.id}/${r.change}\``)
+            .join('\n');
+        multiRepoBlock = `
+> **多仓范围** (${mode}${mode === 'unified' ? `, 主仓: ${primary}` : ''}):
+${repoLines}
+`;
+    }
     return `# 技术方案审批文档: ${index.change}
-
+${multiRepoBlock}
 > 本文档由 \`/specflow:approval\` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
 > 含架构与详细设计等章节,供人工审批使用。AI 闭环/预审结论在对话中反馈,不写入本文。
 > 生成时间: ${index.generated_at} | phase: refined | 产物语言: ${lang} | 技术栈: ${stack} | 项目模式: ${projectMode} | 生成模式: ${modeNote}
@@ -166,6 +184,42 @@ export async function assembleApprovalDocument(options) {
             ],
         };
     }
+    if (index.multi_repo?.enabled) {
+        const mr = index.multi_repo;
+        if (!mr.document_mode) {
+            diagnostics.push({
+                code: 'multi_repo_mode_missing',
+                severity: 'error',
+                message: 'multi_repo.enabled but document_mode not set; ask user unified vs per_repo before assemble',
+            });
+        }
+        if (mr.document_mode === 'unified') {
+            if (!mr.primary_repo) {
+                diagnostics.push({
+                    code: 'multi_repo_primary_missing',
+                    severity: 'error',
+                    message: 'multi_repo.document_mode=unified requires primary_repo',
+                });
+            }
+            else {
+                const primary = mr.repos.find((r) => r.id === mr.primary_repo);
+                if (primary && primary.change !== index.change) {
+                    diagnostics.push({
+                        code: 'multi_repo_change_mismatch',
+                        severity: 'warning',
+                        message: `index.change "${index.change}" differs from primary repo change "${primary.change}"; assemble in primary planning root`,
+                    });
+                }
+            }
+        }
+        if (mr.document_mode === 'per_repo' && !mr.outputs?.per_repo?.length) {
+            diagnostics.push({
+                code: 'multi_repo_outputs_missing',
+                severity: 'warning',
+                message: 'per_repo mode should list outputs.per_repo[] with each repo approval path',
+            });
+        }
+    }
     const partsDir = getApprovalPartsDir(changeDir);
     try {
         await fs.access(partsDir);

package/dist/core/approval/index-schema.d.ts

@@ -29,47 +29,56 @@ export declare const approvalIndexSchema: z.ZodObject<{
         name: z.ZodString;
         action: z.ZodString;
         part: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         id: string;
         name: string;
         action: string;
         part: string;
+        repo?: string | undefined;
     }, {
         id: string;
         name: string;
         action: string;
         part: string;
+        repo?: string | undefined;
     }>, "many">>;
     interfaces: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         short: z.ZodString;
         change: z.ZodString;
         part: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         id: string;
         part: string;
         short: string;
         change: string;
+        repo?: string | undefined;
     }, {
         id: string;
         part: string;
         short: string;
         change: string;
+        repo?: string | undefined;
     }>, "many">>;
     pages: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         route: z.ZodString;
         apis: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         part: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         id: string;
         part: string;
         route: string;
         apis: string[];
+        repo?: string | undefined;
     }, {
         id: string;
         part: string;
         route: string;
+        repo?: string | undefined;
         apis?: string[] | undefined;
     }>, "many">>;
     capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -127,6 +136,172 @@ export declare const approvalIndexSchema: z.ZodObject<{
         tech_stack?: string | undefined;
         project_mode?: string | undefined;
     }>>;
+    multi_repo: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        document_mode: z.ZodOptional<z.ZodEnum<["unified", "per_repo"]>>;
+        primary_repo: z.ZodOptional<z.ZodString>;
+        repos: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            role: z.ZodOptional<z.ZodEnum<["platform", "web", "worker", "hub", "other"]>>;
+            change: z.ZodString;
+            root_hint: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }, {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }>, "many">;
+        outputs: z.ZodOptional<z.ZodObject<{
+            unified: z.ZodOptional<z.ZodObject<{
+                repo: z.ZodString;
+                change: z.ZodString;
+                path: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                path: string;
+                repo: string;
+                change: string;
+            }, {
+                path: string;
+                repo: string;
+                change: string;
+            }>>;
+            per_repo: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                repo: z.ZodString;
+                change: z.ZodString;
+                path: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                path: string;
+                repo: string;
+                change: string;
+            }, {
+                path: string;
+                repo: string;
+                change: string;
+            }>, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        }, {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    }, {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    }>, {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    }, {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     schema: "specflow.approval.index/v1";
     conventions: {
@@ -154,18 +329,21 @@ export declare const approvalIndexSchema: z.ZodObject<{
         name: string;
         action: string;
         part: string;
+        repo?: string | undefined;
     }[];
     interfaces: {
         id: string;
         part: string;
         short: string;
         change: string;
+        repo?: string | undefined;
     }[];
     pages: {
         id: string;
         part: string;
         route: string;
         apis: string[];
+        repo?: string | undefined;
     }[];
     capabilities: {
         id: string;
@@ -182,6 +360,30 @@ export declare const approvalIndexSchema: z.ZodObject<{
         tech_stack?: string | undefined;
         project_mode?: string | undefined;
     } | undefined;
+    multi_repo?: {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    } | undefined;
 }, {
     schema: "specflow.approval.index/v1";
     change: string;
@@ -209,17 +411,20 @@ export declare const approvalIndexSchema: z.ZodObject<{
         name: string;
         action: string;
         part: string;
+        repo?: string | undefined;
     }[] | undefined;
     interfaces?: {
         id: string;
         part: string;
         short: string;
         change: string;
+        repo?: string | undefined;
     }[] | undefined;
     pages?: {
         id: string;
         part: string;
         route: string;
+        repo?: string | undefined;
         apis?: string[] | undefined;
     }[] | undefined;
     capabilities?: {
@@ -237,6 +442,30 @@ export declare const approvalIndexSchema: z.ZodObject<{
         tech_stack?: string | undefined;
         project_mode?: string | undefined;
     } | undefined;
+    multi_repo?: {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    } | undefined;
 }>;
 export declare function parseApprovalIndex(raw: unknown): ApprovalIndex;
 /** Returns true when segmented fast-path (monolithic) is allowed. */

package/dist/core/approval/index-schema.js

@@ -4,23 +4,78 @@ const tableRefSchema = z.object({
     name: z.string().min(1),
     action: z.string().min(1),
     part: z.string().min(1),
+    repo: z.string().min(1).optional(),
 });
 const interfaceRefSchema = z.object({
     id: z.string().min(1),
     short: z.string().min(1),
     change: z.string().min(1),
     part: z.string().min(1),
+    repo: z.string().min(1).optional(),
 });
 const pageRefSchema = z.object({
     id: z.string().min(1),
     route: z.string().min(1),
     apis: z.array(z.string()).default([]),
     part: z.string().min(1),
+    repo: z.string().min(1).optional(),
 });
 const capabilityRefSchema = z.object({
     id: z.string().min(1),
     part: z.string().min(1),
 });
+const outputRefSchema = z.object({
+    repo: z.string().min(1),
+    change: z.string().min(1),
+    path: z.string().min(1),
+});
+const multiRepoSchema = z
+    .object({
+    enabled: z.boolean(),
+    document_mode: z.enum(['unified', 'per_repo']).optional(),
+    primary_repo: z.string().min(1).optional(),
+    repos: z
+        .array(z.object({
+        id: z.string().min(1),
+        label: z.string().min(1),
+        role: z.enum(['platform', 'web', 'worker', 'hub', 'other']).optional(),
+        change: z.string().min(1),
+        root_hint: z.string().min(1).optional(),
+    }))
+        .min(1),
+    outputs: z
+        .object({
+        unified: outputRefSchema.optional(),
+        per_repo: z.array(outputRefSchema).optional(),
+    })
+        .optional(),
+})
+    .superRefine((value, ctx) => {
+    if (!value.enabled) {
+        return;
+    }
+    if (value.repos.length < 2) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'multi_repo.repos must have at least 2 entries when enabled',
+            path: ['repos'],
+        });
+    }
+    if (value.document_mode === 'unified' && !value.primary_repo) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'multi_repo.primary_repo is required when document_mode is unified',
+            path: ['primary_repo'],
+        });
+    }
+    if (value.primary_repo && !value.repos.some((r) => r.id === value.primary_repo)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'multi_repo.primary_repo must match a repos[].id',
+            path: ['primary_repo'],
+        });
+    }
+});
 export const approvalIndexSchema = z.object({
     schema: z.literal('specflow.approval.index/v1'),
     change: z.string().min(1),
@@ -71,6 +126,7 @@ export const approvalIndexSchema = z.object({
         project_mode: z.string().optional(),
     })
         .optional(),
+    multi_repo: multiRepoSchema.optional(),
 });
 export function parseApprovalIndex(raw) {
     return approvalIndexSchema.parse(raw);

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

@@ -1,4 +1,4 @@
-export type { ApprovalAssembleResult, ApprovalDiagnostic, ApprovalIndex, ApprovalManifest, ApprovalGenerationMode, } from './types.js';
+export type { ApprovalAssembleResult, ApprovalDiagnostic, ApprovalIndex, ApprovalManifest, ApprovalGenerationMode, ApprovalMultiRepo, ApprovalDocumentMode, } from './types.js';
 export { parseApprovalIndex, isLightweightApproval, shouldForceSegmented, approvalIndexSchema, } from './index-schema.js';
 export { getChangeDirectory, getApprovalWorkspaceDir, getApprovalIndexPath, getApprovalManifestPath, getApprovalPartsDir, getApprovalPartPath, getApprovalOutputPath, getApprovalAnalysisPath, } from './paths.js';
 export { assembleApprovalDocument, readApprovalIndex, readApprovalManifest, } from './assemble.js';

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

@@ -11,23 +11,50 @@ 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 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[];
+    };
+}
 export interface ApprovalTableRef {
     readonly id: string;
     readonly name: string;
     readonly action: string;
     readonly part: string;
+    readonly repo?: string;
 }
 export interface ApprovalInterfaceRef {
     readonly id: string;
     readonly short: string;
     readonly change: string;
     readonly part: string;
+    readonly repo?: string;
 }
 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 +84,7 @@ export interface ApprovalIndex {
     readonly capabilities: readonly ApprovalCapabilityRef[];
     readonly batching: ApprovalBatching;
     readonly conventions: ApprovalConventionsResolved;
+    readonly multi_repo?: ApprovalMultiRepo;
     readonly meta?: {
         readonly language?: string;
         readonly tech_stack?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.4.6-beta",
+  "version": "1.5.0-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [

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` 解决「项目禁令与风格」;本文件解决「可生成契约与分层」。

package/prompts/approval/generate.md

@@ -20,8 +20,9 @@ Before running this flow, the SKILL.md has confirmed:
 - Tech Stack Intake gate completed when greenfield or stack dimensions are missing
   (user confirmed 前端 / 后端 / 数据库与缓存 / 基础设施, or marked「不涉及」)
 - `uiInScope` resolved; when yes, FE 五元组 confirmed (or marked pending refine)
-- Anchor files extracted from `design.md` + `tasks.md`
+- Anchor files extracted from **each in-scope repo** when `multi_repo.enabled` (Stage 1b)
 - Optional: `specflow/specs/` baseline exists (for Pass 7)
+- When multi-repo: `multi_repo.document_mode` + (`primary_repo` if unified) confirmed by user
 
 You MUST read, in this order, before any analysis:
 
@@ -37,6 +38,11 @@ You MUST read, in this order, before any analysis:
 Do not skip any of the four required artifacts. If any is missing, stop and tell the
 SKILL.md caller which are missing.
 
+When **`multi_repo.enabled=true`**, read **`prompts/approval/multi-repo-guidance.md`** first.
+Load four artifacts **from every repo** in `multi_repo.repos[]` before analysis. Unified mode
+merges cross-repo content into **one** document stored under **`primary_repo`**; per_repo mode
+writes **separate** `approval.md` per repo (see §G).
+
 ---
 
 ## Part A: Closed-Loop Verification (7 Passes)
@@ -809,7 +815,7 @@ CREATE TABLE `orders` (
 **适用范围**:暴露 API / RPC / CLI 命令 / 跨模块函数接口的变更(含「协议不变但本迭代新消费」)。
 **项目类型适配**:Web/服务 → HTTP(+RPC);CLI → commander 等命令参数;库 → 导出函数签名。
 
-> **项目约定(先于起草)**:执行 `prompts/approval/project-conventions-guidance.md`,`topic=api`。  
+> **项目约定(先于起草)**:执行 `prompts/approval/project-conventions-guidance.md`,`topic=api`;再执行 **`prompts/approval/api-guidance.md`**(分层、RPC 锁名、proto/OpenAPI 可生成包)。  
 > 懒加载项目 API/错误码/鉴权/契约约定。有 UI 时 **§4.6** 另跑 `topic=frontend` + `frontend-guidance.md`
 > (勿把页面树塞进 §4.5)。  
 > **优先级**:项目约定 + 现网 OpenAPI/proto **>** SpecFlow §4.5 骨架 **>** LLM。  
@@ -859,6 +865,17 @@ CREATE TABLE `orders` (
 
 > **清单规则(硬)**:本迭代**不调用、不消费**的接口 **不列入** §4.5 清单。**一旦列入清单,无论变更类型是否为「不变」,均须按 §4.5.2 完整骨架输出**,不得精简、不得只写路径、不得跳过示例。
 
+> **分层规则(硬 — 防 B2 类混写)**:同一业务链上的 **Worker HTTP(L2)**、**平台 gRPC+HTTP 绑定(L3)**、**东向 client RPC(L4)** 必须是 **独立 `In`**,各自完整展开。禁止在 L2 写满 HTTP 后,用「内部经 I6/I7 调用」一行代替 L4 详设。见 `api-guidance.md` §1。
+
+**2b) 契约面分层(合订/三端推荐)**:
+
+| 层 | 面 | 清单要求 |
+|----|-----|----------|
+| L1 | 控制台 HTTP | 字段表 + 示例 + 错误 |
+| L2 | Worker→Gateway HTTP | OpenAPI schema 草案 + **完整** work 鉴权头示例 |
+| L3 | Gateway 转码 RPC | **冻结** RPC 名 + proto 字段号 + `google.api.http` + **Gateway 注册点** |
+| L4 | 平台 `client/<svc>/` RPC | 完整骨架;不变亦须字段表+示例,禁止 stub |
+
 **3) 通用错误码约定**(强制;按项目现网风格映射):
 
 | 错误类别 / 状态 | 典型 HTTP 或退出码 | 含义(本迭代) |
@@ -876,6 +893,8 @@ CREATE TABLE `orders` (
 3. **幂等 / 终态语义**:若存在上报类接口,写清「成功 ≠ 资源终态」等不变量(对齐 §2 决策)。
 4. **兼容缺省**:可选字段缺省时的兼容行为写进字段表「默认」列。
 5. **与流程对齐**:接口编号可被 §4.2/§4.3 时序与 §6 测试引用。
+6. **RPC 锁名(硬)**:新增/修改 gRPC **禁止**「暂定」「如 XxxRpc」「实现时命名/对齐」。须写死 `package.ServiceMethod`,并在决策表或 §4.5 元信息一致。见 `api-guidance.md` §2。
+7. **错误映射唯一(硬)**:条件 → **唯一** gRPC code → **唯一** HTTP;禁止「403/409(与 progress 同类)」「或现网」。
 
 ##### 4.5.2 逐接口详设(强制骨架)
 
@@ -888,8 +907,9 @@ CREATE TABLE `orders` (
 | 应用场景 | 谁、在什么用户动作/系统时机下调用 |
 | 协议 | 方法 + 路径(或 CLI 命令 / 导出函数签名) |
 | Content-Type / 编码 | 如 `application/json`(若适用) |
-| 对应 RPC / 内部名 | 若有(可写暂定名 +「实现时与 OpenAPI/proto 对齐」) |
+| 对应 RPC / 内部名 | **冻结**全名(例 `scheduler.SubmitStepResult`);proto 路径;**禁止**暂定/如/实现时 |
 | 鉴权 | 本接口鉴权要点(可引用通道表) |
+| Gateway 注册 | 新增 HTTP 绑定时:**文件+函数名**或 ProtoSets 路径(禁止只写「含新绑定」) |
 | 本迭代变更 | 一句话(新增字段 / 行为扩展 / 不变仅消费 …) |
 
 2. **请求体字段**(有则写;路径参数 / Query / CLI flags 用同级加粗标签分块,如 `**Query 参数**`,仍**不要**升为标题):
@@ -912,6 +932,13 @@ CREATE TABLE `orders` (
 
 7. **处理顺序**(可选):多步服务端合同用编号列表;与 §4.2/§4.3、§4.4 对齐。
 
+8. **Proto / OpenAPI 契约包**( **新增** 或 **修改 HTTP 绑定** 的 RPC — 硬):在接口小节末尾用加粗标签 `**Proto 草案**` / `**OpenAPI 指针**` 输出:
+   - proto:`rpc` 全名 + `message` 字段号表 + `google.api.http` 原文
+   - Gateway:与现网同类 RPC **同一注册点**的文件/函数,或 ProtoSets 条目
+   - Worker:OpenAPI 路径 + schema 字段与 L3 一致;HTTP 示例含 **全部** 必填头
+   - status/enum **闭合**,与现网 ingest 校验一致(禁止「等」、禁止逐步 ingest 写 `running` 除非同步改白名单)
+   详见 `api-guidance.md` §3。
+
 ##### 4.5.3 调用关系(推荐)
 
 用短文本或 Mermaid 概括调用方如何串起 `I1…In`(主路径一条线即可),便于实现与联调对照。
@@ -925,6 +952,8 @@ CREATE TABLE `orders` (
 
 - [ ] 有通道/鉴权表(或多通道说明)+ 本迭代接口清单(编号+变更类型+场景)
 - [ ] 有通用错误码约定 + 命名/错误风格约定
+- [ ] **分层**:L2 Worker HTTP / L3 RPC / L4 东向 RPC 各有独立 `In`,无「内部调用」stub
+- [ ] **RPC 已冻结**:无暂定/如/实现时;新增 RPC 含 proto 字段号 + http option + Gateway 注册点
 - [ ] 清单中**每个**接口(含**不变**)具备:元信息、字段表、成功请求/响应示例、**失败示例(G2)**、错误表
 - [ ] **不变**接口未因「无协议变更」而省略字段表/示例;内容与现网契约或锚点一致
 - [ ] 无「只有路径、无字段/无示例/无错误」的偷懒写法;示例与字段表一致
@@ -1312,14 +1341,16 @@ specflow init --artifact-language <language>
    (d) 每张表字段说明表(含「本迭代用法」)。
    禁止仅用散文描述 schema。MySQL DDL 禁止省略 ENGINE/CHARSET。零 DDL 迭代仍须展示当前基线 DDL —— 当表处于读/写路径时,禁止声称「不涉及数据库」。
 
-10. **§4.5 接口章节质量(硬规则)**:若变更涉及对外/跨服务/跨模块接口(含新增、修改、行为扩展、**协议不变但本迭代消费或调用**),§4.5 **必须**包含:
+10. **§4.5 接口章节质量(硬规则)**:起草前执行 `project-conventions-guidance.md` `topic=api` + **`api-guidance.md`**.若变更涉及对外/跨服务/跨模块接口(含新增、修改、行为扩展、**协议不变但本迭代消费或调用**),§4.5 **必须**包含:
     (a) 调用方/通道 + 鉴权总览,
     (b) 编号稳定的接口清单(变更类型含 新增/修改/行为扩展/不变·本迭代消费/不变·协议不变),
-    (c) 通用错误码映射与命名/错误风格约定,
-    (d) 清单中**每个**接口的元信息表、字段表(名/型/必填/默认/说明)、≥1 组成功请求示例与成功响应示例,
-    **(e) 每个接口 ≥1 组失败请求/响应示例(G2)**(「不变」接口亦须典型失败场景),
-    (f) 错误条件表。
-    禁止只写路径名的 stub。**一旦列入 §4.5 清单,无论协议是否变更,均须完整格式输出**;禁止因「与现网一致」而省略字段表/示例/错误约定(可标注「与现网一致」并仍给出完整骨架)。
+    (c) **契约面分层**:Worker HTTP / 平台 RPC+HTTP 绑定 / 东向 RPC **各自独立 `In`**,禁止 L2 详写、L4 一句 stub,
+    (d) 通用错误码映射(**唯一** gRPC code → **唯一** HTTP;禁止「或」「同类映射」),
+    (e) 清单中**每个**接口的元信息表、字段表、≥1 组成功请求/响应示例,
+    **(f) 每个接口 ≥1 组失败示例(G2)**,
+    (g) 错误条件表,
+    **(h) 新增/改 HTTP 绑定的 RPC**:冻结 RPC 全名 + proto 字段号 + `google.api.http` + Gateway 注册点 + Worker OpenAPI schema(禁止「暂定」「如」「实现时对齐」)。
+    禁止 stub。**一旦列入清单,无论是否不变,均须完整骨架**;可标注「与现网一致」但仍须贴字段表与示例。
 
 11. **§3 架构图须附设计要点(硬规则)**:每个架构 Mermaid 图后**必须**跟编号「设计说明 / 图要点」列表(边界/不变式/复用) —— 禁止仅复述节点名。仅有组件表不够。
 
@@ -1394,7 +1425,9 @@ When `approval/index.yaml` has `mode: segmented` (default for non-trivial §4),
 | L3 | `TODO` / `待补充` / `此处省略` / bare `TBD` | Concrete text or `[待 refine 澄清: <元素>]` |
 | L4 | `详见 design/tasks` without §/In/Page id | Cross-ref `§4.5 I2` / `Page·列表` / `P1` |
 | L5 | New table/interface/page ids not in index | Update `index.yaml` first |
-| L6 | Skip DDL/字段表/失败示例 because "same as design" or "unchanged API" | G2–G6 minimum per entity; **不变**接口仍须完整 §4.5 骨架 |
+| L6 | Skip DDL/字段表/失败示例 because "same as design" or "unchanged API" | G2–G6 minimum; **不变**仍须完整 §4.5 骨架 |
+| L6b | Collapse L4 RPC into「内部调用 I7」; L2-only HTTP without proto | **分层**: L2/L3/L4 各独立 `In`;见 `api-guidance.md` §1 |
+| L6c | RPC「暂定/如/实现时命名」 | **冻结** `Service.Method` + proto 字段号;见 `api-guidance.md` §2–§3 |
 | 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 |
@@ -1430,3 +1463,36 @@ Do not reload entire four artifacts each batch.
 
 Do not rerun Pass 1–7 unless analysis is stale.
 
+---
+
+## Part G: Multi-Repo Approval (多仓)
+
+> Router: `prompts/approval/multi-repo-guidance.md`
+
+### G.1 Trigger
+
+User natural language, workset, or cross-repo design → `multi_repo.enabled=true`.
+
+### 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.
+
+### G.3 Unified 合订
+
+- 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 分仓
+
+- 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
+
+Recommend `repo` on `tables[]` / `interfaces[]` / `pages[]` entries for unified mode traceability.
+

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

@@ -0,0 +1,202 @@
+# Approval · Multi-Repo (多仓) Guidance
+
+> Used by `/specflow:approval` when the user **自然语言指定多仓**、workset 含多个规划根、或
+> design/tasks 明确跨 `talos` / `talos-web` / `talos-worker` 等仓库。
+>
+> **目的**:按各仓四件套与锚点生成技术审批文档,并 **询问用户** 产出 **一份合订** 还是 **多份分仓**;
+> 合订时 **必须** 指定 **主仓** 存放 `approval.md` 与 `approval/` 工作区。
+
+---
+
+## 0. When to run
+
+| 信号 | 动作 |
+|------|------|
+| 用户说「三仓 / talos+web+worker / 多仓合订 / 前后端一体」 | 启用 `multi_repo.enabled=true` |
+| `specflow workset` / 会话上下文含多个 git 规划根 | 列出候选仓,请用户确认 |
+| 仅单仓 change,无跨仓表述 | `multi_repo.enabled=false`,走单仓流程 |
+| Hub + Spoke 联邦 | 见 §5;各 Spoke 可有不同 change id |
+
+Announce:
+
+```text
+Multi-repo approval: enabled | single-repo
+Repos in scope: talos(scenario-job-compile), talos-web(web-scenario-cases), …
+Document mode: (pending user) unified | per_repo
+Primary repo (if unified): (pending user)
+```
+
+---
+
+## 1. Resolve repos (硬顺序)
+
+1. **Parse user natural language** — 仓名、别名(平台/控制台/Worker)、change 名。
+2. **Cross-check workset** — `specflow workset list` / 用户给出的绝对路径;成员顺序 **不** 等于主仓。
+3. **Per repo, verify** (Read-only):
+   - `specflow/changes/<change>/.specflow.yaml` → `phase: refined`
+   - 四件套:`proposal.md`, `specs/**`, `design.md`, `tasks.md`
+4. **Record** in `approval/index.yaml` → `multi_repo.repos[]`:
+
+```yaml
+multi_repo:
+  enabled: true
+  document_mode: unified   # unified | per_repo — 用户确认后写入
+  primary_repo: talos      # unified 时必填
+  repos:
+    - id: talos
+      label: 平台
+      role: platform
+      change: scenario-job-compile
+      root_hint: /path/to/talos    #  agent 读取用,可选
+    - id: talos-web
+      label: 控制台
+      role: web
+      change: web-scenario-cases
+    - id: talos-worker
+      label: Worker
+      role: worker
+      change: scenario-execution
+```
+
+**禁止**在未 Read 各仓四件套前假设内容一致;change id **可以** 各仓不同。
+
+---
+
+## 2. User gate — 一份还是多份 (硬)
+
+在 Pass 1 之前或 Stage 12a 之前,**必须** 询问:
+
+```text
+本需求跨 N 个仓库,审批技术文档如何产出?
+
+A) 一份合订文档 (unified) — 单份 approval.md,含各仓决策/接口/前端/Worker 切片
+B) 多份分仓文档 (per_repo) — 每个仓库各自一份 approval.md,仅写本仓范围
+
+请选择 A 或 B。
+```
+
+### 2.1 Unified（一份合订）
+
+再询问:
+
+```text
+合订文档存放在哪个主仓?(approval.md 与 approval/ 工作区写在该仓 change 目录下)
+
+1) talos (平台)
+2) talos-web (控制台)
+3) talos-worker (Worker)
+…
+
+请选主仓 id。
+```
+
+**硬规则**:
+
+- `multi_repo.document_mode: unified`
+- `multi_repo.primary_repo: <id>` **必填**
+- **工作区路径**(分片模式):
+  - `specflow/changes/<primary.change>/approval/index.yaml`
+  - `specflow/changes/<primary.change>/approval/parts/*.md`
+  - 产出:`specflow/changes/<primary.change>/approval.md`
+- CLI:`specflow approval assemble <primary.change>` **在主仓规划根**执行
+- 文档 §1.2 / §2.3 / 附录 B **必须** 按仓分表;Pass 6 锚点 **分仓列举**
+- 合订 **不是** 只写主仓 design;须合并各仓 specs/design/tasks 的跨端语义
+
+写入 `multi_repo.outputs.unified`:
+
+```yaml
+outputs:
+  unified:
+    repo: talos
+    change: scenario-job-compile
+    path: specflow/changes/scenario-job-compile/approval.md
+```
+
+### 2.2 Per-repo（多份分仓）
+
+**硬规则**:
+
+- `multi_repo.document_mode: per_repo`
+- **每个** `repos[]` 条目独立:
+  - 在该仓 `specflow/changes/<repo.change>/approval/`(分片)或 `approval.md`(单体)
+  - 内容 **仅** 本仓 scope;交叉引用用「见 `<other-repo>` approval §x」
+- 各仓分别 `specflow approval assemble <repo.change>`(若在主仓 CLI,需 `--store` 或 cd 到该根)
+- **禁止**只在主仓写一份然后复制到其它仓
+
+写入 `multi_repo.outputs.per_repo[]`:
+
+```yaml
+outputs:
+  per_repo:
+    - repo: talos
+      change: scenario-job-compile
+      path: specflow/changes/scenario-job-compile/approval.md
+    - repo: talos-web
+      change: web-scenario-cases
+      path: specflow/changes/web-scenario-cases/approval.md
+```
+
+---
+
+## 3. Analysis & Map 上下文
+
+| 模式 | Read 范围 | index 库存 |
+|------|-----------|------------|
+| unified | 各仓四件套 + 各仓锚点 + 各仓约定 | `interfaces/pages/tables` 带 `repo` 字段(推荐) |
+| per_repo | **当前仓**四件套 + 本仓锚点 | 仅本仓实体 |
+
+**Unified 分片建议**:
+
+- `02-design-review` — 三仓决策表
+- `04.5-api` — 按 `repo` 或 L1/L2/L3/L4 分批;Worker 切片须 Read `api-guidance.md` + worker OpenAPI 路径
+- `04.6-*` — 仅 `ui_in_scope` 且 web 仓
+- 附录 B — 按仓允许/禁止路径
+
+**Inventory 扩展**(可选列):
+
+```yaml
+interfaces:
+  - id: I4
+    short: 逐步上报
+    change: scenario-job-compile
+    part: 04.5-api-worker
+    repo: talos-worker
+```
+
+---
+
+## 4. Document header (unified)
+
+合订 `approval.md` 头部 **必须** 声明:
+
+```markdown
+> **覆盖变更（多仓合订,主仓: talos）**:
+> - 平台 `talos/scenario-job-compile`
+> - 控制台 `talos-web/web-scenario-cases`
+> - Worker `talos-worker/scenario-execution`
+> **存放路径**: `specflow/changes/scenario-job-compile/approval.md`
+```
+
+---
+
+## 5. Hub / Federated 注意
+
+- Hub change id 可与 Spoke change id **同名或不同**;`multi_repo.repos[].change` 用 **各规划根内真实目录名**。
+- Hub 合同摘要可读 `--store`;Spoke approval **不**替代 Hub archive。
+- `coordination.yaml`(若有)可 Read;无则 chat 列出各仓 phase。
+
+---
+
+## 6. 自检
+
+- [ ] 用户已选 unified **或** per_repo
+- [ ] unified → `primary_repo` 已选且工作区在该仓
+- [ ] per_repo → 每仓输出路径已写入 `outputs.per_repo`
+- [ ] 各仓四件套已 Read;非主仓内容已进合订正文或分仓文档
+- [ ] Gate 摘要中列出 **所有** 将写入的 `approval.md` 路径
+
+---
+
+## 7. 与单仓关系
+
+`multi_repo.enabled=false` 时忽略本章;`change` 字段为当前规划根 change,行为与旧版一致。

package/prompts/approval/project-conventions-guidance.md

@@ -33,7 +33,7 @@ Conflict policy: project > SpecFlow guidance > LLM
 |--------------|----------------------|----------------|
 | `architecture` | 起草 **§3** 前 | 分层、模块边界、目录约定、禁止直连 |
 | `database` | 起草 **§4.4** 前(且有持久化) | 迁移工具禁令、命名、字符集、现网表规范 |
-| `api` | 起草 **§4.5** 前(且有对外/跨端接口) | 错误码、鉴权、契约/OpenAPI、通道 |
+| `api` | 起草 **§4.5** 前(且有对外/跨端接口) | 错误码、鉴权、契约/OpenAPI、通道;然后 **`api-guidance.md`**(分层、RPC 锁名、proto 可生成包) |
 | `frontend` | 起草 **§4.6** 前(且 `uiInScope=yes`) | 组件/状态/路由/API client/设计系统/**表单/测试/a11y** 等落地约定;须含 IDE skills/rules 扫描(见 `frontend-guidance.md` §3) |
 
 每个主题 **最多 Read 5 个文件**(配置列出的优先;自动探测时取最相关的前 5 个)。细节 references 仅在入口文件点名时再读(禁止 reference 链式跳转)。

package/prompts/approval/segmented-generation.md

@@ -40,7 +40,9 @@ Gate                  →  user confirms index + optional chapters + mode
 | L3 | `TODO` / `待补充` / `此处省略` / bare `TBD` | Concrete text or `[待 refine 澄清: <元素>]` with reason |
 | L4 | `详见 design/tasks` without §/In/Page id | Cross-ref `§4.5 I2` / `Page·列表` / `P1` |
 | L5 | Invent new table/interface/page ids not in index | Update index.yaml first, then write part |
-| L6 | Skip §4.4 DDL/字段表/失败示例 because "same as design" | Minimum viable implementer-ready detail per G2–G6 |
+| L6 | Skip §4.4 DDL/字段表/失败示例 because "same as design" | Minimum per G2–G6; **不变**仍须完整 §4.5 |
+| L6b | L2 HTTP only +「内部 I7」stub; or L4 one-liner | **分层** L2/L3/L4 各 `In`; `api-guidance.md` §1 |
+| L6c | RPC「暂定/如/实现时」 | **冻结**名 + proto 字段号; `api-guidance.md` §2–§3 |
 | 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 table |
 | L9 | Write `## 4.` or foreign `## N.` in parts | Parts use `###`/`####`/`#####` only; CLI injects `## 4` |
@@ -86,8 +88,12 @@ For each batch, **Read only**:
 
 ### §4.5 part minimum (per interface)
 
-- meta table + fields + success req/resp + **failure example (G2)** + error table
-- **不变**接口亦须完整骨架(元信息/字段/成功与失败示例/错误表);禁止因「协议无变更」精简
+- Run **`api-guidance.md`** before batch
+- **One `In` per contract surface** (L2 Worker HTTP / L3 RPC+http / L4 client RPC) — no B2-style collapse
+- meta + fields + success req/resp + **failure example (G2)** + error table (**含不变**)
+- **新增/改 HTTP binding**: `**Proto 草案**` block — frozen RPC name, field numbers, `google.api.http`, Gateway registration, Worker OpenAPI path
+- HTTP examples for L2: **all** required work auth headers (not body-only)
+- **Forbidden**: 暂定 / 如 XxxRpc / 实现时命名 / 内部经 I7 一行代替 L4 详设
 
 ### §4.6 part minimum (per page)
 

package/skills/GUIDANCE_PACKS.md

@@ -24,7 +24,7 @@ Workflow 通过路由 `Read` 路径加载 guidance；禁止写成「invoke `/mys
 | 主题 | `architecture` → §3；`database` → §4.4；`api` → §4.5；`frontend` → §4.6（有 UI；含 IDE skills/rules 落地扫描） |
 | 上限 | 每主题约定文件最多 **3**（helper）；前端专题合计约定+IDE skills/rules ≤ **5**（见 `frontend-guidance.md` §3） |
 
-另：前端详设结构由 `prompts/approval/frontend-guidance.md` 驱动（`uiInScope`、栈五元组、G5/G6、Visual Loop）；与 DB 的 `database-guidance.md` 对称，**暂无**独立 `skills/frontend` guidance pack。
+另：前端详设结构由 `prompts/approval/frontend-guidance.md` 驱动；接口/RPC 可生成契约由 **`prompts/approval/api-guidance.md`** 驱动（分层 L2/L3/L4、RPC 锁名、proto/OpenAPI 包）。与 DB 的 `database-guidance.md` 对称。
 
 **分片生成（非 trivial §4）**：`prompts/approval/segmented-generation.md` + `templates/approval-index.yaml`；Map 写 `approval/parts/`，Reduce 用 `specflow approval assemble`（禁止 LLM 拼接）。
 

package/skills/specflow-approval/SKILL.md

@@ -103,6 +103,37 @@ uiInScope=<yes|no>, stackCoverage=<complete|partial|missing>)."
 
 ---
 
+## Stage 1b: Multi-Repo Intake (多仓)
+
+**Trigger**: user **自然语言** specifies multiple repos (talos + talos-web + worker), workset
+with multiple planning roots, or cross-repo design/tasks.
+
+Read **`prompts/approval/multi-repo-guidance.md`**.
+
+1. Resolve `multi_repo.repos[]` — `id`, `label`, `role`, **per-repo `change`**, optional `root_hint`.
+2. **Read four refined artifacts from each repo** before Pass 1.
+3. **User gate (hard)** — ask before writing any approval file:
+
+```text
+跨 N 个仓库,审批技术文档如何产出?
+A) 一份合订 (unified) — 单份 approval.md
+B) 多份分仓 (per_repo) — 每仓各自 approval.md
+```
+
+4. If **A** — ask **主仓** (stores `approval.md` + `approval/` workspace):
+
+```text
+合订文档存放在哪个主仓? (talos / talos-web / talos-worker / …)
+```
+
+5. Write `approval/index.yaml` → `multi_repo` with user choices + `outputs`.
+6. **Unified**: Stage 12 workspace + `specflow approval assemble` run in **primary** planning root only.
+7. **Per_repo**: repeat Stage 12 + assemble **per repo** (scope = that repo only).
+
+Single-repo → skip (`multi_repo.enabled=false`).
+
+---
+
 ## Gate: Tech Stack Intake (0→1 / 四件套缺选型)
 
 **Trigger** (any):
@@ -344,8 +375,11 @@ Order and hard requirements (from `generate.md` §4.1–4.9):
    (2) `database-guidance.md` + SpecFlow guidance pack / `dbStack`; (3) live DDL/anchors.
    Priority: **project + live DDL > SpecFlow pack > LLM**. §4.4.1 must list 项目约定 + DB 技能.
    **Outline**: only `4.4.1–4.4.4` + `##### table`; DDL/字段说明/JSON = `**bold**`.
-5. **接口设计** — Before §4.5: `project-conventions-guidance.md` `topic=api`.
-   Then inventory + fields + examples + errors…
+5. **接口设计** — Before §4.5: (1) `project-conventions-guidance.md` `topic=api`;
+   (2) **`api-guidance.md`** — 契约面分层(L2/L3/L4 各独立 `In`)、RPC 锁名、proto/OpenAPI 可生成包;
+   (3) live proto/OpenAPI/anchors.
+   Then inventory + **each surface** fields + examples + errors + **Proto 草案**(新增 RPC).
+   **禁止** L2 HTTP 详写 + L4「内部调用」stub; **禁止**「暂定/如/实现时」RPC 名。
    **Outline**: only `4.5.1–4.5.3` + `##### In`; 请求体字段/示例/错误 = `**bold**`.
 6. **前端 / UI** — When `uiInScope=yes`: before §4.6:
    (1) `project-conventions-guidance.md` `topic=frontend`;
@@ -459,7 +493,10 @@ Respect `index.batching.*_per_call`. After each part: update `approval/manifest.
 Minimums (no shortcuts — see Part E hard rules 9–10, 18–20):
 
 - §4.4 batch: DDL + 字段说明 + 本迭代用法 per table; G3/G4 when applicable
-- §4.5 batch: meta + fields + success examples + **failure example (G2)** + error table per interface (**含不变**;完整格式,禁止精简)
+- §4.5 batch: **Read `api-guidance.md`**; one `In` per contract surface (L2 Worker HTTP / L3 RPC / L4 client RPC — no collapsing)
+- meta + fields + success examples + **failure example (G2)** + error table per interface (**含不变**)
+- **新增 RPC**: frozen `Service.Method` + proto field numbers + `google.api.http` + Gateway registration + Worker OpenAPI pointer
+- **禁止** 暂定/如/实现时 RPC; **禁止** L4 stub when L2 is fully written
 - §4.6 batch (when `uiInScope`): IDE skills/rules scan first; page/route + states + G6; §4.5 `In` refs
 
 ### 12c Optional chapters
@@ -522,7 +559,9 @@ Present a summary to the user (**chat only** — these are not document chapters
 - Design quality verdict (PASS / WARNING / FAIL)
 - Implementability overall verdict (READY / NEEDS REFINEMENT / BLOCKED)
 - **AI pre-approval recommendation** (建议批准 / 有条件批准 / 退回 refine / 拒绝) + 理由
-- The path where `approval.md` will be written
+- The path where `approval.md` will be written (**all paths** if `multi_repo.document_mode=per_repo`)
+
+If `multi_repo.enabled`, confirm document mode + primary repo (unified) are already in `index.yaml`.
 
 Ask explicitly about **optional chapters** (record in `approval/index.yaml` → `optional.s5/s7/s8`):
 

package/templates/approval-index.yaml

@@ -50,3 +50,23 @@ meta:
   language: zh-CN
   tech_stack: unknown
   project_mode: brownfield
+
+# 多仓时启用 (见 prompts/approval/multi-repo-guidance.md)
+# multi_repo:
+#   enabled: true
+#   document_mode: unified   # unified | per_repo — 用户确认后填写
+#   primary_repo: talos      # unified 时必填
+#   repos:
+#     - id: talos
+#       label: 平台
+#       role: platform
+#       change: <change-name>
+#     - id: talos-web
+#       label: 控制台
+#       role: web
+#       change: <web-change-name>
+#   outputs:
+#     unified:
+#       repo: talos
+#       change: <change-name>
+#       path: specflow/changes/<change-name>/approval.md