octopus-workflow/core/rules/issue-cross-linking.md

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

Issue Cross-Linking (mandatory)

Traceability flows in two directions. Both MUST be maintained so a reviewer can start at any node — an issue or a Tier-2 artifact-library page — and navigate to every related artifact without asking.

Issue ↔ issue (parent/child groups)

When creating a group of related issues — an Epic with phase/P-level sub-tasks, a roadmap decomposed into chunk tickets, a bug with a regression-test follow-up, or any parent/child breakdown — the issues MUST be cross-linked:

• Parent issue: after creating all children, update the parent body so its task list references each child by #<number> (e.g. - [ ] [org-internal #1556] — [P0] ...). The ticket backend renders these as clickable links and auto-generates a back-reference on each child's timeline.
• Child issue: its body MUST contain a ## 父级 / Parent section referencing the parent by #<number>.
• Never create a group of issues that is only one-way linked or not linked at all. The parent task list is the single navigation hub.

Issue ↔ Tier-2 artifact (pipeline traceability)

When a production skill (analyze-dag, publishing the {epic-slug}/dag artifact; historically the pre-[org-internal #3072] producer skills) publishes an artifact to the Tier-2 artifact library, the link to the source issue is only half-built — the library's index page links forward to the issue, but the issue has no link back to the library. A stakeholder opening the issue sees no path to the pipeline artifacts — the traceability chain is broken.

After publishing, the skill MUST complete the reverse link on the source issue:

• Post / update the "## 工件索引" comment (工件索引协议, per the shared write-patterns doc Pattern 10): a single in-place-edited comment (via the ticket-backend comment-create, then comment-edit API; NEVER post a duplicate; legacy prefix "## Pipeline 工件追踪表" is upgraded in place). One row per artifact: {工件 | 类型 | 版本 | 位置 | 重读} where 重读 ∈ {CORE, ON-DEMAND, ARCHIVE}.
• The CORE rows ARE the compaction re-read set — after compact, recovery reads the 工件索引 comment and fetches every CORE row's 位置 (shared read-patterns doc Pattern 6), instead of hard-coded library paths. Skills' re-read instructions therefore point at the index.
• Archive-at-close（归档动作, [org-internal #1929]/[org-internal #1928]） — issue 关闭即归档；Tier-2 工件库无独立 生命周期。ARCHIVE is not just a per-row re-read priority: at issue close the whole index is marked archived by the closing agent (Verifier at verify Phase 5.6 on the primary path; otherwise the Orchestrator / last-role that closes the issue) via in-place edit. The mechanism (banner + every row's 重读 → ARCHIVE, single-comment invariant, rows/位置 URLs never deleted, L-level library artifacts keep stable URLs) is defined once in the shared write-patterns doc Pattern 10 Archive-at-close — reference it, do not restate. Sequence and actor: the issue-checklist-sync rule § 归档动作.
• Sync the issue's checklist per the issue-checklist-sync rule for the matching exit point (live: the DAG-freeze sync point after review-dag PASS; the legacy requirements-exit / design-exit / plan-exit points were retired with their skills, [org-internal #3072] phase 3).
• Skip if no source issue exists (no Closes #N / Fixes #N / roadmap chunk mapping ties this slug to an issue).

Size/S & Size/M exception ([org-internal #1832]) — RETIRED (2026-08-21, [org-internal #3072] phase 3): retired with the legacy producer skills and the sizing: block. Historical indexes pointing at in-issue artifacts (位置 = #comment-{id}) remain valid, readable locations; new artifacts publish where their live skill/route puts them (DAG: library page {epic-slug}/dag etc.; MVP: ticket body).

Authoritative implementation patterns: shared write-patterns doc Pattern 3 (issue↔issue) and Pattern 10 (issue↔artifact index) under the skills' shared-artifacts directory.