octopus-workflow/core/templates/runs-layout.md

> Core 中立版（Increment 6a 改写，原 deferHard verbatim）。编号与条目结构严格不变（C-2 不变量）；实例术语按 `core/adapters/TERMINOLOGY.md` 绑定。
# Tier 1 Local Run Layout — `<runs-root>/{slug}/`

Normative layout for **Tier 1 local structured artifacts**. Authoritative
boundary rule: `core/rules/two-tier-artifacts.md`. Schemas that validate
the structured files below live in `core/schemas/runs-*.schema.json`.

This document is the **foundation** (MVP slice, [org-internal #1968]). It defines the
container, the manifest, and the metadata. Stage-specific artifact schemas
(design detail dumps, plan items, review dimension findings, synthesis
prompts, draft contracts) are added incrementally as each skill migrates its
transient output here — the follow-up iteration ([org-internal #1988]) has landed: `review-artifact` /
`audit-process` raw findings and producer working drafts are now Tier 1.
([org-internal #3072] phase 3, 2026-08-21: the legacy producer stages whose drafts are listed
below were archived — their rows and artifact dirs are kept for reading
historical run bundles.) See the migrated stages table below.

## Kind/MVP mode ([org-internal #3061])

`Kind/MVP` tickets write **nothing** to `<runs-root>/` by design — no stage
dirs, no `index.json`, no manifest. The ticket body is the doc (`## 决策日志`
+ `## Debt Register`). Optionally a single free-form
`<runs-root>/{slug}/working-notes.md` may capture scratch that does not
belong in the body; it has no schema and is not indexed. On graduation
(relabel `Kind/Feature`) the DAG route initializes the standard layout from
scratch; the MVP body remains the REQMAP baseline (analyze-dag backfill).

## Why a local tier

Agent-internal handoff (subagents sharing one worktree) currently pays the
Gitea tax (HTTP latency, wiki 409 conflicts, auth, Gitea-health dependency)
even though the consumer is a sibling subagent in the same process tree. The
embryo already proved local files viable (`/tmp/octopus/synthesis_task_*.md`
for `prompt_file`, see `core/skills/_shared/review-pipeline-phases.md` §Phase B step 1 — synthesis prompt).
This layout formalizes that embryo into a discoverable, schema-validated,
archive-at-close tier — without touching Gitea's role as the system of record
for human-visible decisions.

## Directory tree

```
<runs-root>/
├── .gitignore                # ignores active-run workspaces; tracks archive/ + self
├── archive/                  # TRACKED — closed-run bundles land here
│   ├── .gitkeep
│   └── {slug}.json           # one bundle per closed run (meta + index digest)
└── {active-slug}/            # GITIGNORED — one subdir per active run
    ├── meta.json             # run metadata        (runs-meta.schema.json)
    ├── index.json            # artifact manifest    (runs-index.schema.json)
    ├── working-notes.md      # cross-stage narrative memory ([org-internal #2600], schema-less md)
    ├── workers/              # worker final-return reports ([org-internal #2847], schema-less md —
    │   └── ...               #   see _shared/worker-report-persistence.md)
    └── {stage}/              # per-stage transient artifacts (added by skills)
        └── ...               #   json (structured) / md (prompt files)
```

### `{active-slug}`

- One subdir per active pipeline run, named by the run slug (the same `{slug}`
  used by the Gitea wiki namespace and the workflow branch tail).
- **Gitignored** while active — subagents share the worktree, not the git
  history, so active-run content stays local (no repo bloat, no merge noise).
- **Initialized at run start** by `bun <harness-package>/script/runs-init.ts
  --slug {slug} --ticket N [--branch …] [--worktree …]` ([org-internal #3642]) — the
  producing role / Orchestrator runs the script (hand-writing the files is the
  legacy path): it creates the `{active-slug}/` workspace, writes `meta.json`
  with `state: "active"` and the run's slug/branch/worktree/ticket (branch
  omitted / worktree null for ad-hoc runs without a worktree), and an empty
  `index.json` (`artifacts: []`), schema-validated before write and idempotent
  on re-run. Kind/MVP and Kind/Documentation tickets are skipped automatically
  (label check, § Kind/MVP mode below). `script/claim-provision.sh` chains this
  after claim + worktree in one command. Subsequent producing roles append to
  `index.json` as they emit artifacts.
- Removed by the Verifier's archive step at close (its content is bundled into
  `archive/{slug}.json` first).

### `meta.json` — run metadata

Schema: `core/schemas/runs-meta.schema.json`. Fields:

| field | type | notes |
|---|---|---|
| `schema_version` | integer | const `1` |
| `slug` | string | run slug; matches branch tail + wiki namespace |
| `ticket` | object\|null | `{ owner, repo, number }` of the source issue, or null for ad-hoc runs |
| `branch` | string | workflow branch, e.g. `workflow/enhancement/1968-two-tier-artifacts`; omitted for ad-hoc runs without a branch |
| `worktree` | string\|null | absolute path of the worktree, or null for ad-hoc runs without a worktree |
| `parent_epic` | object\|null | `{ number }` of the parent Epic, if any |
| `state` | enum | `active` → `archived` (set at close) |
| `created_at` | string | RFC 3339 timestamp |
| `updated_at` | string | RFC 3339 timestamp |
| `closed_at` | string\|null | RFC 3339; null while active |
| `close_commit_sha` | string\|null | git SHA of the archive commit; null while active |

### `index.json` — artifact manifest

Schema: `core/schemas/runs-index.schema.json`. This is the **compact
recovery entry point**: after `compact` (which never deletes local files), an
agent re-reads `index.json` to recover the run's artifact set without scanning
the tree. Each entry:

| field | type | notes |
|---|---|---|
| `schema_version` | integer | const `1` |
| `slug` | string | run slug |
| `artifacts` | array | one entry per Tier 1 artifact in this run |
| `artifacts[].path` | string | path relative to `{active-slug}/` |
| `artifacts[].type` | enum | `meta`, `index`, `design`, `plan`, `review-findings`, `review-status`, `review-synthesis`, `synthesis-prompt`, `precondition-gate`, `working-notes`, `analysis`, `browser-evidence`, `other` (authoritative enum: `core/schemas/runs-index.schema.json`) |
| `artifacts[].schema` | string\|null | `$id` of the validating schema, or null for schema-less (e.g. prompt `.md`) |
| `artifacts[].tier` | const `1` | local tier marker (Tier 2 is never listed here) |
| `artifacts[].stage` | enum\|null | producing pipeline stage (`requirements`/`design`/`plan-iterations`/`implement`/`review-code`/`verify`/…), or null for meta/index |
| `artifacts[].produced_by` | enum\|null | `Producer`/`Reviewer`/`Verifier`/`Tool`/`Coordinator` (canonical role names — the `name` field of `core/skills/_shared/roles/*.yaml`), plus fine-grained sub-roles mapped via `ROLE_ALIASES` in `<harness-package>/src/config/role.ts`: Producer sub-roles `Analyst`/`Architect`/`Planner`/`Developer`/`Synthesizer`/`Orchestrator`/`Remediator`, and the Reviewer sub-role `Auditor` |
| `artifacts[].sha` | string\|null | content digest (sha256), or null if not yet computed |
| `artifacts[].tier2_ref` | string\|null | cross-link to the Tier 2 mirror (e.g. issue comment URL / wiki page) when one exists |

`index.json` is **parallel, not replacement**, for the Tier 2 `## 工件索引`
issue comment: the former is the agent's compact-recovery entry; the latter is
the human-visible traceability hub. They are kept in sync by the producing
role but serve different consumers.

### `working-notes.md` — cross-stage narrative memory ([org-internal #2600])

`index.json` is a MANIFEST: it records WHAT artifacts exist. It does not
carry WHY code was written that way, which paths were tried and abandoned, or
what the reviewer's feedback actually changed — the tacit context every next
stage currently re-derives by re-reading formal artifacts. `working-notes.md`
is that narrative memory, in-file, append-only:

- **Format** (schema-less markdown): each entry is
  `## [{stage}] {role} @ {RFC 3339 ts}` followed by **≤30 lines** covering:
  decisions made (and why), dead ends (do NOT retry these), reviewer feedback
  that changed the work, and one-line hints for the next stage.
- **Append cadence** — one entry per unit of ownership, never per subagent
  dispatch: Producer sub-roles append at **stage exit**; the Reviewer side
  appends **via the Synthesizer at review convergence** (one entry per
  review, not per dimension — 9 dimension dispatches = 1 distilled entry);
  the Verifier appends at **verify exit**; Tool agents append only when the
  task produced a load-bearing finding (e.g. image evidence that changed a
  decision).
- **Re-read rule**: the next stage reads `working-notes.md` FIRST — before
  the formal artifacts — and may then skip full re-reads that the notes
  already cover. Role yamls carry this line in `compact.preserve`
  (`core/skills/_shared/roles/*.yaml`).
- **index.json row** (registered once by the first appending role):
  `type: working-notes`, `schema: null` (markdown), `stage: null`
  (cross-stage), `produced_by: null` (multi-role), `tier2_ref: null`.
- **Tier judgment**: consumed within one worktree/run ✓, never a human gate
  decision ✓, never referenced cross-worktree ✓, archivable at close ✓ — all
  four Tier 1 conditions hold (`core/rules/two-tier-artifacts.md` 判据).

### `workers/` — worker final-return reports ([org-internal #2847])

Every worker sub-agent dispatch (`agent: worker` roles — Producer
sub-roles, Verifier, Synthesizer) persists its **final return report**
verbatim to `workers/{chunk-id}-worker-{seq}.md` as its LAST action before
returning (lightweight fallback when no run workspace exists:
`/tmp/octopus/{chunk-id}-worker-{seq}.md`). The persisted copy is the report
of record — when the task completion notification is lost, the orchestrating
session recovers the worker's conclusion by reading the newest
`workers/{chunk-id}-worker-*.md` match. Skills that own a canonical stage
path for the dispatch (e.g. the review-code Synthesizer's
`reviews/{stage}/round{N}/synthesis-return.md`) use it instead of the
generic name. `index.json` row: `type: "other"`, `schema: null`, `stage` =
producing stage, `produced_by` = role. Full convention:
`core/skills/_shared/worker-report-persistence.md`.

### `browser/` — browser evidence packs ([org-internal #4497] N-03)

A browser-debug session writes one evidence pack per session under
`browser/{session-id}/` (contract `browser-evidence-4486/shared/pack-manifest-v1`,
frozen 2026-09-10 — `<harness-package>/src/browser/evidence-pack.ts` is the writer):

```
browser/{session-id}/
├── manifest.json           # PackManifest: env probe (shared/env-probe-v1),
│                           #   replay metrics {attempted, succeeded, failures[]},
│                           #   artifact rows {kind, path, sha256_16}
├── trace/                  # Playwright trace zips (recorded sessions)
├── screenshots/*.png       # copies — the .playwright-mcp/ layer is additive-not-replaced
├── console-errors.jsonl    # one sanitized entry per line
└── network-failures.json   # sanitized failure summary
```

Write boundary invariants (the graph's single mandatory sanitize point,
`shared/sanitize-api-v1`): every textual capture passes `sanitizeForEvidence`
before hitting the disk; entries whose URL fails the navigation allowlist are
excluded from the pack; the write is non-blocking (the writer returns a handle
before the first byte lands). `index.json` row: `type: "browser-evidence"`,
`path: "browser/{session-id}/manifest.json"`, `stage` = producing session's
stage (`implement`/`verify`), `produced_by: "Tool"`.

### `{stage}/` — per-stage transient artifacts

Added incrementally by each skill as it migrates its transient output to Tier 1.
Conventions established by this foundation:

- Structured data → `.json` (schema-validated).
- Prompt files passed to subagents via `prompt_file` → `.md`.
- File naming mirrors the Gitea wiki namespace so a Tier 1 path and its (former
  / future) Tier 2 mirror are visually paired, e.g. on-disk
  `<runs-root>/{slug}/reviews/{stage}/round{N}/findings-COR.json`. The
  corresponding `index.json` `artifacts[].path` value strips the `{slug}/`
  prefix (it is relative to `{active-slug}/`): `reviews/{stage}/round{N}/findings-COR.json`.
- A stage that has not yet migrated continues to write to Gitea (Tier 2) per its
  existing skill body — the two tiers coexist during the migration.

**Migrated stages ([org-internal #1988]):**

| Stage | Skill | Tier 1 artifacts | Schema | Notes |
|---|---|---|---|---|
| `review-code` | review-code | `reviews/code/round{N}/findings-{DIM}.json` (raw dimension findings), `reviews/code/round{N}/task-synthesizer.md` (synthesis prompt) | `reviewer-output.schema.json` (findings) | synthesis comment + commit status stay Tier 2 |
| `review-roadmap` | review | `reviews/roadmap/round{N}/findings-{DIM}.json` | `reviewer-output.schema.json` | legacy target archived ([org-internal #3072] phase 3) — row kept for historical bundles |
| `review-design-space` | review | `reviews/design-space/round{N}/findings-{DIM}.json` | `reviewer-output.schema.json` | legacy target archived ([org-internal #3072] phase 3) — row kept for historical bundles |
| `review-iteration-plan` | review | `reviews/plan/round{N}/findings-{DIM}.json` | `reviewer-output.schema.json` | legacy target archived ([org-internal #3072] phase 3) — row kept for historical bundles |
| `review-dag` | review | `reviews/review-dag/round{N}/findings-{DIM}.json` | `reviewer-output.schema.json` | synthesis comment + commit status stay Tier 2 |
| `audit-process` | review | `reviews/audit-process/round{N}/findings-{DIM}.json` | `reviewer-output.schema.json` | synthesis wiki page + commit status stay Tier 2 |
| `requirements` (drafts) | requirements-elicitation | `requirements/` (schema-less `.md`/`.json`) | — | legacy skill archived ([org-internal #3072] phase 3) — historical bundles only |
| `design` (drafts) | design | `design/` (schema-less or `design-detail.schema.json`) | `design-detail.schema.json` (moved to `<instance-root>/archive/schemas/` [org-internal #3072] phase 3) | legacy skill archived ([org-internal #3072] phase 3) — historical bundles only |
| `plan-iterations` (drafts) | plan-iterations | `plan-iterations/` (schema-less or `plan-items.schema.json`) | `plan-items.schema.json` (moved to `<instance-root>/archive/schemas/` [org-internal #3072] phase 3) | legacy skill archived ([org-internal #3072] phase 3) — historical bundles only |
| `roadmap` (draft contracts) | roadmap | `roadmap/contracts/{name}.json` | `draft-contract.schema.json` (moved to `<instance-root>/archive/schemas/` [org-internal #3072] phase 3) | legacy skill archived ([org-internal #3072] phase 3) — historical bundles only |

Every review/audit stage additionally maintains a per-stage lifecycle file
`reviews/{stage}/status.json` (schema `review-status.schema.json`) — live
stages: `review-code`, `review-dag`, `audit-process`; legacy bundle stages
(`review-roadmap`, `review-design-space`, `review-iteration-plan`) maintain
the same file in historical bundles only. It is initialized by the
Orchestrator before round 1, appended by the Synthesizer each round, and
finalized with `converged` at Phase E. The Orchestrator appends an
`index.json` row for it (`type` = `review-status`, `stage` = `{REVIEW_TYPE}`,
`produced_by` = `Orchestrator`).

Stages NOT yet migrated (none — all target stages have been migrated or have opt-in Tier 1 affordances): reviser task prompts (wiki pages) remain Tier 2 in this slice; synthesis prompts for `review-artifact` / `audit-process` targets follow the shared Phase B mechanics (Tier 1 for all `tier1-local` skills).

## Archive-at-close

Closed by the **Verifier** at verify PASS (or by the Orchestrator for flows
without verify). The archive step is the ONLY point at which active-run content
enters git history:

1. Set `meta.json.state = "archived"`, record `closed_at` and `close_commit_sha`.
2. Write `archive/{slug}.json` — a compact bundle carrying `meta` + the
   `index.json` manifest (the durable trace; bulk artifacts are summarized by
   digest, not copied wholesale, to keep the archive small). One exception
   ([org-internal #2600]): when `working-notes.md` exists, its final content is inlined as
   the bundle's top-level `working_notes` field — the narrative memory is the
   single artifact whose content (not just digest) rides in the bundle,
   feeding later retro probes and the notes-injection degradation path
   ([org-internal #2601]). The bundle is validated by `runs-bundle.schema.json`.
   Offline review verifiability (TD/TRC-F006, [org-internal #2688]): for each review stage
   the run executed, also embed a top-level `review_history` entry in the
   bundle — `{stage, rounds, final_verdict, per_round[]}` (per-round:
   round/overall_verdict/blockers/majors/minors) — derived from that stage's
   live `reviews/{stage}/status.json` `history[]`. Closed-run probes can then
   reconstruct round counts and verdicts from the bundle alone, without the
   removed workspace or artifact-path reconstruction ([org-internal #2591]).
3. `git add archive/{slug}.json` and commit on the workflow branch (rides into
   main via the `--no-ff` merge).
4. Remove the `{active-slug}/` workspace from the worktree (its durable record
   now lives in the archive bundle).

Steps 1–4 collapse into ONE command ([org-internal #3642]): `bash script/archive-run.sh
{slug} [--pr N]` — run from the session worktree, it resolves the PR by branch
head, generates + validates the bundle via `gen-run-bundle.ts` (recording
`closed_at` / `close_commit_sha` and the `--branch` workflow branch), commits
it with a hook-conforming `[{chunk}][iter-N] chore(runs): …` message, removes
the workspace, and tears the worktree down unless invoked from inside it. The
`## 工件索引` archived remark (issue-checklist-sync.md § 归档动作) remains an
agent action — content judgment, not scripted.

Tier 2 (Gitea) remains the **system of record** for decisions (verdicts, issue
status, PRs, frozen contracts). The Tier 1 git archive is the **reproducibility
trace** — enough to reconstruct what a run produced, without re-paying the
Gitea tax.

## Relationship to existing mechanisms

- **`/tmp/octopus/` embryo** — `review-code` ([org-internal #1988] MVP) now writes its
  synthesis prompt under `<runs-root>/{slug}/reviews/code/` instead of
  `/tmp/octopus/synthesis_task_*`. Other skills still using the `/tmp/octopus/`
  embryo coexist until their own migration iteration.
- **`## 工件索引` issue comment (Tier 2)** — unchanged; `index.json` (Tier 1) is
  its agent-side parallel, not a replacement.
- **compact** — `compact` never deletes local files, so `index.json` survives
  compaction and is the designated re-read entry for a compacted run.
- **worktree discipline** — all subagents of one workflow share its worktree, so
  they share `<runs-root>/{slug}/` directly (no cross-worktree coordination
  needed for Tier 1; that coordination lives in Tier 2).