@playcraft/cli 0.0.43 → 0.0.46

package/project-template/docs/team/collaboration.md

@@ -1,143 +1,302 @@
 # Agent Collaboration Reference
 
+> **Workflow spec**: `growth-rings-v1` — four growth rings, each with inner loops `clarify → build → verify → Ring Gate`.
+
+## Role Quick Index
+
+Each role only needs specific sections of this document. Use this table to skip to what matters for you.
+
+| Role                 | Read these sections                                                                                                                            |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Orchestrator**     | All (this is your primary protocol doc)                                                                                                        |
+| **dispatchPacket**   | Machine dispatch unit: `role + doWhat + flow + sliceId` from `npm run state:get`; supersedes ring-loop invoke wording when active slice exists |
+| **Game Designer**    | § STOP sync checklist, § Agent Handoff, § Four-doc discipline, § Spec Gap Protocol, § ICP                                                      |
+| **Developer**        | § STOP sync checklist, § Agent Handoff, § Developer in build loop, § Spec Gap Protocol, § Spec Quick-Check, § ICP, § Upstream rework routing   |
+| **Artist**           | § STOP sync checklist, § Agent Handoff, § Four-doc discipline, § ICP, § MC five panels                                                         |
+| **Technical Artist** | § STOP sync checklist, § Agent Handoff, § Four-doc discipline, § Spec Quick-Check, § ICP                                                       |
+| **Reviewer**         | § STOP sync checklist, § Agent Handoff, § UI rework sequence                                                                                   |
+
+---
+
 ## Glossary
 
 Canonical terms used across `CLAUDE.md`, agent L1 files, and `refs/`. Prefer the **Canonical** column in new edits.
 
-| Canonical                      | Also called                                | Meaning                                                                                                                                                                            |
-| ------------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Gate #1 package** (四件套)   | four design docs, PM four docs             | PM deliverables before Gate #1 STOP: `docs/project-state.md` + `docs/design-brief.md` + `docs/layout-spec.md` + **`docs/atom-plan.json`**（主）+ `docs/atom-plan.md`（Context 辅） |
-| **Asset Contract**             | Asset Path Contract, assetMapping contract | Locked `layout-spec.md` `assetMapping` paths (+ atlas groups, `frameId`) after Gate #1 — no unilateral path changes                                                                |
-| **devUrl**                     | Dev URL, preview link                      | Local Dev server URL from `npm run dev`; orchestrator shares at Gate #3; user never runs dev themselves                                                                            |
-| **Designer Phase 1 / Phase 2** | —                                          | Ph.1 = MC + ASR + Handoff Pack; Ph.2 = audio + digit + VisualAtom status (v2)                                                                                                      |
-| **ASR Coverage Matrix**        | —                                          | `designer-log` table: every contract id → ASR slot; Gate #2b mandatory                                                                                                             |
-| **Palette Locked**             | —                                          | MC-sampled hex in `designer-log`; delta vs `layout-spec`                                                                                                                           |
-| **production-serial-v1**       | workflow spec version (superseded)         | See `workflow-changelog.md`; serial production waves within `production` stage                                                                                                     |
-| **convergence-v1**             | workflow spec version (current)            | Three convergence loops: design_check → ui_diff → load_check + Gate #3 user                                                                                                        |
-| **design_check**               | Reviewer mode                              | Soft checklist before Gate #1 / #2b — completeness only, not subjective quality                                                                                                    |
-| **ui_diff**                    | Reviewer mode                              | Browser screenshots vs MC panels; routes ui_rework (max 5 rounds)                                                                                                                  |
-| **load_check**                 | Reviewer mode                              | Page loads + no console errors before Gate #3; no gameplay walkthrough                                                                                                             |
-| **ui_ready**                   | devStatus value                            | UI shell complete; gameplay rules not yet implemented                                                                                                                              |
-| **designer-handoff-v2**        | visual handoff spec                        | MC + ASR + Handoff Pack; bundled in convergence-v1                                                                                                                                 |
-| **Production Pipeline**        | serial waves in `project-state`            | Wave 1 Designer Ph.2 → Wave 2 TA; Developer in `ui_pass`                                                                                                                           |
-| **Developer ui_pass**          | —                                          | UI shell + scene switch + simple states; no core gameplay rules                                                                                                                    |
-| **Developer gameplay_pass**    | —                                          | Core gameplay on verified UI; PGS + first level success                                                                                                                            |
-| **Four-doc discipline**        | 四件套写作纪律                             | PM/Designer: contracts only in four docs; narrative in style-exploration + designer-log; TA/Dev intake: agent-conduct + log templates                                              |
-| **TA Step 0 / 1 / 2**          | (not "Phase")                              | **TA cookbook only**: Step 0 = Skill Discovery; Step 1 = Asset Completion; Step 2 = Technical Pipeline — TA runs all three in one `production` invoke                              |
-| **reworkRound**                | `handoff.rework_round` (legacy)            | Superseded by **`uiReworkRound`** for UI convergence (0–5)                                                                                                                         |
-| **uiReworkRound**              | `handoff.ui_rework_round`                  | Counts **ui_diff failures** (0 → 5 max); at 5 → orchestrator decision                                                                                                              |
-| **ICP**                        | Intent Clarification Protocol              | Async agent Q&A in `docs/intent-clarifications.md`; orchestrator does not interrupt user                                                                                           |
-| **MC**                         | Master Composite                           | Five 9:16 panels in one image: concept panel + Hook / Onboarding / End Card / CTA storyboards                                                                                      |
-| **ASR**                        | Asset State Reference Sheet                | 资产状态参考精灵图板：UI 组件状态板 + 元素状态板；Gate #2a 后产出；供 TA crop 量产（非 runtime atlas）                                                                             |
-
-## Mission vs Goals vs Workflow
-
-| Layer            | Location                           | Purpose                                                                       |
-| ---------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
-| **Team Mission** | `CLAUDE.md` § Mission              | Shared vision — why we build playable ads                                     |
-| **Role Goals**   | `.claude/agents/<role>.md` § Goals | **What this role must achieve**, in priority order (Top 3 + success criteria) |
-| **Workflow**     | Same agent file + `refs/`          | How to execute; exit criteria point back to Goals                             |
-
-When instructions conflict: **Goals § Core responsibilities** wins over workflow shortcuts (e.g. Developer must not set `devStatus: ready` with open upstream blockers). Enforceable MUST/NEVER: [agent-conduct.md](agent-conduct.md).
-
-## Gate Protocol (Orchestrator-Only)
-
-Only the **Orchestrator** (main session) may use `AskUserQuestion` toward the user. Sub-agents prepare materials, update `project-state`, then **STOP**.
-
-| Gate    | Sub-agent deliverable                                            | STOP signal (`project-state`) | Orchestrator action                                                                                                                                 |
-| ------- | ---------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **#1**  | PM: four design docs ready for review                            | `gates.#1 = pending`          | Invoke `@reviewer design_check` → pass → `AskUserQuestion` → on pass: `gates.#1 = passed`, `stage: style_exploration`, invoke `@designer`           |
-| **#2a** | Designer: MC options A/B[/C] + partial `style-exploration.md`    | `gates.#2a = pending`         | `AskUserQuestion` pick option → set `selectedMcOption` → resume `@designer` (no Reviewer pre-check)                                                 |
-| **#2b** | Designer: ASR 双板 + complete `style-exploration` + designer-log | `gates.#2b = pending`         | Invoke `@reviewer design_check` → pass → `AskUserQuestion` confirm MC+ASR → `gates.#2b = passed`, `stage: production`, invoke `@designer` Ph.2 only |
-| **#3**  | Reviewer `load_check` pass + `devStatus: ready`                  | `gates.#3 = pending`          | Show **devUrl** → user accept → `stage: done` (gameplay judged by user)                                                                             |
-
-Sub-agent pattern: **write artifacts → update `## Agent handoff` + gates → STOP (no user questions).**
+| Canonical                        | Also called                                | Meaning                                                                                                                                                                                                                                                                                                                    |
+| -------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Growth ring** (iteration 1..4) | iteration, ring                            | Outer loop climbing the atom-tree: engine root → periphery → hook/CTA → production                                                                                                                                                                                                                                         |
+| **Inner loop**                   | clarify / build / verify                   | Per-ring collaboration cycle before Ring Gate                                                                                                                                                                                                                                                                              |
+| **Ring Gate**                    | user_gate, ring acceptance                 | One orchestrator-only user acceptance per ring after objective DoD passes (`npm run ring:gate`)                                                                                                                                                                                                                            |
+| **Ring DoD**                     | ringDoD, objective DoD                     | Machine-checkable verifiers per ring (`verify:contract`, `verify:lifecycle`, `verify:firstwin`, `record:mp4`, `verify:ui`, `playable_validate`, `ui_diff`, `verify:ui:assets`, …)                                                                                                                                          |
+| **Ring 1 package** (minimal)     | playable seed + compact atom selection     | Ring 1 clarify deliverable: a concise `docs/DESIGN.md` playable seed (player action, immediate feedback, progress signal, first win, semantic placeholders, engine hint). Then a temporary ref-flow subagent creates compact `atom-tree.*` selection for scaffold only; no design-brief/layout/full product tree in ring 1 |
+| **Handoff Context**              | shared working memory                      | Structured `handoffContext` in `docs/project-state.json`. `state:get` exposes it as `contextPacket`; agents read it before artifact refs and write it on STOP. Markdown docs remain contracts/evidence, not the default cross-role memory.                                                                                 |
+| **Asset Contract**               | Asset Path Contract, assetMapping contract | `layout-spec.md` `assetMapping` paths — **locked only after ring 4** (`assetMappingLocked: true`)                                                                                                                                                                                                                          |
+| **devUrl**                       | Dev URL, preview link                      | Local Dev server URL from `npm run dev`; orchestrator shares at each Ring Gate; user never runs dev themselves. **Always append `?debug=1`** so the on-screen one-click clear (debug) button is shown — every shared/recorded devUrl must carry `?debug=1`                                                                 |
+| **Artist depth by ring**         | —                                          | Ring 1–2: placeholder; Ring 3: ASR + style lock; Ring 4 Wave 1: audio + digit                                                                                                                                                                                                                                              |
+| **ASR Coverage Matrix**          | —                                          | `artist-log` table: every contract id → ASR slot; mandatory before ring 3 verify                                                                                                                                                                                                                                           |
+| **Palette Locked**               | —                                          | MC-sampled hex in `artist-log`; delta vs `layout-spec`                                                                                                                                                                                                                                                                     |
+| **growth-rings-v1**              | workflow spec version                      | Current workflow; supersedes `convergence-v1`, `production-serial-v1`, waterfall stages                                                                                                                                                                                                                                    |
+| **design_check**                 | Reviewer mode (legacy)                     | Soft checklist — completeness only; use sparingly in growth-rings; prefer ring DoD verifiers                                                                                                                                                                                                                               |
+| **gameplay_conformance**         | Reviewer mode (ring 2+ review-backed DoD)  | Verify DESIGN.md conformance + Skill usage evidence + playwright-cli path reachability; fill `gameplayConformance: pass/fail` in § Ring DoD Fields — `ring:gate` enforces it like `hookCta`/`uiDiff`                                                                                                                       |
+| **ui_diff**                      | Reviewer mode                              | Browser screenshots vs locked ASR; routes UI rework (max 5 rounds) during ring 4 verify                                                                                                                                                                                                                                    |
+| **load_check**                   | Reviewer mode                              | Page loads + no console errors; no gameplay walkthrough                                                                                                                                                                                                                                                                    |
+| **playable_validate**            | Reviewer mode                              | Ring 3+: hook/CTA + headed MP4 rules                                                                                                                                                                                                                                                                                       |
+| **Production Pipeline**          | serial waves in `project-state`            | Ring 4 only: Wave 1 Artist (audio + digit) → Wave 2 TA (bulk production)                                                                                                                                                                                                                                                   |
+| **Four-doc discipline**          | 四件套写作纪律                             | Game Designer/Artist: contracts only in four docs; narrative in style-exploration + artist-log; TA/Dev intake: agent-conduct + log templates                                                                                                                                                                               |
+| **TA Step 0 / 1 / 2**            | (not "Phase")                              | **TA cookbook only**: Step 0 = Skill Discovery; Step 1 = Asset Completion; Step 2 = Technical Pipeline — TA runs all three in one ring 4 build invoke                                                                                                                                                                      |
+| **uiReworkRound**                | —                                          | Counts **ui_diff failures** (0 → 5 max) during ring 4 verify; at 5 → orchestrator decision                                                                                                                                                                                                                                 |
+| **ICP**                          | Intent Clarification Protocol              | Async agent Q&A in `docs/intent-clarifications.md`; orchestrator does not interrupt user                                                                                                                                                                                                                                   |
+| **MC**                           | Master Composite                           | Five 9:16 panels in one image: concept panel + Hook / Onboarding / End Card / CTA storyboards (ring 3+)                                                                                                                                                                                                                    |
+| **ASR**                          | Asset State Reference Sheet                | UI + element state reference sheets; ring 3 build output; TA crop source in ring 4                                                                                                                                                                                                                                         |
+| **archivedRings**                | non-regression snapshot                    | Prior rings' passed DoD; must stay green when advancing iteration                                                                                                                                                                                                                                                          |
+| **Single developer build owner** | Developer                                  | Developer owns every ring's `build` loop: intake, read/load, implementation, integration, `devStatus` / `devUrl` / `devBlockers`                                                                                                                                                                                           |
+
+## Mission vs Role vs Workflow
+
+| Layer            | Location                         | Purpose                                                                               |
+| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------- |
+| **Team Mission** | `CLAUDE.md` § Mission            | Shared vision — why we build playable ads                                             |
+| **Role Card**    | `.claude/agents/<role>.md`       | Who the role is, what it owns, boundaries, success criteria, workflow interface       |
+| **Workflow**     | `refs/` + dispatch-specific docs | How to execute the current task; varies by iteration/loop and orchestrator assignment |
+
+When instructions conflict: role ownership in the role card wins over workflow shortcuts. Enforceable MUST/NEVER: [agent-conduct.md](agent-conduct.md).
+
+## Ring Gate Protocol (Orchestrator-Only)
+
+Only the **Orchestrator** (main session) may use `AskUserQuestion` for **Ring Gate** confirmations. Sub-agents prepare materials, update `project-state`, then **STOP**.
+
+**Slice axis first**: When `state:get` reports `dispatchMode: true`, orchestrator dispatches by **`dispatchPacket` only** — do not tell subagents "Ring N build/verify". Ring Gate runs only after slice queue + objective DoD allow (see Knife 9).
+
+**Objective DoD first**: Before any Ring Gate, orchestrator runs `npm run ring:gate -- --iteration N`. The script spawns verifiers, checks non-regression of prior rings, and sets `ringGateCanAskUser`. If it fails, route back to the owning agent — **do not** ask the user.
+
+**Exception**: Game Designer uses `AskUserQuestion` for gameplay brainstorm/clarification during `loop: clarify` — this is requirement gathering, NOT a Ring Gate.
+
+### Ring 1 engine scaffold (orchestrator, before build)
+
+After Game Designer ring 1 clarify STOP and **before** invoking `@developer`:
+
+```bash
+temporary ref-flow atom-selection subagent       # creates compact docs/atom-tree.json
+playcraft skills validate-atom-tree-selection
+playcraft remix init-template --from-atom-tree
+npm install && npm run verify:contract && npm run verify:lifecycle
+```
+
+- Writes `game/` from `engine-packs/{phaser|threejs}`, `.playcraft-engine`, and `docs/scaffold-manifest.md`.
+- `npm run workflow:doctor` **BLOCKED** if `.playcraft-engine` ≠ `meta.engineDecision.adapter`, or if marker missing during ring 1 `loop: build`.
+- **Do not** silently overwrite `game/` during selection — engine scaffold is always explicit via `init-template`.
+
+See [core-model.md § Command Contract](core-model.md#command-contract) and [harness-legacy-deprecation.md](harness-legacy-deprecation.md).
+
+### Per-ring flow
+
+| Step | Loop    | Agent(s)                                        | STOP → next                                                                                                                                                                                           |
+| ---- | ------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | clarify | `@game-designer` → temporary ref-flow selector  | Orchestrator → ring 1: context packet + compact atom selection → `init-template` + `verify:contract` first → `loop: build` → `@developer`                                                             |
+| 2    | build   | `@developer` (+ Artist/TA per ring)             | Ring 1: Developer self-gate (`verify:contract` + `verify:lifecycle` + `verify:firstwin` + `verify:placeholders`) → `loop: verify` → orchestrator `ring:gate`; ring 2+: → `loop: verify` → `@reviewer` |
+| 3    | verify  | ring 1: orchestrator only; ring 2+: `@reviewer` | Orchestrator → `npm run ring:gate -- --iteration N`                                                                                                                                                   |
+| 4    | —       | **Orchestrator only**                           | If pass → Ring Gate `AskUserQuestion` at devUrl → archive ring → `iteration+1`, `loop: clarify`                                                                                                       |
+
+### Ring DoD by iteration
+
+| Ring  | Objective DoD (via `ring:gate`)                                                                                                     |
+| ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **1** | `verify:contract` + `verify:lifecycle` (HOOK → autoPlay → ENDCARD) + `verify:firstwin` + `verify:placeholders`                      |
+| **2** | Ring 1 DoD + disclosed UI / MP4 evidence gates                                                                                      |
+| **3** | Ring 2 DoD + Reviewer `playable_validate` (hook/CTA)                                                                                |
+| **4** | Ring 3 DoD + Reviewer `ui_diff` + `verify:ui:assets` + `verify:atom-conformance` (when present) + `verify:visual` (when ASR locked) |
+
+After ring 4 Ring Gate pass → project **done** (user accepts devUrl; not `playcraft build`).
+
+Sub-agent pattern: **write artifacts → update `handoffContext` + routing handoff + ringDoD → STOP (no user questions).**
 
 ## Agent Handoff
 
-Machine-readable runtime block in `docs/project-state.md` (YAML fence under `## Agent handoff`). Sub-agents and orchestrator use it as the **single source** for STOP / resume / next step.
+State lives in **`docs/project-state.json`** (machine source of truth). `docs/project-state.md` is a GENERATED, read-only view (including the `## Agent handoff` YAML fence) re-rendered after every write. **Read with `npm run state:get`, write with `npm run state:set` / `npm run ring:gate`. Never open or hand-edit the markdown.**
+
+There are two handoff layers:
+
+- `handoffContext` = shared working memory for the next role. It records ring summary, last role decisions/evidence, next role facts, stable shared decisions, and blockers.
+- `handoff` YAML fields = routing flags for STOP / resume / Ring Gate.
+
+Agents read `contextPacket` from `state:get` first, then open only required files or artifact refs named in that packet. Logs and markdown docs are traceable evidence, not the default memory every role must reload.
+
+| Field                      | Writer                                                                                            | Meaning                                                                                                                                         |
+| -------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `iteration`                | Orchestrator on ring advance                                                                      | Current growth ring 1..4                                                                                                                        |
+| `loop`                     | Orchestrator on loop transition                                                                   | `clarify` \| `build` \| `verify`                                                                                                                |
+| `ringGoal`                 | Orchestrator / Designer on clarify                                                                | Human-readable ring scope                                                                                                                       |
+| `ringGate`                 | Sub-agent on verify STOP                                                                          | `pending` until orchestrator confirms user acceptance                                                                                           |
+| `ringDoD`                  | Sub-agents + `ring:gate` runner                                                                   | Objective verifier status map                                                                                                                   |
+| `archivedRings`            | Orchestrator on Ring Gate pass                                                                    | Non-regression snapshot of prior rings                                                                                                          |
+| `subagent`                 | Sub-agent on STOP                                                                                 | Role that just finished (`game-designer`, temporary `skill-selector`/`ref-flow`, `artist`, `technical-artist`, `developer`, `reviewer`, `none`) |
+| `subagent_stop`            | Sub-agent on STOP                                                                                 | `true` = do not continue until orchestrator acts                                                                                                |
+| `waiting_for`              | Sub-agent: `orchestrator` on STOP; Orchestrator: `user_gate` only after `ringGateCanAskUser: yes` | `user_gate` = Ring Gate only; `orchestrator` = wait for invoke; `none` = active work                                                            |
+| `next_orchestrator_action` | Sub-agent on STOP (**required**)                                                                  | One sentence: the **only** legal next step for orchestrator                                                                                     |
+| `last_completed_by`        | Sub-agent on STOP                                                                                 | Same as `subagent` or action label                                                                                                              |
+| `block_reason`             | Optional                                                                                          | Why pipeline cannot advance                                                                                                                     |
+
+### `handoffContext` structure
+
+| Field             | Writer                       | Meaning                                                                                  |
+| ----------------- | ---------------------------- | ---------------------------------------------------------------------------------------- |
+| `ring`            | Orchestrator / gate runner   | Current ring summary, goal, and passed DoD (Definition of Done, 完成定义)                |
+| `lastRole`        | Stopping sub-agent           | Previous role summary, key decisions, `artifactRefs`, validation results, blockers       |
+| `nextRole`        | Stopping sub-agent           | Next role, must-know facts, required files, forbidden full-read files, artifact refs     |
+| `sharedDecisions` | Roles as decisions stabilize | Cross-role stable facts: engine, core action, semantic placeholders, asset contract refs |
+| `openQuestions`   | Any role                     | Only unresolved questions that block the next step                                       |
+
+**Orchestrator loop:** read handoff → if `waiting_for: user_gate` and `ringGateCanAskUser: yes` → Ring Gate only → else if `subagent_stop` → execute `next_orchestrator_action` → reset handoff before invoke.
+
+**Sub-agent verify STOP:** set `waiting_for: orchestrator` and `next_orchestrator_action: npm run ring:gate -- --iteration N` — **never** `waiting_for: user_gate`.
+
+**Sub-agent loop:** read handoff → if already stopped for this role → refuse duplicate work → else read role card + workflow → update handoff → append `--- PLAYCRAFT_STOP ---` footer.
+
+### Updating handoff (use `state:set`, never hand-edit md)
+
+Agents **must** update state via the CLI helper — do **not** use `python3 -c`, `sed`, or edit `docs/project-state.md`/`.json` by hand (error-prone, and md edits are overwritten on the next render):
+
+```bash
+npm run state:get -- iteration loop subagent_stop waiting_for
+npm run state:set -- contextRole=game-designer contextSummary="Playable seed locked: tap target -> immediate feedback -> first win" contextNextRole=ref-flow contextArtifactRefs=docs/DESIGN.md contextCoreAction="tap target" contextSemanticPlaceholders="player;target;feedback;reward" contextMustKnow="Use DESIGN.md as playable seed only; select engine + compact gameplay trunk" contextRequiredFiles="docs/DESIGN.md"
+npm run state:set -- subagent_stop=true waiting_for=orchestrator next_orchestrator_action="Spawn temporary ref-flow atom-selection subagent for ring 1 atom-tree selection" last_completed_by=game-designer
+```
+
+- Values with spaces: quote the whole `key=value` in shell, or pass as `next_orchestrator_action="npm run ring:gate -- --iteration 1"`.
+- Keys route automatically: handoff keys → handoff block; `devStatus` / `devUrl` / `loadCheck` / `uiReviewStatus` / … → Dev Preview; `ringGate*` → Ring Gate Runner. The renderer always emits every table, so a write never silently no-ops on a missing row.
+- Structured sub-operations: `npm run state:set -- --checkpoint "ring 1 self-gate passed" --by developer` appends a Progress Checkpoint; `npm run state:set -- --wave id=1 owner=artist status=done` sets a Production Pipeline wave row.
+- Read single keys with `npm run state:get -- --json waiting_for next_orchestrator_action` to avoid pulling the whole state.
+- Full context patch: `npm run state:set -- handoffContextPatch='{"lastRole":{"validation":["verify:firstwin pass"]}}'`.
+
+## Developer in `build` loop
 
-| Field                      | Writer                                  | Meaning                                                                                          |
-| -------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `subagent`                 | Sub-agent on STOP                       | Role that just finished (`pm`, `designer`, `technical-artist`, `developer`, `reviewer`, `none`)  |
-| `subagent_stop`            | Sub-agent on STOP                       | `true` = do not continue work until orchestrator acts                                            |
-| `waiting_for`              | Both                                    | `user_gate` = orchestrator must run Gate; `orchestrator` = wait for invoke; `none` = active work |
-| `gate_pending`             | Sub-agent when gate pending             | `"1"` \| `"2a"` \| `"2b"` \| `"3"` \| `null` — sync with Gates table                             |
-| `next_orchestrator_action` | Sub-agent on STOP (**required**)        | One sentence: the **only** legal next step for orchestrator                                      |
-| `last_completed_by`        | Sub-agent on STOP                       | Same as `subagent` or action label                                                               |
-| `rework_round`             | Reviewer on ui_diff fail / orchestrator | Keep in sync with `uiReworkRound` in Gate resume fields (legacy alias)                           |
-| `block_reason`             | Optional                                | Why pipeline cannot advance                                                                      |
+`developer` is the **build-loop owner** for every growth ring.
 
-**Orchestrator loop:** read handoff → if `gate_pending` + `user_gate` → Gate only → else if `subagent_stop` → execute `next_orchestrator_action` → reset handoff before invoke.
+During `loop: build`, Developer is responsible for:
 
-**Sub-agent loop:** read handoff → if already stopped for this role → refuse duplicate work → else branch per agent `## Runtime` → update handoff → append `--- PLAYCRAFT_STOP ---` footer.
+- upstream intake and Spec Quick-Check (depth scales per ring)
+- read/load of current on-disk code, scaffolded code, linked assets, and Skill refs
+- placeholder materialization (`playable-placeholder` skill) in rings 1–3
+- implementation and integration
+- feature-checklist review (ring 2+)
+- `npm run dev`, `devStatus`, `devUrl`, and `devBlockers`
+
+`logs/developer-log.md` is the development truth log: intake, read/load notes, feature checklist, verification, blockers, and readiness rationale.
 
 ## STOP sync checklist
 
 On every sub-agent STOP, update **in order** (see [agent-conduct.md § Invoke protocol](agent-conduct.md#invoke-protocol-all-sub-agents)):
 
-1. **Gates table** — set `#N = pending` when gate materials ready (if applicable).
-2. **`## Agent handoff`** — all fields; `subagent_stop: true`; `next_orchestrator_action` required.
-3. **Progress Checkpoint** — one row (stage, agent, action, outcome).
-4. **Production Pipeline** — when `stage: production`, set this role's wave row to `done` + notes when wave complete.
-5. **Plan convergence (TA / Developer only)** — before STOP, ensure `logs/ta-log.md` § **Production Plan** or `logs/developer-log.md` § **UI Pass Plan** / **Gameplay Pass Plan** is complete (Risk Checklist all `[x]`, no `{{placeholders}}`). Hook `validate-workflow-stop.mjs` enforces on subagent stop.
+1. **handoff** — `npm run state:set -- subagent_stop=true waiting_for=orchestrator next_orchestrator_action="…" last_completed_by=<role>` — **do not** transition `iteration` / `loop`.
+2. **ringDoD** — set fields Reviewer or build loop completed (`npm run state:set -- …` or `npm run ring:gate`).
+3. **Progress Checkpoint** — `npm run state:set -- --checkpoint "<action/outcome>" --by <role>` (programmatic append; never hand-write a table row).
+4. **Production Pipeline** — when ring 4 build, `npm run state:set -- --wave id=N owner=<role> status=done notes="…"` when a wave completes.
+5. **Plan convergence (TA / Developer / Reviewer / Game Designer)** — required logs and handoff fields complete. Hook `validate-workflow-stop.mjs` enforces on STOP.
+
+Example Production Pipeline (ring 4):
+
+| Wave | Agent            | Status | Notes                           |
+| ---- | ---------------- | ------ | ------------------------------- |
+| 1    | Artist           | done   | Ph.2: BGM + SFX + digit strip   |
+| 2    | Technical Artist | done   | All TA atoms + Compliance green |
+
+Checkpoint is a **human log** for evidence — **not** the routing source (`handoff`) or shared working memory (`handoffContext`).
+
+## Iteration field ownership
+
+| Field / transition                             | Writer                                     |
+| ---------------------------------------------- | ------------------------------------------ |
+| `iteration`, `loop`, `ringGoal`                | **Orchestrator only** (on handoff execute) |
+| `ringGate: passed` + `archivedRings` update    | **Orchestrator** after Ring Gate pass      |
+| `ringDoD` verifier fields                      | Sub-agents + `ring:gate` runner            |
+| `selectedMcOption`                             | Orchestrator during ring 3 style lock      |
+| `assetMappingLocked: true`                     | Orchestrator after ring 4 Ring Gate pass   |
+| `devStatus`, `devUrl`, `devBlockers`           | Developer                                  |
+| `uiReviewStatus`, `uiReworkRound`, `loadCheck` | Reviewer                                   |
+
+Sub-agents **MUST NOT** change `iteration` or `loop`. They request orchestrator via `next_orchestrator_action`.
+
+## UI rework sequence (ring 4 verify, orchestrator-owned)
+
+During ring 4 `loop: verify`:
+
+1. **Reviewer** (`ui_diff`) — screenshots vs locked ASR → fail: UI Diff Report in `review-report.md`, `uiReworkRound` +1, handoff `next_orchestrator_action: "Invoke routed agents per review-report, then @reviewer ui_diff"` → STOP.
+2. **Orchestrator** — invoke `@developer` / `@technical-artist` / `@artist` per Action Items (`routeTo`).
+3. **Fix agents** — apply fixes → handoff `Invoke @reviewer ui_diff` → STOP.
+4. **Orchestrator** — invoke `@reviewer ui_diff` again; on pass → `npm run ring:gate -- --iteration 4` → Ring Gate.
+
+Max **5** UI rework rounds (`uiReworkRound`). At 5 → orchestrator decision (proceed to Ring Gate or escalate to user).
+
+Gameplay quality = user judgment at Ring Gate — Reviewer checks conformance + load safety only.
+
+## Optimization sequence (optional, ring 4+)
+
+Optional deep pass after ring 4 `ui_diff` pass and before final Ring Gate (or user requests "optimize"):
 
-Example (update only your row when track complete):
+1. **Orchestrator** — invoke `@reviewer playable_validate` (may already be part of ring 3 DoD).
+2. **Reviewer** — `verify:ui` → `record:mp4` headed → video validate rules → write report + routeTo → STOP.
+3. **Orchestrator** — route fixes or proceed to Ring Gate.
 
-| Wave | Agent            | Status | Notes                                               |
-| ---- | ---------------- | ------ | --------------------------------------------------- |
-| 1    | Designer         | done   | Ph.2: BGM + SFX + digit strip; VisualAtoms ASR-done |
-| 2    | Technical Artist | done   | All TA atoms + Compliance green                     |
+Max **3** optimization rounds (at 3 → orchestrator decision).
 
-Checkpoint is a **human log** for context — **not** the routing source (handoff is).
+## Spec Gap Protocol
 
-## Stage field ownership
+`spec-gap` means an upstream contract hole is blocking downstream work.
 
-| Field / transition                                                                                                              | Writer                                    |
-| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| `gates.#N = pending`                                                                                                            | Sub-agent before STOP                     |
-| `gates.#N = passed`                                                                                                             | **Orchestrator** after user confirms Gate |
-| Mainline `stage` (`pm` → `style_exploration` → `production` → `ui_pass` → `ui_review` → `ui_rework` → `gameplay_pass` → `done`) | **Orchestrator only**                     |
-| `selectedMcOption`                                                                                                              | Orchestrator after Gate #2a               |
-| `devStatus`, `devUrl`, `devBlockers`                                                                                            | Developer                                 |
-| `uiReviewStatus`, `uiReworkRound`, `loadCheck`                                                                                  | Reviewer                                  |
+| Trigger role | Typical trigger                                              | Required action                                                      |
+| ------------ | ------------------------------------------------------------ | -------------------------------------------------------------------- |
+| TA           | Missing size/format/path/atlas clarity in `layout-spec.md`   | Write `spec-gap` into `project-state.md` and route to Game Designer  |
+| Developer    | Missing contract path, unclear asset binding, atom ambiguity | Record blocker in `devBlockers` / handoff and route to Game Designer |
 
-Sub-agents **MUST NOT** set mainline `stage`. They request orchestrator via `next_orchestrator_action` (e.g. `Invoke @reviewer`).
+Rules:
 
-## UI rework sequence (orchestrator-owned)
+- Raise within quick-check, not after long speculative work.
+- Game Designer patches the relevant contract document.
+- Use `block_reason: spec-gap` when the pipeline must pause.
 
-1. **Reviewer** (`ui_diff`) — screenshots vs MC panels → fail: UI Diff Report in `review-report.md`, `uiReworkRound` +1, handoff `next_orchestrator_action: "Set stage=ui_rework, invoke routed agents per review-report"` → STOP (**no** `stage: ui_rework` in reviewer write).
-2. **Orchestrator** — Set `stage: ui_rework`, invoke `@developer` / `@technical-artist` / `@designer` per Action Items (`routeTo`).
-3. **Developer** (primary) — Fix UI issues → `devStatus: ui_ready` → handoff `Invoke @reviewer ui_diff` → STOP.
-4. **Orchestrator** — Invoke `@reviewer ui_diff` again; on pass (or `uiReworkRound == 5`) → `stage: gameplay_pass`.
+## Intent Clarification Protocol (ICP)
 
-Max **5** UI rework rounds. Gameplay has no AI rework loop — only `load_check` before Gate #3.
+Primary file: `docs/intent-clarifications.md`
+
+- Continue with reasonable assumptions when safe.
+- Use ICP when ambiguity materially affects direction, quality, or delivery.
+- Game Designer arbitrates gameplay/spec intent conflicts.
+- Orchestrator does not interrupt the user for internal ICP traffic.
+
+| Need                                                 | Route               |
+| ---------------------------------------------------- | ------------------- |
+| Contract ambiguity, gameplay vs spec conflict        | `@game-designer`    |
+| Missing visual sample / supplementary isolated asset | `@artist`           |
+| Asset production / format / atlas / extraction issue | `@technical-artist` |
+| Runtime binding / implementation path issue          | `@developer`        |
 
 ## Master Composite — five panels
 
-| Name                  | Panel | `playcraft-storyboard` label                      | Role                                                                     |
-| --------------------- | ----- | ------------------------------------------------- | ------------------------------------------------------------------------ |
-| **Concept panel**     | 1     | Main Gameplay                                     | All key element types + static text + full UI; TA primary extract source |
-| **Storyboard panels** | 2–5   | Hook / Onboarding / End Card / CTA Always Visible | Per-stage visual intent; Developer scene reference                       |
+| Name                  | Panel | Role                                                                     |
+| --------------------- | ----- | ------------------------------------------------------------------------ |
+| **Concept panel**     | 1     | All key element types + static text + full UI; TA primary extract source |
+| **Storyboard panels** | 2–5   | Hook / Onboarding / End Card / CTA — Developer scene reference           |
+
+Produced during ring 3 style direction (storyboard subagent or Artist flow).
 
 ## User interaction model (three phases)
 
-| Phase                | User                                                            | Agents                                                                              |
-| -------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| **A — Choose**       | **Orchestrator only** — `AskUserQuestion` for Gate #1, #2a, #2b | Sub-agents STOP when gate materials ready; no mass production until Gate #2b passed |
-| **B — Produce**      | Not interrupted for terminal commands                           | Serial: Designer Ph.2 → TA → Developer (`ui_pass` → `gameplay_pass`)                |
-| **C — Dev delivery** | **Gate #3 only**: open **devUrl** from orchestrator             | Developer UI+gameplay → Reviewer `load_check` → user accepts gameplay in browser    |
+| Phase                | User                                                                                           | Agents                                                                                           |
+| -------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| **A — Choose**       | Game Designer brainstorms during `loop: clarify`; **Orchestrator** confirms each **Ring Gate** | Sub-agents STOP when loop complete; minimal user interruption during build                       |
+| **B — Produce**      | Not interrupted for terminal commands                                                          | Serial ring 4: Artist Wave 1 → TA Wave 2 → Developer integration; UI rework during ring 4 verify |
+| **C — Dev delivery** | Open **devUrl** (with `?debug=1`) from orchestrator at each **Ring Gate**                      | Developer owns dev preview; Reviewer conformance; user judges fun/quality at Ring Gate           |
 
 **User never runs `npm run dev`.** Delivery endpoint = Dev URL acceptance (`done`), not `playcraft build`.
 
 ## Agent responsibility matrix (priority order)
 
-| #        | PM                                                        | Designer                                                          | Technical Artist                                                 | Developer                                                        | Reviewer                                         |
-| -------- | --------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
-| **1**    | Define experience + gameplay (`design-brief`, flow)       | Lock visual + narrative — **MC = UI spec for Developer**          | Style-faithful mass production from MC/ASR                       | **UI shell** (`ui_pass`: layout + scene switch)                  | `design_check` before Gates; `ui_diff` vs MC     |
-| **2**    | Zero-ambiguity contracts (`layout-spec`, `atom-plan`)     | Handoff Pack: ASR Coverage Matrix, Palette Locked, Motion Notes   | 100% `assetMapping` at spec (path check only)                    | **Gameplay** (`gameplay_pass`: PGS, first level success)         | `load_check` before Gate #3                      |
-| **3**    | Gates + ICP; **spec-gap** vs **asset rework** arbitration | Audio + digit strip; **respond to Developer visual/audio rework** | Production-grade assets; **respond on `routeTo: ta` in ui_diff** | **Dev preview owner** (`npm run dev`, devUrl, upstream blockers) | Route UI issues in ui_diff; no gameplay AI audit |
-| **Last** | —                                                         | —                                                                 | —                                                                | `playcraft build` = **future**, not `done`                       | —                                                |
+| #        | Game Designer                                            | Artist                                                       | Technical Artist                                     | Developer                                                  | Reviewer                                           |
+| -------- | -------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------- |
+| **1**    | Experience contracts per ring (`DESIGN`, layout-spec, …) | Placeholder (ring 1–2) → ASR/style (ring 3) → audio (ring 4) | Style-faithful mass production (ring 4)              | Build-loop convergence + dev preview ownership             | `gameplay_conformance` + `load_check` every verify |
+| **2**    | Zero-ambiguity specs (depth grows per ring)              | ASR Coverage Matrix, Palette Locked (ring 3+)                | 100% `assetMapping` at spec (ring 4)                 | Placeholder-first assets (rings 1–3); integration (ring 4) | `playable_validate` (ring 3+), `ui_diff` (ring 4)  |
+| **3**    | ICP; spec-gap arbitration                                | Style Intent Notes; respond to rework routes                 | Bulk production; respond on `routeTo: ta` in ui_diff | `devUrl` / `devBlockers`; route upstream via ICP           | Fill Ring DoD Fields; increment `uiReworkRound`    |
+| **Last** | —                                                        | —                                                            | —                                                    | `playcraft build` = **future**, not `done`                 | —                                                  |
 
 Full detail: `.claude/agents/<role>.md` § Goals.
 
@@ -146,152 +305,87 @@ Full detail: `.claude/agents/<role>.md` § Goals.
 ```
 <project-root>/                     ← playcraft create <name> 初始化后
 │
-├── CLAUDE.md                       ✅ 已存在（协作总纲）
-├── .claude/agents/                 ✅ 已存在（5 个 Agent 指令 + refs/ 详细参考）
-│   ├── pm.md                       PM（项目管理）
-│   ├── designer.md                 Designer（设计）
-│   ├── technical-artist.md         Technical Artist（技术美术）
-│   ├── developer.md                Developer（开发）
-│   ├── reviewer.md                 Reviewer（审核）
-│   └── refs/                       L2 按需细则
-├── .claude/skills/                 ✅ 已存在（平台工具 Skill）
-├── .claude/settings.local.json     ✅ 模板（权限白名单，见文件内说明）
-├── .cursor/rules/                  ✅ 编排与边界规则（Cursor 主会话）
-├── .cursor/hooks.json              ✅ Cursor subagentStop → validate-workflow-stop
-├── .claude/settings.json           ✅ Claude Code SubagentStop hooks（可提交）
-├── .claude/hooks/                  ✅ 共享校验脚本（见 README）
-├── docs/team/agent-conduct.md      ✅ 已存在（MUST/NEVER 行为契约）
-├── templates/                      ✅ 已存在（只读，Agent 创建文档时参考）
-├── .gitignore                      ✅ 已存在
-│
-├── ta-workspace/scripts/           ✅ 已存在（TA 写 Node.js 批量脚本，入库）
-├── ta-workspace/logs/              ✅ 已存在（gitkeep，脚本日志不入库）
-├── ta-workspace/tmp/               ✅ 已存在（gitkeep，临时产物不入库）
-│
-├── assets/images/{bg,tiles,ui,vfx,reference}/  ✅ 已存在（gitkeep 占位；reference = ASR 双板）
-├── assets/audio/{bgm,sfx}/           ✅ 已存在（gitkeep 占位）
-├── assets/models/                    ✅ 已存在（gitkeep 占位，3D GLB 资产）
-├── assets/bundles/                   ✅ 已存在（gitkeep 占位）
-│
-│   以下目录/文件在 playcraft create 时为空，由 Agent 运行时填充：
-│
-├── docs/project-state.md           ⏳ PM 创建
-├── docs/design-brief.md            ⏳ PM 创建
-├── docs/layout-spec.md             ⏳ PM 创建
-├── docs/atom-plan.json             ⏳ PM 创建（skillsMatch + atoms[] DAG）
-├── docs/atom-plan.md               ⏳ PM 创建（验收标准 + Context 富集区）
-├── docs/style-exploration.md       ⏳ Designer Phase 1 创建
+├── CLAUDE.md                       ✅ 协作总纲 (growth-rings-v1)
+├── .claude/agents/                 ✅ 5 个 Agent 指令 + refs/
+├── docs/team/agent-conduct.md      ✅ MUST/NEVER 行为契约
+├── templates/                      ✅ 只读模板
 │
-├── assets/images/**                ⏳ Designer (样本) + TA (补全)
-├── assets/audio/**                 ⏳ Designer (生成) + TA (后处理)
-├── assets/models/**                ⏳ TA (3D 管线)
-├── assets/bundles/**               ⏳ Designer + TA (atom 封包)
+├── docs/project-state.json         ⏳ state-store machine truth
+├── docs/project-state.md           ⏳ generated read-only view
+├── docs/DESIGN.md                  ⏳ Ring 1 clarify（唯一交付物）
+├── docs/design-brief.md            ⏳ Ring 2+ 过程日志（Ring 1 不创建）
+├── docs/atom-tree.json             ⏳ 逐环增长
+├── docs/layout-spec.md             ⏳ Ring 2+ clarify
+├── docs/implementation-plan.md     ⏳ Ring 2+ build 前
+├── docs/style-exploration.md       ⏳ Ring 3+
 │
-├── game/gameplay/                  ⏳ Developer Phase 1
-├── game/config/                    ⏳ Developer Phase 1
-├── game/scenes/                    ⏳ Developer Phase 1
-├── game/index.html                 ⏳ Developer Phase 1 + 2
-│
-├── logs/designer-log.md            ⏳ Designer
-├── logs/ta-log.md                  ⏳ Technical Artist
-├── logs/developer-log.md           ⏳ Developer
-└── logs/review-report.md           ⏳ Reviewer
+├── game/**                         ⏳ Developer build loop
+├── assets/**                       ⏳ Artist + TA (深度随环递进)
+└── logs/*.md                       ⏳ 各角色工作日志
 ```
 
 ## Directory Conventions
 
-**All agents MUST follow this structure.**
-
 ```
 <project-root>/
-├── docs/                  Design documents (PM creates, all agents reference)
-├── assets/
-│   ├── images/{bg,tiles,ui,vfx,reference}   Visual assets (ASR in reference/; samples + TA completions)
-│   ├── audio/{bgm,sfx}       Audio assets (Designer generates, TA post-processes)
-│   ├── models/                3D GLB assets (TA production)
-│   └── bundles/               Atom bundles (Designer + TA create)
-├── game/
-│   ├── gameplay/              PGS + state machine (Developer)
-│   ├── config/                Level configs (Developer)
-│   ├── scenes/                Scene definitions (Developer)
-│   └── index.html             Entry point (Developer)
+├── docs/                  Design documents
+├── assets/                Visual/audio/model assets
+├── game/                  Runtime code (Developer)
 ├── logs/                  Work logs + review report
-├── ta-workspace/          TA batch scripts + temp files
+├── ta-workspace/          TA batch scripts + temp
 └── templates/             Read-only reference templates
 ```
 
 ## File Read/Write Matrix
 
-| File/Directory              | PM     | Designer                | **TA**                                | Developer               | Reviewer |
-| --------------------------- | ------ | ----------------------- | ------------------------------------- | ----------------------- | -------- |
-| `docs/project-state.md`     | Create | Update stage            | **Update stage**                      | Update stage            | Read     |
-| `docs/design-brief.md`      | Create | Read                    | **Read**                              | Read                    | Read     |
-| `docs/layout-spec.md`       | Create | **Read (contract)**     | **Read (contract)**                   | **Read (contract)**     | Read     |
-| `docs/atom-plan.json`       | Create | Update `atoms[].status` | Update `atoms[].status`               | Update `atoms[].status` | Read     |
-| `docs/atom-plan.md`         | Create | Asset Skill Context     | TA Skill Context                      | Impl Skill Context      | Read     |
-| `docs/style-exploration.md` | —      | Create (Phase 1)        | **Read**                              | Read                    | Read     |
-| `assets/images/`            | —      | **Create (samples)**    | **Create (completions + processing)** | Read                    | Read     |
-| `assets/audio/`             | —      | **Create**              | **Post-process**                      | Read                    | Read     |
-| `assets/models/`            | —      | —                       | **Create (3D pipeline)**              | Read                    | Read     |
-| `assets/bundles/`           | —      | **Create (partial)**    | **Create (TA atoms)**                 | Read                    | Read     |
-| `game/`                     | —      | —                       | —                                     | **Create**              | Read     |
-| `logs/designer-log.md`      | —      | Create+Update           | Read                                  | Read                    | Read     |
-| `logs/ta-log.md`            | —      | —                       | **Create**                            | Read                    | Read     |
-| `logs/developer-log.md`     | —      | —                       | —                                     | Create+Update           | Read     |
-| `logs/review-report.md`     | —      | —                       | —                                     | —                       | Create   |
-
-**Key**: Designer and TA both write `assets/`, but responsibilities don't overlap:
-
-- Designer: MC + ASR (Phase 1), audio + digit strip + atom status (Phase 2)
-- TA writes completion assets and technically processed production-grade files
-
-## Asset Contract (Asset Path Contract)
-
-`layout-spec.md` defines **element ID → atlas+frame or file path**, **locked after Gate #1**:
-
-- **PM** defines `assetMapping`, **atlas grouping table**, and specs (default: **WebP** images, **MP3** audio)
-- **≥2 elements same class** (tiles / ui / vfx) → one **`.webp` + `.json`** atlas per group; each element has `frameId`
-- **Exceptions**: full-screen bg (single webp), digit strip (single webp), MC/ASR reference (non-runtime)
-- **Designer** delivers MP3 audio + digit strip webp at contracted paths
-- **TA** delivers runtime atlases + post-processed MP3 per [ta-atlas-deliverable-standard.md](../../.claude/agents/refs/ta-atlas-deliverable-standard.md)
-- **Developer** (`ui_pass` / `gameplay_pass`) binds `loadImage`/atlas+frame at contract paths with **real files** on disk, then integrates in Dev
-- **Path / frame mismatch = integration failure** — TA Compliance + Reviewer check
-- **No unilateral path changes** — PM + user-approved contract change only
+| File/Directory              | Game Designer    | Artist              | **TA**                   | Developer                     | Reviewer         |
+| --------------------------- | ---------------- | ------------------- | ------------------------ | ----------------------------- | ---------------- |
+| `docs/project-state.json`   | via `state:set`  | via `state:set`     | via `state:set`          | via `state:set` / `dev:start` | via `state:set`  |
+| `docs/project-state.md`     | Generated view   | Do not edit/open    | Do not edit/open         | Do not edit/open              | Do not edit/open |
+| `docs/design-brief.md`      | Create           | Read                | Read                     | Read                          | Read             |
+| `docs/layout-spec.md`       | Create (ring 2+) | **Read (contract)** | **Read (contract)**      | **Read (contract)**           | Read             |
+| `docs/atom-tree.json`       | Read             | Read                | Read                     | Read                          | Read             |
+| `docs/style-exploration.md` | —                | Create (ring 3+)    | **Read**                 | Read                          | Read             |
+| `assets/images/`            | —                | **Create**          | **Create (completions)** | Read                          | Read             |
+| `assets/audio/`             | —                | **Create**          | **Post-process**         | Read                          | Read             |
+| `game/`                     | —                | —                   | —                        | **Create / Update**           | Read             |
+| `logs/artist-log.md`        | —                | Create+Update       | Read                     | Read                          | Read             |
+| `logs/ta-log.md`            | —                | —                   | **Create**               | Read                          | Read             |
+| `logs/developer-log.md`     | —                | —                   | —                        | Create+Update                 | Read             |
+| `logs/review-report.md`     | —                | —                   | —                        | —                             | Create           |
 
 ## Four-doc discipline
 
-PM and Designer **own different layers**; TA and Developer **read all layers** at wave start (Upstream Intake).
+| Layer                | Files                                                 | Writer                             | Content rule                                      |
+| -------------------- | ----------------------------------------------------- | ---------------------------------- | ------------------------------------------------- |
+| **Contracts**        | `project-state`, `DESIGN`, `layout-spec`, `atom-tree` | Game Designer + temporary ref-flow | Key fields only — no process chatter in contracts |
+| **Visual narrative** | `style-exploration`, `logs/artist-log`                | Artist                             | MC/ASR intent, Handoff Pack, Coverage Matrix      |
+| **Production proof** | `logs/ta-log`, `logs/developer-log`                   | TA / Developer                     | Upstream Intake + pipeline / implementation logs  |
 
-| Layer                  | Files                                                                                                                                   | Writer                                         | Content rule                                                                                                                       |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| **Contracts (四件套)** | `project-state`, `design-brief`, `layout-spec`, `atom-plan`（**`atom-plan.json`** 机器契约 + **`atom-plan.md`** Gate #1 仅 Acceptance） | PM (Designer: read-only except ICP path fixes) | **Key fields only** — decisions, paths, DAG (`atoms[]`), status. No hex in brief; no Atom List mirror; no prompts or MC/ASR prose. |
-| **Visual narrative**   | `style-exploration`, `logs/designer-log`                                                                                                | Designer                                       | MC/ASR intent, Handoff Pack, Coverage Matrix, Style Intent Notes                                                                   |
-| **Production proof**   | `logs/ta-log`, `logs/developer-log`                                                                                                     | TA / Developer                                 | Upstream Intake table (mandatory), then pipeline / implementation logs                                                             |
-
-Enforceable rules: [agent-conduct.md](agent-conduct.md) (§ PM / Designer / TA / Developer). L2: `ta-pipeline-cookbook.md` Step 0a, `developer-phase1-flow.md` Step 0.
+Enforceable rules: [agent-conduct.md](agent-conduct.md).
 
 ## Spec Quick-Check
 
-Within 30 seconds of each wave start, the active agent validates Layout Spec:
-
-| Checker   | When                                                       | Checks                                               | On Gap                                                            |
-| --------- | ---------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
-| TA        | Production Pipeline Wave 2 (TA entry)                      | Every assetMapping entry has clear size/format specs | Write `spec-gap` to project-state.md, PM supplements within 5 min |
-| Developer | `ui_pass` / `gameplay_pass` start (after TA Wave 2 `done`) | Every GameplayAtom reference exists in assetMapping  | Same                                                              |
+Within 30 seconds at loop entry:
 
-## DAG Modification Protocol
-
-- **Default**: Follow PM's plan
-- **Allowed**: Add/remove/modify atoms — update `atom-plan.json` `atoms[]` + record in `atom-plan.md` § DAG Revisions
-- **Stop for direction changes**: Switching gameplay/style → report back
-- **Reviewer audits**: Every revision evaluated for reasonableness
+| Checker   | When                            | Checks                                                        | On Gap                                                                       |
+| --------- | ------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| TA        | Ring 4 build, Wave 2 (TA entry) | Every assetMapping entry has clear size/format specs          | Write `spec-gap` to project-state.md, Game Designer supplements within 5 min |
+| Developer | Any `loop: build` start         | Every GameplayAtom reference exists in assetMapping (ring 2+) | Same                                                                         |
 
 ## Upstream rework routing (Dev blockers)
 
-| `routeTo`    | Trigger                                                              | Orchestrator action                               |
-| ------------ | -------------------------------------------------------------------- | ------------------------------------------------- |
-| **TA**       | Missing file, wrong size/format, style drift in mass-produced assets | Re-invoke `@technical-artist` → then `@developer` |
-| **Designer** | Wrong/missing sample, audio mood, supplementary art                  | Re-invoke `@designer` → then `@developer`         |
-| **PM**       | Contract ambiguity, gameplay vs spec conflict                        | `@pm` arbitrates ICP → then `@developer`          |
+| `routeTo`         | Trigger                                                              | Orchestrator action                                 |
+| ----------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
+| **TA**            | Missing file, wrong size/format, style drift in mass-produced assets | Re-invoke `@technical-artist` → then `@developer`   |
+| **Artist**        | Wrong/missing sample, audio mood, supplementary art                  | Re-invoke `@artist` → then `@developer`             |
+| **Game Designer** | Contract ambiguity, gameplay vs spec conflict                        | `@game-designer` arbitrates ICP → then `@developer` |
 
 Developer sets `devStatus: blocked_upstream` and **STOPs** until rework completes.
+
+## Selection Revision Protocol
+
+- **Default**: follow current shortlist from `atom-tree.*`
+- **Allowed**: refine `meta.selectedAtoms`, `skillsMatch`, reusable media when new evidence appears
+- **Record where**: `docs/atom-tree.json` + `docs/atom-tree.md` § Revision Notes
+- **Stop for direction changes**: switching gameplay/style/product direction → report back