Positioning
NeonForge stage completion checker — turns "claimed complete" into "individually verifiable" (spec-kit/evaluator pattern).
Each S stage has a stage-spec (docs/design/stage-specs/S{N}.md) that carries machine-verifiable DoD assertions;
this skill executes these assertions one by one, outputting PASS/FAIL + evidence.Verify only, don't fix: FAIL reports the discrepancy and hands it back to development.
When to use
- The user/agent claims some S stage is complete ("S2 is done", "stage complete")
- Request to "run the stage gate", "stage gate", "pass the gate"
- Self-check before closing a stage (the FAILs produced here are the to-do list)
Inputs
- stage-spec：
docs/design/stage-specs/S{N}.md(DoD section = assertion list) - Repository:
apps/desktop(working directory for all gate commands) - Related assets:
docs/tests/coverage-matrix.md(coverage matrix),.scratch/neonforge-v1/audit-items/(audit items),docs/decisions/(decision log)
Hard constraints (non-negotiable)
- Verify only, don't fix— FAIL always reports the discrepancy; do not fix code / do not add tests / do not modify the spec.
- Evidence first— every assertion must carry fresh evidence from this run (command output tail / exit code / test results); "it ran last time" and "it should be fine" don't count.
- Don't fabricate passes— command can't be run, CI can't be queried, manual acceptance not done → judge as unverified(not PASS, not FAIL, list separately).
- Full, one by one— every
- [ ]assertion in the DoD section must be executed; no sampling, no skipping.
Process
- [ ] 1. 定位 spec：docs/design/stage-specs/S{N}.md（N 由用户给出或从语境推断）
- [ ] 2. spec 缺失 → 直接报告「无 spec，阶段无法门禁」（这本身就是发现——spec 未写）
- [ ] 3. 读 DoD 节 → 提取全部 `- [ ]` 断言（含嵌套子断言——行为验收下常有）
- [ ] 4. 逐条执行（分类方法见下节），每条记录：断言原文 / 判定 / 证据尾部
- [ ] 5. 汇总 → 写 gate 报告 docs/audits/stage-gate-S{N}-YYYY-MM-DD.md
- [ ] 6. 全绿 → 阶段可收（附基线信息）；有 FAIL/未验证 → 差异清单交回开发
DoD assertion classification and execution methods
| Assertion type | Judgment method | Evidence form |
|---|---|---|
| L1 full suite | npx vitest run(working directory apps/desktop) |
Output tail (tests/files/passed/failed) + exit code; when the spec has "new cases ≥N", verify the case count |
| L2 contract | npx tsc -p tsconfig.json --noEmit + npx tsc -p tsconfig.main.json --noEmit run both |
PASS only if both have 0 errors; if either has errors → FAIL (list error count/first error location) |
| L3 interaction | npx playwright test --project=interaction |
Passed count/total count; compare against the expected count in the spec (e.g. 31/31) — shortfall means FAIL |
| Behavior acceptance | The commands or tests given in the spec; execute nested sub-assertions one by one (if there's a test file → npx vitest run <file> targeted run) |
Each sub-assertion independently PASS/FAIL + corresponding test output |
| Coverage matrix | docs/tests/coverage-matrix.md exists + spot-check 3 entries against tests/registry |
Spot-check results; when the spec requires "first version produced", verify existence |
| Audit status | Read .scratch/neonforge-v1/audit-items/README.md enumerate open items → check each for fixed/recorded |
Open item list (should be empty or all have closure evidence) |
| Decision log | docs/decisions/000-decision-log.md index up to date (this stage's rulings have ADR numbers) |
Index table tail |
| push status | git status clean + git log @{u}..HEAD empty (no unpushed commits) |
Tail of git output; if the remote CI is green and checkable (not checkable locally → unverified) |
Nested assertions: under behavioral acceptance, the - [ ] sub-items are executed one by one and must not be merged into a single "behavioral acceptance passed".
Gate report (the only output)
docs/audits/stage-gate-S{N}-YYYY-MM-DD.md：
# Stage Gate S{N} 报告
- 日期 / spec 路径 / 基线 commit（阶段首 commit^，如有）
- 结论：全绿 ✓ | 有 FAIL ✗ | 有未验证
## 断言结果
| # | 断言 | 判定 | 证据（输出尾部） |
|---|------|------|-----------------|
| 1 | L1 全量绿 | PASS | vitest: 344 passed, 0 failed |
| 2 | … | FAIL | tsc: 2 errors (src/…:12) |
## 差异清单（交回开发，不修）
- #N：期望 …；实际 …；证据 …
Boundaries (division of labor)
| Adjacent skills | Division of labor |
|---|---|
verification-before-completion |
single verification (one command/one claim); stage-gate = stage-level aggregation (the DoD of the entire spec) — single points first, then aggregation |
executing-plans |
execution plan (task-by-task implementation); stage-gate only verifies, does not execute— the gate comes only after execution is complete |
audit-item |
the gate checks open audit items; new findings are entered by code-review/audit and enumerated at the next gate |
coverage-matrix |
the gate checks that the matrix exists and is consistent; matrix updates are the responsibility of the coverage-matrix skill |
Completion criteria
- Every DoD assertion has an execution result (PASS/FAIL/unverified) + fresh evidence
- FAIL is only reported, not fixed; the discrepancy list specifies assertions and evidence concretely
- the gate report has been persisted to disk
docs/audits/stage-gate-S{N}-YYYY-MM-DD.md - unverified items explicitly list the reason (CI not checkable/manual acceptance not done)
- when the spec is missing, report "cannot gate" rather than pretending it was run
Anti-patterns
- Claiming "all green" without running the command (violates verification-before-completion)
- Fixing FAIL along the way — the gate becomes development and loses neutrality
- Using the previous output/someone else's report as this time's evidence
- Running only L1 and skipping behavioral acceptance, audit checks, and push status
- "Running as usual" against a nonexistent spec — should report spec missing
- Marking "unverified" as PASS