Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)

core/rules/two-tier-artifacts.md

@@ -0,0 +1,122 @@
+> 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.