octopus-workflow/core/rules/two-tier-artifacts.md

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

## Two-Tier Artifact Storage (mandatory)

Agent-internal handoff (subagents sharing one worktree) and human-visible
traceability have different consumers, lifecycles, and costs. The harness
separates them into two tiers so internal handoff stops paying the Tier-2
tax (HTTP latency, write conflicts, auth, backend health) while
human-visible decisions stay in the system of record.

**Iron Law: an artifact's tier is decided by its CONSUMER and LIFECYCLE, not by
its format.** Format (json / md / artifact page / comment) follows the tier
decision, never drives it.

### Tier 1 — local structured (transient, intra-workflow)

- **Consumer**: subagents within one worktree (Producer / Reviewer /
  Synthesizer / Verifier) — never a human gate, never cross-worktree.
- **Lifecycle**: bounded to one run; one worktree; archived-at-close.
- **Visibility**: agent-internal; not human-gated.
- **Storage**: the run workspace `runs/{slug}/` — schema-validated local
  files; active runs gitignored, archive bundle committed at close.
- **Examples**: design detail dumps, plan item lists, raw review dimension
  findings, synthesis prompts, intermediate analysis.

### Tier 2 — ticket backend / git (stable, cross-worktree, human-visible)

- **Consumer**: humans (gate decisions), cross-worktree sessions, traceability.
- **Lifecycle**: outlives a run; cross-worktree stable; the system of
  record.
- **Visibility**: human-visible; authoritative.
- **Storage**: the ticket backend (issues, PRs, artifact pages, commit
  status) + git-committed artifacts.
- **Examples**: frozen inter-chunk contracts, issue status + checklist, PRs,
  review verdict + synthesis (the human gate), `## 工件索引` comment, commit
  status, the workflow branch.

### Decision rule (the 判据)

An artifact belongs to **Tier 1** if and only if ALL of:

1. consumed only within one worktree / one run, AND
2. not a human gate decision (no human reads it to approve/reject), AND
3. not referenced cross-worktree (e.g. a later chunk's frozen contract), AND
4. regenerable-or-archivable at close without losing a decision record.

If ANY condition fails → **Tier 2**. When in doubt, Tier 2: **the Tier-2
default载体 is decided by the ticket backend adapter** (参考实现见
core/adapters/ 的 adapter 层；本组织实例为 Gitea adapter, 术语对照见
core/adapters/TERMINOLOGY.md) — Tier 2 is the default system of record;
Tier 1 is an optimization an artifact opts INTO, not out of.

### Common classifications

Per-artifact table (review findings, prompt files, working drafts, draft/frozen
contracts, issue checklist, 工件索引, `index.json` …): Tier-2 reference page
`rules/two-tier-artifacts-detail` (reachable via the ticket backend); the
decision rule above classifies anything unlisted.

### Two indexes, parallel not replacement

- **Tier 1 `index.json`** (`runs/{slug}/index.json`) — the agent's
  compact-recovery entry; Tier 1 artifacts only.
- **Tier 2 `## 工件索引` comment** — the human-visible traceability hub:
  artifact-page/issue locations + 重读 priority.

Both are kept by the producing role but serve different consumers. Migrating a
skill's output to Tier 1 does NOT remove its Tier 2 row — it repoints 位置 at
the distillation.

### Archive-at-close

Closed by the **Verifier** at verify PASS (or the Orchestrator when no
verify). The archive step is the ONLY point active-run Tier 1 content enters
git history:

1. Generate the bundle [org-internal #3604]:
   the run-bundle generator script with `--slug {slug} [--ticket N] [--pr N]`
   — flips meta to "archived", hashes the workspace into the `sha256_16`
   manifest, writes `archive/{ticket}-{slug}.json`, validates.
2. Commit the bundle on the workflow branch (rides into main via `--no-ff`).
   Direct pushes to main stay blocked by branch protection [org-internal
   [org-internal #3604]]; do not bypass.
3. **归档前置校验** [org-internal #2727]: the generator validates by default
   (`--no-validate` must not reach a merge); red exit = fix before close.
   The L0 merge gate rejects non-compliant bundles at merge anyway.

   merge-gate 另做 **presence（存在性）检查**：PR body/commit 引用 `Closes #N`
   而 merge 树归档目录无 `meta.ticket.number=N` 的 bundle 时拦截（区别于
   schema 包的结构合规检查）。预期无 run 的关闭（文档/audit-only/MVP 晋级
   前/revert/ad-hoc/legacy reopen）贴 `gate-exempt/archive-presence`
   label——label 事件自动重跑 gate。归档前 PR 呈红是设计行为（fail-closed
   until archived）。**禁止以豁免 label 替代确实存在过的 run 的 bundle
   归档**。归档目录的 `.gitkeep` 是该检查的目录存在性不变式，不得删除。

4. Remove the `{active-slug}/` workspace. Direct `rm -rf` is L0-blocked —
   sanctioned exit: the post-merge worktree sync script with `--prune-runs`
   (syncs to the merge commit, prunes the run dir, clears stale-ahead false
   positives), then the session-worktree removal script.
5. Mark the Tier 2 `## 工件索引` archived per the issue-checklist-sync rule
   § 归档动作.

Tier 2 remains the decision record; the Tier 1 git archive is the
reproducibility trace — enough to reconstruct what a run produced.

### Compact interaction

`compact` never deletes local files: `index.json` survives compaction and is
the designated re-read entry — after `compact`, read `runs/{slug}/index.json`,
not conversation memory.

### Gate furlough（[org-internal #3607]）

强制门的唯一退出通道是 gate 台账（furlough ledger）的 furlough 条目
（测量证据 + reopen 条件）；无台账条目的减门/跳过改动一律拒绝，台账
本身是 Tier 2 决策工件。

### Scope

This rule + the runs layout template + schemas are the foundation; the two
tiers coexist — unmigrated artifacts keep writing to the ticket backend per
their existing body.