v0.1.5: standalone-readability pass — delink --strip provenance mode ([TT-NNNN]), Tier-2 dangling refs neutralized, verify/review-code giant skills split into reference/ on-demand files; guards now runtime-neutral (bun|node)
This commit is contained in:
@@ -5,17 +5,17 @@ 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
|
||||
This document is the **foundation** (MVP slice, [TT-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` /
|
||||
transient output here — the follow-up iteration ([TT-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
|
||||
([TT-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 mode ([TT-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 (`## 决策日志`
|
||||
@@ -47,8 +47,8 @@ for human-visible decisions.
|
||||
└── {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 —
|
||||
├── working-notes.md # cross-stage narrative memory ([TT-2600], schema-less md)
|
||||
├── workers/ # worker final-return reports ([TT-2847], schema-less md —
|
||||
│ └── ... # see _shared/worker-report-persistence.md)
|
||||
└── {stage}/ # per-stage transient artifacts (added by skills)
|
||||
└── ... # json (structured) / md (prompt files)
|
||||
@@ -61,7 +61,7 @@ for human-visible decisions.
|
||||
- **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
|
||||
--slug {slug} --ticket N [--branch …] [--worktree …]` ([TT-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
|
||||
@@ -118,7 +118,7 @@ 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])
|
||||
### `working-notes.md` — cross-stage narrative memory ([TT-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
|
||||
@@ -148,7 +148,7 @@ is that narrative memory, in-file, append-only:
|
||||
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])
|
||||
### `workers/` — worker final-return reports ([TT-2847])
|
||||
|
||||
Every worker sub-agent dispatch (`agent: worker` roles — Producer
|
||||
sub-roles, Verifier, Synthesizer) persists its **final return report**
|
||||
@@ -164,7 +164,7 @@ 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)
|
||||
### `browser/` — browser evidence packs ([TT-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`,
|
||||
@@ -204,20 +204,20 @@ Conventions established by this foundation:
|
||||
- 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]):**
|
||||
**Migrated stages ([TT-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-roadmap` | review | `reviews/roadmap/round{N}/findings-{DIM}.json` | `reviewer-output.schema.json` | legacy target archived ([TT-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 ([TT-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 ([TT-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 |
|
||||
| `requirements` (drafts) | requirements-elicitation | `requirements/` (schema-less `.md`/`.json`) | — | legacy skill archived ([TT-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/` [TT-3072] phase 3) | legacy skill archived ([TT-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/` [TT-3072] phase 3) | legacy skill archived ([TT-3072] phase 3) — historical bundles only |
|
||||
| `roadmap` (draft contracts) | roadmap | `roadmap/contracts/{name}.json` | `draft-contract.schema.json` (moved to `<instance-root>/archive/schemas/` [TT-3072] phase 3) | legacy skill archived ([TT-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
|
||||
@@ -241,24 +241,24 @@ enters git history:
|
||||
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
|
||||
([TT-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
|
||||
([TT-2601]). The bundle is validated by `runs-bundle.schema.json`.
|
||||
Offline review verifiability (TD/TRC-F006, [TT-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]).
|
||||
removed workspace or artifact-path reconstruction ([TT-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
|
||||
Steps 1–4 collapse into ONE command ([TT-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
|
||||
@@ -274,7 +274,7 @@ Gitea tax.
|
||||
|
||||
## Relationship to existing mechanisms
|
||||
|
||||
- **`/tmp/octopus/` embryo** — `review-code` ([org-internal #1988] MVP) now writes its
|
||||
- **`/tmp/octopus/` embryo** — `review-code` ([TT-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.
|
||||
|
||||
Reference in New Issue
Block a user