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.