Release 1.1.2 — the default path works end to end

Fix release for 1.1.1: the minimal path end to end, engine commands that run on Godot, Unity and Unreal, hook warnings you can see, and verdicts that say when they could not check. Details in CHANGELOG.md; upgrade steps in UPGRADING.md (v1.1.1 → v1.1.2). Fixes #67 Fixes #131 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WuJn2FdynEybfL5KC697nJ
2026-10-16 01:37:05 +00:00 · 2026-09-29 21:32:19 +10:00
parent 7ed2c3e9c4
commit b21fa0f7f2
383 changed files with 22888 additions and 10618 deletions
@@ -5,14 +5,18 @@ The following agents are available. Each has a dedicated definition file in
 spans multiple domains, the coordinating agent (usually `producer` or the
 domain lead) should delegate to specialists.

-## Tier 1 -- Leadership Agents (Opus)
+Which model an agent runs on is set by the `model:` line in its own file;
+`model-tiers.md` lists the agents that pin one. Every other agent runs on the
+session's model.
+
+## Tier 1 -- Leadership Agents
 | Agent | Domain | When to Use |
 |-------|--------|-------------|
 | `creative-director` | High-level vision | Major creative decisions, pillar conflicts, tone/direction |
 | `technical-director` | Technical vision | Architecture decisions, tech stack choices, performance strategy |
 | `producer` | Production management | Sprint planning, milestone tracking, risk management, coordination |

-## Tier 2 -- Department Lead Agents (Sonnet)
+## Tier 2 -- Department Lead Agents
 | Agent | Domain | When to Use |
 |-------|--------|-------------|
 | `game-designer` | Game design | Mechanics, systems, progression, economy, balancing |
@@ -24,66 +28,66 @@ domain lead) should delegate to specialists.
 | `release-manager` | Release pipeline | Build management, versioning, changelogs, deployment, rollbacks |
 | `localization-lead` | Internationalization | String externalization, translation pipeline, locale testing |

-## Tier 3 -- Specialist Agents (Sonnet or Haiku)
-| Agent | Domain | Model | When to Use |
-|-------|--------|-------|-------------|
-| `systems-designer` | Systems design | Sonnet | Specific mechanic implementation, formula design, loops |
-| `level-designer` | Level design | Sonnet | Level layouts, pacing, encounter design, flow |
-| `economy-designer` | Economy/balance | Sonnet | Resource economies, loot tables, progression curves |
-| `gameplay-programmer` | Gameplay code | Sonnet | Feature implementation, gameplay systems code |
-| `engine-programmer` | Engine systems | Sonnet | Core engine, rendering, physics, memory management |
-| `ai-programmer` | AI systems | Sonnet | Behavior trees, pathfinding, NPC logic, state machines |
-| `network-programmer` | Networking | Sonnet | Netcode, replication, lag compensation, matchmaking |
-| `tools-programmer` | Dev tools | Sonnet | Editor extensions, pipeline tools, debug utilities |
-| `ui-programmer` | UI implementation | Sonnet | UI framework, screens, widgets, data binding |
-| `technical-artist` | Tech art | Sonnet | Shaders, VFX, optimization, art pipeline tools |
-| `sound-designer` | Sound design | Sonnet | SFX design docs, audio event lists, mixing notes |
-| `writer` | Dialogue/lore | Sonnet | Dialogue writing, lore entries, item descriptions |
-| `world-builder` | World/lore design | Sonnet | World rules, faction design, history, geography |
-| `qa-tester` | Test execution | Haiku | Writing test cases, bug reports, test checklists |
-| `performance-analyst` | Performance | Sonnet | Profiling, optimization recs, memory analysis |
-| `devops-engineer` | Build/deploy | Haiku | CI/CD, build scripts, version control workflow |
-| `analytics-engineer` | Telemetry | Sonnet | Event tracking, dashboards, A/B test design |
-| `ux-designer` | UX flows | Sonnet | User flows, wireframes, accessibility, input handling |
-| `prototyper` | Rapid prototyping | Sonnet | Throwaway prototypes, mechanic testing, feasibility validation |
-| `security-engineer` | Security | Sonnet | Anti-cheat, exploit prevention, save encryption, network security |
-| `accessibility-specialist` | Accessibility | Haiku | WCAG compliance, colorblind modes, remapping, text scaling |
-| `live-ops-designer` | Live operations | Sonnet | Seasons, events, battle passes, retention, live economy |
-| `community-manager` | Community | Haiku | Patch notes, player feedback, crisis comms, community health |
+## Tier 3 -- Specialist Agents
+| Agent | Domain | When to Use |
+|-------|--------|-------------|
+| `systems-designer` | Systems design | Specific mechanic implementation, formula design, loops |
+| `level-designer` | Level design | Level layouts, pacing, encounter design, flow |
+| `economy-designer` | Economy/balance | Resource economies, loot tables, progression curves |
+| `gameplay-programmer` | Gameplay code | Feature implementation, gameplay systems code |
+| `engine-programmer` | Engine systems | Core engine, rendering, physics, memory management |
+| `ai-programmer` | AI systems | Behavior trees, pathfinding, NPC logic, state machines |
+| `network-programmer` | Networking | Netcode, replication, lag compensation, matchmaking |
+| `tools-programmer` | Dev tools | Editor extensions, pipeline tools, debug utilities |
+| `ui-programmer` | UI implementation | UI framework, screens, widgets, data binding |
+| `technical-artist` | Tech art | Shaders, VFX, optimization, art pipeline tools |
+| `sound-designer` | Sound design | SFX design docs, audio event lists, mixing notes |
+| `writer` | Dialogue/lore | Dialogue writing, lore entries, item descriptions |
+| `world-builder` | World/lore design | World rules, faction design, history, geography |
+| `qa-tester` | Test execution | Writing test cases, bug reports, test checklists |
+| `performance-analyst` | Performance | Profiling, optimization recs, memory analysis |
+| `devops-engineer` | Build/deploy | CI/CD, build scripts, version control workflow |
+| `analytics-engineer` | Telemetry | Event tracking, dashboards, A/B test design |
+| `ux-designer` | UX flows | User flows, wireframes, accessibility, input handling |
+| `prototyper` | Rapid prototyping | Throwaway prototypes, mechanic testing, feasibility validation |
+| `security-engineer` | Security | Anti-cheat, exploit prevention, save encryption, network security |
+| `accessibility-specialist` | Accessibility | WCAG compliance, colorblind modes, remapping, text scaling |
+| `live-ops-designer` | Live operations | Seasons, events, battle passes, retention, live economy |
+| `community-manager` | Community | Patch notes, player feedback, crisis comms, community health |

 ## Engine-Specific Agents (use the set matching your engine)

 ### Engine Leads

-| Agent | Engine | Model | When to Use |
-| ---- | ---- | ---- | ---- |
-| `unreal-specialist` | Unreal Engine 5 | Sonnet | Blueprint vs C++, GAS overview, UE subsystems, Unreal optimization |
-| `unity-specialist` | Unity | Sonnet | MonoBehaviour vs DOTS, Addressables, URP/HDRP, Unity optimization |
-| `godot-specialist` | Godot 4 | Sonnet | GDScript patterns, node/scene architecture, signals, Godot optimization |
+| Agent | Engine | When to Use |
+| ---- | ---- | ---- |
+| `unreal-specialist` | Unreal Engine 5 | Blueprint vs C++, GAS overview, UE subsystems, Unreal optimization |
+| `unity-specialist` | Unity | MonoBehaviour vs DOTS, Addressables, URP/HDRP, Unity optimization |
+| `godot-specialist` | Godot 4 | GDScript patterns, node/scene architecture, signals, Godot optimization |

 ### Unreal Engine Sub-Specialists

-| Agent | Subsystem | Model | When to Use |
-| ---- | ---- | ---- | ---- |
-| `ue-gas-specialist` | Gameplay Ability System | Sonnet | Abilities, gameplay effects, attribute sets, tags, prediction |
-| `ue-blueprint-specialist` | Blueprint Architecture | Sonnet | BP/C++ boundary, graph standards, naming, BP optimization |
-| `ue-replication-specialist` | Networking/Replication | Sonnet | Property replication, RPCs, prediction, relevancy, bandwidth |
-| `ue-umg-specialist` | UMG/CommonUI | Sonnet | Widget hierarchy, data binding, CommonUI input, UI performance |
+| Agent | Subsystem | When to Use |
+| ---- | ---- | ---- |
+| `ue-gas-specialist` | Gameplay Ability System | Abilities, gameplay effects, attribute sets, tags, prediction |
+| `ue-blueprint-specialist` | Blueprint Architecture | BP/C++ boundary, graph standards, naming, BP optimization |
+| `ue-replication-specialist` | Networking/Replication | Property replication, RPCs, prediction, relevancy, bandwidth |
+| `ue-umg-specialist` | UMG/CommonUI | Widget hierarchy, data binding, CommonUI input, UI performance |

 ### Unity Sub-Specialists

-| Agent | Subsystem | Model | When to Use |
-| ---- | ---- | ---- | ---- |
-| `unity-dots-specialist` | DOTS/ECS | Sonnet | Entity Component System, Jobs, Burst compiler, hybrid renderer |
-| `unity-shader-specialist` | Shaders/VFX | Sonnet | Shader Graph, VFX Graph, URP/HDRP customization, post-processing |
-| `unity-addressables-specialist` | Asset Management | Sonnet | Addressable groups, async loading, memory, content delivery |
-| `unity-ui-specialist` | UI Toolkit/UGUI | Sonnet | UI Toolkit, UXML/USS, UGUI Canvas, data binding, cross-platform input |
+| Agent | Subsystem | When to Use |
+| ---- | ---- | ---- |
+| `unity-dots-specialist` | DOTS/ECS | Entity Component System, Jobs, Burst compiler, hybrid renderer |
+| `unity-shader-specialist` | Shaders/VFX | Shader Graph, VFX Graph, URP/HDRP customization, post-processing |
+| `unity-addressables-specialist` | Asset Management | Addressable groups, async loading, memory, content delivery |
+| `unity-ui-specialist` | UI Toolkit/UGUI | UI Toolkit, UXML/USS, UGUI Canvas, data binding, cross-platform input |

 ### Godot Sub-Specialists

-| Agent | Subsystem | Model | When to Use |
-| ---- | ---- | ---- | ---- |
-| `godot-gdscript-specialist` | GDScript | Sonnet | Static typing, design patterns, signals, coroutines, GDScript performance |
-| `godot-csharp-specialist` | C# / .NET | Sonnet | .NET patterns, [Signal] delegates, async, nullable types, type-safe node access |
-| `godot-shader-specialist` | Shaders/Rendering | Sonnet | Godot shading language, visual shaders, particles, post-processing |
-| `godot-gdextension-specialist` | GDExtension | Sonnet | C++/Rust bindings, native performance, custom nodes, build systems |
+| Agent | Subsystem | When to Use |
+| ---- | ---- | ---- |
+| `godot-gdscript-specialist` | GDScript | Static typing, design patterns, signals, coroutines, GDScript performance |
+| `godot-csharp-specialist` | C# / .NET | .NET patterns, [Signal] delegates, async, nullable types, type-safe node access |
+| `godot-shader-specialist` | Shaders/Rendering | Godot shading language, visual shaders, particles, post-processing |
+| `godot-gdextension-specialist` | GDExtension | C++/Rust bindings, native performance, custom nodes, build systems |
@@ -5,7 +5,7 @@ that uses `AskUserQuestion` or writes files. Skills reference this document
 instead of embedding the full mode-handling rules inline — eliminating drift
 when the pattern needs updating.

-**Scope**: ~44 skills across authoring, review, team orchestration,
+**Scope**: 68 skills across authoring, review, team orchestration,
 implementation, and utility categories. Any skill that gates a decision
 through `AskUserQuestion` or writes files should follow this pattern.

@@ -26,7 +26,11 @@ code. This file is the procedure for applying it.
   does not count.
 3. Derivation from the tree, but **only when it is unambiguous**. Exactly one of
   `src/`, `Assets/` or `Source/` present means that is the root. Two or more
-   present means the project is genuinely undecidable — do not guess.
+   present means the project is genuinely undecidable — do not guess. Compare the
+   names exactly as the directory listing spells them: on Windows and default
+   macOS an existence test for `Assets/` also succeeds on Godot's own `assets/`,
+   which would make `src/` + `assets/` look ambiguous and a lone `assets/` look
+   like Unity.
 4. Otherwise: **unresolved.**

 The hooks already implement exactly this as `resolve_code_root()` in
@@ -74,7 +74,7 @@ falling back to the defaults above when it is absent.

 ## Automated Test Rules

- **Naming**: `[system]_[feature]_test.[ext]` for files; `test_[scenario]_[expected]` for functions
+- **Naming**: per engine — `.claude/rules/test-standards.md`
 - **Determinism**: Tests must produce the same result every run — no random seeds, no time-dependent assertions
 - **Isolation**: Each test sets up and tears down its own state; tests must not depend on execution order
 - **No hardcoded data**: Test fixtures use constant files or factory functions, not inline magic numbers
@@ -94,6 +94,6 @@ falling back to the defaults above when it is absent.
 - No merge if tests fail — tests are a blocking gate in CI
 - Never disable or skip failing tests to make CI pass — fix the underlying issue
 - Engine-specific CI commands:
-  - **Godot**: `godot --headless --script tests/gdunit4_runner.gd`
+  - **Godot**: `godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode`
  - **Unity**: `game-ci/unity-test-runner@v4` (GitHub Actions)
  - **Unreal**: headless runner with `-nullrhi` flag
@@ -35,9 +35,10 @@ the skill body instead.
 Claude Code permission-checks every injected command **before** the skill
 renders. Outside auto mode, anything that does not come back "allow" — including
 a command that would normally just prompt — **aborts the whole invocation**, and
-the model never sees the skill. A preloaded skill (`skills:` on an agent) is
+the model never sees the skill. A read-only command such as `git status`, which
+Claude Code approves on its own, comes back "allow" and runs without a grant. A preloaded skill (`skills:` on an agent) is
 checked the same way at agent launch, so a failing bootstrap line stops the agent
-from starting (GitHub issue #128). Measured on Claude Code 2.1.281 in default
+from starting. Measured on Claude Code 2.1.281 in default
 mode:

 | Bootstrap form | Repo root | Subdirectory | Bash-less agent preloading it |
@@ -53,7 +54,8 @@ What that table rules out:
  can approve it. `${CLAUDE_SKILL_DIR}` and `${CLAUDE_PROJECT_DIR}` are fine: Claude
  Code substitutes them as text before the check.
 - **No `${CLAUDE_PROJECT_DIR}` for the path.** In a skill it is the directory
-  Claude Code was launched from, not the repo root, so it breaks from `src/`.
+  Claude Code was launched from, not the repo root, so it breaks when Claude
+  Code is started in a subdirectory.
  `${CLAUDE_SKILL_DIR}` always names the skill's own folder.
 - **No `source … && …` compound.** Each part must be approved; `bash <file>
  resolve_config` is one command. `yaml-helper.sh` dispatches only
@@ -79,9 +81,9 @@ defaults below.
 review_mode: lean (production/review-mode.txt)
 automation: guided (project.local.yaml)
 workflow: standard (project.yaml)
-docs.density: balanced (default)
-story_granularity: balanced (default)
-qa.level: standard (default)
+docs.density: balanced (rigor:standard)
+story_granularity: balanced (rigor:standard)
+qa.level: standard (rigor:standard)
 team.size: individual (rigor:standard)
 project.stage: Systems Design (production/stage.txt)
 automation_always_ask: scope_changes, file_deletions, schema_changes (default)
@@ -95,7 +97,7 @@ An inline --review flag, if passed, overrides review_mode.
 ```

 Every knob line ends with its **provenance** in parentheses. That is what makes a
-wrong value diagnosable — `review_mode: solo (default)` when `project.yaml` says
+wrong value diagnosable — `review_mode: solo (rigor:minimal)` when `project.yaml` says
 `full` points straight at the problem.

 ## Resolution chain
@@ -117,7 +119,7 @@ default rather than propagating a nonsense mode into every skill.
 > already sets `docs.density: terse` resolves exactly as it did before `rigor`
 > existed, because step 2 answers first. Invert steps 4 and 5 and `rigor` becomes
 > a no-op; hoist step 4 above step 2 and it silently overrides settings people
-> already have. Tests **X.2** and **X.3** assert both directions.
+> already have.
 >
 > Derived values report their provenance as **`rigor:<level>`**, so the source
 > vocabulary is `{project.local.yaml, project.yaml, <legacy path>, rigor:<level>,
@@ -186,32 +188,27 @@ constraint. Raising the tier is one question in `/start` or one `/settings`
 call, and `settings-guidance.md § 4`'s upward triggers are written to fire from
 this starting state. (`team.size` is the one knob the flip does not move:
 `minimal` and `standard` both yield `individual`, and only `full` opts into the
-`studio` roster.) Test **X.8** asserts the six stay defaultless.
+`studio` roster.)

 > **The flip DOES reach existing projects.** A `project.yaml` that sets some of
 > the six explicitly but never sets `rigor` keeps its explicit values and takes
 > the new `minimal` row for the rest -- so an unset `qa.level` that used to
-> resolve `standard` now resolves `minimal`. Test **X.3** pins exactly this.
+> resolve `standard` now resolves `minimal`.
 > Pin the old behaviour by setting `modes.rigor: standard` explicitly; see
 > UPGRADING.md.

 `modes.workflow` is **fronted, not replaced**: it keeps
-`workflow_overrides.system_overrides`, which still beats the derived value
-(**X.6**). Setting any of the six explicitly overrides just that one and leaves
+`workflow_overrides.system_overrides`, which still beats the derived value.
+Setting any of the six explicitly overrides just that one and leaves
 its siblings on the rigor level, which is how "comprehensive but compact"
 (`rigor: full` + `docs.density: terse`) stays expressible. Two of the six —
 `modes.review_mode` and `team.size` — are personal-experience knobs that also
 remain overridable from `project.local.yaml` (that source sits above the
 expansion), unlike the four on-disk knobs, which are locked.

-> **This table is asserted against the helper, not maintained by hand.** Test
-> **X.10** reads `_yaml_helper_defaults` through `get_yaml_default` and checks
-> both directions: every knob listed here must carry the value the helper
-> actually returns, and none of the six fronted knobs may appear at all. It
-> exists because a table can list knobs the helper has stopped defaulting and
-> read as correct: the structural check pairs a knob with the word "default" on
-> a single line, so a two-cell table row is invisible to it. Editing this table
-> without editing the helper now fails the build.
+> **Keep this table in step with the helper.** Every knob listed here must carry
+> the value `_yaml_helper_defaults` returns (read it through `get_yaml_default`),
+> and none of the six fronted knobs may appear in it.

 **`testing.strict.*` has no central default on purpose.** Its unset default
 differs per skill by design: `/smoke-check` treats unset as **blocking** (it is a
@@ -269,12 +266,12 @@ mistake is the easier one to make by copy-paste. The framework has the mechanism
 (`notes:`) and already uses it for absence, emptiness, tabs, locked keys, orphan
 locals and bad enums. Shape is the gap.

-**Deliberately not fixed in v1.1.** Detecting "this key is present in the file but
+**Why it is not caught yet.** Detecting "this key is present in the file but
 resolved to nothing" means changing the parser every config read in the framework
 goes through, and the empty-value fall-through above is a *legitimate* case of
 exactly that signature. Distinguishing "empty on purpose" from "unparseable" is
 real work, not a one-liner, and it lands in the most load-bearing file there is.
-Recorded here as v1.2.
+Until then, check the structure yourself when a setting seems ignored.

 **Duplicate-key precedence was undocumented before this entry.** Last-wins is
 deterministic and reproducible, so it is not a bug — but nothing said so, which
@@ -25,7 +25,7 @@ Two regions, and the distinction is load-bearing:
 | Region | Who reads it | Rule |
 |--------|--------------|------|
 | `<!-- STATUS -->` … `<!-- /STATUS -->` | `statusline.sh` (breadcrumb, Production+ only) | Keep the markers even when empty |
-| `<!-- CHECKPOINT -->` … `<!-- /CHECKPOINT -->` | `session-start.sh` and `pre-compact.sh` | **Overwrite, never append.** Under ~25 lines — hooks inject it verbatim |
+| `<!-- CHECKPOINT -->` … `<!-- /CHECKPOINT -->` | `session-start.sh` (every start, including after a compaction) | **Overwrite, never append.** Under ~25 lines — shown verbatim |
 | Everything after `<!-- /CHECKPOINT -->` | humans, and an agent that wants detail | Free-form; no hook injects it |

 The checkpoint holds: current task, next step, what it is blocked on, files in
@@ -76,9 +76,12 @@ After any disruption (compaction, crash, `/clear`), read the state file first.

 When creating multi-section documents (design docs, architecture docs, lore entries):

-1. Create the file immediately with a skeleton (all section headers, empty bodies)
+1. Ask to create the file ("May I create [path] with the section skeleton?"), then
+   create it with every section header and empty bodies
 2. Discuss and draft one section at a time in conversation
-3. Write each section to the file as soon as it's approved
+3. Write each section to the file as soon as it's approved (a skill that writes
+   once at the end, such as `/create-architecture`, records approved sections in
+   the session state instead)
 4. Update the session state file after each section
 5. After writing a section, previous discussion about that section can be safely
   compacted — the decisions are in the file
@@ -124,10 +127,11 @@ Current helpers:

 Two rules when adding one:

-1. **A skill invoking a script needs `Bash` in `allowed-tools`**, or the step
-   silently no-ops. A skill that only needs *resolved config* does not — use the
-   documented `` !`cmd` `` body form, which is preprocessing and is not gated by
-   `allowed-tools` (see `.claude/docs/config-resolution.md`).
+1. **Grant it the way `.claude/docs/config-resolution.md` shows.** `allowed-tools`
+   pre-approves commands; it does not restrict them — a skill without the grant
+   still runs the script, after a permission prompt. An injected `` !`cmd` `` in
+   the body is stricter: unapproved, it aborts the whole invocation, so it needs
+   the exact grant that doc gives.
 2. **Emit observations, not verdicts.** A script that scores or judges will
   eventually contradict a tier, mode, or per-system override it does not know
   about. Report what is on disk and let the caller decide what it means.
@@ -17,11 +17,11 @@
 Read `.claude/docs/model-tiers.md` on demand. It carries the tier table, the
 per-skill assignments and the authoring rule.

-**One line of it is load-bearing enough to restate here:** a skill's `model:`
-frontmatter is **declared but not applied** — Claude Code reads it and serves the
-skill from the session model regardless. Never tell a user that a skill's tier
-is saving them money. The agent-side `model:` is a different mechanism and is
-untested, not known-broken.
+**Load-bearing enough to restate here:** whether a skill's `model:` is used
+depends on how the skill starts. Typed as `/skill-name`: yes, except a `haiku`
+pin in auto mode. Started by Claude through the Skill tool: no. Never tell a
+user a `haiku` skill saves money; an `opus` skill typed in a Sonnet session
+costs more. The agent-side `model:` is a different mechanism, and is applied.

 ## Subagents vs Agent Teams

@@ -19,10 +19,10 @@ context window.**

 ## Gate Index

-Agent by prefix: `CD-` creative-director (Opus) · `TD-` technical-director (Opus)
-· `PR-` producer (Opus) · `AD-` art-director (Sonnet) · `LP-` lead-programmer ·
-`QL-` qa-lead · `ND-` narrative-director (Tier 2 leads: Sonnet).
-Definition files below are in `.claude/docs/director-gates/`.
+Agent by prefix: `CD-` creative-director · `TD-` technical-director ·
+`PR-` producer · `AD-` art-director · `LP-` lead-programmer · `QL-` qa-lead ·
+`ND-` narrative-director. Definition files below are in
+`.claude/docs/director-gates/`; each one's header names its agent's model tier.

 | Gate ID | Purpose | Definition file |
 |---------|---------|-----------------|
@@ -51,7 +51,7 @@ Definition files below are in `.claude/docs/director-gates/`.
 | LP-FEASIBILITY | Implementation feasibility of the architecture | lp-feasibility.md |
 | LP-CODE-REVIEW | Code review of an implemented story | lp-code-review.md |
 | QL-STORY-READY | Acceptance-criteria testability before sprint | ql-story-ready.md |
-| QL-TEST-COVERAGE | Test coverage review before epic done / advance | ql-test-coverage.md |
+| QL-TEST-COVERAGE | Test coverage review for one story before it closes (`/story-done`) | ql-test-coverage.md |
 | ND-CONSISTENCY | Narrative consistency of writer deliverables | nd-consistency.md |
 | AD-VISUAL | Visual consistency of art/tech-art decisions | ad-visual.md |

@@ -63,8 +63,10 @@ Review intensity controls whether gates run.

 **Global config**: `modes.review_mode` in `project.yaml` — one word: `full`,
 `lean`, or `solo`. Legacy fallback: `production/review-mode.txt` (single line,
-same values); `project.yaml` wins when both are present. Set once during
-`/start`, or change it any time with `/settings modes.review_mode=<value>`.
+same values); `project.yaml` wins when both are present. `/start` never writes
+it: left unset, it follows `modes.rigor` (`minimal` → `solo`, `standard` →
+`lean`, `full` → `full`). Set it explicitly only with
+`/settings modes.review_mode=<value>`.

 **Per-run override**: any gate-using skill accepts `--review [full|lean|solo]`,
 overriding the global config for that run only.
@@ -72,8 +74,12 @@ overriding the global config for that run only.
 | Mode | What runs |
 |------|-----------|
 | `full` | All gates active — every workflow step reviewed |
-| `lean` | PHASE-GATEs only (`/gate-check`) — per-skill gates skipped. **Default** |
-| `solo` | No director gates anywhere (game jams, prototypes, max speed) |
+| `lean` | PHASE-GATEs only (`/gate-check`) — per-skill gates skipped. The `rigor: standard` value |
+| `solo` | No director gates anywhere (game jams, prototypes, max speed). **Default** — the `rigor: minimal` value |
+
+**One exception:** `/team-narrative` runs ND-CONSISTENCY in every review mode
+whenever narrative-director is on the team — it is that pipeline's only
+narrative consistency check, not an optional review.

 ---

@@ -122,16 +128,34 @@ calls before waiting for any result; collect all verdicts before proceeding.

 ## Standard Verdict Format

-All gates return one of three verdicts. Skills must handle all three:
+Every gate returns one of its three verdicts — or NOT ASSESSED when it could not
+judge. Skills must handle all four. The three judgement words are each gate's
+own — its definition file's **Verdicts** line is the authority — and the rows
+below are their meanings (TD-FEASIBILITY's VIABLE / CONCERNS / HIGH RISK,
+PR-MILESTONE's ON TRACK / AT RISK / OFF TRACK). NOT ASSESSED is the same word at
+every gate, so no Verdicts line lists it:

 | Verdict | Meaning | Default action |
 |---------|---------|----------------|
 | **APPROVE / READY** | No issues. Proceed. | Continue the workflow |
-| **CONCERNS [list]** | Issues present but not blocking. | Surface to user via `AskUserQuestion` — options: `Revise flagged items` / `Accept and proceed` / `Discuss further` |
+| **CONCERNS [list]** | Issues present but not blocking. | Surface to user via `AskUserQuestion` — options: `Revise flagged items` / `Accept and proceed` / `Discuss further`. Revise flagged items: the specialist who drafted the section re-drafts it; the revision goes through the skill's normal approve-then-write step, and the header records `REVISED [date]`. |
 | **REJECT / NOT READY [blockers]** | Blocking issues. Do not proceed. | Surface blockers to user. Do not write files or advance stage until resolved. |
+| **NOT ASSESSED [what was missing]** | An input the gate names was missing or unreadable, so no judgement was made. | Name what was missing. Never treat it as APPROVE/READY: supply the input and re-run the gate, or record NOT ASSESSED and let the skill's own verdict reflect it. |
+
+**Rank**: NOT ASSESSED sits below REJECT / NOT READY and CONCERNS, and above
+APPROVE / READY — a known problem is more actionable than an unknown, and a gate
+that could not look has approved nothing. A director that found a problem and
+also lacked an input answers with the problem's word and names the missing
+input in its rationale. An artifact the skill reports as absent is information,
+not a missing input. At a phase gate,
+a missing artifact the target phase requires is a finding (NOT READY or
+CONCERNS); one `/gate-check` passes as "not expected before [phase]" or "not
+required at `workflow: [tier]`" is not a finding — a phase gate judges
+readiness for the phase being entered, not a later one.

 **Escalation rule**: When multiple directors are spawned in parallel, apply the
-strictest verdict — one NOT READY overrides all READY verdicts.
+strictest verdict by that rank — one NOT READY overrides all READY verdicts, and
+one NOT ASSESSED keeps the result from being READY.

 ---

@@ -140,7 +164,7 @@ strictest verdict — one NOT READY overrides all READY verdicts.
 After a gate resolves, record the verdict in the relevant document's status header:

 ```markdown
-> **[Director] Review ([GATE-ID])**: APPROVED [date] / CONCERNS (accepted) [date] / REVISED [date]
+> **[Director] Review ([GATE-ID])**: APPROVED [date] / CONCERNS (accepted) [date] / REVISED [date] / NOT ASSESSED [date] — [missing input]
 ```

 For phase gates, record in `docs/architecture/architecture.md` or
@@ -157,9 +181,10 @@ Spawn in parallel (issue all `Agent` calls before waiting for any result):
 creative-director → CD-PHASE-GATE, technical-director → TD-PHASE-GATE,
 producer → PR-PHASE-GATE, art-director → AD-PHASE-GATE

-Collect all four verdicts, then apply escalation rules:
+Collect every verdict from the directors that ran, then apply escalation rules:
 - Any NOT READY / REJECT → overall verdict minimum FAIL
 - Any CONCERNS → overall verdict minimum CONCERNS
+- Any NOT ASSESSED (and no NOT READY / REJECT or CONCERNS) → overall verdict at best NOT ASSESSED
 - All READY / APPROVE → eligible for PASS (still subject to artifact checks)
 ```

@@ -185,7 +210,7 @@ Collect all four verdicts, then apply escalation rules:
 | **Concept** | CD-PILLARS, AD-CONCEPT-VISUAL | TD-FEASIBILITY, PR-SCOPE |
 | **Systems Design** | TD-SYSTEM-BOUNDARY, CD-SYSTEMS, PR-SCOPE, CD-GDD-ALIGN (per GDD) | ND-CONSISTENCY, AD-VISUAL, TD-CHANGE-IMPACT (on GDD revision) |
 | **Technical Setup** | TD-ARCHITECTURE, TD-ADR (per ADR), TD-MANIFEST, LP-FEASIBILITY, AD-ART-BIBLE | TD-ENGINE-RISK |
-| **Pre-Production** | PR-EPIC, QL-STORY-READY (per story), PR-SPRINT, all four PHASE-GATEs (via gate-check) | CD-PLAYTEST |
-| **Production** | LP-CODE-REVIEW (per story), QL-STORY-READY, PR-SPRINT (per sprint), QL-TEST-COVERAGE (per sprint close-out) | PR-MILESTONE, AD-VISUAL, TD-CHANGE-IMPACT (on GDD revision) |
-| **Polish** | QL-TEST-COVERAGE, CD-PLAYTEST, PR-MILESTONE | AD-VISUAL |
-| **Release** | All four PHASE-GATEs (via gate-check) | QL-TEST-COVERAGE |
+| **Pre-Production** | PR-EPIC, QL-STORY-READY (per story), PR-SPRINT, the PHASE-GATE panel (via gate-check — PR at `minimal`, TD + PR at `standard`, all four at `full`) | CD-PLAYTEST |
+| **Production** | LP-CODE-REVIEW (per story), QL-STORY-READY, PR-SPRINT (per sprint), QL-TEST-COVERAGE (per story, via `/story-done`) | PR-MILESTONE, AD-VISUAL, TD-CHANGE-IMPACT (on GDD revision) |
+| **Polish** | CD-PLAYTEST, PR-MILESTONE | AD-VISUAL |
+| **Release** | The PHASE-GATE panel (via gate-check — PR at `minimal`, TD + PR at `standard`, all four at `full`) | — |
@@ -2,7 +2,7 @@

 # AD-ART-BIBLE — Art Bible Sign-Off

-Agent: `art-director` | Model tier: Sonnet | Domain: Visual identity, art bible, visual production readiness
+Agent: `art-director` | Model tier: session (inherit) | Domain: Visual identity, art bible, visual production readiness

 **Trigger**: After the art bible is drafted (`/art-bible`), before asset production begins

@@ -10,7 +10,7 @@ Agent: `art-director` | Model tier: Sonnet | Domain: Visual identity, art bible,
 - Art bible path (`design/art/art-bible.md`)
 - Game pillars and core fantasy
 - Platform and performance constraints (`platform.*` and `performance.*` from `project.yaml`, falling back to `.claude/docs/technical-preferences.md`)
- Visual identity anchor chosen during brainstorm (from `design/gdd/game-concept.md`)
+- Visual identity anchor chosen during brainstorm (from `design/gdd/game-concept.md`; if there is no `design/gdd/game-concept.md`, pass the "Art & audio direction" line of `design/game-brief.md` instead)

 **Prompt**:
 > "Review this art bible for completeness and internal consistency. Does the color
@@ -2,7 +2,7 @@

 # AD-CONCEPT-VISUAL — Visual Identity Anchor

-Agent: `art-director` | Model tier: Sonnet | Domain: Visual identity, art bible, visual production readiness
+Agent: `art-director` | Model tier: session (inherit) | Domain: Visual identity, art bible, visual production readiness

 **Trigger**: After game pillars are locked (brainstorm Phase 4), in parallel with CD-PILLARS

@@ -22,4 +22,4 @@ Agent: `art-director` | Model tier: Sonnet | Domain: Visual identity, art bible,
 > primary design pillar. Name each direction. Recommend which best serves the stated
 > pillars and explain why."

-**Verdicts**: CONCEPTS (multiple valid options — user selects) / STRONG (one direction clearly dominant) / CONCERNS (pillars don't provide enough direction to differentiate visual identity yet)
+**Verdicts**: CONCEPTS (multiple valid options — user selects) / STRONG (one direction clearly dominant) / CONCERNS (pillars don't provide enough direction to differentiate visual identity yet — name each pillar that gives none, and which of the four elements above it leaves open)
@@ -2,25 +2,30 @@

 # AD-PHASE-GATE — Visual Readiness at Phase Transition

-Agent: `art-director` | Model tier: Sonnet | Domain: Visual identity, art bible, visual production readiness
+Agent: `art-director` | Model tier: session (inherit) | Domain: Visual identity, art bible, visual production readiness

-**Trigger**: Always at `/gate-check` — spawn in parallel with CD-PHASE-GATE, TD-PHASE-GATE, and PR-PHASE-GATE
+**Trigger**: At `/gate-check` when `modes.workflow` is `full` — the panel narrows by workflow, and only the full panel includes art-director; spawn in parallel with CD-PHASE-GATE, TD-PHASE-GATE, and PR-PHASE-GATE

 **Context to pass**:
- Target phase name
+- Target phase name and the resolved `workflow` tier
+- The target gate's required and recommended artifacts at the resolved tier (from `/gate-check`'s loaded gate file)
 - List of all art/visual artifacts present (file paths)
- Visual identity anchor from `design/gdd/game-concept.md` (if present)
+- Visual identity anchor from `design/gdd/game-concept.md` (if present; if there is no `design/gdd/game-concept.md`, the "Art & audio direction" line of `design/game-brief.md`)
 - Art bible path if it exists (`design/art/art-bible.md`)

 **Prompt**:
 > "Review the current project state for [target phase] gate readiness from a visual
-> direction perspective. Is the visual identity established and documented at the
-> level this phase requires? Are the right visual artifacts in place? Would visual
-> teams be able to begin their work without visual direction gaps that cause costly
-> rework later? Are there visual decisions that are being deferred past their latest
-> responsible moment? Return READY, CONCERNS [specific visual direction gaps that
-> could cause production rework], or NOT READY [visual blockers that must exist
-> before this phase can succeed — specify what artifact is missing and why it
-> matters at this stage]."
+> direction perspective, judged against what this gate requires at this tier (the
+> required-artifacts list you were given). Is the visual identity established and
+> documented at the level this phase requires? Are the visual artifacts this phase
+> requires in place? Would visual teams be able to begin their work without
+> visual direction gaps that cause costly rework later? Are there visual
+> decisions that are being deferred past their latest responsible moment?
+> A required artifact passed as "none" is a finding; one passed as "not expected
+> before [phase]" or "not required at `workflow: [tier]`" is not a finding.
+> Return READY, CONCERNS [specific visual direction gaps that could cause
+> production rework], or NOT READY [visual blockers that must exist before this
+> phase can succeed — specify what artifact is missing and why it matters at
+> this stage]."

 **Verdicts**: READY / CONCERNS / NOT READY
@@ -2,7 +2,7 @@

 # AD-VISUAL — Art Director Visual Consistency Review

-Agent: `art-director` | Model tier: Sonnet (Tier 2 lead — invoked when a domain specialist's feasibility sign-off is needed)
+Agent: `art-director` | Model tier: session (inherit)

 **Trigger**: After art direction decisions are made, when new asset types are
 introduced, or when a tech art decision affects visual style
@@ -4,12 +4,12 @@

 Agent: `creative-director` | Model tier: Opus | Domain: Vision, pillars, player experience

-**Trigger**: After a system GDD is authored (design-system, quick-design, or any
-workflow that produces a GDD)
+**Trigger**: After a system GDD is authored (design-system, or any workflow that
+produces a GDD)

 **Context to pass**:
 - GDD file path
- Game pillars (from `design/gdd/game-concept.md` or `design/gdd/game-pillars.md`)
+- Game pillars (from `design/gdd/game-concept.md` or `design/gdd/game-pillars.md`; if there is neither, `design/game-brief.md` has no pillars — pass its pitch and "what they feel" line)
 - MDA aesthetics target for this game
 - System's stated Player Fantasy section

@@ -4,9 +4,9 @@

 Agent: `creative-director` | Model tier: Opus | Domain: Vision, pillars, player experience

-**Trigger**: After narrative GDDs, lore documents, dialogue specs, or world-building
-documents are authored (team-narrative, design-system for story systems, writer
-deliverables)
+**Trigger**: Invoked directly, after narrative GDDs, lore documents, dialogue specs
+or world-building documents are authored — no skill spawns it; `/team-narrative`
+runs its own review, ND-CONSISTENCY

 **Context to pass**:
 - Document file path(s)
@@ -4,18 +4,24 @@

 Agent: `creative-director` | Model tier: Opus | Domain: Vision, pillars, player experience

-**Trigger**: Always at `/gate-check` — spawn in parallel with TD-PHASE-GATE and PR-PHASE-GATE
+**Trigger**: At `/gate-check` when `modes.workflow` is `full` — the panel narrows by workflow, and only the full panel includes creative-director; spawn in parallel with TD-PHASE-GATE, PR-PHASE-GATE and AD-PHASE-GATE

 **Context to pass**:
- Target phase name
+- Target phase name and the resolved `workflow` tier
+- The target gate's required and recommended artifacts at the resolved tier (from `/gate-check`'s loaded gate file)
 - List of all artifacts present (file paths)
 - Game pillars and core fantasy

 **Prompt**:
 > "Review the current project state for [target phase] gate readiness from a
-> creative direction perspective. Are the game pillars faithfully represented in
-> all design artifacts? Does the current state preserve the core fantasy? Are there
-> any design decisions across GDDs or architecture that compromise the intended
-> player experience? Return READY, CONCERNS [list], or NOT READY [blockers]."
+> creative direction perspective, judged against what this gate requires at this
+> tier (the required-artifacts list you were given). Are the game pillars
+> faithfully represented in the design artifacts this phase requires? Does the
+> current state preserve the core fantasy? Do any design decisions in the GDDs,
+> architecture or build that exist so far compromise the intended player
+> experience?
+> A required artifact passed as "none" is a finding; one passed as "not expected
+> before [phase]" or "not required at `workflow: [tier]`" is not a finding.
+> Return READY, CONCERNS [list], or NOT READY [blockers]."

 **Verdicts**: READY / CONCERNS / NOT READY
@@ -8,7 +8,8 @@ Agent: `creative-director` | Model tier: Opus | Domain: Vision, pillars, player
 any session that produces player feedback

 **Context to pass**:
- Playtest report file path
+- Playtest report — its file path, or its content inline when the calling skill
+  reviews before saving (`/playtest-report` does)
 - Game pillars and core fantasy statement
 - The specific hypothesis being tested

@@ -9,7 +9,7 @@ complete system set before GDD authoring begins

 **Context to pass**:
 - Systems index path (`design/gdd/systems-index.md`)
- Game pillars and core fantasy (from `design/gdd/game-concept.md`)
+- Game pillars and core fantasy (from `design/gdd/game-concept.md`; if there is no `design/gdd/game-concept.md`, the pitch and "what they feel" line of `design/game-brief.md`, which has no pillars)
 - Priority tier assignments (MVP / Vertical Slice / Alpha / Full Vision)
 - Any high-risk or bottleneck systems identified in the dependency map

@@ -2,7 +2,7 @@

 # LP-CODE-REVIEW — Lead Programmer Code Review

-Agent: `lead-programmer` | Model tier: Sonnet (Tier 2 lead — invoked when a domain specialist's feasibility sign-off is needed)
+Agent: `lead-programmer` | Model tier: Sonnet

 **Trigger**: After a dev story is implemented (`/dev-story`, `/story-done`), or
 as part of `/code-review`
@@ -2,7 +2,7 @@

 # ND-CONSISTENCY — Narrative Director Consistency Check

-Agent: `narrative-director` | Model tier: Sonnet (Tier 2 lead — invoked when a domain specialist's feasibility sign-off is needed)
+Agent: `narrative-director` | Model tier: session (inherit)

 **Trigger**: After writer deliverables (dialogue, lore, item descriptions) are
 authored, or when a design decision has narrative implications
@@ -9,8 +9,9 @@ broken out — validates the epic structure is producible before `/create-storie
 is invoked

 **Context to pass**:
- Epic definition file paths (all epics just created)
- Epic index path (`production/epics/index.md`)
+- The epic structure for the layer, inline — every epic's scope summary and
+  governing-ADR count. `/create-epics` runs this gate *before* writing any epic
+  file, so there are no paths yet.
 - Milestone timeline and target dates
 - Team capacity (solo / small team / size)
 - Layer being epiced (Foundation / Core / Feature / etc.)
@@ -4,8 +4,8 @@

 Agent: `producer` | Model tier: Opus | Domain: Scope, timeline, dependencies, production risk

-**Trigger**: At milestone review (`/milestone-review`), at mid-sprint retrospectives,
-or when a scope change is proposed that affects the milestone
+**Trigger**: At milestone review (`/milestone-review`), or when a scope change is
+proposed that affects the milestone

 **Context to pass**:
 - Milestone definition and target date
@@ -4,19 +4,27 @@

 Agent: `producer` | Model tier: Opus | Domain: Scope, timeline, dependencies, production risk

-**Trigger**: Always at `/gate-check` — spawn in parallel with CD-PHASE-GATE and TD-PHASE-GATE
+**Trigger**: At every `/gate-check` director panel — producer is on the panel at every `modes.workflow`; spawn in parallel with the rest of it (alone at `minimal`, with TD-PHASE-GATE at `standard`, with TD-PHASE-GATE, CD-PHASE-GATE and AD-PHASE-GATE at `full`)

 **Context to pass**:
- Target phase name
- Sprint and milestone artifacts present
- Team size and capacity
+- Target phase name and the resolved `workflow` tier
+- The target gate's required and recommended artifacts at the resolved tier (from `/gate-check`'s loaded gate file)
+- Sprint and milestone artifacts present — at `minimal`, the Build order in `design/game-brief.md` is the plan (that tier has no sprint plan)
+- Team size (`team.size`) and sprint capacity (from the current sprint plan, if one exists)
 - Current blocked story count

 **Prompt**:
 > "Review the current project state for [target phase] gate readiness from a
-> production perspective. Is the scope realistic for the stated timeline and team
-> size? Are dependencies properly ordered so the team can actually execute in
-> sequence? Are there milestone or sprint risks that could derail the phase within
-> the first two sprints? Return READY, CONCERNS [list], or NOT READY [blockers]."
+> production perspective, judged against what this gate requires at this tier
+> (the required-artifacts list you were given). Is the scope realistic for the
+> stated timeline and team size? Is the work of [target phase] planned to the
+> depth this gate requires — from the Production gate on, a sprint plan at
+> `standard`/`full` and the brief's Build order at `minimal`; before it, no
+> sprint plan is expected — and are its dependencies ordered so the team can
+> execute it in sequence? What milestone or schedule risks could derail the start
+> of [target phase] (its first two sprints, where the tier plans in sprints)?
+> A required artifact passed as "none" is a finding; one passed as "not expected
+> before [phase]" or "not required at `workflow: [tier]`" is not a finding.
+> Return READY, CONCERNS [list], or NOT READY [blockers]."

 **Verdicts**: READY / CONCERNS / NOT READY
@@ -4,8 +4,8 @@

 Agent: `producer` | Model tier: Opus | Domain: Scope, timeline, dependencies, production risk

-**Trigger**: After scope tiers are defined (brainstorm Phase 6, quick-design, or
-any workflow that produces an MVP definition and timeline estimate)
+**Trigger**: After scope tiers are defined (brainstorm Phase 6, map-systems Phase
+4, or any workflow that produces an MVP definition and timeline estimate)

 **Context to pass**:
 - Full vision scope description
@@ -2,13 +2,14 @@

 # QL-STORY-READY — QA Lead Story Readiness Check

-Agent: `qa-lead` | Model tier: Sonnet (Tier 2 lead — invoked when a domain specialist's feasibility sign-off is needed)
+Agent: `qa-lead` | Model tier: session (inherit)

-**Trigger**: Before a story is accepted into a sprint — invoked by `/create-stories`,
-`/story-readiness`, and `/sprint-plan` during story selection
+**Trigger**: Before a story is accepted into a sprint — invoked by `/create-stories`
+and `/story-readiness`

 **Context to pass**:
- Story file path
+- Story file path — or, from `/create-stories` (which runs this gate before any
+  story is written), the story inline
 - Story type (Logic / Integration / Visual/Feel / UI / Config/Data)
 - Acceptance criteria list (verbatim from the story)
 - The GDD requirement (TR-ID and text) the story covers
@@ -2,10 +2,10 @@

 # QL-TEST-COVERAGE — QA Lead Test Coverage Review

-Agent: `qa-lead` | Model tier: Sonnet (Tier 2 lead — invoked when a domain specialist's feasibility sign-off is needed)
+Agent: `qa-lead` | Model tier: session (inherit)

-**Trigger**: After implementation stories are complete, before marking an epic
-done, or at `/gate-check` Production → Polish
+**Trigger**: After implementation stories are complete — `/story-done` runs it for
+each story before marking it Complete

 **Context to pass**:
 - List of implemented stories with story types (Logic / Integration / Visual / UI / Config)
@@ -5,7 +5,7 @@
 Agent: `technical-director` | Model tier: Opus | Domain: Architecture, engine risk, performance

 **Trigger**: After biggest technical risks are identified during scope/feasibility
-(brainstorm Phase 6, quick-design, or any early-stage concept with technical unknowns)
+(brainstorm Phase 6, or any early-stage concept with technical unknowns)

 **Context to pass**:
 - Concept's core loop description
@@ -4,19 +4,29 @@

 Agent: `technical-director` | Model tier: Opus | Domain: Architecture, engine risk, performance

-**Trigger**: Always at `/gate-check` — spawn in parallel with CD-PHASE-GATE and PR-PHASE-GATE
+**Trigger**: At `/gate-check` when `modes.workflow` is `standard` or `full` — the panel narrows by workflow; spawn in parallel with the rest of it (PR-PHASE-GATE, plus CD-PHASE-GATE and AD-PHASE-GATE at `full`)

 **Context to pass**:
- Target phase name
+- Target phase name and the resolved `workflow` tier
+- The target gate's required and recommended artifacts at the resolved tier (from `/gate-check`'s loaded gate file)
 - Architecture document path (if exists)
 - Engine reference path
 - ADR list

 **Prompt**:
 > "Review the current project state for [target phase] gate readiness from a
-> technical direction perspective. Is the architecture sound for this phase? Are
-> all high-risk engine domains addressed? Are performance budgets realistic and
-> documented? Are Foundation-layer decisions complete enough to begin implementation?
+> technical direction perspective, judged against what this gate requires at this
+> tier (the required-artifacts list you were given), not what a later phase will
+> need. Is the technical groundwork this phase requires in place and sound —
+> entering Systems Design, is the concept feasible on the chosen engine; entering
+> Technical Setup, do the systems index and GDDs give enough to architect from;
+> entering Pre-Production, is the architecture sound and are the Foundation-layer
+> decisions complete enough to begin implementation; entering Production or
+> later, is the architecture holding up in the build? Are the high-risk engine
+> domains addressed to the depth this phase requires? Are performance budgets
+> realistic and documented where this phase requires them?
+> A required artifact passed as "none" is a finding; one passed as "not expected
+> before [phase]" or "not required at `workflow: [tier]`" is not a finding.
 > Return READY, CONCERNS [list], or NOT READY [blockers]."

 **Verdicts**: READY / CONCERNS / NOT READY
@@ -12,7 +12,7 @@
 │   └── engine-reference/        # Curated engine API snapshots (version-pinned)
 ├── tests/                       # Game test suites (unit, integration, performance, playtest)
 ├── tools/                       # Build and pipeline tools (ci, build, asset-pipeline)
-├── prototypes/                  # Throwaway prototypes (isolated from src/)
+├── prototypes/                  # Throwaway prototypes (outside the code root)
 ├── production/                  # Production management (sprints, milestones, releases)
 │   ├── session-state/           # Ephemeral session state (active.md — gitignored)
 │   └── session-logs/            # Session audit trail (gitignored)
@@ -31,13 +31,16 @@ own toolchain:
 | **Unity** | `Assets/` | Unity compiles **only** `Assets/` and `Packages/`. Code outside them is invisible to the compiler. |
 | **Unreal** | `Source/<Module>/` | UnrealBuildTool discovers modules under `Source/`; content lives in `Content/`. A module elsewhere is not built. |

-**Resolve the code root from `engine.name` before writing any source file.** Where
-a skill, rule or template says `src/`, read it as *"the code root"* and substitute
-the row above. `src/` is the table's Godot row, not a universal path.
+**Resolve the code root from `engine.name` before writing any source file.** A
+path shown as `src/…` alone is a Godot example: read it as *"the code root"* and
+substitute the row above. `src/` is the table's Godot row, not a universal path.

-> **Known residual — do not read `src/` as settled.** Roughly 30 files under
-> `.claude/` still name `src/` literally, because they were written when Godot was
-> the only engine walked end to end. They are correct for Godot and wrong for the
-> other two. This section is the authority; those files are the default. The
-> breakage is real, not theoretical — a Unity tree laid out this way does not
-> compile, and an Unreal one produces a module no `.uproject` can consume.
+**Tests follow the same rule** — the same compilers decide what they see:
+
+| `engine.name` | Test root | Anywhere else |
+|---|---|---|
+| **Godot** | `tests/unit/`, `tests/integration/` | — |
+| **Unity** | `Assets/Tests/EditMode/`, `Assets/Tests/PlayMode/` | not compiled: "0 tests, Passed" |
+| **Unreal** | `Source/<Module>/Private/Tests/` | not built: "No automation tests matched" |
+
+Read `tests/unit/[system]/` (or `integration/`) anywhere as the test root plus `[System]/`.
@@ -222,7 +222,7 @@ Example of what the whitelist prevents:

 > Sarah sets `modes.workflow: minimal` locally to skip GDD requirements. She
 > doesn't write GDDs because her local mode doesn't require them. Mike runs
-> `/gate-check` with the team default of `standard`; gate-check sees missing
+> `/gate-check` with the team's `project.yaml` value, `standard`; gate-check sees missing
 > GDDs and fails.

 This can't happen because `modes.workflow` is locked to `project.yaml`. Same
@@ -294,7 +294,7 @@ This is intentional and important:

 | Setting | Local default for fast iteration | CI default (`project.yaml`) |
 |---------|----------------------------------|------------------------------|
-| `modes.review_mode` (locally overridable) | `solo` for one developer | `lean` (team default — phase gates always run) |
+| `modes.review_mode` (locally overridable) | `solo` for one developer | `lean` (a team's usual choice — phase gates always run) |
 | `testing.strict.logic` (locally overridable) | `false` for fast WIP commits | `true` (failing tests block CI) |
 | `modes.automation` (locally overridable) | `autonomous` for solo flow | `collaborative` (the team's collab protocol, but CI doesn't ask questions anyway — this is mostly a no-op on CI) |

@@ -327,26 +327,28 @@ behavior: strict project defaults for CI, looser developer overrides for local w

 **Controls:** How many specialist and director agents are spawned during skill execution  
 **Values:** `full` | `lean` | `solo`  
-**Default:** *none* — supplied by `modes.rigor` (`standard` yields `lean`)  
-**Set by:** `/start`, `/adopt`, `/settings`  
+**Default:** *none* — supplied by `modes.rigor` (`minimal`, the default, yields `solo`; `standard` yields `lean`; `full` yields `full`)  
+**Set by:** `/settings`, or `migrate-v1-config.sh` (which `/adopt` runs) when it carries over a v1.0 `production/review-mode.txt`. `/start` and `/adopt` never write it themselves — unset, it follows `modes.rigor`  
 **Read by:** See skill table below

 **Priority chain (all skills):** inline argument flag → `modes.review_mode` in `project.yaml` → `production/review-mode.txt` (legacy fallback) → `modes.rigor` expansion (no terminal default; `minimal`→`solo`, `standard`→`lean`, `full`→`full`)

 > **design-review follows the standard chain.** `modes.review_mode` controls
 > design-review depth, its inline flag is `--review` for consistency with every
-> other review-mode-aware skill, and the default is `lean` to match them.
+> other review-mode-aware skill, and with nothing set it follows `modes.rigor` like
+> them: `solo` at `minimal` (the default), `lean` at `standard`.

 > **Hotfix / day-one-patch exception:** These skills are emergency or release-critical
 > pipelines. They are never gated by `review_mode` — all agents always run.

-> **Known inertness — `full` and `lean` are identical in all nine `team-*`
-> orchestrators.** Each of them documents a three-way split:
-> `full` spawns every director and lead gate, `lean` skips director gates *unless*
-> they are PHASE-GATE type, `solo` skips gate spawning entirely. But every
-> `team-*` skill names exactly four gates — `CD-PHASE-GATE`, `TD-PHASE-GATE`,
-> `PR-PHASE-GATE`, `AD-PHASE-GATE` — and all four are the type `lean` keeps. So
-> `lean` has nothing to skip and behaves as `full`.
+> **Known inertness — `full` and `lean` barely differ in the nine `team-*`
+> orchestrators.** Each documents a three-way split: `full` spawns every director
+> and lead gate, `lean` skips director gates *unless* they are PHASE-GATE type,
+> `solo` skips gate spawning entirely. But the director gates the team skills name
+> are the four PHASE-GATEs, which `lean` keeps — and no team pipeline spawns one
+> (`/gate-check` is their only spawner). Two things differ: `/team-release`'s
+> technical-director release sign-off runs only at `full`, and `/team-narrative` at
+> `team.size: small` adds `localization-lead` and `world-builder` only at `full`.
 >
 > `solo` genuinely differs, and outside the orchestrators (`/design-review`,
 > `/architecture-review`) all three levels differ as documented.
@@ -363,8 +365,8 @@ behavior: strict project defaults for CI, looser developer overrides for local w
 | Value | Intent |
 |-------|--------|
 | `full` | All director and specialist gates active. Best for teams, learning, or anyone who wants thorough AI feedback on every decision. |
-| `lean` | Phase gates only — per-skill director sign-offs skipped. Default. Balances quality with token cost. |
-| `solo` | No gates, no director spawns at all. Fastest. For confident solo iteration. |
+| `lean` | Phase gates only — per-skill director sign-offs skipped. The `rigor: standard` value. Balances quality with token cost. |
+| `solo` | No gates, no director spawns (a pipeline's own review, such as `/team-narrative`'s ND-CONSISTENCY, still runs). Fastest. For confident solo iteration. The default, from `rigor: minimal`. |

 ---

@@ -374,20 +376,22 @@ behavior: strict project defaults for CI, looser developer overrides for local w
 |-------|------|------|------|
 | **design-review** | 5–15 specialist agents spawned in Phase 3b | No specialist agents — single-session analysis only | Phases 1–4 only, no delegation, no next-steps prompt |
 | **gate-check** | Director panel runs in parallel — **width set by `modes.workflow`**, not by this axis | Director panel runs in parallel — same width rule; phase gates always run | Artifact existence checks only, no directors spawned |
-| **design-system** | All section specialists + CD-GDD-ALIGN sign-off gate | All section specialists, CD-GDD-ALIGN skipped | All section specialists, CD-GDD-ALIGN skipped |
+| **design-system** | All section specialists + CD-GDD-ALIGN sign-off gate | Specialists for Sections D and H only (+ G when its knobs interact, + Visual/Audio when visual feedback is central); CD-GDD-ALIGN skipped | No section specialists; CD-GDD-ALIGN skipped |
 | **art-bible** | All section specialists + AD-ART-BIBLE sign-off gate | All section specialists, AD-ART-BIBLE skipped | All section specialists, AD-ART-BIBLE skipped |
-| **architecture-decision** | Engine specialist + TD-ADR gate | Both skipped | Both skipped |
-| **create-architecture** | TD self-review + LP-FEASIBILITY agent | Both skipped | Both skipped |
+| **architecture-decision** | Engine specialist + TD-ADR gate | Engine specialist; TD-ADR skipped | Engine specialist; TD-ADR skipped |
+| **create-architecture** | TD-ARCHITECTURE + LP-FEASIBILITY agents, in parallel | Both skipped | Both skipped |
 | **brainstorm** | CD-PILLARS, AD-CONCEPT-VISUAL, TD-FEASIBILITY, PR-SCOPE | All skipped | All skipped |
 | **map-systems** | TD-SYSTEM-BOUNDARY, PR-SCOPE, CD-SYSTEMS | All skipped | All skipped |
 | **story-done** | QL-TEST-COVERAGE + LP-CODE-REVIEW | Both skipped | Both skipped |
 | **sprint-plan** | PR-SPRINT feasibility check | Skipped | Skipped |
 | **create-epics** | PR-EPIC scope check | Skipped | Skipped |
 | **create-stories** | QL-STORY-READY + test case specs | Skipped | Skipped |
-| **prototype** | CD-PLAYTEST director override | Skipped — prototyper verdict is final | Skipped — prototyper verdict is final |
+| **prototype** | CD-PLAYTEST review — APPROVE keeps the recommendation; CONCERNS and REJECT go to the user, who decides | Skipped — the recommendation stands unreviewed | Skipped — the recommendation stands unreviewed |
 | **milestone-review** | PR-MILESTONE feasibility check | Skipped — no producer verdict | Skipped — no producer verdict |
 | **playtest-report** | CD-PLAYTEST creative assessment | Skipped | Skipped |
 | **story-readiness** | QL-STORY-READY acceptance criteria check | Skipped | Skipped |
+| **create-control-manifest** | TD-MANIFEST (technical-director) review | Skipped | Skipped |
+| **propagate-design-change** | TD-CHANGE-IMPACT (technical-director) review | Skipped | Skipped |

 ---

@@ -400,28 +404,20 @@ behavior: strict project defaults for CI, looser developer overrides for local w
 | **dev-story** | Core programmer routing always runs + engine-specialist escalation on HIGH risk stories | Core programmer routing always runs, engine-specialist escalation skipped | Core programmer routing always runs, engine-specialist escalation skipped |
 | **code-review** | Language, shader, UI specialists + qa-tester | All optional specialists skipped | All optional specialists skipped |
 | **security-audit** | security-engineer spawned | Skipped | Skipped |
-| **create-control-manifest** | technical-director validation step | Skipped | Skipped |
-| **propagate-design-change** | technical-director validation step | Skipped | Skipped |

 ---

 ### Team orchestration skills (pipeline behavior — different relationship)

-Team skills are execution pipelines, not review gates. `review_mode` controls
-whether *optional* specialists within the pipeline are included — not whether
-the pipeline runs.
+Team skills are execution pipelines, not review gates. In them `review_mode` sets
+only director-gate depth; `team.size` picks the agents (see `## team.size`), and a
+pipeline's own review steps run in every mode.

 | Skill | full | lean | solo |
 |-------|------|------|------|
-| **team-combat** | Full pipeline including technical-artist, sound-designer, qa-tester | Core pipeline only (game-designer, gameplay-programmer, ai-programmer) — optional specialists skipped | Core pipeline only |
-| **team-ui** | Full pipeline including accessibility-specialist, art-director review pass | Core pipeline (ux-designer, ui-programmer, engine UI specialist) — optional reviewers skipped | Core pipeline only |
-| **team-audio** | Full pipeline including accessibility-specialist, engine-specialist | Core pipeline (audio-director, sound-designer, technical-artist) — optional specialists skipped | Core pipeline only |
-| **team-qa** | Full QA cycle including per-story qa-tester spawns + qa-lead sign-off | Core qa-lead plan only, per-story tester spawns skipped | Core qa-lead plan only |
-| **team-release** | Full pipeline including security-engineer, analytics-engineer, localization-lead | Core pipeline (producer, release-manager, devops-engineer, qa-lead) — optional reviewers skipped | Core pipeline only |
-| **team-narrative** | Full pipeline including world-builder, writer, localization-lead | Core pipeline (narrative-director, art-director) — optional contributors skipped | Core pipeline only |
-| **team-polish** | Full pipeline including engine-programmer, sound-designer, qa-tester | Core pipeline (performance-analyst, technical-artist) — optional specialists skipped | Core pipeline only |
-| **team-level** | Full pipeline including narrative-director, world-builder, accessibility-specialist, qa-tester | Core pipeline (level-designer, systems-designer, art-director) — optional reviewers skipped | Core pipeline only |
-| **team-live-ops** | Full pipeline including analytics-engineer, community-manager | Core pipeline (live-ops-designer, narrative-director, economy-designer) — optional contributors skipped | Core pipeline only |
+| **All nine `team-*`** | Every director gate the pipeline names | PHASE-GATE-type gates only | No director gates |
+| **team-release** | + technical-director release sign-off before the go/no-go call | Sign-off not run — recorded as `not run (review_mode: lean)` | Sign-off not run — recorded as `not run (review_mode: solo)` |
+| **team-narrative** | ND-CONSISTENCY; at `team.size: small`, + `localization-lead` and `world-builder` | ND-CONSISTENCY; at `small`, `narrative-director` + `writer` only | ND-CONSISTENCY still runs when `narrative-director` is active |

 ---

@@ -435,10 +431,13 @@ the pipeline runs.
  Opus panel cost a two-system jam exactly what it cost a thirty-system
  commercial project. Width never softens a verdict: the strictest verdict from
  whoever ran still wins, and `/gate-check` names the perspectives it skipped.
- **design-system** and **art-bible** always spawn section specialists regardless
-  of mode — only the final sign-off gate is controlled by `review_mode`. Specialist
-  delegation is mandatory for the authoring output to be useful, and that has not
-  changed. What sets `art-bible`'s **spawn count** is therefore not `review_mode`
+- **art-bible** always spawns its section specialists regardless of mode — only
+  the final sign-off gate is controlled by `review_mode`. Specialist delegation is
+  mandatory for the authoring output to be useful, and that has not changed.
+  **design-system** is different: `lean` keeps the specialists for its high-risk
+  sections only (D and H, plus G and Visual/Audio when they matter) and `solo`
+  drafts every section without one, and each skipped spawn is announced by name.
+  What sets `art-bible`'s **spawn count** is therefore not `review_mode`
  but (a) `modes.workflow`, via how many sections get authored at all — `standard`
  requires sections 1–4, not all 9, and Phase 1 recommends the tier's set — and
  (b) batching consecutive sections that call the *same* agent with the *same*
@@ -478,8 +477,8 @@ disk. The two personal-experience knobs it also fronts, `modes.review_mode` and

 | `modes.rigor` | `modes.workflow` | `docs.density` | `qa.level` | `modes.story_granularity` | `modes.review_mode` | `team.size` |
 |---|---|---|---|---|---|---|
-| `minimal` | `minimal` | `terse` | `minimal` | `coarse` | `solo` | `individual` |
-| `standard` *(default)* | `standard` | `balanced` | `standard` | `balanced` | `lean` | `individual` |
+| `minimal` *(default)* | `minimal` | `terse` | `minimal` | `coarse` | `solo` | `individual` |
+| `standard` | `standard` | `balanced` | `standard` | `balanced` | `lean` | `individual` |
 | `full` | `full` | `thorough` | `full` | `fine` | `full` | `studio` |

 ### It fronts, it does not replace
@@ -530,8 +529,8 @@ user just chose.
 the tradeoff between token/time cost of documentation and speed of reaching
 working code  
 **Values:** `full` | `standard` | `minimal`  
-**Default:** *none* — supplied by `modes.rigor` (`standard` yields `standard`)  
-**Set by:** `/start`, `/settings`  
+**Default:** *none* — supplied by `modes.rigor` (`minimal`, the default, yields `minimal`; `standard` yields `standard`; `full` yields `full`)  
+**Set by:** `/start` (via `modes.rigor`), `/settings`  
 **Read by:** See skill tables below

 **Priority chain:** `modes.workflow` in `project.yaml` → `modes.rigor` expansion → *(no hardcoded default)*
@@ -631,20 +630,20 @@ checklists differ per phase per mode.
 | Gate | full | standard | minimal |
 |------|------|----------|---------|
 | Concept → Systems Design | game-concept.md, pillars, Visual Identity Anchor | game-concept.md only | `design/game-brief.md` only (content check, not section check) |
-| Systems Design → Technical Setup | systems-index, all MVP GDDs reviewed (8 sections), cross-GDD review | systems-index, 5-section GDDs reviewed, cross-GDD review optional | Not applicable — no gates between brief and code |
+| Systems Design → Technical Setup | systems-index, all MVP GDDs reviewed (8 sections), cross-GDD review | systems-index, 5-section GDDs reviewed, cross-GDD review optional | Not applicable — no gates between brief and code; the gate PASSes with that note |
 | Technical Setup → Pre-Production | engine, art bible sections 1–4+, 3+ ADRs, architecture, UX specs started | engine, art bible only if visual assets, critical ADRs, architecture | engine configured (required floor) |
-| Pre-Production → Production | prototype, sprint plan, complete art bible, epics, 3+ playtests | prototype, sprint plan, epics, 1+ playtest | prototype (advisory); the brief's Build order is the plan — no separate sprint-plan floor |
-<!-- gate-check reconciliation: the Vertical Slice / prototype keeps
-     its long-standing "recommended, not blocking → CONCERNS if absent; FAIL if
-     built-and-broken" status at ALL tiers — the tier table never upgrades it to
-     a hard blocker. The genuinely-required floor item at this gate is the
-     sprint plan at `standard`/`full`; at `minimal` (Option A) there is
-     no separate sprint-plan step — the brief's Build order is the plan, so the
-     brief existing satisfies the floor. "prototype" above means "checked,
-     advisory," not "blocks." -->
+| Pre-Production → Production | sprint plan, complete art bible, epics, UX specs, control manifest; Vertical Slice + its playtest recommended (absent → CONCERNS) | epics, sprint plan; complete art bible, UX specs, control manifest recommended; Vertical Slice recommended | the brief's Build order + stories under `production/epics/`; the Vertical Slice items drop — the core loop is fun and runs end to end, checked on the current build |
+| Production → Polish | core mechanics, tests, smoke check, QA sign-off, 3+ playtests | core mechanics, smoke check, playable end to end, 1+ playtest, no open S1 bugs | smoke check, playable end to end, no open S1 bugs |
+| Polish → Release | all features, content complete, localization (`/localize qa` per locale), QA, smoke, no open S1–S3 bugs, newest `/security-audit` with no open CRITICAL/HIGH | all features, smoke, no open S1 bugs, the security audit | smoke, no open S1 bugs |

-| Production → Polish | core mechanics, tests, smoke check, QA sign-off | core mechanics, smoke check | smoke check |
-| Polish → Release | all features, content complete, QA, smoke, no critical bugs | all features, smoke, no critical bugs | smoke, no critical bugs |
+<!-- gate-check reconciliation: at `full` and `standard` the Vertical Slice
+     keeps its long-standing "recommended, not blocking → CONCERNS if absent;
+     FAIL if built-and-broken" status — the tier table never upgrades it to a
+     hard blocker. At `minimal` its items drop, and two checks on the current
+     build replace them. The genuinely-required floor item at this gate is the
+     sprint plan at `standard`/`full`; at `minimal` there is no separate
+     sprint-plan step — the brief's Build order plus stories is the floor at
+     `minimal`. -->

 **Director panel width** (`/gate-check` Section 4b) is workflow's second effect
 here. Directors are Opus-tier, so a fixed four-director panel charged a
@@ -669,11 +668,14 @@ never softens a verdict — the strictest verdict from whoever ran still wins, a
 |-------|------|----------|---------|
 | **create-epics** | Requires all GDDs approved (8 sections) | Requires 5-section GDDs approved | **Skipped** (Option A) — no separate epic doc. `/create-stories` reads `design/game-brief.md` directly and synthesizes the implicit epic container itself. |
 | **create-stories** | Requires all ADRs on required list present | Requires critical ADRs present | No ADR requirement |
-| **dev-story** | Requires TR registry + governing ADR + control manifest — blocks without them | TR registry optional; critical ADR required where present | No TR registry, no ADR required — implements against `design/game-brief.md` |
-| **story-readiness** | Full TR registry + ADR + control manifest validation | TR registry optional; critical ADR check only | Acceptance criteria check only |
+| **dev-story** | Requires TR registry + governing ADR — blocks without them, and on a `Proposed`, `Deprecated` or `Superseded` ADR; a missing control manifest warns | TR registry optional; blocks only on a referenced ADR that is missing, `Proposed`, `Deprecated` or `Superseded` | No TR registry or ADR required — implements against `design/game-brief.md`; a referenced ADR that is missing, `Proposed`, `Deprecated` or `Superseded` still blocks |
+| **story-readiness** | Full TR registry + ADR + control manifest validation; any referenced ADR that is missing, `Proposed`, `Deprecated` or `Superseded` BLOCKS | TR registry optional; critical ADR check, and any referenced ADR that is missing, `Proposed`, `Deprecated` or `Superseded` BLOCKS | Acceptance-criteria check (the brief stands in for the GDD); any referenced ADR that is missing, `Proposed`, `Deprecated` or `Superseded` still BLOCKS |
 | **story-done** | Full GDD traceability + ADR consistency check | 5-section GDD traceability check | Acceptance criteria check only |
 | **qa-plan** | Full test plan derived from all 8 GDD sections | Test plan from 5 required sections | Test plan from acceptance criteria only |
 | **regression-suite** | Critical paths mapped from all sections including Edge Cases | Critical paths from required sections (including Edge Cases) | Smoke test coverage only |
+| **release-checklist** | Open S1, S2 or S3 bug in `production/qa/bugs/` fails its Quality Gates item | Open S1 fails; open S2/S3 listed as risks | Open S1 fails; open S2/S3 listed as risks |
+| **launch-checklist** | Zero open S1–S3 bugs, no exceptions | Zero open S1; S2 or a documented exception | Zero open S1; S2 or a documented exception |
+| **team-release** | qa-lead verifies no open S1–S3 bugs | qa-lead verifies no open S1 bugs | qa-lead verifies no open S1 bugs |

 ---

@@ -776,13 +778,13 @@ recommend and proceed — the tradeoff between user control and speed
 **Values:** `collaborative` | `guided` | `autonomous`  
 **Default:** `collaborative`  
 **Set by:** `/start`, `/settings`  
-**Read by:** All ~40 skills that use `AskUserQuestion` or write files
+**Read by:** All 68 skills that use `AskUserQuestion` or write files

 **Priority chain:** `modes.automation` in `project.yaml` → hardcoded default

 > **Unlike review_mode and workflow, this setting is not a per-skill table.**
 > It defines universal interaction rules that apply across all skills. A
-> per-skill breakdown would repeat the same answer 40 times.
+> per-skill breakdown would repeat the same answer 68 times.

 > **Overrides COLLABORATIVE-DESIGN-PRINCIPLE.md:** `guided` and `autonomous`
 > modes intentionally relax the Q→O→D→Draft→Approval protocol defined in that
@@ -942,7 +944,7 @@ appends to the existing log.
 **Controls:** Decision categories that ALWAYS trigger AskUserQuestion regardless of automation mode
 **Values:** list of category names
 **Default:** `[scope_changes, file_deletions, schema_changes]`
-**Set by:** `/start`, `/settings`
+**Set by:** `/settings`
 **Read by:** All skills that respect `modes.automation`

 > **Makes `autonomous` safe.** Without this, `autonomous` is "AI does literally
@@ -983,8 +985,8 @@ The list is a YAML list of these strings. Skills check whether the current decis

 **Controls:** How big each story is and how many stories per epic/sprint
 **Values:** `coarse` | `balanced` | `fine`
-**Default:** *none* — supplied by `modes.rigor` (`standard` yields `balanced`)
-**Set by:** `/start`, `/settings`
+**Default:** *none* — supplied by `modes.rigor` (`minimal`, the default, yields `coarse`; `standard` yields `balanced`; `full` yields `fine`)
+**Set by:** `/start` (via `modes.rigor`), `/settings`
 **Read by:** `/create-epics`, `/create-stories`, `/dev-story`, `/sprint-plan`, `/story-done`, `/sprint-status`

 **Priority chain:** `modes.story_granularity` in `project.yaml` → `modes.rigor` expansion → *(no hardcoded default)*
@@ -995,8 +997,8 @@ The list is a YAML list of these strings. Skills check whether the current decis

 | Value | Story shape | Stories per sprint | Best for |
 |-------|-------------|-------------------|----------|
-| `coarse` | 1 story = 1 feature. 3–5 days work each. 5–10 ACs per story. | 2–4 | Solo devs, prototyping, "I know what I'm building" |
-| `balanced` | 1 story = 1 task. 1–2 days work each. 2–4 ACs per story. Current default behavior. | 6–10 | Most projects |
+| `coarse` | 1 story = 1 feature. 3–5 days work each. 5–10 ACs per story. The default, from `rigor: minimal`. | 2–4 | Solo devs, prototyping, "I know what I'm building" |
+| `balanced` | 1 story = 1 task. 1–2 days work each. 2–4 ACs per story. The `rigor: standard` value. | 6–10 | Most projects |
 | `fine` | 1 story = 1 AC. Hours of work each. Easy code review. Frequent /story-done. | 15–25 | Teams, learning, anything needing fine handoffs |

 ---
@@ -1018,8 +1020,8 @@ The list is a YAML list of these strings. Skills check whether the current decis

 **Controls:** How deep each section in authored docs goes — independent of which sections are required
 **Values:** `terse` | `balanced` | `thorough`
-**Default:** *none* — supplied by `modes.rigor` (`standard` yields `balanced`)
-**Set by:** `/start`, `/settings`
+**Default:** *none* — supplied by `modes.rigor` (`minimal`, the default, yields `terse`; `standard` yields `balanced`; `full` yields `thorough`)
+**Set by:** `/start` (via `modes.rigor`), `/settings`
 **Read by:** `/design-system`, `/art-bible`, `/create-architecture`, `/ux-design`, `/map-systems`, `/brainstorm`

 **Priority chain:** `docs.density` in `project.yaml` → `modes.rigor` expansion → *(no hardcoded default)*
@@ -1038,8 +1040,8 @@ The list is a YAML list of these strings. Skills check whether the current decis

 | Value | Per-section output style |
 |-------|--------------------------|
-| `terse` | Bullet points. 2–5 lines per section. Skip rationale and narrative framing. Skip preambles like "In this game..." Just facts needed to implement. |
-| `balanced` | Paragraphs with light rationale. Examples where helpful. Current default behavior. |
+| `terse` | Bullet points. 2–5 lines per section. Skip rationale and narrative framing. Skip preambles like "In this game..." Just facts needed to implement. The default, from `rigor: minimal`. |
+| `balanced` | Paragraphs with light rationale. Examples where helpful. The `rigor: standard` value. |
 | `thorough` | Full prose. Rationale for every decision. Examples, alternatives considered, design history. |

 ---
@@ -1048,8 +1050,8 @@ The list is a YAML list of these strings. Skills check whether the current decis

 |  | docs.density: terse | balanced | thorough |
 |---|---|---|---|
-| **workflow: minimal** | Game brief in bullets | Game brief in prose | Game brief + rationale |
-| **workflow: standard** | 5 sections, bullets | 5 sections, paragraphs *(default)* | 5 sections + examples |
+| **workflow: minimal** | Game brief in bullets *(default)* | Game brief in prose | Game brief + rationale |
+| **workflow: standard** | 5 sections, bullets | 5 sections, paragraphs | 5 sections + examples |
 | **workflow: full** | 8 sections, bullets *(comprehensive but compact)* | 8 sections, paragraphs *(current full)* | 8 sections + rationale + examples |

 ---
@@ -1099,7 +1101,7 @@ The list is a YAML list of these strings. Skills check whether the current decis
 | **qa-plan** | Test plan tailored to framework's idioms (assertion style, fixture pattern, parameterized tests) |
 | **dev-story** | Test framework name passed to programmer subagent in implementation brief |
 | **regression-suite** | Test file naming and discovery patterns match framework conventions |
-| **test-setup** | Scaffolds the right test runner config (e.g. `gdunit4_runner.gd` for Godot vs Unity Test Framework Asset) |
+| **test-setup** | Scaffolds the right test layout for the engine (gdUnit4 under `addons/gdUnit4/` + `tests/` for Godot; `Assets/Tests/` asmdefs for Unity; `Source/<Module>/Private/Tests/` for Unreal) |
 | **smoke-check** | Invokes framework-appropriate test runner |

 ---
@@ -1110,8 +1112,8 @@ The list is a YAML list of these strings. Skills check whether the current decis
 closing, or produces a warning and lets work continue — per test type
 **Values:** map of `{logic, integration, visual, ui, config}` → `true | false`
 **Default:** `{logic: true, integration: true, visual: true, ui: true, config: false}`
-**Set by:** `/start`, `/settings`
-**Read by:** `story-done`, `story-readiness`, `gate-check`, `smoke-check`, `dev-story`
+**Set by:** `/settings`
+**Read by:** `story-done`, `story-readiness`, `gate-check`, `smoke-check`, `dev-story`, `test-evidence-review`

 > **Per-type, not a single bool.** A global `testing.strict: true|false` forces
 > all-or-nothing: either all test failures block or none do. Per-type matches how
@@ -1145,6 +1147,7 @@ closing, or produces a warning and lets work continue — per test type
 | **gate-check** | CI failures of that type block phase transition | CI failures of that type surfaced as concerns, not blockers |
 | **smoke-check** | Failing smoke (config strict) blocks QA handoff | Failing smoke flagged but handoff proceeds |
 | **dev-story** | References test requirements — flags story as unverifiable if absent | References test requirements — advisory only |
+| **test-evidence-review** | A gap in that type's evidence is a BLOCKING item (the run ends CONCERNS) | The gap is ADVISORY |

 > **Unset-key resolution.** Each skill reads `testing.strict.<type>`; if absent
 > it reads `testing.strict` as a plain boolean (legacy form); if still absent it
@@ -1161,9 +1164,9 @@ closing, or produces a warning and lets work continue — per test type

 **Controls:** What test evidence is required to mark stories Done
 **Values:** `minimal` | `standard` | `full`
-**Default:** *none* — supplied by `modes.rigor` (`standard` yields `standard`)
-**Set by:** `/start`, `/settings`
-**Read by:** `/story-done`, `/story-readiness`, `/dev-story`, `/smoke-check`, `/gate-check`, `/qa-plan`, `/regression-suite`
+**Default:** *none* — supplied by `modes.rigor` (`minimal`, the default, yields `minimal`; `standard` yields `standard`; `full` yields `full`)
+**Set by:** `/start` (via `modes.rigor`), `/settings`
+**Read by:** `/story-done`, `/story-readiness`, `/dev-story`, `/smoke-check`, `/gate-check`, `/qa-plan`, `/regression-suite`, `/team-qa`, `/test-evidence-review`, `/create-stories`, `/retrospective`, `/test-setup`

 **Priority chain:** `qa.level` in `project.yaml` → `modes.rigor` expansion → *(no hardcoded default)*

@@ -1179,10 +1182,10 @@ closing, or produces a warning and lets work continue — per test type
 |--------|---------|----------|------|
 | Logic stories | No test required, no gap flagged | Unit test required (strict.logic controls block) | Unit test + coverage minimum |
 | Integration stories | No test required | Integration test or playtest doc required | Same + regression coverage |
-| Visual stories | No evidence required | Screenshot required (strict.visual controls block) | Screenshot + lead sign-off required |
-| UI stories | No evidence required | Screenshot of each screen required (strict.ui controls block) | Screenshot + walkthrough doc + interaction test |
+| Visual stories | Screenshot + lead sign-off required — the look is never waived (strict.visual controls block) | Same | Same |
+| UI stories | Screenshot of each screen touched required — never waived (strict.ui controls block) | Same | Same |
 | Config/Data stories | No evidence required | Smoke check advisory | Smoke check required |
-| /story-done test gate | Acceptance criteria only | Enforced per story type | Enforced for every story type |
+| /story-done test gate | Acceptance criteria only, except the UI and Visual/Feel screenshot, which is never waived | Enforced per story type | Enforced for every story type |
 | /gate-check phase enforcement | No test gates | Logic + integration must pass | Full coverage + regression suite |
 | /dev-story routing prompt | No "Test required: ..." line | Per-type test requirement included | Per-type + coverage target included |
 | Regression suite required by | Never | Polish stage | Production stage |
@@ -1194,13 +1197,15 @@ closing, or produces a warning and lets work continue — per test type

 | Skill | minimal | standard | full |
 |-------|---------|----------|------|
-| **story-done** | Acceptance criteria check only — no evidence required | Per-type evidence required; strictness from `testing.strict` | All types require evidence; strictness from `testing.strict` |
-| **story-readiness** | No test requirement validated | Test requirement per story type validated | Test requirement + coverage target validated |
+| **story-done** | Acceptance criteria check only — no test evidence required, except the UI and Visual/Feel screenshot, which is never waived | Per-type evidence required; strictness from `testing.strict` | All types require evidence; strictness from `testing.strict` |
+| **story-readiness** | No test requirement validated, except the UI and Visual/Feel screenshot requirement | Test requirement per story type validated | Test requirement + coverage target validated |
 | **dev-story** | Routing prompt has no "Test required" line | Per-type test requirement passed to programmer agent | Coverage target passed to programmer agent |
-| **smoke-check** | Optional | Required before phase transition | Required before every commit |
+| **smoke-check** | Optional; with no game tests (WAIVED), `commands.smoke` (else `commands.build`) when set and the launch and critical-path checks carry the verdict; a build nobody launched is NOT ASSESSED | Required before phase transition | Required before every commit |
 | **gate-check** | No test enforcement at phase transitions | Logic + integration tests must pass | Full coverage check + regression suite |
 | **qa-plan** | Skipped entirely or minimal smoke plan | Full plan per story type | Full plan + coverage targets per system |
 | **regression-suite** | Not generated | Generated at Polish stage entry | Generated at Production stage entry |
+| **team-qa** | A Logic, Integration or Config/Data story without a test is WAIVED; its acceptance-criteria walk in manual QA is its evidence | The automated test is the evidence for those types | Same |
+| **test-evidence-review** | A story with no test evidence is WAIVED, not MISSING; gaps in existing tests are ADVISORY; screenshots never waived | Per-type evidence reviewed; BLOCKING/ADVISORY from `testing.strict` | Same |

 ---

@@ -1239,8 +1244,8 @@ closing, or produces a warning and lets work continue — per test type
 **Controls:** Whether phase gate failures block stage transition or just warn
 **Values:** `true` | `false`
 **Default:** `true`
-**Set by:** `/start`, `/settings`
-**Read by:** `/gate-check`
+**Set by:** `/settings`
+**Read by:** nothing yet (intended reader: `/gate-check`)

 **Priority chain:** `strict_gate_checks` in `project.yaml` → hardcoded default of `true`

@@ -1279,7 +1284,7 @@ closing, or produces a warning and lets work continue — per test type

 > **`individual` at `minimal`/`standard`, `studio` at `full`.** CCGS's audience is
 > overwhelmingly solo indie developers, so the two lighter rigor tiers resolve
-> `team.size` to `individual` — a `standard` (default) project gets one active agent
+> `team.size` to `individual` — a `minimal` (default) or `standard` project gets one active agent
 > per role, not 15 (directors and leads included). Only `rigor: full` opts into the
 > full `studio` roster; a smaller team on a big project sets `team.size: small`
 > explicitly, which wins over the rigor-derived value.
@@ -1295,9 +1300,9 @@ closing, or produces a warning and lets work continue — per test type

 | Value | Active set | Notes |
 |-------|-----------|-------|
-| `individual` | Core 8: `producer`, `game-designer`, `gameplay-programmer`, engine-specialist (engine-driven), `technical-artist`, `sound-designer`, `qa-tester`, `writer`. **Default.** | Directors and lead-* run only on explicit invocation (e.g. via `/architecture-decision`). Specialists outside the core 8 routed through their nearest core agent. |
-| `small` | Core 15: directors (CD, TD, PR) + leads (LP, AD, QL, ND) + game-designer + systems-designer + engine-specialist + technical-artist + sound-designer + qa-tester + ux-designer + writer | `team-*` skills run their full pipeline. Optional specialists added per `review_mode`. |
-| `studio` | All 49 agents available. Engine sub-specialists (e.g. `unity-dots-specialist` separate from `unity-specialist`) routed when relevant. Adversarial review patterns active. | Commercial titles, learning the full org chart, large teams with parallel work. |
+| `individual` | Core 8: `producer`, `game-designer`, `gameplay-programmer`, engine-specialist (engine-driven), `technical-artist`, `sound-designer`, `qa-tester`, `writer`. **Default.** | Directors and lead-* run only on explicit invocation (e.g. via `/architecture-decision`). Specialists outside the core 8 routed through their nearest core agent. Each `team-*` skill names its own set per value, which can sit outside the core 8 (`team-release` runs `release-manager`); each skill's own `team.size` list is authoritative, and the Affected skills table below mirrors it. |
+| `small` | Core 15: directors (CD, TD, PR) + leads (LP, AD, QL, ND) + game-designer + systems-designer + engine-specialist + technical-artist + sound-designer + qa-tester + ux-designer + writer | `team-*` skills add their `small` set (below); most reach their full pipeline only at `studio`. |
+| `studio` | All 49 agents available. Engine sub-specialists (e.g. `unity-dots-specialist` separate from `unity-specialist`) routed when relevant. The adversarial review pass in `team-combat`, `team-ui` and `team-polish`. | Commercial titles, learning the full org chart, large teams with parallel work. |

 ---

@@ -1305,21 +1310,23 @@ closing, or produces a warning and lets work continue — per test type

 | Skill | individual | small | studio |
 |-------|------|-------|--------|
-| **team-combat** | Single agent (gameplay-programmer) runs the pipeline; ai-programmer escalated only if AI work flagged | Default pipeline as documented | Default + engine sub-specialists + adversarial review pass |
-| **team-narrative** | writer only; narrative-director invoked only on explicit pillar conflict | narrative-director + writer + (per review_mode) localization-lead, world-builder | All narrative agents active + per-system writer reviews |
-| **team-ui** | ui-programmer + ux-designer | + accessibility-specialist + art-director | + engine UI specialist + adversarial review pass |
-| **team-audio** | sound-designer only | + audio-director + technical-artist | + localization-lead + per-system audio reviewers |
-| **team-level** | level-designer + gameplay-programmer | + systems-designer + art-director | + narrative-director + world-builder + accessibility-specialist |
+| **team-combat** | Single agent (gameplay-programmer) runs the pipeline; ai-programmer escalated only if AI work flagged | Default pipeline as documented | Default + the primary engine specialist may use its sub-specialists + adversarial review pass (Phase 5's qa-tester looks for how it breaks) |
+| **team-narrative** | writer only; narrative-director invoked only on explicit pillar conflict | narrative-director + writer, + localization-lead and world-builder at `review_mode: full` | All six narrative agents, whatever the review mode |
+| **team-ui** | ui-programmer + ux-designer | + accessibility-specialist + art-director | + engine UI specialist + adversarial review pass (Phase 4's reviewers look for where it fails its spec) |
+| **team-audio** | sound-designer only | + audio-director + technical-artist + gameplay-programmer | + accessibility-specialist + the primary engine specialist |
+| **team-level** | level-designer only | + systems-designer + art-director + qa-tester | + narrative-director + world-builder + accessibility-specialist |
 | **team-qa** | qa-tester only; qa-lead invoked at phase gates only | qa-lead + qa-tester pipeline | qa-lead + per-story qa-tester spawn + sign-off |
-| **team-release** | release-manager only | + producer + devops-engineer + qa-lead | + security-engineer + analytics-engineer + localization-lead |
+| **team-release** | release-manager only | + producer + devops-engineer + qa-lead + community-manager | + security-engineer + analytics-engineer + localization-lead + performance-analyst, and network-programmer when the game is multiplayer |
+| **team-polish** | performance-analyst + technical-artist; no programmer is active, so Phase 2's optimisation list is handed to `/dev-story` | + sound-designer + qa-tester + engine-programmer (implements Phase 2's optimisation list), and tools-programmer when Phase 1 traces a cause to a content authoring tool | engine-programmer, as at small, + adversarial review pass (Phase 5's qa-tester looks for how it breaks) |
+| **team-live-ops** | live-ops-designer + economy-designer | + analytics-engineer + community-manager | + writer + narrative-director |
 | **gate-check** | Panel width is `modes.workflow`'s axis, not this one (gates always run) — `team.size` affects only specialist depth within each director's review | Same as individual for directors; specialists within directors' reviews use small set | Same plus engine sub-specialists |
-| **architecture-decision** | TD + lead-programmer; engine-specialist | TD + LP + engine-specialist + engine sub-specialist if applicable | All of small + adversarial review by alternate engine-specialist |
+| **architecture-decision** | TD-ADR (in `full` review mode) + the primary engine specialist | Same | Same — no sub-specialist or adversarial reviewer at any size |

 ---

 ### Special cases

- The 3 directors (CD, TD, PR) are present in ALL team sizes — phase gates require them. The setting affects *who else* shows up.
+- `team.size` does not decide whether directors run: `/gate-check`'s panel follows `review_mode` and `modes.workflow`, and no `team-*` pipeline spawns a director phase gate. In a team skill, a "phase gate" is one of the decision points its own pipeline lists, whatever the `automation` mode.
 - `individual` does not disable agents — it just changes which are active by default. Any agent can still be invoked by name.
 - When `team.size: individual` and a non-core agent is needed (e.g. `network-programmer` for a multiplayer story), the skill emits an informational note and routes through the nearest active core agent.

@@ -1330,11 +1337,11 @@ closing, or produces a warning and lets work continue — per test type
 **Controls:** Whether the project includes real-time online multiplayer — determines
 which specialists are routed and which architecture sections are required  
 **Values:** `true` | `false`  
-**Default:** `false`  
-**Set by:** `/setup-engine`, `/settings`  
-**Read by:** `dev-story`, `create-architecture`, `security-audit`, `team-release`, `gate-check`
+**Default:** none — unset is not `false`  
+**Set by:** `/settings`  
+**Read by:** `security-audit`, `team-release` (and the `security-engineer` agent)

-**Priority chain:** `platform.multiplayer` in `project.yaml` → hardcoded default of `false`
+**Priority chain:** `platform.multiplayer` in `project.yaml` → unset (`platform.*` is locked to `project.yaml`, so `project.local.yaml` cannot set it). Nothing writes it except `/settings`, so on most projects it is unset: `/security-audit` and `/team-release` ask whether the game is multiplayer rather than reading unset as `false`.

 > **Distinct from `platform.online`.** `multiplayer` is *real-time multiplayer
 > specifically* (network specialist, netcode review, replication architecture).
@@ -1351,8 +1358,8 @@ which specialists are routed and which architecture sections are required

 | Value | Meaning |
 |-------|---------|
-| `true` | Game has real-time online multiplayer. Network specialist included in routing. Architecture requires networking layer. Security audit includes netcode review. |
-| `false` | No real-time multiplayer. Network specialist excluded from routing. Architecture has no networking section. |
+| `true` | Game has real-time online multiplayer. `/security-audit` runs its netcode category and rates a HIGH finding as release-blocking; `/team-release` adds `network-programmer`'s sign-off. |
+| `false` | No real-time multiplayer. `/security-audit` skips the netcode category and says so; `/team-release` does not spawn `network-programmer`. |

 ---

@@ -1360,11 +1367,11 @@ which specialists are routed and which architecture sections are required

 | Skill | multiplayer: true | multiplayer: false |
 |-------|------------------|-------------------|
-| **dev-story** | `network-programmer` included in routing table for networking stories | `network-programmer` excluded — networking stories flagged as out of scope |
-| **create-architecture** | Networking layer section required in architecture doc | Networking section omitted entirely |
-| **security-audit** | Includes netcode review — authentication, replication, cheat vectors | Netcode review skipped |
+| **security-audit** | Includes netcode review — authentication, replication, cheat vectors | Netcode review skipped, and the report says so |
 | **team-release** | `network-programmer` included in release sign-off pipeline | `network-programmer` excluded |
-| **gate-check** | Technical Setup gate checks for network architecture ADR | No network architecture requirement |
+
+No other skill reads this key: `/dev-story`, `/create-architecture` and `/gate-check`
+decide networking scope from the story, GDD or architecture in front of them.

 ---

@@ -1372,11 +1379,11 @@ which specialists are routed and which architecture sections are required

 **Controls:** Whether the project has any online features (leaderboards, cloud saves, telemetry, IAP)
 **Values:** `true` | `false`
-**Default:** `false`
-**Set by:** `/setup-engine`, `/settings`
-**Read by:** `dev-story`, `create-architecture`, `security-audit`, `team-live-ops`, `gate-check`
+**Default:** none — unset is not `false`
+**Set by:** `/settings`
+**Read by:** `security-audit`, `team-release` (and the `security-engineer` agent)

-**Priority chain:** `platform.online` in `project.yaml` → hardcoded default of `false`
+**Priority chain:** `platform.online` in `project.yaml` → unset (`platform.*` is locked to `project.yaml`, so `project.local.yaml` cannot set it). Nothing writes it except `/settings`: `/security-audit` and `/team-release` ask rather than reading unset as `false`.

 > **Independent of `platform.multiplayer`.** A single-player game with Steam
 > Cloud and leaderboards is `online: true, multiplayer: false`. The two settings
@@ -1388,8 +1395,8 @@ which specialists are routed and which architecture sections are required

 | Value | Meaning |
 |-------|---------|
-| `true` | Project includes online services (cloud saves, leaderboards, achievements, telemetry, IAP, anything calling external APIs at runtime). Analytics-engineer included; live-ops considerations active; security-audit includes data-transit review. |
-| `false` | Project is fully offline. No analytics-engineer routing, no live-ops scope, security audit is local-only. |
+| `true` | Project includes online services (cloud saves, leaderboards, achievements, telemetry, IAP, anything calling external APIs at runtime). `/security-audit` runs Category 2 (network and multiplayer — including a plaintext-token check) when this or `platform.multiplayer` is true or unset; `/team-release` adds a `security-engineer` sign-off. |
+| `false` | Project is fully offline. `/security-audit` skips Category 2 only when `platform.multiplayer` is also false. |

 ---

@@ -1397,11 +1404,11 @@ which specialists are routed and which architecture sections are required

 | Skill | online: true | online: false |
 |-------|--------------|---------------|
-| **create-architecture** | Data layer must include online service integration (cloud save sync, leaderboard auth, telemetry buffering) | Data layer is local storage only |
-| **security-audit** | Includes data-transit review — TLS, save data integrity, leaderboard tampering | Local-only review (save file tampering, save data privacy) |
-| **dev-story** | `analytics-engineer` routed for telemetry stories | analytics-engineer not routed |
-| **team-live-ops** | Skill is available (live-ops-designer routes meaningfully) | Skill emits "no online features — live ops scope is empty" |
-| **gate-check** | Technical Setup gate checks for online architecture decisions in critical ADRs | No online ADR requirement |
+| **security-audit** | Category 2 (network) runs — server authority, packet validation, rate limits, plaintext tokens | Category 2 skipped only when `platform.multiplayer` is also false |
+| **team-release** | `security-engineer` sign-off when the game is online or stores player data | No online-driven security sign-off |
+
+No other skill reads this key: `/create-architecture`, `/dev-story`, `/team-live-ops`
+and `/gate-check` decide online scope from the documents in front of them.

 ---

@@ -1409,17 +1416,20 @@ which specialists are routed and which architecture sections are required

 > ### WIRED — this setting is live
 >
-> `/launch-checklist` and `/release-checklist` both resolve it and emit
-> console/mobile certification items only for the platforms it names, asking
-> which are in scope when it is unset.
+> `/launch-checklist` and `/release-checklist` both resolve it and branch on its
+> four values — `none` emits no certification section, `itch` and `steam` their
+> storefront's requirements, `console` full platform certification — and ask which
+> platforms are in scope when it is unset.

 **Controls:** Certification target — scopes what `/launch-checklist` asks for
 **Values:** `none` | `itch` | `steam` | `console`
-**Default:** `none`
-**Set by:** `/setup-engine`, `/settings`
+**Default:** *none* — unset stays unset, so the skills ask
+**Set by:** `/settings` — nothing else writes it, so it stays unset (and the skills ask) until you set it
 **Read by:** `/launch-checklist`, `/release-checklist`

-**Priority chain:** `platform.cert_tier` in `project.yaml` → hardcoded default of `none`
+**Priority chain:** `platform.cert_tier` in `project.yaml` → unset (no default is
+substituted: unset is a missing decision, `none` is a made one, and the skills
+must tell them apart)

 ---

@@ -1460,8 +1470,8 @@ which specialists are routed and which architecture sections are required
 **Controls:** Accessibility commitment level — routes accessibility specialist and gates audit requirements
 **Values:** `none` | `standard` | `aaa`
 **Default:** `none`
-**Set by:** `/start`, `/settings`
-**Read by:** `/team-ui`, `/team-level`, `/team-polish`, `/gate-check`
+**Set by:** `/settings`
+**Read by:** nothing yet (intended readers: `/team-ui`, `/team-level`, `/team-polish`, `/gate-check`)

 **Priority chain:** `accessibility.target` in `project.yaml` → hardcoded default of `none`

@@ -1507,13 +1517,13 @@ which specialists are routed and which architecture sections are required
 - `sprint_length`: `1w` | `2w` | `3w` | `4w` | `none`
 - `milestone_length`: `4w` | `6w` | `8w` | `12w`
 **Defaults:** `sprint_length: 2w`, `milestone_length: 8w`
-**Set by:** `/start`, `/settings`
-**Read by:** `/sprint-plan`, `/milestone-review`, `/sprint-status`, future velocity tracking
+**Set by:** `/settings`
+**Read by:** nothing yet (intended readers: `/sprint-plan`, `/milestone-review`, `/sprint-status`, future velocity tracking)

 **Priority chain:** `cadence.*` in `project.yaml` → hardcoded defaults

 > **`none` for `sprint_length`** means continuous-flow / kanban-style — no sprint boundaries.
-> `/sprint-plan` becomes `/work-plan` and is invoked manually as needed. Velocity tracking
+> `/sprint-plan` is then invoked manually as needed. Velocity tracking
 > is per-week rather than per-sprint.

 ---
@@ -1535,7 +1545,7 @@ which specialists are routed and which architecture sections are required
 **Values:** integers (e.g. `60`, `16.67`)
 **Default:** none — unset means no budget was ever committed to
 **Set by:** the user, by hand or via `/settings`
-**Read by:** `/perf-profile`, `/gate-check`
+**Read by:** `/perf-profile`, `/gate-check`, `/team-polish`

 ## performance.draw_call_limit and performance.memory_ceiling_mb

@@ -1543,7 +1553,7 @@ which specialists are routed and which architecture sections are required
 **Values:** integers
 **Default:** none — unset means no budget was ever committed to
 **Set by:** the user, by hand or via `/settings`
-**Read by:** `/perf-profile`, `/gate-check`
+**Read by:** `/perf-profile`, `/gate-check`, `/team-polish`

 > **Every setting needs its own `## ` heading in this file, not just a table
 > row.** The dead-settings audit derives what it checks from those headings, so
@@ -1563,7 +1573,7 @@ which specialists are routed and which architecture sections are required
 **Controls:** Whether performance budget violations warn or block
 **Values:** `warn` | `block` | `off`
 **Default:** `warn`
-**Set by:** `/start`, `/settings`
+**Set by:** `/settings`
 **Read by:** `/perf-profile`, `/gate-check`, CI runner

 **Priority chain:** `performance.enforce` in `project.local.yaml` → `project.yaml` → hardcoded default of `warn`, resolved by `resolve_config --keys performance.enforce`
@@ -1592,17 +1602,18 @@ which specialists are routed and which architecture sections are required
 validates and what artifacts are expected to exist  
 **Values:** `Concept` | `Systems Design` | `Technical Setup` | `Pre-Production` | `Production` | `Polish` | `Release`  
 **Default:** `Concept`  
-**Set by:** `/gate-check` on PASS verdict only — never set manually  
-**Read by:** `gate-check`, `project-stage-detect`, `help`, `sprint-status`, `day-one-patch`
+**Set by:** `/gate-check` on a PASS, or on a CONCERNS the user explicitly accepts (the accepted risks are recorded); a FAIL never advances it — never set manually  
+**Read by:** `gate-check`, `project-stage-detect`, `help`, `day-one-patch`, `team-release`, `launch-checklist`, `release-checklist`, `map-systems`, `team-qa`, `adopt`

 > **Stage count:** This document uses the
 > 7-stage reality implemented by gate-check:
 > `Concept | Systems Design | Technical Setup | Pre-Production | Production | Polish | Release`

 > **This is a project attribute, not a mode.** It records where the project is
-> in its lifecycle. Only `/gate-check` writes it — and only on a PASS verdict
-> with user confirmation. Never write it manually mid-session except to correct
-> an incorrect auto-detect.
+> in its lifecycle. Only `/start` (at onboarding) and `/gate-check` write it —
+> `/gate-check` on a PASS verdict with user confirmation, or on a CONCERNS
+> verdict whose risks the user explicitly accepts (they are recorded); a FAIL never advances it.
+> Never write it manually mid-session except to correct an incorrect auto-detect.

 > **Legacy fallback + dual-write.** Stage is read from `project.stage` in
 > `project.yaml` first, then legacy `production/stage.txt`, then artifact
@@ -1621,10 +1632,10 @@ Each row is the gate that must be passed to advance FROM that stage.
 |------------|-------------------------------|-------------------|
 | **Concept** | `game-concept.md`, design pillars, Visual Identity Anchor | `Systems Design` |
 | **Systems Design** | `systems-index.md`, all MVP GDDs reviewed, cross-GDD consistency check | `Technical Setup` |
-| **Technical Setup** | Engine configured, art bible sections 1–4 (if visual stories exist), 3+ ADRs, architecture doc, control manifest, test framework | `Pre-Production` |
-| **Pre-Production** | Prototype, 3+ playtests, UX specs, epics defined, first sprint plan | `Production` |
+| **Technical Setup** | Engine configured, art bible sections 1–4 (at `standard`, only if visual stories exist), 3+ ADRs, architecture doc, traceability index, test framework, accessibility and interaction-pattern docs | `Pre-Production` |
+| **Pre-Production** | Epics defined, first sprint plan, UX specs, control manifest (a Vertical Slice is recommended, not required) | `Production` |
 | **Production** | Core mechanics implemented, main path playable, smoke check passes, QA sign-off | `Polish` |
-| **Polish** | All features complete, content complete, localization, no critical bugs | `Release` |
+| **Polish** | All features complete, content complete, localization, security audit, no open S1–S3 bugs | `Release` |

 Gates adjust per `modes.workflow` — see `modes.workflow` section for what is
 required at `standard` and `minimal` levels.
@@ -1635,11 +1646,12 @@ required at `standard` and `minimal` levels.

 | Skill | How it uses stage |
 |-------|------------------|
-| **gate-check** | Reads current stage to determine which gate to validate. Writes next stage on PASS. |
+| **gate-check** | Reads current stage to determine which gate to validate. Writes next stage on PASS, or on a CONCERNS the user explicitly accepts. |
 | **project-stage-detect** | Reads `project.stage` first — if set, uses it as authoritative. Falls back to heuristic detection only if absent. |
 | **help** | Uses stage to determine "where are you in the pipeline" and surfaces the correct next steps. |
 | **sprint-status** | Displays current stage in status summary. |
-| **day-one-patch** | Validates that stage is `Release` before proceeding — refuses to run if project is not at release stage. |
+| **day-one-patch** | Proceeds only when the stage is `Release` or `Polish`; otherwise says it is not appropriate yet. |
+| **team-release** | Stops before Phase 1 unless the stage is `Release` ("run `/gate-check release` first"); proceeding takes an explicit override, recorded in the go/no-go record and the report. Never writes the stage. |

 ---

@@ -1693,7 +1705,7 @@ implementation, review, and architecture validation
 **Values:** `Godot` | `Unity` | `Unreal`  
 **Default:** `[UNSET]` — must be configured via `/setup-engine`  
 **Set by:** `/setup-engine`  
-**Read by:** `dev-story`, `code-review`, `architecture-decision`, `create-architecture`, all `team-*` skills
+**Read by:** `dev-story`, `code-review`, `architecture-decision`, `create-architecture`, `team-combat`, `team-ui`, `team-audio`

 > **Currently stored in `technical-preferences.md`**, not `project.yaml`. After
 > YAML expansion, `engine.name` and the specialist routing table move to
@@ -1725,7 +1737,7 @@ implementation, review, and architecture validation
 | **code-review** | Routes review to language, shader, or UI specialist based on file type being reviewed. |
 | **architecture-decision** | Loads `docs/engine-reference/[engine]/VERSION.md` before authoring. Spawns engine specialist to validate ADR for API correctness and post-cutoff compatibility. |
 | **create-architecture** | Includes engine-specific constraints and patterns in architecture doc based on engine choice. |
-| **team-combat / team-ui / team-audio / team-level / team-polish** | All team skills spawn the appropriate engine specialist for implementation phases. |
+| **team-combat / team-ui / team-audio** | Spawn the engine specialist their pipeline names: team-combat the primary engine specialist (from `team.size: small`), team-ui the engine UI specialist (`specialists.ui`, at `studio`), team-audio the primary engine specialist (at `studio`). The other six `team-*` skills spawn none. |

 ---

@@ -1742,7 +1754,7 @@ implementation, review, and architecture validation
 **Values:** strings — shell-executable commands
 **Default:** `[UNSET]` — populated by `/setup-engine` with engine-typical defaults
 **Set by:** `/setup-engine`, `/settings`
-**Written by:** `/setup-engine`, `/settings`. **Read by:** `test` — `/dev-story` (Phase 6 parse check), `/smoke-check`, `project-coherence.sh`; `smoke` — `/dev-story`; `build` — `/smoke-check`, `project-coherence.sh`; `run` — `/dev-story` (Phase 6 step 4, the run-and-observe step). `/launch-checklist` and `/regression-suite` name these commands but cannot execute them — their `allowed-tools` has no `Bash`.
+**Written by:** `/setup-engine`, `/settings`. **Read by:** `test` — `/smoke-check`, `/hotfix` (narrowed to the affected suite), `/bug-report` (verify mode, narrowed to the affected suite), `/day-one-patch` (targeted fix and, when set, the broader regression — NOT ASSESSED if unset), `/dev-story` (Godot parse-check executable resolution), `/test-setup` (the `<Project>.` filter root on Unreal), `project-coherence.sh`; `smoke` — `/dev-story` (Unity parse check), `/smoke-check` (build check when tests are WAIVED); `build` — `/smoke-check` (build check when tests are WAIVED and `smoke` is unset), `project-coherence.sh`; `run` — `/dev-story` (Phase 6 step 4, the run-and-observe step). `/launch-checklist` and `/regression-suite` name these commands but do not run them.
  *(Derived by grep. A helper-based read would not show up, so treat this list as the verified floor, not a ceiling.)*

 **Priority chain:** `commands.*` in `project.yaml` → engine-typical default → no command available
@@ -1762,7 +1774,7 @@ Each command can be a simple string (used on all OSes) or an OS-aware map:
 ```yaml
 commands:
  build: "godot --headless --export-debug '<PRESET>'"   # ask; see the note below
-  test:  "godot --headless --script tests/gdunit4_runner.gd"
+  test:  "godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode"
  run:   "godot --path . --windowed --resolution 1280x720"
  smoke: "godot --headless --quit-after 5"
 ```
@@ -1779,7 +1791,7 @@ commands:
    windows: "godot.exe --headless --export-debug 'Windows Desktop'"
    macos:   "godot --headless --export-debug 'macOS'"
  test:
-    default: "godot --headless --script tests/gdunit4_runner.gd"
+    default: "godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode"
  run:
    default: "godot --path . --windowed --resolution 1280x720"
  smoke:
@@ -1797,10 +1809,10 @@ keys are inside the locked file, not a local override).

 | Field | Purpose |
 |-------|---------|
-| `build` | Full project build for CI or release. Used by `/launch-checklist`, CI hooks. |
-| `test` | Run the full test suite. Used by `/smoke-check`, `/regression-suite`, CI hooks. |
+| `build` | Full project build for CI or release. `/smoke-check` runs it only as the WAIVED-path build check when `commands.smoke` is unset; `project-coherence.sh` (which `/smoke-check` runs first) checks the export preset it names, and `/launch-checklist` only asks whether the build produces a valid artifact. |
+| `test` | Run the full test suite. Run by `/smoke-check` and, narrowed to the affected suite, by `/hotfix`, `/bug-report` (verify mode) and `/day-one-patch`; `project-coherence.sh` checks the runner it names. `/regression-suite` does **not** run it. |
 | `run` | Launch the **game** windowed at a fixed resolution — not the editor. Used by `/dev-story` Phase 6 step 4 to observe the feature and retain a screenshot; see `.claude/docs/run-and-observe.md` for the per-engine capture flags that are appended to it. |
-| `smoke` | Minimal "does it boot?" check. Named by `/smoke-check` in its prose. Should complete in < 5 seconds. |
+| `smoke` | Minimal "does it boot?" check. Run by `/dev-story` as the Unity parse check (Phase 6 step 2), and by `/smoke-check` as the build check when `qa.level: minimal` waives tests. |

 ---

@@ -1814,9 +1826,13 @@ engine reference in this repo can source it. See `/setup-engine` §"The Godot

 | Engine | build | test | run | smoke |
 |--------|-------|------|-----|-------|
-| Godot | `godot --headless --export-debug '<PRESET>'` | `godot --headless --script tests/gdunit4_runner.gd` | `godot --path . --windowed --resolution 1280x720` | `godot --headless --quit-after 5` |
-| Unity | `Unity -batchmode -quit -projectPath . -buildTarget <TARGET>` | `Unity -runTests -projectPath . -testPlatform PlayMode` | `Builds/<Target>/<Game>.exe -screen-width 1280 -screen-height 720 -screen-fullscreen 0` | `Unity -batchmode -quit -projectPath . -executeMethod SmokeCheck.Run` |
-| Unreal | engine-specific (varies by version) | engine-specific | engine-specific | engine-specific |
+| Godot | `godot --headless --export-debug '<PRESET>'` | `godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode` | `godot --path . --windowed --resolution 1280x720` | `godot --headless --quit-after 5` |
+| Unity | `"<Unity editor>" -batchmode -quit -projectPath . -buildTarget <TARGET> -build<PLATFORM>Player Builds/<Target>/<Game>.exe` | `"<Unity editor>" -batchmode -runTests -projectPath . -testPlatform EditMode -testResults test-results/editmode.xml` | `Builds/<Target>/<Game>.exe -screen-width 1280 -screen-height 720 -screen-fullscreen 0` | `"<Unity editor>" -batchmode -quit -projectPath . -logFile -` |
+| Unreal | `"<UE root>/Engine/Binaries/DotNET/AutomationTool/AutomationTool.exe" BuildCookRun -project="$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -platform=Win64 -build -cook` (confirm per project) | `"<UE root>/Engine/Binaries/Win64/UnrealEditor-Cmd.exe" "$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -ExecCmds="Automation RunTests <project>.; Quit" -unattended -nullrhi -stdout -FullStdOutLogOutput` | `"<UE root>/Engine/Binaries/Win64/UnrealEditor.exe" "$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -game -windowed -ResX=1280 -ResY=720` | `"<UE root>/Engine/Binaries/Win64/UnrealEditor-Cmd.exe" "$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -game -nullrhi -unattended -stdout -ExecCmds="Quit"` |
+
+The Unreal row is Windows'. `/setup-engine` writes the Linux block (`Engine/Build/BatchFiles/RunUAT.sh`,
+`Engine/Binaries/Linux/UnrealEditor`) on Linux, and on macOS only `build`, leaving `test`, `run` and
+`smoke` as TODOs — see `docs/engine-reference/unreal/current-best-practices.md`, "Command Line".

 > **`<PRESET>` and `<TARGET>` are placeholders, not values to copy.** A Godot
 > export preset is whatever string the operator typed into `export_presets.cfg`;
@@ -1836,11 +1852,11 @@ Users override per-project as needed via `/settings commands.<field>=<value>` or

 | Skill | How `commands` is used |
 |-------|------------------------|
-| **smoke-check** | Invokes `commands.smoke` (or `commands.test` for full pass). Critical path for QA hand-off. |
-| **launch-checklist** | Emits a checklist **item** asking whether the build produces a valid artifact. It does **not** run `commands.build` — its `allowed-tools` has no `Bash`. The verification is a human step. |
-| **validate-push.sh** | Does **not** read `commands.*`. It warns on pushes to protected branches (`develop`/`main`/`master`) and runs no build or smoke command — the block path in it is commented out, so it never fails a push. |
-| **dev-story** | Phase 6 step 2 runs `commands.test` or `commands.smoke` as the parse check. Phase 6 step 4 runs `commands.run` — the windowed game launch — to observe the feature and retain a screenshot (`.claude/docs/run-and-observe.md`). |
-| **regression-suite** | Maps coverage by **globbing test filenames**. It does **not** invoke `commands.test` — its `allowed-tools` has no `Bash`, so coverage here means "a test file exists", never "a test passed". |
+| **smoke-check** | Runs `commands.test`, or the engine's default when it is unset; on Unreal it builds the editor target first. Critical path for QA hand-off. |
+| **launch-checklist** | Emits a checklist **item** asking whether the build produces a valid artifact. It does **not** run `commands.build`; the verification is a human step. |
+| **validate-push.sh** | Does **not** read `commands.*`. It warns on pushes to protected branches (`main`/`master`/`release/*`) and runs no build or smoke command — the block path in it is commented out, so it never fails a push. |
+| **dev-story** | Phase 6 step 2 is the parse check: `.claude/scripts/godot-parse-check.gd` on Godot, `commands.smoke` on Unity, the editor-target build on Unreal. Phase 6 step 4 runs `commands.run` — the windowed game launch — to observe the feature and retain a screenshot (`.claude/docs/run-and-observe.md`). |
+| **regression-suite** | Maps coverage by **globbing test filenames**. It does **not** invoke `commands.test`, so coverage here means "a test file exists", never "a test passed". |

 ---

@@ -1865,10 +1881,12 @@ conventions into a brief, manifest or spec. **NOT by `/code-review` and NOT by
 > naming logic. If you need enforcement, it has to be added.
 >
 > **Known rough edge — asset filenames.** `validate-assets.sh` warns unless files
-> under `assets/` are lowercase-with-underscores, and it takes no config input,
-> while `/asset-spec` specifies asset names from `naming.*`. On Unity, Unreal and
-> Godot-C#, where `/setup-engine` sets `naming.files: PascalCase`, that hook will
-> warn on assets named exactly as `/asset-spec` specified them. The two are
+> under Godot's `assets/` are lowercase-with-underscores, and it takes no config
+> input, while `/asset-spec` specifies asset names from `naming.*`. Unity's
+> `Assets/` and Unreal's `Content/` are not naming-checked: those engines name
+> assets in PascalCase. On Godot-C#, where `/setup-engine` sets
+> `naming.files: PascalCase`, the hook will warn on assets named exactly as
+> `/asset-spec` specified them. The two are
 > measuring different things — `naming.files` describes **source** files by its
 > own examples (`PlayerController.cs`), and no key currently governs asset
 > filenames — so treat the hook's naming warning as advisory on those engines.
@@ -1929,27 +1947,29 @@ log files, `active.yaml` checkpoint — see the scope note above) or relies on
 skeleton-first output files for recovery  
 **Values:** `off` | `on`  
 **Default:** `on`  
-**Set by:** `/start`, `/settings`  
-**Read by:** All 7 session-lifecycle hooks; `statusline.sh`; any skill that writes
-to `production/session-state/`
+**Set by:** `/settings`  
+**Read by:** Six hooks — `session-start.sh` (its recovery preview only),
+`pre-compact.sh`, `post-compact.sh`, `session-stop.sh`, `log-agent.sh` and
+`log-agent-stop.sh`. No skill reads it, and neither does `statusline.sh`.

-> **This is the recommended setting for most users.** The session state pipeline
-> was built to solve mid-task context loss during long conversations, but the
-> problem is better solved by long-form skills writing self-describing skeleton
-> files upfront. `session_state: on` is an opt-in for teams or power users who
-> want explicit tracking across many files over many days.
+> **`on` is the recommended setting.** Long-form skills write self-describing
+> skeleton files upfront, which covers much of mid-task recovery on its own; the
+> session pipeline adds the checkpoint preview at session start, the session
+> archive and the subagent tally. Turn it `off` only to save that preview's
+> tokens.

 > **Priority chain:** `features.session_state` in `project.local.yaml` →
 > `project.yaml` → hardcoded default of **`on`**. Hooks read it via
 > `session_state_enabled()` in `yaml-helper.sh` and exit early when `off`.
-> Skills check it before writing to `production/session-state/`.
+> Skills do not read it: `/dev-story` and `/story-done` update the checkpoint in
+> `active.md` whatever its value.

 > **The default is `on`, deliberately.** `.claude/docs/context-management.md`
 > tells you to rely on `production/session-state/active.md` as your
 > crash-recovery checkpoint, so defaulting this off would quietly take away
-> recovery, the session archive and the subagent tally. The ~2–5k tokens per
-> session are an explicit opt-out (`/settings features.session_state=off`),
-> never a silent default.
+> recovery, the session archive and the subagent tally. What `off` saves — the
+> checkpoint preview, at most ~750 tokens per session start — is an explicit
+> opt-out (`/settings features.session_state=off`), never a silent default.

 > **`session-start.sh` is gated per-block, not at the top.** Its sprint,
 > milestone and git context is not part of the session-state pipeline; only the
@@ -1963,25 +1983,27 @@ to `production/session-state/`

 | Value | Intent |
 |-------|--------|
-| `off` | Recovery via skeleton-first output files. Long-form skills write a complete skeleton (all section headers, empty bodies) before starting. If context clears or compacts, the agent reads the skeleton + relevant docs and resumes. No hooks, no logs, no separate state file. ~2,000–5,000 tokens saved per session. |
-| `on` | Full session tracking. `active.yaml` checkpoint, session-stop archival, compaction log, agent audit log, and STATUS breadcrumb all active. Adds ~2,000–5,000 tokens per session-start and ~1,000–6,000 per compaction event. |
+| `off` | Recovery via skeleton-first output files. Long-form skills write a complete skeleton (all section headers, empty bodies) before starting. If context clears or compacts, the agent reads the skeleton + relevant docs and resumes. The six session-state hooks do nothing, so no logs; skills still update the checkpoint in `active.md`, but session start does not show it. Saves at most ~750 tokens per session start. |
+| `on` | Full session tracking. Session-stop archival, compaction log and agent audit log all active. Adds the checkpoint preview to each session start, capped at 25 lines or 3,000 characters (at most ~750 tokens). Compaction hooks log to disk and add nothing to Claude's context. |

 ---

 ### Hook behavior

 > **Implementation note:** The feature flag check lives inside each hook script,
-> not at the harness level. Every session-state-aware hook reads
-> `features.session_state` from `project.yaml` at its top (via Python fallback
-> chain) and exits silently with no output if the value is `off`. This ensures
+> not at the harness level. Every session-state-aware hook calls
+> `session_state_enabled()` from `yaml-helper.sh` at its top (an awk read of
+> `project.local.yaml`, then `project.yaml`) and exits silently with no output if
+> the value is `off` — except `session-start.sh`, which skips only its recovery
+> preview. This ensures
 > the harness always fires the hook — the hook decides whether to act.

 | Hook | session_state: off | session_state: on |
 |------|--------------------|-------------------|
 | **session-start.sh** | Runs normally (git/sprint context) — skips active.yaml preview block | Runs fully including active.yaml preview |
 | **detect-gaps.sh** | Runs unchanged — gap detection is independent of session state | Runs unchanged |
-| **pre-compact.sh** | Emits: "Read skeleton files and relevant docs to resume" — no active.yaml dump, no WIP scan, no compaction-log append | Full dump: active.yaml content + git diff + WIP scan + compaction-log append |
-| **post-compact.sh** | No-op — exits silently | Runs: reminds agent to re-read active.yaml |
+| **pre-compact.sh** | No-op — exits silently (no compaction-log append) | The CHECKPOINT block (and any STATUS lines) from `active.md`, changed and untracked file names and design docs with WIP markers — each list capped at 20 — then a compaction-log append; the output goes to the debug log, since PreCompact output never reaches Claude |
+| **post-compact.sh** | No-op — exits silently | Runs: prints a re-read reminder to the debug log (PostCompact output never reaches Claude; `session-start.sh` restores context) |
 | **session-stop.sh** | No-op — exits silently | Archives active.yaml to session-log, appends commits and diffs |
 | **log-agent.sh** | No-op — exits silently | Appends to agent-audit.log |
 | **log-agent-stop.sh** | No-op — exits silently | Appends to agent-audit.log |
@@ -1992,7 +2014,7 @@ to `production/session-state/`

 | File | session_state: off | session_state: on |
 |------|--------------------|-------------------|
-| `production/session-state/active.yaml` | Not created | Written by skills, read by hooks and status line |
+| `production/session-state/active.md` | Still written by skills; session start does not show it | Written by skills; session start shows its checkpoint |
 | `production/session-logs/session-log.md` | Not written | Append-only archive of each session's active.yaml |
 | `production/session-logs/compaction-log.txt` | Not written | Append-only timestamp log of compaction events |
 | `production/session-logs/agent-audit.log` | Not written | Append-only log of agent spawn/complete events |
@@ -2029,11 +2051,11 @@ and resumes at the first `incomplete` section. No active.yaml needed.
 | Skill | Output file | Skeleton written when |
 |-------|-------------|----------------------|
 | **design-system** | `design/gdd/[system].md` | Before Phase 1 (section discussion) |
-| **art-bible** | `design/art/art-bible.md` | Before section 1 discussion |
-| **create-architecture** | `docs/architecture/architecture.md` | Before layer discussion |
+| **art-bible** | `design/art/art-bible.md` | From `.claude/docs/templates/art-bible.md`, after asking, when section 1 is approved |
+| **create-architecture** | `docs/architecture/architecture.md` | Not skeleton-first: written once at Phase 7 after its ask (an existing document is updated in place) |
 | **ux-design** | `design/ux/[screen].md` | Before screen discussion |
-| **create-stories** | `production/epics/[epic-slug]/story-NNN-[slug].md` | Before story authoring loop |
-| **create-epics** | `production/epics/[epic-slug]/EPIC.md` | Before epic authoring loop |
+| **create-stories** | `production/epics/[epic-slug]/story-NNN-[slug].md` | Not skeleton-first: written in Step 6, after the ask names every file |
+| **create-epics** | `production/epics/[epic-slug]/EPIC.md` | Not skeleton-first: written after its per-epic "May I write `production/epics/[epic-slug]/EPIC.md` and add its row to `production/epics/index.md`" ask |
 | **map-systems** | `design/gdd/systems-index.md` | Before system enumeration |
 | **brainstorm** | `design/gdd/game-concept.md` (`standard`/`full`) · `design/game-brief.md` (`minimal`) | Before concept discussion |

@@ -2056,14 +2078,16 @@ and resumes at the first `incomplete` section. No active.yaml needed.

 > **Stage detection is always independent of session state.** `statusline.sh`
 > auto-detects stage from `project.yaml` `project.stage` or artifact heuristics regardless
-> of `session_state` value — only the breadcrumb is gated.
+> of `session_state` value, and so is the breadcrumb: `statusline.sh` never reads
+> `session_state`. (At `workflow: minimal` the status line shows the story count
+> instead of the stage.)

 | Feature | session_state: off | session_state: on |
 |---------|--------------------|-------------------|
 | Context % display | Always shown | Always shown |
 | Model display | Always shown | Always shown |
-| Stage display | Always shown (from project.yaml or heuristics) | Always shown (same) |
-| Epic/Feature/Task breadcrumb | Not shown — no active.yaml parsed | Parsed from `status:` block in `active.yaml` |
+| Stage display | From project.yaml or heuristics — except at `workflow: minimal`, where `Minimal · <done>/<total> stories` (or `Minimal · brief` before any story exists) replaces it | Same |
+| Epic/Feature/Task breadcrumb | Parsed from `status:` block in `active.yaml` (not gated) | Parsed from `status:` block in `active.yaml` |

 ---

@@ -2071,15 +2095,16 @@ and resumes at the first `incomplete` section. No active.yaml needed.

 Skills interact with session state in two ways: **inference** (reading active.yaml
 to resolve a missing argument) and **extraction** (appending a SESSION EXTRACT
-block after completing work). Both behaviors are gated by `session_state`.
+block after completing work). Neither is gated: no skill reads `session_state`,
+so both happen whatever its value.

 #### Inference — skills that read active.yaml to fill in missing arguments

-When `session_state: off`, these skills cannot infer from active.yaml and must
-receive the argument explicitly. If called without an argument, they should prompt
-the user rather than fail silently.
+When active.yaml holds nothing to infer from, these skills must receive the
+argument explicitly. If called without an argument, they should prompt the user
+rather than fail silently.

-| Skill | What it infers from active.yaml | Fallback when `off` |
+| Skill | What it infers from active.yaml | Fallback when nothing is found |
 |-------|----------------------------------|---------------------|
 | **dev-story** | Active story path (when no arg given) | Prompt user for story path |
 | **story-done** | In-progress story path (when no arg given) | Prompt user for story path |
@@ -2087,15 +2112,16 @@ the user rather than fail silently.
 | **team-qa** | Active sprint (when no arg given) | Prompt user for sprint file |
 | **help** | Current task and STATUS block for context-aware suggestions | Responds without session context — surfaces next steps from sprint/epics only |

-#### Extraction — skills that append SESSION EXTRACT to active.yaml
+#### Extraction — skills that write session state to active.md

-These skills append a structured block after completing work when `session_state: on`.
-When `off`, they skip this write entirely.
+These skills write a structured block after completing work, whatever
+`session_state` is. `/dev-story` and `/story-done` overwrite
+the `<!-- CHECKPOINT -->` block; the others append a SESSION EXTRACT.

-| Skill | What it writes to active.yaml |
-|-------|-------------------------------|
-| **dev-story** | Story path, files changed, test written, blockers, next steps |
-| **story-done** | Verdict, story path, tech debt count, next recommended story |
+| Skill | What it writes to active.md |
+|-------|-----------------------------|
+| **dev-story** | Checkpoint: story path, next step, blockers, files changed, run result |
+| **story-done** | Checkpoint: verdict, story path, next story, tech debt count |
 | **architecture-review** | Verdict, TR coverage counts, new TR-IDs, GDD flags, ADR gaps, report path |
 | **prototype** | Prototype scope, current phase, key decisions |
 | **vertical-slice** | Slice concept, current phase, blocked items |
@@ -2108,11 +2134,10 @@ When `off`, they skip this write entirely.

 | Scenario | session_state: off | session_state: on |
 |----------|--------------------|-------------------|
-| Per session start | ~500 tokens (git/sprint context only) | ~2,000–5,000 tokens (+ active.yaml preview) |
-| Per compaction event | ~200 tokens (reminder only) | ~1,000–6,000 tokens (active.yaml + git diff + WIP scan) |
+| Per session start | ~500 tokens (git/sprint context only) | ~500–1,250 tokens (+ checkpoint preview, at most ~750) |
+| Per compaction event | 0 (compaction hook output never reaches Claude) | 0 (logged to disk only) |
 | Per session end | 0 | File I/O only (no conversation tokens) |
 | Recovery after /clear | Read skeleton + 2–3 docs (~1,000–3,000 tokens) | Read active.yaml (~200–500 tokens) |
-| Net for 50 sessions, 2 compactions/session | ~60,000 tokens | ~250,000–550,000 tokens |

 > **Note:** The `off` recovery cost (reading skeleton + docs) is paid only when
 > recovery is actually needed. The `on` session-start cost is paid every session
@@ -2133,8 +2158,8 @@ When `off`, they skip this write entirely.
 **Controls:** Context usage threshold at which session warnings fire
 **Values:** float between 0.0 and 1.0
 **Default:** `0.7` (warn at 70%)
-**Set by:** `/start`, `/settings`
-**Read by:** `pre-compact.sh`, `session-start.sh`, `statusline.sh`
+**Set by:** `/settings`
+**Read by:** nothing yet (intended readers: `pre-compact.sh`, `session-start.sh`, `statusline.sh`)

 **Priority chain:** `features.token_budget_warn_at` in `project.yaml` → hardcoded default of `0.7`

@@ -2183,10 +2208,10 @@ When `off`, they skip this write entirely.

 **Controls:** Tracks which CCGS version created or last touched this project
 **Values:** `framework.version` (semver string) + `framework.last_upgraded` (ISO date)
-**Default:** auto-populated by `/start` and `/adopt`
-**Set by:** `/start`, `/adopt`
-**Read by:** no skill branches on it — it is file metadata, not a behavioural setting. It appears in `/start`, `/gate-check`, `/brainstorm`, `/settings` and `/setup-engine` as part of the `project.yaml` block they **write or display**, and in `yaml-helper.sh`.
-  *(The five skills above were verified to name it; whether each reads it or merely emits it was NOT separated, so this says 'appears in', not 'read by'.)*
+**Default:** stamped in the template's `project.yaml` at each release
+**Set by:** the template; `/start` (Phase 3c), `/setup-engine` and `/gate-check` write the block into a `project.yaml` they create, and `migrate-v1-config.sh` (which `/adopt` runs) writes `framework.version` into the one it builds
+**Read by:** no skill branches on it — it is file metadata, not a behavioural setting. It appears in `/start`, `/gate-check`, `/settings` and `/setup-engine` as part of the `project.yaml` block they **write or display**, and in `yaml-helper.sh`.
+  *(The four skills above were verified to name it; whether each reads it or merely emits it was NOT separated, so this says 'appears in', not 'read by'.)*

 ---

@@ -2200,17 +2225,16 @@ framework:

 | Field | Purpose |
 |-------|---------|
-| `version` | The CCGS version that created the project (or last ran `/upgrade`). Used to determine which migrations apply when CCGS itself is updated. |
-| `last_upgraded` | ISO date of most recent `/adopt` or `/upgrade` run. Helps detect long-stale projects. |
+| `version` | The CCGS version that created the project (or was last updated to — see `UPGRADING.md`). |
+| `last_upgraded` | ISO date of the most recent template update. |

 ---

 ### Affected skills

-| Skill | How it uses framework |
-|-------|----------------------|
-| **adopt** | Reads `framework.version` to determine which migration steps apply. Updates both fields after running. |
-| **session-start hook** | Warns if `last_upgraded` is more than 90 days stale: "Project was last upgraded over 3 months ago — consider running /adopt." |
+None. No skill or hook reads `framework.version` or `last_upgraded` — `/adopt`
+does not consult them and no hook checks their age. They record which template
+version the project came from; `UPGRADING.md` is the upgrade path.

 ---

@@ -2248,11 +2272,11 @@ director reviews" tier; v1.1 renamed that tier to `solo` (the enum is
 the rename in the migration report's Warnings. This is the one documented value
 rename, so it is mapped-and-flagged rather than preserved raw: writing `none`
 verbatim would produce an enum-invalid `project.yaml` that `resolve_config` rejects
-and falls back to `lean` (reviews *on*) — inverting the user's intent. The
+and falls back to the `modes.rigor` value — at `standard` that is `lean`, reviews *on* —
+inverting the user's intent. The
 `--finalize` preservation check applies the same mapping so it does not falsely
 refuse. Every *other* non-v1.1 stage/review value is a fork, not a rename:
-preserved raw and flagged for manual resolution, never coerced (test II.21-23; the
-rename is II.25-27).
+preserved raw and flagged for manual resolution, never coerced.

 Settings absent from the legacy files (new v1.1 settings like `qa.level`,
 `docs.density`, `team.size`, etc.) get hardcoded defaults from the v1.1 schema.
@@ -2399,8 +2423,8 @@ performance:

 commands:                    # simple string OR OS-aware map per command
  build: "godot --headless --export-debug '<PRESET>'"   # your export_presets.cfg name
-  test: "godot --headless --script tests/gdunit4_runner.gd"
-  run: "godot --editor"
+  test: "godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode"
+  run: "godot --path . --windowed --resolution 1280x720"
  smoke: "godot --headless --quit-after 5"

 features:
@@ -4,7 +4,7 @@ Shared procedure for any skill that spawns agents via the `Agent` tool. Referenc
 `## Error Recovery Protocol` section of each orchestration/review skill. Those
 skills keep the two load-bearing imperatives (surface immediately, produce a
 partial report) inline, and keep their own **Common blockers** list inline —
-those are skill-specific. This file holds the full four-step procedure.
+those are skill-specific. This file holds the full procedure.

 ## Trigger 0 — verify the artifact before reading the response

@@ -40,20 +40,25 @@ When the path is missing:
   over re-spawning — the context is usually still there, and a re-spawn pays
   for the whole investigation again.
 3. If the second attempt also produces nothing, treat it as BLOCKED and apply
-   steps 1–4 below.
+   steps 1–5 below.

 ---

 If any spawned agent returns BLOCKED, errors, or cannot complete:

 1. **Surface immediately** — report "[AgentName]: BLOCKED — [reason]" to the user
-   before continuing to dependent phases.
+   before continuing to dependent phases. The reason names what is missing and
+   where it was expected (the path or the input), so the user can supply it.
 2. **Assess dependencies** — check whether the blocked agent's output is required
   by subsequent phases. If yes, do not proceed past that dependency point without
   user input.
 3. **Offer options** via `AskUserQuestion`:
-   - Skip this agent and note the gap in the final report
+   - Skip this agent and note the gap in the final report — never fill the skipped agent's section with content of your own
   - Retry with narrower scope
   - Stop here and resolve the blocker first
 4. **Always produce a partial report** — output whatever was completed. Never
   discard work because one agent blocked.
+5. **A skip does not clear the block.** In a `/team-*` pipeline, choosing "skip
+   this agent and note the gap" lets the remaining phases run, but the skipped
+   agent's work is missing from what the pipeline delivers: the final verdict is
+   BLOCKED, naming the skipped agent and its gap — never COMPLETE.
@@ -4,19 +4,24 @@ Hooks are configured in `.claude/settings.json` and fire automatically:

 | Hook | Event | Trigger | Action |
 | ---- | ----- | ------- | ------ |
-| `validate-commit.sh` | PreToolUse (Bash) | `git commit` commands | Validates design doc sections, JSON data files, hardcoded values, TODO format |
-| `validate-push.sh` | PreToolUse (Bash) | `git push` commands | Warns on pushes to protected branches (develop/main) |
-| `validate-assets.sh` | PostToolUse (Write/Edit) | Asset file changes | Checks naming conventions and JSON validity for files in `assets/` |
+| `validate-commit.sh` | PreToolUse (Bash, PowerShell) | `git commit` commands | Validates design doc sections, JSON data files, hardcoded values, TODO format |
+| `validate-push.sh` | PreToolUse (Bash, PowerShell) | `git push` commands | Warns on pushes to protected branches (`main`, `master` and `release/*`) |
+| `validate-assets.sh` | PostToolUse (Write/Edit) | Asset file changes | Checks data-file JSON under `assets/`, `Assets/` or `Content/`, and asset naming in Godot's `assets/` only |
 | `session-start.sh` | SessionStart | Session begins | Loads sprint context, milestone, git activity; detects and previews active session state file for recovery |
 | `detect-gaps.sh` | SessionStart | Session begins | Detects fresh projects (suggests /start) and missing documentation when code/prototypes exist, suggests /reverse-document or /project-stage-detect |
-| `pre-compact.sh` | PreCompact | Context compression | Dumps session state (active.md, modified files, WIP design docs) into conversation before compaction so it survives summarization |
-| `post-compact.sh` | PostCompact | After compaction | Reminds Claude to restore session state from `active.md` checkpoint |
+| `pre-compact.sh` | PreCompact | Context compression | Logs the compaction to `production/session-logs/compaction-log.txt`. Its state summary goes to the debug log only: Claude Code does not add PreCompact output to the conversation. `session-start.sh`, which runs again after every compaction, is what restores context |
+| `post-compact.sh` | PostCompact | After compaction | Prints a re-read reminder to the debug log. PostCompact output never reaches Claude; recovery comes from `session-start.sh` |
 | `notify.sh` | Notification | Notification event | Shows Windows toast notification via PowerShell |
 | `session-stop.sh` | Stop | **Every response ends** — not once per session | Summarizes accomplishments, updates session log, and writes the subagent spawn tally to `production/session-logs/session-cost.md`. Archives `active.md` only when its content hash changed; without that guard a long session appended the whole file on every turn. |
-| `log-agent.sh` | SubagentStart | Agent spawned | Audit trail start — logs subagent invocation with timestamp and session id |
-| `log-agent-stop.sh` | SubagentStop | Agent stops | Audit trail stop — completes subagent record |
+| `log-agent.sh` | SubagentStart | Agent spawned, resumed, or a teammate handles a new message | Audit trail start — logs subagent invocation with timestamp and session id. SubagentStart fires for a resume and for each agent-team message too, so the spawn tally counts those |
+| `log-agent-stop.sh` | SubagentStop | Agent stops | Audit trail stop — completes subagent record. Skips Claude Code's internal agents (prompt suggestions, `/btw`), which arrive with an empty `agent_type` |
 | `validate-skill-change.sh` | PostToolUse (Write/Edit) | Skill file changes | Advises running `/skill-test` after any `.claude/skills/` file is written or edited |

+Warnings from the four `validate-*` hooks are shown to you and passed to Claude
+as hook JSON (`hook_warn` in `yaml-helper.sh`); only a problem that must be fixed
+now exits 2. See `hooks-reference/hook-input-schemas.md` for why stderr is not
+enough.
+
 ### Subagent cost visibility

 The three hooks above form one chain. `log-agent.sh` writes a record per spawn
@@ -47,7 +52,7 @@ Three constraints that must not be "tidied" later:

 ## Events considered and deliberately not added

-Claude Code offers many more hook events than the eleven above. These were
+Claude Code offers many more hook events than the nine the hooks above use. These were
 evaluated and rejected. Recorded so a future review does not re-propose them
 from the event list alone.

@@ -1,10 +1,17 @@
 # Hook Input/Output Schemas

-This documents the JSON payloads each Claude Code hook receives on stdin for every event type.
+This documents the JSON payloads each Claude Code hook receives on stdin for every
+event type, and how a hook's output reaches the user and Claude. Every payload
+also carries the common fields `session_id`, `transcript_path`, `cwd` and
+`hook_event_name`; the examples below show the event-specific ones. The full
+reference is the Claude Code hooks documentation (https://code.claude.com/docs/en/hooks).

 ## PreToolUse

-Fired before a tool is executed. Can **allow** (exit 0) or **block** (exit 2).
+Fired before a tool is executed. Exit 2 **blocks** the call. Exit 0 lets it
+continue through the normal permission flow — it does not approve it, and the
+user can still be asked. To warn without blocking, exit 0 and print hook JSON —
+see [Output](#output-warnings-someone-sees) below.

 ### PreToolUse: Bash

@@ -19,6 +26,9 @@ Fired before a tool is executed. Can **allow** (exit 0) or **block** (exit 2).
 }
 ```

+The PowerShell tool sends the same shape with `"tool_name": "PowerShell"`, so a
+matcher of `Bash|PowerShell` covers both.
+
 ### PreToolUse: Write

 ```json
@@ -55,9 +65,18 @@ Fired before a tool is executed. Can **allow** (exit 0) or **block** (exit 2).
 }
 ```

+In real payloads a file tool's `file_path` is absolute, with the platform's own
+separators — backslashes on Windows. Strip the project root first, then match
+from the start of what is left (`assets/data/`). A segment such as
+`/assets/data/` matched anywhere also fires on a parent folder of the same name
+and on files outside the project, such as the user's own `~/.claude/skills/`.
+`validate-assets.sh` shows the stripping.
+
 ## PostToolUse

-Fired after a tool completes. **Cannot block** (exit code ignored for blocking). Stderr messages are shown as warnings.
+Fired after a tool completes. **Cannot block** — the tool already ran. Exit 2
+shows stderr to Claude, so it can fix what it just wrote. stderr on exit 0 goes to
+the debug log only, so an advisory warning must be hook JSON on stdout.

 ### PostToolUse: Write

@@ -68,7 +87,10 @@ Fired after a tool completes. **Cannot block** (exit code ignored for blocking).
    "file_path": "assets/data/enemy_stats.json",
    "content": "{\"goblin\": {\"health\": 50}}"
  },
-  "tool_output": "File written successfully"
+  "tool_response": {
+    "filePath": "assets/data/enemy_stats.json",
+    "type": "create"
+  }
 }
 ```

@@ -82,7 +104,7 @@ Fired after a tool completes. **Cannot block** (exit code ignored for blocking).
    "old_string": "\"health\": 50",
    "new_string": "\"health\": 75"
  },
-  "tool_output": "File edited successfully"
+  "tool_response": { "filePath": "assets/data/enemy_stats.json" }
 }
 ```

@@ -90,35 +112,79 @@ Fired after a tool completes. **Cannot block** (exit code ignored for blocking).

 Fired when a subagent is spawned via the `Agent` tool (named `Task` before
 Claude Code 2.1.63; `Task` still works as an alias in permission rules and
-`tools:` frontmatter, but the hook payload's `tool_name` is now `Agent`).
+`tools:` frontmatter, but the hook payload's `tool_name` is now `Agent`). The
+agent's name is in `agent_type` — there is no `agent_name` field.

 ```json
 {
-  "agent_name": "game-designer",
-  "model": "sonnet",
-  "description": "Design the combat healing mechanic"
+  "agent_id": "agent-abc123",
+  "agent_type": "game-designer"
 }
 ```

 ## SessionStart

-Fired when a Claude Code session begins. **No stdin input** — the hook just runs and its stdout is shown to Claude as context.
+Fired when a session starts, resumes, is cleared with `/clear`, or is compacted.
+Stdin carries `source`: `startup`, `resume`, `clear`, `compact` or `fork`. Plain stdout is
+added to Claude's context — this is the event that restores context after a
+compaction.

 ## PreCompact

-Fired before context window compression. **No stdin input** — the hook runs to save state before compression occurs.
+Fired before context compaction. Stdin carries `trigger` (`manual` or `auto`).
+**Its output does not reach Claude**: stdout goes to the debug log and
+`systemMessage` is discarded. Exit 2 blocks the compaction.

 ## Stop

-Fired when the Claude Code session ends. **No stdin input** — the hook runs for cleanup and logging.
+Fired **every time Claude finishes a response**, not once when the session ends.
+Stdin carries the common fields plus `stop_hook_active` and
+`last_assistant_message`. Exit 2 keeps Claude working instead of stopping.
+
+## Output: warnings someone sees
+
+A hook that warns but must not block exits 0 — and **on exit 0, stderr reaches
+no one**. Print a JSON object on stdout instead:
+
+```json
+{
+  "systemMessage": "Shown to the user",
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "Given to Claude next to the tool result"
+  }
+}
+```
+
+- stdout must hold **only** that object.
+- `hookEventName` is required inside `hookSpecificOutput`.
+- **Leave out `permissionDecision`** unless you mean it: on PreToolUse, `"allow"`
+  skips the user's permission prompt.
+
+CCGS hooks use `hook_warn` from `.claude/hooks/yaml-helper.sh`, which builds this
+object and escapes the message without needing `jq`:
+
+```bash
+. .claude/hooks/yaml-helper.sh
+hook_warn PostToolUse "Asset names must be lowercase: $FILE_PATH"
+exit 0
+```

 ## Exit Code Reference

-| Exit Code | Meaning | Applicable Events |
-|-----------|---------|-------------------|
-| 0 | Allow / Success | All events |
-| 2 | Block (stderr shown to Claude) | PreToolUse only |
-| Other | Treated as error, tool proceeds | All events |
+| Exit Code | Meaning |
+|-----------|---------|
+| 0 | Success. A JSON object on stdout is read as hook output; other stdout goes to the debug log, except on UserPromptSubmit, UserPromptExpansion, SessionStart and PostModelSwitch, where it is added to Claude's context. stderr goes to the debug log only. |
+| 2 | Blocks on PreToolUse (Claude sees stderr as the reason), UserPromptSubmit (the prompt is erased), UserPromptExpansion, Stop, SubagentStop (the subagent keeps working) and PreCompact. On PostToolUse it shows stderr to Claude — the tool already ran. On SessionStart, SubagentStart, PostCompact and PostModelSwitch it shows stderr to the user only. On Notification it is ignored. The full per-event table is in the Claude Code hooks documentation. |
+| Other | Non-blocking error; the action proceeds. |
+
+**Output is capped at 10,000 characters (observed; the Claude Code hooks documentation does not state it).**
+Plain stdout, and each of `additionalContext`, `systemMessage` and
+`initialUserMessage`, is measured on its own. Past the cap Claude Code saves
+the text to a file and passes a path
+plus a 2,000-character preview, and nothing tells Claude to read the file. Keep
+what Claude must see inside the cap — `session-start.sh` caps its checkpoint
+preview for this reason.

 ## Notes

@@ -2,14 +2,14 @@

 ## Trigger

-Runs after any merge to the `develop` or `main` branch that includes changes
-to `assets/`.
+Runs after any merge to `main` (the trunk) or a `release/*` branch that
+includes changes to `assets/`.

 ## Purpose

 Validates that all assets in the merged branch conform to naming conventions,
 size budgets, and format requirements. Prevents non-compliant assets from
-accumulating on integration branches.
+accumulating on the trunk.

 ## Implementation

@@ -2,7 +2,9 @@

 ## Trigger

-Runs before any commit that modifies files in `src/`.
+Runs before any commit that modifies files under the code root — `src/`
+(Godot), `Assets/` (Unity) or `Source/` (Unreal); see
+`.claude/docs/code-root-resolution.md`.

 ## Purpose

@@ -17,14 +19,23 @@ values that should be data-driven.
 # Pre-commit hook: Code quality checks
 # Adapt the specific checks to your language and tooling

-CODE_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^src/')
+# The code root depends on the engine; resolve it the way the shipped commit
+# check does. An unresolved root is reported, never guessed as src/.
+. "$(git rev-parse --show-toplevel)/.claude/hooks/yaml-helper.sh"
+CODE_ROOT=$(resolve_code_root | cut -f1)
+if [ -z "$CODE_ROOT" ]; then
+    echo "SKIPPED: no code root (set engine.name in project.yaml) — code checks did not run."
+    exit 0
+fi
+
+CODE_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E "^$CODE_ROOT/")

 EXIT_CODE=0

 if [ -n "$CODE_FILES" ]; then
    for file in $CODE_FILES; do
        # Check for hardcoded magic numbers in gameplay code
-        if [[ "$file" == src/gameplay/* ]]; then
+        if [[ "$file" == */[Gg]ameplay/* ]]; then
            # Look for numeric literals that are likely balance values
            # Adjust the pattern for your language
            if grep -nE '(damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:=][[:space:]]*[0-9]+' "$file"; then
@@ -2,8 +2,8 @@

 ## Trigger

-Runs before any push to a remote branch. Mandatory for pushes to `develop`
-and `main`.
+Runs before any push to a remote branch. Mandatory for pushes to `main` (the
+trunk) and to `release/*` branches.

 ## Purpose

@@ -20,17 +20,13 @@ before code affects other developers.
 REMOTE="$1"
 URL="$2"

-# Only enforce full gate for develop and main
-PROTECTED_BRANCHES="develop main"
+# Only enforce the full gate on the trunk and release branches
 CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

 FULL_GATE=false
-for branch in $PROTECTED_BRANCHES; do
-    if [ "$CURRENT_BRANCH" = "$branch" ]; then
-        FULL_GATE=true
-        break
-    fi
-done
+case "$CURRENT_BRANCH" in
+    main|release/*) FULL_GATE=true ;;
+esac

 echo "=== Pre-Push Quality Gate ==="

@@ -1,32 +1,47 @@
 # Model Tier Assignment

-> ### DECLARED, NOT CURRENTLY APPLIED — skills only
+> ### When a skill's `model:` is used — skills only
 >
-> **Claude Code reads `model:` from a skill's frontmatter and then serves the
-> skill from the session's model anyway.** This has been measured directly
-> against session transcripts on several Claude Code versions, and held every
-> time. To re-test it on a newer version, run a skill that declares a tier
-> different from the session model and check which model the transcript
-> attributes the skill's turns to.
+> A skill's `model:` overrides the session model for the rest of the turn the
+> skill runs in, and your next prompt returns to the session model. Whether the
+> override happens depends on how the skill starts (measured on Claude Code
+> 2.1.282):
 >
-> So the skill tiers below are **intent, not behaviour**. Setting one changes
-> nothing today. They are kept because they are correct descriptions of what each
-> skill needs, and because they cost nothing to carry if Claude Code honours them
-> later — but do not budget on them, and never tell a user a tier is saving them
-> money.
+> | How the skill starts | Is `model:` used? |
+> |---|---|
+> | You type `/skill-name` in Manual (`default`) mode | Yes |
+> | You type `/skill-name` in auto mode | `sonnet` and `opus`: yes. `haiku`: no — auto mode does not support Haiku, so the session keeps its model (documented) |
+> | Claude starts the skill itself, through the Skill tool | No — the session model runs it (measured; the docs do not say) |
+>
+> Two things follow:
+>
+> - **An `opus` skill costs more in a Sonnet session.** Typing
+>   `/architecture-review`, `/gate-check` or `/review-all-gdds` moves that turn
+>   to Opus.
+> - **A `haiku` skill saves nothing in auto mode** (this project's settings start
+>   terminal sessions in Manual, but a user can switch) — or when Claude starts
+>   it. Never tell a user a `haiku` tier is saving them money.
+>
+> Because the override ends at your next prompt, a skill that stops to ask you
+> something in chat finishes on the session model after you answer.
 >
 > **This does NOT apply to agents.** `model:` in `.claude/agents/*.md` is a
-> different mechanism, spawned as a separate session rather than executed inline.
-> It has not been measured here, so treat the agent section below as unverified
-> in either direction rather than assuming it behaves the same way.
+> different mechanism, spawned as a separate session rather than executed inline,
+> and Claude Code documents it as applied: it is second in the subagent model
+> order, after a `model` Claude passes for one invocation. See the agent section
+> below.

-Skills and agents are assigned tiers by task complexity:
+Skills and agents are assigned tiers by task complexity. A tier is written as
+the alias `model:` takes, never as a model ID: Claude Code resolves each alias
+to the current model in that family, so this table does not change when a new
+model ships.

-| Tier | Model | When to use |
-|------|-------|-------------|
-| **Haiku** | `claude-haiku-4-5-20251001` | Read-only status checks, formatting, simple lookups — no creative judgment needed |
-| **Sonnet** | `claude-sonnet-5` | Implementation, design authoring, analysis of individual systems — default for most work |
-| **Opus** | `claude-opus-5` | Multi-document synthesis, high-stakes phase gate verdicts, cross-system holistic review |
+| Tier | `model:` | When to use |
+|------|----------|-------------|
+| **Haiku** | `haiku` | Read-only status checks, formatting, simple lookups — no creative judgment needed |
+| **Sonnet** | `sonnet` | Implementation, design authoring, analysis of individual systems — default for most work |
+| **Opus** | `opus` | Multi-document synthesis, high-stakes phase gate verdicts, cross-system holistic review |
+| **Session** | `inherit` | Agents only — runs on whatever model the session runs |

 Skills with `model: haiku` (5): `/help`, `/onboard`, `/project-stage-detect`,
 `/scope-check`, `/sprint-status`
@@ -49,7 +64,45 @@ this repo declares a tier, and the lists above are kept in step with what the
 `SKILL.md` files declare. That is a check on two descriptions agreeing; it
 proves nothing about which model actually runs.

-**Agent model tiers.** Orchestrator-spawned agents (`team-*`, `/review-all-gdds`)
-use `model: inherit` so a fixed smaller model can't overflow when the parent runs
-a large-context tier. Directors stay `opus`, `community-manager`/`devops-engineer`
-stay `haiku`, and non-orchestrator agents stay pinned at `sonnet` as a floor.
+**Agent model tiers.** 30 agents use `model: inherit` and run on the session's
+model. 19 are pinned:
+
+- **opus (3):** `creative-director`, `producer`, `technical-director`. Under an
+  Opus session an `opus` pin runs on the session's exact model, `[1m]` included,
+  so it never gets a smaller window than its parent.
+- **sonnet (16):** `lead-programmer`, `prototyper`, `devops-engineer`,
+  `community-manager` and the 12 engine sub-specialists:
+  `godot-csharp-specialist`, `godot-gdextension-specialist`,
+  `godot-gdscript-specialist`, `godot-shader-specialist`,
+  `ue-blueprint-specialist`, `ue-gas-specialist`, `ue-replication-specialist`,
+  `ue-umg-specialist`, `unity-addressables-specialist`,
+  `unity-dots-specialist`, `unity-shader-specialist`, `unity-ui-specialist`.
+  `/dev-story` and `/code-review` spawn the sub-specialists named in
+  `project.yaml`'s `specialists` block (which `/setup-engine` writes); `/team-ui` spawns
+  `unity-ui-specialist` and `ue-umg-specialist`; `/team-release` spawns
+  `devops-engineer` and `community-manager`, and `/team-live-ops` spawns
+  `community-manager`.
+- **haiku (0):** no agent. The Haiku row above is for read-only lookups and
+  formatting; every agent drafts, writes or judges. Building CI pipelines and
+  writing player-facing text are Sonnet work, as they are for `/patch-notes`.
+
+Every agent not named above is `inherit`. The `model:` line in the agent's own
+file is what runs, and this list is kept in step with those files.
+
+A pin gets that model's context window, whatever the session runs. On the
+Anthropic API `sonnet` currently resolves to Sonnet 5, which always has a 1M
+window, so a `sonnet` pin is not smaller than a 1M session there; `haiku`
+resolves to Haiku 4.5 and its 200K window, and behind an LLM gateway a `sonnet`
+pin can be smaller too. A subagent starts from
+the brief it is given, not the parent's conversation, so this only matters when
+a brief is very large. If a pinned agent does overflow, run every subagent on
+the session's model with one line in your `.claude/settings.local.json`
+(Claude Code v2.1.257 or later):
+
+```json
+{ "env": { "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1" } }
+```
+
+It applies to **every** pin, the three `opus` directors included: under a
+Sonnet session they run on Sonnet too. `CLAUDE_CODE_SUBAGENT_MODEL` alone does
+not do it: it applies only to agents that set no model of their own.
@@ -11,24 +11,48 @@ major engine subsystems. All design agents and templates are grounded in
 established game design theory (MDA Framework, Self-Determination Theory,
 Flow State, Bartle Player Types). Use whichever engine set matches your project.

+## The Default Path: Rigor Minimal
+
+`modes.rigor` defaults to `minimal` (`/start` asks; `/settings` changes it any
+time). At `minimal` the path to code is four steps:
+
+1. `/setup-engine` -- configure the engine
+2. `/brainstorm` -- writes the one-page `design/game-brief.md`, in place of the
+   concept doc, systems decomposition and per-system GDDs
+3. `/create-stories` -- turns the brief's MVP list into stories under
+   `production/epics/<slug>/`; the brief's build order is the plan, so there is
+   no `/create-epics` or `/sprint-plan`
+4. `/dev-story` then `/story-done`, story by story -- `/story-done` names the
+   next story, and `/help` knows this route
+
+Nothing at `minimal` runs `/gate-check`, so `project.stage` stays at Concept.
+Every skill still runs at any tier. The trade: no GDDs catch design problems
+before code. Raise rigor with `/settings` when the game outgrows the brief;
+`standard` and `full` are the longer pipelines under
+[First Steps for a New Project](#first-steps-for-a-new-project).
+
 ## How to Use

 ### 1. Understand the Hierarchy

 There are three tiers of agents:

- **Tier 1 (Opus)**: Directors who make high-level decisions
+- **Tier 1 — Directors** who make high-level decisions (they run on Opus)
  - `creative-director` -- vision and creative conflict resolution
  - `technical-director` -- architecture and technology decisions
  - `producer` -- scheduling, coordination, and risk management

- **Tier 2 (Sonnet)**: Department leads who own their domain
+- **Tier 2 — Department leads** who own their domain
  - `game-designer`, `lead-programmer`, `art-director`, `audio-director`,
    `narrative-director`, `qa-lead`, `release-manager`, `localization-lead`

- **Tier 3 (Sonnet/Haiku)**: Specialists who execute within their domain
+- **Tier 3 — Specialists** who execute within their domain
  - Designers, programmers, artists, writers, testers, engineers

+The tiers are seniority of role. Most agents run on your session's model; the
+agent file's own `model:` line says which do not
+(`.claude/docs/model-tiers.md`).
+
 ### 2. Pick the Right Agent for the Job

 Ask yourself: "What department would handle this in a real studio?"
@@ -111,7 +135,7 @@ Ask yourself: "What department would handle this in a real studio?"
 | `/scope-check` | Detect scope creep against plan |
 | `/perf-profile` | Performance profiling and bottleneck ID |
 | `/tech-debt` | Scan, track, and prioritize tech debt |
-| `/gate-check` | Validate phase readiness (PASS/CONCERNS/FAIL) |
+| `/gate-check` | Validate phase readiness (PASS/CONCERNS/NOT ASSESSED/FAIL) |
 | `/consistency-check` | Scan all GDDs for cross-document inconsistencies (conflicting stats, names, rules) |
 | `/security-audit` | Audit for security vulnerabilities: save tampering, cheat vectors, network exploits, data exposure |
 | `/reverse-document` | Generate design/architecture docs from existing code |
@@ -157,6 +181,7 @@ Templates are in `.claude/docs/templates/`:
 - `game-design-document.md` -- for new mechanics and systems
 - `architecture-decision-record.md` -- for technical decisions
 - `architecture-traceability.md` -- maps GDD requirements to ADRs to story IDs
+  (`/architecture-review` writes it to `docs/architecture/requirements-traceability.md`)
 - `risk-register-entry.md` -- for new risks
 - `narrative-character-sheet.md` -- for new characters
 - `test-plan.md` -- for feature test plans
@@ -173,6 +198,7 @@ Templates are in `.claude/docs/templates/`:
 - `release-notes.md` -- for player-facing release notes
 - `incident-response.md` -- for live incident response playbooks
 - `game-concept.md` -- for initial game concepts (MDA, SDT, Flow, Bartle)
+- `game-brief.md` -- for the one-page brief that replaces the concept doc at `rigor: minimal`
 - `pitch-document.md` -- for pitching the game to stakeholders
 - `economy-model.md` -- for virtual economy design (sink/faucet model)
 - `faction-design.md` -- for faction identity, lore, and gameplay role
@@ -202,6 +228,9 @@ Templates are in `.claude/docs/templates/`:
 **Don't know where to begin?** Run `/start`. It asks where you are and routes
 you to the right workflow. No assumptions about your game, engine, or experience level.

+The paths below walk the `standard`/`full` pipeline. At `rigor: minimal` (the
+default), follow [The Default Path](#the-default-path-rigor-minimal) instead.
+
 If you already know what you need, jump directly to the relevant path:

 ### Path A: "I have no idea what to build"
@@ -217,6 +246,7 @@ If you already know what you need, jump directly to the relevant path:
   - If the engine version is newer than the LLM's training data, it fetches
     current docs from the web so agents suggest correct APIs
 3. **Validate the concept** — Run `/design-review design/gdd/game-concept.md`
+   (or `design/game-brief.md`, if `/brainstorm` wrote the one-page brief)
 4. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies
 5. **Design each system** — Run `/design-system [system-name]` (or `/map-systems next`)
   to write GDDs in dependency order
@@ -264,14 +294,14 @@ If you have design docs, prototypes, or code already:
 ## File Structure Reference

 ```
-CLAUDE.md                          -- Master config (read this first, ~60 lines)
+CLAUDE.md                          -- Master config (read this first, ~80 lines)
 project.yaml                       -- Machine-readable project config (engine, modes, stage) — source of truth
 .claude/
  settings.json                    -- Claude Code hooks and project settings
  agents/                          -- 49 agent definitions (YAML frontmatter)
  skills/                          -- 74 slash command definitions (YAML frontmatter)
  hooks/                           -- 12 event hooks (.sh, wired by settings.json) + yaml-helper.sh
-  rules/                           -- 11 path-specific rule files
+  rules/                           -- 13 path-specific rule files
  docs/
    quick-start.md                 -- This file
    technical-preferences.md       -- Legacy fallback for project.yaml config (mirror; see project.yaml at repo root)
@@ -283,5 +313,5 @@ project.yaml                       -- Machine-readable project config (engine, m
    setup-requirements.md          -- System prerequisites (Git Bash, jq, Python)
    settings-local-template.md     -- Personal settings.local.json guide
    CLAUDE-local-template.md       -- Personal CLAUDE.local.md guide (gitignored overrides)
-    templates/                     -- 38 document templates (+ per-section guidance)
+    templates/                     -- 39 document templates (+ per-section guidance)
 ```
@@ -6,8 +6,8 @@ every tool use, and not when it creates one.

 Three consequences, and none of them are optional reading:

-1. **Reading, not editing.** A rule scoped to `src/gameplay/**` reaches the model
-   when a file there is opened. An agent that writes a brand-new file in that
+1. **Reading, not editing.** A rule scoped to a gameplay folder reaches the
+   model when a file there is opened. An agent that writes a brand-new file in that
   directory without opening an existing one never sees it. Most work in this
   framework creates files rather than reads them, so this is the common case,
   not the corner case.
@@ -26,24 +26,43 @@ alone.

 To see which rules actually load, and why, wire the `InstructionsLoaded` hook —
 `.claude/hooks/log-instructions.sh` records every instruction file and its load
-reason (`session_start`, `path_glob_match`, `nested_traversal`, `compact`) to
-`production/session-logs/instructions-loaded.log`.
+reason (`session_start`, `path_glob_match`, `nested_traversal`, `include`,
+`compact`) to `production/session-logs/instructions-loaded.log`.
+
+**Globs match regardless of case.** Claude Code 2.1.282 matches `paths:`
+gitignore-style and case-insensitively (observed; the docs do not say), so
+`Assets/**/UI/**` also matches a Godot project's `assets/ui/` art. That is why
+the Unity and Unreal code globs below name their file types.
+
+Paths are listed Godot · Unity · Unreal. Folder names are shown in one case;
+each rule's own globs list the case variants (`{AI,Ai,ai}`).

 | Rule File | Path Pattern | Enforces |
 | ---- | ---- | ---- |
-| `gameplay-code.md` | `src/gameplay/**` | Data-driven values, delta time, no UI references |
-| `engine-code.md` | `src/core/**` | Zero allocs in hot paths, thread safety, API stability |
-| `ai-code.md` | `src/ai/**` | Performance budgets, debuggability, data-driven params |
-| `network-code.md` | `src/networking/**` | Server-authoritative, versioned messages, security |
-| `ui-code.md` | `src/ui/**` | No game state ownership, localization-ready, accessibility |
-| `design-docs.md` | `design/gdd/**` | Required 8 sections, formula format, edge cases |
+| `gameplay-code.md` | `src/gameplay/**` · `Assets/**/Gameplay/**/*.cs` · `Source/**/Gameplay/**/*.{h,cpp}` | Data-driven values, delta time, no UI references |
+| `engine-code.md` | `src/core/**` · `Assets/**/Core/**/*.cs` · `Source/**/Core/**/*.{h,cpp}` | Zero allocs in hot paths, thread safety, API stability |
+| `ai-code.md` | `src/ai/**` · `Assets/**/AI/**/*.cs` · `Source/**/AI/**/*.{h,cpp}` | Performance budgets, debuggability, data-driven params |
+| `network-code.md` | `src/networking/**` · `Assets/**/Network(ing)/**/*.cs` · `Source/**/Network(ing)/**/*.{h,cpp}` | Server-authoritative, versioned messages, security |
+| `ui-code.md` | `src/ui/**` · `Assets/**/UI/**/*.cs` · `Source/**/UI/**/*.{h,cpp}` | No game state ownership, localization-ready, accessibility |
+| `design-docs.md` | `design/gdd/**` | Required sections per `modes.workflow` (8 at `full`, 5 at `standard`), formula format, edge cases |
 | `narrative.md` | `design/narrative/**` | Lore consistency, character voice, canon levels |
-| `data-files.md` | `assets/data/**` | JSON validity, naming conventions, schema rules |
-| `test-standards.md` | `tests/**` | Test naming, coverage requirements, fixture patterns |
+| `data-files.md` | `assets/data/**/*.json` · `Assets/**/Data/**/*.json` · `Content/**/Data/**/*.json` | JSON validity, naming conventions, schema rules |
+| `test-standards.md` | `tests/**` · `Assets/Tests/**/*.cs` · `Source/**/Tests/**/*.{h,cpp}` | Test naming, coverage requirements, fixture patterns |
 | `prototype-code.md` | `prototypes/**` | Relaxed standards, README required, hypothesis documented |
-| `shader-code.md` | `assets/shaders/**` | Naming conventions, performance targets, cross-platform rules |
+| `shader-code.md` | `assets/shaders/**`, `**/*.gdshader` · `Assets/**/*.{shader,hlsl,cginc,compute,shadergraph}` · `Shaders/**`, `**/*.{usf,ush}` | Naming conventions, performance targets, cross-platform rules |
 | `agent-memory.md` | `.claude/agent-memory/**` | The one place an agent may write unasked — and why a temporary absence must never be recorded as a durable fact |
-| `skill-authoring.md` | `.claude/skills/**`, `.claude/agents/**` | A check that cannot report it did not run is not a check — verdict vocabularies, fail-closed defaults, self-announcing skips, sourcing, derived gate coverage |
+| `skill-authoring.md` | `.claude/skills/**`, `.claude/agents/**` | A check must be able to report that it did not run — the five obligations for verdicts, defaults, skips, sourcing and derived coverage |
+
+Each engine-facing rule loads on all three engines:
+
+- **Code rules** (`gameplay`, `engine`, `ai`, `network`, `ui`) match
+  `Assets/**/<System>/**/*.cs` and `Source/**/<System>/**/*.{h,cpp}` (`Core`,
+  `AI`, `Networking`/`Network`, `UI` for the others).
+- **`data-files.md`** matches `Assets/**/Data/**/*.json` and `Content/**/Data/**/*.json`
+  — JSON only, so C# or C++ in a `Data/` folder does not pick up its file-naming rule.
+- **`shader-code.md`** matches shader files by type: `.gdshader`, `.shader`,
+  `.hlsl`, `.cginc`, `.compute`, `.shadergraph`, `.usf`, `.ush`, plus `Shaders/**`.
+- **`test-standards.md`** matches `Assets/Tests/**/*.cs` and `Source/**/Tests/**/*.{h,cpp}`.

 > **`skill-authoring.md` is the odd one out and deliberately so.** Every other
 > rule here scopes a *game* directory; that one scopes the **framework's own**
@@ -47,7 +47,7 @@ engine has a native way.
 |---|---|---|---|---|---|
 | Godot 4 | `godot --path . --windowed --resolution 1280x720 <scene>.tscn` | `--write-movie <path>.png --quit-after <N>` | beside the given path, `<name>00000000.png` … | `--headless` | **none** |
 | Unity 6 | built player `.exe -screen-width 1280 -screen-height 720 -screen-fullscreen 0 --scene <Name>` | `ScreenCapture.CaptureScreenshot(<abs path>)` from a bootstrap script | the absolute path you pass | `-batchmode`, `-nographics` | one MonoBehaviour |
-| Unreal 5 | `MSYS_NO_PATHCONV=1 UnrealEditor.exe <Game>.uproject <MapURL> -game -windowed -ResX=1280 -ResY=720` | `HighResShot filename=<path>` console command | `Saved/Screenshots/Windows/` | `-nullrhi`, `-unattended` alone | one actor or `-ExecCmds` |
+| Unreal 5 | `MSYS_NO_PATHCONV=1 "<UE root>/Engine/Binaries/Win64/UnrealEditor.exe" "$(pwd -W 2>/dev/null || pwd)/<Game>.uproject" <MapURL> -game -windowed -ResX=1280 -ResY=720` | `HighResShot 1280x720 filename=<abs path>` console command | the path you pass (else `Saved/Screenshots/WindowsEditor/`) | `-nullrhi`, `-unattended` alone | one actor or `-ExecCmds` |

 ### Godot 4 — zero scaffold

@@ -77,41 +77,93 @@ Builds/Win64/Game.exe -screen-width 1280 -screen-height 720 -screen-fullscreen 0
 ```

 `-screen-*` are Unity's own player arguments. `--scene`, `--screenshot` and
-`--after` are **yours**: a `ScreenshotOnArg` MonoBehaviour in the bootstrap
-scene parses `System.Environment.GetCommandLineArgs()`, loads `--scene`, waits
-`--after` frames, calls `ScreenCapture.CaptureScreenshot(path)`, waits one more
-frame, then `Application.Quit()`. Pass an **absolute** path — the relative base
-differs between editor and player. `CaptureScreenshot` captures the last frame
-*presented*, so it must run after at least one rendered frame.
+`--after` are **yours**, read by the script below. The template does not ship
+it: the first time a Unity story needs a screenshot, `/dev-story` asks to write
+it, verbatim, to `Assets/Scripts/ScreenshotOnArg.cs`. It needs no scene edit — it boots itself, and does nothing unless the player
+was launched with `--screenshot`:

-`/test-setup` scaffolds this script under the code root. Building the player
-first costs 1–3 minutes on a small project; that is the price of looking at
-the thing you ship rather than the editor.
+```csharp
+using System.Collections;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+// Run-and-observe capture: Game.exe --scene Shop --screenshot C:/abs/shop.png --after 60
+public class ScreenshotOnArg : MonoBehaviour
+{
+    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterSceneLoad)]
+    static void Boot()
+    {
+        if (Arg("--screenshot") == null) return;
+        var go = new GameObject(nameof(ScreenshotOnArg));
+        DontDestroyOnLoad(go);
+        go.AddComponent<ScreenshotOnArg>();
+    }
+
+    static string Arg(string name)
+    {
+        var args = System.Environment.GetCommandLineArgs();
+        for (int i = 0; i < args.Length - 1; i++)
+            if (args[i] == name) return args[i + 1];
+        return null;
+    }
+
+    IEnumerator Start()
+    {
+        var scene = Arg("--scene");
+        if (!string.IsNullOrEmpty(scene)) yield return SceneManager.LoadSceneAsync(scene);
+        int after = int.TryParse(Arg("--after"), out var n) ? n : 60;
+        for (int i = 0; i < after; i++) yield return null;
+        yield return new WaitForEndOfFrame();
+        ScreenCapture.CaptureScreenshot(Arg("--screenshot"));
+        for (int i = 0; i < 3; i++) yield return null;   // the file is written after the frame
+        Application.Quit();
+    }
+}
+```
+
+Pass an **absolute** path — the relative base differs between editor and
+player. `--scene` must be in the build settings. Building the player first
+costs 1–3 minutes on a small project; that is the price of looking at the thing
+you ship rather than the editor.

 ### Unreal 5 — one actor, or `-ExecCmds`

 ```
-MSYS_NO_PATHCONV=1 UnrealEditor.exe Game.uproject /Game/Maps/Shop -game -windowed -ResX=1280 -ResY=720
+MSYS_NO_PATHCONV=1 timeout 60 "<UE root>/Engine/Binaries/Win64/UnrealEditor.exe" "$(pwd -W 2>/dev/null || pwd)/Game.uproject" /Game/Maps/Shop -game -windowed -ResX=1280 -ResY=720
 ```

+That line is Windows'. On Linux the same arguments go to
+`"<UE root>/Engine/Binaries/Linux/UnrealEditor"` (no `MSYS_NO_PATHCONV` needed);
+on macOS Epic documents only the `UnrealEditor.app` bundle, so run the map from
+the editor or a command you have confirmed (see
+`docs/engine-reference/unreal/current-best-practices.md`, "Command Line").
+
 `-game` runs standalone without the editor UI. The map is a **positional URL
 immediately after the `.uproject`** — not a console command. **The
 `MSYS_NO_PATHCONV=1` prefix is required on Windows:** Claude Code runs commands
 in Git Bash, which rewrites any argument beginning with `/` as a Windows path, so
 `/Game/Maps/Shop` reaches the engine as `C:/Program Files/Git/Game/Maps/Shop`
 and the game stops on a "map not found" dialog nobody can see. Alternatively
-pass the map through `-ExecCmds="open /Game/Maps/Shop"`, which is not converted. Capture is the
+pass the map through `-ExecCmds="open /Game/Maps/Shop"`, which is not converted.
+**The project path must be absolute** — with `MSYS_NO_PATHCONV` set, only
+`$(pwd -W 2>/dev/null || pwd)` gives one: a relative `Game.uproject` is not
+found, and the launch waits on an error dialog forever (verified on 5.7). There
+is no `-unattended` on this line, so every failure is a dialog nobody clicks:
+always run it under `timeout`. Capture is the
 `HighResShot` console command, fired either from a dev actor (`Execute Console
 Command` on BeginPlay after a short delay, then `quit`) or from the launch line:

 ```
-ExecCmds="HighResShot filename=C:/abs/path/shop.png,Quit"
+-ExecCmds="HighResShot 1280x720 filename=C:/abs/path/shop.png"
 ```

-`-ExecCmds` is comma-separated. Output defaults to `Saved/Screenshots/Windows/`.
-**Do not `Quit` on the same frame as the request** — the file flushes late and
-an immediate quit can leave nothing on disk; a one-second delay before `quit`
-is enough. The Blueprint node `Take High Res Screenshot` is editor-only and
+The size (or a multiplier such as `2`) comes **before** `filename=`:
+`HighResShot filename=…` alone is rejected as bad input and saves nothing.
+Without `filename=` the file lands in `Saved/Screenshots/WindowsEditor/`.
+**Do not put `Quit` in the same `-ExecCmds` list** — it runs on the same
+frame, before the file is written, and leaves nothing on disk. `-ExecCmds` has
+no delay, so let `timeout` end the launch (exit 124 is expected) and check the
+file exists; a dev actor can instead wait a second, then `quit`. The Blueprint node `Take High Res Screenshot` is editor-only and
 does not work in a `-game` launch.

 ### Any engine — OS capture fallback
@@ -172,7 +224,8 @@ engine on this machine". Absence of a path is not absence of an engine.

 ---

-*Commands and APIs above verified against the official Godot 4.7, Unity 6.3 LTS
-and Unreal 5.8 references on 2026-09-14. `docs/engine-reference/<engine>/` is
+*Commands above were run on Windows with Godot 4.6.1 (gdUnit4 6.1.3), Unity
+6000.3.23f1 and Unreal Engine 5.7; the Unreal Linux and macOS notes come from
+Epic's documentation. `docs/engine-reference/<engine>/` is
 the project's pinned authority; check it before trusting a version-qualified
 claim here.*
@@ -44,7 +44,7 @@ points, not verdicts — the user can always override.
 |---|---|---|---|
 | Weekend jam / prototype / throwaway | `minimal` | Shipping beats recording; design lives in the maker's head | Bump one deep system: `workflow_overrides.system_overrides: {combat: full}` |
 | Small solo / hobby game (arcade, puzzle, short narrative) | `minimal` → `standard` if it grows | Start light; add rigor when scope proves real | — |
-| Focused commercial indie (platformer, roguelike, tactics, deckbuilder) | `standard` *(default)* | One well-understood loop; enough design to build correctly | "Comprehensive but compact": `rigor: full` + `docs.density: terse` |
+| Focused commercial indie (platformer, roguelike, tactics, deckbuilder) | `standard` | One well-understood loop; enough design to build correctly | "Comprehensive but compact": `rigor: full` + `docs.density: terse` |
 | Systems-heavy / long-haul (open-world RPG, colony sim, immersive sim, 4X, survival) | `full` | Many interacting systems; a design mistake costs weeks | Solo dev: keep `full` on disk, set `review_mode: solo` locally |
 | Live-service / competitive multiplayer | `full` + domain emphasis | Full pipeline *plus* netcode/security/live-ops | Raise `qa.level` / `testing.strict.*` for the online-critical types |

@@ -63,7 +63,7 @@ an archetype and **pre-select** the recommendation rather than asking cold. Sign
 | open-world, RPG, sim, sandbox, faction, crafting, economy, MMO, multiplayer, "systems" | `full` |
 | jam, weekend, prototype, "first game", small, "just trying", experiment | `minimal` |
 | "release", "commercial", "on Steam", a single clear core loop | `standard` |
-| *ambiguous / nothing above* | `standard` (the documented default) |
+| *ambiguous / nothing above* | `minimal` (the documented default) |

 **Rules:** these are heuristics, never locks. Always confirm the pre-selection with
 the user in their own terms ("Sounds like a big systems game — I'd suggest `full`
@@ -86,7 +86,7 @@ modes exist to eliminate.

 | Trigger (crossing) | Direction | Detectable signal | Suggested action |
 |---|---|---|---|
-| Project grew past its band | ↑ raise | System-GDD count crosses ~9, or `src/` crosses the Production threshold, while rigor is `minimal` | "You're at N systems on `rigor: minimal` — most projects this size run `standard`. Revisit? → `/settings`" |
+| Project grew past its band | ↑ raise | System-GDD count crosses ~9, or the code root (`src/`, `Assets/` or `Source/`) crosses the Production threshold, while rigor is `minimal` | "You're at N systems on `rigor: minimal` — most projects this size run `standard`. Revisit? → `/settings`" |
 | Stage advanced into Production | ↑ raise | `/gate-check` PASS into Production while rigor is `minimal` | Same, offered once at the gate |
 | User sounds overwhelmed by process | ↓ lower | Phrases like "too many steps", "so much documentation", "overwhelmed" — *and* rigor is not already `minimal` | "If the required-doc list feels heavy, a lower rigor trims it → `/settings modes.rigor=standard`" |
 | Chosen rigor mismatches described scope | flag once | Onboarding pick contradicts the Phase-2 description | State it in one sentence, offer `/settings`, do not re-ask |
@@ -1,23 +1,25 @@
 # Setup Requirements

 This template requires a few tools to be installed for full functionality.
-All hooks fail gracefully if tools are missing — nothing will break, but
-you'll lose validation features.
+Hooks carry on without an optional tool and lose only the check it powers. The
+required ones are required: without Python 3 every setting falls back to its
+default and a commit that stages data JSON is blocked, and without Bash no hook
+runs at all.

 ## Required

 | Tool | Purpose | Install |
 | ---- | ---- | ---- |
 | **Git** | Version control, branch management | [git-scm.com](https://git-scm.com/) |
-| **Claude Code** | AI agent CLI | `npm install -g @anthropic-ai/claude-code` |
+| **Claude Code** | AI agent CLI | Native installer: `curl -fsSL https://claude.ai/install.sh \| bash` (macOS, Linux, WSL) or `irm https://claude.ai/install.ps1 \| iex` (Windows PowerShell). npm also works: `npm install -g @anthropic-ai/claude-code` (Node.js 22+). See [code.claude.com/docs/en/setup](https://code.claude.com/docs/en/setup) |
+| **Python 3** | Reads `project.yaml` for every skill and hook | [python.org](https://www.python.org/). Without it every setting silently falls back to its default, and a commit that stages data JSON is blocked because it cannot be validated |
+| **Bash** | Runs every hook | Built into macOS and Linux. On Windows, install [Git for Windows](https://git-scm.com/downloads/win) — Claude Code runs without it, but no CCGS hook does |

 ## Recommended

 | Tool | Used By | Purpose | Install |
 | ---- | ---- | ---- | ---- |
-| **jq** | Hooks (7 of 12) | JSON parsing in commit/push/asset/agent hooks | See below |
-| **Python 3** | Hooks (2 of 12) | JSON validation for data files | [python.org](https://www.python.org/) |
-| **Bash** | All hooks | Shell script execution | Included with Git for Windows |
+| **jq** | Hooks (8 of 12) | JSON parsing in commit/push/asset/agent hooks | See below |

 ### Installing jq

@@ -45,7 +47,9 @@ sudo pacman -S jq       # Arch
 ### Windows
 - Git for Windows includes **Git Bash**, which provides the `bash` command
  used by all hooks in `settings.json`
- Ensure Git Bash is on your PATH (default if installed via the Git installer)
+- If Claude Code can't find Git Bash, set `CLAUDE_CODE_GIT_BASH_PATH` to its
+  `bash.exe` in the `env` block of your settings (for example
+  `C:\\Program Files\\Git\\bin\\bash.exe` in JSON)
 - Hooks use `bash .claude/hooks/[name].sh` — this works on Windows because
  Claude Code invokes commands through a shell that can find `bash.exe`

@@ -61,16 +65,16 @@ Run these commands to check prerequisites:
 git --version          # Should show git version
 bash --version         # Should show bash version
 jq --version           # Should show jq version (optional)
-python3 --version      # Should show python version (optional)
+python --version       # Required: Python 3 (python3 or py also work)
 ```

 ## What Happens Without Optional Tools

 | Missing Tool | Effect |
 | ---- | ---- |
-| **jq** | Commit validation, push protection, asset validation, and agent audit hooks silently skip their checks. Commits and pushes still work. |
-| **Python 3** | JSON data file validation in commit and asset hooks is skipped. Invalid JSON can be committed without warning. |
-| **Both** | All hooks still execute without error (exit 0) but provide no validation. You're flying without safety nets. |
+| **jq** | Nothing is lost: every hook falls back to `grep` to read its JSON input. jq is only more robust with unusual input. |
+| **Python 3** | Not optional (see Required). Every setting falls back to its default, because `project.yaml` is read through Python; the asset hook skips JSON validation and says so; a commit that stages data JSON is blocked. |
+| **Both** | As without Python. |

 ## Optional Performance Settings

@@ -103,6 +107,11 @@ agents would write files you never approved.
 If you genuinely want it off, override it in `.claude/settings.local.json`,
 which takes precedence. Understand what you are turning off first.

+**The VS Code extension does not read it.** The extension never reads a
+project's `.claude/settings.json` for the permission mode a conversation starts
+in. To get the same behaviour there, set `claudeCode.initialPermissionMode` to
+`default` in your VS Code user settings.
+
 ## Recommended IDE

 Claude Code works with any editor, but the template is optimized for:
@@ -1,6 +1,6 @@
 # Available Skills (Slash Commands)

-73 slash commands organized by phase. Type `/` in Claude Code to access any of them.
+74 slash commands organized by phase. Type `/` in Claude Code to access any of them.

 ## Onboarding & Navigation

@@ -11,6 +11,7 @@
 | `/project-stage-detect` | Full project audit — detect phase, identify existence gaps, recommend next steps |
 | `/setup-engine` | Configure engine + version, detect knowledge gaps, populate version-aware reference docs |
 | `/adopt` | Brownfield format audit — checks internal structure of existing GDDs/ADRs/stories, produces migration plan |
+| `/settings` | View or change project config — the effective merged values, or a local override in `project.local.yaml` |

 ## Game Design

@@ -71,7 +72,7 @@
 | `/scope-check` | Analyze feature or sprint scope against original plan, flag scope creep |
 | `/perf-profile` | Structured performance profiling with bottleneck identification |
 | `/tech-debt` | Scan, track, prioritize, and report on technical debt |
-| `/gate-check` | Validate readiness to advance between development phases (PASS/CONCERNS/FAIL) |
+| `/gate-check` | Validate readiness to advance between development phases (PASS/CONCERNS/NOT ASSESSED/FAIL) |
 | `/consistency-check` | Scan all GDDs against the entity registry to detect cross-document inconsistencies (stats, names, rules that contradict each other) |
 | `/security-audit` | Audit the game for security vulnerabilities: save tampering, cheat vectors, network exploits, data exposure, and input validation gaps |

@@ -144,7 +145,7 @@ Claude Code ships its own skills, and one name collides with CCGS's.
 | You type | You get | Use it for |
 |---------|---------|-----------|
 | `/code-review` | **CCGS's** — project skills take the bare name | Architectural review against this project's coding standards, SOLID, testability and the control manifest. Knows about ADRs, stories and `docs/architecture/`. |
-| `/code-review:code-review` | **Claude Code's bundled** review | Reviewing a pull request or a plain diff, with no knowledge of CCGS's design documents or gates. |
+| `/review` | **Claude Code's bundled** review — the alias of its `/code-review`, which CCGS's skill shadows | Reviewing a pull request or a plain diff for correctness bugs, with no knowledge of CCGS's design documents or gates. |

 Both are useful; they answer different questions. Reach for the CCGS one during
 `/dev-story` and before `/story-done`, because it checks the things the gates
@@ -60,7 +60,7 @@ Story Author — Decomposes game design epics into atomic, testable user stories
 - `production/qa/evidence/` (creates test evidence stubs)

 **Cannot Touch:**
- `src/` (no game code)
+- The code root — `src/`, `Assets/` or `Source/` by engine (no game code)
 - `assets/` (no asset modifications)
 - Source data files (read-only)

@@ -3,7 +3,7 @@
 > Authoring guidance: .claude/docs/templates/guidance/accessibility-requirements-guide.md (load per-section as you author — do not read entirely).

 > **Status**: Draft | Committed | Audited | Certified
-> **Author**: [ux-designer / producer]
+> **Author**: [user + ux-designer]
 > **Last Updated**: [Date]
 > **Accessibility Tier Target**: [Basic / Standard / Comprehensive / Exemplary]
 > **Platform(s)**: [PC / Xbox / PlayStation 5 / Nintendo Switch / iOS / Android]
@@ -19,10 +19,12 @@
 > **Why this document exists**: Per-screen accessibility annotations belong in
 > UX specs. This document captures the project-wide accessibility commitments,
 > the feature matrix across all systems, the test plan, and the audit history.
-> It is created once during Technical Setup by the UX designer and producer,
-> then updated as features are added and audits are completed. If a feature
-> conflicts with a commitment made here, this document wins — change the feature,
-> not the commitment, unless the producer approves a formal revision.
+> It is created once during Technical Setup by the UX designer with
+> `/ux-design accessibility` — you pick the tier, against the criteria
+> accessibility-specialist sets and audits against — then updated as features
+> are added and audits are completed. If a feature conflicts with a commitment
+> made here, this document wins — change the feature, not the commitment,
+> unless the producer approves a formal revision.
 >
 > **When to update**: After each `/gate-check` pass, after any accessibility
 > audit, and whenever a new game system is added to `systems-index.md`.
@@ -42,7 +42,7 @@ chosen approach.]

 | Field | Value |
 |-------|-------|
-| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.4] |
+| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.7] |
 | **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input / Scripting] |
 | **Layer** | [Foundation / Core / Feature / Presentation] |
 | **Knowledge Risk** | [LOW — in training data / MEDIUM — near cutoff, verify / HIGH — post-cutoff, must verify] |
@@ -54,12 +54,13 @@ chosen approach.]
 > project upgrades engine versions. Flag it as "Superseded" and write a new ADR.

 > **`Layer` is the ADR's own layer, not the referencing epic's — and it is a
-> different taxonomy from `Domain`.** Four sites branch on whether an ADR is
+> different taxonomy from `Domain`.** Several sites branch on whether an ADR is
 > *critical (Foundation-layer)*: `/create-stories`, `/create-epics`,
-> `/architecture-decision`, and `gate-pre-production.md`. At `standard`,
+> `/architecture-decision`, `/story-readiness`, `/propagate-design-change` and
+> `gate-pre-production.md`; a missing row counts as critical. At `standard`,
 > `/create-stories` **stops** for a missing critical ADR and only **warns** for a
 > non-critical one, so this row decides whether a run halts. Earlier revisions of
-> this template recorded no layer at all, leaving those four sites to infer one from
+> this template recorded no layer at all, leaving those sites to infer one from
 > the referencing epic — which gives the wrong answer whenever a Foundation-layer
 > ADR is referenced by a Core-layer epic, the common case.
 >
@@ -1,80 +1,67 @@
 # Art Bible: [Game Title]

-## Document Status
- **Version**: 1.0
- **Last Updated**: [Date]
- **Owned By**: art-director
- **Status**: [Draft / Under Review / Approved]
+> **Status**: [Draft / Under Review / Approved]
+> **Owned By**: art-director
+> **Last Updated**: [Date]
+> **Art Director Sign-Off (AD-ART-BIBLE)**: [Not yet reviewed]

-## Visual Identity Summary
-[2-3 sentences describing the overall visual identity]
+`/art-bible` writes these nine sections in this order and replaces each
+section's `[To be designed]` line as that section is approved. A section still
+holding its placeholder is incomplete; a later run fills only those.

-## Reference Board
-[List reference games, films, art, and what specific visual quality each represents]
+## 1. Visual Identity Statement

-| Reference | Medium | What We're Taking |
-| --------- | ------ | ----------------- |
-| [Name] | [Game/Film/Art] | [Specific quality] |
+[To be designed] — a one-line visual rule that resolves any visual ambiguity,
+plus 2–3 supporting principles, each with a design test ("when X is ambiguous,
+choose Y") and the pillar it serves.

-## Color Palette
+## 2. Mood & Atmosphere

-### Primary Palette
-| Name | Hex | Usage |
-| ---- | --- | ----- |
-| [Color Name] | #XXXXXX | [Where and when to use] |
+[To be designed] — for each major game state (exploration, combat, victory,
+defeat, menus — whichever this game has): the emotional target, lighting
+character (time of day, colour temperature, contrast), 3–5 atmospheric
+descriptors, and energy level. Each state must look distinct from the others.

-### Emotional Color Mapping
-| Game State | Dominant Colors | Mood |
-| ---------- | --------------- | ---- |
-| Exploration | [Colors] | [Feeling] |
-| Combat | [Colors] | [Feeling] |
-| Safe zones | [Colors] | [Feeling] |
-| Danger | [Colors] | [Feeling] |
+## 3. Shape Language

-## Art Style
+[To be designed] — character silhouette philosophy (readable at thumbnail
+size, one distinguishing trait per archetype), environment geometry, UI shape
+grammar, and hero versus supporting shapes.

-### Rendering Style
-[Realistic / Stylized / Pixel / Cel-shaded / etc.]
+## 4. Color System

-### Proportions
-[Character proportions, environment scale, UI scale relationships]
+[To be designed] — a primary palette of 5–7 colours with their meaning in this
+world, semantic colour usage, per-area colour temperature rules, the UI palette
+and where it diverges, and colourblind safety: which semantic colours need a
+shape, icon or sound backup.

-### Level of Detail
-[How detailed are characters, environments, UI elements?]
+## 5. Character Design Direction

-### Visual Hierarchy
-[How do we guide the player's eye? What's always most prominent?]
+[To be designed] — the player character's visual archetype, how players tell
+enemies, NPCs and allies apart at a glance, expression and pose style, and how
+much detail survives at game camera distance (LOD philosophy).

-## Character Art Standards
-[Silhouette requirements, color coding, animation style, proportions]
+## 6. Environment Design Language

-## Environment Art Standards
-[Tilesets, modularity, lighting, atmospheric effects, scale]
+[To be designed] — architectural style and its tie to the world's culture,
+texture philosophy (painted, PBR or stylised, and why), prop density rules per
+area type, and environmental storytelling guidelines.

-## UI Art Standards
-[Button styles, typography, icon style, menu layout principles, HUD density]
+## 7. UI/HUD Visual Direction

-## VFX Standards
-[Particle style, screen effects, impact feedback, color coding]
+[To be designed] — diegetic versus screen-space HUD, typography (personality,
+weight, size hierarchy, minimum readable size), iconography style, UI animation
+feel, and any art-direction versus readability conflict and how it was decided.

-## Asset Production Standards
+## 8. Asset Standards

-### Naming Convention
-`[category]_[name]_[variant]_[size].[ext]`
+[To be designed] — file formats, naming convention, texture resolution tiers,
+LOD levels, export settings, and the engine's hard limits (poly budgets per
+asset category, texture memory, material slots). Where an art preference and a
+technical limit disagree, record both and the trade-off chosen.

-### Texture Standards
-| Category | Max Resolution | Format | Color Space |
-| -------- | -------------- | ------ | ----------- |
-| Characters | [Size] | [Format] | [Space] |
-| Environments | [Size] | [Format] | [Space] |
-| UI | [Size] | [Format] | [Space] |
-| VFX | [Size] | [Format] | [Space] |
+## 9. Reference Direction

-### Animation Standards
-[Frame rates, blend times, animation graph structure]
-
-## Accessibility
- Colorblind-safe UI elements required
- Minimum text size: [X]px at 1080p
- High contrast mode specifications
- Icon + color (never color alone) for game state
+[To be designed] — 3–5 references (games, films, art styles or artists). For
+each: the specific element to take from it, and what to avoid so the result
+does not read as a copy.
@@ -17,6 +17,13 @@

 ---

+## Summary
+
+[2–3 sentences: what this system is, what it does for the player, why it
+exists — inferred from code; mark `[inferred — confirm]`]
+
+---
+
 ## 1. Overview

 **Purpose**: [What problem does this system solve?]
@@ -32,9 +39,17 @@

 ---

-## 2. Detailed Design
+## 2. Player Fantasy

-### 2.1 Core Mechanics
+[What the player should FEEL when using this system. Code does not record this:
+infer it from the player-facing effects above, then CONFIRM it with the designer
+and mark it `[inferred — confirm]` until they do.]
+
+---
+
+## 3. Detailed Design
+
+### 3.1 Core Mechanics

 [Describe the mechanics as implemented, organized clearly]

@@ -50,20 +65,7 @@
 - **Design Rationale**: [Why it exists]
 - **Player-Facing**: [Player experience]

-### 2.2 Rules and Formulas
-
-**Formulas Discovered in Code**:
-
-| Formula | Expression | Purpose | Verified? |
-|---------|-----------|---------|-----------|
-| [Formula 1] | `[mathematical expression]` | [What it calculates] | ✅ / ⚠️ needs tuning |
-| [Formula 2] | `[expression]` | [Purpose] | ✅ / ⚠️ needs tuning |
-
-**Clarifications**:
- [Formula X]: Originally [value/approach], user clarified intent is [corrected intent]
- [Formula Y]: Implemented as [X], but should be [Y] — flagged for update
-
-### 2.3 State and Data
+### 3.2 State and Data

 **Data Structures** (from code):
 - [Data structure 1]: `[fields/properties]`
@@ -78,7 +80,7 @@
 - Saved: [What is saved to player save file]
 - Not saved: [What is session-only or recalculated]

-### 2.4 Integration Points
+### 3.3 Integration Points

 **Dependencies** (systems this depends on):
 - [System 1]: [What it provides]
@@ -94,7 +96,22 @@

 ---

-## 3. Edge Cases
+## 4. Formulas
+
+**Formulas Discovered in Code**:
+
+| Formula | Expression | Purpose | Verified? |
+|---------|-----------|---------|-----------|
+| [Formula 1] | `[mathematical expression]` | [What it calculates] | ✅ / ⚠️ needs tuning |
+| [Formula 2] | `[expression]` | [Purpose] | ✅ / ⚠️ needs tuning |
+
+**Clarifications**:
+- [Formula X]: Originally [value/approach], user clarified intent is [corrected intent]
+- [Formula Y]: Implemented as [X], but should be [Y] — flagged for update
+
+---
+
+## 5. Edge Cases

 **Handled in Code**:
 - ✅ [Edge case 1]: [How it's handled]
@@ -109,7 +126,7 @@

 ---

-## 4. Dependencies
+## 6. Dependencies

 **Technical Dependencies**:
 - [Dependency 1]: [Why needed]
@@ -125,7 +142,7 @@

 ---

-## 5. Balance and Tuning
+## 7. Tuning Knobs

 **Current Values** (as implemented):

@@ -144,7 +161,7 @@

 ---

-## 6. Acceptance Criteria
+## 8. Acceptance Criteria

 **What Exists** (implemented):
 - ✅ [Criterion 1]
@@ -162,7 +179,7 @@

 ---

-## 7. Open Questions and Follow-Up Work
+## Open Questions and Follow-Up Work

 ### Questions Needing User Decision
 1. **[Question 1]**: [What needs to be decided?]
@@ -180,7 +197,7 @@

 ---

-## 8. Version History
+## Version History

 | Date | Author | Changes |
 |------|--------|---------|
@@ -4,7 +4,7 @@
 THE ONE-PAGE BRIEF. At the `minimal` workflow tier this is the ENTIRE design doc —
 it replaces the full concept doc, systems decomposition, and per-system GDDs.
 Keep it to one screen. If a field needs a second paragraph, you're writing a GDD,
-not a brief. Fill every REQUIRED field; the two RECOMMENDED one-liners are cheap
+not a brief. Fill every REQUIRED field; the three RECOMMENDED one-liners are cheap
 but optional. Engine is set separately (project.yaml / /setup-engine) — don't restate it.

 Field set grounded in industry practice — Tim Ryan (*Anatomy of a Design Document*),
@@ -39,3 +39,5 @@ thinking and cuts ceremony), and lean/agile GDD practice.
 **Who it's for / what they feel:** [One line: the player and the feeling. e.g. "solo puzzle fans who want a cozy 20-minute sitting."]

 **Art & audio direction:** [One line of aesthetic intent — drives asset choices. e.g. "flat pastel vector art, lo-fi ambient."]
+
+**Reference game:** [One shipped game this is closest to, and the ~10% of it the MVP keeps. e.g. "Vampire Survivors — the auto-attack loop on one map; no meta-progression." Scoping against a real game is the fastest honest MVP check.]
@@ -289,7 +289,7 @@ so it can be cited in design reviews.]

 ---

-## Section 10 — Accessibility (HUD Specific)
+## Section 10 — Accessibility

 > **Why this section exists**: HUD accessibility failures are the most visible
 > accessibility failures in games — players encounter the HUD in every session,
@@ -374,7 +374,7 @@ Example: "Health bar numerical label grows with text scale — bar expands sligh

 | Question | Owner | Deadline | Resolution |
 |----------|-------|----------|-----------|
-| [e.g., Should the minimap show enemy positions by default, or only after a detection skill is unlocked?] | [systems-designer + ui-designer] | [Sprint 5, Day 2] | [Pending — depends on progression GDD decision] |
+| [e.g., Should the minimap show enemy positions by default, or only after a detection skill is unlocked?] | [systems-designer + ux-designer] | [Sprint 5, Day 2] | [Pending — depends on progression GDD decision] |
 | [e.g., Does the game have a boss health bar, or do bosses use the standard enemy health bar? Bosses need a visually distinct treatment if they are significantly more important than normal enemies.] | [game-designer] | [Sprint 5, Day 1] | [Pending] |
-| [e.g., Damage numbers: diegetic (floating in world space, occluded by geometry) or screen space (always readable, overlaid on HUD layer)?] | [ui-designer + lead-programmer] | [Sprint 4, Day 5] | [Pending — architecture decision affects rendering layer choice] |
+| [e.g., Damage numbers: diegetic (floating in world space, occluded by geometry) or screen space (always readable, overlaid on HUD layer)?] | [ux-designer + lead-programmer] | [Sprint 4, Day 5] | [Pending — architecture decision affects rendering layer choice] |
 | [e.g., Mobile portrait vs. landscape: does the game support both orientations? If yes, each requires its own zone layout.] | [producer] | [Sprint 3, Day 3] | [Pending — platform scope decision required first] |
@@ -154,7 +154,7 @@ Example:
 └──────────────────────────────────────────────┘
 ```

-**Worked example — zone definitions table (5.2)**:
+**Worked example — layout zones table (5.2)**:

 | Zone Name | Description | Approximate Size | Scrollable? | Overflow Behavior |
 |-----------|-------------|-----------------|-------------|-------------------|
@@ -286,7 +286,7 @@ Example:

 ---

-## Section 10 — Transition & Animation
+## Section 10 — Transitions & Animations

 > **Why this section exists**: Transitions are not decoration — they communicate
 > hierarchy and causality. A screen that slides in from the right implies the
@@ -320,7 +320,7 @@ Example:

 ---

-## Section 12 — Screen-Level Accessibility Requirements
+## Section 12 — Accessibility

 > **Why this section exists**: Accessibility requirements must be specified at design
 > time because retrofitting them is expensive and often architecturally impractical.
@@ -437,7 +437,7 @@ and independently verifiable:

 | Question | Owner | Deadline | Resolution |
 |----------|-------|----------|-----------|
-| [e.g., Should item comparison be automatic (always showing equipped stats) or player-triggered (press Compare)?] | [ui-designer] | [Sprint 4, Day 3] | [Pending] |
-| [e.g., Do we support controller cursor (free aim) in the item grid, or d-pad-only grid navigation?] | [lead-programmer + ui-designer] | [Sprint 4, Day 3] | [Pending — depends on ADR-0015 input model decision] |
+| [e.g., Should item comparison be automatic (always showing equipped stats) or player-triggered (press Compare)?] | [ux-designer] | [Sprint 4, Day 3] | [Pending] |
+| [e.g., Do we support controller cursor (free aim) in the item grid, or d-pad-only grid navigation?] | [lead-programmer + ux-designer] | [Sprint 4, Day 3] | [Pending — depends on ADR-0015 input model decision] |
 | [e.g., What is the game's item drop policy — permanent loss or drop-to-world?] | [systems-designer] | [Requires GDD update] | [Blocked on inventory GDD Edge Cases section] |
 | [e.g., Maximum inventory size — does the grid have a hard cap or is it infinite-scroll?] | [economy-designer] | [Sprint 3, Day 5] | [Pending] |
@@ -3,13 +3,14 @@
 > Authoring guidance: .claude/docs/templates/guidance/hud-design-guide.md (load per-section as you author — do not read entirely).

 > **Status**: Draft | In Review | Approved | Implemented
-> **Author**: [Name or agent — e.g., ui-designer]
+> **Author**: [Name or agent — e.g., ux-designer]
 > **Last Updated**: [Date]
 > **Game**: [Game name — this is a single document per game, not per element]
 > **Platform Targets**: [All platforms this HUD must work on — e.g., PC, PS5, Xbox Series X, Steam Deck]
 > **Related GDDs**: [Every system that exposes information through the HUD — e.g., `design/gdd/combat.md`, `design/gdd/progression.md`, `design/gdd/quests.md`]
 > **Accessibility Tier**: Basic | Standard | Comprehensive | Exemplary
-> **Style Reference**: [Link to art bible HUD section if it exists — e.g., `design/art/art-bible.md § HUD Visual Language`]
+> **Style Reference**: [Link to art bible HUD section if it exists — e.g., `design/art/art-bible.md § 7. UI/HUD Visual Direction`]
+> **Template**: HUD Design

 > **Note — Scope boundary**: This document specifies all elements that overlay the
 > game world during active gameplay — health bars, ammo counters, minimaps, quest
@@ -204,7 +205,7 @@ Repositioning saves to player profile, not to a single slot. Applies across play

 ---

-## 10. Accessibility — HUD Specific
+## 10. Accessibility

 > HUD-specific requirements only — refer to the project's
 > `design/accessibility-requirements.md` for the full project standard.
@@ -1,6 +1,6 @@
 # Incident Response: [Incident Title]

-**Severity**: [S1-Critical / S2-Major / S3-Moderate / S4-Minor]
+**Severity**: [S1-Critical / S2-High / S3-Medium / S4-Low]
 **Status**: [Active / Mitigated / Resolved / Post-Mortem Complete]
 **Detected**: [Date Time UTC]
 **Resolved**: [Date Time UTC or ONGOING]
@@ -12,6 +12,8 @@
 > - `design/art/art-bible.md` — visual standards (colors, typography, iconography)
 > - `design/accessibility-requirements.md` — accessibility commitments per feature
 > - `docs/ux/ux-spec-[screen].md` — individual screen specs that reference patterns
+>
+> **Template**: Interaction Pattern Library

 > **Why this document exists**: Every UI screen spec should be able to say
 > "uses Button (Primary) pattern" rather than re-specifying hover states,
@@ -686,7 +688,8 @@ These three patterns define how screens enter and exit the navigation stack.

 > Every interactive event should have audio feedback. Sound is a primary feedback
 > channel, not a decoration. The sounds defined here are event categories — the
-> specific audio assets are defined in `docs/sound-bible.md`. This table maps
+> specific audio assets are defined in `design/audio/sound-bible.md` (or
+> `design/gdd/sound-bible.md`, where earlier versions put it). This table maps
 > interaction events to sound categories so the sound designer and UI programmer
 > use the same vocabulary.

@@ -49,7 +49,7 @@ these are met.]
 | Frame rate | > [X] FPS on min spec | Performance profiling |
 | Load time | < [X] seconds | Automated timing |
 | Critical bugs | 0 open S1 | Bug tracker |
-| Major bugs | < [X] open S2 | Bug tracker |
+| High-severity bugs | < [X] open S2 High | Bug tracker |
 | Test coverage | > [X]% | Test framework report |

 ## Risk Register
@@ -2,6 +2,7 @@

 **Generated**: [DATE]
 **Stage**: [Concept | Systems Design | Technical Setup | Pre-Production | Production | Polish | Release]
+**Stage Confidence**: [PASS / CONCERNS / NOT ASSESSED / FAIL — reason]
 **Analysis Scope**: [Full project | Specific role: programmer/designer/producer]

 ---
@@ -30,11 +31,11 @@

 ### Source Code
 - **Status**: [X%] complete
- **Files Found**: [N] source files in `src/`
+- **Files Found**: [N] source files in `[code root]/` (`src/` Godot, `Assets/` Unity, `Source/` Unreal)
 - **Major Systems Identified**:
-  - ✅ [System 1] (`src/path/`) — [brief status]
-  - ✅ [System 2] (`src/path/`) — [brief status]
-  - ⚠️  [System 3] (`src/path/`) — [issue or incomplete]
+  - ✅ [System 1] (`[code root]/path/`) — [brief status]
+  - ✅ [System 2] (`[code root]/path/`) — [brief status]
+  - ⚠️  [System 3] (`[code root]/path/`) — [issue or incomplete]
 - **Key Gaps**:
  - [ ] [Missing system 1 + impact]
  - [ ] [Missing system 2 + impact]
@@ -174,7 +175,7 @@ design/
  narrative/     [N] files
  levels/        [N] files

-src/
+[code root]/     (src/, Assets/ or Source/<Module>/)
  core/          [N] files
  gameplay/      [N] files
  ai/            [N] files
@@ -51,7 +51,7 @@ directly where possible.]

 ---

-## Recommendation: [PROCEED / PIVOT / KILL]
+## Recommendation: [PROCEED / PIVOT / KILL / NOT ASSESSED — built but nobody has played it]

 [One paragraph explaining the recommendation with evidence from the result above.]

@@ -22,7 +22,12 @@

 ### Critical Bugs
 - [ ] Zero S1 (Critical) bugs open
- [ ] Zero S2 (Major) bugs -- or documented exceptions below:
+- [ ] Zero S2 (High) bugs -- or documented exceptions below (no exceptions at `workflow: full`):
+- [ ] Zero S3 (Medium) bugs open -- required at `workflow: full`
+
+> The release gate (`/gate-check release`) blocks any open S1–S3 bug at `workflow: full`,
+> with no exceptions; at `standard` and `minimal` it blocks open S1 only, and an open
+> S2 or S3 is a risk to record here.

 | Bug ID | Description | Exception Rationale | Approved By |
 | ---- | ---- | ---- | ---- |
@@ -6,7 +6,7 @@
  This file has TWO regions and they are not interchangeable:

    1. The CHECKPOINT region below (STATUS + CHECKPOINT blocks) is the part
-       machines read. Hooks inject it verbatim into the context, so it is
+       machines read. session-start.sh shows it verbatim in the context, so it is
       BOUNDED BY CONSTRUCTION: keep it under ~25 lines. It is OVERWRITTEN on
       every update, never appended to.

@@ -41,6 +41,7 @@ Task:
 **Next step:** [one line — the very next action, concrete enough to resume cold]
 **Blocked on:** [one line, or `nothing`]
 **Files in progress:** [paths, comma-separated, or `none`]
+**Run result:** [`/dev-story` writes its `Run result:` line here, verbatim, for `/story-done` to read; other writers leave this line out]
 **Open questions:** [one line each, or `none`]
 <!-- /CHECKPOINT -->

@@ -64,7 +65,8 @@ or agent picking this up cold.]

  CHECKPOINT block
    The recovery payload. `session-start.sh` shows it when a previous session
-    left state; `pre-compact.sh` injects it before compaction. Both read THIS
+    left state, and again after a compaction (SessionStart runs then too).
+    `pre-compact.sh` reads it as well, for the debug log. Both read THIS
    region and nothing else, which is what keeps the cost fixed no matter how
    long the narrative gets.

@@ -1,5 +1,8 @@
 # Sound Bible: [Project Name]

+> **Location**: `design/audio/sound-bible.md` — not `design/gdd/`, where the GDD checks count every file as a system GDD
+> **Owned By**: audio-director
+
 ## Audio Vision

 ### Sonic Identity
@@ -56,7 +56,7 @@

 - [ ] All Must Have tasks completed
 - [ ] All tasks pass acceptance criteria
- [ ] QA plan exists (`production/qa/qa-plan-sprint-[N].md`)
+- [ ] QA plan exists (`production/qa/qa-plan-[sprint-slug]-[date].md`, from `/qa-plan sprint`)
 - [ ] All Logic/Integration stories have passing unit/integration tests
 - [ ] Smoke check passed (`/smoke-check sprint`)
 - [ ] QA sign-off report: APPROVED or APPROVED WITH CONDITIONS (`/team-qa sprint`)
@@ -142,5 +142,5 @@ These should be prototyped early regardless of priority tier.]
 - [ ] Review and approve this systems enumeration
 - [ ] Design MVP-tier systems first (use `/design-system [system-name]`)
 - [ ] Run `/design-review` on each completed GDD
- [ ] Run `/gate-check pre-production` when MVP systems are designed
+- [ ] Run `/gate-check technical-setup` when MVP systems are designed
 - [ ] Validate the highest-risk systems with `/vertical-slice` before committing to Production
@@ -12,7 +12,7 @@

 | Field | Value |
 |-------|-------|
-| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.4] |
+| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.7] |
 | **APIs Depended On** | [Specific classes/methods/nodes used, version-pinned — e.g. `CharacterBody3D.move_and_slide() (Godot 4.x)`] |
 | **References Consulted** | [engine-reference docs read before writing this — e.g. `docs/engine-reference/godot/modules/physics.md`] |
 | **Post-Cutoff Features Used** | [Features from engine versions beyond LLM training cutoff, or "None"] |
@@ -69,19 +69,21 @@ If nothing notable: *No significant observations.*

 ## Sign-Off

-All roles must sign off before the story can be marked COMPLETE via `/story-done`.
-Visual/Feel stories require the designer or art-lead sign-off. UI stories require
-the UX lead or designer sign-off.
+A **Visual/Feel** story needs the lead sign-off below — the art-director, or the
+designer who owns the feature — before `/story-done` marks it COMPLETE. A **UI**
+story is closed by the retained screenshot of each screen it touched; a sign-off
+here is welcome but not required (`.claude/docs/coding-standards.md`).

-**Solo developers**: all sign-offs may be by the same person in each role. The
-intent is that someone deliberately reviews the evidence before marking complete —
-not that three separate people must participate.
+**Solo developers**: you may sign as the lead yourself. The intent is that
+someone deliberately reviews the evidence before marking complete.

 | Role | Name | Date | Signature |
 |------|------|------|-----------|
-| Developer (implemented) | | | [ ] Approved |
-| Designer / Art Lead / UX Lead | | | [ ] Approved |
-| QA Lead | | | [ ] Approved |
+| Lead (art-director / designer) | | | [ ] Approved |
+
+*Optional:* add a row for anyone else whose review your team wants, such as the
+developer or the QA lead. `/story-done` and `/test-evidence-review` treat every
+row in this table as required, so add one only for someone who will sign.

 **Any sign-off can be marked "Deferred — [reason]"** if the person is
 unavailable. Deferred sign-offs must be resolved before the story advances
@@ -15,7 +15,7 @@
 | [story title] | Logic | Unit test — `tests/unit/[system]/` | None |
 | [story title] | Integration | Integration test — `tests/integration/[system]/` | Smoke check |
 | [story title] | Visual/Feel | None (not automatable) | Screenshot + lead sign-off |
-| [story title] | UI | None (not automatable) | Manual step-through |
+| [story title] | UI | None (verified by its screenshots) | Retained screenshot of each screen touched |
 | [story title] | Config/Data | Data validation (optional) | Spot-check in-game values |

 **Totals**: [N] Logic, [N] Integration, [N] Visual/Feel, [N] UI, [N] Config/Data
@@ -57,17 +57,17 @@

 ### [Story Title] — Visual/Feel

-**Verification method**: Screenshot + [designer / art-lead] sign-off
+**Verification method**: Screenshot + [designer / art-director] sign-off
 **Evidence file**: `production/qa/evidence/[story-slug]-evidence.md`
-**Who must sign off**: [designer / lead-programmer / art-lead]
+**Who must sign off**: [art-director / owning designer]

 - [ ] [Specific observable condition — e.g., "hit flash appears on frame of impact, not the frame after"]
 - [ ] [Another falsifiable condition]

 ### [Story Title] — UI

-**Verification method**: Manual step-through
-**Evidence file**: `production/qa/evidence/[story-slug]-evidence.md`
+**Verification method**: Retained screenshot of each screen touched
+**Evidence**: `production/qa/evidence/[story-slug]/[NN]-[what-it-shows].png`, one per screen

 - [ ] [Every acceptance criterion translated into a manual check item]

@@ -104,7 +104,8 @@ A story is DONE when ALL of the following are true:

 - [ ] All acceptance criteria verified — automated test result OR documented manual evidence
 - [ ] Test file exists for all Logic and Integration stories and passes
- [ ] Manual evidence document exists for all Visual/Feel and UI stories
+- [ ] Retained screenshot of each screen touched, in `production/qa/evidence/`, for all Visual/Feel and UI stories
+- [ ] Signed-off evidence doc at `production/qa/evidence/[story-slug]-evidence.md` for all Visual/Feel stories
 - [ ] Smoke check passes (run `/smoke-check sprint` before QA hand-off)
 - [ ] No regressions introduced — previous sprint's features still pass
 - [ ] Code reviewed (via `/code-review` or documented peer review)
@@ -3,7 +3,7 @@
 > Authoring guidance: .claude/docs/templates/guidance/ux-spec-guide.md (load per-section as you author — do not read entirely).

 > **Status**: Draft | In Review | Approved | Implemented
-> **Author**: [Name or agent — e.g., ui-designer]
+> **Author**: [Name or agent — e.g., ux-designer]
 > **Last Updated**: [Date]
 > **Screen / Flow Name**: [Short identifier used in code and tickets — e.g., `InventoryScreen`, `NewGameFlow`]
 > **Platform Target**: [PC | Console | Mobile | All — list all that this spec covers]
@@ -11,6 +11,7 @@
 > **Related ADRs**: [Any architectural decisions that constrain this screen — e.g., `ADR-0012: UI Framework Selection`]
 > **Related UX Specs**: [Sibling and parent screens — e.g., `ux-spec-pause-menu.md`, `ux-spec-settings.md`]
 > **Accessibility Tier**: Basic | Standard | Comprehensive | Exemplary
+> **Template**: UX Spec

 > **Note — Scope boundary**: This template covers discrete screens and flows (menus,
 > dialogs, inventory, settings, cutscene UI, etc.). For persistent in-game overlays
@@ -100,7 +101,7 @@

 ## 5. Layout Specification

-### 5.1 Wireframe
+### 5.1 ASCII Wireframe

 ```
 [Draw the screen layout using ASCII art. Suggested characters:
@@ -114,7 +115,7 @@
 See guide Section 5 for a completed example wireframe.]
 ```

-### 5.2 Zone Definitions
+### 5.2 Layout Zones

 | Zone Name | Description | Approximate Size | Scrollable? | Overflow Behavior |
 |-----------|-------------|-----------------|-------------|-------------------|
@@ -131,6 +132,11 @@ See guide Section 5 for a completed example wireframe.]

 **Primary focus element on open**: [Element that receives focus when the screen opens, including deep-link and empty-state cases]

+### 5.4 Information Hierarchy
+
+[What the player must see first on this screen, what second, and what can wait
+behind a tab, a scroll or a button — in that order, with the reason for each.]
+
 ---

 ## 6. States & Variants
@@ -197,7 +203,7 @@ See guide Section 5 for a completed example wireframe.]

 ---

-## 10. Transition & Animation
+## 10. Transitions & Animations

 > Specify at least the screen enter and exit transitions, plus reduced-motion
 > behavior for each. See guide Section 10 for a worked example.
@@ -242,7 +248,7 @@ See guide Section 5 for a completed example wireframe.]

 ---

-## 12. Screen-Level Accessibility Requirements
+## 12. Accessibility

 > Project-wide standards live in `design/accessibility-requirements.md` — consult it
 > before filling this section so you do not duplicate or contradict project-level
@@ -90,12 +90,14 @@ encounter, 0.5 days per UI screen"]

 ---

-## Recommendation: [PROCEED / PIVOT / KILL]
+## Recommendation: [PROCEED / PIVOT / KILL / NOT ASSESSED — the slice was built but nobody has played it]

 [One paragraph with evidence — reference the validation question directly. Did a
 player experience the core fantasy within the target time, without developer guidance?
 Can the team build at this quality on the projected schedule?]

+**Creative Director review (CD-PLAYTEST):** [APPROVE / CONCERNS / REJECT / NOT ASSESSED — the director's reason; or "not run — [review mode]"]
+
 ---

 ## If Proceeding
@@ -116,13 +118,25 @@ Can the team build at this quality on the projected schedule?]
 **Performance targets:** [Confirmed / Revised — list changes if revised]

 **Playtest note:** Run `/playtest-report` to structure additional session data
-before running `/gate-check pre-production`.
+before running `/gate-check production`.

 **Next steps:**
-1. `/gate-check pre-production` — formally advance to Production
-2. `/create-epics layer:foundation` — plan Foundation layer epics
-3. `/create-epics layer:core` — plan Core layer epics
+1. `/create-epics layer:foundation` — plan Foundation layer epics
+2. `/create-epics layer:core` — plan Core layer epics
+3. `/create-stories [epic-slug]` — break each epic into stories
 4. `/sprint-plan` — use velocity data from this report in the estimate
+5. `/gate-check production` — formally advance to Production
+
+---
+
+## If Not Assessed
+
+[The slice was built but nobody has played it through, so there is no evidence
+for PROCEED, PIVOT or KILL yet.]
+
+**Next step:** play the slice unguided (at least one documented session), then
+re-run `/vertical-slice` — it resumes from the checkpoint in
+`production/session-state/active.md`.

 ---

@@ -17,6 +17,64 @@
 # Phase gates (/gate-check): verdicts are ADVISORY — they guide the decision
 # but never hard-block advancement. The user always decides whether to proceed.

+# Tier paths: a tier whose route is not the phase ladder. At `workflow: minimal`
+# nothing on the path runs /gate-check, so project.stage never leaves Concept —
+# and walking the Concept phase names the concept doc, art bible and systems map
+# (all REQUIRED there) as blockers on a project that already has stories.
+# /help reads paths.minimal instead of the ladder at that tier. Same step schema
+# as phases; artifact-check.sh reports a path only when asked with --path <id>.
+
+paths:
+
+  minimal:
+    label: "Minimal path"
+    description: "Engine, one-page brief, stories, then build — the brief's build order is the plan"
+    steps:
+      - id: engine-setup
+        name: "Engine Setup"
+        command: /setup-engine
+        required: true
+        # Same alternatives as concept.engine-setup — see the notes there.
+        artifact:
+          any_of:
+            - glob: "project.yaml"
+              pattern: 'name:[[:space:]]*"?(Godot|Unity|Unreal)'
+            - glob: ".claude/docs/technical-preferences.md"
+              pattern: '\*\*Engine\*\*: [^[]'
+        description: "Configure the engine and pin its version"
+
+      - id: game-brief
+        name: "Game Brief"
+        command: /brainstorm
+        required: true
+        artifact:
+          glob: "design/game-brief.md"
+        description: "One page: pitch, MVP features, build order. Replaces the concept doc, art bible, systems map and GDDs at this tier"
+
+      - id: create-stories
+        name: "Stories"
+        command: /create-stories
+        required: true
+        artifact:
+          glob: "production/epics/*/story-*.md"
+        description: "One story per MVP feature, in build order. No /create-epics or /sprint-plan at this tier"
+
+      - id: implement
+        name: "Build the Next Story"
+        command: /dev-story
+        required: true
+        repeatable: true
+        artifact:
+          note: "Each story's Status line (Ready / In Progress / Complete) is the record — story files are numbered in build order"
+        description: "Implement the next story in build order: /dev-story [story-path]"
+
+      - id: story-done
+        name: "Close the Story"
+        command: /story-done
+        required: true
+        repeatable: true
+        description: "Verify the acceptance criteria and mark the story Complete, then build the next one"
+
 phases:

  concept:
@@ -37,17 +95,21 @@ phases:
        # v1.1: engine.name in project.yaml is the primary source; technical-
        # preferences.md is the legacy fallback. Checking only the legacy file
        # made a correctly-configured project fail this REQUIRED gate.
+        # /setup-engine writes the value quoted (`name: "Godot"`), so the quote
+        # is optional; without it only the legacy alternative ever matched.
+        # Single-quoted so the `"` needs no escape — artifact-check.sh strips
+        # the outer quotes and does not unescape.
        artifact:
          any_of:
            - glob: "project.yaml"
-              pattern: "name:[[:space:]]*(Godot|Unity|Unreal)"
+              pattern: 'name:[[:space:]]*"?(Godot|Unity|Unreal)'
            # technical-preferences.md writes "- **Engine**: Godot 4.6", so the
            # pattern must clear the bold markers. The previous "Engine: [^[]"
            # required a literal "Engine: " and therefore never matched any
            # file /setup-engine produces. The [^[] guard rejects the
            # "[TO BE CONFIGURED]" placeholder.
            - glob: ".claude/docs/technical-preferences.md"
-              pattern: "\\*\\*Engine\\*\\*: [^[]"
+              pattern: '\*\*Engine\*\*: [^[]'
        description: "Configure engine, pin version, set naming conventions and performance budgets"

      - id: game-concept
@@ -168,6 +230,22 @@ phases:
          glob: "design/accessibility-requirements.md"
        description: "Run `/ux-design accessibility`. Commit accessibility tier (Basic/Standard/Comprehensive/Exemplary) and feature matrix. UX specs (Phase 4) reference this tier."

+      - id: interaction-patterns
+        name: "Interaction Pattern Library"
+        command: /ux-design
+        required: true
+        artifact:
+          glob: "design/ux/interaction-patterns.md"
+        description: "Run `/ux-design patterns` to start the pattern library that UX specs reuse. The Technical Setup → Pre-Production gate requires it at `full` (recommended at `standard`)."
+
+      - id: test-setup
+        name: "Test Framework Setup"
+        command: /test-setup
+        required: true
+        artifact:
+          glob: ".github/workflows/tests.yml"
+        description: "Scaffold the test framework, the CI workflow and an example test. The Technical Setup → Pre-Production gate requires all three at `standard` and `full`. Leads to /test-helpers for fixture generation, /qa-plan per epic, and /smoke-check per sprint."
+
  pre-production:
    label: "Pre-Production"
    description: "Visual entity inventory, UX specs, asset specs, prototype the core mechanic, define stories, validate fun"
@@ -239,14 +317,6 @@ phases:
          min_count: 2
        description: "Break each epic into implementable story files. Run per epic: /create-stories [epic-slug]"

-      - id: test-setup
-        name: "Test Framework Setup"
-        command: /test-setup
-        required: false
-        artifact:
-          note: "Check tests/ directory for engine-specific test framework scaffold"
-        description: "Scaffold the test framework and CI pipeline once before the first sprint. Leads to /test-helpers for fixture generation, /qa-plan per epic, and /smoke-check per sprint."
-
      - id: sprint-plan
        name: "First Sprint Plan"
        command: /sprint-plan
@@ -295,7 +365,7 @@ phases:
        required: true
        repeatable: true
        artifact:
-          note: "Check src/ for active code and production/epics/**/*.md for In Progress stories"
+          note: "Check the code root (src/, Assets/ or Source/ by engine) for active code and production/epics/**/*.md for In Progress stories"
        description: "Pick the next ready story and implement it with /dev-story [story-path]. Routes to the correct programmer agent."

      - id: code-review
@@ -369,7 +439,7 @@ phases:
      - id: balance-check
        name: "Balance Check"
        command: /balance-check
-        required: false
+        required: true
        description: "Analyze game balance formulas and data for outliers and broken progressions"

      - id: asset-audit
@@ -396,31 +466,51 @@ phases:
        required: true
        description: "Coordinated polish pass across performance, audio, visual, and UX"

-  release:
-    label: "Release"
-    description: "Launch preparation, certification, and ship"
-    next_phase: null
-    steps:
+      - id: security-audit
+        name: "Security Audit"
+        command: /security-audit
+        required: true
+        artifact:
+          glob: "production/security/security-audit-*.md"
+        description: "The Polish -> Release gate reads the newest `full`-scope report (plus any later `quick` re-run) at standard and full: no open CRITICAL or HIGH finding"
+
+      - id: localize-qa
+        name: "Localization QA"
+        command: /localize
+        required: false
+        description: "Run `/localize qa` for every language you ship; at full the release gate needs PASS or PASS WITH CONDITIONS for each (recommended at standard, dropped at minimal)"
+
      - id: release-checklist
        name: "Release Checklist"
        command: /release-checklist
        required: true
-        description: "Pre-release validation across all departments: code, content, store, legal"
+        description: "Pre-release validation across all departments: code, content, store, legal. The Polish -> Release gate checks it, so it runs before /gate-check release"
+
+      - id: changelog
+        name: "Changelog"
+        command: /changelog
+        required: true
+        description: "Internal changelog from commits, sprints, and design docs. The release gate needs the changelog or the patch notes drafted"

      - id: patch-notes
        name: "Patch Notes"
        command: /patch-notes
        required: false
-        description: "Generate player-facing patch notes from git history and sprint data"
-
-      - id: changelog
-        name: "Changelog"
-        command: /changelog
-        required: false
-        description: "Auto-generate internal changelog from commits, sprints, and design docs"
+        description: "Player-facing patch notes from git history and sprint data; /team-release finalizes them on a GO"

+  release:
+    label: "Release"
+    description: "Launch preparation, certification, and ship"
+    next_phase: null
+    steps:
      - id: launch-checklist
        name: "Launch Checklist"
        command: /launch-checklist
        required: true
        description: "Final launch readiness — last gate before shipping to players"
+
+      - id: team-release
+        name: "Coordinated Release"
+        command: /team-release
+        required: false
+        description: "Release candidate, quality gate, go/no-go and deployment, coordinated across release, QA and DevOps"
@@ -130,7 +130,7 @@ the expansion.) Per-system overrides read via

 **Default**: `minimal` (the rationale block above `_yaml_helper_defaults` in
 `.claude/hooks/yaml-helper.sh` carries the reasoning and the ordering
-constraint). **Set by**: `/start`, `/settings`. **Locked to
+constraint). **Set by**: `/start` (via `modes.rigor`), `/settings`. **Locked to
 `project.yaml`** (not locally overridable — divergence would change which
 artifacts must exist on disk).