@playcraft/cli 0.0.44 → 0.0.47

package/project-template/docs/project-state.md

@@ -0,0 +1,211 @@
+# Project State
+
+> **Agent entry**: run `npm run state:get` first. Use its summary (`iteration`, `loop`, `nextCommands`, required/deferred files). Do **not** read this entire file during Ring 1 — the handoff YAML block below is the machine source of truth.
+
+## Workflow spec
+
+| Field                   | Value                                                                 |
+| ----------------------- | --------------------------------------------------------------------- |
+| **templateVersion**     | `0.3.2-alpha.0`                                                       |
+| **workflowSpecVersion** | `growth-rings-v1`                                                     |
+| **Template Changelog**  | [CHANGELOG.md](../CHANGELOG.md)                                       |
+| **Workflow Changelog**  | [docs/team/workflow-changelog.md](../docs/team/workflow-changelog.md) |
+
+## Ring Gate Scope
+
+| Field            | Value                                                                                                     |
+| ---------------- | --------------------------------------------------------------------------------------------------------- |
+| ringGatePolicy   | `ring gate checks objective DoD verifiers + non-regression of prior rings + user-decision readiness only` |
+| ringGateExcludes | `subjective quality judgment, gameplay fun, final visual taste, user preference choice`                   |
+
+## Settings
+
+| Field                  | Value   | Description                                                                                  |
+| ---------------------- | ------- | -------------------------------------------------------------------------------------------- |
+| **designerAutoDecide** | `false` | When `true`, Game Designer may self-decide simple/obvious questions without asking the user. |
+
+<!--
+  designerAutoDecide:
+    false (default) = Designer asks the user every brainstorm question via AskUserQuestion.
+    true            = Designer may auto-decide questions that have an obvious best answer based on
+                      genre convention, research, or hard constraints. Auto-decisions are logged in
+                      design-brief.md as [AGENT-AUTO] with reasoning. The user can override any
+                      auto-decision in subsequent rounds.
+
+  Only affects brainstorm questions. Ring Gate confirmations remain orchestrator-only regardless.
+-->
+
+<!--
+  growth-rings-v1: Four growth rings climb the atom-tree from engine root upward.
+  Each ring runs clarify → build → verify inner loops with full role collaboration.
+  Objective DoD verifiers replace pre-development document packages.
+-->
+
+## User Intent
+
+> {{user_intent — ≤2 sentences; do NOT restate Style Direction or five-axis tables from design-brief}}
+
+## Current Iteration
+
+> **Human-readable view.** The machine source of truth is the `## Agent handoff` YAML block below (`iteration:` + `loop:` + `ringGate:` + `ringDoD:`). `workflow-doctor` and agents read that block; keep this prose in sync for humans.
+
+**Iteration 1** — engine-root + core gameplay (placeholder art)
+
+`1 (engine-root → core gameplay)` → `2 (gameplay + periphery)` → `3 (playable ad hook/CTA)` → `4 (production + architecture)` → `done`
+
+Each iteration runs inner loops: `clarify` → `build` → `verify` → **Ring Gate** (user acceptance) → next iteration.
+
+<!-- Iteration definitions: see CLAUDE.md § Growth-Ring Model -->
+
+## Ring DoD (current iteration)
+
+> Objective Definition-of-Done for the **current** growth ring. Orchestrator runs `npm run ring:gate -- --iteration N` to update verifier status.
+> **Human-readable view.** Machine source of truth is `ringDoD:` in the `## Agent handoff` YAML block.
+
+| Check         | Status  | Verifier                      | Notes                                                              |
+| ------------- | ------- | ----------------------------- | ------------------------------------------------------------------ |
+| contract      | pending | `npm run verify:contract`     | Engine boots; neutral runtime contract wired (`window.__playable`) |
+| lifecycle     | pending | `npm run verify:lifecycle`    | Ring 1: starts at HOOK and autoPlay reaches ENDCARD without MP4    |
+| firstLevelWin | pending | `npm run verify:firstwin`     | Ring 1: headless autoPlay reaches ENDCARD (first level winnable)   |
+| placeholders  | pending | `npm run verify:placeholders` | Ring 1: semantic placeholder files exist for loaded asset paths    |
+
+> Future-ring DoD checks are hidden at Ring 1. Run `npm run state:get` after each loop/ring transition to see the active verifier set.
+
+## Ring Gate
+
+> Only the **orchestrator** runs `AskUserQuestion` toward the user. Sub-agents set `ringGate: pending` and STOP.
+> One Ring Gate per iteration replaces the old six waterfall gates.
+
+| Field      | Value      | Notes                                                                       |
+| ---------- | ---------- | --------------------------------------------------------------------------- |
+| ringGate   | pending    | Orchestrator confirms after all ring DoD checks pass + user plays at devUrl |
+| iteration  | {{1..4}}   | Current growth ring                                                         |
+| canAskUser | {{yes/no}} | Set by `ring:gate` runner — only `yes` when all DoD checks pass             |
+
+## Agent handoff
+
+> Sub-agents and orchestrator **must** read/write this block before STOP or invoke. See `docs/team/collaboration.md` § Agent Handoff.
+> This block is the **single machine-readable source of truth** for `iteration`, `loop`, `ringGate`, and `ringDoD`.
+
+```yaml
+iteration: 1
+ringGoal: engine-root + core gameplay (placeholder art)
+loop: clarify
+subagent: none
+subagent_stop: false
+waiting_for: orchestrator
+ringGate: pending
+ringDoD: { contract: pending, lifecycle: pending, firstLevelWin: pending, placeholders: pending }
+archivedRings: {}
+next_orchestrator_action: null
+last_completed_by: null
+block_reason: null
+```
+
+## Handoff Context
+
+> Structured shared working memory. Machine source of truth is `handoffContext` in `docs/project-state.json`; agents read it through `npm run state:get -- --json contextPacket`.
+
+| Area                        | Value                                                  |
+| --------------------------- | ------------------------------------------------------ |
+| ring.summary                | Ring 1 starts as a semantic placeholder playable demo. |
+| lastRole.role               | none                                                   |
+| lastRole.summary            | No sub-agent has completed work yet.                   |
+| nextRole.role               | orchestrator                                           |
+| nextRole.mustKnow           | Run state:get and follow currentAction / nextCommands. |
+| shared.engine               | unset                                                  |
+| shared.coreAction           | unset                                                  |
+| shared.semanticPlaceholders | none                                                   |
+| openQuestions               | none                                                   |
+
+<!--
+Examples (copy structure on STOP — do not leave nulls):
+
+Slice-axis Designer STOP (seed queue):
+  subagent: game-designer
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: clarify
+  next_orchestrator_action: "Invoke @developer per dispatchPacket (slice core-action-feedback-v1)"
+  last_completed_by: game-designer
+
+Slice-axis Developer STOP (after verify:slice + slice:set verified):
+  subagent: developer
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: build
+  next_orchestrator_action: "Invoke @developer per dispatchPacket for next pending slice, or npm run ring:gate when queue drained"
+  last_completed_by: developer
+
+Ring 1 clarify STOP (Designer — legacy, no sliceState):
+  subagent: game-designer
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: clarify
+  next_orchestrator_action: "Spawn temporary ref-flow atom-selection subagent for ring 1 atom-tree selection"
+  last_completed_by: game-designer
+
+Ring 1 atom-tree STOP (temporary ref-flow selector):
+  subagent: skill-selector
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: clarify
+  next_orchestrator_action: "Run scaffold gate, then invoke @developer (legacy ring 1 build loop, or dispatchPacket when slice queue exists)"
+  last_completed_by: skill-selector
+
+Ring 1 build STOP (Developer):
+  subagent: developer
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: build
+  next_orchestrator_action: "npm run ring:gate -- --iteration 1"
+  last_completed_by: developer
+
+Ring 1 verify (orchestrator — no Reviewer invoke):
+  subagent: none
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: verify
+  next_orchestrator_action: "npm run ring:gate -- --iteration 1"
+  last_completed_by: developer
+
+Ring 2+ verify STOP (Reviewer — after load_check pass):
+
+Orchestrator after ring:gate pass (ringGateCanAskUser: yes):
+  subagent: none
+  subagent_stop: true
+  waiting_for: user_gate
+  loop: verify
+  next_orchestrator_action: "Run Ring Gate AskUserQuestion for iteration 1"
+  last_completed_by: orchestrator
+
+Ring Gate pass → iteration 2:
+  iteration: 2
+  ringGoal: gameplay + periphery (HUD / flow skeleton)
+  loop: clarify
+  ringGate: pending
+  ringDoD: resolved by state:get / ring-config for the active iteration
+  archivedRings: { 1: { contract: passed, lifecycle: passed, firstLevelWin: passed } }
+-->
+
+<!--
+  Deferred human tables (Ring Gate Runner, Archived Rings, Dev Preview, Progress Checkpoint, …)
+  are updated by npm run state:set / ring:gate. Full field reference: docs/team/collaboration.md
+-->
+
+## File Index (current ring)
+
+> Current-ring files only. Future Ring files stay hidden until `state:get` discloses them.
+
+### Current Package (Ring 1 — engine root + core gameplay)
+
+| File                                      | Description                                             | Status     |
+| ----------------------------------------- | ------------------------------------------------------- | ---------- |
+| [DESIGN.md](docs/DESIGN.md)               | Player experience contract: core loop + first-level win | {{status}} |
+| [developer-log.md](logs/developer-log.md) | Developer work log + devUrl                             | {{status}} |
+| `game/gameplay/`                          | PGS + state machine                                     | {{status}} |
+| `game/config/`                            | Level configuration                                     | {{status}} |
+| `game/scenes/`                            | Scene definitions                                       | {{status}} |
+| `game/index.html`                         | Entry point                                             | {{status}} |
+
+> Hidden until later Rings: `docs/design-brief.md`, `docs/layout-spec.md`, `docs/implementation-plan.md`, `docs/style-exploration.md`, `logs/artist-log.md`, `logs/ta-log.md`, `logs/review-report.md`, production pipeline.

package/project-template/docs/team/agent-conduct.md

@@ -2,120 +2,66 @@
 
 > Single source for enforceable behavior. When this conflicts with workflow shortcuts, **this wins** (except where an agent Goals § Core responsibilities explicitly overrides for that role).
 >
-> Gate flow detail: [collaboration.md § Gate Protocol](collaboration.md#gate-protocol-orchestrator-only). STOP fields: [§ STOP sync checklist](collaboration.md#stop-sync-checklist).
+> Ring Gate flow: [collaboration.md § Ring Gate Protocol](collaboration.md#ring-gate-protocol-orchestrator-only). STOP fields: [§ STOP sync checklist](collaboration.md#stop-sync-checklist). Hook enforcement: `.claude/hooks/validate-workflow-stop.mjs`.
 
 ## Invoke protocol (all sub-agents)
 
 On every invoke, in order:
 
-1. Read `docs/project-state.md` → parse **`## Agent handoff`** YAML (routing truth — not Progress Checkpoint alone).
-2. Read **this role's `## Runtime`** in `.claude/agents/<role>.md` → pick **one** branch.
-3. Read `refs/` or SKILL **only when** Runtime or that branch says so — do not read long Workflow first.
+1. Run `npm run state:get` → read `contextPacket` first, then the handoff summary (routing truth — not Progress Checkpoint alone). `docs/project-state.md` is a generated view; never open or hand-edit it.
+2. Read **this role's L1 role card** in `.claude/agents/<role>.md` to understand role ownership, boundaries, and current workflow interface.
+3. Read the specific workflow / `refs/` / SKILL documents **only when** the current task or workflow interface says so — do not load long workflow docs by default.
 4. On STOP: complete [§ STOP sync checklist](collaboration.md#stop-sync-checklist).
 
 ## All roles (including Orchestrator)
 
-|              | Rule                                                                                                                      |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------- |
-| **MUST**     | Read `docs/project-state.md` before any work; parse `## Agent handoff` YAML; resume from Progress Checkpoint when present |
-| **MUST**     | Update `docs/project-state.md` Progress Checkpoint when finishing a major step                                            |
-| **MUST**     | On STOP: update `## Agent handoff` (`subagent_stop: true`, `next_orchestrator_action` required)                           |
-| **MUST NOT** | Change `layout-spec.md` `assetMapping` paths after Gate #1 without PM + user-approved contract change                     |
-| **MUST NOT** | Treat `playcraft build` as required for `done` — endpoint is **user acceptance at devUrl**                                |
-| **MUST NOT** | Ask the **user** to run `npm run dev` (Gate #3 = open orchestrator-provided link only)                                    |
+|              | Rule                                                                                                                                                        |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Run `npm run state:get` before any work (never open the generated `docs/project-state.md`); start from `contextPacket`, then follow required files          |
+| **MUST**     | Append a Progress Checkpoint when finishing a major step via `npm run state:set -- --checkpoint "…" --by <role>`                                            |
+| **MUST**     | On STOP: write `handoffContext` for the next role, then `npm run state:set -- subagent_stop=true next_orchestrator_action="…"` (context + routing required) |
+| **MUST NOT** | Change `layout-spec.md` `assetMapping` paths after ring 4 (`assetMappingLocked: true`) without Game Designer + user-approved contract change                |
+| **MUST NOT** | Treat `playcraft build` as required for `done` — endpoint is **user acceptance at devUrl**                                                                  |
+| **MUST NOT** | Ask the **user** to run `npm run dev` (Ring Gate = open orchestrator-provided link only)                                                                    |
 
 ## Orchestrator only
 
-|              | Rule                                                                                                                                             |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **MUST**     | Be the **only** role that uses `AskUserQuestion` toward the user (Gate #1, #2a, #2b, #3)                                                         |
-| **MUST**     | After any sub-agent STOP, read `## Agent handoff` in `project-state.md` before spawn / resume / Gate                                             |
-| **MUST**     | After any sub-agent STOP, verify: all atoms `status ≠ pending`, `actualOutput` files exist, Context sections filled, Skill Preflight done        |
-| **MUST**     | If `gate_pending` is non-null and `waiting_for: user_gate`, run **only** the matching Gate (`AskUserQuestion`) — **do not** invoke sub-agents    |
-| **MUST**     | If `subagent_stop: true` and `waiting_for: orchestrator`, execute **only** `next_orchestrator_action`                                            |
-| **MUST**     | Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, set `subagent` to target role)                                        |
-| **MUST**     | Dispatch = WHAT + skill refs + constraints only; do NOT write detailed production steps for sub-agents                                           |
-| **MUST**     | Run Reviewer `design_check` before Gate #1 and Gate #2b — do **not** ask user until Reviewer passes soft checklist                               |
-| **MUST NOT** | Role-play all five agents in one session when sub-agent invoke is available                                                                      |
-| **MUST NOT** | Skip Gate #2a / #2b while gates are `pending`                                                                                                    |
-| **MUST NOT** | Invoke `@technical-artist` before Production Pipeline Wave 1 (Designer Ph.2) is `done`                                                           |
-| **MUST NOT** | Invoke `@developer` or set `stage: ui_pass` before Production Pipeline Wave 2 (TA) is `done`                                                     |
-| **MUST NOT** | Spawn `@developer` during `stage: production` (serial workflow: Designer → TA → Developer ui_pass)                                               |
-| **MUST NOT** | Advance mainline `stage` when a sub-agent could do it — **orchestrator owns** `stage` transitions (see collaboration.md § Stage field ownership) |
-| **MUST NOT** | Advance to next stage if post-STOP verification fails (atom status, actualOutput, Context, Skill Preflight)                                      |
-
-## Sub-agents only (PM, Designer, TA, Developer, Reviewer)
-
-|              | Rule                                                                                                                                                                                                  |
-| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **MUST NOT** | Use `AskUserQuestion` or present Gate choices to the user                                                                                                                                             |
-| **MUST**     | On Gate-ready materials: sync `gates.#N = pending` + handoff (`gate_pending`, `waiting_for: user_gate`) → **STOP**                                                                                    |
-| **MUST**     | Run Spec Quick-Check within 30s: TA when starting production Wave 2; Developer when starting `ui_pass`                                                                                                |
-| **MUST**     | Update `atom-plan.json` → `atoms[].status` + `atoms[].actualOutput` upon completing each assigned atom — never leave `pending` after delivery                                                         |
-| **MUST**     | Fill corresponding `atom-plan.md` § Context section (Asset / TA / Impl Skill Context) — never leave `(Pending)` after delivery                                                                        |
-| **MUST**     | Check `atom-plan.json` → `skillsMatch.mediaGroups` for reusable assets before generating from scratch (Designer/TA)                                                                                   |
-| **MUST**     | Complete Skill Preflight (read relevant platform Skills) before production — TA: `ta-log § Skill Preflight`; Developer: `developer-log § Skill Preflight`; Designer: `designer-log § Skill Preflight` |
-| **MUST NOT** | Continue producing while `subagent_stop: true` and `waiting_for: orchestrator` (resume only when orchestrator clears handoff)                                                                         |
-| **MUST NOT** | Change mainline `stage` (orchestrator only — see collaboration.md § Stage field ownership)                                                                                                            |
-| **MUST NOT** | Skip required logs (`designer-log`, `ta-log`, `developer-log`, `review-report`)                                                                                                                       |
-| **MUST NOT** | Ignore `mediaGroups` matches and generate from scratch when a pre-matched asset exists — link first, skip only with documented reason                                                                 |
-| **MUST**     | Complete [STOP sync checklist](collaboration.md#stop-sync-checklist) on every STOP                                                                                                                    |
-
-### PM (four-doc discipline)
-
-|              | Rule                                                                                                                                                                                                                                                                                           |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **MUST**     | Keep **四件套** contract-only: playable decisions in `design-brief` (no hex — palette in `layout-spec`); paths/zones/specs in `layout-spec`; DAG in **`atom-plan.json`**; acceptance one-liners in **`atom-plan.md`**; status/handoff in `project-state` — **key fields only**, no prose dumps |
-| **MUST**     | Before Gate #1: `playcraft skills match --json` → `docs/atom-plan.json` → `skillsMatch`; bind `GameplayAtom`/`ConfigAtom` `skillRef` only from `skillsMatch.items` (or `null` + `dagRevisions` gap); run `playcraft skills validate-atom-plan`                                                 |
-| **MUST NOT** | Paste long research, full prompts, MC/ASR narrative, or generation logs into the four docs — point downstream to `style-exploration.md` / `logs/designer-log.md` instead                                                                                                                       |
-| **MUST NOT** | Put `playcraft-*` in `skillRef`, or use atomIds absent from `skillsMatch.items` without `dagRevisions` — format: [`atom-plan-format.md`](atom-plan-format.md)                                                                                                                                  |
-| **MUST NOT** | Duplicate the same fact across multiple four-doc files — one canonical home per fact (see `collaboration.md` § Four-doc discipline); Gate #1: no Atom List / DAG Order in `atom-plan.md`; no hex in `design-brief`; no Emotion Target in Experience Flow                                       |
-
-### Designer (four-doc discipline)
-
-|              | Rule                                                                                                                                                                      |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **MUST**     | Put visual narrative, Handoff Pack, ASR tables, and generation notes in **`style-exploration.md`** + **`logs/designer-log.md`** — not in PM's four docs                   |
-| **MUST NOT** | Edit `design-brief.md` or `layout-spec.md` except ICP-driven contract fixes (paths/palette deltas) — do not rewrite gameplay or duplicate PM contracts                    |
-| **MUST**     | When PM needs a contract delta, write **one-line deltas** (e.g. Palette Locked vs layout-spec) in `designer-log.md`; PM patches layout-spec if user/orchestrator approves |
-
-### Technical Artist
-
-|              | Rule                                                                                                                                                                                                                                        |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **MUST**     | Before any asset generation in production Wave 2: complete **Upstream Intake** in `logs/ta-log.md` — Read (tool or `cat`) **四件套** + `docs/style-exploration.md` + `logs/designer-log.md`; tick every row; note one-line takeaway per doc |
-| **MUST**     | Execute `refs/ta-pipeline-cookbook.md` **Step 0a → Step 0** in order after intake                                                                                                                                                           |
-| **MUST NOT** | Start bulk generation or write `ta-log` Style Interpretation until Upstream Intake is complete                                                                                                                                              |
-| **MUST NOT** | Mark TA wave `done` without Upstream Intake + Style Interpretation sections filled                                                                                                                                                          |
-| **MUST**     | Before any asset generation: complete **`logs/ta-log.md` § Production Plan** — Coverage Plan covering 100% `assetMapping`, Atlas Assembly Plan matching layout-spec groups, Risk Checklist all `[x]`                                        |
-| **MUST NOT** | Start bulk generation or write deliverables under `assets/` until Production Plan Risk Checklist is fully checked                                                                                                                           |
-| **MUST**     | Pass **`.claude/hooks/validate-workflow-stop.mjs`** on STOP (Claude `SubagentStop` + Cursor `subagentStop` — see `.claude/hooks/README.md`)                                                                                                 |
-
-### Developer
-
-|              | Rule                                                                                                                                                                                                                                                     |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **MUST**     | Before Spec Quick-Check or any `game/` work in `ui_pass`: complete **Upstream Intake** in `logs/developer-log.md` — Read **四件套** + `docs/style-exploration.md` + `logs/designer-log.md` + `logs/ta-log.md`; tick every row; one-line takeaway per doc |
-| **MUST**     | Execute `refs/developer-phase1-flow.md` **Step 0 → Step 1** in order after intake                                                                                                                                                                        |
-| **MUST NOT** | Start Skill Preflight or edit `game/**` until Upstream Intake is complete                                                                                                                                                                                |
-| **MUST**     | **`ui_pass` scope only**: scene switching, element placement, simple state display — bind real assets at contract paths; **MUST NOT** implement core gameplay rules (scoring, elimination, level logic, win/lose)                                        |
-| **MUST**     | Before `ui_pass` STOP: complete **`logs/developer-log.md` § UI Pass Plan** — Scene-Asset Binding + scene navigation + Risk Checklist all `[x]`                                                                                                           |
-| **MUST**     | Set `devStatus: ui_ready` (not `ready`) after `ui_pass`; handoff `Invoke @reviewer ui_diff`                                                                                                                                                              |
-| **MUST**     | **`gameplay_pass` scope**: add core gameplay on verified UI shell — PGS, first level success, CTA; complete **`logs/developer-log.md` § Gameplay Pass Plan** before gameplay logic                                                                       |
-| **MUST**     | Before any `game/` implementation: for each non-empty `skillRef`, read Recipe + `ref/` from `.claude/skills/<skillRef>/` when link exists; else `playcraft skills read` — log in `developer-log.md` § Skill Preflight                                    |
-| **MUST NOT** | Rewrite UI layout during `gameplay_pass` unless open UI Diff items remain                                                                                                                                                                                |
-| **MUST NOT** | Set `devStatus: ready` while `devBlockers` has open items                                                                                                                                                                                                |
-| **MUST NOT** | Use placeholder assets or silently skip `blocked` atoms                                                                                                                                                                                                  |
-| **MUST**     | Pass **`.claude/hooks/validate-workflow-stop.mjs`** on STOP (plan section validated per stage: UI Pass Plan vs Gameplay Pass Plan)                                                                                                                       |
-
-### Reviewer
-
-|              | Rule                                                                                                                                                                                                   |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **MUST**     | Operate in one of three modes per orchestrator invoke: **`design_check`** \| **`ui_diff`** \| **`load_check`**                                                                                         |
-| **MUST**     | Read **`playwright-cli`** skill before `ui_diff` or `load_check` browser steps                                                                                                                         |
-| **MUST**     | **`design_check`**: soft checklist only — block obvious defects (missing docs, wrong MC ratio, empty assetMapping); do **not** judge subjective design quality                                         |
-| **MUST**     | **`ui_diff`**: screenshot each MC panel scene via `playwright-cli`; compare layout/color/elements; route issues with `routeTo: developer \| ta \| designer`; increment `uiReworkRound` on fail (max 5) |
-| **MUST**     | **`load_check`**: confirm page loads within 10s, no Error-level console logs; do **not** perform gameplay walkthrough                                                                                  |
-| **MUST NOT** | Modify production files (only `logs/review-report.md` + `project-state` checkpoint)                                                                                                                    |
-| **MUST NOT** | Write mainline `stage` — set handoff `next_orchestrator_action` for orchestrator (`Set stage=ui_rework`, `Run Gate #3`, etc.)                                                                          |
+|              | Rule                                                                                                                                                                                              |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Be the **only** role that uses `AskUserQuestion` for **Ring Gate** confirmations (one per growth ring)                                                                                            |
+| **MUST**     | After any sub-agent STOP, run `npm run state:get` to read `contextPacket` and routing handoff before spawn / resume / Ring Gate                                                                   |
+| **MUST**     | After any sub-agent STOP, verify: `handoffContext` complete, ring DoD evidence complete, logs filled, required preflight done                                                                     |
+| **MUST**     | If `waiting_for: user_gate` and `subagent_stop: true` and `ringGateCanAskUser: yes`, run **only** Ring Gate (`AskUserQuestion`) — **do not** invoke sub-agents                                    |
+| **MUST**     | If `subagent_stop: true` and `waiting_for: orchestrator`, execute **only** `next_orchestrator_action`                                                                                             |
+| **MUST**     | Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, set `subagent` to target role)                                                                                         |
+| **MUST**     | Dispatch = WHAT + skill refs + constraints only; do NOT write detailed production steps for sub-agents                                                                                            |
+| **MUST**     | Before Ring Gate: run `npm run ring:gate -- --iteration N` — do **not** ask user until the script returns pass                                                                                    |
+| **MUST**     | Before **ring 1 `loop: build`**: ensure `playcraft remix init-template --from-atom-tree` has run, `.playcraft-engine` matches `meta.engineDecision.adapter`, and `npm run verify:contract` passes |
+| **MUST**     | After ring 1 Game Designer STOP, spawn a temporary ref-flow atom-selection subagent before scaffold; do not select atoms inline as orchestrator                                                   |
+| **MUST**     | Archive Ring Gate snapshots through `ring:gate` / state helpers so the next ring inherits stable decisions, not prior-ring process noise                                                          |
+| **MUST NOT** | Role-play all five agents in one session when sub-agent invoke is available                                                                                                                       |
+| **MUST NOT** | Advance `iteration` without archiving prior ring in `archivedRings` (non-regression)                                                                                                              |
+| **MUST NOT** | Invoke `@technical-artist` before ring 4 Artist Wave 1 is `done`                                                                                                                                  |
+| **MUST NOT** | Advance `iteration` when a sub-agent could do it — **orchestrator owns** `iteration` / `loop` transitions                                                                                         |
+| **MUST NOT** | Advance to next iteration if post-STOP verification fails (required package, logs/evidence, Skill Preflight)                                                                                      |
+
+## Sub-agents only (Game Designer, Artist, TA, Developer, Reviewer)
+
+|              | Rule                                                                                                                                                                                              |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST NOT** | Use `AskUserQuestion` for Ring Gate choices or final confirmations (Ring Gates remain orchestrator-only)                                                                                          |
+| **EXCEPT**   | Game Designer MAY use `AskUserQuestion` for gameplay brainstorm/clarification during `loop: clarify`                                                                                              |
+| **MUST**     | On verify-loop completion: sync `handoffContext` verdict + `ringGate: pending` + handoff (`waiting_for: orchestrator`, `next_orchestrator_action: npm run ring:gate -- --iteration N`) → **STOP** |
+| **MUST**     | Run Spec Quick-Check within 30s: TA when starting ring 4 build; Developer when starting any `loop: build`                                                                                         |
+| **MAY**      | Append concise downstream notes to `atom-tree.md` when actual reading/usage differs from the initial selection                                                                                    |
+| **MUST**     | Check `atom-tree.json` → `mediaGroups` for reusable assets before generating from scratch (Artist/TA)                                                                                             |
+| **MUST**     | Complete Skill Preflight (read relevant platform Skills) before production — TA: `ta-log § Skill Preflight`; Developer: `developer-log § Skill Preflight`; Artist: `artist-log § Skill Preflight` |
+| **MUST NOT** | Continue producing while `subagent_stop: true` and `waiting_for: orchestrator` (resume only when orchestrator clears handoff)                                                                     |
+| **MUST NOT** | Change `iteration` or `loop` (orchestrator only)                                                                                                                                                  |
+| **MUST NOT** | Skip required logs (`artist-log`, `ta-log`, `developer-log`, `review-report`)                                                                                                                     |
+| **MUST NOT** | Ignore `mediaGroups` matches and generate from scratch when a pre-matched asset exists — link/reuse first, skip only with documented reason                                                       |
+| **MUST**     | Complete [STOP sync checklist](collaboration.md#stop-sync-checklist) on every STOP, including structured `handoffContext`                                                                         |
+
+## Tool Surface Policy
+
+Role cards should list only the tools that role actually owns. Long command catalogs belong in role refs or Skills. If a command family moves to a specialist role, remove it from upstream roles instead of duplicating it.