> tier-dependent requirements/design/plan artifact-existence checks and the
> design-space / iteration-plan review-convergence checks that used to head
> this list belonged to the archived legacy pipeline (`<instance-root>/archive/`).
> Live input modes: DAG task mode (node spec from the frozen
> `{epic-slug}/dag` copy — see the DAG-mode input path above; convergence
> precondition = `octopus review status --stage review-dag` shows `success`)
> and standalone modes (bugfix / refactor / port — the request itself is the
> spec). Historical req/design/plan pages stay readable via
> `_shared/gitea-read-patterns.md`.
- [ ] Work item is specified (DAG node ticket `{node-id}`, or a clear task
description in standalone modes).
- [ ]`core/checklists/implementation.md` is accessible.
- [ ]`slug` matches the run's slug (DAG: `{epic-slug}`).
- [ ] 跨阶段门控清单: `core/checklists/pipeline-gate.md` is accessible and
its DAG 路由变体 section has been confirmed item by item. Specifically:
the frozen DAG copy exists and the single gate has converged; the
node's cross-session upstream dependencies are at terminal state
(`ready`). If any dependency is not complete → abort, listing the
blocked nodes.
**If any precondition is unmet, abort and inform the user.** Refer to
`core/checklists/pipeline-gate.md` for the complete gate checklist. List
every missing artifact, every un-converged review, and every blocked dependency
explicitly so the user knows exactly what upstream work remains before
implementation can begin. Refer to the Recovery Protocol in
`core/checklists/pipeline-gate.md` to determine the recovery action for
each missing item.
#### Work-item selection
When the user requests implementation without specifying a work item, resolve
the work-item list from the frozen DAG copy: the ready/pending task nodes in
`{epic-slug}/dag` (via `wiki 读写 API（见 TERMINOLOGY）`), cross-checked against the
node tickets on the Epic's `## DAG 状态` table. (Legacy tier-based resolution
via `{slug}/04-plan-04-iteration-assignment` was archived 2026-08-21,
[org-internal #3072] phase 3.) Present the current ready nodes for selection:
```
Current iteration: Iteration {N}: {Goal}
Available work items:
| Work Item | Description | Complexity | Status |
|-----------|-------------|------------|--------|
| WI-001 | ... | 3 | PENDING |
| WI-002 | ... | 2 | PENDING |
→ Which work item should be implemented?
```
---
#### Phase 1 — Parse Context
> **Pipeline stage**: if the source issue exists, move it to the `implement`
> 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 to build a complete implementation context.
Resolve inputs per the DAG-route read map (Preconditions above); standalone
modes read the request/bug report instead:
1.**Work item** — the node spec in `{epic-slug}/dag` (+ the
`{epic-slug}/dag-nodes/{node-id}` subpage when detail is sunk) and the
node ticket's issue body:
- Node id, title, complexity (`size_attrs`).
- Requirements covered (`req_refs`).
- Component(s) involved (node component field).
2.**Acceptance criteria** — the node `acceptance_criteria` in
`{epic-slug}/dag` (+ sunk subpages) and the node ticket's issue body:
- Every falsifiable AC (`AC-{n}`) and `NFR:` entry.
- The declared 测试用例 ID (`test_id`) for each criterion — these drive the
Red → Green test-first order in Phase 3 and are the handshake with `verify`
(DOD-1.6).
3.**Design context** — the node spec + the node's cross-session edge
contracts in the frozen DAG copy (design detail is folded into node AC +
contracts; there is no separate design page). Historical
`{slug}/03-design-*` pages from legacy runs stay readable.
4.**Existing codebase** — use `glob` and `grep` to locate:
- Existing files in the component's directory.
- Existing tests.
- Existing type definitions, schemas, configuration files the work item
touches.
**Output**: internal only. The Developer MUST have read every referenced
design file before writing a single line of code.
---
#### Phase 2 — Plan Implementation
Before writing code, produce a brief implementation plan:
```markdown
## Implementation Plan: {WI-ID}
**Work item**: {description}
**Files to create**:
-`path/to/new/file.ts` — {purpose}
**Files to modify**:
-`path/to/existing/file.ts` — {what changes, why}
**Design compliance**:
- Component: {COMP-XXX} from {design-file}
- Interface: {iface-name} from {design-file}
- Data entity: {entity-name} from {design-file}
**Acceptance criteria to satisfy**:
- [ ] {criterion 1}
- [ ] {criterion 2}
```
**Rules**:
- If the implementation plan reveals that the work item touches > 3 files,
pause and ask: "This work item spans {N} files. Is the scope correct, or
should it be split?" The Builder (or user) MUST split it into smaller
work items each touching ≤ 3 files before proceeding.
- If the work item requires a file that doesn't map to any design component,
flag a design gap and abort. Do NOT invent design decisions.
Present the plan to the user:
```
Implementation plan for {WI-ID}:
- {N} files to create, {M} files to modify
- {K} acceptance criteria
→ Proceed? (yes / no / revise)
```
---
#### Phase 3 — Implement
Write code following these rules:
##### Design Discipline
- Component interfaces, method signatures, and return types MUST match the
design document exactly.
- Data model fields, types, and relationships MUST match the data design.
- API endpoints, request/response schemas, and status codes MUST match the
interface design.
- If a design decision proves impossible in practice, stop and report the gap
to the Builder. Do NOT silently deviate.
##### Code Quality
- Follow existing project conventions (read neighbor files first to
understand patterns).
- Use existing libraries and utilities already in the codebase — do not
introduce new dependencies without explicit justification.
- Keep functions small and single-purpose — but per `rules/style-guide`, do NOT
preemptively extract single-use helpers; inline at the call site unless the
helper is reused, hides a genuinely complex boundary, or has a clear
independent name that improves the caller.
- Handle errors at the appropriate layer (matching the design's error
handling strategy).
- Write self-documenting code; add comments only for genuinely non-obvious
logic.
- Document all new/modified public APIs inline (JSDoc/TSDoc/pydoc/etc.)
with parameter descriptions, return types, and thrown errors.
- If the project has an API documentation file (e.g. OpenAPI spec, API.md),
update it to reflect the new endpoints, schemas, or behavior changes.
##### Test Discipline
- **Test-first (Red → Green) for declared test_ids.** For every acceptance
criterion (node AC in `{epic-slug}/dag`, whose `test_id` mapping is declared
inline; historically the `04-plan-05-acceptance-criteria` table) that
declares a `test_id`, write that test FIRST and confirm it fails for the
intended reason (Red) before writing the implementation that satisfies it
(Green). The test's `file-path :: test-name` MUST match the declared
`test_id` exactly — this is the implement-side handshake with `verify`
(DOD-1.6). A `test_id` marked `MANUAL` or `BENCH:<script>` is implemented
per its method and is exempt from the Red step. If a test already passes
against existing code (the behavior is already present), note it in the
Phase 5 report rather than forcing an artificial failure.
- Write tests that verify the acceptance criteria.
- Tests must be independent (no shared mutable state).
- Test edge cases identified in the acceptance criteria.
- Test failure paths that the design specifies.
##### Incremental Commitments
- Implement in dependency order within the work item: shared types first,
then data access, then business logic, then API handlers.
- After each coherent unit, run typecheck to catch errors early.
---
#### Common Rationalizations
Implementation fails far more often from **pressure** than from ignorance — the
Developer knows the rules and rationalizes skipping them under context or time
pressure. These are the excuses that precede every review blocker and silent
defect. If you catch yourself thinking any row's "Excuse", stop: the "Reality"
column is the exact rule you are about to break, and breaking it is what turns
a one-pass implementation into a multi-round review.
| Excuse | Reality (the rule being broken) |
|--------|---------------------------------|
| "Design says X, but Y is simpler/better" | Silent deviation is a hidden design gap. Phase 3 Design Discipline: stop and report to the Builder — never silently deviate. |
| "Small change, a test is overkill" | A one-line edit can break a contract. Every acceptance criterion maps to ≥1 test (Phase 4 Brownfield check). 30 seconds now vs. a review blocker later. |
| "I'll write tests after it works" | Tests-after verify what you built, not what was required — you test your own bias, not the spec. |
| "Typecheck passed, lint is cosmetic" | Lint is a Phase 4 gate, not optional polish. Failing lint is an automatic review blocker. |
| "Self-check passed, I'll trust it" | Rubber-stamping misses the MAJORs the formal review will catch. Rule: if YOU can find a MAJOR, fix it now — the first review should never discover what you could have. |
| "This neighbor looks buggy, I'll fix it too" | Scope creep. Log it as an observation in the report; do not fix unrelated code (Greenfield/Brownfield rule). |
| "Spans 5 files but it's one logical change" | The ≤3-files rule is structural, not aesthetic. Split the work item via the Builder (Phase 2 rule). |
| "Design is ambiguous here, I'll pick the obvious option" | Inventing a design decision is a Phase 2 abort condition. Flag the gap; do not guess. |
| "Already manually verified it works" | Manual ≠ systematic — no record, can't re-run, can't bisect. `bun run test:changed` is the evidence the report demands. |
| "Report is busywork, the diff speaks for itself" | No report → review-code cannot trace AC→test. Phase 5 is the handoff contract; skip it and the review stalls. |
| "X× improvement — assumed, no measurement" | Quick-measure before it becomes an AC. Unverified assumptions in ACs waste framing cost ([org-internal #1932]: YAML token density assumed 2-3×, measured 0.95 — hypothesis rejected by data). |
---
#### Phase 4 — Self-Check
After writing all code, run the project's verification commands:
1.**Typecheck**: `bun typecheck` (or project-equivalent). Fix all type errors.
2.**Lint**: `bun oxlint --deny-warnings` (repo root — the review-code
mechanical gate's canonical lint invocation; `bun lint` is the package-script
alias). Fix all lint errors.
3.**Tests**: `bun run test:changed` (or project-equivalent). All affected tests must pass.
4.**Post-deletion cleanup** (mandatory when any code was removed): If files or code blocks were deleted (dead code, test cleanup, refactored-out modules), re-run `bun oxlint --deny-warnings` specifically to catch orphaned imports and unused variables — these are the most common post-deletion regressions. Re-run `bun typecheck` to catch orphaned type references to deleted modules.
Then self-check against `core/checklists/implementation.md`:
- Verify every checklist item marked PRE (pre-implementation) was satisfied
before coding.
- Verify every checklist item marked POST (post-implementation) is satisfied
now.
- For any failed checklist item, fix the code before reporting.
##### Brownfield Self-Check (additional)
For brownfield work items, additionally:
1.**Design spec cross-check**: Re-read the node's cross-session edge
contracts in the frozen DAG copy (historically the design's interface
design section, `03-design-04-interface-design`). Verify every interface
