123 lines
5.9 KiB
Markdown
123 lines
5.9 KiB
Markdown
> 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.
|