octopus-workflow/core/rules/issue-checklist-sync.md

> Core 中立版（Increment 4 改写）。术语对照见 core/adapters/TERMINOLOGY.md；本组织实例表述见 dogfood 对应文件。

## Issue Checklist Sync (mandatory, progressive)

The source issue's checklist is the **stakeholder-facing progress tracker**.
It MUST be kept in sync with actual work state at every pipeline milestone —
not just at close time. Stakeholders should be able to open the issue at any
point and see exactly what is done, in progress, and deferred.

### Sync points (progressive)

| When | Who | What |
|------|-----|------|
| After the DAG artifact is frozen (`review-dag` PASS + freeze confirmation per `analyze-dag/SKILL.md` §Output & Lifecycle step 2, [org-internal #3379]) | Aggregator agent | Convert the source Epic's draft acceptance criteria into a formal checklist; annotate requirement-covered items `_(DAG frozen: {epic-slug}/dag v1)_` |
| After each iteration commit (`implement` Phase 4.5) | Developer | Check off items delivered by this iteration |
| After a PR is created | Developer | Append a `## 当前状态` live-status section (or update it) with PR number + mergeable; in an Epic task list, append the PR reference to the corresponding row |
| After code review converges (`review-code` PASS, Phase E) | Orchestrator | Check off review-related items; annotate `_(reviewed: round N PASS)_`; update the `## 当前状态` review row; label the PR `ready-to-merge` — keep-mergeable automation takes over (hand-written keep-mergeable commits are retired) |
| On CI key state transitions (first green / failure / cumulative goal reached) | Verifier or Developer | Update the process-type AC (e.g. "N consecutive green runs") progress note in the issue; record the run number |
| At `verify` Phase 5.6 (final sweep before PASS) / issue close | Closing agent (Verifier on the primary path; otherwise the last role that closes the issue) | Final sweep — every remaining item gets annotated; **archive-at-close**: fold `## 当前状态`, then mark the `## 工件索引` comment archived per the artifact-index-guards rule guard #3 (see「归档动作」below) |

> Historical ([org-internal #3072] phase 3): the requirements/design/plan exit sync points
> were archived with their skills (detail: Tier-2 reference page
> `rules/issue-checklist-sync-detail`, reachable via the ticket backend).

Between sync points the checklist stays as-is. **PR / review / CI
transitions** MUST also be visible via the live status note below — the
checklist is not the only carrier.

### Live status note (`## 当前状态`)

For flows with externally visible transitions between skill exits —
standalone bugfix, incident response, long-running reviews — maintain a short
live status table near the top of the issue body, updated in place via the
ticket-backend issue-update API at the transition moment (closes the
stale-issue gap [org-internal #1668]/[org-internal #1689]]).

All roles use the literal heading `## 当前状态` (no suffix). If an issue carries
a legacy variant (e.g. `## 当前状态 (live)` from [org-internal #1668]), normalize it to
`## 当前状态` at the first transition touched. Example table + legacy-variant
list: Tier-2 reference page `rules/issue-checklist-sync-detail`, reachable
via the ticket backend.

Rules:

- One row per externally visible transition. Skill-exit sync points are
  surfaced by checklist annotations alone — do NOT add live-status rows for
  them. PR / review / CI transitions carry BOTH a checklist annotation AND
  a live-status row.
- **Stage rows live on the board, not here**: pipeline stage transitions are
  represented by the Pipeline Stages board column (shared write-patterns
  Pattern 7.5), NOT by `## 当前状态` rows. Keep only the
  status-sync-automated rows (PR / 代码评审 / CI) and non-stage
  blockers/deferrals.
- Update in place (same section heading `## 当前状态`), never append a second copy.
- Optional for quiet pipeline flows; **MANDATORY for incident-response and
  standalone-bugfix flows** (long windows without skill exits).
- At verify PASS / issue close, fold the table's content into checklist
  annotations and remove the section (see the「归档动作」section below).

### Automated sync ([org-internal #1833], timer-polled since [org-internal #2813])

PR / review / CI status-row transitions are automated by the `status-sync`
poller (deployed as a host timer, every 5 min; event sources + latency table
on the Tier-2 reference page `rules/issue-checklist-sync-detail`, reachable
via the ticket backend). Roles do NOT hand-write those three row types. A PR
body may carry several close refs (batch PRs, [org-internal #3731]
`land-batch`): rows fan out to EVERY referenced issue
(`parseClosesFixesWide` — [org-internal #3867], merged 2026-08-31) — Chinese 关闭/修复 refs
drive rows too, even though the ticket backend never auto-closes those
keywords. The remaining sync points (checklist annotations at skill exits,
`## 当前状态` creation, deferral/pending marking, section fold-at-close) are
still manual (content judgment, not event detection). Fallback for poller
outages / manual replay: the `status-sync` manual dispatch
(`issue`/`row`/`value`) — the row-write engine is a no-op when the section
or row is absent, never creates or corrupts them; poller failures file a
deduplicated `[status-sync-cron]` issue.

### Standalone bugfix / incident flows

Pipeline mode has natural sync points at skill exits; standalone bugfix and
incident flows do NOT — the only boundaries are commit → PR → review → CI →
merge, and EACH is a sync point with the same annotations as the progressive
table above (full table: Tier-2 reference page
`rules/issue-checklist-sync-detail`, reachable via the ticket backend): fix
commit → tick fix-delivered ACs `_(commit {sha}: file)_`; PR → open/update
`## 当前状态`; review convergence → tick review ACs + review row; CI
transitions → process-AC progress with run number; verify PASS / close →
final sweep, fold `## 当前状态`, archive per「归档动作」.

### DAG-routed tickets — node checklist variant

For tickets routed through the DAG pipeline (see workflow-routing rule
§"DAG 路由 (v2)"), the task-node checklist has a fixed shape (spec-08
§1/§2/§3):

- **Task tickets (nodes) use a fixed 5-row checklist** + an optional 6th row:
  验收标准 / 依赖就绪 / PR / 评审(review-code) / CI — **fixed 5 rows, fixed
  order, no free additions**. The `verify里程碑` row exists ONLY when the node
  fans into a milestone.
- **Row 6 close-time semantics**: if at ticket close the milestone is not yet
  green, keep `- [ ]` + `_(Pending: M-01 未 green)_` — mapped to **Pending**, not
  STALE, so it satisfies the Iron Law (no stale items at close). After milestone
  verify PASS the aggregator agent flips it to `- [x]` in place.
- **Epic aggregator `## DAG 状态` vs `## 当前状态`**: `## DAG 状态` is the
  node-status aggregator table (one row per DAG node — never carries ARCHIVE);
  `## 当前状态` carries only PR / 评审 / CI rows (no stage rows).
- **Archive rule unchanged**: the archive marker stays ONLY on the `## 工件索引`
  comment (single-comment invariant). The body aggregator table is kept as a
  historical snapshot at close and does NOT carry ARCHIVE.

### Kind/MVP tickets — exemption ([org-internal #3061])

`Kind/MVP` tickets run the interactive no-pipeline mode: no stage exits →
**nothing to sync**, no `## 当前状态` section (no PR/review/CI rows until
graduation). The body itself is the living document: `## 决策日志` is
append-only (superseded decisions struck through, never edited); `## Debt
Register` rows update in place. On graduation (relabel `Kind/Feature`) normal
sync rules resume from the DAG route; the decision log stays as backfill input.

### Annotation format

- **Done** → `- [x]` + parenthetical evidence: `_(PR #NNN: file/component)_`
  or `_(commit {sha}: file)_` if no PR yet.
- **Deferred** → keep `- [ ]` + `_(Deferred: TD-XXX <reason>)_`.
- **Pending** → keep `- [ ]` + `_(Pending: <blocker>)_`.

### How to sync (each point)

Find the source issue (`Closes #N` / `Fixes #N` in the PR body or commit
messages, `## 父级 / Parent` / roadmap chunk mapping, or the issue the user
referenced; none exists → skip). Fetch the body, map each `- [ ]` item
**relevant to this sync point** to evidence (`- [x]` + `_(PR #NNN: …)_` /
`_(commit {sha}: file)_`), deferral, or pending — leave out-of-scope items
untouched for a later point — and update in place, preserving all
non-checklist content. PR / review / CI transitions ALSO go into the
`## 当前状态` live-status section.

### 归档动作（issue 关闭 = 归档）

**生命周期 = 工单生命周期**（[org-internal #1929]）：文档生命周期与源 issue 绑定 —— verify PASS → issue 关闭 = 归档。Tier-2 工件库无独立生命周期。

归档是 **显式动作**，由关闭 issue 的 agent 执行：主路径为 Verifier 在 `verify` Phase 5.6；路径跳过 verify 时（audit-only、文档类、standalone/bugfix）由关闭 issue 的 role 代为执行。无论哪个 actor，均遵循 artifact-index-guards 规则 guard #3（机制以共享 write-patterns Pattern 10 为准）。动作序列：

1. **Checklist 终扫**（Phase 5.6 既有步骤 / closing agent 补执行）：每个 `- [ ]` 项都被注解（done / deferred / pending）。
2. **Fold `## 当前状态`**（Phase 5.6 既有步骤 / closing agent 补执行）：表格内容折入 checklist 注解后移除该节。
3. **标记 `## 工件索引` 归档**：按共享 write-patterns Pattern 10 Archive-at-close 原位 edit（机制以 Pattern 10 为准）。横幅日期以实际关闭日为准。
4. **关闭 issue**：PR body 的 `Closes #N` 在 merge 时自动关闭；无 PR 的流程由 **关闭 issue 的 agent** 执行工单后端的 issue-close API 完成闭环。

约束（[org-internal #1928] 设计约束；机制细节以共享 write-patterns Pattern 10 Archive-at-close 为准，此处不重复）：

- **L 级大件（>~300 行）留 Tier-2 工件库不删除** —— 页面与位置列 URL 保持不动（稳定 URL 供历史与共享契约引用）。
- **索引/状态/归档判定全部收敛到 issue** —— Tier-2 工件库无独立生命周期；归档标记只落在 `## 工件索引` 评论。
- 归档标记可逆（原位 edit）：PR 被拒 / issue 重开时恢复行级 重读 即可。

### Iron Law

NO ISSUE MAY BE CLOSED WITH STALE CHECKLIST ITEMS. If a checklist item
cannot be mapped to evidence or deferral at verify time, the iteration is
NOT done.