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

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

@@ -0,0 +1,120 @@
+export type ApprovalGenerationMode = 'segmented' | 'monolithic';
+export type ApprovalPartStatus = 'draft' | 'ok' | 'retry';
+export interface ApprovalOptionalChapters {
+    readonly s5: boolean;
+    readonly s7: boolean;
+    readonly s8: boolean;
+}
+export interface ApprovalBatching {
+    readonly tables_per_call: number;
+    readonly interfaces_per_call: number;
+    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;
+    readonly part: string;
+}
+export interface ApprovalConventionsResolved {
+    readonly architecture?: readonly string[];
+    readonly database?: readonly string[];
+    readonly api?: readonly string[];
+    readonly frontend?: readonly string[];
+}
+export interface ApprovalIndex {
+    readonly schema: 'specflow.approval.index/v1';
+    readonly change: string;
+    readonly generated_at: string;
+    readonly mode: ApprovalGenerationMode;
+    readonly ui_in_scope: boolean;
+    readonly db_in_scope: boolean;
+    readonly api_in_scope: boolean;
+    readonly optional: ApprovalOptionalChapters;
+    readonly parts_order: readonly string[];
+    readonly design_points: readonly string[];
+    readonly decisions: readonly string[];
+    readonly tables: readonly ApprovalTableRef[];
+    readonly interfaces: readonly ApprovalInterfaceRef[];
+    readonly pages: readonly ApprovalPageRef[];
+    readonly capabilities: readonly ApprovalCapabilityRef[];
+    readonly batching: ApprovalBatching;
+    readonly conventions: ApprovalConventionsResolved;
+    readonly multi_repo?: ApprovalMultiRepo;
+    readonly meta?: {
+        readonly language?: string;
+        readonly tech_stack?: string;
+        readonly project_mode?: string;
+    };
+}
+export interface ApprovalManifestPart {
+    readonly id: string;
+    readonly path: string;
+    readonly status: ApprovalPartStatus;
+    readonly sha256?: string;
+    readonly updated_at?: string;
+}
+export interface ApprovalManifest {
+    readonly schema: 'specflow.approval.manifest/v1';
+    readonly change: string;
+    readonly parts: readonly ApprovalManifestPart[];
+    readonly assembled_at?: string;
+    readonly approval_sha256?: string;
+}
+export type ApprovalDiagnosticSeverity = 'error' | 'warning';
+export interface ApprovalDiagnostic {
+    readonly code: string;
+    readonly severity: ApprovalDiagnosticSeverity;
+    readonly message: string;
+    readonly part?: string;
+}
+export interface ApprovalAssembleResult {
+    readonly markdown?: string;
+    readonly outputPath?: string;
+    readonly diagnostics: readonly ApprovalDiagnostic[];
+    readonly ok: boolean;
+}

package/dist/core/approval/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.4.4-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` 解决「项目禁令与风格」;本文件解决「可生成契约与分层」。