@hongmaple0820/scale-engine 0.47.0 → 0.49.0

package/dist/workflow/gates/TestIntegrityGate.js

@@ -0,0 +1,175 @@
+// SCALE Engine — G23 Test Integrity Gate (P1.2, PR-D1)
+// Detects "fake green" test tampering by analysing the test-file diff:
+// assertion count drops, newly introduced skip/only, weakened assertions, and
+// inflated timeouts. PR-D1 ships advisory (warn-only); enforcement + verify→ship
+// hash consistency + coverage regression land in PR-D2.
+import { execSync } from 'node:child_process';
+function createEvidence(input) {
+    return {
+        id: `EVID-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        ...input,
+    };
+}
+function textEvidence(items) {
+    return items.map(item => `${item.label}: ${item.detail}`).join('\n');
+}
+/** Matches test files by filename suffix or by living under a tests/__tests__ dir. */
+const TEST_FILE_PATTERN = /(?:^|\/)(?:__tests__|tests?|specs?)\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+/** expect(...) / assert(...) / assert.* / .should / should(...) — line-level assertion signal. */
+const ASSERTION_PATTERN = /\bexpect\s*\(|\bassert\s*\(|\bassert\.|\.should\b|\bshould\s*\(/;
+const SKIP_PATTERN = /\b(?:describe|context|suite|it|test|bench)\.skip\b|\.skip\s*\(|\bx(?:it|describe|test|context)\s*\(/;
+const ONLY_PATTERN = /\b(?:describe|context|suite|it|test|bench)\.only\b|\.only\s*\(|\bf(?:it|describe|test)\s*\(/;
+const WEAKENED_PATTERN = /expect\.any\s*\(|expect\.anything\s*\(|\.toBeTruthy\s*\(|\.toBeFalsy\s*\(|\.toBeDefined\s*\(|\.toBeUndefined\s*\(|\.toBeNull\s*\(/;
+const TIMEOUT_PATTERN = /\b(?:jest|vi)\.setTimeout\s*\(|testTimeout\s*[:=]|\bsetTimeout\s*\(|\btimeout\s*[:=]\s*\d{4,}/;
+function isTestFile(path) {
+    return TEST_FILE_PATTERN.test(path);
+}
+/** Parse a unified `git diff` into per-line records limited to test files. */
+export function parseTestDiff(diff) {
+    const lines = [];
+    let currentFile = '';
+    let inTestFile = false;
+    for (const raw of diff.split('\n')) {
+        if (raw.startsWith('diff --git')) {
+            currentFile = '';
+            inTestFile = false;
+            continue;
+        }
+        if (raw.startsWith('+++ ')) {
+            const path = raw.slice(4).replace(/^b\//, '').trim();
+            currentFile = path === '/dev/null' ? currentFile : path;
+            inTestFile = isTestFile(currentFile);
+            continue;
+        }
+        if (raw.startsWith('--- ') || raw.startsWith('@@') || raw.startsWith('index '))
+            continue;
+        if (!inTestFile || !currentFile)
+            continue;
+        if (raw.startsWith('+'))
+            lines.push({ file: currentFile, origin: '+', text: raw.slice(1) });
+        else if (raw.startsWith('-'))
+            lines.push({ file: currentFile, origin: '-', text: raw.slice(1) });
+        else if (raw.startsWith(' '))
+            lines.push({ file: currentFile, origin: ' ', text: raw.slice(1) });
+    }
+    return lines;
+}
+/** Pure heuristic analysis of a unified test diff. Exported for unit testing. */
+export function analyzeTestDiff(diff) {
+    const parsed = parseTestDiff(diff);
+    const analyzedFiles = [...new Set(parsed.map(line => line.file))].sort();
+    // Pre side = context + removed; post side = context + added. Approximates the
+    // assertion balance within the changed hunks (whole-file counts arrive with AST in P1.1).
+    let preChangeAssertionCount = 0;
+    let postChangeAssertionCount = 0;
+    for (const line of parsed) {
+        const hasAssertion = ASSERTION_PATTERN.test(line.text);
+        if (!hasAssertion)
+            continue;
+        if (line.origin === '-' || line.origin === ' ')
+            preChangeAssertionCount++;
+        if (line.origin === '+' || line.origin === ' ')
+            postChangeAssertionCount++;
+    }
+    const assertionCountDelta = postChangeAssertionCount - preChangeAssertionCount;
+    const findings = [];
+    if (assertionCountDelta < 0) {
+        findings.push({
+            file: analyzedFiles.join(', ') || '(test files)',
+            kind: 'assertion-removed',
+            severity: 'block',
+            detail: `Net assertion count dropped by ${Math.abs(assertionCountDelta)} (pre=${preChangeAssertionCount}, post=${postChangeAssertionCount})`,
+        });
+    }
+    for (const line of parsed) {
+        if (line.origin !== '+')
+            continue;
+        const text = line.text;
+        if (SKIP_PATTERN.test(text)) {
+            findings.push({ file: line.file, kind: 'skip-added', severity: 'block', detail: `Introduced skipped test: ${text.trim().slice(0, 120)}` });
+        }
+        if (ONLY_PATTERN.test(text)) {
+            findings.push({ file: line.file, kind: 'only-added', severity: 'block', detail: `Introduced focused (.only) test: ${text.trim().slice(0, 120)}` });
+        }
+        if (WEAKENED_PATTERN.test(text)) {
+            findings.push({ file: line.file, kind: 'weakened-assertion', severity: 'warn', detail: `Weakened assertion: ${text.trim().slice(0, 120)}` });
+        }
+        if (TIMEOUT_PATTERN.test(text)) {
+            findings.push({ file: line.file, kind: 'timeout-inflated', severity: 'warn', detail: `Test timeout changed: ${text.trim().slice(0, 120)}` });
+        }
+    }
+    const flaggedPatterns = findings.map(f => `[${f.severity}] ${f.kind}: ${f.detail}`);
+    return { analyzedFiles, preChangeAssertionCount, postChangeAssertionCount, assertionCountDelta, findings, flaggedPatterns };
+}
+/**
+ * G23 — Test Integrity. Advisory in PR-D1: always PASSED, surfaces heuristic
+ * findings as evidence. PR-D2 wires it into verify/ship and flips `block`
+ * severity findings into real blockers under the `full`/`ci` profiles (E1).
+ */
+export class TestIntegrityGate {
+    constructor(options = {}) {
+        this.stage = 'G23';
+        this.name = 'Test Integrity';
+        this.description = 'Detect test weakening (assertion drops, skip/only, weakened matchers, inflated timeouts)';
+        this.requiredLevel = 'M';
+        this.cwd = options.cwd ?? process.cwd();
+        this.baseRef = options.baseRef ?? 'HEAD';
+        this.injectedDiff = options.diff;
+        this.advisory = options.advisory ?? true;
+    }
+    collectDiff() {
+        if (this.injectedDiff !== undefined)
+            return this.injectedDiff;
+        try {
+            return execSync(`git diff ${this.baseRef}`, { encoding: 'utf-8', stdio: 'pipe', cwd: this.cwd, maxBuffer: 32 * 1024 * 1024 });
+        }
+        catch {
+            return '';
+        }
+    }
+    async execute() {
+        const startedAt = Date.now();
+        const analysis = analyzeTestDiff(this.collectDiff());
+        const evidence = {
+            analyzedFiles: analysis.analyzedFiles,
+            preChangeAssertionCount: analysis.preChangeAssertionCount,
+            postChangeAssertionCount: analysis.postChangeAssertionCount,
+            assertionCountDelta: analysis.assertionCountDelta,
+            flaggedPatterns: analysis.flaggedPatterns,
+            findings: analysis.findings,
+            advisory: this.advisory,
+        };
+        const blockingFindings = analysis.findings.filter(f => f.severity === 'block');
+        // PR-D1: advisory — never block. PR-D2 will drive blocking via profile policy.
+        const blockers = this.advisory ? [] : blockingFindings.map(f => `${f.kind}: ${f.detail}`);
+        const passed = blockers.length === 0;
+        const summaryDetail = analysis.analyzedFiles.length === 0
+            ? 'No test files changed; nothing to analyse.'
+            : `Analyzed ${analysis.analyzedFiles.length} test file(s); assertion delta ${analysis.assertionCountDelta >= 0 ? '+' : ''}${analysis.assertionCountDelta}; ${analysis.findings.length} finding(s)${this.advisory ? ' (advisory)' : ''}.`;
+        const evidenceItems = [
+            createEvidence({
+                kind: 'scan',
+                label: 'Test integrity summary',
+                passed: passed && blockingFindings.length === 0,
+                detail: summaryDetail,
+                source: JSON.stringify(evidence),
+            }),
+            ...analysis.findings.map(finding => createEvidence({
+                kind: 'scan',
+                label: `Test integrity finding (${finding.kind})`,
+                passed: this.advisory ? true : finding.severity !== 'block',
+                detail: `[${finding.severity}] ${finding.file}: ${finding.detail}`,
+            })),
+        ];
+        return {
+            gate: this.stage,
+            status: passed ? 'PASSED' : 'FAILED',
+            passed,
+            evidence: textEvidence(evidenceItems),
+            evidenceItems,
+            blockers,
+            durationMs: Date.now() - startedAt,
+        };
+    }
+}
+//# sourceMappingURL=TestIntegrityGate.js.map

package/dist/workflow/gates/TestIntegrityGate.js.map

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

package/dist/workflow/types.d.ts

@@ -1,4 +1,4 @@
-export type GateStage = 'G0' | 'G1' | 'G2' | 'G3' | 'G4' | 'G5' | 'G6' | 'G7' | 'G8' | 'G9' | 'G10' | 'G11' | 'G12' | 'G13' | 'G14' | 'G15' | 'G16' | 'G17' | 'G18' | 'G19' | 'G20' | 'G21' | 'G22';
+export type GateStage = 'G0' | 'G1' | 'G2' | 'G3' | 'G4' | 'G5' | 'G6' | 'G7' | 'G8' | 'G9' | 'G10' | 'G11' | 'G12' | 'G13' | 'G14' | 'G15' | 'G16' | 'G17' | 'G18' | 'G19' | 'G20' | 'G21' | 'G22' | 'G23';
 export type GateStatus = 'PENDING' | 'PASSED' | 'FAILED' | 'BLOCKED';
 export type ModelTier = 'LOW' | 'MEDIUM' | 'HIGH';
 export type Verdict = 'APPROVE' | 'ITERATE' | 'REJECT';

package/docs/guides/DEVELOPMENT_WORKFLOW.md

@@ -97,3 +97,31 @@ git diff --check
 - worktree 状态
 - 截图、trace、缓存
 - 只对一次任务有意义的中间文件
+
+## Agent 边界约束
+
+这是把 [AGENTS.md](../../AGENTS.md) / [CLAUDE.md](../../CLAUDE.md) 的「工作原则」落到日常执行的硬约束，违反基本都会被对应门禁拦下：
+
+- **未验证不得声称**：没有实际运行结果，不说「已通过」；`dry-run` 只代表入口可调度，不代表质量通过。证据写进 `verification.md`（G8）。
+- **不确定显式标记**：拿不准的事实标 `[UNCERTAIN]`，不要用猜测填 `reality-check.md` 的 `## Confirmed`（G2 校验该文件分区）。
+- **最小必要修改**：只改与任务直接相关的文件，不顺手重构、不扩大 diff。未提交文件过多或有大文件会被 G16 拦下。
+- **不覆盖用户改动**：动手前先看 `git status`；不把本地 worktree、缓存、日志、截图混进提交。
+- **行为改动配测试**：改 `src/` 行为原则上同步改 `tests/`，否则 G3 阻断。
+- **规则优先落到物理层**：重要约定要落到脚本、门禁、配置、模板，不只停留在口头或文档；改模板前先读 [模板选择指南](../workflow/TEMPLATE_GUIDE.md) 的双源说明，避免改错一套。
+
+## 长任务检查点模式
+
+跨多次会话、或步骤很多的任务，用检查点把进度落到状态文件，避免上下文丢失后从头再来：
+
+```bash
+make checkpoint PHASE=execute   # 记录当前阶段到 .agent/state
+make resume                     # 恢复：打印当前任务、阶段、下一步
+make status                     # 等价于 make resume
+```
+
+实践要点：
+
+- **一个阶段一个检查点**：探索→规划→执行→验证→沉淀，每跨一个阶段 `make checkpoint`。
+- **分阶段提交**：长任务拆成多个小提交，别攒成一个巨型提交（同样利于 G16）。
+- **状态与计划同步**：`plan.md` 的 `## Steps with Gates` 勾到哪一步，状态就 checkpoint 到哪一步，恢复时一眼对上。
+- **恢复先 `make resume`**：新会话开始先读当前状态，再继续，不要凭记忆重做。

package/docs/workflow/E2E_EXAMPLE.md

@@ -0,0 +1,133 @@
+# 端到端示例：从 `make new-task` 到提交
+
+本文走一遍**完整一次任务**：建任务 → 探索 → 规划 → 过工作流门 → 提交。
+用 **L 级**任务，因为它能覆盖 G2 对「human confirmation」的要求。
+
+> 范围说明：本文聚焦 `make new-task → 提交全程`。
+> 关于 FSM Guard（物理阻止「未验证就 COMPLETE」）的**状态机**示例，
+> 见 [../TASK_GUARD_WORKFLOW_DEMO.md](../TASK_GUARD_WORKFLOW_DEMO.md)，本文不重复。
+>
+> 模板怎么选见 [TEMPLATE_GUIDE.md](TEMPLATE_GUIDE.md)，门禁目录见 [GATES_AND_SCORE.md](GATES_AND_SCORE.md)。
+
+下面每条命令和输出均在本仓库实跑（日期取运行当天，你本地会不同）。
+
+---
+
+## 1. 建任务
+
+```bash
+make new-task NAME=add-dark-mode LEVEL=L
+```
+
+```text
+bash scripts/workflow/new-task.sh "add-dark-mode" "L"
+[NEW-TASK] created: /.../.planning/tasks/2026-06-11-add-dark-mode
+[NEW-TASK] state: /.../.agent/state/current.json
+[NEW-TASK] next: fill explore.md, runtime.md, and reality-check.md before execution
+```
+
+`new-task` 在 `.planning/tasks/<date>-add-dark-mode/` 一次性生成 9 个核心制品：
+`explore.md`、`mini-prd.md`、`plan.md`、`runtime.md`、`reality-check.md`、
+`resource-cleanup.md`、`verification.md`、`review.md`、`summary.md`。
+
+> 需要 `spec.md` / `tasks.md`（深规划）时改用 `make plan NAME=add-dark-mode LEVEL=L`。
+
+---
+
+## 2. 探索（G1）
+
+读至少 3 个相关文件并写清主矛盾：
+
+```bash
+make explore FILES='AGENTS.md docs/workflow/templates/plan.md src/api/cli.ts' \
+  MSG='template selection has no guidance'
+```
+
+```text
+[EXPLORE] recorded 3 files
+[EXPLORE] main contradiction: template selection has no guidance
+```
+
+---
+
+## 3. 规划（G2）
+
+编辑 `.planning/tasks/<date>-add-dark-mode/plan.md`，把各段的 `TBD` 填成真内容。
+模板已内置 G2 需要的全部段落（见 [TEMPLATE_GUIDE §4](TEMPLATE_GUIDE.md#4-模板--门禁映射)）：
+范围、异常（≥3 次）、回滚、验收，以及 **L/CRITICAL 的 `## Human Confirmation` 段**。
+你要做的是**填内容**，而不是补标题。
+
+跑计划门，开箱即过：
+
+```bash
+bash scripts/gates/G2-verify.sh
+```
+
+```text
+========================================
+[G2] Plan gate
+========================================
+[G2] checking: /.../.planning/tasks/2026-06-11-verify-plan-template/plan.md
+[G2] passed
+[G2] exception/error mentions: 6
+```
+
+> `exception/error mentions: 6` 说明异常覆盖 ≥ 3，满足 G2。
+> 若把 `## Human Confirmation` 段删掉，L/CRITICAL 会被 G2 拦下
+> （`[G2] L/CRITICAL plan should record human confirmation requirement`）——
+> 这正是模板默认保留该段的原因。
+
+---
+
+## 4. 执行 + 工作流门（G1/G2/G3/G16）
+
+写代码时记住：改 `src/` 行为要同步改 `tests/`，否则 G3 拦下。改完跑：
+
+```bash
+make gate-workflow
+```
+
+该聚合命令依次跑 G1、G2、G3、G16。本次因为只动文档/计划、未改 `src/`，
+G3 会跳过（`no source behavior changes detected; skip`）。
+
+---
+
+## 5. 质量门 + 完整验证
+
+```bash
+make gate-quality            # G0,G4,G5,G6,G7,G8,G17,G18,G19,G20
+make verify PROFILE=default  # 完整 profile 验证
+git diff --check
+```
+
+L 级任务别忘了留审查记录（`.agent/state/review-*.json`），否则 G19 阻断。
+
+---
+
+## 6. 提交
+
+按 [CONTRIBUTING.md](../../CONTRIBUTING.md) 的约定从 `master` 切 `docs/*`、
+`feature/*` 或 `fix/*` 分支，提交信息用 `<type>: <desc>`：
+
+```bash
+git checkout -b feature/add-dark-mode
+git add src/ tests/
+git commit -m "feat: add dark mode toggle"
+```
+
+> `.planning/` 与 `.agent/state/` 已在 `.gitignore` 中，任务制品不会被提交，
+> 它们是给门禁和人审用的过程证据，不进生产代码。
+
+---
+
+## 速查
+
+```text
+make new-task NAME=x LEVEL=L     # 建任务 + 生成制品
+make explore FILES='...' MSG='...'  # G1：探索 ≥3 文件 + 主矛盾
+# 编辑 plan.md（含 Human Confirmation）
+make gate-workflow               # G1,G2,G3,G16
+make gate-quality                # G0,G4,G5,G6,G7,G8,G17,G18,G19,G20
+make verify PROFILE=default      # 完整验证
+git diff --check
+```

package/docs/workflow/README.md

@@ -52,6 +52,12 @@ See [GATES_AND_SCORE.md](GATES_AND_SCORE.md) for gate catalog visibility, archit
 
 See [PROMPT_OPTIMIZATION.md](PROMPT_OPTIMIZATION.md) for the deterministic prompt rewrite layer used by `scale prompt optimize` and `scale define`.
 
+## 模板与示例
+
+- 不知道一个任务该用哪些模板、模板和哪个门禁挂钩，先读 [TEMPLATE_GUIDE.md](TEMPLATE_GUIDE.md)（按等级 + 按改动类型的选择矩阵，含模板↔门禁映射）。
+- 想看从 `make new-task` 到提交的完整一遍真实命令，读 [E2E_EXAMPLE.md](E2E_EXAMPLE.md)。
+- FSM Guard（物理阻止「未验证就 COMPLETE」）的状态机示例见 [../TASK_GUARD_WORKFLOW_DEMO.md](../TASK_GUARD_WORKFLOW_DEMO.md)。
+
 ## 门禁说明
 
 SCALE 2.0 共 23 个门禁，分三层：核心门禁（G0-G8）、元治理门禁（G9-G15）、增强门禁（G16-G22）。

package/docs/workflow/TEMPLATE_GUIDE.md

@@ -0,0 +1,162 @@
+# 模板选择指南（Template Guide）
+
+本指南回答两个一直没有文档化的问题：
+
+1. **一个任务到底该用哪些模板？**（按等级 + 按改动类型）
+2. **每个模板和哪个门禁挂钩？**（写不对会被哪个 Gate 拦下）
+
+模板本体在 [`./templates/`](./templates/)，门禁目录见 [GATES_AND_SCORE.md](GATES_AND_SCORE.md)，
+日常闭环见 [../guides/DEVELOPMENT_WORKFLOW.md](../guides/DEVELOPMENT_WORKFLOW.md)。
+
+> 数据来源：模板选择矩阵从 `src/skills/routing/SkillPolicy.ts` 的 `domains` 提取；
+> 等级脚手架从 `scripts/workflow/new-task.sh` 与 `scripts/workflow/plan.sh` 提取；
+> 模板↔门禁映射从 `scripts/gates/*-verify.sh` 提取。改了这些源文件请同步本表。
+
+---
+
+## 1. 模板全景（24 个）
+
+| 模板 | 一句话场景 | 谁生成/何时用 |
+| --- | --- | --- |
+| [explore.md](./templates/explore.md) | 记录读了哪些文件、主矛盾是什么 | `new-task` 自动生成，G1 检查 |
+| [mini-prd.md](./templates/mini-prd.md) | 一页纸目标/范围/验收，需求侧澄清 | `new-task` 自动生成 |
+| [spec.md](./templates/spec.md) | What / Why / 约束的规格说明 | `make plan` 深规划时生成 |
+| [plan.md](./templates/plan.md) | 边界、异常、回滚、验收的实现计划 | `new-task` 自动生成，**G2 核心** |
+| [tasks.md](./templates/tasks.md) | 计划拆成可勾选的任务清单 | `make plan` 深规划时生成 |
+| [runtime.md](./templates/runtime.md) | 配置来源、运行环境、运行时契约 | `new-task` 自动生成，G2/G18 |
+| [reality-check.md](./templates/reality-check.md) | 已确认/未验证/造假/受限分区自检 | `new-task` 自动生成，**G2 必填** |
+| [resource-cleanup.md](./templates/resource-cleanup.md) | 新增资源保留/移动/删除的处置表 | `new-task` 自动生成，G2 必须存在 |
+| [verification.md](./templates/verification.md) | 实际跑了哪些验证命令、结果如何 | `new-task` 自动生成，G8 |
+| [review.md](./templates/review.md) | 代码审查发现与结论 | `new-task` 自动生成，**G19（L/CRITICAL）** |
+| [summary.md](./templates/summary.md) | 改了什么、验证了什么、未验证什么 | `new-task` 自动生成，沉淀阶段 |
+| [api-contract.md](./templates/api-contract.md) | 接口端点、请求/响应、错误码契约 | 改 API/路由时（domain: api） |
+| [db-change-plan.md](./templates/db-change-plan.md) | 表结构/数据变更与向后兼容 | 改 DB/迁移时（domain: db） |
+| [security-review.md](./templates/security-review.md) | 资产、信任边界、鉴权规则审查 | 改鉴权/权限/迁移时（domain: security/db） |
+| [architecture-review.md](./templates/architecture-review.md) | 触及的模块、公共契约、数据流评估 | 跨模块/标准类改动（domain: engineeringStandards） |
+| [standards-impact.md](./templates/standards-impact.md) | 日志脱敏、架构边界、ORM 等规范核对 | 改 `src/` 工程规范面（domain: engineeringStandards） |
+| [docs-impact.md](./templates/docs-impact.md) | 代码改动需要同步哪些文档 | 改文档或带文档影响时（domain: docs） |
+| [resource-impact.md](./templates/resource-impact.md) | 产物的 Git 策略与保留期 | 涉及资产/媒体/报告时（domain: resourceGovernance） |
+| [ui-spec.md](./templates/ui-spec.md) | 用户目标与主流程的 UI 规格 | 改前端/界面时（domain: ui） |
+| [visual-review.md](./templates/visual-review.md) | 截图证据、布局与响应式核对 | 改 UI 后的视觉验收（domain: ui） |
+| [e2e-plan.md](./templates/e2e-plan.md) | 用户路径与浏览器覆盖计划 | E2E/浏览器自动化（domain: e2e/browserAutomation） |
+| [product-smoke.md](./templates/product-smoke.md) | 经真实产品边界的最小端到端路径 | 需要产品冒烟证据时（G8 profile） |
+| [skill-plan.md](./templates/skill-plan.md) | 识别到的领域意图与技能选择 | skill 路由启用时（多数 domain 必备） |
+| [skill-evidence.md](./templates/skill-evidence.md) | 技能/工具选择理由与证据 | skill 路由启用时（多数 domain 必备） |
+
+---
+
+## 2. 按任务等级选模板
+
+任务等级定义见 [AGENTS.md](../../AGENTS.md) 的「任务等级」表。脚手架由
+`make new-task` / `make plan` 生成，下表标注**最低**要求。
+
+| 模板 | S | M | L | CRITICAL |
+| --- | :-: | :-: | :-: | :-: |
+| explore.md | ✅ | ✅ | ✅ | ✅ |
+| plan.md | 选填 | ✅ | ✅ | ✅ |
+| reality-check.md | 选填 | ✅ | ✅ | ✅ |
+| runtime.md | 选填 | ✅ | ✅ | ✅ |
+| resource-cleanup.md | 选填 | ✅ | ✅ | ✅ |
+| verification.md | ✅ | ✅ | ✅ | ✅ |
+| summary.md | 选填 | ✅ | ✅ | ✅ |
+| mini-prd.md | — | 选填 | ✅ | ✅ |
+| spec.md / tasks.md | — | 选填 | ✅ | ✅ |
+| review.md | — | 选填 | ✅（G19 阻断） | ✅（G19 阻断） |
+| security-review.md | — | 视改动 | 视改动 | ✅（安全/权限/发布） |
+
+要点：
+
+- `make new-task NAME=x LEVEL=M` 一次性生成 9 个核心制品（explore、mini-prd、plan、
+  runtime、reality-check、resource-cleanup、verification、review、summary）。
+- `make plan NAME=x LEVEL=L` 额外生成 spec.md、tasks.md（深规划）。
+- **L / CRITICAL 的 plan.md 必须写「human confirmation / review before execution」**，
+  否则 G2 直接报错（见 §4）。
+- CRITICAL（安全、权限、发布、破坏性操作）需补 security-review.md 并完成人工确认。
+
+---
+
+## 3. 按改动类型选模板（领域矩阵）
+
+下表直接对应 `SkillPolicy.ts` 的 `domains`。命中任一「触发」条件（改动的文件路径或
+任务描述关键词），就应补齐对应**必备模板**。`skill-plan.md` 与 `skill-evidence.md`
+在 skill 路由启用时（默认 M/L/CRITICAL）几乎都需要，表中不再重复列出。
+
+| 改动类型 | 触发（文件/关键词，节选） | 必备模板（除 skill-plan/skill-evidence） |
+| --- | --- | --- |
+| 前端 / UI | `*.tsx` `*.css`，"ui/界面/组件/响应式" | mini-prd · ui-spec · visual-review |
+| API / 接口 | `**/api/**` `**/routes/**`，"endpoint/接口/路由" | mini-prd · api-contract |
+| 数据库 / 迁移 | `**/migrations/**` `*.sql` `schema.*`，"migration/迁移/schema" | db-change-plan · security-review |
+| 安全 / 鉴权 | `**/auth/**` `**/permission/**`，"token/权限/密钥/rbac" | security-review |
+| 文档 | `docs/**` `*.md`，"docs/文档/readme" | docs-impact |
+| 资源治理 | 媒体/报告/`docs/modules/**`，"asset/资产/截图/视频" | docs-impact · resource-impact |
+| 工程规范 | `src/**` `packages/**`，"日志/脱敏/架构规范/ORM" | standards-impact · architecture-review · security-review |
+| E2E / 浏览器 | `tests/e2e/**` `playwright.config.*`，"e2e/浏览器/端到端" | e2e-plan · verification |
+| 外部 CLI | `scripts/**` `.github/workflows/**`，"codex/claude code/gemini cli" | verification |
+| 代码审查 | PR 模板，"review/评审/pull request" | review |
+| 发版 / 发布 | `CHANGELOG.md` `package.json`，"release/发版/部署" | review · summary |
+| 全栈原型 | "fullstack/mvp/prototype/next.js" | mini-prd · api-contract |
+
+> 一个任务可同时命中多个领域（如「改 API + 写迁移」=api+db），取并集补齐。
+> skill 路由的强弱由 `.scale/skills.json` 的 `mode`（off/warn/block）与 `enforceLevels` 决定。
+
+---
+
+## 4. 模板 → 门禁映射
+
+下表说明「模板写不对/缺失会被哪个 Gate 拦下」，关键词约束直接来自门禁脚本，
+**不要改这些关键词**，否则正则匹配失败、门禁立刻报错。
+
+| 模板 | 门禁 | 门禁检查什么（关键词/条件） |
+| --- | --- | --- |
+| explore.md | G1 | 探索至少记录 3 个文件并写主矛盾 |
+| plan.md | **G2** | 见下方 G2 关键词清单 |
+| reality-check.md | **G2** | 必须含 6 个分区标题（见下） |
+| runtime.md | G2 / G18 | G2 要求文件存在；G18 校验运行时证据新鲜度与退出码 |
+| resource-cleanup.md | G2 | 必须存在于任务目录 |
+| verification.md | G8 | 文档/工作流制品标准（避免 localhost 链接等） |
+| review.md | **G19** | L/CRITICAL 任务需有审查记录（`.agent/state/review-*.json`） |
+| 任意变更的 `*.md` | G17 | 变更的 markdown 内部相对链接必须有效 |
+
+### G2 计划门——必须保留的关键词（来自 `scripts/gates/G2-verify.sh`）
+
+| 检查项 | 必须匹配的关键词（任一，大小写不敏感） |
+| --- | --- |
+| 范围 | `scope` / `boundary` / `boundaries` / `limit` / `non-goal` |
+| 异常覆盖 | `exception` / `error` / `fail` / `failure` / `rollback`（合计 **≥ 3 次**） |
+| 回滚策略 | `rollback` / `recovery` / `disable` / `fallback` |
+| 验收标准 | `acceptance` / `success criteria` / `definition of done` |
+| L/CRITICAL | `human confirmation` / `review before execution` |
+
+> ⚠️ `plan.md` 现有 `## Acceptance Criteria` 段名命中 `acceptance` 关键词。
+> 若想改名，必须保留 `acceptance` / `success criteria` / `definition of done` 之一，
+> 例如改成 `## Acceptance & Completion Criteria`，否则 G2 报「missing acceptance criteria」。
+
+### G2 reality-check.md 必填分区
+
+`## Confirmed`、`## Not Verified`、`## Stub / Fake / Partial`、`## Credential-Gated`、
+`## Environment-Gated`、`## User-Visible Risk` 六个标题缺一不可。
+
+---
+
+## 5. 两套模板源（改之前先确认）
+
+模板有两套独立来源，消费路径不同，**不要假设它们已经同步**：
+
+| 源 | 路径 | 消费者 | 用途 |
+| --- | --- | --- | --- |
+| 文件版 | `docs/workflow/templates/*.md` | `new-task.sh` / `plan.sh` | 本仓库自用任务制品 |
+| 内嵌版 | `src/workflow/GovernanceTemplates.ts` | `scale init` 脚手架 | 生成到**用户项目** |
+
+- 改本仓库工作流：改**文件版**即可。
+- 改 `scale` CLI 给用户生成的脚手架：改**内嵌版**（并注意 `tests/` 下的
+  `governanceTemplates` 相关测试可能断言其内容）。
+- 两套同步是独立任务，混在一起改容易让测试挂掉。
+
+---
+
+## 6. 端到端怎么走
+
+从 `make new-task` 到提交的完整一遍真实命令演练，见
+[E2E_EXAMPLE.md](./E2E_EXAMPLE.md)。
+FSM Guard（阻止未验证就 COMPLETE）的状态机示例见
+[../TASK_GUARD_WORKFLOW_DEMO.md](../TASK_GUARD_WORKFLOW_DEMO.md)。

package/docs/workflow/templates/plan.md

@@ -3,6 +3,17 @@
 Date: {{DATE}}
 Level: {{LEVEL}}
 
+## Goal
+
+- Problem / why now:
+- Desired outcome (goal-driven, not just a task list):
+- Success looks like:
+
+## Preconditions
+
+- Required state before starting:
+- Dependencies / blockers:
+
 ## Scope / Boundary
 
 - In scope:
@@ -14,6 +25,15 @@ Level: {{LEVEL}}
 2. TBD
 3. TBD
 
+## Steps with Gates
+
+| # | Step | Gate it satisfies |
+| --- | --- | --- |
+| 1 | Explore ≥3 files, record main contradiction | G1 |
+| 2 | This plan: scope / exception / rollback / acceptance | G2 |
+| 3 | Implement; change `src/` ⇒ change `tests/` | G3 |
+| 4 | Run lint / tests / verify | G4 / G5 / G6 |
+
 ## Exception / Failure Paths
 
 - Expected failure:
@@ -30,6 +50,12 @@ Level: {{LEVEL}}
 
 - TBD
 
+## Human Confirmation (L / CRITICAL)
+
+- L/CRITICAL requires human confirmation / review before execution.
+- Who confirms / when:
+- For S/M: write `N/A`.
+
 ## Verification
 
 - `make gate-quality`

package/docs/workflow/templates/spec.md

@@ -3,14 +3,42 @@
 Date: {{DATE}}
 Level: {{LEVEL}}
 
+> P0 六要素契约（借鉴 Codex Goals 完成契约模型）。`Outcome` 复用 `What`，其余为可选补强字段；
+> 留空即视为未声明，不会破坏旧流程。CLI 对应参数见 `docs/workflow/TEMPLATE_GUIDE.md`。
+
 ## What
 
+<!-- Outcome: 期望的最终现实状态，而非任务步骤描述。 -->
 
 ## Why
 
 
+## Verification Surface
+
+<!-- 具体证据来源：测试名 / 基准命令 / 产物路径。verify/review/ship 的 evidence 应能映射回这里。 -->
+<!-- CLI: scale define ... --verification-surface "tests/foo.test.ts,npm run e2e" -->
+-
+
+## Constraints
+
+<!-- 运行期间不能退化的指标（性能 / 安全 / 兼容性）。 -->
+<!-- CLI: --constraints "p95 < 200ms,no new prod dependency" -->
+-
+
 ## Boundaries
 
+<!-- CLI: --boundary-files / --boundary-tools / --boundary-forbidden -->
+- Files:
+- Tools:
+- Forbidden:
+
+## Iteration Strategy
+
+<!-- build 阶段每轮迭代后如何决定下一步。CLI: --iteration-strategy "..." -->
+
+## Blocked Stop Condition
+
+<!-- 无可行路径时报告什么、需要什么才能解锁。CLI: --blocked-stop "..." -->
 
 ## Acceptance Criteria
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hongmaple0820/scale-engine",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Executable AI agent governance with workflow gates, evidence, skill/tool orchestration, and traceable HTML artifacts",
   "repository": {
     "type": "git",
@@ -57,6 +57,7 @@
   "dependencies": {
     "@hono/node-server": "^2.0.4",
     "@modelcontextprotocol/sdk": "1.29.0",
+    "@typescript-eslint/typescript-estree": "^8.59.3",
     "better-sqlite3": "^11.10.0",
     "chokidar": "^3.6.0",
     "citty": "^0.1.6",
@@ -82,6 +83,7 @@
     "@types/better-sqlite3": "^7.6.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.14.0",
+    "@typescript-eslint/eslint-plugin": "^8.60.1",
     "@typescript-eslint/parser": "^8.59.3",
     "eslint": "^9.0.0",
     "tsx": "^4.21.0",