2026-09-15 08:41:51 +08:00
---
name : verify
description : >
Use ONLY after all work items in an iteration have passed code review. The
Verifier (Worker) runs the iteration's DoD matrix, integration tests, NFR
validation, and regression checks. The iteration is not Done until all DoD
items pass.
stage : verify
triggers :
- verify iteration
- 验证迭代
- iteration verification
- 检查迭代完成
- validate iteration
- DoD check
role : Verifier
---
> Core 中立版（Increment 6a 改写，原 deferHard verbatimDir）。机制、结构与 frontmatter 保持；实例术语（工具名、路径、工单号）按 `core/adapters/TERMINOLOGY.md` 绑定到具体实例。
# Iteration Verification
Systematically verify that all work items in the current iteration integrate
correctly and satisfy every Definition-of-Done criterion. This is the
iteration-level quality gate — individual work items may have passed code
review, but the iteration is not complete until integration is verified.
## Process Overview
Every diamond is a gate the Verifier rationalizes waiving — most often by confusing "nothing failed yet" with "verified passing".
```dot
digraph verify {
rankdir=TB;
node [shape=box, fontname="Helvetica"];
pre [shape=diamond, label="Reviews converged?\n(code + review-dag for DAG runs)"];
abort [label="ABORT: list un-converged\nreviews / missing artifacts"];
exec [label="Phase 2: Execute\n(full suite + typecheck + lint\n+ perf + security + regression)"];
dod [shape=diamond, label="Any DoD criterion\nFAIL?"];
nfr [shape=diamond, label="Any NFR threshold\nviolated?"];
td [shape=diamond, label="Every tech-debt trigger\nobjectively verifiable?"];
tdgap [label="Not tech debt →\niteration verdict = FAIL"];
commit [shape=diamond, label="Commits exist\nfor this iteration?"];
done [shape=doublecircle, label="Iteration Done"];
pre -> abort [label="no"];
pre -> exec [label="yes"];
exec -> dod;
dod -> exec [label="yes: route to Developer"];
dod -> nfr [label="all PASS"];
nfr -> exec [label="yes"];
nfr -> td [label="all PASS"];
td -> tdgap [label="no"];
td -> commit [label="yes"];
commit -> done [label="yes"];
commit -> abort [label="no: must commit first"];
}
```
## Agent Role
2026-09-25 00:09:37 +08:00
> **Progressive disclosure ([TT-3722], [TT-3734], [TT-3745])**: when dispatching a Verifier
2026-09-15 08:41:51 +08:00
> scoped to one phase, pass `skills: ["verify:phase-2"]` (preamble + that
> phase only) instead of the full body; multi-phase dispatches may union.
2026-09-25 00:09:37 +08:00
> Phase 5 is subdivided ([TT-3734]): `phase-5` covers the report template only;
2026-09-15 08:41:51 +08:00
> each mandatory filing subsection carries its own marker (`phase-5.5` tech
> debt, `phase-5.55` baseline failures, `phase-5.56` flaky tests,
> `phase-5.6` checklist sync, `phase-5.7` CI sync). Dispatch recipes:
> FAIL verdict → `"verify:phase-5,phase-5.5,phase-5.6"` (union `phase-5.55`
> / `phase-5.56` when baseline failures / flaky tests are present); PASS
> close-out →
> `"verify:phase-5,phase-5.5,phase-5.55,phase-5.56,phase-5.6,phase-5.7,phase-6"`.
2026-09-25 00:09:37 +08:00
> The DAG branch is separately marked ([TT-3745]): `phase-6` narrows to
2026-09-15 08:41:51 +08:00
> Approval + Commit Gate, and the tail References rides `dag-branch` (same
> tail rule as review-code's phase-e). Non-DAG dispatches thereby drop the
> ~175-line DAG branch; DAG milestone/task verify → union `dag-branch` onto
> the close-out family (`"…,phase-6,dag-branch"`) — the branch's override
> clauses take precedence over the unioned phase bodies.
> Sections not listed here (Process Overview, Preconditions, …) are unmarked
> preamble and always inject. Full-body remains the default when no selector
> is passed.
The verification is owned and executed by the **Verifier** (Worker). The Verifier is a dedicated sub-agent that
validates — it does not write code.
The Verifier is responsible for:
- Reading the iteration's DoD matrix from the plan.
- Running the full test suite (unit + integration) for the iteration.
- Validating non-functional requirements against quantified thresholds.
- Running regression tests to confirm no prior iteration is broken.
- Producing a pass/fail verdict per DoD criterion with evidence.
- Reporting failures back for the Developer to fix.
The Orchestrator's role is to present the verification result and, on failure,
route findings back to a new implementation cycle. The Verifier MUST NOT
modify code, tests, or configuration files — only validate and report.
**Context compaction** : verify is a stage boundary in the main session's
pipeline. The orchestrator compacts at this clean boundary ONLY when a
capacity/projection trigger holds, per the L1 rule `core/rules/compact.md`
§"Stage-boundary compaction" (long multi-stage runs — DAG Epic orchestration — keep the legacy
every-boundary compaction; short runs — bugfix / DAG task — and standalone
runs default to NOT compacting). The
Verifier sub-agent itself is single-phase: it persists its verdict to
`{slug}/05-verify-iteration-{N}` as it goes, so a mid-run compaction loses
nothing — re-read the DoD matrix and the verify wiki page to resume (see the
Verifier role's `compact.preserve` list in
`core/skills/_shared/roles/verifier.yaml` ).
## Greenfield vs. Brownfield
**Greenfield** (new project): Verify the current iteration's DoD matrix only.
No prior iterations exist.
**Brownfield** (existing project + new feature):
- **Regression is PRIMARY.** Run the FULL test suite (all prior iterations +
new code). A regression failure blocks the iteration regardless of new
feature DoD status.
- If no prior verification report exists (check Gitea wiki for
`{slug}/05-verify-iteration-{N}` pages — this replaces the deprecated
`.artifacts/{slug}/verification/` directory),
run the full test suite first to establish a baseline BEFORE verifying the
new iteration. Baseline failures that pre-date this iteration are **filed as
`baseline-failure` Gitea issues in Phase 5.55** — they do not block the
iteration verdict, but the iteration is NOT Done until every pre-existing
failure is registered (an un-filed baseline failure is a process gap). Only
new regressions (caused by this iteration) block the verdict.
- New NFR thresholds must not degrade existing system metrics. If a new feature
increases P99 latency from 150ms to 180ms (still under 200ms threshold),
log it as a warning — the trend is toward the limit.
- In brownfield mode the Phase 2.1 full-suite run executes FIRST (before DoD
evaluation) so its output doubles as the regression baseline for Phase 2.6 —
still a single execution per tree state (2.6 reuses it; see Phase 2.1).
---
## Preconditions
Before starting verification, confirm:
- [ ] All work items in the current iteration have passed code review
AND code review has **converged** . Run `octopus review status --stage code`
— the `pipeline/review-code` commit status must show state `success` .
Auto-approve does not guarantee convergence; a review that found
BLOCKERs and stopped before resolution is not converged.
- [ ] Code review final report exists at `{slug}/reviews/code/final/report`
(Gitea wiki page; deprecated: `.artifacts/{slug}/reviews/code/final/report.md` )
and final verdict is PASS (or user-approved WARN with no unresolved
BLOCKERs).
- [ ] The work spec exists. DAG task/milestone mode (the live path — see the
DAG branch below): the frozen DAG copy `{epic-slug}/dag` supplies the
node spec, its `acceptance_criteria` + `test_id` declarations, and the
DoD slice. (Legacy tier rule — `{slug}/04-plan-*` wiki pages / issue
comment, and the design-space + iteration-plan convergence checks that
2026-09-25 00:09:37 +08:00
used to follow here — was archived 2026-08-21, [TT-3072] phase 3; historical
2026-09-15 08:41:51 +08:00
plan/AC pages stay readable via `_shared/gitea-read-patterns.md` .)
- [ ] `core/checklists/verification.md` is accessible.
- [ ] `slug` matches the run's slug (DAG: `{epic-slug}` ).
- [ ] Upstream dependencies are complete. DAG task mode: the node's
cross-session in-edge source nodes are at terminal state (task `done` /
milestone `green` ). If any dependency is not complete → abort, listing
the blocked nodes.
- [ ] Carried items from the previous iteration are closed: every carried
item must have an explicit Target Iteration and must have been handled
in the current iteration or have a fresh deferral record. If any
carried item is not closed → warn and list the open items.
- [ ] Carried risks from the previous iteration are updated: each carried
risk recorded by the prior iteration (historically the plan's Carried
Risks table) is marked `open` or `closed` with a current status. A risk
left `open` without an explicit reactivation note is a gap → warn and
list it.
If the user asks to verify an iteration that still has unreviewed work items,
warn and ask via the `question` tool, passing `stage: "verify"` :
```
Work items {list} have not passed code review.
All work items in an iteration must be code-reviewed before integration
verification.
→ Run code review first? (yes / no)
```
The `question` tool auto-approves per `core/rules/auto-approve.md` (stage `"verify"` ).
For any other precondition failure (missing artifacts, un-converged reviews,
incomplete dependency chunks, open carried items), abort and inform the user.
Refer to `core/checklists/pipeline-gate.md` — both the Failure Protocol
and the Recovery Protocol — to determine which skill to run next to fix
each missing item.
---
<!-- section:phase-1 -->
## Phase 1 — Load Verification Context
> **Pipeline stage**: if the source issue exists, move it to the `verify`
> column on the Pipeline Stages board per `_shared/gitea-write-patterns.md`
> Pattern 7.5. Skip if no source issue exists.
Read the upstream artifacts. DAG task/milestone mode (the live path — see
the DAG branch below for its read map):
1. **Work scope** — the node(s) under verification in the frozen DAG copy
`{epic-slug}/dag` (+ `{epic-slug}/dag-nodes/{node-id}` subpages when AC
detail is sunk) and the node ticket's issue body:
- Node ACs, `size_attrs` , and the milestone DoD slice (milestone mode).
2. **DoD matrix** — the node `acceptance_criteria` with each AC's declared
`test_id` (`{file-path}::{test-name}` / `MANUAL` / `BENCH:<script>` /
`BROWSER:{pack-ref}` for UI-claim browser-evidence rows — see Phase 2.7
and Phase 3, contract `browser-evidence-4486/shared/evidence-ref-v1` );
milestone mode uses the fan-in slice (spec-05 §5).
3. **Requirements** (for reference) — the DAG's requirement registry rows
(`req_refs` ) and any `NFR:` entries on the node ACs.
4. **Non-functional targets** — the node's `NFR:` AC entries (product NFRs
live in node AC; there is no separate NFR design page on the DAG route).
(The legacy `Size/*` -tiered locations — `{slug}/04-plan-*` ,
`{slug}/02-requirements-index` , `{slug}/02-03-req-design` ,
`{slug}/03-design-06-non-functional-design` — were archived 2026-08-21,
2026-09-25 00:09:37 +08:00
[TT-3072] phase 3; historical pages stay readable for legacy-run verification
2026-09-15 08:41:51 +08:00
via `_shared/gitea-read-patterns.md` .)
5. **Code review final report** — `{slug}/reviews/code/final/report`
(Gitea wiki page; deprecated: `.artifacts/{slug}/reviews/code/final/report.md` ):
- Confirm all issues are resolved and code review verdict is PASS.
**Output** : internal. Produce a verification plan summary:
```markdown
## Verification Plan: Iteration {N}
**DoD entries** : {K} total
- {U} unit-test verifiable
- {I} integration-test verifiable
- {P} performance-test verifiable
- {S} security-scan verifiable
- {M} manual verifiable
**Non-functional targets** : {NF} from plan
**Regression scope** : iterations 0–
```
---
<!-- section:phase-2 -->
## Phase 2 — Execute Verification
Run verification commands from the relevant package directory (per `rules/testing.md` — do NOT run tests from repo root). Capture all output.
### 2.0 — Reuse Same-SHA CI Results (fail-closed)
Mechanical checks Gitea CI has already gated on this exact code state must
not be re-run locally. If a PR exists for the iteration branch:
1. Resolve the PR head SHA and read that SHA's commit statuses (the read
counterpart of `_shared/gitea-write-patterns.md` Pattern 8:
`GET /api/v1/repos/Octopus/octopus/commits/{sha}/statuses` ).
2. For Phase 2.2 (typecheck), 2.3 (lint), and 2.5 (security scan): if the
corresponding same-SHA CI status/job is `success` (e.g. the `CI` workflow's
`check` job, the SAST workflow), cite it as the DoD evidence (record the
job name + SHA in the report) and SKIP the local re-run.
3. A `pending` , `failure` , or missing status is NOT evidence — run the check
locally instead. Do not block waiting for a pending CI run.
4. Phase 2.1 (full suite) is never skipped this way: PR CI runs `test:changed`
(incremental), so the full `test:parallel` execution stays local unless a
same-SHA `run-full-tests` run exists.
If no PR exists (or statuses are stale/missing), run everything locally as
before. This section saves redundant typecheck/lint/security re-runs; it
never weakens a gate.
**Second evidence source — the review-code precondition-gate cache
2026-09-25 00:09:37 +08:00
(eff-gate-cache [TT-2598] / [TT-2990])**. The mechanical checks this phase would re-run
2026-09-15 08:41:51 +08:00
(oxlint / typecheck / `test:changed` ) are exactly the precondition-gate's
check-set, and the gate caches GREEN results keyed on a tree fingerprint
(HEAD + tracked diff + untracked contents) in
`<runs-root>/<slug>/reviews/code/precondition-gate.jsonl` (Tier 1, same
worktree). Consume it by RUNNING the gate script — it computes the
fingerprint, reuses the green record on a cache hit, and appends an audit
record; never re-derive the fingerprint by hand:
```bash
bun core/skills/review-code/scripts/precondition-gate.ts <slug>
```
5. Exit 0 with `GREEN (cache hit …)` — the identical tree was already proven
mechanically green by review-code's gate. Cite the record (slug +
fingerprint timestamp from the output) as the DoD evidence for Phase 2.2
(typecheck) and 2.3 (lint) and skip their local re-runs — the same
fail-closed reuse as the CI clauses above.
6. Exit 0 with a FRESH green (fingerprint differs — the tree changed after
review-code, e.g. review fixes landed): this run IS the single local
mechanical execution for the new tree state; its record now serves any
later consumer. Cite it the same way.
7. Exit 1 (RED) or the gate log absent (different worktree — Tier 1 is
worktree-local): NOT evidence — follow the normal local path above. After
an environment change (bun version, fresh node_modules) pass `--no-cache`
so a stale green can never be reused across environments.
Phase 2.1 (full suite) is never skipped by the gate cache either — the gate
deliberately excludes `test:parallel` (the full suite belongs to verify). The
gate fingerprint is keyed on the working tree (SHA + uncommitted state +
untracked), so it covers pre-push/headless states the same-SHA CI clauses
cannot.
### 2.1 Full Test Suite
```bash
bun run test:parallel # or project-equivalent
```
- **Single execution per tree state**: run the full suite ONCE. The captured
output serves Phase 2.6 (regression classification) as well — do not re-run
the suite there. Re-run only if code changed since this run (fixes landed
mid-verification).
- All tests must pass. Any failure is a DoD failure.
- If the project uses separate unit and integration test commands, run both.
- **Detect flaky tests.** Re-run ONLY the tests that failed or look
timing-sensitive (targeted reruns via
`cd <harness-package> && bun test --timeout 120000 <file>` ,
per checklist item 2.4's isolated-serial allowance) — not the whole suite.
Checklist 2.4: modules using `git worktree add/remove` may hang
`test:parallel` on git internal file locks (parallel git contention); the
isolated/serial rerun above with `--timeout 120000` is the accepted
substitute and must be annotated TST-GIT-CONTENTION. Record each flaky
test name; new flaky tests introduced this iteration are routed to the
Developer for root-cause, and every flaky test NOT fixed in-iteration is
filed in Phase 5.56.
### 2.2 Typecheck
```bash
bun typecheck
```
- Zero type errors. Type errors after code review indicate a merge or
integration issue.
### 2.3 Lint
```bash
bun oxlint --deny-warnings
```
- Zero lint errors. The canonical invocation is `bun oxlint --deny-warnings`
at the repo root, mirroring ci.yml — `bun lint` is the package-script alias.
Warnings are noted but do not block DoD unless the project gates on them.
### 2.4 Performance Validation
For each DoD entry with verification method "Performance test":
1. **Baseline** : if prior iteration performance data exists (brownfield mode),
load it as the baseline. If no baseline exists (greenfield), run the
performance test suite twice and use the average as the baseline for
future iterations.
2. **Run performance tests** : execute the project's performance test suite.
Capture P50, P95, P99, and throughput for each critical path.
3. **Compare** : compare against the quantified targets from the design
document AND against the baseline. A regression below the threshold but
trending toward it (>10% degradation) is a ⚠️ WARNING, not a FAIL.
4. **Profile if failing** : if a performance target is exceeded, run a profiler
(e.g. `clinic` , `0x` , `py-spy` , `pprof` ) on the critical path and identify
the bottleneck. Include the profile hotspot in the failure report.
5. If no automated performance tests exist, identify the gap and mark the
criterion as `⚠️ UNVERIFIABLE — no automated test` . Suggest a specific
performance test framework or benchmark library for the project's
technology stack.
### 2.5 Security Validation
For each DoD entry with verification method "Security scan":
1. Run the project's security scanner (e.g. `npm audit` , SAST tool).
2. Check for new vulnerabilities introduced in this iteration.
3. If no automated security scan exists, mark as `⚠️ UNVERIFIABLE` .
### 2.6 Regression Check
1. Reuse the Phase 2.1 full-suite output (same tree, same run) — the suite
covers tests from all prior iterations by construction. Re-run the full
suite ONLY if code changed since Phase 2.1 (fixes landed mid-verification).
2. Confirm zero regressions — no previously passing test now fails.
3. If regressions are found, report each with the failing test name and
likely cause (from git diff since last successful run).
4. **Classify each failure as regression vs pre-existing (brownfield).** For
every failing test, run it on the last known-green commit (or the base
branch) in isolation. **Never use `git stash` for this** — the stash stack
is shared across all worktrees of this repo and a parallel session can
2026-09-25 00:09:37 +08:00
overwrite your entry mid-flight (issue [TT-1655]). Instead, use the
lifecycle-managed scratch-worktree script ([TT-2790]) — it registers the
2026-09-15 08:41:51 +08:00
worktree for the sweep backstop, symlinks `node_modules` from the source
checkout when `bun.lock` matches (dropping the per-instance cost from
~170k inodes to ~7k), and deregisters on removal:
```bash
bash script/scratch-worktree.sh create <slug>-base <base> # base / last-green commit
(cd /tmp/octopus/<slug>-base/<harness-package> && bun test --timeout 120000 <failing-test>)
bash script/scratch-worktree.sh remove <slug>-base # cleanup when done
` ``
When ` create` symlinks ` node_modules` (its output says so) the test run
reuses the source checkout's install directly — do NOT run ` bun install`
in the scratch worktree (it would write through the symlink into the
shared ` node_modules`). Only if ` create` printed the "bun.lock differs"
note run a real ` bun install --silent` there first.
The current iteration worktree stays dirty and untouched; the scratch
worktree runs the baseline in isolation. If the failing test needs
uncommitted changes from the iteration branch to even _run_, WIP-commit
them on a throwaway branch (` git switch -c wip/<slug>-base-check && git
commit -am "wip: baseline probe"`) and cherry-pick that commit into the
scratch worktree instead (create it with ` --base` pointing at a throwaway
branch the commit is cherry-picked onto).
- **Fails on base too** → **pre-existing / baseline failure (BF)**. Does
NOT block the verdict; MUST be filed in Phase 5.55.
- **Passes on base, fails here** → **regression** (caused by this
iteration). BLOCKS the verdict; route to the Developer.
Abandoned scratch worktrees (session died before ` remove`) are reclaimed
by the ` sweep` backstop — see ` script/scratch-worktree.sh` header and
` deploy/systemd/octopus-scratch-sweep.service`.
Never silently drop a pre-existing failure as "someone else's problem" —
every BF becomes a tracked ` baseline-failure` issue or the iteration is
not Done.
### 2.7 — Browser Evidence Reference Validation (UI-touching PR)
For DoD entries of the「UI 主张 ↔ 可复现浏览器证据」type — contract
2026-09-25 00:09:37 +08:00
` browser-evidence-4486/shared/evidence-ref-v1` (frozen 2026-09-10, [TT-4498]).
2026-09-15 08:41:51 +08:00
Applicable ONLY to UI-touching PRs (changes under ` packages/app`,
` packages/ui`, or ` packages/console/*` frontend surfaces):
1. Validate each ` BROWSER:{pack-ref}` reference mechanically
(` pack-ref` = ` <runs-root>/{slug}/browser/{session-id}`, the manifest's
directory):
` bun <harness-package>/scripts/browser-evidence-ref.ts {pack-ref}`.
Exit 0 / ` status: ok` = manifest parses with the pack-manifest-v1 shape,
the pack is REGISTERED in {slug}/index.json (browser-evidence row), and it
carries a trace (replayable). Every other status — ` unregistered`
(no such dir, not a .../browser/{session-id} layout, or no index row),
` manifest-missing`, ` manifest-corrupt`, ` not-replayable` (no trace),
` over-limit` — is an explicit failure: the
DoD row is ⚠️ UNVERIFIABLE at best (❌ FAIL when the evidence itself was
the deliverable), never silently green.
2. Summary line for the DoD Evidence column / PR description (contract §2):
` UI 主张 {claim} ↔ {pack-ref}（ ， ） `
— rendered from the pack manifest only; the publisher never touches raw
captures (sanitize boundary is upstream, ` shared/pack-manifest-v1` §5).
3. Tier-2 visibility: at most 5 screenshots / 200KB total may be published
to the wiki evidence namespace (` {slug}/verify/evidence/{name}`, existing
convention); the pack itself stays Tier 1 and rides archived-at-close
into git.
4. A pack without a trace is not replayable and MUST NOT produce a green
DoD row for a replay claim.
5. Non-UI-touching PRs do not carry this entry type at all — a BROWSER row
on a backend-only change is a DoD-matrix error.
---
<!-- section:phase-3 -->
## Phase 3 — DoD Matrix Evaluation
For every DoD entry, produce a verdict:
` ``markdown
| # | REQ ID | Acceptance Criterion | Verification Method | Verdict | Evidence |
| --- | ---------- | ------------------------------- | ------------------- | --------------- | ---------------------------------------------------------- |
| 1 | REQ-F-001 | User can register with email+pw | Integration test | ✅ PASS | ` test/auth/register.test.ts:42` passes |
| 2 | REQ-F-001 | Invalid email returns 400 | Unit test | ✅ PASS | ` test/auth/register.test.ts:67` passes |
| 3 | REQ-NF-005 | Login P99 < 200ms | Performance test | ❌ FAIL | P99 measured at 312ms (target: 200ms) |
| 4 | REQ-F-003 | JWT expiry at 1h | Unit test | ⚠️ UNVERIFIABLE | No test found; code review confirmed but no automated test |
| 5 | REQ-F-002 | 登录页视觉回归可回放证据 | Browser evidence | ✅ PASS | UI 主张 登录页视觉回归 ↔ <runs-root>/{slug}/browser/{session-id}（ ， ）
` ``
### Verdict Rules
| Verdict | Meaning | Blocks Iteration? |
| --------------- | ---------------------------------------- | ---------------------------- |
| ✅ PASS | Criterion verified with passing evidence | No |
| ❌ FAIL | Criterion verified and fails | YES |
| ⚠️ UNVERIFIABLE | No automated test exists to verify | No (but logged as tech debt) |
Browser-evidence rows (UI-touching PRs only, Phase 2.7): ✅ PASS requires a
mechanically validated, replayable pack-ref; ` unregistered` / ` manifest-missing` /
` manifest-corrupt` / ` not-replayable` / ` over-limit` references are
⚠️ UNVERIFIABLE at best — the reference channel fails explicitly, never
2026-09-25 00:09:37 +08:00
silently green ([TT-4498] AC-4).
2026-09-15 08:41:51 +08:00
### Iteration Verdict
The iteration verdict is computed from the DoD matrix:
- **PASS**: 100% of verifiable criteria are ✅ PASS. UNVERIFIABLE entries do
not block.
- **FAIL**: One or more criteria are ❌ FAIL.
---
<!-- section:phase-4 -->
## Phase 4 — Non-Functional Validation
For each non-functional requirement target in the current iteration:
` ```markdown
| NFR ID | Target | Measured | Threshold | Verdict | Notes |
| ---------- | ------------------------ | -------- | --------- | ------- | --------------------- |
| REQ-NF-005 | Login P99 latency | 312ms | < 200ms | ❌ FAIL | Exceeds target by 56% |
| REQ-NF-007 | Registration P99 latency | 145ms | < 200ms | ✅ PASS | |
| REQ-NF-010 | Test coverage | 87% | ≥ 80% | ✅ PASS | |
` ```
---
<!-- section:phase-5 -->
## Phase 5 — Report
Produce the verification report:
` ``markdown
# Iteration Verification Report
**Project**: {slug}
**Iteration**: {N}: {Goal}
**Date**: YYYY-MM-DD
## Verdict: {PASS | FAIL}
## DoD Matrix Summary
| Status | Count |
| --------------- | ----- |
| ✅ PASS | {N} |
| ❌ FAIL | {N} |
| ⚠️ UNVERIFIABLE | {N} |
| **Total** | {N} |
## Failed Criteria
| # | REQ ID | Criterion | Measured | Expected | Gap |
| --- | ---------- | ----------------- | -------- | -------- | ---- |
| 3 | REQ-NF-005 | Login P99 < 200ms | 312ms | 200ms | +56% |
## NFR Summary
- {N}/{M} thresholds passed
- {F} thresholds violated
## Unverifiable Criteria (Tech Debt)
| REQ ID | Criterion | Reason | Reactivation Trigger | Issue |
| --------- | ---------------- | ------------------------ | -------------------- | ----- |
| REQ-F-003 | JWT expiry at 1h | No automated test exists | {可客观判断的条件} | #NNNN |
> Every row is registered as a ` ## TD 登记` registry row in Phase 5.5
> (` core/rules/ticket-lifecycle.md`). The ` Issue` column records the
> mapping produced there: ` TD-NNN → 登记行（source #NNNN ） ` while unpromoted,
> ` TD-NNN → #NNNN ` once promoted.
## Regression Status
- Prior iteration tests: {N} passing, {M} failing (regressions)
- Non-regression check: {PASS | FAIL — {list}}
## Baseline Failures (Pre-existing)
| # | Test | BF ID | Issue | Severity | Root cause (if known) |
| --- | ---------------------------- | ------ | ----- | -------- | ---------------------------------------------- |
| 1 | ` test/foo/bar.test.ts::name` | BF-NNN | #NNNN | MEDIUM | pre-dates this iteration; fails on base commit |
> Every pre-existing failure classified in Phase 2.6 is filed against (or
> into) a root-cause family umbrella in Phase 5.55. The ` BF-NNN → #NNNN `
> mapping names the FAMILY umbrella; sibling occurrences attach as evidence
> comments on it. If this section is empty, record "0 baseline failures".
## Flaky Tests (Intermittent)
| # | Test | FT ID | Issue | Severity | Status |
| --- | ---------------------------- | ------ | ----- | -------- | ----------------------------- |
| 1 | ` test/foo/bar.test.ts::name` | FT-NNN | #NNNN | MEDIUM | intermittent (3/10 runs fail) |
> Every flaky test not fixed in-iteration is filed against (or into) a
> root-cause family umbrella in Phase 5.56. If this section is empty, record
> "0 flaky tests".
` ``
## Verification Commands Executed
` ``
bun run test:parallel → N passed, M failed
bun typecheck → {pass/fail}
bun oxlint --deny-warnings → {pass/fail}
` ``
## Next Steps
- If PASS: iteration is complete. Ready for next iteration.
- If FAIL: route failed criteria to Developer. Re-run ` review-code` on fixes,
then re-run verification.
Write the report as a Gitea wiki page using ` wiki 读写 API（见 TERMINOLOGY） ` with
title ` {slug}/05-verify-iteration-{N}` (replaces the deprecated
` .artifacts/{slug}/verification/iteration-{N}/report.md` path).
Then update the ` ## 工件索引` comment on the source issue per
` _shared/gitea-write-patterns.md` Pattern 10: add the ` VERIFY-{N}` row
(位置 = the report page, 重读 = ARCHIVE — closed-iteration reports are never
re-read for context recovery). Per-row ARCHIVE here marks this iteration's
report; the **archive-at-close action** (banner + all rows → ARCHIVE at
issue close) is performed later in Phase 5.6 — see
` rules/issue-checklist-sync.md` § 归档动作.
<!-- section:phase-5.5 -->
2026-09-25 00:09:37 +08:00
### Phase 5.5–
> The four mandatory-before-PASS filing protocols — Phase 5.5 Tech-Debt
> registry filing (sprint-mode override), Phase 5.55 baseline-failure
> registration, Phase 5.56 flaky-test registration, Phase 5.6 issue
> checklist final sweep — live in ` reference/issue-filing.md`. Read each at
> its boundary during Phase 5; PASS is blocked until all applicable filings
> report completion. Phase 5.7 (CI state sync) stays inline below.
2026-09-15 08:41:51 +08:00
<!-- section:phase-5.7 -->
### Phase 5.7 — CI State Transition Sync (progressive)
Process-type acceptance criteria (e.g. "ci.yml passes N consecutive runs",
2026-09-25 00:09:37 +08:00
AC#3 in [TT-1668]) have no single moment of completion — their progress lives on
2026-09-15 08:41:51 +08:00
the issue. The ` CI` row in ` ## 当前状态` is written by the ` status-sync` poller
(` .gitea/scripts/status-sync-poll.ts`), NOT this skill — do NOT manually
` 工单 API（见 TERMINOLOGY） ` it. When verification observes a CI state transition
(first green, a failure, or the cumulative goal being reached), update only the
process-AC's progress note in place via ` 工单 API（见 TERMINOLOGY） ` (per the
` issue-checklist-sync` L1 rule § Automated sync — the poller owns the CI row;
the checklist annotation remains manual). Do NOT wait for Phase 5.6: a
2026-09-25 00:09:37 +08:00
transition left unsynced for tens of minutes is exactly the staleness [TT-1689]
2026-09-15 08:41:51 +08:00
targets. Skip if no source issue exists.
---
<!-- section:phase-6 -->
## Phase 6 — Approval
Present the verification result to the user and obtain approval via the
` question` tool, passing ` stage: "verify"`:
` ``
[Iteration {N} Verification: {PASS | FAIL}]
DoD: {passed}/{total} passed, {failed} failed
## Failed items:
| REQ ID | Criterion | Gap |
|--------|-----------|-----|
| REQ-NF-005 | Login P99 < 200ms | 312ms (+56%) |
## Tech Debt (Gitea issues created):
| TD ID | Issue | Severity | Description |
|-------|-------|----------|-------------|
| TD-NNN | #NNNN | MEDIUM | ... |
## Baseline Failures (Gitea issues created):
| BF ID | Issue | Severity | Test |
|-------|-------|----------|------|
| BF-NNN | #NNNN | MEDIUM | ` file::test-name` |
## Flaky Tests (Gitea issues created):
| FT ID | Issue | Severity | Test |
|-------|-------|----------|------|
| FT-NNN | #NNNN | MEDIUM | ` file::test-name` |
→ If FAIL: route to Developer for fixes? (yes / no)
→ If PASS: iteration complete. {N} tech-debt (labeled ` tech-debt`), {M} baseline-failure (labeled ` baseline-failure`), and {K} flaky-test (labeled ` flaky-test`) issues created. Start next iteration? (yes / no)
` ``
The ` question` tool auto-approves per ` core/rules/auto-approve.md` (stage ` "verify"`).
Do NOT advance without approval (auto or explicit).
---
## Phase 6.5 — Commit Gate (mandatory after PASS)
After verification PASS, confirm that git commits exist for the iteration
before declaring Done. Verification PASS without committed code is a process
gap — the feature exists only as uncommitted working tree changes.
### Check
` ``bash
git log <base-branch>..HEAD --oneline --no-merges
` ``
If zero commits exist on the current branch (all work uncommitted), ask via the
` question` tool, passing ` stage: "verify"`:
` ``
⚠️ Verification PASS but 0 commits found on this branch.
The iteration code must be committed before Done can be declared.
→ Commit the work with per-iteration granularity now? (yes / no)
` ``
The ` question` tool auto-approves per ` core/rules/auto-approve.md` (stage ` "verify"`).
If the user confirms, invoke the commit workflow per
` core/skills/implement/SKILL.md` Phase 4.5 (iteration completion commit).
### Gate Rule
| Condition | Verdict | Action |
| --------------------------- | -------- | ----------------------- |
| Commits exist for this iter | ✅ PASS | Proceed to Done |
| No commits | ❌ BLOCK | Must commit before Done |
An iteration is NOT Done until all code is committed in git history.
After the commit gate passes, move the source issue to the ` done` column on
the Pipeline Stages board per ` _shared/gitea-write-patterns.md` Pattern 7.5.
Skip if no source issue exists. ` done` is a stage column marker; issue
closing follows the lifecycle per ` issue-checklist-sync.md` 归档动作.
To notify workflow completion, call the ` signal_stage_done` tool.
---
<!-- section:dag-branch -->
2026-09-25 00:09:37 +08:00
## DAG branch (milestone + task modes) — see ` reference/dag-branch.md`
2026-09-15 08:41:51 +08:00
2026-09-25 00:09:37 +08:00
> This branch (milestone mode / task mode / no-milestone Epic gate) lives in
> ` reference/dag-branch.md`, read it on-demand when the Epic is DAG-shaped:
> frozen DAG at ` {epic-slug}/dag` + ` task_route.keep_gates` includes ` verify`.
> Legacy iteration verify (the sections above) remains authoritative for
> non-DAG iterations. Spec: ` dag-pipeline/spec-05` §5.
2026-09-15 08:41:51 +08:00
## References
- ` core/checklists/verification.md` — Verification self-check checklist
- ` core/skills/implement/SKILL.md` — Implementation (precedes verification)
- ` core/skills/review-code/SKILL.md` — Code review (precedes verification)
- ` core/skills/browser-debug/SKILL.md` — Interactive browser evidence capture (use for UI/E2E DoD entries; save screenshots as Gitea wiki pages under ` {slug}/verify/evidence/{name}` using ` wiki 读写 API（见 TERMINOLOGY） ` — replaces the deprecated ` .artifacts/{slug}/verify/evidence/` directory)
- ` core/rules/` and L2 wiki pages — Engineering conventions (test commands, typecheck; style-guide, effect-rules, database conventions per the "L2 on-demand reference" section of AGENTS.md)
- ISO/IEC/IEEE 29119:2022 — Software testing
