Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)

2026-09-15 08:41:51 +08:00
commit bb35e661b2
114 changed files with 20240 additions and 0 deletions
@@ -0,0 +1,592 @@
+> Extracted from implement/SKILL.md (Mode: implement) — moved verbatim 2026-08-25, ticket [org-internal #3381].
+
+### Mode: implement (default)
+
+The standard implementation workflow for work items from an approved
+iteration plan. Implement a single work item, guided by the approved design,
+and self-verify before passing to code review.
+
+#### Pre-flight
+
+The pre-flight self-check prompt format ([org-internal #2599]), prepended to the Developer
+sub-agent's task prompt when `routes.{Kind}.preflight` is non-empty:
+
+```
+Pre-flight self-check (evidence-based, from retrospective — verify each
+BEFORE writing code; if one is already satisfied, note why in impl-notes):
+1. {item} (evidence: {evidence})
+2. ...
+```
+
+#### Process Overview
+
+Every diamond below is a gate agents rationalize skipping. None are optional.
+
+```dot
+digraph implement {
+    rankdir=TB;
+    node [shape=box, fontname="Helvetica"];
+
+    pre      [shape=diamond, label="Preconditions\n(artifacts + reviews\nconverged)?"];
+    abort    [label="ABORT: list every\nmissing item"];
+    p1       [label="Phase 1: Parse Context"];
+    p2       [label="Phase 2: Plan\n(≤3 files per WI)"];
+    scope    [shape=diamond, label="Scope ≤3 files\nAND maps to a\ndesign component?"];
+    gap      [label="Flag design gap,\nDO NOT invent decisions"];
+    p3       [label="Phase 3: Implement\n(design-exact, tests cover AC)"];
+    p4       [label="Phase 4: Self-Check\n(typecheck + lint +\ntest:changed + review checklist)"];
+    clean    [shape=diamond, label="0 BLOCKERs\nand 0 MAJORs?"];
+    p5       [label="Phase 5: Report\n(AC → test traceability)"];
+    p6       [shape=doublecircle, label="Phase 6: Handoff\nto review-code"];
+
+    pre   -> abort [label="no"];
+    pre   -> p1    [label="yes"];
+    p1    -> p2;
+    p2    -> scope;
+    scope -> gap   [label="no"];
+    scope -> p3    [label="yes"];
+    p3    -> p4;
+    p4    -> clean;
+    clean -> p4    [label="no: fix + re-run"];
+    clean -> p5    [label="yes"];
+    p5    -> p6;
+}
+```
+
+#### Tester focus for implement
+
+The Tester role in implement writes **boundary + contract tests**:
+
+- **Contract tests** — for every public API signature in `impl-notes.md`,
+  verify the documented inputs/outputs, error paths, and side effects.
+  Each acceptance criterion (node `acceptance_criteria` in `{epic-slug}/dag`;
+  historically `04-plan-05-acceptance-criteria`) MUST map to at least one
+  test.
+- **Boundary tests** — empty values, malformed input, permission
+  boundaries, concurrency edges, and the edge cases the node spec's decision
+  tables / state machines imply.
+- **Failure-path tests** — every error scenario the node's cross-session
+  edge contracts (historically the interface design,
+  `03-design-04-interface-design`) specify.
+
+The Developer's Phase 4 self-check (`bun run test:changed` to green) covers
+the happy path and existing tests; the Tester's job is the cases the
+Developer is structurally biased to miss.
+
+#### Preconditions
+
+> **Publish target (tiered targeting retired, [org-internal #3072] phase 3)**: the
+> `Size/*`-tiered publish rule (`rules/workflow-routing.md` §"Publish target
+> by Size/* tier — RETIRED") was retired with the legacy producer skills.
+> Artifacts publish where the live mode puts them: DAG task mode → node spec
+> in the frozen `{epic-slug}/dag` copy (see the DAG-mode input path below);
+> standalone bugfix → `{slug}/bugfix-report` + issue body per bugfix Phase 5.
+> Legacy tiered locations (`{slug}/02-03-req-design`, `{slug}/04-plan-*`, …)
+> stay readable for historical runs via `_shared/gitea-read-patterns.md`.
+
+> **DAG-mode input path** (DAG ticket pipeline — `Kind/Epic` / `Kind/Feature`
+> DAG parent, routes-table direct):
+> DAG-routed tickets **ignore `Size/*`** (`core/skills/analyze-dag/SKILL.md`).
+> When the ticket routes through the DAG pipeline, the tiered Preconditions
+> below are replaced by the node spec: the work item and its acceptance
+> criteria resolve from the **frozen DAG copy** wiki page `{epic-slug}/dag`
+> (and the `{epic-slug}/dag-nodes/{node-id}` subpages when AC detail is sunk)
+> plus the node ticket's issue body — there is no `{slug}/04-plan-*` page and
+> no `Size/*`-tiered req/design page. The design-space + iteration-plan review
+> convergence preconditions are replaced by the **review-dag single-gate
+> convergence**: `octopus review status --stage review-dag` must show state
+> `success` before the node is implemented.
+
+> **DAG-route read map** (applies to Phase 1 read inputs and the Phase 3/4
+> artifact references below — mirror `verify/SKILL.md`'s DAG branch): when
+> DAG-routed, resolve each legacy tiered artifact reference (any mention below
+> of `{slug}/04-plan-*` / `{slug}/03-design-*` pages) from the frozen
+> DAG copy instead:
+>
+> - Work item — `{slug}/04-plan-04-iteration-assignment` / issue body → the
+>   node spec in `{epic-slug}/dag` + the node ticket's issue body.
+> - Acceptance criteria — `{slug}/04-plan-05-acceptance-criteria` / issue body
+>   → the node `acceptance_criteria` in `{epic-slug}/dag` (+
+>   `{epic-slug}/dag-nodes/{node-id}` subpages when AC detail is sunk) + the
+>   node ticket's issue body.
+> - `test_id` (測試用例 ID) declared in `04-plan-05-acceptance-criteria` → the
+>   `test_id` declared on the node AC in `{epic-slug}/dag`.
+> - Design sections — `{slug}/03-design-**` / `{slug}/02-03-req-design` → the
+>   node spec + cross-session edge contracts in the frozen DAG copy (design
+>   detail is folded into node AC + contracts; there is no `{slug}/03-design-*`
+>   page).
+> - Interface design — `03-design-04-interface-design` → the node's
+>   cross-session edge contracts in `{epic-slug}/dag`.
+> - Component mapping — `{slug}/03-design-08-traceability` → the node
+>   `req_refs` + component field in `{epic-slug}/dag`.
+>
+> At Phase 6 handoff, pass `mode: "dag-task"` to review-code (its DAG Task
+> Mode keys off the same frozen-DAG-copy detection).
+
+Before starting implementation, confirm:
+
+> **Legacy pipeline preconditions retired ([org-internal #3072] phase 3, 2026-08-21)**: the
+> 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
+   promise — method signatures, return types, output formats, error messages,
+   config field names, param descriptions — is satisfied exactly as specified.
+   Schema annotations MUST match actual code behavior.
+2. **Test coverage**: For each new function, method, or exported API added,
+   confirm at least one test exercises it. If `bun run test:changed` reports zero new
+   tests, add them before handoff.
+
+##### Review Readiness Self-Check (mandatory before handoff)
+
+Before submitting to code review, the Developer MUST self-attest against the
+code review checklist. This reduces round-trips by catching common defects
+before the first review submission. **The self-check must achieve 0 BLOCKERs
+and 0 MAJORs before handoff** — if the Developer can find a MAJOR issue during
+self-check, the formal reviewers will find it too.
+
+1. **Run the code review checklist**: Read `core/checklists/code-review.md`
+   and self-attest that the code likely passes, for each of its 10 dimensions
+   (COR, DGN, SEC, PERF, TST, STY, DBT, A11Y, DOC, TRC — the authoritative
+   dimension set lives in the checklist's section headers and
+   `review-code/reference/code-review-dimensions.md`; do NOT hand-maintain a
+   copy here).
+2. Record the self-attestation in the Phase 5 report under "Review Readiness"
+   as a pass/fail per dimension. Any FAIL dimension MUST be fixed before handoff.
+3. **Hard gate**: self-check MUST find 0 BLOCKERs and 0 MAJORs. If the
+   Developer finds even one MAJOR, fix it and re-run self-check before handoff.
+   The first formal code review should never discover issues the Developer
+   could have caught themselves.
+
+---
+
+#### Phase 4.5 — Iteration Completion Commit
+
+After ALL work items in the current iteration have been implemented and passed
+Self-Check (Phase 4), create a git commit BEFORE proceeding to the next
+iteration. This preserves per-iteration traceability and enables `git bisect`
+per iteration.
+
+##### Commit Rules
+
+1. Commit after the last WI of the iteration is done and self-checked.
+2. Commit message format: `[{chunk-id}][{iteration}] {summary}`.
+   - Example: `[chunk-resolution][iter-1] feat: add two-pass chain resolution engine`
+3. **Commit body is REQUIRED for non-trivial commits** (any commit touching > 1 file
+   or > 20 LOC). The body MUST contain:
+   - **What**: a 1-3 line summary of the changes (files + purpose), including
+     the work item ID (`WI-{NNN}`) the commit delivers — code-review TRC 10.1
+     requires the commit/PR description to carry the work item ID.
+   - **Why**: the design/requirement motivation (cite REQ-ID or ADR if applicable).
+   - **Evidence**: test names or verification commands run (e.g. `90 compaction
+     tests pass`).
+   - Subject-only commits are acceptable only for single-line fixes or doc tweaks.
+4. Include all source + test files from the iteration.
+5. After commit, proceed to Phase 4.6 (Issue Checklist Sync), then Phase 5
+   (Report) for the iteration, then start the next iteration's WIs.
+
+##### Multi-Iteration Workflow
+
+```
+Iteration 1 WIs → Self-Check → Commit [iter-1] → Checklist Sync → Code Review →
+Iteration 2 WIs → Self-Check → Commit [iter-2] → Checklist Sync → Code Review → Merge
+```
+
+---
+
+#### Phase 4.6 — Issue Checklist Sync (progressive)
+
+After committing the iteration, sync the source issue's checklist so
+stakeholders see progress in real time. This is mandated by the
+`issue-checklist-sync` L1 rule — follow its "How to sync (each point)"
+procedure (identify source issue → fetch body → map → update, preserving
+non-checklist content); this phase adds only the implement-specific annotation:
+
+- **Stage-specific row**: for each `- [ ]` item the iteration's work satisfies,
+  mark `- [x]` and append `_(commit {sha}: file/component)_` or
+  `_(PR #NNN: file)_`.
+- **Do NOT touch items outside this iteration's scope** — they will be caught
+  at a later sync point (next iteration, DAG-freeze aggregation sync, or
+  verify Phase 5.6). Only check off what this iteration actually delivered.
+
+This is a **progressive** sync: the checklist fills in incrementally as
+iterations complete, giving stakeholders a live view of progress without
+waiting for the final verify gate.
+
+#### Phase 4.7 — PR-Creation Sync
+
+The session pushes its branch and reports `status=done branch=<ref> verify=…
+risk=…`; the orchestrator admits the PR (serially, one open at a time) —
+workers never open PRs (TD-678/[org-internal #4425]; `uncoordinated` self-open only when
+the orchestrator is unreachable). Once that PR exists, update the source
+issue so stakeholders see the mergeable state without waiting for code
+review. Mandated by the `issue-checklist-sync` L1 rule; skip if no source
+issue exists.
+
+> PR shape per mode: default = one 1:1 PR per task (body carries the worker
+> report); batch-mode epics ([org-internal #3731], per-epic opt-in) = the orchestrator
+> composes ONE batch PR per iteration via the `land-batch` skill. This phase
+> then runs per member issue as usual (N times), each pointing at its PR
+> (batch: the single batch PR); the poller writes the PR/CI/review rows
+> against every member issue (multi-close-ref fan-out).
+
+1. Re-fetch the issue body via `工单 API（见 TERMINOLOGY）get`.
+2. **Ensure the `## 当前状态` live-status section exists** (create it if
+   absent — MANDATORY for incident / standalone-bugfix flows; for quiet
+   pipeline flows, create it only if it already exists, otherwise skip). The
+   `PR` row itself is written by the `status-sync` poller
+   (`.gitea/scripts/status-sync-poll.ts`), NOT this skill — do NOT manually
+   `工单 API（见 TERMINOLOGY）update` the PR / 代码评审 / CI rows (per
+   `issue-checklist-sync.md` § Automated sync).
+3. If this is an Epic task list, append the PR reference to the row that this
+   iteration's work corresponds to.
+4. Preserve all non-checklist content.
+5. **Never hand-sync main into the PR branch.** Keeping the PR mergeable is
+   the keep-mergeable workflow's job: once review converges the orchestrator
+   labels the PR `ready-to-merge` and the server-side keep-mergeable cron
+   (`.gitea/scripts/keep-mergeable.ts`, driven by
+   `script/keep-mergeable-cron.sh` under a systemd timer) fetches the PR head,
+   probes `merge-tree --write-tree`, and pushes a non-force `commit-tree` merge
+   into the head branch (the retired `POST /pulls/{n}/update-branch` API path
+   returned 405 on this instance — see AGENTS.md "PR keep-mergeable").
+   Hand-written `chore: merge origin/main (keep PR mergeable)` commits are
+   retired — each one re-triggered the full CI surface for near-zero re-tested
+   risk.
+
+> **Kanban column lifecycle**: automated (`工单 API（见 TERMINOLOGY）create` → Backlog,
+> `gitea_pull__create` → Review; no manual moves). Single shared reference:
+> `_shared/gitea-write-patterns.md` Pattern 7.5; column semantics: wiki
+> `kanban-lifecycle`.
+
+---
+
+#### Phase 5 — Report
+
+Produce an implementation report:
+
+```markdown
+## Implementation Report: {WI-ID}
+
+**Work item**: {description}
+**Iteration**: {iteration number}: {goal}
+
+### Files Changed
+
+| File               | Action   | Purpose        |
+| ------------------ | -------- | -------------- |
+| `path/to/file.ts`  | created  | {purpose}      |
+| `path/to/other.ts` | modified | {what changed} |
+
+### Acceptance Criteria
+
+| Criterion     | Status | Evidence                           |
+| ------------- | ------ | ---------------------------------- |
+| {criterion 1} | ✅     | {test name or manual verification} |
+| {criterion 2} | ✅     | {test name or manual verification} |
+
+### Verification Results
+
+- Typecheck: {pass / fail + error count}
+- Lint: {pass / fail + warning count}
+- Tests: {N} passed, {M} failed, {K} skipped
+
+### Design Deviations
+
+{list any intentional deviations from design with rationale, or "None"}
+
+### Open Items
+
+{anything incomplete with reason, or "None"}
+
+---
+
+**Handoff**: Ready for `core/skills/review-code/SKILL.md`
+```
+
+**Persist before returning ([org-internal #2847])**: the Developer MUST write the final
+report above to disk as its LAST action, BEFORE returning it —
+`<runs-root>/{slug}/workers/{chunk-id}-worker-{seq}.md` when the Tier 1
+run workspace exists, else `/tmp/octopus/{chunk-id}-worker-{seq}.md`
+(`{chunk-id}`/`{seq}` come from the dispatch prompt — see
+`../_shared/worker-report-persistence.md`). The persisted copy is the
+report of record; the task notification is a convenience copy. The same
+step applies to EVERY mode's report phase (bugfix Phase 5, refactor
+Phase 6, port report) — no worker return may exist only in the task
+notification.
+
+---
+
+#### Phase 6 — Handoff to Code Review
+
+Present the report to the user and signal readiness for review:
+
+```
+Implementation of {WI-ID} complete.
+- {N} files changed ({C} created, {M} modified)
+- {T} tests passing
+- All acceptance criteria satisfied
+- Typecheck + lint clean
+
+→ Run code review? (yes / no)
+```
+
+Do NOT mark the work item as complete until code review passes.
+
+To notify workflow completion, call the `signal_stage_done` tool.
+
+#### Legacy notes
+
+> **Publish target (tiered targeting retired, [org-internal #3072] phase 3)**: the
+> `Size/*`-tiered publish rule (`rules/workflow-routing.md` §"Publish target
+> by Size/* tier — RETIRED") was retired with the legacy producer skills.
+> Artifacts publish where the live mode puts them: DAG task mode → node spec
+> in the frozen `{epic-slug}/dag` copy (see the DAG-mode input path above);
+> standalone bugfix → `{slug}/bugfix-report` + issue body per bugfix Phase 5.
+> Legacy tiered locations (`{slug}/02-03-req-design`, `{slug}/04-plan-*`, …)
+> stay readable for historical runs via `_shared/gitea-read-patterns.md`.