spec-manager 0.1.0

package/dist/schemas/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/schemas/spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,eAAe,qCAAmC,CAAC;AAChE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAEzD,eAAO,MAAM,gBAAgB,wEAAsE,CAAC;AACpG,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE3D,eAAO,MAAM,gBAAgB,qEAAmE,CAAC;AACjG,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC3D,eAAO,MAAM,cAAc,mDAAiD,CAAC;AAC7E,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEvD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYhC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBhC,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;EAIzB,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGzB,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;EAK9B,CAAC"}

package/dist/schemas/spec.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { PLAN_STEPS_MAX, SPEC_CODE_RE } from '../core/constants.js';
+export const SpecLevelSchema = z.enum(['L0', 'L1', 'L2', 'L3']);
+export const SpecStatusSchema = z.enum(['draft', 'confirmed', 'frozen', 'implemented', 'archived']);
+export const StepStatusSchema = z.enum(['pending', 'running', 'succeeded', 'failed', 'skipped']);
+export const StepTypeSchema = z.enum(['llm_call', 'mcp_tool', 'human_gate']);
+export const StepFrontmatterSchema = z.object({
+    stepNo: z.union([z.number(), z.string()]),
+    stepType: StepTypeSchema,
+    name: z.string().min(1),
+    status: StepStatusSchema.default('pending'),
+    toolName: z.string().optional(),
+    inputJson: z.string().optional(),
+    outputJson: z.string().optional(),
+    errorCode: z.string().optional(),
+    errorMessage: z.string().optional(),
+    latencyMs: z.number().optional(),
+    reportedAt: z.string().optional(),
+});
+export const SpecFrontmatterSchema = z.object({
+    id: z.string().optional(),
+    code: z.string().regex(SPEC_CODE_RE, 'code 必须是 <topic>-L<level>[.<n>...][-desc] 格式'),
+    level: SpecLevelSchema,
+    title: z.string().min(1),
+    topic: z.string().min(1),
+    parentCode: z.string().nullable(),
+    status: SpecStatusSchema,
+    project: z.number().int().positive().default(1),
+    milestone: z.string().regex(/^v\d+(\.\d+)*(-[a-z0-9]+)?$/i, 'milestone 格式: v1.0 / v1.0.1 / v2.0-beta').optional(),
+    aiSummary: z.string().max(300, 'aiSummary 必须 ≤300 字符').default(''),
+    coveredTasks: z.array(z.string()).default([]),
+    steps: z.array(StepFrontmatterSchema).optional(),
+    relations: z.array(z.object({
+        type: z.enum(['based_on', 'supersedes', 'implements', 'references']),
+        target: z.string(),
+    })).default([]),
+    created: z.string().optional(),
+    updated: z.string().optional(),
+    changeSummary: z.string().optional(),
+});
+export const PlanStepSchema = z.object({
+    stepNo: z.union([z.number().int().positive(), z.string()]),
+    stepType: StepTypeSchema,
+    name: z.string().min(1),
+});
+export const PlanJsonSchema = z.object({
+    coveredSpecs: z.array(z.string()).optional(),
+    steps: z.array(PlanStepSchema).min(1).max(PLAN_STEPS_MAX, `R11: 步骤数 ≤${PLAN_STEPS_MAX}`),
+});
+export const DecisionInputSchema = z.object({
+    topic: z.string().min(1),
+    what: z.string().min(1).max(500),
+    why: z.string().max(500).optional(),
+    affectedCriteria: z.array(z.string()).optional(),
+});
+//# sourceMappingURL=spec.js.map

package/dist/schemas/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/schemas/spec.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "spec-manager",
+  "version": "0.1.0",
+  "description": "spec-manager: local-first spec-driven development platform. Pure markdown storage, no network, no MCP. Portable CLI + multi-agent instructions.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "spec-manager": "dist/cli/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skill",
+    "templates",
+    "rules",
+    "AGENTS.md",
+    "CODEBUDDY.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "tsc --watch",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "spec-driven",
+    "spec",
+    "methodology",
+    "claude-code",
+    "codex",
+    "opencode",
+    "codebuddy",
+    "agents-md",
+    "skill",
+    "ai-coding",
+    "agent",
+    "delta-spec"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.4.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/loki-ai-ch/spec-manager.git"
+  },
+  "bugs": {
+    "url": "https://github.com/loki-ai-ch/spec-manager/issues"
+  },
+  "author": "loki",
+  "homepage": "https://github.com/loki-ai-ch/spec-manager"
+}

package/rules/_TEMPLATE.md

@@ -0,0 +1,20 @@
+# 规则 frontmatter 模板
+
+> 复制本文件改 ID 即可。所有规则统一格式,便于 applies_to 过滤。
+
+```markdown
+---
+id: R<N>
+title: 一句话标题
+added: 0.1.0
+applies_to: [action_1, action_2, ...]
+---
+
+## 正文
+
+详细规则 + 判定标准 + 违反示例 + 豁免 + 关联。
+```
+
+字段说明:
+- `applies_to` — 该规则被检查的 action 名。CLI 和 skill 都通过 `applies_to` 过滤当前操作要加载哪些规则（人工筛选）。
+- 其它字段（`trigger_count` / `last_triggered` / `health` / `reason_inc` / `audit_type`）已废弃：触发次数看 `spec-manager audit show`，incident 关联看 incident 文件 frontmatter。

package/rules/code-discipline.md

@@ -0,0 +1,47 @@
+# 代码纪律规则
+
+> 本文件管辖:R8 R9 R12
+> 主题:改代码前自检、批准必须走 spec-manager 入口、禁凭记忆
+
+## R8 — 改代码前必须调研
+
+---
+id: R8
+title: 改代码前必须调研
+added: 0.1.0
+applies_to: [pre_code_change, L3_write]
+---
+
+改代码前必须先：
+1. `spec-manager spec show <相关 spec code>` 确认 spec 已 frozen
+2. Read 相关源文件确认路径存在(R12)
+3. grep/Read 了解调用链
+4. 识别测试文件
+
+**禁止**：凭记忆写文件路径 / 函数名。
+
+## R9 — 批准必须走 spec-manager 入口，不能凭上下文
+
+---
+id: R9
+title: 批准必须走 spec-manager 入口，不能凭上下文
+added: 0.1.0
+applies_to: [user_approve]
+---
+
+当用户在迭代上下文中说出"批准"/"已确认"/"通过"等信号时，AI agent **必须**重新进入 spec-manager workflow（skill、`AGENTS.md` 指令入口或同等项目指令），由该入口触发后续状态推进。
+
+**禁止**：凭上下文理解直接调用 `spec-manager spec confirm` / `freeze` / `implement`。
+
+## R12 — 禁止凭记忆写 planJson，必须从模板读
+
+---
+id: R12
+title: 禁止凭记忆写 planJson，必须从模板读
+added: 0.1.0
+applies_to: [doc_write, task_write, L3_write]
+---
+
+写 L3 spec 的 planJson 前，**必须**先 Read 本仓库 `templates/agent-plan.json` 确认字段名（`stepNo` / `stepType` / `name`）。
+
+**禁止字段名**：`no` / `type` / `desc` / `description`（INC-005 教训）。

package/rules/codebase-survey.md

@@ -0,0 +1,37 @@
+# 代码调查规则
+
+> 本文件管辖:R23
+> 主题:Spec 写作前必须基于实际代码（不靠想象）
+
+## R23 — Spec 写作前必须执行三级代码调查
+
+---
+id: R23
+title: Spec 写作前必须执行三级代码调查
+added: 0.1.0
+applies_to: [L1_create, L2_create, L3_create]
+---
+
+| Level | 触发时机 | 内容 | 最低要求 |
+|---|---|---|---|
+| Level 1 架构概览 | 写 L1 前 | 项目结构、技术栈、模块、API 端点、数据模型 | 读 README / 找 architecture-baseline；或 find + grep 补扫 |
+| Level 2 模块深潜 | 写 L2 前 | 受影响模块的 controller / service / entity + 复用工具类 | 至少 Read 3 个源文件 |
+| Level 3 文件级分析 | 写 L3 前 | 精确函数签名 / 插入行号 / 调用链 / 测试文件 | Read 验证每个文件路径存在 |
+
+### 策略
+
+- **基线优先**：先查 `spec list --q architecture-baseline` 看是否有基线 spec
+- **基线不足时**：用 `find` / `grep` 实时补扫
+- **Read 一致性**：写完 L1/L2/L3 后再 Read 一次确认字段名/路径未变化
+
+### 违反判定
+
+- L2 复用清单无具体路径（只有"用现有的 X"）
+- L3 受影响模块未经 Read 验证
+- 有基线 spec 但没读
+- 新项目无基线就开始写 L1
+
+### 关联
+
+- R8 改代码前自检
+- R12 planJson 字段名从模板读

package/rules/delta.md

@@ -0,0 +1,42 @@
+# Delta Spec 规则
+
+> 本文件管辖:R24
+> 主题:OpenSpec 风格的增量 spec 提案（change folder）的完整性
+
+## R24 — delta change 必须含 proposal + delta spec
+
+---
+id: R24
+title: delta change 必须含 proposal + delta spec
+added: 0.1.0
+applies_to: [change_new, change_archive]
+---
+
+**核心规则**：`spec-manager change new <name>` 创建的 change 文件夹（`changes/YYYY-MM-DD-<name>/`）必须满足：
+
+1. **proposal.md** 非空 — 至少含 ## 为什么（Why）/ ## 影响范围（Scope）/ ## 验收标准（AC）
+2. **至少一个 delta spec** — 在 `changes/.../specs/<topic>/<code>/` 下的 `*.md`，使用 ## ADDED Requirements / ## MODIFIED Requirements / ## REMOVED Requirements / ## RENAMED Requirements 四个段之一
+
+`spec-manager change archive <name>` 会校验：
+- proposal.md 存在且非空
+- delta spec 文件存在且包含合法 delta 段落
+- ADDED 操作的占位文件位于 `changes/<name>/specs/<topic>/<code>/<code>.md`，archive 时按占位 frontmatter 的 `parentCode` 字段把新 spec 放到主 specs 树的正确嵌套位置
+
+违反任一条件 `change archive` 拒绝执行（exit 2），并打印具体缺什么。
+
+### 为什么
+
+- **避免 "delta 半截"**：没 proposal 的 change 是无目的的修改，没 delta spec 的 change 是凭空合并
+- **可审计性**：archive 时机 = 知识合并点，必须有完整变更描述
+- **可回滚**：proposal + delta 是 archive 的"原账本"，未来回滚或查询靠它们
+
+### 与 R13/R14 的关系
+
+- R13：delta spec 也必须写 aiSummary（`spec-manager spec update --ai-summary`）
+- R14：delta spec 引用主 spec 时用 specCode，不复述原文
+
+### 关联
+
+- `templates/proposal.md` — change proposal 模板
+- `templates/delta-spec.md` — delta spec 模板
+- Phase 3 实施：`change new/archive/list` 三个 CLI 命令

package/rules/doc-governance.md

@@ -0,0 +1,195 @@
+# 文档治理规则
+
+> 本文件管辖:R7 R11 R13 R14 R16 R17 R19 R20 R21 R22
+> 主题:层级绑定、粒度控制、摘要与变更说明、跨层引用、批量建齐、正文非空门禁
+
+## Contents
+
+- **R7 层级绑定** — L2/L3 必须有 `parentCode`
+- **R11 粒度控制** — Agent Task ≤20 步
+- **R13 aiSummary 上传** — 写完 contentTemplate 必须给 aiSummary
+- **R14 跨层引用** — 用 specCode 而不是复述上层内容
+- **R16 L1 去重** — 创建前必须搜同 topic
+- **R17 L2 架构拆解** — L2 是架构不是 todolist
+- **R19 研究先看摘要** — 研究期 `spec show` 默认收窄,需 aiSummary；跨层设计必须读父全文
+- **R20 批量建 L3** — scope-split L2 必须 1 次建齐所有子 L3
+- **R21 aiSummary ≤300 字符** — 硬限制
+- **R22 创建即写正文** — 防 contentTemplate 空白进审核
+
+---
+
+## R7 — 层级建模已启用,L2/L3 必须绑定父 Spec
+
+---
+id: R7
+title: 层级建模已启用,L2/L3 必须绑定父 Spec
+added: 0.1.0
+applies_to: [L2_create, L3_create]
+---
+
+`spec-manager spec new L2 --parent <L1 code>` 必须指定 `parentCode`。
+`spec-manager spec new L3 --parent <L2 code>` 必须指定 `parentCode`。
+CLI 在 `L2`/`L3` 缺 `--parent` 时直接拒绝（exit 2），不会创建文件。
+
+## R11 — Agent Task 粒度控制
+
+---
+id: R11
+title: Agent Task 粒度控制
+added: 0.1.0
+applies_to: [agent_task_create]
+---
+
+- 单个 Agent Task = 单个 L3 Spec = **≤ 20 个步骤**(用户授权 ≤10)
+- **单步单责**：每个 planJson step 只做一件事（改一个文件 / 调一个工具 / 运行一次验证）
+- 超过 16 步时，必须拆分为多个 L3 Spec
+
+`spec-manager spec validate-plan` 自动检查并 warn。
+
+## R13 — 写完 contentTemplate 后必须上传 aiSummary
+
+---
+id: R13
+title: 写完 contentTemplate 后必须上传 aiSummary
+added: 0.1.0
+applies_to: [doc_update]
+---
+
+每次 `spec-manager spec update <code> --content <file>` 后，必须紧跟 `--ai-summary "..."`（同一调用或下次调用均可）。
+
+**摘要必须遵循** `docs/ai-summary-spec.md` 的写作规范（三秒可读 + 具体到字段/文件/接口路径 + 按层级模板，≤200字）。
+
+**同时要求**：每次 `spec-manager spec update` 必须在同一调用中传入 `--change-summary`，描述本次写入的原因。
+
+## R14 — 跨层引用用 specCode,不复述上层内容
+
+---
+id: R14
+title: 跨层引用用 specCode,不复述上层内容
+added: 0.1.0
+applies_to: [L2_write, L3_write]
+---
+
+**核心规则**:L2 Spec 引用 L1 时只写 `parentCode + 一句话定位`,不复制 L1 的用户故事/验收标准。L3 Spec 引用 L2 时只写一句话,不复制 L2 的架构描述。
+
+### 判定
+
+✅ 正确:
+
+- L2: `本 L2 实现 2026-06-04-a1b2c3 的目标 3(演进闭环)。L1 的用户故事详见其正文。`
+- L3: `本 L3 对应 2026-06-05-b2c3d4 的 L3 裂变计划,落地 5 份模板文件。`
+
+❌ 错误:
+
+- L2 正文大段粘贴 L1 的"用户故事"和"验收标准"章节
+- L3 正文重复 L2 的"方案概述"和"关键技术决策"
+- L3 重新阐述业务背景(应引用 L1 code)
+
+### 为什么
+
+- **单一真相源**:同一信息只写一处,修改时不分裂
+- **反向溯源**:未来审计链路 L3→L2→L1 通过 parentCode 一跳一跳走
+- **分层老化**:L3 短期失效(实施完成即历史),L1 长期沉淀
+
+## R16 — L1 创建前必须搜索去重
+
+---
+id: R16
+title: L1 创建前必须搜索去重
+added: 0.1.0
+applies_to: [L1_create]
+---
+
+创建 L1 Spec 前，必须先执行：
+
+```bash
+spec-manager spec list --level L1 --topic <topic>
+```
+
+若发现同 topic 的 L1 已存在，应复用现有 L1（追加用户故事/验收标准），而非新建。
+
+## R17 — L2 是架构拆解，不是任务清单
+
+---
+id: R17
+title: L2 是架构拆解，不是任务清单
+added: 0.1.0
+applies_to: [L2_create]
+---
+
+**L1:L2 比例必须控制在 1:1 或 1:2。** L2 的拆分维度是**模块边界 / 系统层**，不是功能点清单。
+
+### 自检
+
+创建 L2 前问自己：
+1. 这个 L2 和同层其他 L2 是否改的是**不同模块/系统层**？→ 是则合理
+2. 这些 L2 是否都在改**同一个模块的不同功能点**？→ 是则应合并为一个 L2，功能点下沉到 L3
+
+## R19 — 跨层引用/研究优先读 aiSummary
+
+---
+id: R19
+title: 跨层引用/研究优先读 aiSummary
+added: 0.1.0
+applies_to: [doc_list, spec_show, research, cross_layer_reference, L2_write, L3_write, cross_layer_design]
+---
+
+> 人工审计:本规则靠自律,默认收窄视图,需全文时显式 `--include-content` / `Include-Content`。
+
+**核心规则**：研究、扫目录、跨层引用场景，**优先只读 `aiSummary`**（≤300字），不要 `spec show <code> --include-content` 拉全文。
+
+### 何时必须只读 aiSummary
+
+- `spec list` 返回结果的初筛（扫 code + aiSummary 判断是否相关）
+- L2/L3 启动时读父层（`spec show <parent>` 只为"知道父层长啥样"）
+- 跨 topic 关联时扫 `decision list` 结果
+- L1 去重搜索（R16）的结果比对
+
+### 何时允许读全文
+
+只有以下 3 种场景允许 `--include-content`：
+
+1. **即将写作本层正文** — 需要精确对齐父层的用户故事/接口契约/章节编号
+2. **执行 Agent Task 步骤** — 需要精确字段名/文件行号（R12 要求凭 Spec 不凭记忆）
+3. **aiSummary 明显不够** — 读完 aiSummary 仍无法判断是否重复/是否要引用
+
+### 跨层设计必须读父层全文
+
+**核心规则**：写 L2 正文前必须读 L1 全文，写 L3 正文前必须读 L2 全文。aiSummary 不能替代全文。这是流程问题，不是优化问题。
+
+## R20 — scope-split L2 必须批量建齐所有子 L3
+
+---
+id: R20
+title: scope-split L2 必须批量建齐所有子 L3
+added: 0.1.0
+applies_to: [L2_scope_split, L3_create]
+---
+
+**核心规则**：当一个 L2 决定拆成 N 个 L3 执行（scope-split）时，必须在第一个 L3 推 `frozen` **之前**，把全部 N 个子 L3 spec 都通过 `spec-manager spec new` 建好（可保持 `draft` 状态）。禁止"先建 L3-A 走 frozen → complete，再回头建 L3-B"的顺序。
+
+**重要**："建齐" = 每个子 L3 都同时满足（1）`spec new` 建立 +（2）`spec update --content` 写入非空正文。
+
+## R21 — aiSummary ≤300 字符
+
+---
+id: R21
+title: aiSummary ≤300 字符
+added: 0.1.0
+applies_to: [doc_update]
+---
+
+`spec-manager spec update --ai-summary` 入参 >300 字符时自动截断并 warn。**不 throw**。
+
+**生成摘要时直接控制在 200 字以内即可**（与 R13 写作规范一致）。
+
+## R22 — spec 创建后必须立即写正文，通知用户审核前自检 contentTemplate 非空
+
+---
+id: R22
+title: spec 创建后必须立即写正文,通知用户审核前自检 contentTemplate 非空
+added: 0.1.0
+applies_to: [doc_create_spec, user_review_signal, L1_create, L2_create, L3_create, scope_split_batch_create]
+---
+
+**核心规则**：调用 `spec-manager spec new` 后，**必须紧跟一次** `spec-manager spec update <code> --content <file> --ai-summary "..." --change-summary "..."` 写入非空正文，才能视为该 spec 创建完成。**禁止**只创建空架子（仅 metadata：title/code/level/parentCode/description）就向用户发出"spec 写完了，请审核"信号。

package/rules/flow-control.md

@@ -0,0 +1,65 @@
+# 流程控制规则
+
+> 本文件管辖:R1 R2 R3 R4
+> 主题:何时 STOP、何时推进状态、何时建 Task、审核独立性
+
+## R1 — 写内容后必须停下等审核
+
+---
+id: R1
+title: 写内容后必须停下等审核
+added: 0.1.0
+applies_to: [L1_create, L2_create, L3_create]
+---
+
+每次 `spec-manager spec update <code> --content` 写入后，**必须停下**，告知用户文件路径，等用户明确说"批准"/"已确认"/"继续"/"通过"等。
+
+**严禁一口气做**：`new L1 → update --content → confirm → new L2 → update → confirm → new L3 → freeze → task create → start`。
+
+## R2 — 状态推进是用户行为,不是 AI 行为
+
+---
+id: R2
+title: 状态推进是用户行为,不是 AI 行为
+added: 0.1.0
+applies_to: [L1_confirm, L2_confirm, L3_confirm, L3_freeze, user_approve]
+---
+
+`draft → confirmed` 和 `confirmed → frozen` 都是用户审核意见的体现。AI agent **不能**在未获用户明确批准前主动调用 `spec-manager spec confirm` / `freeze`。
+
+**唯一例外**：`frozen → implemented` 由 `spec-manager task complete` 自动触发，允许 AI agent 执行。
+
+**用户批准信号必须通过 spec-manager 入口响应**：当用户在迭代上下文中说出批准信号（"继续"/"已审批"/"通过"/"批准"/"ok"/"确认"等），AI agent **必须重新进入 spec-manager workflow**（Claude/CodeBuddy skill、Codex/OpenCode 的 `AGENTS.md` 指令入口等），不能凭已有上下文自行推进。
+
+**原因**：AI 拥有上下文≠有权跳过流程。上下文只是信息，流程管控的是质量和可追溯性。
+
+```
+正确：用户说"已审批" → AI 进入 spec-manager workflow → 执行下一步状态推进
+错误：用户说"已审批" → AI 凭上下文直接读文件、建 Task、动代码
+```
+
+## R3 — 创建 Agent Task 前必须 spec 已 frozen
+
+---
+id: R3
+title: 创建 Agent Task 前必须 spec 已 frozen
+added: 0.1.0
+applies_to: [agent_task_create]
+---
+
+只有当用户明确批准并且 L3 spec 状态为 `frozen` 时，才能调用 `spec-manager task create`。
+
+## R4 — 每层 Spec 都是独立审核点
+
+---
+id: R4
+title: 每层 Spec 都是独立审核点
+added: 0.1.0
+applies_to: [L1_confirm, L2_confirm, L3_confirm]
+---
+
+> 人工审计:本规则依赖人工判断,无法通过系统强制执行,实际执行由人工审核保障。
+
+L1 PRD 审核、L2 Design 审核、L3 Impl 审核是**三个独立的停止点**。不能因为 L1 批准了就连带假设 L2 也批准。
+
+**人工审计说明**：本规则依赖人工判断，无法通过系统强制执行。hooks 作为辅助提醒，实际执行由人工审核保障。

package/rules/quality-gate.md

@@ -0,0 +1,73 @@
+# 质量门禁规则
+
+> 本文件管辖:R5 R6 R10 R15 R18
+> 主题:执行可观测、task 后状态校验、step 必含 summary
+
+## R5 — 执行期间不得跳步
+
+---
+id: R5
+title: 执行期间不得跳步
+added: 0.1.0
+applies_to: [agent_step_report]
+---
+
+每个 planJson 的 step **必须**通过 `spec-manager task step` 单独上报，禁止跳号。
+
+**错误**：planJson 有 10 步但只上报 step 1、5、10，然后调用 `task complete`。
+
+## R6 — task_complete 后校验 implemented
+
+---
+id: R6
+title: task_complete 后校验 implemented
+added: 0.1.0
+applies_to: [agent_task_complete]
+---
+
+调用 `spec-manager task complete` 后，**必须立即** `spec-manager spec show <L3 code>` 校验 status 是否已自动 cascade 到 `implemented`。未级联则手动 `spec-manager spec implement <L3 code>`。
+
+**原因**：避免 INC-20260424-001 — L3-A implemented → 级联误判 L2 完成，而 L3-B 还没建。
+
+## R10 — planJson 最后一步必须是验证
+
+---
+id: R10
+title: planJson 最后一步必须是验证
+added: 0.1.0
+applies_to: [agent_task_create]
+---
+
+`spec-manager spec validate-plan` 校验时，末步 name 应含 "验证"/"verify"/"test"/"check"/"curl"/"gradle"/"mvn"/"pytest"/"vitest" 等关键字。`spec validate-plan` 输出 `R10` warning 需用户确认。
+
+**原因**：避免"实施完成但无验证" — 无法证明功能真工作。
+
+## R15 — step_report outputJson 必含 summary
+
+---
+id: R15
+title: step_report outputJson 必含 summary
+added: 0.1.0
+applies_to: [agent_step_report]
+---
+
+每次 `spec-manager task step` 调用，`--output-json` 必须是合法 JSON 且含 `summary` 字段（≤500 字）。files 字段如有也应给出。
+
+**原因**：summary 是步骤可读的"工作内容"，无 summary 等于审计不可用。
+
+## R18 — L1 implemented 后必须建决策卡片
+
+---
+id: R18
+title: L1 implemented 后必须建决策卡片
+added: 0.1.0
+applies_to: [L1_implemented]
+---
+
+L1 spec 状态推进到 `implemented`（通常通过 L3 cascade）后，**必须**至少创建 1 张决策卡片：
+
+```bash
+spec-manager decision create <L1 code> --topic <topic> --what "..." --why "..." --criteria AC-1,AC-2
+```
+
+新 L1 创建前（PRE-WRITE Q4）必须 `spec-manager decision list --topic <topic>` 查询历史决策。