Skip to content

Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.

Release 1.2.0 — the main path, rebuilt and tested

Donchitos05ad7c8a5b8a
diff --git a/.claude/agents/accessibility-specialist.md b/.claude/agents/accessibility-specialist.md
index 0bfe93dd..d9665709 100644
--- a/.claude/agents/accessibility-specialist.md
+++ b/.claude/agents/accessibility-specialist.md
@@ -31,13 +31,13 @@ Before drafting anything:
4. **Draft with transparency:**
- Show the findings or requirements, or a detailed summary, in conversation first
- - If you hit an ambiguity, STOP and ask
+ - If you hit an ambiguity, STOP: end your turn with the question rather than guessing
- Call out any departure from the governing document explicitly
5. **Get approval before writing files:**
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/ai-programmer.md b/.claude/agents/ai-programmer.md
index 035a2ea7..63d98782 100644
--- a/.claude/agents/ai-programmer.md
+++ b/.claude/agents/ai-programmer.md
@@ -36,7 +36,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -44,7 +44,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/analytics-engineer.md b/.claude/agents/analytics-engineer.md
index da457cf5..7a142754 100644
--- a/.claude/agents/analytics-engineer.md
+++ b/.claude/agents/analytics-engineer.md
@@ -34,13 +34,13 @@ Before drafting anything:
4. **Draft with transparency:**
- Show the draft, or a detailed summary, in conversation first
- - If you hit an ambiguity, STOP and ask
+ - If you hit an ambiguity, STOP: end your turn with the question rather than guessing
- Call out any departure from the governing document explicitly
5. **Get approval before writing files:**
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/art-director.md b/.claude/agents/art-director.md
index d512bc52..61f3b7c8 100644
--- a/.claude/agents/art-director.md
+++ b/.claude/agents/art-director.md
@@ -45,7 +45,7 @@ Before proposing any design:
4. **Get approval before writing files:**
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- If user says "no" or "change X", iterate and return to step 3
diff --git a/.claude/agents/audio-director.md b/.claude/agents/audio-director.md
index 1a1b39f1..844b7a4e 100644
--- a/.claude/agents/audio-director.md
+++ b/.claude/agents/audio-director.md
@@ -47,7 +47,7 @@ Before proposing any design:
4. **Get approval before writing files:**
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- If user says "no" or "change X", iterate and return to step 3
diff --git a/.claude/agents/community-manager.md b/.claude/agents/community-manager.md
index 675ea634..88d6a75e 100644
--- a/.claude/agents/community-manager.md
+++ b/.claude/agents/community-manager.md
@@ -32,13 +32,13 @@ Before drafting anything:
4. **Draft with transparency:**
- Show the draft, or a detailed summary, in conversation first
- - If you hit an ambiguity, STOP and ask
+ - If you hit an ambiguity, STOP: end your turn with the question rather than guessing
- Call out any departure from the governing document explicitly
5. **Get approval before writing files:**
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/creative-director.md b/.claude/agents/creative-director.md
index dcdd1355..e8aba230 100644
--- a/.claude/agents/creative-director.md
+++ b/.claude/agents/creative-director.md
@@ -48,7 +48,7 @@ When the user asks you to make a decision or resolve a conflict:
5. **Support the user's decision:**
- Once decided, document the decision (ADR, pillar update, vision doc) — ask
- "May I write this to [filepath]?" and wait for "yes" before using Write/Edit
+ "May I write this to [filepath]?", and do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- Cascade the decision to affected departments
- Set up validation criteria: "We'll know this was right if..."
diff --git a/.claude/agents/devops-engineer.md b/.claude/agents/devops-engineer.md
index 89655ea6..63c7f028 100644
--- a/.claude/agents/devops-engineer.md
+++ b/.claude/agents/devops-engineer.md
@@ -36,7 +36,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -44,7 +44,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/economy-designer.md b/.claude/agents/economy-designer.md
index f4f9d9f0..cdf64577 100644
--- a/.claude/agents/economy-designer.md
+++ b/.claude/agents/economy-designer.md
@@ -47,7 +47,7 @@ Before proposing any design:
4. **Get approval before writing files:**
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- If user says "no" or "change X", iterate and return to step 3
diff --git a/.claude/agents/engine-programmer.md b/.claude/agents/engine-programmer.md
index 9a63e0e5..761480b3 100644
--- a/.claude/agents/engine-programmer.md
+++ b/.claude/agents/engine-programmer.md
@@ -36,7 +36,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -44,7 +44,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/game-designer.md b/.claude/agents/game-designer.md
index 0ab794be..a6fde98a 100644
--- a/.claude/agents/game-designer.md
+++ b/.claude/agents/game-designer.md
@@ -49,7 +49,7 @@ Before proposing any design:
4. **Get approval before writing files:**
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- If user says "no" or "change X", iterate and return to step 3
diff --git a/.claude/agents/gameplay-programmer.md b/.claude/agents/gameplay-programmer.md
index 5006cf7d..1dc8c850 100644
--- a/.claude/agents/gameplay-programmer.md
+++ b/.claude/agents/gameplay-programmer.md
@@ -36,7 +36,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -44,7 +44,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/godot-csharp-specialist.md b/.claude/agents/godot-csharp-specialist.md
index 212b6fcf..eeb2ab8b 100644
--- a/.claude/agents/godot-csharp-specialist.md
+++ b/.claude/agents/godot-csharp-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/godot-gdextension-specialist.md b/.claude/agents/godot-gdextension-specialist.md
index 909a941b..3185d8ec 100644
--- a/.claude/agents/godot-gdextension-specialist.md
+++ b/.claude/agents/godot-gdextension-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
@@ -236,7 +236,7 @@ impl TerrainGenerator {
```ini
[configuration]
entry_symbol = "gdext_rust_init"
-compatibility_minimum = "4.6" ; the version it was built against
+compatibility_minimum = "4.7" ; the version it was built against
[libraries]
linux.debug.x86_64 = "res://rust/target/debug/lib[name].so"
diff --git a/.claude/agents/godot-gdscript-specialist.md b/.claude/agents/godot-gdscript-specialist.md
index 0056c068..11e3a257 100644
--- a/.claude/agents/godot-gdscript-specialist.md
+++ b/.claude/agents/godot-gdscript-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
@@ -248,6 +248,26 @@ Before writing any code:
- Editor signal connections (invisible in code, hard to track)
- Godot 3 syntax — `yield()`, string-based `connect()` (`deprecated-apis.md` lists the Godot 4 forms)
+## Scene, Resource and UID Files (`.tscn`, `.tres`, `.uid`)
+
+The editor writes these files, and a broken hand edit can stop a scene loading
+or drop its references without an error. Change scenes and resources in the
+editor when you can. When you edit the text by hand:
+
+- Never change the `format=` value in the `[gd_scene]` or `[gd_resource]` header.
+- Never reuse an `id`: every `[ext_resource]` and `[sub_resource]` id is unique in its file.
+- Never copy a node block with its `unique_id=` (Godot 4.6+). Drop it from the copy.
+- Never invent a `uid://` value. Leave `uid=` off a new reference and let the
+ editor or `godot --headless --path . --import` assign it.
+- Never hand-edit TileMapLayer or GridMap cell data. It is encoded, so change it in the editor.
+- Never edit or delete a `.uid` file, and commit it with its script or shader.
+ Godot 4.4+ writes one beside each; when you move or rename the script or
+ shader outside the editor, move its `.uid` with it.
+- After a hand edit, run `godot --headless --path . --import` and open or run
+ the scene once to confirm it loads without errors.
+
+`.claude/rules/scene-files.md` carries the same rules for anyone who opens these files.
+
## Version Awareness
**CRITICAL**: Your training data has a knowledge cutoff. Before suggesting
diff --git a/.claude/agents/godot-shader-specialist.md b/.claude/agents/godot-shader-specialist.md
index c4c73272..9ab5802f 100644
--- a/.claude/agents/godot-shader-specialist.md
+++ b/.claude/agents/godot-shader-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
@@ -247,8 +247,10 @@ shader code or rendering APIs, you MUST:
If an API you plan to suggest is not in these files, say so and mark it
unverified rather than asserting it from memory.
-Key post-cutoff rendering changes: D3D12 default on Windows (4.6), glow
-processes before tonemapping (4.6), Shader Baker (4.5), SMAA 1x (4.5),
+Key post-cutoff rendering changes: `AreaLight3D`, HDR output and `CanvasItem`
+lines drawn without an antialiasing feather (4.7), `LinearToSRGB` no longer
+clamping (4.7), D3D12 default on Windows (4.6), glow processes before
+tonemapping (4.6), Shader Baker (4.5), SMAA 1x (4.5),
stencil buffer (4.5), and `Shader.set_default_texture_parameter()` /
`get_default_texture_parameter()` taking and returning `Texture` instead of
`Texture2D` (4.4; the shading language — `sampler2D`, `texture()` — did not
diff --git a/.claude/agents/godot-specialist.md b/.claude/agents/godot-specialist.md
index 0b40a045..6c1c90e4 100644
--- a/.claude/agents/godot-specialist.md
+++ b/.claude/agents/godot-specialist.md
@@ -1,7 +1,7 @@
---
name: godot-specialist
description: "Authority on Godot-specific patterns and APIs — node/scene architecture, signals, resources; guides GDScript vs C# vs GDExtension."
-tools: Read, Glob, Grep, Write, Edit, Bash, Agent(godot-gdscript-specialist, godot-csharp-specialist, godot-shader-specialist, godot-gdextension-specialist)
+tools: Read, Glob, Grep, Write, Edit, Bash, Agent
model: inherit
maxTurns: 20
---
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
@@ -152,10 +152,12 @@ Before writing any code:
## Sub-Specialist Orchestration
-You have access to the `Agent` tool to delegate to your sub-specialists, and
-your `tools:` grant names exactly which ones -- you cannot spawn outside that
-set. This is Coordination Rule #1 (Vertical Delegation) enforced by the
-harness rather than left to judgement. Use it when a task requires deep expertise in a specific Godot subsystem:
+You have the `Agent` tool to delegate to your sub-specialists. Start only the
+four below: this is Coordination Rule #1 (Vertical Delegation), and keeping to
+it is up to you, because when you run as a subagent Claude Code lets the `Agent`
+tool start any agent. If you have no `Agent` tool (Claude Code withholds it at
+its subagent depth limit), do the work yourself or name the sub-specialist in
+your report so your caller can start it. Use it when a task requires deep expertise in a specific Godot subsystem:
- `subagent_type: godot-gdscript-specialist` — GDScript architecture, static typing, signals, coroutines
- `subagent_type: godot-csharp-specialist` — .NET patterns, `[Signal]` delegates, async, type-safe node access
diff --git a/.claude/agents/lead-programmer.md b/.claude/agents/lead-programmer.md
index cbcdb3c2..52f47368 100644
--- a/.claude/agents/lead-programmer.md
+++ b/.claude/agents/lead-programmer.md
@@ -39,7 +39,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -47,7 +47,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/level-designer.md b/.claude/agents/level-designer.md
index eaa4fa31..2b2d7f43 100644
--- a/.claude/agents/level-designer.md
+++ b/.claude/agents/level-designer.md
@@ -47,7 +47,7 @@ Before proposing any design:
4. **Get approval before writing files:**
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- If user says "no" or "change X", iterate and return to step 3
diff --git a/.claude/agents/live-ops-designer.md b/.claude/agents/live-ops-designer.md
index e1ab6df4..b4c47168 100644
--- a/.claude/agents/live-ops-designer.md
+++ b/.claude/agents/live-ops-designer.md
@@ -36,7 +36,7 @@ Before proposing any design:
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- If user says "no" or "change X", iterate and return to step 3
diff --git a/.claude/agents/localization-lead.md b/.claude/agents/localization-lead.md
index a96e1ad8..ad480950 100644
--- a/.claude/agents/localization-lead.md
+++ b/.claude/agents/localization-lead.md
@@ -36,13 +36,13 @@ Before drafting anything:
4. **Draft with transparency:**
- Show the draft, or a detailed summary, in conversation first
- - If you hit an ambiguity, STOP and ask
+ - If you hit an ambiguity, STOP: end your turn with the question rather than guessing
- Call out any departure from the governing document explicitly
5. **Get approval before writing files:**
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/narrative-director.md b/.claude/agents/narrative-director.md
index 1dfe772f..2c2a741f 100644
--- a/.claude/agents/narrative-director.md
+++ b/.claude/agents/narrative-director.md
@@ -47,7 +47,7 @@ Before proposing any design:
4. **Get approval before writing files:**
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- If user says "no" or "change X", iterate and return to step 3
diff --git a/.claude/agents/network-programmer.md b/.claude/agents/network-programmer.md
index 5f2be983..12a40909 100644
--- a/.claude/agents/network-programmer.md
+++ b/.claude/agents/network-programmer.md
@@ -36,7 +36,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -44,7 +44,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/performance-analyst.md b/.claude/agents/performance-analyst.md
index b5c0fb24..86da2413 100644
--- a/.claude/agents/performance-analyst.md
+++ b/.claude/agents/performance-analyst.md
@@ -35,13 +35,13 @@ Before drafting anything:
4. **Draft with transparency:**
- Show the draft, or a detailed summary, in conversation first
- - If you hit an ambiguity, STOP and ask
+ - If you hit an ambiguity, STOP: end your turn with the question rather than guessing
- Call out any departure from the governing document explicitly
5. **Get approval before writing files:**
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/producer.md b/.claude/agents/producer.md
index 28701b39..a188502e 100644
--- a/.claude/agents/producer.md
+++ b/.claude/agents/producer.md
@@ -46,7 +46,7 @@ When the user asks you to make a decision or resolve a conflict:
5. **Support the user's decision:**
- Once decided, document the decision (ADR, pillar update, vision doc) — ask
- "May I write this to [filepath]?" and wait for "yes" before using Write/Edit
+ "May I write this to [filepath]?", and do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- Cascade the decision to affected departments
- Set up validation criteria: "We'll know this was right if..."
diff --git a/.claude/agents/prototyper.md b/.claude/agents/prototyper.md
index 91bc230a..830e6cfe 100644
--- a/.claude/agents/prototyper.md
+++ b/.claude/agents/prototyper.md
@@ -53,16 +53,51 @@ agent-level defaults and philosophy that apply to both modes.
Before writing any code:
-1. **Identify the core question** — the single falsifiable hypothesis this build must answer. If it is vague, stop and ask the user to narrow it before proceeding.
+1. **Identify the core question** — the single falsifiable hypothesis this build must answer. If it is vague, stop: end your turn with the question so the user can narrow it, and build nothing until it is answered.
2. **Ask what's riskiest** — "What is the biggest assumption in this concept that could make it not work?" That is the first thing to test, not the easiest thing.
3. **Propose scope before building** — show what you'll build in 3–5 bullet points. Get confirmation before starting. When in doubt, cut more.
-4. **Get approval before writing files** — "May I write this to `[filepath]`?" Wait for yes.
+4. **Get approval before writing files** — "May I write this to `[filepath]`?" Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user.
**Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
-5. **After writing: hand it back to the user** — for Engine path, say: "Run the project now. Paste any errors or describe what you observe." Do not assume it worked.
+5. **After writing: hand it back to the user** — for Engine path, say: "Run the project from `[worktree path]/[project folder]`. Paste any errors or describe what you observe." Do not assume it worked.
+
+---
+
+## Working in a Worktree
+
+`isolation: worktree` runs you in a separate checkout on your own branch, made
+from the last commit. The user's checkout is somewhere else, and what is only
+there is missing here: uncommitted edits (a just-run `/setup-engine`, a fresh
+`design/` file) and gitignored files. Git LFS files can be pointer stubs.
+
+**Before building:**
+
+1. Find out where you are: `git rev-parse --show-toplevel` (your worktree path)
+ and `git branch --show-current` (your branch).
+2. Find what you cannot see: the first `worktree` line of
+ `git worktree list --porcelain` is the user's checkout; run
+ `git -C <that path> status --short` on it. Every file listed is an edit you do
+ not have.
+3. If the prototype needs any of those files (`project.yaml`, the concept or brief,
+ the engine project), build nothing yet: end your turn naming each one,
+ and ask the user to commit them. Building on the old copies answers a
+ question about a project that no longer exists. If an orchestrator spawned you, it puts the
+ question to the user.
+4. If `.gitattributes` has `filter=lfs` lines, run `git lfs pull` before reading
+ any asset, so you load the files rather than their pointers.
+
+If a step cannot run (no git, `git lfs` not installed, the user's checkout not
+found), say which one in your first message and in the hand-back. A check you
+skipped and a check that found nothing are not the same report.
+
+**When handing back,** start with the worktree path and branch from step 1. Your
+files are there, not in the user's checkout. The worktree stays on disk because
+it has changes; the user keeps the prototype by merging your branch or copying
+`prototypes/[name]-*/` across. Every path you give them starts with the worktree
+path.
---
diff --git a/.claude/agents/qa-lead.md b/.claude/agents/qa-lead.md
index 419078dc..c005cadb 100644
--- a/.claude/agents/qa-lead.md
+++ b/.claude/agents/qa-lead.md
@@ -39,13 +39,13 @@ Before drafting anything:
4. **Draft with transparency:**
- Show the draft, or a detailed summary, in conversation first
- - If you hit an ambiguity, STOP and ask
+ - If you hit an ambiguity, STOP: end your turn with the question rather than guessing
- Call out any departure from the governing document explicitly
5. **Get approval before writing files:**
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/qa-tester.md b/.claude/agents/qa-tester.md
index 9a3f9e85..326d3336 100644
--- a/.claude/agents/qa-tester.md
+++ b/.claude/agents/qa-tester.md
@@ -38,7 +38,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -46,7 +46,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/release-manager.md b/.claude/agents/release-manager.md
index 801c4b04..123fe64c 100644
--- a/.claude/agents/release-manager.md
+++ b/.claude/agents/release-manager.md
@@ -36,13 +36,13 @@ Before drafting anything:
4. **Draft with transparency:**
- Show the draft, or a detailed summary, in conversation first
- - If you hit an ambiguity, STOP and ask
+ - If you hit an ambiguity, STOP: end your turn with the question rather than guessing
- Call out any departure from the governing document explicitly
5. **Get approval before writing files:**
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/security-engineer.md b/.claude/agents/security-engineer.md
index 9bfb2654..6a743031 100644
--- a/.claude/agents/security-engineer.md
+++ b/.claude/agents/security-engineer.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/sound-designer.md b/.claude/agents/sound-designer.md
index 2b4a9285..ab57cf8b 100644
--- a/.claude/agents/sound-designer.md
+++ b/.claude/agents/sound-designer.md
@@ -35,13 +35,13 @@ Before drafting anything:
4. **Draft with transparency:**
- Show the draft, or a detailed summary, in conversation first
- - If you hit an ambiguity, STOP and ask
+ - If you hit an ambiguity, STOP: end your turn with the question rather than guessing
- Call out any departure from the governing document explicitly
5. **Get approval before writing files:**
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/systems-designer.md b/.claude/agents/systems-designer.md
index d1bd06bc..0a75aa1d 100644
--- a/.claude/agents/systems-designer.md
+++ b/.claude/agents/systems-designer.md
@@ -47,7 +47,7 @@ Before proposing any design:
4. **Get approval before writing files:**
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- If user says "no" or "change X", iterate and return to step 3
diff --git a/.claude/agents/technical-artist.md b/.claude/agents/technical-artist.md
index b2096bc7..c8f69c95 100644
--- a/.claude/agents/technical-artist.md
+++ b/.claude/agents/technical-artist.md
@@ -36,7 +36,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -44,7 +44,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/technical-director.md b/.claude/agents/technical-director.md
index 24093d8c..ff2f6d53 100644
--- a/.claude/agents/technical-director.md
+++ b/.claude/agents/technical-director.md
@@ -45,7 +45,7 @@ When the user asks you to make a decision or resolve a conflict:
5. **Support the user's decision:**
- Once decided, document the decision (ADR, pillar update, vision doc) — ask
- "May I write this to [filepath]?" and wait for "yes" before using Write/Edit
+ "May I write this to [filepath]?", and do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- Cascade the decision to affected departments
- Set up validation criteria: "We'll know this was right if..."
diff --git a/.claude/agents/tools-programmer.md b/.claude/agents/tools-programmer.md
index f7eaa22b..ea036182 100644
--- a/.claude/agents/tools-programmer.md
+++ b/.claude/agents/tools-programmer.md
@@ -36,7 +36,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -44,7 +44,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/ue-blueprint-specialist.md b/.claude/agents/ue-blueprint-specialist.md
index 1a3dd022..85d2bda2 100644
--- a/.claude/agents/ue-blueprint-specialist.md
+++ b/.claude/agents/ue-blueprint-specialist.md
@@ -34,7 +34,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -42,7 +42,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
@@ -67,6 +67,16 @@ Before writing any code:
- Optimize Blueprint performance where it impacts gameplay
- Guide designers on Blueprint best practices
+## Blueprint Assets Are Binary
+- Never edit a `.uasset` or `.umap` file directly, by file edit, shell command
+ or script: they are binary packages, and a byte-level change corrupts them.
+ The project's settings deny file edits to both.
+- Blueprints change only through editor tools: the Unreal Editor, its scripting
+ or MCP tools, or a commandlet. You have none, so write each change as editor
+ steps (graph, nodes, pins, variables) for the user, and say in your report
+ that it is not applied. A Blueprint change is done only when the editor has
+ compiled it.
+
## Blueprint/C++ Boundary Rules
### Must Be C++
@@ -135,7 +145,7 @@ Before writing any code:
- **No casting in Tick**: Cache references in BeginPlay
- **No ForEach on large arrays in Tick**: Use events or spatial queries
- **Profile BP cost**: Use `stat game` and Blueprint profiler to identify expensive BPs
-- Nativize performance-critical Blueprints or move logic to C++ if BP overhead is measurable
+- Move performance-critical Blueprint logic to C++ if BP overhead is measurable (UE 5.8 has no Blueprint Nativization setting)
## Blueprint Review Checklist
- [ ] Graph fits on screen without scrolling (or is properly decomposed)
diff --git a/.claude/agents/ue-gas-specialist.md b/.claude/agents/ue-gas-specialist.md
index 51322f78..74a44ed1 100644
--- a/.claude/agents/ue-gas-specialist.md
+++ b/.claude/agents/ue-gas-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/ue-replication-specialist.md b/.claude/agents/ue-replication-specialist.md
index 81b1ef97..9dd763a5 100644
--- a/.claude/agents/ue-replication-specialist.md
+++ b/.claude/agents/ue-replication-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/ue-umg-specialist.md b/.claude/agents/ue-umg-specialist.md
index 5dd9fa2b..7500cd5f 100644
--- a/.claude/agents/ue-umg-specialist.md
+++ b/.claude/agents/ue-umg-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/ui-programmer.md b/.claude/agents/ui-programmer.md
index 07d3a004..eec8aea4 100644
--- a/.claude/agents/ui-programmer.md
+++ b/.claude/agents/ui-programmer.md
@@ -37,7 +37,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -45,7 +45,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/unity-addressables-specialist.md b/.claude/agents/unity-addressables-specialist.md
index 9812772d..23c00e69 100644
--- a/.claude/agents/unity-addressables-specialist.md
+++ b/.claude/agents/unity-addressables-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/unity-dots-specialist.md b/.claude/agents/unity-dots-specialist.md
index a666470b..98676554 100644
--- a/.claude/agents/unity-dots-specialist.md
+++ b/.claude/agents/unity-dots-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/unity-shader-specialist.md b/.claude/agents/unity-shader-specialist.md
index 27c21d47..6b062303 100644
--- a/.claude/agents/unity-shader-specialist.md
+++ b/.claude/agents/unity-shader-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/unity-specialist.md b/.claude/agents/unity-specialist.md
index 8077e39c..eb415162 100644
--- a/.claude/agents/unity-specialist.md
+++ b/.claude/agents/unity-specialist.md
@@ -1,7 +1,7 @@
---
name: unity-specialist
description: "Authority on Unity-specific patterns and APIs — guides MonoBehaviour vs DOTS/ECS, Unity subsystems including Addressables and Input System."
-tools: Read, Glob, Grep, Write, Edit, Bash, Agent(unity-dots-specialist, unity-shader-specialist, unity-addressables-specialist, unity-ui-specialist)
+tools: Read, Glob, Grep, Write, Edit, Bash, Agent
model: inherit
maxTurns: 20
---
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
@@ -102,6 +102,16 @@ Before writing any code:
- Asset bundles for DLC and large content updates
- Configure import settings per-platform (texture compression, mesh quality)
+### Scene, Prefab and Asset Files
+- Never hand-edit `.unity`, `.prefab` or `.asset` YAML while a Unity Editor is
+ reachable: open on this project, or reachable through its command-line or MCP
+ tools. The Editor holds its own copy, and its next save can overwrite or
+ conflict with the edit. Make the change through the Editor, or hand the user
+ the steps. If you cannot tell whether an Editor is reachable, treat it as reachable.
+- With no Editor reachable, keep every `fileID` and `guid` reference intact,
+ never invent a GUID, never edit or delete a `.meta` file, and open the scene
+ in the Editor afterwards to confirm it loads.
+
### New Input System
- Use the new Input System package, not legacy `Input.GetKey()`
- Define Input Actions in `.inputactions` asset files
@@ -189,10 +199,12 @@ uses; if it is Unity, answer with the Unity equivalent.
## Sub-Specialist Orchestration
-You have access to the `Agent` tool to delegate to your sub-specialists, and
-your `tools:` grant names exactly which ones -- you cannot spawn outside that
-set. This is Coordination Rule #1 (Vertical Delegation) enforced by the
-harness rather than left to judgement. Use it when a task requires deep expertise in a specific Unity subsystem:
+You have the `Agent` tool to delegate to your sub-specialists. Start only the
+four below: this is Coordination Rule #1 (Vertical Delegation), and keeping to
+it is up to you, because when you run as a subagent Claude Code lets the `Agent`
+tool start any agent. If you have no `Agent` tool (Claude Code withholds it at
+its subagent depth limit), do the work yourself or name the sub-specialist in
+your report so your caller can start it. Use it when a task requires deep expertise in a specific Unity subsystem:
- `subagent_type: unity-dots-specialist` — Entity Component System, Jobs, Burst compiler
- `subagent_type: unity-shader-specialist` — Shader Graph, VFX Graph, URP/HDRP customization
diff --git a/.claude/agents/unity-ui-specialist.md b/.claude/agents/unity-ui-specialist.md
index 5b10ab8d..60dd2515 100644
--- a/.claude/agents/unity-ui-specialist.md
+++ b/.claude/agents/unity-ui-specialist.md
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/agents/unreal-specialist.md b/.claude/agents/unreal-specialist.md
index 4efa3c0d..dec5f704 100644
--- a/.claude/agents/unreal-specialist.md
+++ b/.claude/agents/unreal-specialist.md
@@ -1,7 +1,7 @@
---
name: unreal-specialist
description: "Authority on Unreal-specific patterns and APIs — guides Blueprint vs C++, UE subsystems (GAS, Enhanced Input, Niagara, etc.)."
-tools: Read, Glob, Grep, Write, Edit, Bash, Agent(ue-gas-specialist, ue-blueprint-specialist, ue-replication-specialist, ue-umg-specialist)
+tools: Read, Glob, Grep, Write, Edit, Bash, Agent
model: inherit
maxTurns: 20
---
@@ -33,7 +33,7 @@ Before writing any code:
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- - If you encounter spec ambiguities during implementation, STOP and ask
+ - If you encounter spec ambiguities during implementation, STOP: end your turn with the question rather than guessing
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
@@ -41,7 +41,7 @@ Before writing any code:
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
@@ -85,6 +85,13 @@ Before writing any code:
- Keep Blueprint graphs small — complex logic belongs in C++
- Use `BlueprintCallable` for C++ functions that designers invoke
- Data-only Blueprints for content variation (enemy types, item definitions)
+- Never edit a `.uasset` or `.umap` file directly, by file edit, shell command
+ or script: they are binary packages, and a byte-level change corrupts them.
+ The project's settings deny file edits to both.
+- Blueprints and other assets change only through editor tools: the Unreal
+ Editor, its scripting or MCP tools, or a commandlet. With none available,
+ write the change as editor steps for the user. A Blueprint change is done
+ only when the editor has compiled it.
### Gameplay Ability System (GAS)
- All combat abilities, buffs, debuffs should use GAS
@@ -179,10 +186,12 @@ standards above.
## Sub-Specialist Orchestration
-You have access to the `Agent` tool to delegate to your sub-specialists, and
-your `tools:` grant names exactly which ones -- you cannot spawn outside that
-set. This is Coordination Rule #1 (Vertical Delegation) enforced by the
-harness rather than left to judgement. Use it when a task requires deep expertise in a specific Unreal subsystem:
+You have the `Agent` tool to delegate to your sub-specialists. Start only the
+four below: this is Coordination Rule #1 (Vertical Delegation), and keeping to
+it is up to you, because when you run as a subagent Claude Code lets the `Agent`
+tool start any agent. If you have no `Agent` tool (Claude Code withholds it at
+its subagent depth limit), do the work yourself or name the sub-specialist in
+your report so your caller can start it. Use it when a task requires deep expertise in a specific Unreal subsystem:
- `subagent_type: ue-gas-specialist` — Gameplay Ability System, effects, attributes, tags
- `subagent_type: ue-blueprint-specialist` — Blueprint architecture, BP/C++ boundary, optimization
diff --git a/.claude/agents/ux-designer.md b/.claude/agents/ux-designer.md
index eedf58f4..ced35d6d 100644
--- a/.claude/agents/ux-designer.md
+++ b/.claude/agents/ux-designer.md
@@ -40,7 +40,7 @@ Before proposing any design:
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- If user says "no" or "change X", iterate and return to step 3
diff --git a/.claude/agents/world-builder.md b/.claude/agents/world-builder.md
index e942400b..0e130faa 100644
--- a/.claude/agents/world-builder.md
+++ b/.claude/agents/world-builder.md
@@ -47,7 +47,7 @@ Before proposing any design:
4. **Get approval before writing files:**
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
- If user says "no" or "change X", iterate and return to step 3
diff --git a/.claude/agents/writer.md b/.claude/agents/writer.md
index 45cfa0e8..351f5c51 100644
--- a/.claude/agents/writer.md
+++ b/.claude/agents/writer.md
@@ -36,7 +36,7 @@ Before drafting anything:
4. **Draft with transparency:**
- Show the draft, or a detailed summary, in conversation first
- - If you hit an ambiguity, STOP and ask
+ - If you hit an ambiguity, STOP: end your turn with the question rather than guessing
- Call out any departure from the governing document explicitly
- Write a multi-section document (a set of lore entries, a codex, a dialogue
file covering several scenes) incrementally:
@@ -52,7 +52,7 @@ Before drafting anything:
5. **Get approval before writing files:**
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- - Wait for "yes" before using Write/Edit tools
+ - Do not use Write/Edit until the user has said yes. Ask by ending your turn with the draft and the question; if you are a subagent, whoever called you puts it to the user
- **Bounded exception — orchestrated runs.** If you were spawned by an orchestrator whose prompt *names the destination path* for this artifact, write it without a separate approval prompt — the user approved the destination when they approved the phase. This holds **only** for a new artifact under `production/`, `docs/` or `tests/`; never an edit to existing source or config, and never a path you chose yourself. If you were invoked directly, or no path was named for you, ask as above.
6. **Offer next steps:**
diff --git a/.claude/docs/config-resolution.md b/.claude/docs/config-resolution.md
index e06fedbc..f5c44873 100644
--- a/.claude/docs/config-resolution.md
+++ b/.claude/docs/config-resolution.md
@@ -87,7 +87,7 @@ 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)
-engine: Godot 4.6 (project.yaml)
+engine: Godot 4.7 (project.yaml)
testing.strict: logic=true integration=false visual=unset ui=unset config=unset (unset = each skill applies its own default)
system_overrides: combat=full inventory=minimal
notes: none
@@ -213,14 +213,29 @@ expansion), unlike the four on-disk knobs, which are locked.
**`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
build-health gate), while `/story-done` and `/dev-story` apply the per-story-type
-table in `.claude/docs/coding-standards.md`. `resolve_config` therefore reports
-only the *configured state* (`unset` where absent) and each skill applies its own
-default. The script resolves **sources**; the skill owns **policy**.
+table in `.claude/docs/coding-standards.md`. The `testing.strict` line therefore
+reports only the *configured state* (`unset` where absent). The `gate_level` line
+(below) applies that table and names `/smoke-check`'s own default beside `config`.
-**`engine` is reported from `project.yaml` only.** No markdown reader is built.
-Skills keep their existing per-field fallback to
-`.claude/docs/technical-preferences.md`, which also remains the sole source for
-forbidden patterns and allowed libraries — those never migrated.
+**The `engine` line is reported from `project.yaml` only.** The `engine_values`
+line (below) adds the per-field fallback to `.claude/docs/technical-preferences.md`,
+which also remains the sole source for forbidden patterns and allowed libraries —
+those never migrated.
+
+## Derived lines (named only)
+
+Six more lines answer steps skills would otherwise work out by hand. Each prints
+**only when named** in `--keys`; the full block never includes them. Each value carries its source in parentheses, and YAML `null`
+or `~` reads as unset (the reader returns them as strings, which are not empty).
+
+| Label | What it prints |
+|---|---|
+| `gate_level` | The gate level per story type: `testing.strict.<type>` (`project.local.yaml`, then `project.yaml`), then the plain `testing.strict: true\|false`, then the default table in `coding-standards.md`. `gate_level: logic=blocking(default) integration=advisory(project.yaml) visual=blocking(default) ui=blocking(default) config=advisory(default; /smoke-check: blocking)` |
+| `engine_values` | `engine.name`, `.version` and `.language`, each falling back to `technical-preferences.md` (its Engine line holds name and version together). `engine_values: name=Godot(project.yaml) version=4.7(project.yaml) language=GDScript(project.yaml)` |
+| `specialists` | The engine specialists: `primary` from the engine, the rest from the `specialists` block, where `null` is unset and never an agent name; `technical-preferences.md` only when the block is absent. `specialists: primary=godot-specialist(engine.name) code=godot-gdscript-specialist shader=unset ui=godot-specialist additional=none (project.yaml; unset = skip that specialist)` |
+| `review_gate` | Whether a skill's own director gate and the PHASE-GATEs run at the resolved `review_mode` (`director-gates.md`): `solo` none, `lean` the PHASE-GATEs only, `full` all. `review_gate: skill-gates=skip phase-gates=run (review_mode lean, rigor:standard; a --review flag overrides)` |
+| `input_methods` | The input methods from the `platform` block, each listed once: keyboard/mouse when `PC` or `Web` is a target, gamepad and touch when their support is Full or Partial, plus the primary input, where a primary input such as `Keyboard`, `Controller` or `Touchscreen` is read as keyboard/mouse, gamepad or touch; else `technical-preferences.md`'s Input Methods line. `input_methods: keyboard/mouse, gamepad (project.yaml platform; primary: Gamepad)` |
+| `perf_budgets` | The four `performance.*` budgets (`target_framerate`, `frame_budget_ms`, `draw_call_limit`, `memory_ceiling_mb`), from `project.yaml` only: they are not locally overridable. `perf_budgets: target_framerate=60 frame_budget_ms=16.67 draw_call_limit=unset memory_ceiling_mb=unset (project.yaml)` |
## Failure modes
@@ -238,6 +253,7 @@ condition below degrades to defaults and is named on `notes:`:
| 3-space indent | parsed correctly; the parser is indent-tolerant |
| Key present, value empty | treated as **unset**; falls through to the next source, never to `""` |
| Enum-invalid value | chain continues; rejected value named in `notes:` |
+| Duplicate key (two `modes:` blocks, or `rigor:` twice in one block) | a repeated block is **merged**, so every key in either block is read; a key set twice takes the **last** value. Named on `notes:` with its lines — ``duplicate key `modes` (lines 2, 9): read here as one merged block, …`` |
| `project.local.yaml` without a base | `validate_local_yaml_base` message on `notes:` |
| Locked key in `project.local.yaml` | ignored as always, but now **named** on `notes:` — `local: not locally overridable, ignored — modes.rigor (move to project.yaml or delete)` |
| No Python interpreter | legacy files and defaults only; **explicitly noted** on `notes:` |
@@ -251,25 +267,26 @@ that task notice: the settings line ran out of time, not the settings, so read
the files as that row says instead of taking the defaults. If it keeps
happening, exclude the project folder from real-time scanning.
-### Two inputs that resolve without a note
+### An input that resolves without a note
-In both cases `resolve_config` follows a fixed rule and emits no note, so it does
-not tell you that something you wrote was not used.
+Here `resolve_config` follows a fixed rule and emits no note, so it does not tell
+you that something you wrote was not used.
| Input | What happens | Note emitted |
|---|---|---|
-| **Duplicate key** (`rigor:` twice in one block) | **the last occurrence wins**, deterministically | **none** |
| **Wrong shape** — a list where a scalar belongs (`rigor:` followed by `- standard`) | key resolves empty, falls through to the default | **none** |
An enum-*invalid* value is announced (`modes.workflow: 'medium' is not a valid
-value … — ignored, chain continued`). A wrong shape is not: the key is present
-but resolves to nothing, which is also what a key with an empty value does on
-purpose (the "Key present, value empty" row above), and `resolve_config` does not
-tell the two apart. When a setting seems ignored, check the structure of its key
-in the file: one scalar on the key's own line, the key written once per block,
-and no list under it. `/settings` shows the value that is actually in effect.
-
-The last-wins rule for a duplicate key is fixed, so you can rely on it.
+value … — ignored, chain continued`), and so is a duplicate key. A wrong shape
+is not: the key is present but resolves to nothing, which is also what a key
+with an empty value does on purpose (the "Key present, value empty" row above),
+and `resolve_config` does not tell the two apart. When a setting seems ignored,
+check the structure of its key in the file: one scalar on the key's own line and
+no list under it. `/settings` shows the value that is actually in effect.
+
+Merging a repeated block and taking the last value of a repeated key are fixed
+rules here, but most other YAML tools keep only the last block. Combine repeated
+blocks rather than rely on the merge.
## Why not inject at session start
diff --git a/.claude/docs/coordination-rules.md b/.claude/docs/coordination-rules.md
index d2b9f8ef..b0ec85c3 100644
--- a/.claude/docs/coordination-rules.md
+++ b/.claude/docs/coordination-rules.md
@@ -11,6 +11,14 @@
`producer` agent coordinates the propagation.
5. **No Unilateral Cross-Domain Changes**: An agent must never modify files
outside its designated directories without explicit delegation.
+6. **Read Design Docs by Section**: A brief names the sections an agent needs
+ by heading. Find a heading in a GDD, ADR or the art bible with the Grep
+ tool (`^#`, content mode) and Read that range with offset and limit; read a doc
+ whole only when the task needs all of it, and say why. `validate-read.sh`
+ refuses a whole-file read of a doc over 40 KB.
+7. **Nothing Goes Upstream**: Never file, open or comment on an issue or pull
+ request in an engine, plugin or vendor repository, even when asked. Write a
+ draft (`/bug-report` drafts only) and the user submits it.
## Model Tier Assignment
@@ -28,8 +36,7 @@ costs more. The agent-side `model:` is a different mechanism, and is applied.
This project uses two distinct multi-agent patterns:
### Subagents (current, always active)
-Spawned via the `Agent` tool within a single Claude Code session (renamed from
-`Task` in Claude Code 2.1.63; `Task` still works as an alias). Used by all
+Spawned via the `Agent` tool within a single Claude Code session. Used by all
`team-*` skills and orchestration skills. Subagents share the session's
permission context, run sequentially or in parallel within the session, and
return results to the parent.
diff --git a/.claude/docs/directory-structure.md b/.claude/docs/directory-structure.md
index 384b2ead..b26476bf 100644
--- a/.claude/docs/directory-structure.md
+++ b/.claude/docs/directory-structure.md
@@ -16,7 +16,7 @@
├── production/ # Production management (sprints, milestones, releases)
│ ├── session-state/ # Ephemeral session state (active.md — gitignored)
│ └── session-logs/ # Session audit trail (gitignored)
-└── CCGS Skill Testing Framework/ # QA for the skills/agents themselves — /skill-test, /skill-improve
+└── studio-tests/ # QA for the skills/agents themselves — /skill-test, /skill-improve
```
## The code root is engine-specific
diff --git a/.claude/docs/effects-map.md b/.claude/docs/effects-map.md
index fc22895f..3e923322 100644
--- a/.claude/docs/effects-map.md
+++ b/.claude/docs/effects-map.md
@@ -124,6 +124,9 @@ The rule for deciding which side a setting belongs on:
| `performance.enforce` | Whether budget violations block your local work (CI enforces project defaults) |
| `features.session_state` | Your session tracking preference |
| `features.token_budget_warn_at` | Your personal cost threshold |
+| `features.read_guard` | Whether your whole-file reads of large design docs are refused |
+| `features.read_guard_kb` | The size over which they are |
+| `updates.check` | Whether you see the new-release line; turning it off for you leaves it on for teammates |
**Locked to `project.yaml`** (project-wide — would create artifact divergence if local):
@@ -398,7 +401,7 @@ These skills run the same way at `full`, `lean` and `solo`. None of them takes a
|-------|--------------------------|
| **review-all-gdds** | Phase 2 consistency pass and Phase 3 design-theory pass, in parallel |
| **architecture-review** | The primary engine specialist is consulted after the engine audit (recorded as NOT ASSESSED when no engine is configured) |
-| **dev-story** | Core programmer routing, plus the engine specialist when the story involves engine-specific APIs or patterns, and always when engine risk is HIGH |
+| **dev-story** | Core programmer routing, plus the engine specialist's check of every code story |
| **code-review** | Language, shader and UI specialists when an engine is configured, plus `qa-tester` for Logic and Integration stories |
| **security-audit** | `security-engineer` is spawned to run the audit |
@@ -458,7 +461,7 @@ pipeline's own review steps run in every mode.
**Default:** `minimal` — see the rationale block above `_yaml_helper_defaults`
in `.claude/hooks/yaml-helper.sh`. Short version: the heavier tier costs more to
reach working code without producing a better result.
-**Set by:** `/start` (Phase 3d), `/settings`
+**Set by:** `/start` (Phase 4: inferred from the user's description, shown, saved on a yes), `/settings`
**Read by:** nothing directly — it is read *through* the six knobs it supplies
**Priority chain:** `modes.rigor` in `project.yaml` → hardcoded default `minimal`
@@ -996,7 +999,7 @@ The list is a YAML list of these strings. Skills check whether the current decis
**Values:** `coarse` | `balanced` | `fine`
**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`
+**Read by:** `/create-stories`, `/sprint-plan`, `/sprint-status`, `/story-readiness`
**Priority chain:** `modes.story_granularity` in `project.yaml` → `modes.rigor` expansion → *(no hardcoded default)*
@@ -1016,11 +1019,8 @@ The list is a YAML list of these strings. Skills check whether the current decis
| Skill | coarse | balanced | fine |
|-------|--------|----------|------|
-| **create-epics** | Generates 3–5 child stories per epic | Generates 5–10 child stories per epic | Generates 10–20 child stories per epic |
| **create-stories** | Each story carries 5–10 ACs covering an entire feature | Each story carries 2–4 ACs covering one task | Each story carries 1 AC; story name = AC restatement |
-| **dev-story** | Routing prompt expects multi-day implementation cycle. Subagent given longer working context. | Standard 1–2 day expectation. | Each story implementable in hours; subagent given tighter context. |
| **sprint-plan** | Allocates 2–4 stories per sprint based on velocity. | Allocates 6–10 stories per sprint. | Allocates 15–25 stories per sprint. |
-| **story-done** | Fires every 3–5 days on average. | Fires every 1–2 days on average. | Fires multiple times per day. |
| **sprint-status** | Burn-down reads in feature-sized chunks. | Burn-down reads in task-sized chunks. | Burn-down reads in AC-sized chunks. |
---
@@ -1035,9 +1035,9 @@ The list is a YAML list of these strings. Skills check whether the current decis
**Priority chain:** `docs.density` in `project.yaml` → `modes.rigor` expansion → *(no hardcoded default)*
-> **Distinct from `workflow`, but no longer independent by default.** `workflow`
+> **Distinct from `workflow`, but not independent by default.** `workflow`
> controls which sections exist; `density` controls how deep each section goes.
-> `modes.rigor` now sets both together, so the diagonal (`rigor: full` → 8
+> `modes.rigor` sets both together, so the diagonal (`rigor: full` → 8
> sections *and* thorough prose) is what you get without asking. The off-diagonal
> is still reachable and is the reason `rigor` overrides both ways: `rigor: full`
> + an explicit `docs.density: terse` gives "all sections but each is compact" —
@@ -1189,14 +1189,14 @@ closing, or produces a warning and lets work continue — per test type
| Aspect | minimal | standard | full |
|--------|---------|----------|------|
-| Logic stories | No test required, no gap flagged | Unit test required (strict.logic controls block) | Unit test + coverage minimum |
+| Logic stories | No test required, no gap flagged | Unit test required (strict.logic controls block) | Unit test, and every acceptance criterion covered |
| Integration stories | No test required | Integration test or playtest doc required | Same + regression coverage |
| 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 |
+| Config/Data stories | No evidence required | Smoke check advisory | Smoke check required (blocking unless `testing.strict.config: false`) |
| /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 |
+| /dev-story routing prompt | No "Test required: ..." line | Per-type test requirement included | Per-type, and every criterion must be covered |
| Regression suite required by | Never | Polish stage | Production stage |
| Best for | Jam games, throwaway prototypes, fast iteration | Most projects | Commercial, console cert, learning, paranoid teams |
@@ -1206,9 +1206,9 @@ closing, or produces a warning and lets work continue — per test type
| Skill | minimal | standard | full |
|-------|---------|----------|------|
-| **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-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`; more than half the criteria untested blocks | Per-type evidence required; a Config/Data smoke report blocks by default; any untested criterion blocks |
| **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 |
+| **dev-story** | Routing prompt has no "Test required" line | Per-type test requirement passed to programmer agent | Per-type requirement, and every criterion must be covered by a test |
| **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 |
@@ -1741,7 +1741,7 @@ implementation, review, and architecture validation
| Skill | How engine.name is used |
|-------|------------------------|
-| **dev-story** | Routes code stories to language specialist. Spawns engine specialist alongside for HIGH engine-risk stories or engine-specific API usage. |
+| **dev-story** | Routes code stories to a programmer agent, then hands the changed files to the language specialist (the generic engine specialist when none is set) for an engine-API check. |
| **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. |
@@ -1945,9 +1945,8 @@ skeleton-first output files for recovery
**Values:** `off` | `on`
**Default:** `on`
**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`.
+**Read by:** Five hooks — `session-start.sh` (its recovery preview only),
+`pre-compact.sh`, `session-stop.sh`, `log-agent.sh` and `log-agent-stop.sh`. No skill reads it, and neither does `statusline.sh`.
> **`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
@@ -1980,7 +1979,7 @@ skeleton-first output files for recovery
| 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. 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. |
+| `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 five 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. |
---
@@ -1999,9 +1998,8 @@ skeleton-first output files for recovery
|------|--------------------|-------------------|
| **session-start.sh** | Runs normally (git/sprint context) — skips the `active.md` checkpoint preview | Runs fully, including the `active.md` checkpoint preview |
| **detect-gaps.sh** | Runs unchanged — gap detection is independent of session state | Runs unchanged |
-| **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.md` to `session-log.md` when it has changed, appends commits and uncommitted file names |
+| **pre-compact.sh** | No-op — exits silently (no compaction-log append) | Appends one line to `compaction-log.txt` and prints nothing (PreCompact output never reaches Claude; `session-start.sh` restores context) |
+| **session-stop.sh** | No-op — exits silently | Archives `active.md` to `session-log.md` when it has changed, appends commits and uncommitted file names, writes the spawn tally to `session-cost.md`; prints nothing |
| **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 |
@@ -2148,7 +2146,7 @@ the `<!-- CHECKPOINT -->` block; the others append a SESSION EXTRACT.
**Values:** float between 0.0 and 1.0
**Default:** `0.7` (warn at 70%)
**Set by:** `/settings`
-**Read by:** nothing yet (intended readers: `pre-compact.sh`, `session-start.sh`, `statusline.sh`)
+**Read by:** nothing yet (intended readers: `session-start.sh`, `statusline.sh`)
**Priority chain:** `features.token_budget_warn_at` in `project.yaml` → hardcoded default of `0.7`
@@ -2168,6 +2166,88 @@ the `<!-- CHECKPOINT -->` block; the others append a SESSION EXTRACT.
---
+## features.read_guard
+
+**Controls:** Whether a whole-file Read of a large design doc is refused
+**Values:** `on` | `off`; `true` and `false` also work
+**Default:** `on`
+**Set by:** `/settings`
+**Read by:** `validate-read.sh` (PreToolUse Read), through `.claude/scripts/read-guard.sh check`
+
+> **Priority chain:** `features.read_guard` in `project.local.yaml` →
+> `project.yaml` → default **`on`**.
+
+A Read with no offset and no limit of a file under `design/`, `docs/architecture/`
+or `production/session-state/` that is over `features.read_guard_kb` is refused.
+The refusal lists the doc's headings with their line numbers, so the next call
+reads one section with offset and limit. A ranged read always passes, so no skill
+can get stuck behind the guard; images and PDFs are never checked. It blocks
+rather than warns because a warning would let the whole read happen, and the
+read is the cost.
+
+---
+
+## features.read_guard_kb
+
+**Controls:** The size over which `features.read_guard` refuses a whole-file read
+**Values:** a whole number of KB (1 KB = 1,024 bytes)
+**Default:** `40`
+**Set by:** `/settings`
+**Read by:** `validate-read.sh`, through `.claude/scripts/read-guard.sh check`
+
+> **Priority chain:** `features.read_guard_kb` in `project.local.yaml` →
+> `project.yaml` → default **`40`**. A value that is not a whole number is
+> ignored, and `read-guard.sh check` names it on its `threshold` row.
+
+By file size, not lines: token cost follows bytes, and one table row can be 2 KB.
+40 KB is about 10,000 tokens and sits above every shipped template (the largest is
+33 KB).
+
+---
+
+## updates.check
+
+**Controls:** Whether session start tells you that a newer Claude Code Game
+Studios release is out
+**Values:** `true` | `false`
+**Default:** `true`
+**Set by:** `/settings` (`/settings --local updates.check=false` turns it off
+for you only)
+**Read by:** `session-start.sh`, through `update-check.sh`
+
+> When a newer release is out, session start shows one line: *"Update: Claude
+> Code Game Studios 1.3.0 is out (this project has 1.2.0). What changed and how
+> to upgrade: <release page> — to stop this notice: /settings --local
+> updates.check=false"*. Nothing is downloaded or changed; upgrading stays your
+> call (`UPGRADING.md`).
+
+> **Priority chain:** `updates.check` in `project.local.yaml` → `project.yaml` →
+> default **`true`**. A value other than `true` or `false` is skipped and named
+> in the session-start schema errors. The check is also off whenever the `CI`
+> environment variable is set: nobody reads session start there.
+
+---
+
+### How it checks
+
+- At most once a day, a background job asks GitHub for the latest release
+ (`api.github.com/repos/Donchitos/Claude-Code-Game-Studios/releases/latest`)
+ and stores the answer in `~/.cache/claude-code-game-studios/latest-release`
+ (under `$XDG_CACHE_HOME` when that is set). The file is per user and outside
+ every project, so `git status` stays clean and one check covers every project
+ on the machine.
+- Session start only reads that file. It makes no network call and never waits;
+ a new answer shows from the next session on.
+- Offline, or with neither `curl` nor `wget`, it stays silent. The cache keeps
+ the last answer, plus an `error=` line saying why the last check failed.
+- Pre-releases are never offered.
+- The version compared is the one the framework's own hook files carry, not
+ `framework.version`: an upgrade that keeps your `project.yaml` leaves that
+ number behind, and the line would announce the release you already have.
+- With `false`, nothing is read and nothing is requested.
+
+---
+
## schema_version
**Controls:** Which version of the project.yaml schema this file conforms to
@@ -2198,7 +2278,7 @@ the `<!-- CHECKPOINT -->` block; the others append a SESSION EXTRACT.
**Controls:** Tracks which CCGS version created or last touched this project
**Values:** `framework.version` (semver string) + `framework.last_upgraded` (ISO date)
**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
+**Set by:** the template; `/start` (through `set-stage.sh`), `/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'.)*
@@ -2208,8 +2288,8 @@ the `<!-- CHECKPOINT -->` block; the others append a SESSION EXTRACT.
```yaml
framework:
- version: "1.1.0"
- last_upgraded: "2026-05-14"
+ version: "1.2.0"
+ last_upgraded: "2026-10-18"
```
| Field | Purpose |
@@ -2315,8 +2395,8 @@ Godot project. Use this as the reference shape when authoring or migrating.
schema_version: 1
framework:
- version: "1.1.0"
- last_upgraded: "2026-05-15"
+ version: "1.2.0"
+ last_upgraded: "2026-10-18"
project:
name: "Forge Knights"
@@ -2377,7 +2457,7 @@ platform:
engine:
name: "Godot" # Godot | Unity | Unreal — set by /setup-engine
- version: "4.6"
+ version: "4.7"
language: "GDScript" # GDScript | C# | C++ | Blueprint
rendering: "Forward+"
physics: "Jolt"
@@ -2419,6 +2499,11 @@ commands: # simple string OR OS-aware map per command
features:
session_state: on # off | on
token_budget_warn_at: 0.7 # 0.0-1.0; warn at this context % usage
+ read_guard: on # on | off; true and false also work. Refuse whole-file reads of large design docs
+ read_guard_kb: 40 # the size, in KB, over which they are refused
+
+updates:
+ check: true # false: no new-release line at session start
```
And a minimal sparse `project.local.yaml` example — a single developer who wants autonomous mode locally:
diff --git a/.claude/docs/hooks-reference.md b/.claude/docs/hooks-reference.md
index 0645b940..64455889 100644
--- a/.claude/docs/hooks-reference.md
+++ b/.claude/docs/hooks-reference.md
@@ -5,21 +5,25 @@ Hooks are configured in `.claude/settings.json` and fire automatically:
| Hook | Event | Trigger | Action |
| ---- | ----- | ------- | ------ |
| `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-push.sh` | PreToolUse (Bash, PowerShell) | `git push`, `git tag`, `git merge` and release commands | Warns on pushes to protected branches (`main`, `master` and `release/*`), and on the steps that ask first: `git tag` (not a listing), `git merge` (not `--abort`), `gh release`, `butler push` and `steamcmd` with `+run_app_build`. Which commands count is `bash .claude/scripts/write-guard.sh git` |
+| `validate-registry.sh` | PreToolUse (Write/Edit) | Writes and edits of `design/registry/entities.yaml` and `docs/architecture/tr-registry.yaml` | Warns, and never blocks, when the change would delete or renumber an entry or set a status outside the values the file's header lists. It runs before the write, while the old file can still be compared; the check itself is `bash .claude/scripts/registry.sh compare`. The skills that write a registry also run `registry.sh validate` after writing, because hooks do not run in every tool |
+| `validate-write.sh` | PreToolUse (Write/Edit) | Writes and edits the rules below name | Warns, and never blocks, when a write would replace a file skills never overwrite (an existing `EPIC.md`, `project.godot`, `tests/helpers/*`, the tech-debt register, an engine reference doc, the files `/test-setup` creates), set a config value outside its list or a key `project.local.yaml` cannot hold, set the review mode, leave a prototype file without its `PROTOTYPE` or `VERTICAL SLICE` header or reach between `prototypes/` and the code root, change a string table during an active freeze, or, from a subagent, write anything but a new file under `production/`, `docs/` or `tests/`. The check is `bash .claude/scripts/write-guard.sh check`, which the skills that write these files also run themselves |
+| `validate-read.sh` | PreToolUse (Read) | A Read with no offset and no limit under `design/`, `docs/architecture/` or `production/session-state/` | Blocks a whole-file read of a doc over 40 KB (`features.read_guard_kb`) and answers with the doc's headings by line, so the retry reads one section; a ranged read always passes. `features.read_guard: off` turns it off. The check is `bash .claude/scripts/read-guard.sh check` |
+| `validate-agent-artifact.sh` | SubagentStop | A subagent stops | Warns you, and never blocks, when the file its return contract named ("Write your full output to `<path>`") is not on disk, a failed phase however its reply reads. Shown to you only: on this event, text for Claude would keep the subagent running |
| `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 |
+| `session-start.sh` | SessionStart | Session begins | Loads sprint context, milestone, git activity; detects and previews active session state file for recovery, with one line when its checkpoint names a different branch from the one you are on; one line when a newer release is out, from a cache `update-check.sh` refreshes in the background at most once a day (`updates.check` in `effects-map.md`) |
| `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 | 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. |
+| `pre-compact.sh` | PreCompact | Context compression | Appends one line to `production/session-logs/compaction-log.txt` and prints nothing: Claude Code does not add PreCompact output to the conversation. `session-start.sh`, which runs again after every compaction, is what restores context |
+| `notify.sh` | Notification (`permission_prompt`, `idle_prompt`) | Claude is waiting on a permission prompt, or has been idle about a minute | Shows Windows toast notification via PowerShell |
+| `session-stop.sh` | Stop, async | **Every response ends** — not once per session | Updates the session log and writes the subagent spawn tally to `production/session-logs/session-cost.md`; prints nothing. Archives `active.md` only when its content hash changed; without that guard a long session appended the whole file on every turn. Runs in the background, so the turn does not wait for it; under `claude -p` it is cancelled if still running when the session ends |
| `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
+Warnings from the `validate-*` hooks are shown to you and passed to Claude (only
+to you from `validate-agent-artifact.sh`)
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
+now exits 2, and the read guard's refusal. See `hooks-reference/hook-input-schemas.md` for why stderr is not
enough.
### Subagent cost visibility
@@ -33,12 +37,12 @@ YYYYMMDD_HHMMSS | <session_id> | Agent invoked: <agent_type>
`session-stop.sh` greps the literal string `" | $SESSION_ID | Agent invoked: "`
to tally the current session, then writes a count plus a per-agent breakdown to
-`production/session-logs/session-cost.md` and echoes a one-line total.
+`production/session-logs/session-cost.md`.
The field order of that record is fixed. `session-stop.sh` matches it literally,
so a different order silently zeroes the spawn count instead of raising an error.
-When the hook input has no session id, `session-stop.sh` prints no total. A
+When the hook input has no session id, `session-stop.sh` writes no total. A
total spanning every session in the log would look plausible and be wrong, which
is worse than none.
@@ -47,7 +51,7 @@ is worse than none.
## Events considered and deliberately not added
-Claude Code offers many more hook events than the nine the hooks above use. These were
+Claude Code offers many more hook events than the eight the hooks above use. These were
evaluated and not adopted, for the reasons given.
| Event | Why not |
@@ -58,6 +62,7 @@ evaluated and not adopted, for the reasons given.
| `PreToolUse` `updatedInput` | Could rewrite a non-conventional commit message instead of blocking it. Silently editing the user's input contradicts the collaboration protocol: this project blocks and explains rather than acting unasked. |
| `PostToolUseFailure` | Would add another log with no reader. |
| `SessionEnd` | `session-stop.sh` stays on `Stop`. `SessionEnd` fires on termination, which a crash may never reach, and the content-hash guard already makes the per-response firing cheap. |
+| `PostCompact` | Its output and `systemMessage` never reach Claude, and `session-start.sh` already restores context after a compaction. A hook here would only cost a process start per compaction. |
| `InstructionsLoaded` | Useful for debugging which CLAUDE.md and rules files actually loaded, but it is a diagnostic, not a project requirement. Wire it in your own `.claude/settings.local.json` when you need it rather than paying for it on every load. |
Hook reference documentation: `.claude/docs/hooks-reference/`
diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.md
index 4be68683..44f80f9c 100644
--- a/.claude/docs/quick-start.md
+++ b/.claude/docs/quick-start.md
@@ -13,8 +13,8 @@ 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:
+`modes.rigor` defaults to `minimal` (`/start` infers it from what you describe and shows it
+before saving; `/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
@@ -248,7 +248,7 @@ If you already know what you need, jump directly to the relevant path:
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. **Prototype the mechanic** — Run `/prototype [core-mechanic]` (1–3 days) to
+4. **Prototype the mechanic** — Run `/prototype [core-mechanic]` (1 day at most) to
test that the core idea is fun before you write GDDs
5. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies
6. **Design each system** — Run `/design-system [system-name]` (or `/map-systems next`)
@@ -261,7 +261,7 @@ If you already know what you need, jump directly to the relevant path:
If you already have a game concept and engine choice:
1. **Set up the engine** — Run `/setup-engine [engine] [version]`
- (e.g., `/setup-engine godot 4.6`) — also creates technical preferences
+ (e.g., `/setup-engine godot 4.7`) — also creates technical preferences
2. **Write the Game Pillars** — delegate to `creative-director`
3. **Decompose into systems** — Run `/map-systems` to enumerate systems and dependencies
4. **Design each system** — Run `/design-system [system-name]` for GDDs in dependency order
@@ -301,8 +301,8 @@ project.yaml -- Machine-readable project config (engine, m
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/ -- 13 path-specific rule files
+ hooks/ -- 15 event hooks (.sh, wired by settings.json) + yaml-helper.sh, update-check.sh
+ rules/ -- 14 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)
@@ -314,5 +314,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/ -- 39 document templates (+ per-section guidance)
+ templates/ -- 62 document templates (+ per-section guidance)
```
diff --git a/.claude/docs/rules-reference.md b/.claude/docs/rules-reference.md
index 509b26a2..e02ed917 100644
--- a/.claude/docs/rules-reference.md
+++ b/.claude/docs/rules-reference.md
@@ -50,6 +50,7 @@ each rule's own globs list the case variants (`{AI,Ai,ai}`).
| `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/**`, `**/*.gdshader` · `Assets/**/*.{shader,hlsl,cginc,compute,shadergraph}` · `Shaders/**`, `**/*.{usf,ush}` | Naming conventions, performance targets, cross-platform rules |
+| `scene-files.md` | `**/*.tscn`, `**/*.tres` · `**/*.unity`, `**/*.prefab`, `Assets/**/*.asset` · — | Hand-edit limits for editor-written scene and asset files; Unreal `.uasset`/`.umap` are binary, and `settings.json` denies edits to them |
| `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 must be able to report that it did not run — the five obligations for verdicts, defaults, skips, sourcing and derived coverage |
@@ -63,6 +64,8 @@ Each engine-facing rule loads on all three engines:
- **`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}`.
+- **`scene-files.md`** is the exception: Godot and Unity scene and asset files are text and have
+ rules; Unreal's are binary, so a deny rule blocks edits instead of a rule guiding them.
> **`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**
diff --git a/.claude/docs/run-and-observe.md b/.claude/docs/run-and-observe.md
index ee7f63f7..a079c380 100644
--- a/.claude/docs/run-and-observe.md
+++ b/.claude/docs/run-and-observe.md
@@ -33,10 +33,16 @@ engine has a native way.
4. **Look.** `Read` the PNG. Compare what is on screen to the acceptance
criteria. Clipped text, an overflowing panel, a missing element, the wrong
colour — these are defects, and this is the only step that finds them.
-5. **Retain.** Copy the image to
- `production/qa/evidence/[story-slug]/[NN]-[what-it-shows].png` and reference
- it from the evidence doc. A screenshot that was taken and discarded is an
- assertion, not evidence.
+5. **Retain.** Capture straight into the story's evidence folder, so nothing
+ needs copying: `mkdir -p production/qa/evidence/[story-slug]`, then pass
+ `production/qa/evidence/[story-slug]/[NN]-[what-it-shows].png` as the capture
+ path (Godot adds its frame number to the name). `[story-slug]` is the story
+ file's name without `.md`: `story-003-light-pickup` for
+ `production/epics/core/story-003-light-pickup.md`. Reference the image from
+ the evidence doc. A screenshot that was taken and discarded is an
+ assertion, not evidence. Beside it, stamp the files it proves:
+ `bash .claude/scripts/review-receipts.sh hash <each file the story changed> > production/qa/evidence/[story-slug]/stamp.txt`.
+ A later edit to one of them then shows the evidence as older than the code.
6. **Report** one `Run result:` line in the implementation summary — vocabulary
below.
@@ -57,8 +63,13 @@ godot --path . --windowed --resolution 1280x720 --write-movie shots/shop.png --q
`--write-movie` is Movie Maker mode: with a `.png` target it writes a frame
sequence and `--quit-after` sets the frame count. Filenames carry **8**
zero-padded digits — `shop00000000.png` through `shop00000059.png` — so take the
-last. `--fixed-fps` is applied automatically. The scene path is positional; any
-`.tscn` can be launched directly, which is how step 2 is satisfied.
+last; a `shop.wav` lands beside them. `--fixed-fps` is applied automatically. The
+scene path is positional; any `.tscn` can be launched directly, which is how step
+2 is satisfied. The frames are recorded at the project's viewport size
+(`display/window/size/viewport_width` and `_height`, 1152x648 when unset), not at
+`--resolution`, which only sizes the window; the log's `recording movie in
+<W>×<H>` line says which. The capture-on-trigger alternative below saves at the
+window size.
Capture-on-trigger alternative, for a state a scene launch cannot reach: an
autoload that on the wanted condition does
@@ -223,7 +234,8 @@ engine on this machine". Absence of a path is not absence of an engine.
---
-*Commands above were run on Windows with Godot 4.6.1 (gdUnit4 6.1.3), Unity
+*Commands above were run on Windows with Godot 4.6.1 (gdUnit4 6.1.3) and the
+Godot ones again on 4.7.2 (gdUnit4 6.2.2), 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
diff --git a/.claude/docs/settings-guidance.md b/.claude/docs/settings-guidance.md
index c3c13919..fa4e39bc 100644
--- a/.claude/docs/settings-guidance.md
+++ b/.claude/docs/settings-guidance.md
@@ -72,8 +72,8 @@ rigor; want that?"). If the user has **no concept yet** (exploring), do not seed
"No concept yet" means **no signal**, not a particular onboarding path. A rough
one-line hint is still a description: if it trips the signals above, seed from the
signal. Only fall back to `minimal`-for-exploring when the user has given you
-nothing to map. (`/start` Phase 3d states the same rule for its Path A/B branch;
-both drive the same recommendation.)
+nothing to map. (`/start` Phase 4 applies the same rule when it infers rigor for its
+Path A/B branch.)
---
@@ -100,7 +100,7 @@ state is needed — but never emit the same suggestion twice in one session.
| Skill | Moment | Sections used |
|---|---|---|
-| `/start` | Phase 3d/4 — choosing rigor | § 2 (presets), § 3 (seed from concept) |
+| `/start` | Phase 4 — inferring rigor for the card | § 2 (presets), § 3 (seed from concept) |
| `/help` | escalation footer when user sounds stuck/overwhelmed | § 4 (lower trigger) |
| `/gate-check` | on PASS into a new stage | § 4 (raise trigger) |
| `/settings` | view output — further reading | § 2 (choosing a value) |
diff --git a/.claude/docs/settings-local-template.md b/.claude/docs/settings-local-template.md
index 487be2ca..26407367 100644
--- a/.claude/docs/settings-local-template.md
+++ b/.claude/docs/settings-local-template.md
@@ -1,7 +1,7 @@
# settings.local.json Template
Create `.claude/settings.local.json` for personal overrides that should NOT
-be committed to version control. Add it to `.gitignore`.
+be committed to version control. The shipped `.gitignore` already ignores it.
## Example settings.local.json
@@ -9,39 +9,55 @@ be committed to version control. Add it to `.gitignore`.
{
"permissions": {
"allow": [
- "Bash(git *)",
- "Bash(npm *)",
- "Read",
- "Glob",
- "Grep"
+ "Bash(git add *)",
+ "Bash(git commit *)",
+ "Bash(npm run *)"
],
"deny": [
- "Bash(rm -rf *)",
- "Bash(git push --force *)"
+ "Bash(git push *)"
]
}
}
```
+Put the `*` after the subcommand. `Bash(git commit *)` allows only commits;
+`Bash(git *)` would allow every git command, `git push` included. Read-only
+commands such as `git status`, `git log` and `ls` need no rule: Claude Code runs
+them without asking. Your rules add to the shipped ones in
+`.claude/settings.json`, so its deny rules still apply.
+
## Permission Modes
-Claude Code supports different permission modes. Recommended for game dev:
+Claude Code has several permission modes. The shipped `.claude/settings.json`
+starts terminal sessions in `default`; to start in another, set
+`permissions.defaultMode` here. "One setting CCGS does ship" in
+`setup-requirements.md` lists what that can and cannot change. You can also
+switch during a session. Suggested for game dev:
+
+### During Development — Manual (`default`)
+Claude asks before running most commands and before editing files. This is the
+safest for production code.
-### During Development (Default)
-Use **normal mode** — Claude asks before running most commands. This is safest
-for production code.
+### During Prototyping — `acceptEdits`
+File edits and common filesystem commands such as `mkdir` and `mv` are accepted
+without asking; other commands still ask. It applies to the whole working
+directory, not only `prototypes/`, so switch back when you return to production
+code.
-### During Prototyping
-Use **auto-accept mode** with limited scope — faster iteration on throwaway code.
-Only use this when working in `prototypes/` directory.
+### During Code Review — `plan`
+Claude reads files and runs read-only commands to explore, but does not edit
+your source files.
-### During Code Review
-Use **read-only** permissions — Claude can read and search but not modify files.
+### `auto`
+Runs without routine prompts: a background classifier checks each action before
+it runs. A local `defaultMode` cannot start a terminal session in it; switch
+during the session instead (`setup-requirements.md` lists the routes).
## Customizing Hooks Locally
You can add personal hooks in `settings.local.json` that extend (not override)
-the project hooks. For example, adding a notification when builds complete:
+the project hooks. For example, a personal log line each time Claude finishes a
+response:
```json
{
@@ -52,7 +68,7 @@ the project hooks. For example, adding a notification when builds complete:
"hooks": [
{
"type": "command",
- "command": "bash -c 'echo Session ended at $(date)'",
+ "command": "bash -c 'echo \"Response finished at $(date)\" >> \"$CLAUDE_PROJECT_DIR/production/session-logs/my-stops.log\"'",
"timeout": 5
}
]
@@ -61,3 +77,9 @@ the project hooks. For example, adding a notification when builds complete:
}
}
```
+
+A hook's output reaches Claude for only a few events, such as `SessionStart`
+and `UserPromptSubmit`. For the others, including `Stop`, Claude Code writes
+stdout to the debug log, so a hook that only prints shows nothing: write to a
+file, as above, or to another tool. `Stop` fires at the end of every response,
+not once per session.
diff --git a/.claude/docs/templates/accessibility-requirements.md b/.claude/docs/templates/accessibility-requirements.md
index d189dcb9..e9ccec2a 100644
--- a/.claude/docs/templates/accessibility-requirements.md
+++ b/.claude/docs/templates/accessibility-requirements.md
@@ -1,10 +1,10 @@
-# Accessibility Requirements: [Game Title]
+# Accessibility Requirements
> 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
+> **Status**: [In Design | Committed | Audited | Certified]
> **Author**: [user + ux-designer]
-> **Last Updated**: [Date]
+> **Last Updated**: [today's date]
> **Accessibility Tier Target**: [Basic / Standard / Comprehensive / Exemplary]
> **Platform(s)**: [PC / Xbox / PlayStation 5 / Nintendo Switch / iOS / Android]
> **External Standards Targeted**:
@@ -15,6 +15,7 @@
> - Apple / Google Accessibility Guidelines [Yes / No / N/A — mobile only]
> **Accessibility Consultant**: [Name and organization, or "None engaged"]
> **Linked Documents**: `design/gdd/systems-index.md`, `design/ux/interaction-patterns.md`
+> **Template**: Accessibility Requirements
> **Why this document exists**: Per-screen accessibility annotations belong in
> UX specs. This document captures the project-wide accessibility commitments,
@@ -33,6 +34,8 @@
## Accessibility Tier Definition
+[To be designed]
+
### Tier Definitions
| Tier | Core Commitment | Typical Effort |
@@ -58,6 +61,8 @@
## Visual Accessibility
+[To be designed]
+
| Feature | Target Tier | Scope | Status | Implementation Notes |
|---------|-------------|-------|--------|---------------------|
| Minimum text size — menu UI | Standard | All menu screens | Not Started | 24px minimum at 1080p. At 4K, scale proportionally. Reference: WCAG 2.1 SC 1.4.4 requires text resizable to 200% without loss of content. |
@@ -93,6 +98,8 @@
## Motor Accessibility
+[To be designed]
+
| Feature | Target Tier | Scope | Status | Implementation Notes |
|---------|-------------|-------|--------|---------------------|
| Full input remapping | Standard | All gameplay inputs, all platforms | Not Started | Every input bound by default must be rebindable. Remapping applies to keyboard, mouse, controller, and any supported peripheral independently. No two actions may be bound to the same input simultaneously (warn on conflict). Persist remapping to player profile. |
@@ -110,6 +117,8 @@
## Cognitive Accessibility
+[To be designed]
+
| Feature | Target Tier | Scope | Status | Implementation Notes |
|---------|-------------|-------|--------|---------------------|
| Difficulty options | Standard | All gameplay difficulty parameters | Not Started | Separate granular sliders where possible (damage dealt, damage received, enemy aggression, enemy speed) rather than a single Easy/Normal/Hard label. Document which parameters are adjustable and which are fixed. Fixed parameters require a design justification. |
@@ -125,6 +134,8 @@
## Auditory Accessibility
+[To be designed]
+
| Feature | Target Tier | Scope | Status | Implementation Notes |
|---------|-------------|-------|--------|---------------------|
| Subtitles for all spoken dialogue | Basic | All voiced content | Not Started | 100% coverage — no exceptions. Include narration, in-engine dialogue, radio/environmental dialogue heard from a distance. Test subtitle sync against voice acting timing. |
@@ -148,6 +159,8 @@
## Platform Accessibility API Integration
+[To be designed]
+
| Platform | API / Standard | Features Planned | Status | Notes |
|----------|---------------|-----------------|--------|-------|
| Xbox (GDK) | Xbox Game Core Accessibility / XAG | [Input remapping via Xbox Ease of Access, high contrast support, narrator integration for menus] | Not Started | XAG compliance is required for ID@Xbox Game Pass consideration. Review XAG checklist at https://docs.microsoft.com/gaming/accessibility/guidelines |
@@ -161,6 +174,8 @@
## Per-Feature Accessibility Matrix
+[To be designed]
+
> When a new system is added to systems-index.md, a row must be added here. If a
> system has an unaddressed accessibility concern, it cannot be marked Approved
> in the systems index. See guide for example rows.
@@ -173,6 +188,8 @@
## Accessibility Test Plan
+[To be designed]
+
| Feature | Test Method | Test Cases | Pass Criteria | Responsible | Status |
|---------|------------|------------|--------------|-------------|--------|
| Text contrast ratios | Automated — contrast analyzer tool on all UI screenshots | All text/background combinations at all game states | All body text ≥ 4.5:1; all large text ≥ 3:1; subtitle backgrounds ≥ 7:1 | ux-designer | Not Started |
@@ -189,6 +206,8 @@
## Known Intentional Limitations
+[To be designed]
+
> Every entry here is a risk — assess it honestly. See guide for example rows.
| Feature | Tier Required | Why Not Included | Risk / Impact | Mitigation |
@@ -199,6 +218,8 @@
## Audit History
+[To be designed]
+
> See guide for example rows.
| Date | Auditor | Type | Scope | Findings Summary | Status |
@@ -209,6 +230,8 @@
## External Resources
+[To be designed]
+
| Resource | URL | Relevance |
|----------|-----|-----------|
| WCAG 2.1 (Web Content Accessibility Guidelines) | https://www.w3.org/TR/WCAG21/ | Foundational accessibility standard — contrast ratios, text sizing, input requirements |
@@ -224,6 +247,8 @@
## Open Questions
+[To be designed]
+
| Question | Owner | Deadline | Resolution |
|----------|-------|----------|-----------|
| [Add question] | [Owner] | [Deadline] | [Resolution] |
diff --git a/.claude/docs/templates/adoption-plan.md b/.claude/docs/templates/adoption-plan.md
new file mode 100644
index 00000000..0ac5bbbf
--- /dev/null
+++ b/.claude/docs/templates/adoption-plan.md
@@ -0,0 +1,79 @@
+# Adoption Plan
+
+> **Generated**: [date]
+> **Project phase**: [phase]
+> **Engine**: [name + version, or "Not configured"]
+> **Template version**: v1.0+
+
+Work through these steps in order. Check off each item as you complete it.
+Re-run `/adopt` anytime to check remaining gaps.
+
+---
+
+## Step 1: Fix Blocking Gaps
+
+[One sub-section per blocking gap with problem, fix command, time estimate, checkbox]
+
+---
+
+## Step 2: Fix High-Priority Gaps
+
+[One sub-section per high gap]
+
+---
+
+## Step 3: Bootstrap Infrastructure
+
+[At `workflow: minimal`, replace 3a–3d with one line: "Not on the minimal path —
+the brief's build order is the plan. Next: `/create-stories` (or `/dev-story`
+once stories exist)."]
+
+### 3a. Register existing requirements (creates tr-registry.yaml)
+Run `/architecture-review` — even if ADRs already exist, this run bootstraps
+the TR registry from your existing GDDs and ADRs.
+**Time**: 1 session (review can be long for large codebases)
+- [ ] tr-registry.yaml created
+
+### 3b. Create control manifest
+Run `/create-control-manifest`
+**Time**: 30 min
+- [ ] docs/architecture/control-manifest.md created
+
+### 3c. Create sprint tracking file
+Run `/sprint-plan update`
+**Time**: 5 min (if sprint plan already exists as markdown)
+- [ ] production/sprint-status.yaml created
+
+### 3d. Set authoritative project stage
+Run `/gate-check [current-phase]` (the gate into the phase the project is in;
+at Concept there is none — Concept is the default stage, nothing to run)
+**Time**: 5 min
+- [ ] `project.stage` in `project.yaml` written (legacy `production/stage.txt` also updated)
+
+---
+
+## Step 4: Medium-Priority Gaps
+
+[One sub-section per medium gap]
+
+---
+
+## Step 5: Optional Improvements
+
+[One sub-section per low gap]
+
+---
+
+## What to Expect from Existing Stories
+
+Existing stories continue to work with all template skills. New format checks
+(TR-ID validation, manifest version staleness) auto-pass when the fields are
+absent — so nothing breaks. They won't benefit from staleness tracking until
+regenerated. Do not regenerate stories that are in progress or done.
+
+---
+
+## Re-run
+
+Run `/adopt` again after completing Step 3 to verify all blocking and high gaps
+are resolved. The new run will reflect the current state of the project.
diff --git a/.claude/docs/templates/adoption-summary.md b/.claude/docs/templates/adoption-summary.md
new file mode 100644
index 00000000..c4469c79
--- /dev/null
+++ b/.claude/docs/templates/adoption-summary.md
@@ -0,0 +1,14 @@
+## Adoption Audit Summary
+Phase detected: [phase]
+Engine: [configured / NOT CONFIGURED]
+GDDs audited: [N] ([X] fully compliant, [Y] with gaps)
+ADRs audited: [N] ([X] fully compliant, [Y] with gaps)
+Stories audited: [N]
+
+Gap counts:
+ BLOCKING: [N] — template skills will malfunction without these fixes
+ HIGH: [N] — unsafe to run /create-stories or /story-readiness
+ MEDIUM: [N] — quality degradation
+ LOW: [N] — optional improvements
+
+Estimated remediation: [X blocking items × ~Y min each = roughly Z hours]
diff --git a/.claude/docs/templates/architecture-decision-record.md b/.claude/docs/templates/architecture-decision-record.md
index 147f1225..9638b4de 100644
--- a/.claude/docs/templates/architecture-decision-record.md
+++ b/.claude/docs/templates/architecture-decision-record.md
@@ -18,13 +18,13 @@
## Date
-[YYYY-MM-DD — when this ADR was written]
+[Date of decision]
## Last Verified
[YYYY-MM-DD — when this ADR was last confirmed accurate against the current
-engine version and design. Update this date when you re-read and confirm it
-is still correct, even if nothing changed.]
+engine version and design. Update this date when you re-read and confirm it is
+still correct, even if nothing changed.]
## Decision Makers
@@ -33,21 +33,21 @@ is still correct, even if nothing changed.]
## Summary
[2 sentences: what problem this ADR solves, and what was decided. Written for
-tiered context loading — a skill scanning 20 ADRs uses this to decide whether
-to read the full decision. Be specific: name the system, the problem, and the
+tiered context loading — a skill scanning 20 ADRs uses this to decide whether to
+read the full decision. Be specific: name the system, the problem, and the
chosen approach.]
## Engine Compatibility
| Field | Value |
|-------|-------|
-| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.7] |
-| **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input / Scripting] |
+| **Engine** | [e.g. Godot 4.7] |
+| **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input] |
| **Layer** | [Foundation / Core / Feature / Presentation] |
-| **Knowledge Risk** | [LOW — in training data / MEDIUM — near cutoff, verify / HIGH — post-cutoff, must verify] |
-| **References Consulted** | [e.g. `docs/engine-reference/godot/modules/physics.md`, `breaking-changes.md`] |
-| **Post-Cutoff APIs Used** | [Specific APIs from post-cutoff engine versions this decision depends on, or "None"] |
-| **Verification Required** | [Concrete behaviours to test against the target engine version before shipping, or "None"] |
+| **Knowledge Risk** | [LOW / MEDIUM / HIGH — from VERSION.md] |
+| **References Consulted** | [List engine-reference docs read, e.g. `docs/engine-reference/godot/modules/physics.md`] |
+| **Post-Cutoff APIs Used** | [Any APIs from post-LLM-cutoff versions this decision depends on, or "None"] |
+| **Verification Required** | [Specific behaviours to test before shipping, or "None"] |
> **Note**: If Knowledge Risk is MEDIUM or HIGH, this ADR must be re-validated if the
> project upgrades engine versions. Flag it as "Superseded" and write a new ADR.
@@ -79,110 +79,68 @@ chosen approach.]
## Context
### Problem Statement
-
-[What problem are we solving? Why must this decision be made now? What is the
-cost of not deciding?]
+[What problem are we solving? Why does this decision need to be made now?]
### Current State
-
[How does the system work today? What is wrong with the current approach?]
### Constraints
-
-- [Technical constraints -- engine limitations, platform requirements]
-- [Timeline constraints -- deadline pressures, dependencies]
-- [Resource constraints -- team size, expertise available]
-- [Compatibility requirements -- must work with existing systems]
+- [Technical constraints]
+- [Timeline constraints]
+- [Resource constraints]
+- [Compatibility requirements]
### Requirements
-
-- [Functional requirement 1]
-- [Functional requirement 2]
-- [Performance requirement -- specific, measurable]
-- [Scalability requirement]
+- [Must support X]
+- [Must perform within Y budget]
+- [Must integrate with Z]
## Decision
-[The specific technical decision, described in enough detail for someone to
-implement it without further clarification.]
-
-### Architecture
+[The specific technical decision made, described in enough detail for someone
+to implement it.]
-```
-[ASCII diagram showing the system architecture this decision creates.
-Show components, data flow direction, and key interfaces.]
-```
+### Architecture Diagram
+[ASCII diagram or description of the system architecture this creates]
### Key Interfaces
-
-```
-[Pseudocode or language-specific interface definitions that this decision
-creates. These become the contracts that implementers must respect.]
-```
+[API contracts or interface definitions this decision creates]
### Implementation Guidelines
-
-[Specific guidance for the programmer implementing this decision.]
+[Specific guidance for the programmer implementing this decision — the rules a
+`/create-control-manifest` or `/dev-story` run should follow. State mandates as
+"must / must never" so they extract cleanly.]
## Alternatives Considered
### Alternative 1: [Name]
-
-- **Description**: [How this approach would work]
-- **Pros**: [What is good about this approach]
-- **Cons**: [What is bad about this approach]
-- **Estimated Effort**: [Relative effort compared to chosen approach]
+- **Description**: [How this would work]
+- **Pros**: [Advantages]
+- **Cons**: [Disadvantages]
+- **Estimated Effort**: [Relative effort compared to the chosen approach]
- **Rejection Reason**: [Why this was not chosen]
### Alternative 2: [Name]
-
-[Same structure as above]
+- **Description**: [How this would work]
+- **Pros**: [Advantages]
+- **Cons**: [Disadvantages]
+- **Estimated Effort**: [Relative effort compared to the chosen approach]
+- **Rejection Reason**: [Why this was not chosen]
## Consequences
### Positive
-
- [Good outcomes of this decision]
### Negative
-
-- [Trade-offs and costs we are accepting]
+- [Trade-offs and costs accepted]
### Neutral
-
- [Changes that are neither good nor bad, just different]
## Risks
-
-| Risk | Probability | Impact | Mitigation |
-|------|------------|--------|-----------|
-
-## Performance Implications
-
-| Metric | Before | Expected After | Budget |
-|--------|--------|---------------|--------|
-| CPU (frame time) | [X]ms | [Y]ms | [Z]ms |
-| Memory | [X]MB | [Y]MB | [Z]MB |
-| Load Time | [X]s | [Y]s | [Z]s |
-| Network (if applicable) | [X]KB/s | [Y]KB/s | [Z]KB/s |
-
-## Migration Plan
-
-[If this changes existing systems, the step-by-step plan to migrate.]
-
-1. [Step 1 -- what changes, what breaks, how to verify]
-2. [Step 2]
-3. [Step 3]
-
-**Rollback plan**: [How to revert if this decision proves wrong]
-
-## Validation Criteria
-
-[How we will know this decision was correct after implementation.]
-
-- [ ] [Measurable criterion 1]
-- [ ] [Measurable criterion 2]
-- [ ] [Performance criterion]
+- [Things that could go wrong]
+- [Mitigation for each risk]
## GDD Requirements Addressed
@@ -190,15 +148,29 @@ creates. These become the contracts that implementers must respect.]
requirement, or explicitly state it is a foundational decision with no GDD
dependency. Traceability is audited by /architecture-review. -->
-| GDD Document | System | Requirement | How This ADR Satisfies It |
-|-------------|--------|-------------|--------------------------|
-| [e.g. `design/gdd/combat.md`] | [e.g. Combat] | [e.g. "Hitbox detection must resolve within 1 frame"] | [e.g. "Jolt physics collision queries run synchronously in _physics_process"] |
+| GDD System | Requirement | How This ADR Addresses It |
+|------------|-------------|--------------------------|
+| [system-name].md | [specific rule, formula, or performance constraint from that GDD] | [how this decision satisfies it] |
> If this is a foundational decision with no direct GDD dependency, write:
> "Foundational — no GDD requirement. Enables: [list what GDD systems this
> decision unlocks or constrains]"
-## Related
+## Performance Implications
+- **CPU**: [Expected impact]
+- **Memory**: [Expected impact]
+- **Load Time**: [Expected impact]
+- **Network**: [Expected impact, if applicable]
-- [Link to related ADRs — note if supersedes, contradicts, or depends on]
-- [Link to relevant code files once implemented]
+## Migration Plan
+[If this changes existing code, how do we get from here to there?]
+
+**Rollback plan**: [How to revert if this decision proves wrong]
+
+## Validation Criteria
+[How will we know this decision was correct? What metrics or tests?]
+
+## Related
+- [Links to related ADRs — note if supersedes, contradicts, or depends on]
+- [Links to related design documents]
+- [Links to relevant code files once implemented]
diff --git a/.claude/docs/templates/architecture-traceability.md b/.claude/docs/templates/architecture-traceability.md
index 78b9bf01..ed119210 100644
--- a/.claude/docs/templates/architecture-traceability.md
+++ b/.claude/docs/templates/architecture-traceability.md
@@ -6,7 +6,7 @@
## Document Status
- **Last Updated**: [YYYY-MM-DD]
-- **Engine**: [e.g. Godot 4.6]
+- **Engine**: [e.g. Godot 4.7]
- **GDDs Indexed**: [N]
- **ADRs Indexed**: [M]
- **Last Review**: [link to docs/architecture/architecture-review-[date].md]
@@ -31,8 +31,8 @@
| Req ID | GDD | System | Requirement Summary | ADR(s) | Status | Notes |
|--------|-----|--------|---------------------|--------|--------|-------|
-| TR-[gdd]-001 | [filename] | [system name] | [one-line summary] | [ADR-NNNN] | ✅ | |
-| TR-[gdd]-002 | [filename] | [system name] | [one-line summary] | — | ❌ GAP | Needs `/architecture-decision [title]` |
+| TR-[system]-001 | [filename] | [system name] | [one-line summary] | [ADR-NNNN] | ✅ | |
+| TR-[system]-002 | [filename] | [system name] | [one-line summary] | — | ❌ GAP | Needs `/architecture-decision [title]` |
---
diff --git a/.claude/docs/templates/bug-closure-record.md b/.claude/docs/templates/bug-closure-record.md
new file mode 100644
index 00000000..9b9ee699
--- /dev/null
+++ b/.claude/docs/templates/bug-closure-record.md
@@ -0,0 +1,8 @@
+## Closure Record
+**Closed**: [date]
+**Resolution**: Fixed — [one-line description of what was changed]
+**Fix commit / PR**: [if known]
+**Verified by**: [the verify record's `**Verified by**:` line — the test that ran and passed, or "[user], manual, build [X]"]
+**Closed by**: [user]
+**Regression test**: [test file path, or "Manual verification" when verify recorded a manual play]
+**Status**: Closed
diff --git a/.claude/docs/templates/bug-report.md b/.claude/docs/templates/bug-report.md
new file mode 100644
index 00000000..15d2588b
--- /dev/null
+++ b/.claude/docs/templates/bug-report.md
@@ -0,0 +1,47 @@
+# Bug Report
+
+## Summary
+**Title**: [Concise, descriptive title]
+**ID**: BUG-[NNNN]
+**Severity**: [S1-Critical / S2-High / S3-Medium / S4-Low]
+**Priority**: [P1-Fix this sprint / P2-Fix soon / P3-Backlog / P4-Won't fix]
+**Status**: Open
+**Reported**: [Date]
+**Reporter**: [the reporter's name as the user gives it, else `—`; never an email address or account ID taken from the session]
+
+## Classification
+- **Category**: [Gameplay / UI / Audio / Visual / Performance / Crash / Network]
+- **System**: [Which game system is affected — when the bug spans systems, the one whose code must change; the others go under Related systems]
+- **Frequency**: [Always / Often (>50%) / Sometimes (10-50%) / Rare (<10%)]
+- **Regression**: [Yes/No/Unknown -- was this working before?]
+
+## Environment
+- **Build**: [Version or commit hash]
+- **Platform**: [OS, hardware if relevant]
+- **Scene/Level**: [Where in the game]
+- **Game State**: [Relevant state -- inventory, quest progress, etc.]
+
+## Reproduction Steps
+**Preconditions**: [Required state before starting]
+
+1. [Exact step 1]
+2. [Exact step 2]
+3. [Exact step 3]
+
+**Expected Result**: [What should happen]
+**Actual Result**: [What actually happens]
+
+## Technical Context
+- **Likely affected files**: [List of files based on codebase search]
+- **Related systems**: [What other systems might be involved]
+- **Possible root cause**: [If identifiable from the description]
+
+## Evidence
+- **Logs**: [Relevant log output if available]
+- **Visual**: [Description of visual evidence]
+
+## Related Issues
+- [Links to related bugs or design documents]
+
+## Notes
+[Any additional context or observations]
diff --git a/.claude/docs/templates/certification-console.md b/.claude/docs/templates/certification-console.md
new file mode 100644
index 00000000..c9e3bf57
--- /dev/null
+++ b/.claude/docs/templates/certification-console.md
@@ -0,0 +1,9 @@
+### Certification: Console
+- [ ] TRC/TCR/Lotcheck requirements checklist complete
+- [ ] First-party certification submission prepared
+- [ ] Platform-specific achievement/trophy integration tested
+- [ ] Parental controls respected
+- [ ] Save-data rules compliant (corruption, full storage, user switching)
+- [ ] Controller-mapping rules met, platform-correct button prompts
+- [ ] Suspend/resume verified
+- [ ] Age ratings obtained (ESRB, PEGI, regional)
diff --git a/.claude/docs/templates/certification-itch.md b/.claude/docs/templates/certification-itch.md
new file mode 100644
index 00000000..d110b43a
--- /dev/null
+++ b/.claude/docs/templates/certification-itch.md
@@ -0,0 +1,6 @@
+### Certification: itch.io
+- [ ] Build size within itch.io upload limits
+- [ ] itch.io page complete (cover art, screenshots, description, tags)
+- [ ] Age/content tags set honestly
+- [ ] Downloadable vs browser build decided and tested
+- [ ] Butler channel names correct for each platform uploaded
diff --git a/.claude/docs/templates/certification-none.md b/.claude/docs/templates/certification-none.md
new file mode 100644
index 00000000..b5dc7cfc
--- /dev/null
+++ b/.claude/docs/templates/certification-none.md
@@ -0,0 +1 @@
+Certification: omitted — cert_tier is 'none' (internal build, alpha or jam release).
diff --git a/.claude/docs/templates/certification-steam.md b/.claude/docs/templates/certification-steam.md
new file mode 100644
index 00000000..00f3bf39
--- /dev/null
+++ b/.claude/docs/templates/certification-steam.md
@@ -0,0 +1,8 @@
+### Certification: Steamworks
+- [ ] Steamworks SDK integrated and tested
+- [ ] Store page complete (capsule art, trailer, description, system requirements)
+- [ ] Depot build uploaded and installs cleanly from a fresh account
+- [ ] Achievements functional
+- [ ] Cloud saves functional
+- [ ] Steam Deck compatibility verified (if targeting)
+- [ ] Steam common content rules reviewed
diff --git a/.claude/docs/templates/certification-unknown.md b/.claude/docs/templates/certification-unknown.md
new file mode 100644
index 00000000..3412a907
--- /dev/null
+++ b/.claude/docs/templates/certification-unknown.md
@@ -0,0 +1,3 @@
+### Certification: NOT ASSESSED — cert tier unknown
+
+[Why the tier could not be determined — `platform.cert_tier` is unset and the platforms in scope are not known — and what would settle it.]
diff --git a/.claude/docs/templates/changelog-internal.md b/.claude/docs/templates/changelog-internal.md
new file mode 100644
index 00000000..f61e56f1
--- /dev/null
+++ b/.claude/docs/templates/changelog-internal.md
@@ -0,0 +1,43 @@
+# Internal Changelog: [Version]
+Date: [Date]
+Sprint(s): [Sprint numbers covered]
+Commits: [Count] ([first-hash]..[last-hash])
+
+## New Features
+- [Feature Name] -- [Technical description, affected systems]
+ - Commits: [hash1], [hash2]
+ - Owner: [who implemented it]
+ - Design doc: [link if applicable]
+
+## Improvements
+- [Improvement] -- [What changed technically and why]
+ - Commits: [hashes]
+ - Owner: [who]
+
+## Bug Fixes
+- [BUG-ID] [Description of bug and root cause]
+ - Fix: [What was changed]
+ - Commits: [hashes]
+ - Owner: [who]
+
+## Balance Changes
+- [What was tuned] -- [Old value -> New value] -- [Design intent]
+ - Owner: [who]
+
+## Technical Debt / Refactoring
+- [What was cleaned up and why]
+ - Commits: [hashes]
+
+## Miscellaneous
+- [Change that didn't fit other categories, or vague commit message]
+ - Commits: [hashes]
+
+## Known Issues
+- [Issue description] -- [Severity] -- [ETA for fix if known]
+
+## Metrics
+- Total commits: [N]
+- Files changed: [N]
+- Lines added: [N]
+- Lines removed: [N]
+- Commits without task reference: [N]
diff --git a/.claude/docs/templates/changelog-template.md b/.claude/docs/templates/changelog-template.md
index 56f9cf3b..8db24a5d 100644
--- a/.claude/docs/templates/changelog-template.md
+++ b/.claude/docs/templates/changelog-template.md
@@ -1,62 +1,29 @@
-# What's New in [Version]
+# What is New in [Version]
**Release Date**: [Date]
----
-
## New Features
-
-- **[Feature Name]**: [Player-friendly description of what they can now do. Focus on the experience, not the implementation. 1-2 sentences.]
-
-- **[Feature Name]**: [Description]
-
----
+- **[Feature Name]**: [Player-friendly description of what they can now do
+ and why it is exciting. Focus on the experience, not the implementation.]
## Improvements
-
-- **[Area Improved]**: [How this makes the game better for the player. Be specific.]
-
-- **[Area Improved]**: [Description]
-
----
-
-## Balance Changes
-
-- **[What Changed]**: [Old value] -> [New value]. [Brief design reasoning in player terms. Example: "Healing potions now restore 50 HP (up from 30) -- late-game encounters needed more recovery options."]
-
-- **[What Changed]**: [Description]
-
----
+- **[What improved]**: [How this makes the game better for the player.
+ Be specific but avoid jargon.]
## Bug Fixes
+- Fixed an issue where [describe what the player experienced, not what was
+ wrong in the code]
+- Fixed [player-visible symptom]
-- Fixed an issue where [describe the player-visible symptom, not the code fix]
-- Fixed [another player-visible symptom]
-- Fixed [symptom]
-
----
+## Balance Changes
+- [What changed in player-understandable terms and the design intent.
+ Example: "Healing potions now restore 50 HP (up from 30) -- we felt
+ players needed more recovery options in late-game encounters."]
## Known Issues
-
-- [Issue description in player terms]. [Workaround if one exists.] We're working on a fix.
+- We are aware of [issue description in player terms] and are working on a
+ fix. [Workaround if one exists.]
---
-
-## Technical Notes (Internal Only -- Remove Before Publishing)
-
-### Commits Covered
-- Range: `[first-hash]..[last-hash]`
-- Total commits: [N]
-
-### Internal Changes
-- [Refactoring, infrastructure, or tooling changes not visible to players]
-
-### Deferred Items
-- [Features or fixes originally planned for this release but moved to next]
- - Reason: [why deferred]
- - New target: [version or sprint]
-
----
-
-Thank you for playing! Your feedback helps us improve the game.
-Report issues at [support link].
+Thank you for playing! Your feedback helps us make the game better.
+Report issues at [link].
diff --git a/.claude/docs/templates/game-design-document.md b/.claude/docs/templates/game-design-document.md
index e17d95a9..7393284d 100644
--- a/.claude/docs/templates/game-design-document.md
+++ b/.claude/docs/templates/game-design-document.md
@@ -1,219 +1,77 @@
-# [Mechanic/System Name]
+# [System Name]
-> **Status**: Draft | In Review | Approved | Implemented
-> **Author**: [Agent or person]
-> **Last Updated**: [Date]
-> **Last Verified**: [Date — when this doc was last confirmed accurate against current design]
-> **Implements Pillar**: [Which game pillar this supports]
+> Authoring guidance: .claude/docs/templates/guidance/game-design-document-guide.md (load per-section as you author — do not read entirely).
+
+> **Status**: [In Design | Designed | In Review | Needs Revision | Approved | Implemented]
+> **Author**: [user + agents]
+> **Last Updated**: [today's date]
+> **Last Verified**: [today's date]
+> **Implements Pillar**: [from context]
## Summary
-[2–3 sentences: what this system is, what it does for the player, and why it
-exists in this game. Written for tiered context loading — a skill scanning
-20 GDDs uses this section to decide whether to read further. No jargon.]
+[To be designed]
> **Quick reference** — Layer: `[Foundation | Core | Feature | Presentation]` · Priority: `[MVP | Vertical Slice | Alpha | Full Vision]` · Key deps: `[System names or "None"]`
## Overview
-[One paragraph that explains this mechanic to someone who knows nothing about
-the project. What is it, what does the player do, and why does it exist?]
+[To be designed]
## Player Fantasy
-[What should the player FEEL when engaging with this mechanic? What is the
-emotional or power fantasy being served? This section guides all detail
-decisions below.]
+[To be designed]
## Detailed Design
### Core Rules
-[Precise, unambiguous rules. A programmer should be able to implement this
-section without asking questions. Use numbered rules for sequential processes
-and bullet points for properties.]
+[To be designed]
### States and Transitions
-[If this system has states (e.g., weapon states, status effects, phases),
-document every state and every valid transition between states.]
-
-| State | Entry Condition | Exit Condition | Behavior |
-|-------|----------------|----------------|----------|
+[To be designed]
### Interactions with Other Systems
-[How does this system interact with combat? Inventory? Progression? UI?
-For each interaction, specify the interface: what data flows in, what flows
-out, and who is responsible for what.]
+[To be designed]
## Formulas
-[Every mathematical formula used by this system. For each formula:]
-
-### [Formula Name]
-
-```
-result = base_value * (1 + modifier_sum) * scaling_factor
-```
-
-| Variable | Type | Range | Source | Description |
-|----------|------|-------|--------|-------------|
-| base_value | float | 1-100 | data file | The base amount before modifiers |
-| modifier_sum | float | -0.9 to 5.0 | calculated | Sum of all active modifiers |
-| scaling_factor | float | 0.5-2.0 | data file | Level-based scaling |
-
-**Expected output range**: [min] to [max]
-**Edge case**: When modifier_sum < -0.9, clamp to -0.9 to prevent negative results.
+[To be designed]
## Edge Cases
-[Explicitly document what happens in unusual situations. Each edge case
-should have a clear resolution.]
-
-| Scenario | Expected Behavior | Rationale |
-|----------|------------------|-----------|
-| [What if X is zero?] | [This happens] | [Because of this reason] |
-| [What if both effects trigger?] | [Priority rule] | [Design reasoning] |
+[To be designed]
## Dependencies
-[List every system this mechanic depends on or that depends on this mechanic.]
-
-| System | Direction | Nature of Dependency |
-|--------|-----------|---------------------|
-| [Combat] | This depends on Combat | Needs damage calculation results |
-| [Inventory] | Inventory depends on this | Provides item effect data |
+[To be designed]
## Tuning Knobs
-[Every value that should be adjustable for balancing. Include the current
-value, the safe range, and what happens at the extremes.]
-
-| Parameter | Current Value | Safe Range | Effect of Increase | Effect of Decrease |
-|-----------|--------------|------------|-------------------|-------------------|
+[To be designed]
## Visual/Audio Requirements
-[What visual and audio feedback does this mechanic need?]
-
-| Event | Visual Feedback | Audio Feedback | Priority |
-|-------|----------------|---------------|----------|
+[To be designed]
## Game Feel
-> **Why this section exists separately from Visual/Audio Requirements**: Visual/Audio
-> Requirements document WHAT feedback events occur (tables of events mapped to assets).
-> Game Feel documents HOW the mechanic feels to operate — the responsiveness, weight,
-> snap, and kinesthetic quality of the interaction. These are design targets for timing,
-> frame data, and physical sensation of control. Game feel must be specified at design
-> time because it drives animation budgets, input handling architecture, and hitbox
-> timing. Retrofitting feel targets after implementation is expensive and often requires
-> fundamental rework.
-
-### Feel Reference
-
-[Name a specific game, mechanic, or moment that captures the target feel. Be precise —
-cite the exact mechanic, not just the game. Explain what quality you are borrowing.
-Optionally include an anti-reference (what this should NOT feel like).]
-
-> Example: "Should feel like Dark Souls weapon swings — weighty, committed, and
-> telegraphed, but satisfying on contact. NOT floaty like early Halo melee."
-
-### Input Responsiveness
-
-[Maximum acceptable latency from player input to visible/audible response, per action.]
-
-| Action | Max Input-to-Response Latency (ms) | Frame Budget (at 60fps) | Notes |
-|--------|-----------------------------------|------------------------|-------|
-| [Primary action] | [e.g., 50ms] | [e.g., 3 frames] | |
-| [Secondary action] | | | |
-
-### Animation Feel Targets
-
-[Frame data targets for each animation in this mechanic. Startup = windup before the
-action has any effect. Active = frames when the action is "happening" (hitbox live,
-ability firing, etc.). Recovery = committed/vulnerable frames after the action resolves.]
-
-| Animation | Startup Frames | Active Frames | Recovery Frames | Feel Goal | Notes |
-|-----------|---------------|--------------|----------------|-----------|-------|
-| [e.g., Light attack] | | | | [e.g., Snappy, low commitment] | |
-| [e.g., Heavy attack] | | | | [e.g., Weighty, high commitment] | |
-
-### Impact Moments
-
-[Defines the punctuation of the mechanic — the moments of peak feedback intensity that
-make actions feel consequential. Every high-stakes event should have at least one entry.]
-
-| Impact Type | Duration (ms) | Effect Description | Configurable? |
-|-------------|--------------|-------------------|---------------|
-| Hit-stop (freeze frames) | [e.g., 80ms] | [Freeze both objects on contact] | Yes |
-| Screen shake | [e.g., 150ms] | [Directional, decaying] | Yes |
-| Camera impact | | | |
-| Controller rumble | | | |
-| Time-scale slowdown | | | |
-
-### Weight and Responsiveness Profile
-
-[A short prose description of the overall feel target. Answer the following:]
-
-- **Weight**: Does this feel heavy and deliberate, or light and reactive?
-- **Player control**: How much does the player feel in control at every moment?
- (High control = can course-correct mid-action; Low control = committed, momentum-based)
-- **Snap quality**: Does this feel crisp and binary, or smooth and analog?
-- **Acceleration model**: Does movement/action start instantly (arcade feel) or
- ramp up from zero (simulation feel)? Same question for deceleration.
-- **Failure texture**: When the player makes an error, does the mechanic feel fair
- or punishing? What is the read on WHY they failed?
-
-### Feel Acceptance Criteria
-
-[Specific, testable criteria a playtester can verify without measurement instruments.
-These are subjective targets stated precisely enough to get consistent verdicts.]
-
-- [ ] [e.g., "Combat feels impactful — playtesters comment on weight unprompted"]
-- [ ] [e.g., "No reviewer uses the words 'floaty', 'slippery', or 'unresponsive'"]
-- [ ] [e.g., "Input latency is imperceptible at target 60fps framerate"]
-- [ ] [e.g., "Hit-stop reads as satisfying, not as lag or stutter"]
+[To be designed]
## UI Requirements
-[What information needs to be displayed to the player and when?]
-
-| Information | Display Location | Update Frequency | Condition |
-|-------------|-----------------|-----------------|-----------|
+[To be designed]
## Cross-References
-[Declare every explicit dependency on another GDD's specific mechanic, value, or
-rule. This table is machine-checked by `/review-all-gdds` Phase 2c — it replaces
-implicit prose references with verifiable declarations. If you reference another
-system's behaviour anywhere in this document, it must appear here.]
-
-| This Document References | Target GDD | Specific Element Referenced | Nature |
-|--------------------------|-----------|----------------------------|--------|
-| [e.g., "combo multiplier feeds score"] | `design/gdd/score.md` | `combo_multiplier` output value | Data dependency |
-| [e.g., "death triggers respawn"] | `design/gdd/respawn.md` | Death state transition | State trigger |
-| [e.g., "stamina gates dodge"] | `design/gdd/stamina.md` | Stamina depletion rule | Rule dependency |
-
-> **Note on "Nature"**: use one of — `Data dependency` (we consume their output),
-> `State trigger` (their state change triggers our behaviour), `Rule dependency`
-> (our rule assumes their rule is also true), `Ownership handoff` (we hand off
-> ownership of a value to them).
+[To be designed]
## Acceptance Criteria
-[Testable criteria that confirm this mechanic is working as designed.]
-
-- [ ] [Criterion 1: specific, measurable, testable]
-- [ ] [Criterion 2]
-- [ ] [Criterion 3]
-- [ ] Performance: System update completes within [X]ms
-- [ ] No hardcoded values in implementation
+[To be designed]
## Open Questions
-[Anything not yet decided. Each question should have an owner and deadline.]
-
-| Question | Owner | Deadline | Resolution |
-|----------|-------|----------|-----------|
+[To be designed]
diff --git a/.claude/docs/templates/guidance/accessibility-requirements-guide.md b/.claude/docs/templates/guidance/accessibility-requirements-guide.md
index dcfe0ba8..4ae40a38 100644
--- a/.claude/docs/templates/guidance/accessibility-requirements-guide.md
+++ b/.claude/docs/templates/guidance/accessibility-requirements-guide.md
@@ -177,7 +177,7 @@ Features explicitly out of scope:
| Feature | Tier Required | Why Not Included | Risk / Impact | Mitigation |
|---------|--------------|-----------------|--------------|------------|
-| [Screen reader support for in-game world (NPCs, objects, environmental text)] | Exemplary | Engine (Godot 4.6) AccessKit integration covers menus only; extending to the game world requires a custom spatial audio description system beyond current scope | Affects blind and low-vision players who can navigate menus but cannot independently explore the game world | Ensure all critical world information is duplicated in accessible menu systems (quest log, map); evaluate for post-launch DLC |
+| [Screen reader support for in-game world (NPCs, objects, environmental text)] | Exemplary | Engine (Godot 4.7) AccessKit integration covers menus only; extending to the game world requires a custom spatial audio description system beyond current scope | Affects blind and low-vision players who can navigate menus but cannot independently explore the game world | Ensure all critical world information is duplicated in accessible menu systems (quest log, map); evaluate for post-launch DLC |
| [Full subtitle customization (font/color/background)] | Comprehensive | Scope reduction — targeting Standard tier. Custom font rendering in Godot requires additional asset pipeline work | Affects deaf and hard-of-hearing players with specific legibility needs; particularly affects players with dyslexia who use custom fonts | Provide two preset subtitle styles (default and high-readability) as a partial mitigation; log for post-launch update |
| [Tactile/haptic alternatives for all audio cues] | Exemplary | Platform rumble API integration for non-Xbox platforms is out of scope for v1.0 | Affects deaf players relying on haptic feedback; PC players with non-Xbox controllers get no haptic response | Xbox controller haptic integration is in scope; evaluate PlayStation DualSense haptic API for a post-launch patch |
@@ -205,6 +205,6 @@ Features explicitly out of scope:
| Question | Owner | Deadline | Resolution |
|----------|-------|----------|-----------|
-| [Does Godot 4.6 AccessKit support dynamic accessibility node updates for HUD elements, or only static menus?] | [ux-designer] | [Before Technical Setup gate] | [Unresolved — check engine-reference/godot/ docs] |
+| [Does Godot 4.7 AccessKit support dynamic accessibility node updates for HUD elements, or only static menus?] | [ux-designer] | [Before Technical Setup gate] | [Unresolved — check engine-reference/godot/ docs] |
| [What is the Xbox ID@Xbox minimum XAG compliance requirement for our release window?] | [producer] | [Before Pre-Production gate] | [Unresolved] |
| [Will the dialogue system support timed choice extensions without a full architecture change?] | [lead-programmer] | [During Technical Design] | [Unresolved] |
diff --git a/.claude/docs/templates/guidance/game-design-document-guide.md b/.claude/docs/templates/guidance/game-design-document-guide.md
new file mode 100644
index 00000000..faa1fc5c
--- /dev/null
+++ b/.claude/docs/templates/guidance/game-design-document-guide.md
@@ -0,0 +1,264 @@
+> Authoring guidance for game-design-document.md. Load only the part covering the section currently being authored — not the whole file at once.
+
+# Game Design Document Template — Authoring Guidance
+
+The template is the skeleton every GDD starts from: each section holds
+`[To be designed]` until it is written, so a section still holding it reads as
+not written yet. This guide says what goes in each section once it is written,
+with the tables and columns to use. It is organised by the template's section
+headings; when authoring a section, read only that section's guidance below.
+
+---
+
+## Header
+
+- **Status**: one of `In Design` (the skeleton's value), `Designed`,
+ `In Review`, `Needs Revision`, `Approved`, `Implemented`.
+- **Author**: the agent or person who wrote it.
+- **Last Updated**: the date of the last edit.
+- **Last Verified**: when this doc was last confirmed accurate against the
+ current design.
+- **Implements Pillar**: which game pillar this system supports.
+
+---
+
+## Summary
+
+2–3 sentences: what this system is, what it does for the player, and why it
+exists in this game. Written for tiered context loading — a skill scanning
+20 GDDs uses this section to decide whether to read further. No jargon.
+
+Keep the **Quick reference** line under it, filled in: the system's layer, its
+priority and its key dependencies.
+
+---
+
+## Overview
+
+One paragraph that explains this mechanic to someone who knows nothing about
+the project. What is it, what does the player do, and why does it exist?
+
+---
+
+## Player Fantasy
+
+What should the player FEEL when engaging with this mechanic? What is the
+emotional or power fantasy being served? This section guides all detail
+decisions below.
+
+---
+
+## Detailed Design
+
+### Core Rules
+
+Precise, unambiguous rules. A programmer should be able to implement this
+section without asking questions. Use numbered rules for sequential processes
+and bullet points for properties.
+
+### States and Transitions
+
+If this system has states (e.g., weapon states, status effects, phases),
+document every state and every valid transition between states.
+
+| State | Entry Condition | Exit Condition | Behavior |
+|-------|----------------|----------------|----------|
+
+### Interactions with Other Systems
+
+How does this system interact with combat? Inventory? Progression? UI?
+For each interaction, specify the interface: what data flows in, what flows
+out, and who is responsible for what.
+
+---
+
+## Formulas
+
+Every mathematical formula used by this system. For each formula:
+
+### [Formula Name]
+
+```
+result = base_value * (1 + modifier_sum) * scaling_factor
+```
+
+| Variable | Type | Range | Source | Description |
+|----------|------|-------|--------|-------------|
+| base_value | float | 1-100 | data file | The base amount before modifiers |
+| modifier_sum | float | -0.9 to 5.0 | calculated | Sum of all active modifiers |
+| scaling_factor | float | 0.5-2.0 | data file | Level-based scaling |
+
+**Expected output range**: [min] to [max]
+**Edge case**: When modifier_sum < -0.9, clamp to -0.9 to prevent negative results.
+
+---
+
+## Edge Cases
+
+Explicitly document what happens in unusual situations. Each edge case
+should have a clear resolution.
+
+| Scenario | Expected Behavior | Rationale |
+|----------|------------------|-----------|
+| [What if X is zero?] | [This happens] | [Because of this reason] |
+| [What if both effects trigger?] | [Priority rule] | [Design reasoning] |
+
+---
+
+## Dependencies
+
+List every system this mechanic depends on or that depends on this mechanic.
+
+| System | Direction | Nature of Dependency |
+|--------|-----------|---------------------|
+| [Combat] | This depends on Combat | Needs damage calculation results |
+| [Inventory] | Inventory depends on this | Provides item effect data |
+
+---
+
+## Tuning Knobs
+
+Every value that should be adjustable for balancing. Include the current
+value, the safe range, and what happens at the extremes.
+
+| Parameter | Current Value | Safe Range | Effect of Increase | Effect of Decrease |
+|-----------|--------------|------------|-------------------|-------------------|
+
+---
+
+## Visual/Audio Requirements
+
+What visual and audio feedback does this mechanic need?
+
+| Event | Visual Feedback | Audio Feedback | Priority |
+|-------|----------------|---------------|----------|
+
+---
+
+## Game Feel
+
+> **Why this section exists separately from Visual/Audio Requirements**: Visual/Audio
+> Requirements document WHAT feedback events occur (tables of events mapped to assets).
+> Game Feel documents HOW the mechanic feels to operate — the responsiveness, weight,
+> snap, and kinesthetic quality of the interaction. These are design targets for timing,
+> frame data, and physical sensation of control. Game feel must be specified at design
+> time because it drives animation budgets, input handling architecture, and hitbox
+> timing. Retrofitting feel targets after implementation is expensive and often requires
+> fundamental rework.
+
+Write the section with these six parts.
+
+### Feel Reference
+
+Name a specific game, mechanic, or moment that captures the target feel. Be precise —
+cite the exact mechanic, not just the game. Explain what quality you are borrowing.
+Optionally include an anti-reference (what this should NOT feel like).
+
+> Example: "Should feel like Dark Souls weapon swings — weighty, committed, and
+> telegraphed, but satisfying on contact. NOT floaty like early Halo melee."
+
+### Input Responsiveness
+
+Maximum acceptable latency from player input to visible/audible response, per action.
+
+| Action | Max Input-to-Response Latency (ms) | Frame Budget (at 60fps) | Notes |
+|--------|-----------------------------------|------------------------|-------|
+| [Primary action] | [e.g., 50ms] | [e.g., 3 frames] | |
+| [Secondary action] | | | |
+
+### Animation Feel Targets
+
+Frame data targets for each animation in this mechanic. Startup = windup before the
+action has any effect. Active = frames when the action is "happening" (hitbox live,
+ability firing, etc.). Recovery = committed/vulnerable frames after the action resolves.
+
+| Animation | Startup Frames | Active Frames | Recovery Frames | Feel Goal | Notes |
+|-----------|---------------|--------------|----------------|-----------|-------|
+| [e.g., Light attack] | | | | [e.g., Snappy, low commitment] | |
+| [e.g., Heavy attack] | | | | [e.g., Weighty, high commitment] | |
+
+### Impact Moments
+
+Defines the punctuation of the mechanic — the moments of peak feedback intensity that
+make actions feel consequential. Every high-stakes event should have at least one entry.
+
+| Impact Type | Duration (ms) | Effect Description | Configurable? |
+|-------------|--------------|-------------------|---------------|
+| Hit-stop (freeze frames) | [e.g., 80ms] | [Freeze both objects on contact] | Yes |
+| Screen shake | [e.g., 150ms] | [Directional, decaying] | Yes |
+| Camera impact | | | |
+| Controller rumble | | | |
+| Time-scale slowdown | | | |
+
+### Weight and Responsiveness Profile
+
+A short prose description of the overall feel target. Answer the following:
+
+- **Weight**: Does this feel heavy and deliberate, or light and reactive?
+- **Player control**: How much does the player feel in control at every moment?
+ (High control = can course-correct mid-action; Low control = committed, momentum-based)
+- **Snap quality**: Does this feel crisp and binary, or smooth and analog?
+- **Acceleration model**: Does movement/action start instantly (arcade feel) or
+ ramp up from zero (simulation feel)? Same question for deceleration.
+- **Failure texture**: When the player makes an error, does the mechanic feel fair
+ or punishing? What is the read on WHY they failed?
+
+### Feel Acceptance Criteria
+
+Specific, testable criteria a playtester can verify without measurement instruments.
+These are subjective targets stated precisely enough to get consistent verdicts.
+
+- [ ] [e.g., "Combat feels impactful — playtesters comment on weight unprompted"]
+- [ ] [e.g., "No reviewer uses the words 'floaty', 'slippery', or 'unresponsive'"]
+- [ ] [e.g., "Input latency is imperceptible at target 60fps framerate"]
+- [ ] [e.g., "Hit-stop reads as satisfying, not as lag or stutter"]
+
+---
+
+## UI Requirements
+
+What information needs to be displayed to the player and when?
+
+| Information | Display Location | Update Frequency | Condition |
+|-------------|-----------------|-----------------|-----------|
+
+---
+
+## Cross-References
+
+Declare every explicit dependency on another GDD's specific mechanic, value, or
+rule. `/review-all-gdds` Phase 2c reads this table — it replaces implicit prose
+references with verifiable declarations. If you reference another system's
+behaviour anywhere in the document, it must appear here.
+
+| This Document References | Target GDD | Specific Element Referenced | Nature |
+|--------------------------|-----------|----------------------------|--------|
+| [e.g., "combo multiplier feeds score"] | `design/gdd/score.md` | `combo_multiplier` output value | Data dependency |
+| [e.g., "death triggers respawn"] | `design/gdd/respawn.md` | Death state transition | State trigger |
+| [e.g., "stamina gates dodge"] | `design/gdd/stamina.md` | Stamina depletion rule | Rule dependency |
+
+> **Note on "Nature"**: use one of — `Data dependency` (we consume their output),
+> `State trigger` (their state change triggers our behaviour), `Rule dependency`
+> (our rule assumes their rule is also true), `Ownership handoff` (we hand off
+> ownership of a value to them).
+
+---
+
+## Acceptance Criteria
+
+Testable criteria that confirm this mechanic is working as designed.
+
+- [ ] [Criterion 1: specific, measurable, testable]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+- [ ] Performance: System update completes within [X]ms
+- [ ] No hardcoded values in implementation
+
+---
+
+## Open Questions
+
+Anything not yet decided. Each question should have an owner and deadline.
+
+| Question | Owner | Deadline | Resolution |
+|----------|-------|----------|-----------|
diff --git a/.claude/docs/templates/guidance/interaction-pattern-library-guide-game-specific.md b/.claude/docs/templates/guidance/interaction-pattern-library-guide-game-specific.md
index 8b3c3214..7b2d2a30 100644
--- a/.claude/docs/templates/guidance/interaction-pattern-library-guide-game-specific.md
+++ b/.claude/docs/templates/guidance/interaction-pattern-library-guide-game-specific.md
@@ -58,7 +58,7 @@ any context where an ability must show availability state.
`Control` nodes for cooldown radial and charge pips. The cooldown radial uses a
custom shader on a `ColorRect` rotating a mask — or implement with a
`ProgressBar` styled as circular if engine supports it. Verify against
-engine-reference/godot/ for Godot 4.6 shader support for this pattern.]
+engine-reference/godot/ for Godot 4.7 shader support for this pattern.]
---
diff --git a/.claude/docs/templates/guidance/interaction-pattern-library-guide-standard-controls.md b/.claude/docs/templates/guidance/interaction-pattern-library-guide-standard-controls.md
index 6fb46286..f17f9219 100644
--- a/.claude/docs/templates/guidance/interaction-pattern-library-guide-standard-controls.md
+++ b/.claude/docs/templates/guidance/interaction-pattern-library-guide-standard-controls.md
@@ -508,7 +508,7 @@ which is high friction.
but always include a visible `Label` node as the field's accessible name. Bind
`text_changed` signal for real-time validation. Bind `text_submitted` for form
submission on Enter. On console, `LineEdit.call("_popup_keyboard")` or use the OS
-virtual keyboard API — verify against engine-reference/godot/ for Godot 4.6
+virtual keyboard API — verify against engine-reference/godot/ for Godot 4.7
console keyboard API specifics.]
---
diff --git a/.claude/docs/templates/help-escalation.md b/.claude/docs/templates/help-escalation.md
new file mode 100644
index 00000000..12f21494
--- /dev/null
+++ b/.claude/docs/templates/help-escalation.md
@@ -0,0 +1,11 @@
+---
+Need more detail?
+- `/project-stage-detect` — full gap analysis with all missing artifacts listed
+- `/gate-check` — formal readiness check for your next phase
+- `/start` — re-orient from scratch
+- `/settings` — if the process feels mismatched to your project, adjust
+ `modes.rigor`. Apply the change-triggers in
+ `.claude/docs/settings-guidance.md § 4`: a **lower** tier when the user sounds
+ overwhelmed by process (and rigor isn't already `minimal`), or a **higher** tier
+ when the project has outgrown it (many systems, or in Production on
+ `workflow: minimal`)
diff --git a/.claude/docs/templates/help-where-you-are-minimal.md b/.claude/docs/templates/help-where-you-are-minimal.md
new file mode 100644
index 00000000..f1fe1941
--- /dev/null
+++ b/.claude/docs/templates/help-where-you-are-minimal.md
@@ -0,0 +1,13 @@
+## Where You Are: Minimal path — [N] of [M] stories complete
+
+**In progress:** [from active.md, if any]
+
+### ✓ Done
+- Engine: [engine] · Game brief · [N] stories
+
+### → Next up
+**[Story NNN: title]** — [what it delivers]
+Command: `/story-done [story-path]` for an In Review story, or an In Progress one whose work is written; otherwise `/dev-story [story-path]`
+
+### Coming up after that
+- [the next Ready stories in build order, at most 3]
diff --git a/.claude/docs/templates/help-where-you-are.md b/.claude/docs/templates/help-where-you-are.md
new file mode 100644
index 00000000..e0140167
--- /dev/null
+++ b/.claude/docs/templates/help-where-you-are.md
@@ -0,0 +1,22 @@
+## Where You Are: [Phase Label]
+
+**In progress:** [from active.md, if any]
+
+### ✓ Done
+- [completed step name]
+- [completed step name]
+
+### → Next up (REQUIRED)
+**[Step name]** — [description]
+Command: `[/command]`
+
+### ~ Also available (OPTIONAL)
+- **[Step name]** — [description] → `/command`
+- **[Step name]** — [description] → `/command`
+
+### Coming up after that
+- [Next required step name] (`/command`)
+- [Next required step name] (`/command`)
+
+---
+Approaching **[next phase]** gate → run `/gate-check` when ready.
diff --git a/.claude/docs/templates/hud-design.md b/.claude/docs/templates/hud-design.md
index ee32bf35..4e427fea 100644
--- a/.claude/docs/templates/hud-design.md
+++ b/.claude/docs/templates/hud-design.md
@@ -1,12 +1,12 @@
-# HUD Design: [Game Name]
+# HUD Design
> 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., ux-designer]
-> **Last Updated**: [Date]
+> **Status**: [In Design | In Review | Approved | Implemented]
+> **Author**: [user + ux-designer]
+> **Last Updated**: [today's 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]
+> **Platform Targets**: [target platforms and input methods from 2h]
> **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 § 7. UI/HUD Visual Direction`]
@@ -23,6 +23,8 @@
## 1. HUD Philosophy
+[To be designed]
+
**What is this game's relationship with on-screen information?**
[One-paragraph design statement — see guide Section 1 for framing and examples]
@@ -43,6 +45,16 @@
> inventory of game information, not just HUD information. See guide Section 2
> for a worked example covering typical information types.
+### 2.1 Full Information Inventory
+
+[To be designed]
+
+[Every piece of information the game generates, one line each — health, resources, objectives, timers, status effects, subtitles and the rest — whether or not the HUD shows it.]
+
+### 2.2 Categorization
+
+[To be designed]
+
| Information Type | Always Show | Contextual (show when relevant) | On Demand (menu/button) | Hidden (environmental / diegetic) | Reasoning |
|-----------------|-------------|--------------------------------|------------------------|----------------------------------|-----------|
| [Information type — e.g., Health, resource, minimap, quest objective, subtitles, status effects, timer, XP] | [ ] | [ ] | [ ] | [ ] | [Why this presentation category] |
@@ -51,6 +63,8 @@
## 3. Layout Zones
+[To be designed]
+
### 3.1 Zone Diagram
```
@@ -99,6 +113,8 @@
## 4. HUD Element Specifications
+[To be designed]
+
### 4.1 Element Overview Table
> One row per HUD element. This is the master inventory for implementation planning.
@@ -132,6 +148,8 @@
## 5. HUD States by Gameplay Context
+[To be designed]
+
> Define the HUD transformation for every gameplay context — at minimum:
> exploration, combat, dialogue/cutscene, and paused/menu. See guide Section 5
> for a worked example covering nine contexts.
@@ -144,6 +162,8 @@
## 6. Information Hierarchy
+[To be designed]
+
> Assign every element a priority tier (MUST KEEP / SHOULD KEEP / CAN HIDE /
> ALWAYS HIDE) with reasoning. See guide Section 6 for a worked example.
@@ -155,6 +175,8 @@
## 7. Visual Budget
+[To be designed]
+
> These numbers are hard limits, not guidelines. Every element addition that
> would breach a limit requires explicit approval and must displace or reduce an
> existing element. See guide Section 7 for how to apply the budgets.
@@ -173,6 +195,8 @@
## 8. Feedback & Notification Systems
+[To be designed]
+
> One row per notification type. Every notification must have queue/priority
> behavior defined. See guide Section 8 for a worked example table and queue rules.
@@ -189,6 +213,8 @@
## 9. Platform Adaptation
+[To be designed]
+
> Every target platform requires explicit layout testing before certification.
> See guide Section 9 for a worked example.
@@ -207,6 +233,8 @@ Repositioning saves to player profile, not to a single slot. Applies across play
## 10. Accessibility
+[To be designed]
+
> HUD-specific requirements only — refer to the project's
> `design/accessibility-requirements.md` for the full project standard.
@@ -267,6 +295,8 @@ The following player-adjustable settings must be available from the Accessibilit
## 11. Tuning Knobs
+[To be designed]
+
> Document all tunable parameters before implementation so the programmer knows
> which values to externalize. See guide Section 11 for a worked example.
@@ -278,6 +308,8 @@ The following player-adjustable settings must be available from the Accessibilit
## 12. Acceptance Criteria
+[To be designed]
+
> These criteria are the certification checklist for the HUD. Every item must
> pass before the HUD can be marked Approved. QA must be able to verify each
> item independently.
@@ -322,6 +354,8 @@ The following player-adjustable settings must be available from the Accessibilit
## 13. Open Questions
+[To be designed]
+
> Track unresolved design questions here. All questions must be resolved before
> the HUD design document can be marked Approved. See guide Section 13 for
> example questions.
diff --git a/.claude/docs/templates/interaction-pattern-library.md b/.claude/docs/templates/interaction-pattern-library.md
index a9e5494b..45fec8a7 100644
--- a/.claude/docs/templates/interaction-pattern-library.md
+++ b/.claude/docs/templates/interaction-pattern-library.md
@@ -1,12 +1,12 @@
-# Interaction Pattern Library: [Game Title]
+# Interaction Pattern Library
> Authoring guidance: .claude/docs/templates/guidance/interaction-pattern-library-guide.md (load per-section as you author — do not read entirely).
-> **Status**: Draft | Stable | Under Revision
-> **Author**: [ux-designer]
-> **Last Updated**: [Date]
+> **Status**: [In Design | Stable | Under Revision]
+> **Author**: [user + ux-designer]
+> **Last Updated**: [today's date]
> **Version**: [1.0]
-> **Engine**: [Godot 4.6 / Unity 6 / Unreal Engine 5]
+> **Engine**: [Godot 4.7 / Unity 6 / Unreal Engine 5]
> **UI Framework**: [Godot Control nodes / Unity UI Toolkit / Unreal UMG]
> **Related Documents**:
> - `design/art/art-bible.md` — visual standards (colors, typography, iconography)
@@ -35,7 +35,11 @@
---
-## How to Use This Library
+## Overview
+
+[To be designed]
+
+### How to Use This Library
**If you are designing a screen**: Browse the Pattern Catalog Index below before
inventing new interactions. When a standard pattern fits, reference it by name
@@ -59,7 +63,11 @@ update this document before or simultaneously with any implementation change.
---
-## Pattern Catalog Index
+## Pattern Catalog
+
+[To be designed]
+
+### Pattern Catalog Index
> Add a row here every time a new pattern is added to this document.
> The "Used In" column is the usages audit trail — update it when new screens
@@ -108,7 +116,11 @@ update this document before or simultaneously with any implementation change.
---
-## Standard Control Patterns
+## Patterns
+
+[Individual pattern entries added here as they are defined]
+
+### Standard Control Patterns
> Full reference specifications for every pattern in this section (state tables
> with timing/audio values, accessibility requirements, implementation notes)
@@ -431,7 +443,7 @@ update this document before or simultaneously with any implementation change.
---
-## Game-Specific UI Patterns
+### Game-Specific UI Patterns
> Full reference specifications for every pattern in this section are in
> `.claude/docs/templates/guidance/interaction-pattern-library-guide-game-specific.md` — load only the
@@ -551,7 +563,7 @@ update this document before or simultaneously with any implementation change.
---
-## Navigation Patterns
+### Navigation Patterns
> Full reference specifications for this section and the next are in
> `.claude/docs/templates/guidance/interaction-pattern-library-guide-navigation-feedback.md` — load
@@ -608,7 +620,7 @@ These three patterns define how screens enter and exit the navigation stack.
---
-## Feedback and Loading Patterns
+### Feedback and Loading Patterns
---
@@ -653,6 +665,7 @@ These three patterns define how screens enter and exit the navigation stack.
**Principle**: Error messages are never the player's fault. They tell the player what happened and what to do next.
---
+
## Animation Standards
> These timing values apply to ALL patterns in this library. When a pattern says
@@ -721,11 +734,19 @@ These three patterns define how screens enter and exit the navigation stack.
---
+## Gaps & Patterns Needed
+
+[To be designed]
+
+---
+
## Open Questions
+[To be designed]
+
| Question | Owner | Deadline | Resolution |
|----------|-------|----------|-----------|
-| [Does the engine's accessibility node system support screen reader announcements for toast notifications without requiring focus? Verify against engine-reference/godot/ for Godot 4.6.] | [ux-designer] | [Before first menu implementation] | [Unresolved] |
+| [Does the engine's accessibility node system support screen reader announcements for toast notifications without requiring focus? Verify against engine-reference/godot/ for Godot 4.7.] | [ux-designer] | [Before first menu implementation] | [Unresolved] |
| [What is the platform-correct confirm/cancel button mapping for Nintendo Switch release? Nintendo first-party convention differs from Xbox/PlayStation.] | [producer] | [Before platform certification submission] | [Unresolved] |
| [Should damage numbers be pooled as Label3D nodes or rendered in a SubViewport? Verify performance budget in coordination with technical-director.] | [lead-programmer, ux-designer] | [Before combat HUD implementation] | [Unresolved] |
| [What is the maximum number of simultaneous toast notifications before the queue becomes visually overwhelming? Needs playtesting.] | [ux-designer] | [First playtesting session] | [Unresolved] |
diff --git a/.claude/docs/templates/launch-checklist.md b/.claude/docs/templates/launch-checklist.md
new file mode 100644
index 00000000..34c03dad
--- /dev/null
+++ b/.claude/docs/templates/launch-checklist.md
@@ -0,0 +1,196 @@
+# Launch Checklist: [Game Title]
+Target Launch: [Date or DRY RUN]
+Generated: [Date]
+
+---
+
+## 1. Code Readiness
+
+### Build Health
+- [ ] Clean build on all target platforms
+- [ ] Zero compiler warnings
+- [ ] All unit tests passing
+- [ ] All integration tests passing
+- [ ] Performance benchmarks within targets
+- [ ] No memory leaks (verified via extended soak test)
+- [ ] Build size within platform limits
+- [ ] Build version correctly set and tagged in source control
+
+### Code Quality
+- [ ] TODO count: [N] (zero required for launch, or documented exceptions)
+- [ ] FIXME count: [N] (zero required)
+- [ ] HACK count: [N] (each must have documented justification)
+- [ ] No debug output in production code
+- [ ] No hardcoded dev/test values
+- [ ] All feature flags set to production values
+- [ ] Error handling covers all critical paths
+- [ ] Crash reporting integrated and verified
+
+### Security
+- [ ] No exposed API keys or credentials in source
+- [ ] Save data encrypted
+- [ ] Network communication secured (TLS/DTLS)
+- [ ] Anti-cheat measures active (if multiplayer)
+- [ ] Input validation on all server endpoints (if multiplayer)
+- [ ] Privacy policy compliance verified
+
+---
+
+## 2. Content Readiness
+
+### Assets
+- [ ] All placeholder art replaced with final assets
+- [ ] All placeholder audio replaced with final audio
+- [ ] Audio mix finalized and approved by audio director
+- [ ] All VFX polished and performance-verified
+- [ ] No missing or broken asset references
+- [ ] Asset naming conventions enforced
+
+### Text and Localization
+- [ ] All player-facing text proofread
+- [ ] No hardcoded strings (all externalized for localization)
+- [ ] All supported languages translated and verified
+- [ ] Text fits UI in all languages (text fitting pass complete)
+- [ ] Font coverage verified for all supported languages
+- [ ] Credits complete, accurate, and up to date
+
+### Game Content
+- [ ] All levels/maps playable from start to finish
+- [ ] Tutorial flow complete and tested with new players
+- [ ] All achievements/trophies implemented and tested
+- [ ] Save/load works correctly for all game states
+- [ ] Difficulty settings balanced and tested
+- [ ] End-game/credits sequence complete
+
+---
+
+## 3. Quality Assurance
+
+### Testing
+- [ ] Full regression test suite passed
+- [ ] Zero S1 (Critical) bugs open
+- [ ] Zero S2 (High) bugs open (or documented exceptions) — at `workflow: full` instead: zero S2 (High) and S3 (Medium) bugs open, no exceptions
+- [ ] Soak test passed (the longest soak `/soak-test` runs, or longer by hand if a play session lasts longer)
+- [ ] Multiplayer stress test passed (if applicable)
+- [ ] All critical user paths tested on every platform
+- [ ] Edge cases tested (full storage, no network, suspend/resume)
+
+[Certification: the one block for this project's `platform.cert_tier`, copied from `certification-none.md`, `certification-itch.md`, `certification-steam.md` or `certification-console.md`; `certification-unknown.md` when the tier cannot be determined]
+
+**Every tier**, because these are not certification-gated:
+- [ ] Accessibility: minimum standards met (remapping, text scaling, colorblind)
+
+### Performance
+- [ ] Target FPS met on minimum spec hardware
+- [ ] Load times within budget on all platforms
+- [ ] Memory usage within budget on all platforms
+- [ ] Network bandwidth within targets (if multiplayer)
+- [ ] No frame hitches in critical gameplay moments
+
+---
+
+## 4. Store and Distribution
+
+### Store Pages
+- [ ] Store page copy finalized and proofread
+- [ ] Screenshots current and per-platform resolution
+- [ ] Trailers current and approved
+- [ ] Key art and capsule images finalized
+- [ ] System requirements accurate (PC)
+- [ ] Pricing configured for all regions
+- [ ] Pre-purchase/wishlist campaigns active (if applicable)
+
+### Legal
+- [ ] EULA finalized and approved by legal
+- [ ] Privacy policy published and linked
+- [ ] Third-party license attributions complete
+- [ ] Music/audio licensing verified
+- [ ] Trademark/IP clearance confirmed
+- [ ] GDPR/CCPA compliance verified (data collection, consent, deletion)
+
+---
+
+## 5. Infrastructure
+
+### Servers (if multiplayer/online)
+- [ ] Production servers provisioned and load-tested
+- [ ] Auto-scaling configured and tested
+- [ ] Database backups configured
+- [ ] CDN configured for content delivery
+- [ ] DDoS protection active
+- [ ] Monitoring and alerting configured
+
+### Analytics and Monitoring
+- [ ] Analytics pipeline verified and receiving data
+- [ ] Crash reporting active and dashboard accessible
+- [ ] Server monitoring dashboards live
+- [ ] Key metrics tracked: DAU, session length, retention, crashes
+- [ ] Alerts configured for critical thresholds
+
+---
+
+## 6. Community and Marketing
+
+### Community Readiness
+- [ ] Community guidelines published
+- [ ] Moderation team briefed and tools ready
+- [ ] Discord/forum/social channels set up
+- [ ] FAQ and known issues page prepared
+- [ ] Support email/ticketing system active
+
+### Marketing
+- [ ] Launch trailer published
+- [ ] Press/influencer review keys distributed
+- [ ] Social media launch posts scheduled
+- [ ] Launch day blog post/dev update drafted
+- [ ] Patch notes for launch version published
+
+---
+
+## 7. Operations
+
+### Team Readiness
+- [ ] On-call schedule set for first 72 hours post-launch
+- [ ] Incident response playbook reviewed by team
+- [ ] Rollback plan documented and tested
+- [ ] Hotfix pipeline tested (can ship emergency fix within 4 hours)
+- [ ] Communication plan for launch issues (who posts, where, how fast)
+
+### Day-One Plan
+- [ ] Day-one patch prepared (if needed)
+- [ ] Server unlock/go-live procedure documented
+- [ ] Launch monitoring dashboard bookmarked by all leads
+- [ ] War room/channel established for launch day
+
+---
+
+## Go / No-Go Decision
+
+**Overall Status**: [READY / CONDITIONAL / NOT ASSESSED / NOT READY]
+
+First match wins: **NOT READY** if Blocking Items is not empty; else **NOT
+ASSESSED** if any item is `- [?]`, any section came out `NOT ASSESSED`, or any
+item is still unconfirmed — neither ticked on evidence or on a Phase 4b answer,
+nor marked N/A, nor listed below (name each; group by section when there are
+many); else **CONDITIONAL** if Conditional
+Items is not empty; else **READY**. NOT ASSESSED outranks CONDITIONAL and READY —
+an item nobody could check is not a passed one — and ranks below NOT READY, so a
+known blocker is never buried behind it.
+
+### Blocking Items
+[Every FAIL or unresolved finding: a check that found a problem — FIXMEs, debug
+output, placeholder assets, hardcoded dev values, an open S1 bug, a failing
+build or test — with no documented workaround and no explicitly accepted risk]
+
+### Conditional Items
+[Every shortfall with a documented workaround or an explicitly accepted risk —
+e.g. a HACK with its documented justification, an S2 with a documented
+exception (below `workflow: full`, which allows none). Name the workaround, or
+who accepted the risk]
+
+### Sign-Offs Required
+- [ ] Creative Director — Content and experience quality
+- [ ] Technical Director — Technical health and stability
+- [ ] QA Lead — Quality and test coverage
+- [ ] Producer — Schedule and overall readiness
+- [ ] Release Manager — Build and deployment readiness
diff --git a/.claude/docs/templates/patch-notes-brief.md b/.claude/docs/templates/patch-notes-brief.md
new file mode 100644
index 00000000..44e03dee
--- /dev/null
+++ b/.claude/docs/templates/patch-notes-brief.md
@@ -0,0 +1,15 @@
+# Patch [Version] — [Title]
+
+**New**
+- [Feature 1]
+- [Feature 2]
+
+**Changes**
+- [Balance/mechanic change with before → after values]
+
+**Fixes**
+- [Bug fix 1]
+- [Bug fix 2]
+
+**Known Issues**
+- [Issue 1]
diff --git a/.claude/docs/templates/patch-notes-commentary.md b/.claude/docs/templates/patch-notes-commentary.md
new file mode 100644
index 00000000..317b6a97
--- /dev/null
+++ b/.claude/docs/templates/patch-notes-commentary.md
@@ -0,0 +1,4 @@
+## Developer Commentary
+### [Topic]
+> [Developer insight into a major change — why it was made, what was considered,
+> what the team learned. Written in first-person team voice.]
diff --git a/.claude/docs/templates/project-stage-report.md b/.claude/docs/templates/project-stage-report.md
index a75d5819..ff7c9730 100644
--- a/.claude/docs/templates/project-stage-report.md
+++ b/.claude/docs/templates/project-stage-report.md
@@ -1,171 +1,41 @@
-# Project Stage Analysis Report
+# Project Stage Analysis
-**Generated**: [DATE]
-**Stage**: [Concept | Systems Design | Technical Setup | Pre-Production | Production | Polish | Release]
-**Stage Confidence**: [PASS / CONCERNS / NOT ASSESSED / FAIL — reason]
+**Date**: [date]
+**Stage**: [Concept/Systems Design/Technical Setup/Pre-Production/Production/Polish/Release]
+**Stage Confidence**: [PASS — clearly detected / CONCERNS — ambiguous signals / NOT ASSESSED — a check the stage depends on did not run / FAIL — critical gaps block progress]
**Analysis Scope**: [Full project | Specific role: programmer/designer/producer]
----
-
-## Executive Summary
-
-[1-2 paragraph overview of project state, primary gaps, and recommended priority]
-
-**Current Focus**: [What the project is actively working on]
-**Blocking Issues**: [Critical gaps preventing progress]
-**Estimated Time to Next Stage**: [If applicable]
-
----
-
## Completeness Overview
-
-### Design Documentation
-- **Status**: [X%] complete
-- **Files Found**: [N] documents in `design/`
- - GDD sections: [N] files in `design/gdd/`
- - Narrative docs: [N] files in `design/narrative/`
- - Level designs: [N] files in `design/levels/`
-- **Key Gaps**:
- - [ ] [Missing doc 1 + why it matters]
- - [ ] [Missing doc 2 + why it matters]
-
-### Source Code
-- **Status**: [X%] complete
-- **Files Found**: [N] source files in `[code root]/` (`src/` Godot, `Assets/` Unity, `Source/` Unreal)
-- **Major Systems Identified**:
- - ✅ [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]
-
-### Architecture Documentation
-- **Status**: [X%] complete
-- **ADRs Found**: [N] decisions documented in `docs/architecture/`
-- **Coverage**:
- - ✅ [Decision area 1] — documented
- - ⚠️ [Decision area 2] — undocumented but implemented
- - ❌ [Decision area 3] — neither documented nor decided
-- **Key Gaps**:
- - [ ] [Missing ADR 1 + why it's needed]
- - [ ] [Missing ADR 2 + why it's needed]
-
-### Production Management
-- **Status**: [X%] complete
-- **Found**:
- - Sprint plans: [N] in `production/sprints/`
- - Milestones: [N] in `production/milestones/`
- - Roadmap: [Exists | Missing]
-- **Key Gaps**:
- - [ ] [Missing production artifact + impact]
-
-### Testing
-- **Status**: [X%] coverage (estimated)
-- **Test Files**: [N] in `tests/`
-- **Coverage by System**:
- - [System 1]: [X%] (estimated)
- - [System 2]: [X%] (estimated)
-- **Key Gaps**:
- - [ ] [Missing test area + risk]
-
-### Prototypes
-- **Active Prototypes**: [N] in `prototypes/`
- - ✅ [Prototype 1] — documented with REPORT.md
- - ⚠️ [Prototype 2] — no README, unclear status
-- **Archived**: [N] (experiments completed)
-- **Key Gaps**:
- - [ ] [Undocumented prototype + why it matters]
-
----
+- Design: [X%] ([N] docs, [gaps])
+- Code: [X%] ([N] files, [systems])
+- Architecture: [X%] ([N] ADRs, [gaps])
+- Production: [X%] ([status] — at `minimal`: stories complete in the brief's build order, never "no sprint plan")
+- Tests: [X%] ([coverage estimate])
## Stage Classification Rationale
+**Configured stage**: [`project.stage` in `project.yaml`, else `production/stage.txt`, else "not set"]
+**Observed stage**: [the stage the scanned artifacts indicate]
+[The indicators found for the observed stage. When the two stages disagree, say
+so: the configured stage may be stale, or work exists outside this repo. At
+`workflow: minimal` the configured stage is not advanced, so the lag is expected.]
-**Why [Stage]?**
-
-[Explain why the project is classified at this stage based on indicators found]
-
-**Indicators for this stage**:
-- [Indicator 1 that matches this stage]
-- [Indicator 2 that matches this stage]
-
-**Next stage requirements**:
-- [ ] [Requirement 1 to reach next stage]
-- [ ] [Requirement 2 to reach next stage]
-- [ ] [Requirement 3 to reach next stage]
-
----
-
-## Gaps Identified (with Clarifying Questions)
-
-### Critical Gaps (block progress)
-
-1. **[Gap Name]**
- - **Impact**: [Why this blocks progress]
- - **Question**: [Clarifying question before assuming solution]
- - **Suggested Action**: [What could be done, pending clarification]
-
-### Important Gaps (affect quality/velocity)
-
-2. **[Gap Name]**
- - **Impact**: [Why this matters]
- - **Question**: [Clarifying question]
- - **Suggested Action**: [Proposed solution]
-
-### Nice-to-Have Gaps (polish/best practices)
-
-3. **[Gap Name]**
- - **Impact**: [Minor but valuable]
- - **Question**: [Clarifying question]
- - **Suggested Action**: [Optional improvement]
-
----
+## Gaps Identified
+1. [Gap description + clarifying question]
+2. [Gap description + clarifying question]
## Recommended Next Steps
-
-### Immediate Priority (Do First)
-1. **[Action 1]** — [Why it's priority 1]
- - Suggested skill: `/[skill-name]` or manual work
- - Estimated effort: [S/M/L]
-
-2. **[Action 2]** — [Why it's priority 2]
- - Suggested skill: `/[skill-name]`
- - Estimated effort: [S/M/L]
-
-### Short-Term (This Sprint/Week)
-3. **[Action 3]** — [Why it's important soon]
-4. **[Action 4]** — [Why it's important soon]
-
-### Medium-Term (Next Milestone)
-5. **[Action 5]** — [Future need]
-6. **[Action 6]** — [Future need]
-
----
+[Priority-ordered list based on stage and role]
## Role-Specific Recommendations
-[If role filter was used, provide role-specific guidance]
-
-### For [Role]:
-- **Focus areas**: [What this role should prioritize]
-- **Blockers**: [What's blocking this role's work]
-- **Next tasks**:
- 1. [Task 1]
- 2. [Task 2]
-
----
+[Only when a role filter was given — the focus areas for that role]
## Follow-Up Skills to Run
-Based on gaps identified, consider running:
-
-- `/reverse-document [type] [path]` — [For which gap]
-- `/architecture-decision` — [For which gap]
-- `/sprint-plan` — [If production planning missing]
-- `/milestone-review` — [If approaching deadline]
-- `/onboard [role]` — [If new contributor joining]
-
----
+[Only skills for the gaps the project's workflow tier surfaces — e.g.
+`/map-systems` for a concept with no systems index, `/architecture-decision`
+for undocumented decisions, `/sprint-plan` when production planning is missing
+(not at `rigor: minimal`)]
## Appendix: File Counts by Directory
@@ -193,8 +63,4 @@ tests/ [N] test files
prototypes/ [N] directories
```
----
-
-**End of Report**
-
-*Generated by `/project-stage-detect` skill*
+*Generated by `/project-stage-detect`*
diff --git a/.claude/docs/templates/quick-design-change.md b/.claude/docs/templates/quick-design-change.md
new file mode 100644
index 00000000..e491e93d
--- /dev/null
+++ b/.claude/docs/templates/quick-design-change.md
@@ -0,0 +1,49 @@
+# Quick Design Spec: [Title]
+
+**Type**: [Tweak / Addition]
+**System**: [System name]
+**GDD Reference**: `design/gdd/[filename].md`
+**Date**: [today]
+
+## Change Summary
+
+[1-2 sentences describing what changes and why.]
+
+## Motivation
+
+[Why is this change needed? What player experience problem does it solve?
+Reference the relevant MDA aesthetic or player feedback if applicable.]
+
+## Design Delta
+
+Current GDD says (quoting `design/gdd/[filename].md`, [section]):
+
+> [exact quote of the relevant rule or description]
+
+This spec changes that to:
+
+[New rule or description, written with the same precision as a GDD Detailed
+Rules section. A programmer should be able to implement from this text alone.]
+
+## New Rules / Values
+
+[Full unambiguous statement of the replacement content. If this introduces
+new states, list them. If it introduces new parameters, define their ranges.]
+
+## Affected Systems
+
+| System | Impact | Action Required |
+|--------|--------|-----------------|
+| [system] | [how it is affected] | [update GDD / update data file / no action] |
+
+## Acceptance Criteria
+
+- [ ] [Specific, testable criterion 1]
+- [ ] [Specific, testable criterion 2]
+- [ ] [Specific, testable criterion 3]
+- [ ] No regression: [the original behavior this must not break]
+
+## GDD Update Required?
+
+[Yes / No]
+[If yes: which file, which section, and what the update should say.]
diff --git a/.claude/docs/templates/quick-design-new-system.md b/.claude/docs/templates/quick-design-new-system.md
new file mode 100644
index 00000000..42bcc868
--- /dev/null
+++ b/.claude/docs/templates/quick-design-new-system.md
@@ -0,0 +1,39 @@
+# Quick Design Spec: [Title]
+
+**Type**: New Small System
+**Scope**: [1-2 sentence description of what this system does and doesn't do]
+**Date**: [today]
+**Estimated Implementation**: [hours]
+
+## Overview
+
+[One paragraph a new team member could understand. What does this system do,
+when does it activate, and what does it produce?]
+
+## Core Rules
+
+[Unambiguous rules for the system. Use numbered lists for sequential behavior
+and bullet lists for conditions. Be precise enough that a programmer can
+implement without asking questions.]
+
+## Tuning Knobs
+
+| Knob | Default | Range | Category | Rationale |
+|------|---------|-------|----------|-----------|
+| [name] | [value] | [min–max] | [feel/curve/gate] | [why this default] |
+
+All values must live in `assets/data/[appropriate-file].json`, not hardcoded.
+
+## Acceptance Criteria
+
+- [ ] [Functional criterion: does the right thing]
+- [ ] [Functional criterion: handles the edge case]
+- [ ] [Experiential criterion: feels right — what a playtest validates]
+- [ ] [Regression criterion: does not break adjacent system]
+
+## Systems Index
+
+This system is not currently in `design/gdd/systems-index.md`.
+[If it should be added: suggest which layer and priority tier.]
+[If it is too small to track: state "This system is below systems-index
+tracking threshold — quick spec is sufficient."]
diff --git a/.claude/docs/templates/quick-design-tuning.md b/.claude/docs/templates/quick-design-tuning.md
new file mode 100644
index 00000000..9b785620
--- /dev/null
+++ b/.claude/docs/templates/quick-design-tuning.md
@@ -0,0 +1,24 @@
+# Quick Design Spec: [Title]
+
+**Type**: Tuning
+**System**: [System name]
+**GDD Reference**: `design/gdd/[filename].md` — Tuning Knobs section
+**Date**: [today]
+
+## Change
+
+| Parameter | Old Value | New Value | Rationale |
+|-----------|-----------|-----------|-----------|
+| [param] | [old] | [new] | [why] |
+
+## Tuning Knob Mapping
+
+Maps to GDD Tuning Knob: [knob name and its documented range].
+New value is [within / at the edge of / outside] the documented range.
+[If outside: explain why the range should be extended.]
+
+## Acceptance Criteria
+
+- [ ] [Parameter] reads [new value] from `assets/data/[file]`
+- [ ] Behavior difference is observable in [specific context]
+- [ ] No regression in [related behavior]
diff --git a/.claude/docs/templates/release-checklist-template.md b/.claude/docs/templates/release-checklist-template.md
index e093c179..b78c1efd 100644
--- a/.claude/docs/templates/release-checklist-template.md
+++ b/.claude/docs/templates/release-checklist-template.md
@@ -1,130 +1,91 @@
-# Release Checklist: [Version] -- [Platform]
+## Release Checklist: [Version] -- [Platform]
+Generated: [Date]
-**Release Date**: [Target Date]
-**Release Manager**: [Name]
-**Status**: [ ] GO / [ ] NO-GO
-
----
-
-## Build Verification
+### Codebase Health
+- Scanned: [N] source files (or `NOT ASSESSED — [reason]`, per Phase 3)
+- TODO count: [N] ([list top 5 if many])
+- FIXME count: [N] ([list all -- these are potential blockers])
+- HACK count: [N] ([list all -- these need review])
+### Build Verification
- [ ] Clean build succeeds on all target platforms
- [ ] No compiler warnings (zero-warning policy)
-- [ ] Build version number set correctly: `[version]`
-- [ ] Build is reproducible from tagged commit: `[commit hash]`
-- [ ] Build size within budget: [actual] / [budget]
- [ ] All assets included and loading correctly
-- [ ] No debug/development features enabled in release build
-
----
-
-## Quality Gates
-
-### Critical Bugs
-- [ ] Zero S1 (Critical) bugs open
-- [ ] Zero S2 (High) bugs -- or documented exceptions below (no exceptions at `workflow: full`):
-- [ ] Zero S3 (Medium) bugs open -- required at `workflow: full`
+- [ ] Build size within budget ([target size])
+- [ ] Build version number correctly set ([version])
+- [ ] Build is reproducible from tagged commit
+
+### Quality Gates
+- Open bugs (`production/qa/bugs/`): [N] S1, [N] S2, [N] S3 -- or `NOT ASSESSED — no bug records`
+- [ ] Zero open S1 (Critical) bugs
+- [ ] Zero open S2 (High) bugs, no exceptions -- this row at `workflow: full` only; at `standard`/`minimal` open S2 bugs go in the Rationale as risks
+- [ ] Zero S3 (Medium) bugs open, no exceptions -- this row at `workflow: full` only; at `standard`/`minimal` open S3 bugs go in the Rationale as risks
+- [ ] All critical path features tested and signed off by QA
+- [ ] Performance within budgets:
+ - [ ] Target FPS met on minimum spec hardware
+ - [ ] Memory usage within budget
+ - [ ] Load times within budget
+ - [ ] No memory leaks over extended play sessions
+- [ ] No regression from previous build
+- [ ] Soak test passed (4+ hours continuous play)
> 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 |
-| ---- | ---- | ---- | ---- |
-| | | | |
-
-### Test Coverage
-- [ ] All critical path features tested and signed off
-- [ ] Full regression suite passed: [pass rate]%
-- [ ] Soak test passed (4+ hours continuous play)
-- [ ] Edge case testing complete
-
-### Performance
-- [ ] Target FPS met on minimum spec: [actual] / [target] FPS
-- [ ] Memory usage within budget: [actual] / [budget] MB
-- [ ] Load times within budget: [actual] / [target] seconds
-- [ ] No memory leaks over extended play (soak test)
-- [ ] No frame drops below [threshold] in normal gameplay
-
----
-
-## Content Complete
+> S2 or S3 is a risk to record in the Rationale.
+### Content Complete
- [ ] All placeholder assets replaced with final versions
+- [ ] All TODO/FIXME in content files resolved or documented
- [ ] All player-facing text proofread
- [ ] All text localization-ready (no hardcoded strings)
-- [ ] Localization complete for: [list locales]
- [ ] Audio mix finalized and approved
- [ ] Credits complete and accurate
-- [ ] Legal notices and third-party attributions complete
-
----
-
-## Platform: PC
-- [ ] Minimum and recommended specs documented
-- [ ] Keyboard+mouse controls fully functional
-- [ ] Controller support tested (Xbox, PlayStation, generic)
-- [ ] Resolution scaling tested: 1080p, 1440p, 4K, ultrawide
-- [ ] Windowed, borderless, fullscreen modes working
-- [ ] Graphics settings save and load correctly
-- [ ] Store SDK integrated and tested: [Steam/Epic/GOG]
-- [ ] Achievements functional
-- [ ] Cloud saves functional
+[Platform Requirements: one block per device the platform argument names (`pc`, `console`, `mobile`; `all` is all three), copied from `release-platform-requirements.md`]
-## Platform: Console (if applicable)
-
-- [ ] TRC/TCR/Lotcheck requirements met
-- [ ] Platform controller prompts correct
-- [ ] Suspend/resume works
-- [ ] User switching handled
-- [ ] Network loss handled gracefully
-- [ ] Storage full scenario handled
-- [ ] Parental controls respected
-- [ ] Certification submission prepared
-
----
-
-## Store and Distribution
+[Certification: the one block for this project's `platform.cert_tier`, copied from `certification-none.md`, `certification-itch.md`, `certification-steam.md` or `certification-console.md`; `certification-unknown.md` when the tier cannot be determined]
+### Store / Distribution
- [ ] Store page metadata complete and proofread
-- [ ] Screenshots current and meet platform requirements
-- [ ] Trailer current
-- [ ] Key art and capsule images final
-- [ ] Age ratings obtained: [ ] ESRB [ ] PEGI [ ] Other
-- [ ] Legal: EULA, Privacy Policy, Terms of Service
+ - [ ] Short description
+ - [ ] Long description
+ - [ ] Feature list
+ - [ ] System requirements (PC)
+- [ ] Screenshots up to date and per-platform resolution requirements met
+- [ ] Trailers up to date
+- [ ] Key art and capsule images current
+- [ ] Age rating obtained and configured:
+ - [ ] ESRB
+ - [ ] PEGI
+ - [ ] Other regional ratings as required
+- [ ] Legal notices, EULA, and privacy policy in place
+- [ ] Third-party license attributions complete
- [ ] Pricing configured for all regions
----
-
-## Launch Readiness
-
-- [ ] Analytics/telemetry verified and receiving data
-- [ ] Crash reporting configured: [service name]
-- [ ] Day-one patch prepared (if needed)
+### Launch Readiness
+- [ ] Analytics / telemetry verified and receiving data
+- [ ] Crash reporting configured and dashboard accessible
+- [ ] Day-one patch prepared and tested (if needed)
- [ ] On-call team schedule set for first 72 hours
-- [ ] Community announcements drafted
-- [ ] Press/influencer keys prepared
-- [ ] Support team briefed on known issues
-- [ ] Rollback plan documented and tested
-
----
-
-## Sign-offs
-
-| Role | Name | Status | Date |
-| ---- | ---- | ---- | ---- |
-| QA Lead | | [ ] Approved | |
-| Technical Director | | [ ] Approved | |
-| Producer | | [ ] Approved | |
-| Creative Director | | [ ] Approved | |
-
----
-
-## Final Decision
-
-**GO / NO-GO**: ____________
-
-**Rationale**: [Summary of readiness. If NO-GO, list specific blocking items and estimated time to resolve.]
-
-**Notes**: [Any additional context, known risks accepted, or conditions on the release.]
+- [ ] Community launch announcements drafted
+- [ ] Press/influencer keys prepared for distribution
+- [ ] Support team briefed on known issues and FAQ
+- [ ] Rollback plan documented (if critical issues found post-launch)
+
+### Go / No-Go: [READY / NOT ASSESSED / NOT READY]
+
+First match wins: **NOT READY** if any blocking item fails; else **NOT ASSESSED**
+if any section or item came out `NOT ASSESSED` (name each one); else **READY**. NOT
+ASSESSED outranks READY — an unassessed section is not a passed one — and ranks
+below NOT READY, so a known blocker is never buried behind it.
+
+**Rationale:**
+[Summary of readiness assessment. List any blocking items that must be
+resolved before launch. If NOT READY, list the specific items that need
+resolution and estimated time to address them.]
+
+**Sign-offs Required:**
+- [ ] QA Lead
+- [ ] Technical Director
+- [ ] Producer
+- [ ] Creative Director
diff --git a/.claude/docs/templates/release-notes.md b/.claude/docs/templates/release-notes.md
index 6771809c..310b1741 100644
--- a/.claude/docs/templates/release-notes.md
+++ b/.claude/docs/templates/release-notes.md
@@ -1,103 +1,37 @@
-# Release Notes: [Game Title] v[Version]
+# Patch [Version] — [Title]
+*[Date]*
-*Released: [Date]*
+## Highlights
+[1-2 sentence summary of the most exciting changes]
----
-
-## Headline
-
-> [One compelling sentence summarizing the most exciting part of this release.
-> This is what appears in store update notifications and social media.]
-
----
-
-## What's New
-
-### [Major Feature 1 Name]
-[2-4 sentences describing the feature. Focus on what players can DO, not
-how it works internally. Include a screenshot or GIF reference if applicable.]
-
-### [Major Feature 2 Name]
-[Description]
-
----
+## New Content
+### [Feature Name]
+[2-3 sentences describing the feature and why players should be excited]
## Gameplay Changes
+### Balance
+| Change | Before | After | Reason |
+| ---- | ---- | ---- | ---- |
+| [Item/ability] | [old value] | [new value] | [brief rationale] |
-### Balance Adjustments
-
-| Target | Change | Before | After | Context |
-| ---- | ---- | ---- | ---- | ---- |
-| [Weapon/Ability/Item] | [What changed] | [Old value] | [New value] | [Why — 1 sentence] |
-| | | | | |
-
-### Mechanic Changes
-- **[Change Name]**: [What changed and how it affects gameplay. Be specific
- about what players will experience differently.]
-
----
+### Mechanics
+- **[Change]**: [explanation of what changed and why]
## Quality of Life
-
-- [Improvement 1 — describe the player benefit, not the technical change]
-- [Improvement 2]
-- [Improvement 3]
-
----
+- [Improvement with context]
## Bug Fixes
+### Combat
+- Fixed [description of what players experienced]
-### Critical Fixes
-- Fixed [describe what players experienced, e.g., "a crash when loading
- saved games from version 1.0"]
-
-### Gameplay Fixes
-- Fixed [describe the incorrect behavior and the correct behavior now]
-
-### UI Fixes
+### UI
- Fixed [description]
-### Audio Fixes
+### Networking
- Fixed [description]
-### Platform-Specific Fixes
-- **[Platform]**: Fixed [description]
-
----
-
-## Performance Improvements
-
-- [Improvement players will notice, e.g., "Reduced load times by approximately
- 30% on all platforms"]
-- [Improvement]
-
----
+## Performance
+- [Improvement players will notice]
## Known Issues
-
-We are aware of the following issues and are working on fixes for a future update:
-
-- **[Issue]**: [Brief description and workaround if available]
-- **[Issue]**: [Description]
-
----
-
-## Coming Next
-
-[Optional — tease upcoming content to build anticipation. Keep it vague enough
-to not create binding commitments.]
-
-> [1-2 sentences about what the team is working on next]
-
----
-
-## Thank You
-
-[Brief message thanking the community. Reference specific community feedback
-that influenced changes in this release if applicable.]
-
----
-
-*For the full changelog with technical details, see the [developer changelog](link).*
-*Report bugs: [link to bug report channel/form]*
-*Join the community: [link to Discord/forum]*
+- [Issue and workaround if available]
diff --git a/.claude/docs/templates/release-platform-requirements.md b/.claude/docs/templates/release-platform-requirements.md
new file mode 100644
index 00000000..b31f8310
--- /dev/null
+++ b/.claude/docs/templates/release-platform-requirements.md
@@ -0,0 +1,33 @@
+# Platform Requirements
+
+One block per device the release checklist's platform argument names (`pc`,
+`console`, `mobile`; `all` is all three). Copy only the blocks named. They hold
+no certification or store-SDK rows: those are in the `certification-<tier>.md`
+templates, chosen by `platform.cert_tier`, not by the device.
+
+### Platform Requirements: PC
+- [ ] Minimum and recommended specs verified and documented
+- [ ] Keyboard+mouse controls fully functional
+- [ ] Controller support tested (Xbox, PlayStation, generic)
+- [ ] Resolution scaling tested (1080p, 1440p, 4K, ultrawide)
+- [ ] Windowed, borderless, and fullscreen modes working
+- [ ] Graphics settings save and load correctly
+
+### Platform Requirements: Console
+- [ ] Platform-specific controller prompts display correctly
+- [ ] Suspend/resume works correctly
+- [ ] User switching handled properly
+- [ ] Network connectivity loss handled gracefully
+- [ ] Storage full scenario handled
+
+### Platform Requirements: Mobile
+- [ ] App store guidelines compliance verified
+- [ ] All required device permissions justified and documented
+- [ ] Privacy policy linked and accurate
+- [ ] Data safety/nutrition labels completed
+- [ ] Touch controls tested on multiple screen sizes
+- [ ] Battery usage within acceptable range
+- [ ] Background behavior correct (pause, resume, terminate)
+- [ ] Push notification permissions handled correctly
+- [ ] In-app purchase flow tested (if applicable)
+- [ ] App size within store limits
diff --git a/.claude/docs/templates/session-state.md b/.claude/docs/templates/session-state.md
index e4529e70..5b342814 100644
--- a/.claude/docs/templates/session-state.md
+++ b/.claude/docs/templates/session-state.md
@@ -64,9 +64,12 @@ or agent picking this up cold.]
CHECKPOINT block
The recovery payload. `session-start.sh` shows it when a previous session
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.
+ It reads THIS region and nothing else, which is what keeps the cost fixed
+ no matter how long the narrative gets.
+
+ Keep `Branch` current. This file is not committed, so it stays put when you
+ switch branches; session-start.sh compares `Branch` with the branch you are
+ on and adds one line when they differ.
Write it so a cold reader can resume without reading anything else. "Current
task: fixing the thing" is useless; "Current task: adding wall-jump to
diff --git a/.claude/docs/templates/soak-test-protocol.md b/.claude/docs/templates/soak-test-protocol.md
new file mode 100644
index 00000000..a8aa9b84
--- /dev/null
+++ b/.claude/docs/templates/soak-test-protocol.md
@@ -0,0 +1,132 @@
+# Soak Test Protocol
+
+> **Date**: [date]
+> **Duration**: [duration]
+> **Focus**: [memory | stability | balance | all]
+> **Engine**: [engine]
+> **Generated by**: /soak-test
+
+---
+
+## Pre-Session Setup
+
+Before starting the soak:
+
+- [ ] Game is running from a **fresh launch** (not resumed from a prior session)
+- [ ] All background applications closed (minimise OS memory interference)
+- [ ] Performance monitoring tool open and recording:
+ - **Godot**: Debugger → Monitors tab → Memory section visible
+ - **Unity**: Memory Profiler window open
+ - **Unreal**: `stat memory` ready in console
+ - Tool actually used, as named in this editor: [record it — the names above
+ are NOT SOURCEABLE from `docs/engine-reference/`; none found → NOT ASSESSED]
+- [ ] Soak target confirmed: [session design intent from game concept]
+- [ ] Prior known issues to watch for: [from most recent playtest / qa-plan]
+
+---
+
+## Baseline (T+0) — Record Before Playing
+
+| Metric | Baseline Value |
+|--------|---------------|
+| Memory / Heap | [record before first frame of gameplay] |
+| Object Count | [record] |
+| FPS (first 30 seconds) | [record] |
+| [Engine-specific metric] | [record] |
+
+---
+
+## Checkpoint Log
+
+### T+[N] minutes
+
+**Memory / Stability** *(if applicable)*:
+
+| Metric | Value | Δ from Baseline | Alert? |
+|--------|-------|-----------------|--------|
+| Memory / Heap | | | |
+| Object Count | | | |
+| FPS | | | |
+| Crashes / Hangs | | | |
+
+**Stability checks**:
+- [ ] No crash or hang since last checkpoint
+- [ ] Frame rate within budget ([N] fps target)
+- [ ] Audio correct
+- [ ] HUD rendering correctly
+- [ ] Input responding correctly
+
+**Balance / Fatigue** *(if applicable)*:
+- Core mechanic still rewarding: Y / N
+- Difficulty perception: too easy / appropriate / too hard
+- Notable moments: [note any peak engagement or frustration]
+- Content exhaustion signs: Y / N — [describe]
+
+**Free observations**:
+*(Note anything unexpected observed since the last checkpoint)*
+
+---
+
+[Repeat Checkpoint Log section for each timed checkpoint]
+
+---
+
+## Post-Session Analysis
+
+### Memory Trend
+
+| Checkpoint | Memory | Δ/hr extrapolated |
+|------------|--------|-------------------|
+| T+0 | | |
+| [T+N] | | |
+
+**Leak detected?** Y / N
+**Estimated time to OOM at current rate**: [N hours / not applicable]
+
+### Stability Summary
+
+Total crashes: [N]
+Total hangs: [N]
+Worst FPS observed: [N] fps at [checkpoint]
+Performance degradation: stable / mild / severe
+
+### Balance / Fatigue Summary
+
+Fun curve: [engaged throughout / fatigue onset at T+N / repetitive from start]
+Content exhaustion point: [never / at T+N / early]
+Difficulty arc: [appropriate / too easy throughout / difficulty spike at T+N]
+
+### Issues Found
+
+| ID | Severity | Checkpoint | Description |
+|----|----------|------------|-------------|
+| SOAK-001 | S[1-4] | T+[N] | [description] |
+
+---
+
+## Verdict: PASS / PASS WITH CONCERNS / NOT ASSESSED / FAIL
+
+**PASS**: No leaks detected, stability maintained, fun factor consistent
+**PASS WITH CONCERNS**: Minor drift or fatigue noted; addressable in Polish
+**NOT ASSESSED**: The soak did not run to a length that could show what it looks
+for — say how far it got and which checkpoints were never reached
+**FAIL**: Memory leak confirmed, stability breach, or severe fun fatigue
+
+> **A short soak cannot return PASS.** Everything this protocol exists to detect
+> — slow leaks, fatigue, late-appearing edge cases — is by definition invisible
+> early, so a session that ended before the checkpoints it was built around has
+> not shown stability; it has shown nothing yet. Record `NOT ASSESSED — reached
+> T+[N] of [duration]; checkpoints [list] not reached`. Ranks **above both pass
+> values** and **below FAIL**: a crash observed at T+20 is a real finding no
+> matter how short the run, and must not be demoted behind the run's length.
+> The same applies when the build crashed for reasons unrelated to the soak, when
+> no memory instrumentation was available (nothing was measured, so "no leaks
+> detected" means "no leaks could have been detected"), or when the protocol was
+> written but never executed — a protocol document is not a result.
+
+---
+
+## Sign-Off
+
+- **Tester**: [name] — [date]
+- **QA Lead review**: [name] — [date]
diff --git a/.claude/docs/templates/sprint-plan.md b/.claude/docs/templates/sprint-plan.md
index 631e17b6..1741f76b 100644
--- a/.claude/docs/templates/sprint-plan.md
+++ b/.claude/docs/templates/sprint-plan.md
@@ -1,59 +1,48 @@
# Sprint [N] — [Start Date] to [End Date]
## Sprint Goal
+[One sentence describing what this sprint achieves toward the milestone]
-[One sentence: what does this sprint achieve toward the current milestone?]
+## Goal Prerequisites
+| Needed to show the goal | Status |
+|-------------------------|--------|
## Milestone Context
-
-- **Current Milestone**: [Name]
-- **Milestone Deadline**: [Date]
-- **Sprints Remaining**: [N]
+- Current Milestone: [Name]
+- Milestone Deadline: [Date]
+- Sprints Remaining: [N]
## Capacity
-
-- **Total days**: [X]
-- **Buffer (20%)**: [Y days reserved for unplanned work]
-- **Available**: [Z days]
+- Total days: [X]
+- Buffer (20%): [Y days reserved for unplanned work]
+- Available: [Z days]
## Tasks
### Must Have (Critical Path)
-
-| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria | Status |
-|----|------|-------------|-----------|-------------|-------------------|--------|
-| S[N]-001 | | | | None | | Not Started |
-| S[N]-002 | | | | S[N]-001 | | Not Started |
+| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria |
+|----|------|-------------|-----------|-------------|-------------------|
### Should Have
+| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria |
+|----|------|-------------|-----------|-------------|-------------------|
-| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria | Status |
-|----|------|-------------|-----------|-------------|-------------------|--------|
-| S[N]-010 | | | | | | Not Started |
-
-### Nice to Have (Cut First)
-
-| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria | Status |
-|----|------|-------------|-----------|-------------|-------------------|--------|
-| S[N]-020 | | | | | | Not Started |
+### Nice to Have
+| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria |
+|----|------|-------------|-----------|-------------|-------------------|
-## Carryover from Sprint [N-1]
+## Carryover from Previous Sprint
+| Task | Reason | New Estimate |
+|------|--------|-------------|
-| Original ID | Task | Reason for Carryover | New Estimate | Priority Change |
-|------------|------|---------------------|-------------|----------------|
+## Risks
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
-## Risks to This Sprint
-
-| Risk | Probability | Impact | Mitigation | Owner |
-|------|------------|--------|-----------|-------|
-
-## External Dependencies
-
-| Dependency | Status | Impact if Delayed | Contingency |
-|-----------|--------|------------------|-------------|
-
-## Definition of Done
+## Dependencies on External Factors
+- [List any external dependencies]
+## Definition of Done for this Sprint
- [ ] All Must Have tasks completed
- [ ] All tasks pass acceptance criteria
- [ ] QA plan exists (`production/qa/qa-plan-[sprint-slug]-[date].md`, from `/qa-plan sprint`)
@@ -63,4 +52,3 @@
- [ ] No S1 or S2 bugs in delivered features
- [ ] Design documents updated for any deviations
- [ ] Code reviewed and merged
-
diff --git a/.claude/docs/templates/sprint-status.yaml b/.claude/docs/templates/sprint-status.yaml
new file mode 100644
index 00000000..4bf0a682
--- /dev/null
+++ b/.claude/docs/templates/sprint-status.yaml
@@ -0,0 +1,28 @@
+# Auto-generated by /sprint-plan. Updated by /story-done and /dev-story.
+# DO NOT edit manually — use /story-done to update story status.
+#
+# Status value mapping (yaml ↔ story file Status field):
+# backlog ↔ Not Started
+# ready-for-dev ↔ Ready
+# in-progress ↔ In Progress
+# review ↔ In Review
+# done ↔ Complete
+# blocked ↔ Blocked
+
+sprint: [N]
+goal: "[sprint goal]"
+start: "[YYYY-MM-DD]"
+end: "[YYYY-MM-DD]"
+generated: "[YYYY-MM-DD]"
+updated: "[YYYY-MM-DD]"
+
+stories:
+ - id: "[epic-story, e.g. 1-1]"
+ name: "[story name]"
+ file: "[production/epics/[epic-slug]/story-NNN-[slug].md]" # the real path, verbatim from the Glob above
+ priority: must-have # must-have | should-have | nice-to-have
+ status: ready-for-dev # backlog | ready-for-dev | in-progress | review | done | blocked
+ owner: ""
+ estimate_days: 0
+ blocker: ""
+ completed: ""
diff --git a/.claude/docs/templates/start-paths.md b/.claude/docs/templates/start-paths.md
new file mode 100644
index 00000000..0067ed09
--- /dev/null
+++ b/.claude/docs/templates/start-paths.md
@@ -0,0 +1,41 @@
+# Your Path
+
+Here's your path at rigor `[value]`. Every skill still runs at any rigor; rigor changes
+what's required, not what's allowed.
+
+**`minimal`: 4 steps to running code**
+1. `/setup-engine`: choose and configure the engine
+2. `/brainstorm`: write the one-page `design/game-brief.md`
+3. `/create-stories`: turn the brief's MVP list into stories (no epics or sprint plan needed)
+4. `/dev-story`: the first line of game code
+
+**`standard`**
+- Concept: `/setup-engine` → `/brainstorm` → `/prototype` → `/art-bible` → `/gate-check`
+- Systems Design: `/map-systems` → `/design-system` (once per system) → `/review-all-gdds` →
+ `/gate-check`
+- Architecture: `/create-architecture` → `/architecture-decision` (once per decision) →
+ `/create-control-manifest` → `/architecture-review` → `/test-setup` → `/ux-design`
+ (accessibility and interaction patterns) → `/gate-check`
+- Pre-Production: `/ux-design` (HUD and key screens) → `/create-epics` → `/create-stories` →
+ `/sprint-plan` → `/gate-check`
+- Production: `/dev-story`
+
+Each `/gate-check` moves the project one stage, and only when it passes.
+
+**`full`:** everything in `standard`, plus `/vertical-slice` and `/playtest-report` in
+Pre-Production and `/design-review` after each GDD.
+
+**Path D with existing work** (stage `Systems Design` or later, or code on disk) gets this instead.
+Print only the steps that apply, and for the brief only the one source that applies. At `minimal`:
+1. `/project-stage-detect`: what stage the project is at and what is missing
+2. `/adopt`: whether the existing files are in the format the skills read
+3. `/setup-engine`: only when no engine is set; leave it out when `engine` names one
+4. The brief, only if `concept` is absent: `/reverse-document design [code_root]` when the code
+ root holds 10 or more source files (it writes the brief from the game), and then do not mention
+ `/brainstorm` at all; `/brainstorm` only when it holds fewer
+
+At `standard` and `full`, steps 1 to 3, then `/design-system retrofit [path]`,
+`/architecture-decision retrofit [path]`, `/architecture-review` and `/gate-check`.
+
+`minimal` is the documented floor, not a lesser mode. Its trade: no GDDs, so design
+problems show up in code.
diff --git a/.claude/docs/templates/story.md b/.claude/docs/templates/story.md
new file mode 100644
index 00000000..02372385
--- /dev/null
+++ b/.claude/docs/templates/story.md
@@ -0,0 +1,109 @@
+# Story [NNN]: [title]
+
+> **Epic**: [epic name]
+> **Status**: [Ready | Blocked — BLOCKED: <reason>]
+> **Layer**: [Foundation / Core / Feature / Presentation]
+> **Type**: [Logic | Integration | Visual/Feel | UI | Config/Data]
+> **Estimate**: [S | M | L, or hours — /create-stories proposes one]
+> **Manifest Version**: [date from control-manifest.md header]
+> **Last Updated**: [set by /dev-story when implementation begins]
+
+## Context
+
+**GDD**: `design/gdd/[filename].md`
+**Requirement**: `TR-[system]-NNN`
+*(Requirement text lives in `docs/architecture/tr-registry.yaml` — read fresh at review time)*
+
+**ADR Governing Implementation**: [ADR-NNNN: title]
+**ADR Decision Summary**: [1-2 sentence summary of what the ADR decided]
+**ADR Version**: [the ADR's `## Last Verified` date, else its `## Date`, else `unversioned`]
+
+**Engine**: [name + version] | **Risk**: [LOW / MEDIUM / HIGH]
+**Engine Notes**: [from ADR Engine Compatibility section — post-cutoff APIs, verification required]
+
+**Control Manifest Rules (this layer)**:
+- Required: [relevant required pattern]
+- Forbidden: [relevant forbidden pattern]
+- Guardrail: [relevant performance guardrail]
+
+---
+
+## Acceptance Criteria
+
+*From GDD `design/gdd/[filename].md`, scoped to this story:*
+
+- [ ] [criterion 1 — directly from GDD]
+- [ ] [criterion 2]
+- [ ] [performance criterion if applicable]
+
+---
+
+## Implementation Notes
+
+*Derived from ADR-NNNN Implementation Guidelines:*
+
+[Specific, actionable guidance from the ADR. Do not paraphrase in ways that
+change meaning. This is what the programmer reads instead of the ADR.]
+
+---
+
+## Out of Scope
+
+*Handled by neighbouring stories — do not implement here:*
+
+- [Story NNN+1]: [what it handles]
+
+---
+
+## Files
+
+*The code and test files this story creates or changes. `/create-stories` lists the
+planned ones; `/dev-story` replaces the list with the files it changed; `/story-done`
+checks scope against it.*
+
+- [path under the code root]
+- [test path]
+
+---
+
+## QA Test Cases
+
+*Written by qa-lead at story creation. The developer implements against these — do not invent new test cases during implementation. (At tiers where the QL-STORY-READY gate is skipped — `minimal`, or `lean`/`solo` review mode — no qa-lead specs exist, and this section reads: N/A — no qa-lead specs at this tier; implement against the Acceptance Criteria above.)*
+
+**[For Logic / Integration stories — automated test specs]:**
+
+- **AC-1**: [criterion text]
+ - Given: [precondition]
+ - When: [action]
+ - Then: [assertion]
+ - Edge cases: [boundary values / failure states]
+
+**[For Visual/Feel / UI stories — manual verification steps]:**
+
+- **AC-1**: [criterion text]
+ - Setup: [how to reach the state]
+ - Verify: [what to look for]
+ - Pass condition: [unambiguous pass description]
+
+---
+
+## Test Evidence
+
+*Governed by `qa.level`: at `qa.level: minimal` tests are **waived** (advisory, never "must exist and pass"), but a Visual/Feel or UI story's retained screenshot is not.*
+
+**Story Type**: [type]
+**Required evidence**:
+- Logic: `tests/unit/[system]/[story-slug]_test.[ext]` — must exist and pass (`/story-done` checks that it EXISTS; pass/fail is established by `/gate-check` and `/smoke-check`, both later)
+- Integration: `tests/integration/[system]/[story-slug]_test.[ext]` OR playtest doc
+- Visual/Feel: a retained screenshot in `production/qa/evidence/` + sign-off in `production/qa/evidence/[story-slug]-evidence.md`
+- UI: a retained screenshot of each screen touched, in `production/qa/evidence/`
+- Config/Data: smoke check pass (`production/qa/smoke-*.md`)
+
+**Status**: [ ] Not yet created
+
+---
+
+## Dependencies
+
+- Depends on: [the path of each story that must be DONE first, e.g. `production/epics/<epic>/story-001-<slug>.md`, or "None"]
+- Unlocks: [the path of each story this one unblocks, or "None"]
diff --git a/.claude/docs/templates/technical-design-document.md b/.claude/docs/templates/technical-design-document.md
index 900ac58e..00df6254 100644
--- a/.claude/docs/templates/technical-design-document.md
+++ b/.claude/docs/templates/technical-design-document.md
@@ -12,7 +12,7 @@
| Field | Value |
|-------|-------|
-| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.7] |
+| **Engine** | [e.g. Godot 4.7 / Unity 6 / Unreal Engine 5.8] |
| **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"] |
diff --git a/.claude/docs/templates/test-plan.md b/.claude/docs/templates/test-plan.md
index 40a985ea..afbbffd8 100644
--- a/.claude/docs/templates/test-plan.md
+++ b/.claude/docs/templates/test-plan.md
@@ -1,14 +1,13 @@
# QA Plan: [Sprint/Feature Name]
-
-> **Date**: [date]
-> **Generated by**: /qa-plan
-> **Scope**: [N stories across N systems]
-> **Engine**: [engine name and version]
-> **Sprint file**: [path to sprint plan]
+**Date**: [date]
+**Generated by**: /qa-plan
+**Scope**: [N stories across [N systems]]
+**Engine**: [engine name — `engine.name` from project.yaml if present and non-empty, else the Engine field from .claude/docs/technical-preferences.md, else "Not configured"]
+**Sprint File**: [path to sprint plan if applicable]
---
-## Story Coverage Summary
+## Test Summary
| Story | Type | Automated Test Required | Manual Verification Required |
|-------|------|------------------------|------------------------------|
@@ -16,7 +15,7 @@
| [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 (verified by its screenshots) | Retained screenshot of each screen touched |
-| [story title] | Config/Data | Data validation (optional) | Spot-check in-game values |
+| [story title] | Config/Data | Data validation test | Spot-check in-game values |
**Totals**: [N] Logic, [N] Integration, [N] Visual/Feel, [N] UI, [N] Config/Data
@@ -24,65 +23,63 @@
## Automated Tests Required
-### [Story Title] — Logic
-
-**Test file path**: `tests/unit/[system]/[story-slug]_test.[ext]`
+*(At `qa.level: minimal`, omit this entire section and blank the Test Summary's
+"Automated Test Required" column — automated tests are not required there; list
+manual/smoke verification only.)*
+### [Story Title] — [Type]
+**Test file path**: `tests/[unit|integration]/[system]/[story-slug]_test.[ext]`
**What to test**:
-- [Formula or rule from GDD Formulas section — e.g., "damage = base * multiplier where multiplier ∈ [0.5, 3.0]"]
-- [Each named state transition]
-- [Each side effect that should / should not occur]
+- [Specific formula or rule from the GDD Formulas section]
+- [Each named state transition or decision branch]
+- [Each side effect that should or should not occur]
**Edge cases to cover**:
-- Zero / minimum input values
-- Maximum / boundary input values
-- Invalid or null input
-- [GDD-specified edge cases]
+- Zero/minimum input values (e.g., 0 damage, empty inventory)
+- Maximum/boundary input values (e.g., max level, stat cap)
+- Invalid or null input (e.g., missing target, dead entity)
+- [Any edge case explicitly called out in the GDD Edge Cases section]
**Estimated test count**: ~[N] unit tests
----
-
-### [Story Title] — Integration
-
-**Test file path**: `tests/integration/[system]/[story-slug]_test.[ext]`
-
-**What to test**:
-- [Cross-system interaction — e.g., "applying buff updates CharacterStats and triggers UI refresh"]
-- [Round-trip — e.g., "save → load restores all fields"]
+[If no GDD formula reference was found for this story, note:]
+*No formula found in referenced GDD — test cases must be derived from acceptance
+criteria directly. Review the GDD Formulas section before writing tests.*
---
## Manual QA Checklist
-### [Story Title] — Visual/Feel
-
-**Verification method**: Screenshot + [designer / art-director] sign-off
-**Evidence file**: `production/qa/evidence/[story-slug]-evidence.md`
-**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**: Retained screenshot of each screen touched
-**Evidence**: `production/qa/evidence/[story-slug]/[NN]-[what-it-shows].png`, one per screen
+### [Story Title] — [Type]
+**Verification method**: [Screenshot + designer sign-off | Playtest session |
+Manual step-through | Comparison against reference footage]
+**Who must sign off**: [designer / lead-programmer / qa-lead / art-director]
+**Evidence to capture**: [screenshot of X | video clip of Y | written playtest
+notes | side-by-side comparison]
+Checklist:
+- [ ] [Specific observable condition — concrete and falsifiable]
+- [ ] [Another condition]
- [ ] [Every acceptance criterion translated into a manual check item]
+*If any criterion uses subjective language ("feels", "looks", "seems"), it must
+be supplemented with a specific benchmark or a playtest protocol note.*
+
---
## Smoke Test Scope
-Critical paths to verify before QA hand-off (run via `/smoke-check`):
+Critical paths to verify before any QA hand-off for this sprint:
1. Game launches to main menu without crash
-2. New game / session can be started
+2. New game / new session can be started
3. [Primary mechanic introduced or changed this sprint]
-4. [System with regression risk from this sprint's changes]
+4. [Any system with a regression risk from this sprint's changes]
5. Save / load cycle completes without data loss (if save system exists)
-6. Performance is within budget on target hardware
+6. Performance is within budget on target hardware (no new frame spikes)
+
+*Smoke tests are verified by the developer via `/smoke-check`. Reference this
+list when running that skill.*
---
@@ -90,34 +87,35 @@ Critical paths to verify before QA hand-off (run via `/smoke-check`):
| Story | Playtest Goal | Min Sessions | Target Player Type |
|-------|--------------|--------------|-------------------|
-| [story] | [What question must be answered?] | [N] | [new player / experienced / etc.] |
+| [story] | [What question must the session answer?] | [N] | [new player / experienced] |
-Sign-off requirement: Playtest notes → `production/session-logs/playtest-[sprint]-[story-slug].md`
+**Sign-off requirement**: Playtest notes must be written with `/playtest-report` to
+`production/qa/playtests/` (naming the story) and reviewed by
+the [designer / qa-lead] before the story can be marked COMPLETE.
-If no playtest sessions required: *No playtest sessions required for this sprint.*
+If no stories require playtest validation: *No playtest sessions required for
+this sprint.*
---
## Definition of Done — This Sprint
-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
-- [ ] 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
+A story is DONE when ALL of the following are true (at `qa.level: minimal`, drop
+the test-file and smoke rows below — tests are waived there; the screenshot and
+sign-off rows stay at every level, because the look is not):
+
+- [ ] All acceptance criteria verified — via automated test result OR documented
+ manual evidence (screenshot, video, or playtest notes with sign-off)
+- [ ] Test file exists at the specified path for all Logic and Integration stories *(qa.level standard/full)*
+- [ ] Retained screenshot of each screen touched, in `production/qa/evidence/`, for all Visual/Feel and UI stories *(every qa.level)*
+- [ ] Signed-off evidence doc at `production/qa/evidence/[story-slug]-evidence.md` for all Visual/Feel stories *(every qa.level)*
+- [ ] Smoke check passes (run `/smoke-check sprint` before QA hand-off) *(qa.level standard/full)*
+- [ ] No regressions introduced
- [ ] Code reviewed (via `/code-review` or documented peer review)
-- [ ] Story file updated to `Status: Complete` via `/story-done`
+- [ ] Story file updated to `Status: Complete` (via `/story-done`)
**Stories requiring playtest sign-off before close**: [list, or "None"]
---
----
-
*Results and sign-off are tracked in the QA sign-off report generated by `/team-qa` — not in this plan file.*
-
-*Template: `.claude/docs/templates/test-plan.md`*
-*Generated by: `/qa-plan` — do not edit this line*
diff --git a/.claude/docs/templates/ux-spec.md b/.claude/docs/templates/ux-spec.md
index f97a5f94..ad8eb51b 100644
--- a/.claude/docs/templates/ux-spec.md
+++ b/.claude/docs/templates/ux-spec.md
@@ -1,12 +1,13 @@
-# UX Specification: [Screen / Flow Name]
+# UX Spec: [Screen/Flow Name]
> 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., ux-designer]
-> **Last Updated**: [Date]
+> **Status**: [In Design | In Review | Approved | Implemented]
+> **Author**: [user + ux-designer]
+> **Last Updated**: [today's date]
+> **Journey Phase(s)**: [from context]
> **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]
+> **Platform Target**: [target platforms and input methods from 2h]
> **Related GDDs**: [Links to the GDD sections that generated this UI requirement — e.g., `design/gdd/inventory.md § UI Requirements`]
> **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., `pause-menu.md`, `settings.md`]
@@ -23,6 +24,8 @@
## 1. Purpose & Player Need
+[To be designed]
+
**What player need does this screen serve?**
[One paragraph — the real human need from the player's perspective, not the system function. See guide Section 1 for good/bad examples.]
@@ -39,6 +42,8 @@
## 2. Player Context on Arrival
+[To be designed]
+
| Question | Answer |
|----------|--------|
| What was the player just doing? | [Prior activity / triggering state] |
@@ -56,6 +61,8 @@
## 3. Navigation Position
+[To be designed]
+
**Screen hierarchy** (use indentation to show parent-child relationships):
```
@@ -82,6 +89,8 @@
## 4. Entry & Exit Points
+[To be designed]
+
> Every entry point must have a corresponding exit point. Empty cells are a sign
> that design work is unfinished. See guide Section 4 for worked examples.
@@ -103,6 +112,8 @@
### 5.1 ASCII Wireframe
+[To be designed]
+
```
[Draw the screen layout using ASCII art. Suggested characters:
┌ ┐ └ ┘ │ ─ for borders
@@ -117,12 +128,16 @@ See guide Section 5 for a completed example wireframe.]
### 5.2 Layout Zones
+[To be designed]
+
| Zone Name | Description | Approximate Size | Scrollable? | Overflow Behavior |
|-----------|-------------|-----------------|-------------|-------------------|
| [Zone] | [Contents and purpose] | [% width x % height] | [Yes/No] | [Overflow handling] |
### 5.3 Component Inventory
+[To be designed]
+
> List every discrete UI component on this screen. This table drives the implementation
> task list — each row becomes a component to build or reuse.
@@ -134,6 +149,8 @@ See guide Section 5 for a completed example wireframe.]
### 5.4 Information Hierarchy
+[To be designed]
+
[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.]
@@ -141,6 +158,8 @@ behind a tab, a scroll or a button — in that order, with the reason for each.]
## 6. States & Variants
+[To be designed]
+
> Document every state before implementation — at minimum: loading, empty,
> populated, and error. The states table is also the test matrix for QA.
> See guide Section 6 for a worked example.
@@ -153,6 +172,8 @@ behind a tab, a scroll or a button — in that order, with the reason for each.]
## 7. Interaction Map
+[To be designed]
+
> Cover every input method for the platform target (mouse, keyboard, gamepad,
> touch). Gaps in this table are bugs waiting to happen. See guide Section 7.
@@ -178,6 +199,8 @@ behind a tab, a scroll or a button — in that order, with the reason for each.]
## 8. Data Requirements
+[To be designed]
+
> UI reads data; it does not own it. UI fires events; it does not write state
> directly. Every displayed data element needs a source system and owner.
> See guide Section 8 for a worked example.
@@ -194,6 +217,8 @@ behind a tab, a scroll or a button — in that order, with the reason for each.]
## 9. Events Fired
+[To be designed]
+
> Every destructive or state-changing player action must appear in this table.
> See guide Section 9 for a worked example.
@@ -205,6 +230,8 @@ behind a tab, a scroll or a button — in that order, with the reason for each.]
## 10. Transitions & Animations
+[To be designed]
+
> Specify at least the screen enter and exit transitions, plus reduced-motion
> behavior for each. See guide Section 10 for a worked example.
@@ -216,6 +243,8 @@ behind a tab, a scroll or a button — in that order, with the reason for each.]
## 11. Input Method Completeness Checklist
+[To be designed]
+
> Fill this checklist before marking the spec as Approved. Any unchecked item
> blocks implementation start.
@@ -250,6 +279,8 @@ behind a tab, a scroll or a button — in that order, with the reason for each.]
## 12. Accessibility
+[To be designed]
+
> Project-wide standards live in `design/accessibility-requirements.md` — consult it
> before filling this section so you do not duplicate or contradict project-level
> commitments.
@@ -290,6 +321,8 @@ behind a tab, a scroll or a button — in that order, with the reason for each.]
## 13. Localization Considerations
+[To be designed]
+
**General rules for this screen**:
- All text elements must tolerate a minimum of 40% expansion from English baseline
- RTL layout (Arabic, Hebrew): mirrored layout required — document which elements mirror and which do not
@@ -304,6 +337,8 @@ behind a tab, a scroll or a button — in that order, with the reason for each.]
## 14. Acceptance Criteria
+[To be designed]
+
> Write criteria a QA tester can verify independently, without asking the designer
> what they meant. Every criterion should be binary — pass or fail, not subjective.
@@ -351,6 +386,8 @@ behind a tab, a scroll or a button — in that order, with the reason for each.]
## 15. Open Questions
+[To be designed]
+
> Track unresolved design questions here. Each question should have a clear owner
> and a deadline. An Approved spec must have zero open questions — move to a decision
> or explicitly document the deferral rationale.
diff --git a/.claude/docs/workflow-catalog.yaml b/.claude/docs/workflow-catalog.yaml
index aa7bb60e..03d811bc 100644
--- a/.claude/docs/workflow-catalog.yaml
+++ b/.claude/docs/workflow-catalog.yaml
@@ -102,7 +102,7 @@ phases:
any_of:
- glob: "project.yaml"
pattern: 'name:[[:space:]]*"?(Godot|Unity|Unreal)'
- # technical-preferences.md writes "- **Engine**: Godot 4.6", so the
+ # technical-preferences.md writes "- **Engine**: Godot 4.7", so the
# pattern must clear the bold markers. The [^[] guard rejects the
# "[TO BE CONFIGURED]" placeholder.
- glob: ".claude/docs/technical-preferences.md"
@@ -305,8 +305,8 @@ phases:
required: true
repeatable: true
artifact:
- glob: "production/epics/**/*.md"
- min_count: 2
+ glob: "production/epics/*/story-*.md"
+ min_count: 1
description: "Break each epic into implementable story files. Run per epic: /create-stories [epic-slug]"
- id: sprint-plan
diff --git a/.claude/hooks/detect-gaps.sh b/.claude/hooks/detect-gaps.sh
index 128c350a..766df369 100644
--- a/.claude/hooks/detect-gaps.sh
+++ b/.claude/hooks/detect-gaps.sh
@@ -11,16 +11,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
@@ -198,18 +201,24 @@ else
SRC_FILES=0
fi
+# Only the GDDs at the top of design/gdd/ count, as in the commit check: copies
+# in a subfolder such as archive/ are not the project's design.
if [ -d "design/gdd" ]; then
- DESIGN_FILES=$(find design/gdd -type f -name "*.md" 2>/dev/null | wc -l)
+ DESIGN_FILES=$(find design/gdd -maxdepth 1 -type f -name "*.md" 2>/dev/null | wc -l)
+ SUB_DESIGN_FILES=$(find design/gdd -mindepth 2 -type f -name "*.md" 2>/dev/null | wc -l)
else
DESIGN_FILES=0
+ SUB_DESIGN_FILES=0
fi
# Normalize whitespace from wc output
SRC_FILES=$(echo "$SRC_FILES" | tr -d ' ')
DESIGN_FILES=$(echo "$DESIGN_FILES" | tr -d ' ')
+SUB_DESIGN_FILES=$(echo "$SUB_DESIGN_FILES" | tr -d ' ')
if [ "$DOC_CHECKS" = true ] && [ "$SRC_FILES" -gt 50 ] && [ "$DESIGN_FILES" -lt 5 ]; then
echo "⚠️ GAP: Substantial codebase ($SRC_FILES source files) but sparse design docs ($DESIGN_FILES files)"
+ [ "$SUB_DESIGN_FILES" -gt 0 ] && echo " Not counted: $SUB_DESIGN_FILES .md file(s) in design/gdd/ subfolders (such as archive/)"
echo " Suggested action: /reverse-document design ${CODE_ROOT:-<code root>}/[system]"
echo " Or run: /project-stage-detect to get full analysis"
fi
diff --git a/.claude/hooks/log-agent-stop.sh b/.claude/hooks/log-agent-stop.sh
index cd4cddbf..611449db 100644
--- a/.claude/hooks/log-agent-stop.sh
+++ b/.claude/hooks/log-agent-stop.sh
@@ -11,16 +11,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
diff --git a/.claude/hooks/log-agent.sh b/.claude/hooks/log-agent.sh
index 21c068b2..8ec795e8 100644
--- a/.claude/hooks/log-agent.sh
+++ b/.claude/hooks/log-agent.sh
@@ -11,16 +11,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
diff --git a/.claude/hooks/log-instructions.sh b/.claude/hooks/log-instructions.sh
index 4c46a410..b7303d31 100644
--- a/.claude/hooks/log-instructions.sh
+++ b/.claude/hooks/log-instructions.sh
@@ -10,16 +10,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
@@ -36,28 +39,25 @@ fi
# files: a new GDD, a new source file, a new test. So "does the gameplay-code
# rule ever actually reach the model?" has a real answer, and before
# this hook the only way to get it was to infer it from behaviour afterwards.
+# An inferred answer goes wrong silently: a rule can specify one convention
+# while agents follow another, and nothing surfaces the disagreement. A log of
+# the load events replaces the inference with a record.
#
-# That inference was made once here, expensively: a data-file rule specified one
-# key casing, agents wrote the other, and nothing surfaced the disagreement.
-# Measurement replaces the inference.
-#
-# MEASURED, same repo, one session:
+# WHAT IT RECORDS
# session_start CLAUDE.md
-# include its four @-imports, each carrying parent_file_path
-# path_glob_match .claude/rules/skill-authoring.md, after READING a file
-# under .claude/agents/** -- one of its declared paths
-# (nothing) after CREATING a file under prototypes/** -- a declared
-# path of .claude/rules/prototype-code.md
+# include its @-imports, each carrying parent_file_path
+# path_glob_match a path-scoped rule, after READING a file that matches one
+# of its declared paths
+# (nothing) after CREATING a file that matches a declared path
# Read fires, create does not. Keep this hook wired: the behaviour is upstream
# and can change in either direction, and this is the only thing here that would
# notice.
#
# SCHEMA CONFIRMED, NOT ASSUMED
# The common fields are documented; the event-specific ones are not. `pick()`
-# tries the confirmed name first and keeps alternates behind it, so a schema
-# change degrades to a fallback rather than to a blank column -- and the RAW
-# line carries the answer regardless. That is how `load_reason` was found: the
-# first guess (`reason`) missed, and the raw payload named the real field.
+# tries the confirmed name first (`load_reason` for the reason) and keeps
+# alternates behind it, so a schema change degrades to a fallback rather than
+# to a blank column -- and the RAW line carries the answer regardless.
#
# NOT GATED ON features.session_state, deliberately. This is a diagnostic wired
# up on purpose; silencing it from an unrelated flag would make it do nothing
diff --git a/.claude/hooks/notify.sh b/.claude/hooks/notify.sh
index 035e496f..a3792861 100644
--- a/.claude/hooks/notify.sh
+++ b/.claude/hooks/notify.sh
@@ -11,16 +11,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
diff --git a/.claude/hooks/post-compact.sh b/.claude/hooks/post-compact.sh
deleted file mode 100644
index d7f43224..00000000
--- a/.claude/hooks/post-compact.sh
+++ /dev/null
@@ -1,59 +0,0 @@
-#!/usr/bin/env bash
-
-# --- work from the project root ----------------------------------------------
-# Every path below is repo-relative, so a hook invoked with a working directory
-# that is not the repo root would silently read and write the WRONG TREE --
-# returning a near-empty result instead of the session-recovery block, and
-# creating stray trees such as docs/production/session-logs/ on write.
-#
-# PRECEDENCE IS LOAD-BEARING. A cwd that IS a project root carries real
-# information and must win: a caller sitting inside another project means that
-# project, not this one. Resolving to the script's own location first would
-# override them. So, in order:
-# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
-# 4. this script's location -> <root>/.claude/hooks/../.. by construction
-# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
-# overriding a caller that legitimately means somewhere else.
-#
-# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
- CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
- CCGS_ROOT="$CLAUDE_PROJECT_DIR"
-else
- CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
-fi
-[ -n "$CCGS_ROOT" ] && cd "$CCGS_ROOT" 2>/dev/null || true
-
-# post-compact.sh — fires after conversation compaction
-#
-# THIS OUTPUT DOES NOT REACH CLAUDE. Claude Code writes PostCompact stdout to
-# the debug log and discards its systemMessage (hooks documentation). Recovery
-# after a compaction is session-start.sh, which SessionStart runs again with
-# source `compact`; the reminder below is for the debug log only.
-
-# features.session_state: off => this hook is a no-op. Default `on`; see
-# session_state_enabled() in yaml-helper.sh.
-if [ -f .claude/hooks/yaml-helper.sh ]; then
- . .claude/hooks/yaml-helper.sh
- session_state_enabled || exit 0
-fi
-
-ACTIVE="production/session-state/active.md"
-
-echo "=== Context Restored After Compaction ==="
-
-if [ -f "$ACTIVE" ]; then
- # tr: BSD wc (macOS) right-aligns its count ("( 35 lines)").
- SIZE=$(wc -l < "$ACTIVE" 2>/dev/null | tr -d ' ')
- echo "Session state file exists: $ACTIVE (${SIZE:-?} lines)"
- echo "IMPORTANT: Read this file now to restore your working context."
- echo "It contains: current task, decisions made, files in progress, open questions."
-else
- echo "No session state file found at $ACTIVE"
- echo "If you were mid-task, check production/session-logs/ for the last session audit."
-fi
-
-echo "========================================="
diff --git a/.claude/hooks/pre-compact.sh b/.claude/hooks/pre-compact.sh
index 5b981305..a9672cd8 100644
--- a/.claude/hooks/pre-compact.sh
+++ b/.claude/hooks/pre-compact.sh
@@ -11,32 +11,33 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
fi
[ -n "$CCGS_ROOT" ] && cd "$CCGS_ROOT" 2>/dev/null || true
-# Claude Code PreCompact hook: log the compaction, and summarise session state.
+# Claude Code PreCompact hook: log the compaction. Nothing else.
#
-# THIS OUTPUT DOES NOT REACH CLAUDE. Claude Code writes PreCompact stdout to the
-# debug log and discards its systemMessage (hooks documentation). What survives
-# a compaction is the file on disk: SessionStart fires again with source
-# `compact`, and session-start.sh shows the CHECKPOINT then. The one effect
-# here that lands is the compaction-log line at the end; the summary stays
-# bounded for anyone reading the debug log. The notes below were written when
-# the output was believed to reach the context -- the bounds still hold, the
-# "into the context" reasoning does not.
+# PRINTS NOTHING, ON PURPOSE. Claude Code writes PreCompact stdout to the debug
+# log and discards its systemMessage (hooks documentation), so a state summary
+# printed here reached no one -- and gathering it cost git and grep spawns on
+# every compaction. What survives a compaction is the file on disk:
+# SessionStart fires again with source `compact`, and session-start.sh shows
+# the CHECKPOINT from production/session-state/active.md then.
# features.session_state: off => this hook is a no-op. Default `on`; see
# session_state_enabled() in yaml-helper.sh.
@@ -45,134 +46,9 @@ if [ -f .claude/hooks/yaml-helper.sh ]; then
session_state_enabled || exit 0
fi
-echo "=== SESSION STATE BEFORE COMPACTION ==="
-echo "Timestamp: $(date)"
-
-# --- Active session state: the CHECKPOINT region, BY REFERENCE ---
-#
-# Injecting `head -n 100` of active.md here would be wrong twice over.
-#
-# First, the cap bounds the wrong dimension. active.md's lines are long, so 100
-# of them was 12.7 KB (~3,200 tokens) -- injected at the one moment context is
-# scarcest, and growing with the file.
-#
-# Second: this was written believing hook output goes INTO the context that is
-# about to be compacted. It does not (see the top of this file) -- PreCompact
-# output reaches the debug log only, so a dump bought nothing, and
-# session-start.sh, which runs after every compaction, is what restores the
-# file. Pointer + a bounded checkpoint beats a dump on both cost and
-# fidelity.
-#
-# So: emit only the region between the CHECKPOINT markers (bounded by the schema
-# in .claude/docs/templates/session-state.md) plus a pointer to the whole file.
-STATE_FILE="production/session-state/active.md"
-if [ -f "$STATE_FILE" ]; then
- echo ""
- echo "## Active Session State — checkpoint from $STATE_FILE"
- CHECKPOINT=$(sed -n '/<!-- CHECKPOINT -->/,/<!-- \/CHECKPOINT -->/p' "$STATE_FILE" 2>/dev/null \
- | grep -v '<!-- /\?CHECKPOINT -->')
- STATUS_BLOCK=$(sed -n '/<!-- STATUS -->/,/<!-- \/STATUS -->/p' "$STATE_FILE" 2>/dev/null \
- | grep -v '<!-- /\?STATUS -->' | grep -E '^(Epic|Feature|Task):[[:space:]]*[^[:space:]]')
- [ -n "$STATUS_BLOCK" ] && printf '%s\n' "$STATUS_BLOCK"
- if [ -n "$CHECKPOINT" ]; then
- printf '%s\n' "$CHECKPOINT"
- else
- # No markers: an unmigrated or hand-written file. Fall back to a small
- # head slice rather than nothing -- but say so, because a missing
- # checkpoint is a real problem the user should fix, not absorb silently.
- echo "(no CHECKPOINT block — showing the first 20 lines instead;"
- echo " re-create this file from .claude/docs/templates/session-state.md)"
- head -n 20 "$STATE_FILE"
- fi
- echo ""
- echo "Full detail (NOT reproduced here — read the file if you need it): $STATE_FILE"
-else
- echo ""
- echo "## No active session state file found"
- echo "Consider maintaining production/session-state/active.md for better recovery."
- echo "Template: .claude/docs/templates/session-state.md"
-fi
-
-# --- Files modified this session (unstaged + staged + untracked) ---
-echo ""
-echo "## Files Modified (git working tree)"
-
-# BOUNDED. These three lists must never be emitted in full, one line per
-# file, with no cap. This output reaches the debug log, where an unbounded dump
-# still costs time and log size: a tree with thousands of untracked files (a
-# fresh asset import, or build output that is not gitignored) would otherwise
-# print one line per file on every compaction. The checkpoint above is
-# by-reference for the same reason (see the note at the top of this file).
-#
-# A count plus a sample is what this section is actually for -- orienting the
-# agent after compaction -- and the full list is one `git status` away.
-_PC_CAP=20
-_pc_list() { # $1=label $2=newline-separated paths
- [ -n "$2" ] || return 0
- _n=$(printf '%s\n' "$2" | grep -c .)
- echo "$1 ($_n):"
- printf '%s\n' "$2" | head -n "$_PC_CAP" | while read -r f; do [ -n "$f" ] && echo " - $f"; done
- if [ "$_n" -gt "$_PC_CAP" ]; then
- echo " ... and $((_n - _PC_CAP)) more (run: git status)"
- fi
-}
-
-CHANGED=$(git diff --name-only 2>/dev/null)
-STAGED=$(git diff --staged --name-only 2>/dev/null)
-UNTRACKED=$(git ls-files --others --exclude-standard 2>/dev/null)
-
-_pc_list "Unstaged changes" "$CHANGED"
-_pc_list "Staged changes" "$STAGED"
-_pc_list "New untracked files" "$UNTRACKED"
-
-if [ -z "$CHANGED" ] && [ -z "$STAGED" ] && [ -z "$UNTRACKED" ]; then
- echo " (no uncommitted changes)"
-fi
-
-# --- Work-in-progress design docs ---
-echo ""
-echo "## Design Docs — Work In Progress"
-
-WIP_FOUND=false
-# BOUNDED and BATCHED. One `grep -n` per design doc, printing every matching
-# line from every file, fails twice over -- the same two ways as above:
-# unbounded OUTPUT into a compacting context, and unbounded
-# COST -- one process spawn per file, which grows past this hook's 10s budget
-# on a project with a large set of GDDs.
-#
-# `xargs -0` bounds the spawn count by ARG_MAX rather than by file count, and
-# the NUL delimiter keeps it portable: `-d` is GNU-only, BSD xargs rejects it,
-# and the pipeline swallows that error silently. The
-# report is capped. What the agent needs after compaction is "these docs are
-# unfinished", not every TODO line in the project.
-_WIP_HITS=$(printf '%s\n' design/gdd/*.md | tr '\n' '\0' \
- | xargs -0 grep -lE "TODO|WIP|PLACEHOLDER|\[TO BE|\[TBD\]" 2>/dev/null || true)
-if [ -n "$_WIP_HITS" ]; then
- WIP_FOUND=true
- _wn=$(printf '%s\n' "$_WIP_HITS" | grep -c .)
- echo "$_wn design doc(s) contain TODO/WIP/PLACEHOLDER markers:"
- printf '%s\n' "$_WIP_HITS" | head -n "$_PC_CAP" | while read -r f; do
- [ -n "$f" ] && echo " - $f"
- done
- if [ "$_wn" -gt "$_PC_CAP" ]; then
- echo " ... and $((_wn - _PC_CAP)) more"
- fi
-fi
-
-if [ "$WIP_FOUND" = false ]; then
- echo " (no WIP markers found in design docs)"
-fi
-
-# --- Log compaction event ---
SESSION_LOG_DIR="production/session-logs"
mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
echo "Context compaction occurred at $(date)." \
>> "$SESSION_LOG_DIR/compaction-log.txt" 2>/dev/null
-echo ""
-echo "## Recovery Instructions"
-echo "After compaction, read $STATE_FILE to recover full working context."
-echo "Then read any files listed above that are being actively worked on."
-echo "=== END SESSION STATE ==="
-
exit 0
diff --git a/.claude/hooks/session-start.sh b/.claude/hooks/session-start.sh
index 1a0a836f..7bc05f8d 100644
--- a/.claude/hooks/session-start.sh
+++ b/.claude/hooks/session-start.sh
@@ -11,16 +11,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
@@ -118,6 +121,19 @@ if [ -f ".claude/hooks/yaml-helper.sh" ]; then
fi
fi
+# --- Update alert ---
+# One line when a newer release is out. It reads a cache that a background job
+# refreshes at most once a day, so this hook makes no network call and never
+# waits for one. `updates.check: false` turns it off (effects-map.md).
+if [ -f .claude/hooks/update-check.sh ]; then
+ . .claude/hooks/update-check.sh
+ UPDATE_LINE=$(update_check_notice 2>/dev/null)
+ if [ -n "$UPDATE_LINE" ]; then
+ echo ""
+ echo "$UPDATE_LINE"
+ fi
+fi
+
# --- Stage source agreement ---
# `project.stage` in project.yaml is authoritative; production/stage.txt is a
# legacy mirror kept for unmigrated hooks. Twelve consumers read the mirror --
@@ -160,16 +176,16 @@ if [ -n "$LATEST_MILESTONE" ]; then
echo "Active milestone: $(basename "$LATEST_MILESTONE" .md)"
fi
-# Open bug count
-BUG_COUNT=0
-for dir in tests/playtest production; do
- if [ -d "$dir" ]; then
- count=$(find "$dir" -name "BUG-*.md" 2>/dev/null | wc -l)
- BUG_COUNT=$((BUG_COUNT + count))
- fi
-done
-if [ "$BUG_COUNT" -gt 0 ]; then
- echo "Open bugs: $BUG_COUNT"
+# Open bug count: bug files whose header Status is not Closed or Verified
+# Fixed, as bug-stats.sh counts them. Counting the files themselves reported
+# every closed bug as open.
+BUG_OPEN=""
+if [ -f .claude/scripts/bug-stats.sh ]; then
+ BUG_OPEN=$(bash .claude/scripts/bug-stats.sh --root . tests/playtest production 2>/dev/null \
+ | awk -F'\t' '$1 == "open" { print $2 }')
+fi
+if [ -n "$BUG_OPEN" ] && [ "$BUG_OPEN" -gt 0 ]; then
+ echo "Open bugs: $BUG_OPEN"
fi
# Code health quick check.
@@ -255,15 +271,23 @@ if [ -f "$STATE_FILE" ] && { ! command -v session_state_enabled >/dev/null 2>&1
echo "A previous session left state at: $STATE_FILE"
echo "Read this file to recover context and continue where you left off."
echo ""
- # The CHECKPOINT region -- the same region pre-compact.sh reads.
+ # The CHECKPOINT region, as the schema in
+ # .claude/docs/templates/session-state.md defines it.
+ #
+ # Previewing `tail -20` here while pre-compact took `head -100` put two
+ # consumers on opposite ends of one file, so which slice you got
+ # depended on which hook happened to fire. Neither was wrong, because
+ # nothing defined where the recoverable state lived. The schema does now.
#
- # Previewing `tail -20` here while pre-compact takes `head -100` would put two
- # consumers on opposite ends of one file, so which slice you got would
- # depend on which hook happened to fire. Neither was wrong, because
- # nothing defined where the recoverable state lived. The schema in
- # .claude/docs/templates/session-state.md defines it; both read it now.
- CHECKPOINT=$(sed -n '/<!-- CHECKPOINT -->/,/<!-- \/CHECKPOINT -->/p' "$STATE_FILE" 2>/dev/null \
- | grep -v '<!-- /\?CHECKPOINT -->')
+ # A marker is a line holding only the marker (spaces and a CR around it
+ # allowed), as rotate-session-state.sh matches it. The template's HOW
+ # comment quotes `<!-- /CHECKPOINT -->` inside a sentence, so an unanchored
+ # match took that quote for the closing marker of a file that had lost its
+ # real one, and previewed the narrative as the checkpoint.
+ CP_OPEN_RE='^[[:space:]]*<!-- CHECKPOINT -->[[:space:]]*$'
+ CP_CLOSE_RE='^[[:space:]]*<!-- /CHECKPOINT -->[[:space:]]*$'
+ CHECKPOINT=$(sed -n '/^[[:space:]]*<!-- CHECKPOINT -->[[:space:]]*$/,/^[[:space:]]*<!-- \/CHECKPOINT -->[[:space:]]*$/p' "$STATE_FILE" 2>/dev/null \
+ | grep -v -e "$CP_OPEN_RE" -e "$CP_CLOSE_RE")
TOTAL_LINES=$(wc -l < "$STATE_FILE" 2>/dev/null | tr -d ' ')
# A sed range whose END address never matches runs to EOF. So a file with an
# opening marker and NO closing one produced a non-empty capture of the whole
@@ -275,8 +299,8 @@ if [ -f "$STATE_FILE" ] && { ! command -v session_state_enabled >/dev/null 2>&1
# Two consumers of one region must agree on what malformed means.
# `<!-- CHECKPOINT -->` cannot match `<!-- /CHECKPOINT -->` -- the slash sits
# where the space would be -- so these two counts are independent.
- CP_OPEN=$(grep -c '<!-- CHECKPOINT -->' "$STATE_FILE" 2>/dev/null | tr -d ' ')
- CP_CLOSE=$(grep -c '<!-- /CHECKPOINT -->' "$STATE_FILE" 2>/dev/null | tr -d ' ')
+ CP_OPEN=$(grep -c "$CP_OPEN_RE" "$STATE_FILE" 2>/dev/null | tr -d ' ')
+ CP_CLOSE=$(grep -c "$CP_CLOSE_RE" "$STATE_FILE" 2>/dev/null | tr -d ' ')
if [ "${CP_OPEN:-0}" -gt 0 ] && [ "${CP_CLOSE:-0}" -eq 0 ]; then
echo " [!] CHECKPOINT block is not terminated — no <!-- /CHECKPOINT --> marker."
echo " Not previewing it: without the closing marker the checkpoint"
@@ -285,6 +309,19 @@ if [ -f "$STATE_FILE" ] && { ! command -v session_state_enabled >/dev/null 2>&1
echo " Re-create from .claude/docs/templates/session-state.md."
echo " ... ($TOTAL_LINES total lines — read the full file to continue)"
elif [ -n "$CHECKPOINT" ]; then
+ # active.md is gitignored, so it stays put when you switch branches and
+ # a checkpoint written on one branch was shown as current on another.
+ # Its Branch value is the first backquoted word, or else the first word.
+ # Silent when there is no value, it is the template's [branch], or HEAD
+ # is detached ("HEAD") or not a repository (empty), so nothing compares.
+ CP_BRANCH=$(printf '%s\n' "$CHECKPOINT" | sed -n -E 's/^\*\*Branch(:\*\*|\*\*:)[[:space:]]*//p' \
+ | head -1 | tr -d '\r' | sed -E 's/^`([^`]*)`.*/\1/; s/[[:space:]].*//')
+ case "$CP_BRANCH" in
+ ''|'['*) ;;
+ *) if [ -n "$BRANCH" ] && [ "$BRANCH" != "HEAD" ] && [ "$CP_BRANCH" != "$BRANCH" ]; then
+ echo "[!] This checkpoint is from branch $CP_BRANCH; you are on $BRANCH. Check it still applies before acting on it."
+ fi ;;
+ esac
# Capped at 25 lines / 3,000 characters. Claude Code keeps 10,000
# characters of hook output and shows only a 2,000-character preview
# past that, so an uncapped checkpoint could cut itself -- and anything
diff --git a/.claude/hooks/session-stop.sh b/.claude/hooks/session-stop.sh
index 3d5320b9..aeb15ac7 100644
--- a/.claude/hooks/session-stop.sh
+++ b/.claude/hooks/session-stop.sh
@@ -11,16 +11,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
@@ -29,6 +32,12 @@ fi
# Claude Code Stop hook: Log session summary when Claude finishes
# Records what was worked on for audit trail and sprint tracking
+#
+# Registered with "async": true: it only writes files, so the turn does not
+# wait for it. Two consequences: Claude Code does not enforce its timeout, and
+# under `claude -p` it is cancelled if still running at teardown, so a headless
+# run's last archive can be cut short. Two firings can overlap; the hash guards
+# below then append a duplicate at worst, never lose an entry.
# features.session_state: off => this hook is a no-op. Default `on`; see
# session_state_enabled() in yaml-helper.sh.
@@ -109,9 +118,10 @@ fi
# into a running count.
#
# Ordering matters: everything above runs BEFORE stdin is touched. Stop hooks
-# are piped JSON, but if stdin were ever absent the read would block until the
-# 10s timeout killed the hook -- and the state archive above must not be lost
-# to that. Read last, fail silent.
+# are piped JSON, but if stdin were ever absent the read would block -- and
+# Claude Code enforces no timeout on an async hook, so only `timeout 2` below
+# bounds it. The state archive above must not wait on that. Read last, fail
+# silent.
AUDIT_LOG="$SESSION_LOG_DIR/agent-audit.log"
if [ ! -t 0 ] && [ -f "$AUDIT_LOG" ]; then
@@ -158,8 +168,8 @@ if [ ! -t 0 ] && [ -f "$AUDIT_LOG" ]; then
echo "To reduce this: lower \`modes.review_mode\` (\`/settings modes.review_mode=solo\`)"
echo "or \`modes.rigor\` (\`/settings modes.rigor=minimal\`)."
} > "$SESSION_LOG_DIR/session-cost.md" 2>/dev/null
-
- echo "Subagent spawns this session: $SPAWN_COUNT (see production/session-logs/session-cost.md)"
+ # No echo: a Stop hook's stdout reaches only the debug log, and
+ # this hook runs async, so nothing would ever read it.
fi
fi
fi
diff --git a/.claude/hooks/update-check.sh b/.claude/hooks/update-check.sh
new file mode 100644
index 00000000..73dd038a
--- /dev/null
+++ b/.claude/hooks/update-check.sh
@@ -0,0 +1,187 @@
+#!/bin/bash
+# Hook helper: update-check.sh
+# Purpose: one line at session start when a newer Claude Code Game Studios
+# release is out. Sourced by session-start.sh; run directly as
+# `bash update-check.sh refresh` or `notice` (to see the line by hand).
+#
+# update_check_notice
+# Prints the notice line when the cached latest release is newer than this
+# framework, or nothing. Starts a background refresh when the cache is
+# missing or a day old. Never touches the network itself and never waits.
+#
+# bash update-check.sh refresh
+# Asks GitHub for the latest release and writes the cache. Run in the
+# background by update_check_notice; safe to run by hand.
+#
+# Off when `updates.check: false` (project.local.yaml first, then project.yaml;
+# see effects-map.md) or when the CI environment variable is set: nobody reads a
+# session-start line in CI, and a fresh runner has no cache to stop it asking
+# GitHub on every run.
+#
+# Cross-platform: Windows Git Bash, macOS bash 3.2, Linux. Needs curl or wget
+# for the refresh only.
+
+# THE VERSION OF THE FRAMEWORK THESE FILES BELONG TO. Bumped at every release,
+# with framework.version in the template's project.yaml.
+#
+# Not framework.version itself: that is the project's file, and an upgrade
+# that keeps your project.yaml leaves it on the old number (UPGRADING.md says
+# so), which would announce the release you already have. This file is replaced
+# with the rest of .claude/hooks/ on every upgrade, so its number is the
+# framework actually installed.
+UPDATE_CHECK_VERSION="1.2.0"
+UPDATE_CHECK_REPO="Donchitos/Claude-Code-Game-Studios"
+
+# This file's absolute path, taken before anything changes directory, so the
+# background refresh can always find it. Builtins only: this runs every session.
+case "${BASH_SOURCE[0]}" in
+ /*|[A-Za-z]:*) _UPDATE_CHECK_SELF="${BASH_SOURCE[0]}" ;;
+ *) _UPDATE_CHECK_SELF="$PWD/${BASH_SOURCE[0]}" ;;
+esac
+
+# Per user, outside every project: git status stays clean, and one check a day
+# covers every project on the machine.
+_update_check_cache() {
+ printf '%s' "${XDG_CACHE_HOME:-$HOME/.cache}/claude-code-game-studios/latest-release"
+}
+
+_update_check_now() {
+ # EPOCHSECONDS is bash 5 and costs no process; macOS bash 3.2 falls to date.
+ if [ -n "${EPOCHSECONDS:-}" ]; then printf '%s' "$EPOCHSECONDS"; else date +%s; fi
+}
+
+# 0 when $1 is a newer release than $2. Plain x.y.z numbers only; anything after
+# a `-` is ignored, so 1.2.0-dev is not newer than 1.2.0.
+_update_check_newer() {
+ local a="${1%%-*}" b="${2%%-*}" i x y
+ local IFS=.
+ set -- $a; local a1="${1:-0}" a2="${2:-0}" a3="${3:-0}"
+ set -- $b; local b1="${1:-0}" b2="${2:-0}" b3="${3:-0}"
+ for i in 1 2 3; do
+ eval "x=\$a$i; y=\$b$i"
+ case "$x$y" in *[!0-9]*|'') return 1 ;; esac
+ [ "$x" -gt "$y" ] && return 0
+ [ "$x" -lt "$y" ] && return 1
+ done
+ return 1
+}
+
+# 0 unless updates.check is false. project.local.yaml first (it is a personal
+# setting), then project.yaml. A value other than true or false is skipped, as
+# resolve_setting skips it, and the session-start schema check names it.
+# awk, not get_effective_yaml_key: that starts Python twice per session start.
+_update_check_enabled() {
+ local f v root="${_YH_ROOT:-.}"
+ [ -n "${CI:-}" ] && return 1
+ for f in "$root/project.local.yaml" "$root/project.yaml"; do
+ [ -f "$f" ] || continue
+ v=$(awk '
+ /^updates:[[:space:]]*(#.*)?$/ { inu=1; next }
+ /^[^[:space:]#]/ { inu=0 }
+ inu && /^[[:space:]]+check:/ {
+ sub(/^[[:space:]]*check:[[:space:]]*/, "")
+ sub(/[[:space:]]*#.*$/, "")
+ gsub(/["'"'"'[:space:]]/, "") # [:space:] also strips the CR of a CRLF line
+ print; exit
+ }' "$f" 2>/dev/null)
+ case "$v" in
+ false) return 1 ;;
+ true) return 0 ;;
+ esac
+ done
+ return 0
+}
+
+update_check_notice() {
+ _update_check_enabled || return 0
+ local cache latest="" checked=0 line now
+ cache=$(_update_check_cache)
+ if [ -f "$cache" ]; then
+ while IFS= read -r line; do
+ case "$line" in
+ latest=*) latest="${line#latest=}" ;;
+ checked=*) checked="${line#checked=}" ;;
+ esac
+ done < "$cache"
+ fi
+ case "$checked" in ''|*[!0-9]*) checked=0 ;; esac
+
+ # A day old or never checked: ask again in the background. Every descriptor
+ # is redirected and the job is started from a subshell, so this hook returns
+ # at once and nothing it prints can reach the session.
+ # A stamp in the future (a clock that was wrong) counts as old, or it would
+ # hold off every refresh until that date.
+ now=$(_update_check_now)
+ if { [ $((now - checked)) -ge 86400 ] || [ "$checked" -gt "$now" ]; } && [ -f "$_UPDATE_CHECK_SELF" ]; then
+ ( bash "$_UPDATE_CHECK_SELF" refresh </dev/null >/dev/null 2>&1 & ) >/dev/null 2>&1
+ fi
+
+ if [ -n "$latest" ] && _update_check_newer "$latest" "$UPDATE_CHECK_VERSION"; then
+ echo "Update: Claude Code Game Studios $latest is out (this project has $UPDATE_CHECK_VERSION). What changed and how to upgrade: https://github.com/$UPDATE_CHECK_REPO/releases/latest — to stop this notice: /settings --local updates.check=false"
+ fi
+ return 0
+}
+
+# Ask GitHub, write the cache. A failed or unreadable answer keeps the last
+# known release and still stamps the time, so an offline machine asks once a
+# day, not every session; the reason is kept in the cache for anyone checking.
+update_check_refresh() {
+ local cache dir body="" tag="" err="" old="" line tmp
+ cache=$(_update_check_cache); dir="${cache%/*}"
+ mkdir -p "$dir" 2>/dev/null || return 0
+ local url="https://api.github.com/repos/$UPDATE_CHECK_REPO/releases/latest"
+ if command -v curl >/dev/null 2>&1; then
+ body=$(curl -fsSL --max-time 10 -H 'Accept: application/vnd.github+json' "$url" 2>/dev/null) || err="request failed"
+ elif command -v wget >/dev/null 2>&1; then
+ # One try (wget retries 20 times by default, and -T applies to each of
+ # them, so an offline machine kept this job alive for minutes); -T is its
+ # DNS, connect and read timeout each, so 5 keeps it near curl's 10 s total.
+ body=$(wget -q -t 1 -T 5 -O - "$url" 2>/dev/null) || err="request failed"
+ else
+ err="neither curl nor wget found"
+ fi
+ if [ -z "$err" ]; then
+ tag=$(printf '%s' "$body" | grep -o '"tag_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 \
+ | sed 's/.*"\([^"]*\)"$/\1/; s/^v//')
+ case "$tag" in
+ [0-9]*.[0-9]*.[0-9]*) case "$tag" in *[!0-9.]*) err="unexpected tag: $tag"; tag="" ;; esac ;;
+ *) err="no release tag in the answer"; tag="" ;;
+ esac
+ fi
+ if [ -z "$tag" ] && [ -f "$cache" ]; then
+ while IFS= read -r line; do
+ case "$line" in latest=*) old="${line#latest=}" ;; esac
+ done < "$cache"
+ tag="$old"
+ fi
+ tmp="$cache.$$"
+ {
+ echo "checked=$(_update_check_now)"
+ echo "latest=$tag"
+ # An `if`, not `[ ] && echo`: as the block's last command that returns 1
+ # when there is no error, and the cache was never written on a success.
+ if [ -n "$err" ]; then echo "error=$err"; fi
+ } > "$tmp" 2>/dev/null && mv -f "$tmp" "$cache" 2>/dev/null
+ rm -f "$tmp" 2>/dev/null
+ return 0
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+ # Run directly, work from the project root, in session-start.sh's order: a
+ # cwd that is a project root wins, then CLAUDE_PROJECT_DIR, then this file's
+ # own location. Sourced, it leaves the caller's directory alone.
+ if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
+ CCGS_ROOT="$PWD"
+ elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
+ CCGS_ROOT="$CLAUDE_PROJECT_DIR"
+ else
+ CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
+ fi
+ [ -n "$CCGS_ROOT" ] && cd "$CCGS_ROOT" 2>/dev/null || true
+ case "${1:-}" in
+ refresh) update_check_refresh ;;
+ notice) update_check_notice ;;
+ *) echo "update-check.sh: usage: bash update-check.sh refresh|notice" ;;
+ esac
+ exit 0
+fi
diff --git a/.claude/hooks/validate-agent-artifact.sh b/.claude/hooks/validate-agent-artifact.sh
new file mode 100644
index 00000000..1240363c
--- /dev/null
+++ b/.claude/hooks/validate-agent-artifact.sh
@@ -0,0 +1,105 @@
+#!/bin/bash
+
+# --- work from the project root ----------------------------------------------
+# Every path below is repo-relative, so a hook invoked with a working directory
+# that is not the repo root would silently read and write the WRONG TREE --
+# returning a near-empty result instead of the session-recovery block, and
+# creating stray trees such as docs/production/session-logs/ on write.
+#
+# PRECEDENCE IS LOAD-BEARING. A cwd that IS a project root carries real
+# information and must win: a caller sitting inside another project means that
+# project, not this one. Resolving to the script's own location first would
+# override them. So, in order:
+# 1. cwd holds project.yaml -> cwd (a project root)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
+# 4. this script's location -> <root>/.claude/hooks/../.. by construction
+# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
+# overriding a caller that legitimately means somewhere else.
+#
+# NOT an upward search: that resolves a nested project to its parent's config.
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
+ CCGS_ROOT="$PWD"
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
+ CCGS_ROOT="$CLAUDE_PROJECT_DIR"
+else
+ CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
+fi
+[ -n "$CCGS_ROOT" ] && cd "$CCGS_ROOT" 2>/dev/null || true
+
+# Claude Code SubagentStop hook: warns when a subagent stops without writing
+# the file its return contract named. An orchestrating skill ends each agent
+# prompt with "Write your full output to `<path>`"; a named artifact that is
+# not on disk is a failed phase however fluent the reply reads
+# (error-recovery-protocol.md, Trigger 0). The orchestrator still checks the
+# path itself; this hook is the extra guarantee, shown to the user.
+#
+# The path is read from the subagent's own transcript (agent_transcript_path),
+# from its prompt only: the transcript's first user message. The rest of the
+# transcript holds what the subagent read, and a file that quotes the phrase
+# (hooks-reference.md does, with `<path>`) is not its contract. The first
+# "Write your full output to `...`" in the prompt whose path is not a template
+# placeholder ([path], <path>, {path}, or a path holding one) is the contract.
+# A subagent whose prompt names no path is not checked. The existence check is
+# `.claude/scripts/write-guard.sh artifact`, its helper twin.
+#
+# Exit behavior:
+# exit 0 always = advisory (it warns, never blocks; additionalContext on
+# this event would keep the subagent running, so only systemMessage is used)
+#
+# Input schema (SubagentStop):
+# { "agent_id": "...", "agent_type": "qa-tester", "agent_transcript_path": "...",
+# "last_assistant_message": "..." }
+
+INPUT=$(cat)
+
+# Claude Code's internal agents arrive with an empty agent_type
+# (log-agent-stop.sh skips them for the same reason).
+case "$INPUT" in *'"agent_transcript_path"'*) ;; *) exit 0 ;; esac
+
+if command -v jq >/dev/null 2>&1; then
+ # tr: a native Windows jq.exe ends its lines CRLF under Git Bash.
+ _VA_TYPE=$(printf '%s' "$INPUT" | jq -r '.agent_type // empty' 2>/dev/null | tr -d '\r')
+ _VA_T=$(printf '%s' "$INPUT" | jq -r '.agent_transcript_path // empty' 2>/dev/null | tr -d '\r')
+else
+ _VA_TYPE=$(printf '%s' "$INPUT" | LC_ALL=C grep -oE '"agent_type"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | LC_ALL=C sed 's/^"agent_type"[[:space:]]*:[[:space:]]*"//; s/"$//')
+ # A path holds no quote; its backslashes arrive doubled, so \\ becomes one.
+ _VA_T=$(printf '%s' "$INPUT" | LC_ALL=C grep -oE '"agent_transcript_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 \
+ | LC_ALL=C sed 's/^"agent_transcript_path"[[:space:]]*:[[:space:]]*"//; s/"$//; s/\\\\/\\/g')
+fi
+[ -n "$_VA_TYPE" ] || exit 0
+_VA_T=$(printf '%s' "$_VA_T" | sed 's|\\|/|g')
+
+# Not hook_warn (yaml-helper.sh): it also sets additionalContext, which on this
+# event would keep the subagent running. systemMessage only, escaped the same
+# way.
+va_say() {
+ _va_m=$(printf '%s' "$1" | tr -d '\000-\010\013-\037' | sed 's/\\/\\\\/g; s/"/\\"/g' \
+ | awk '{ gsub(/\t/, "\\t"); if (NR > 1) printf "\\n"; printf "%s", $0 }')
+ printf '{"systemMessage":"%s"}\n' "$_va_m"
+ exit 0
+}
+
+[ -n "$_VA_T" ] && [ -f "$_VA_T" ] || va_say "Artifact check did not run for subagent $_VA_TYPE: its transcript ($_VA_T) could not be read."
+# The first named path in the prompt, the transcript's first user message (a
+# JSONL line of type "user"); a template placeholder is not a path.
+_VA_P=$(LC_ALL=C awk 'BEGIN { BINMODE = 3 }
+ /"type"[ \t]*:[ \t]*"user"/ {
+ s = $0
+ while (match(s, /Write your full output to `[^`]+`/)) {
+ # 27: the phrase and its opening backtick; 28 adds the closing one.
+ p = substr(s, RSTART + 27, RLENGTH - 28); s = substr(s, RSTART + RLENGTH)
+ if (p !~ /\[[^]]*\]|<[^>]*>|\{[^}]*\}/) { print p; exit }
+ }
+ exit
+ }' "$_VA_T")
+[ -n "$_VA_P" ] || exit 0
+[ -f .claude/scripts/write-guard.sh ] || va_say "Artifact check did not run for subagent $_VA_TYPE: the helper .claude/scripts/write-guard.sh is missing."
+case "$(bash .claude/scripts/write-guard.sh --root . artifact "$_VA_P" 2>/dev/null)" in
+ *" missing") ;;
+ *) exit 0 ;;
+esac
+va_say "Subagent $_VA_TYPE stopped, and the file its return contract named is not on disk: $_VA_P. Treat that phase as not done (error-recovery protocol, Trigger 0): resume the agent and tell it to write the file."
diff --git a/.claude/hooks/validate-assets.sh b/.claude/hooks/validate-assets.sh
index 9ed345ae..53e07359 100644
--- a/.claude/hooks/validate-assets.sh
+++ b/.claude/hooks/validate-assets.sh
@@ -11,16 +11,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
diff --git a/.claude/hooks/validate-commit.sh b/.claude/hooks/validate-commit.sh
index 3aba5d53..7128e41a 100644
--- a/.claude/hooks/validate-commit.sh
+++ b/.claude/hooks/validate-commit.sh
@@ -11,16 +11,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
@@ -65,8 +68,10 @@ else
| tr '\002' '\\')
fi
-# Print the first segment of $2 that runs `git $1`, anywhere in the command.
-# Anchoring on ^git let every chained form through unchecked:
+# git_segment prints the first segment of $2 that runs `git $1`, anywhere in
+# the command; command_segments does the splitting, which validate-push.sh
+# also uses on its release tools. Anchoring on ^git let every chained form
+# through unchecked:
# `git add -A && git commit`, `git -C . commit`, `cd x && git commit`,
# `GIT_DIR=.git git commit`, a commit on a second line. Segments split on
# && || ; & | ( ) backticks and quotes, and on newlines. Before a segment's
@@ -87,7 +92,7 @@ fi
# string rather than opening a value. All splitting is awk: BSD sed writes a
# literal `n` for `\n`, so on macOS a sed split missed every chained form.
# Over-splitting only costs a check that finds nothing staged; under-splitting
-# is the bypass. Kept identical in validate-push.sh.
+# is the bypass. Both functions are kept identical in validate-push.sh.
#
# `git` itself is matched case-insensitively (`Git`, `GIT`) and a bare quoted
# `"git"` or `'git'` (no path) reads as plain `git` too, the same as a quoted
@@ -114,8 +119,8 @@ fi
# is the same kind of text and is dropped the same way; the double-quote form
# (`@"` ... `"@`) is left alone, because PowerShell itself expands `$(...)`
# inside it, and that content is still live.
-git_segment() {
- printf '%s\n' "$2" \
+command_segments() {
+ printf '%s\n' "$1" \
| awk '{ while ($0 ~ /\\$/) { line = $0; sub(/\\$/, "", line); if ((getline nxt) > 0) { $0 = line nxt } else { $0 = line; break } } print }' \
| awk '
pd != "" { t = $0; sub(/\r$/, "", t); if (t ~ /^'"'"'@/) pd = ""; next }
@@ -171,7 +176,12 @@ git_segment() {
}
s = out s
gsub(/&&|\|\|/, "\n", s); gsub(/[;&|()`"'"'"']/, "\n", s); print s
- }' \
+ }'
+}
+
+# The segment whose command, after the prefixes above, is git and then $1.
+git_segment() {
+ command_segments "$2" \
| grep -E "^[[:space:]]*((if|then|else|elif|do|while|until|time|exec|command|nohup|!|[{])[[:space:]]+|(env|sudo|doas|xargs|nice|timeout|stdbuf|winpty|command)([[:space:]]+-[A-Za-z0-9-]+(=[^[:space:]]*)?([[:space:]]+[^-[:space:]][^[:space:]]*)?)*[[:space:]]+([0-9][0-9.]*[smhd]?[[:space:]]+)?|[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*([^[:space:]]*[/\\])?[Gg][Ii][Tt](\.exe)?([[:space:]]+(-[Cc][[:space:]]+[^[:space:]]+|--(git-dir|work-tree|namespace|super-prefix|config-env|attr-source)[[:space:]]+[^[:space:]]+|-[A-Za-z]|--[A-Za-z-]+(=[^[:space:]]+)?))*[[:space:]]+$1([[:space:]]|\$)"
}
@@ -271,14 +281,20 @@ if [ -n "$_VC_PY" ]; then
fi
_VC_AWAY=0
[ -n "$_VC_CWD" ] && [ ! "$_VC_CWD" -ef . ] && _VC_AWAY=1
+ # PowerShell's escape is the backtick: a backslash there is a path separator.
+ _VC_PS=0
+ printf '%s' "$INPUT" | LC_ALL=C grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"PowerShell"' && _VC_PS=1
_VC_TOK=$(printf '%s\n' "$COMMAND" | "$_VC_PY" -c '
import re, shlex, subprocess, sys
+PS = len(sys.argv) > 2 and sys.argv[2] == "1"
OPS = set(";&|()<>")
GIT_ARG = {"-C", "-c", "--git-dir", "--work-tree", "--namespace", "--super-prefix", "--config-env", "--attr-source"}
REDIR = re.compile(r"^[<>]+&?$|^&>+$") # >, >>, >&, <, <<, &>: a redirection operator
COMMIT_ARG = {"--message", "--file", "--reuse-message", "--reedit-message", "--fixup", "--squash",
"--author", "--date", "--template", "--cleanup", "--trailer", "--pathspec-from-file"}
def words(line):
+ if PS: # git reads assets/data/x.json as assets\data\x.json
+ line = line.replace("\\", "/")
try:
lx = shlex.shlex(line, posix=True, punctuation_chars=True)
lx.whitespace_split = True
@@ -302,7 +318,8 @@ def add(w, k): # git add/stage from w[k] -> pathspecs, takes untracked, -f, -n,
if a and set(a) <= OPS:
break
if rest or not a.startswith("-") or a == "-":
- specs.append(a)
+ # $f, $(...), `...`: known only when the shell runs, so the whole tree
+ specs.append(":/" if "$" in a or "`" in a else a)
elif a == "--":
rest = True
elif a.startswith("--"):
@@ -394,7 +411,7 @@ for s, new, force in ([] if only else adds):
if new:
more += git("ls-files", "--others", "--full-name", *([] if force else ["--exclude-standard"]), "--", *s).stdout
sys.stdout.buffer.write((b"CCGS-ONLY\n" if only else b"CCGS-INDEX\n") + (out.stdout if out else b"") + more)
-' "$_VC_AWAY" 2>/dev/null)
+' "$_VC_AWAY" "$_VC_PS" 2>/dev/null)
case "$_VC_TOK" in CCGS-ONLY*) INDEX_FILES="" ;; esac
WT_FILES=$(printf '%s\n%s' "$WT_FILES" "$(printf '%s\n' "$_VC_TOK" | tail -n +2)")
else
@@ -602,8 +619,9 @@ fi
# design/gdd/ also holds governance and registry files that are not system
# GDDs and have none of these sections, so they warned on every commit (#133).
# Skip the names not_a_system_gdd() skips in gdd-structure-check.sh and
-# review-scope.sh; keep the three lists the same.
-DESIGN_FILES=$(echo "$STAGED" | grep -E '^design/gdd/' \
+# review-scope.sh; keep the three lists the same. Only top-level files count as
+# system GDDs: archive/ and reviews/ copies under design/gdd/ are not checked.
+DESIGN_FILES=$(echo "$STAGED" | grep -E '^design/gdd/[^/]+\.md$' \
| grep -vE '/(game-concept|systems-index|game-pillars|gdd-cross-review-[^/]*|gameplay-tags|fixture-swap-ledger|entity-registry|sound-bible)\.md$')
if [ -n "$DESIGN_FILES" ]; then
WORKFLOW="standard"
@@ -641,21 +659,53 @@ if [ -n "$DESIGN_FILES" ]; then
# documents warn -- a behaviour change smuggled inside a performance
# fix. If that wants tightening it should be its own change with its
# own test.
- printf '%s\n' "$DESIGN_FILES" | "$_VC_PY" -c '
-import sys, os
+ #
+ # It reads what the commit takes, as the JSON check above does: the
+ # staged copy ("I"), or the working copy for a file this command adds
+ # itself ("W", git add or commit -a). Reading the working copy alone
+ # judged a GDD the commit does not contain, either way round.
+ LC_ALL=C awk -v OFS='\t' 'NR == FNR { if ($0 != "") wt[$0] = 1; next }
+ $0 != "" { print (($0 in wt) ? "W" : "I"), $0 }' \
+ <(printf '%s\n' "$WT_FILES") <(printf '%s\n' "$DESIGN_FILES") \
+ | CCGS_VC_PREFIX="$_VC_PREFIX" "$_VC_PY" -c '
+import sys, os, subprocess
argv = sys.argv
required = [x for x in argv[1].split("|") if x]
workflow = argv[2]
+items = [l.split("\t", 1) for l in sys.stdin.buffer.read().decode("utf-8").splitlines() if "\t" in l]
+staged = [p for mode, p in items if mode == "I"]
+# Paths are project-relative; the index names them from the repository top.
+prefix = os.environ.get("CCGS_VC_PREFIX", "")
+blobs = {}
+if staged:
+ raw = subprocess.run(["git", "cat-file", "--batch"], stdout=subprocess.PIPE,
+ input="".join(":" + prefix + p + "\n" for p in staged).encode("utf-8")).stdout
+ pos = 0
+ for p in staged:
+ end = raw.index(b"\n", pos)
+ head = raw[pos:end].split()
+ pos = end + 1
+ if len(head) == 3 and head[1] == b"blob":
+ size = int(head[2])
+ blobs[p] = raw[pos:pos + size]
+ pos += size + 1
out = []
-for line in sys.stdin.read().splitlines():
- path = line.strip()
- if not path or not path.endswith(".md") or not os.path.isfile(path):
- continue
- try:
- with open(path, "r", encoding="utf-8", errors="replace") as fh:
- body = fh.read().lower()
- except OSError:
+for mode, path in items:
+ if not path.endswith(".md"):
continue
+ if mode == "I":
+ if path not in blobs:
+ continue # removed from the index: nothing of it is committed
+ data = blobs[path]
+ else:
+ if not os.path.isfile(path):
+ continue
+ try:
+ with open(path, "rb") as fh:
+ data = fh.read()
+ except OSError:
+ continue
+ body = data.decode("utf-8", "replace").lower()
for section in required:
if section.lower() not in body:
out.append("DESIGN: %s missing section required at workflow=%s: %s"
diff --git a/.claude/hooks/validate-push.sh b/.claude/hooks/validate-push.sh
index 727889c5..7c10e30e 100644
--- a/.claude/hooks/validate-push.sh
+++ b/.claude/hooks/validate-push.sh
@@ -11,25 +11,32 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
fi
[ -n "$CCGS_ROOT" ] && cd "$CCGS_ROOT" 2>/dev/null || true
-# Claude Code PreToolUse hook: Validates git push commands
-# Warns on pushes to protected branches -- as hook JSON on stdout, the only
-# channel the user or Claude sees on exit 0.
+# Claude Code PreToolUse hook: Validates git push commands, and the git and
+# release actions that ask first
+# Warns on pushes to protected branches, and on git tag, git merge, gh release,
+# butler push and steamcmd +run_app_build (the deploy steps /hotfix and
+# /team-release describe; which segments count is
+# `.claude/scripts/write-guard.sh git`, the helper twin) -- as hook JSON on
+# stdout, the only channel the user or Claude sees on exit 0.
# Exit 0 = allow (the normal permission flow still applies), Exit 2 = block
#
# Input schema (PreToolUse for Bash):
@@ -37,13 +44,17 @@ fi
INPUT=$(cat)
-# Most Bash and PowerShell calls do not mention git at all. Leave before any
-# parsing: this hook runs on every one of them, and the parse is most of its
-# cost (the early exit is the shell start-up alone).
+# Most Bash and PowerShell calls do not mention git or a release tool at all.
+# Leave before any parsing: this hook runs on every one of them, and the parse
+# is most of its cost (the early exit is the shell start-up alone).
# Tested only after the "tool_input" key: matching the whole payload also
# tests cwd and transcript_path, so a project path containing "GitHub" or
-# "digital" never took this exit and paid the full parse on every call.
-case "$INPUT" in *'"tool_input"'*[Gg][Ii][Tt]*) ;; *) exit 0 ;; esac
+# "digital" never took this exit and paid the full parse on every call. `gh`
+# must start a word, or "through " and "high " paid it too.
+case "$INPUT" in
+ *'"tool_input"'*[Gg][Ii][Tt]*|*'"tool_input"'*butler*|*'"tool_input"'*steamcmd*|*'"tool_input"'*[!A-Za-z0-9_.-]gh[\ .]*) ;;
+ *) exit 0 ;;
+esac
# Parse command -- use jq if available, fall back to grep. The fallback's string
# body is (\\.|[^"\\])* so an escaped quote does not end it early.
@@ -60,11 +71,11 @@ else
| tr '\002' '\\')
fi
-# Print the first segment of $2 that runs `git $1`, anywhere in the command.
-# An ^git anchor missed every chained push (`git add . && git push`).
-# Kept identical in validate-commit.sh, which explains the splitting.
-git_segment() {
- printf '%s\n' "$2" \
+# Print $1 split into its command segments, one per line: here-doc bodies
+# dropped, quoted git option values kept whole. Kept identical to
+# command_segments in validate-commit.sh, which explains the splitting.
+command_segments() {
+ printf '%s\n' "$1" \
| awk '{ while ($0 ~ /\\$/) { line = $0; sub(/\\$/, "", line); if ((getline nxt) > 0) { $0 = line nxt } else { $0 = line; break } } print }' \
| awk '
pd != "" { t = $0; sub(/\r$/, "", t); if (t ~ /^'"'"'@/) pd = ""; next }
@@ -120,12 +131,109 @@ git_segment() {
}
s = out s
gsub(/&&|\|\|/, "\n", s); gsub(/[;&|()`"'"'"']/, "\n", s); print s
- }' \
+ }'
+}
+
+# Print the first segment of $2 that runs `git $1`, anywhere in the command.
+# An ^git anchor missed every chained push (`git add . && git push`). Kept
+# identical in validate-commit.sh.
+git_segment() {
+ command_segments "$2" \
| grep -E "^[[:space:]]*((if|then|else|elif|do|while|until|time|exec|command|nohup|!|[{])[[:space:]]+|(env|sudo|doas|xargs|nice|timeout|stdbuf|winpty|command)([[:space:]]+-[A-Za-z0-9-]+(=[^[:space:]]*)?([[:space:]]+[^-[:space:]][^[:space:]]*)?)*[[:space:]]+([0-9][0-9.]*[smhd]?[[:space:]]+)?|[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*([^[:space:]]*[/\\])?[Gg][Ii][Tt](\.exe)?([[:space:]]+(-[Cc][[:space:]]+[^[:space:]]+|--(git-dir|work-tree|namespace|super-prefix|config-env|attr-source)[[:space:]]+[^[:space:]]+|-[A-Za-z]|--[A-Za-z-]+(=[^[:space:]]+)?))*[[:space:]]+$1([[:space:]]|\$)"
}
-# Only process git push commands
-PUSH_SEG=$(git_segment push "$COMMAND") || exit 0
+# Print $1 with the text inside each quoted argument masked (every character
+# but a newline becomes _), so a command named inside one -- `grep -rn "git tag
+# v1"`, `git log --grep "git merge"`, a commit message -- is not read as that
+# command. command_segments splits at quotes, which is right for the commit
+# checks (a quoted string may be a whole command) but put quoted text on a line
+# of its own here. Left as written: a quoted git path ("C:/.../git.exe" is the
+# command), the string a shell runs (bash -c "...", eval "..."), here-doc
+# delimiters and bodies (command_segments drops a body unless a shell reads it).
+# An unclosed quote masks nothing after it.
+mask_quoted() {
+ printf '%s\n' "$1" | LC_ALL=C awk '
+ { s = s (NR > 1 ? "\n" : "") $0 }
+ END {
+ n = length(s); i = 1; out = ""; nh = 0; sq = sprintf("%c", 39)
+ while (i <= n) {
+ c = substr(s, i, 1)
+ if (c == "\\") { out = out substr(s, i, 2); i += 2; continue }
+ if (c == "\n" && nh > 0) {
+ # Here-doc bodies, in order, each to its delimiter line.
+ out = out c; i++
+ for (k = 1; k <= nh; k++) {
+ while (i <= n) {
+ j = index(substr(s, i), "\n"); line = (j > 0) ? substr(s, i, j - 1) : substr(s, i)
+ out = out line (j > 0 ? "\n" : ""); i += (j > 0) ? j : length(line)
+ t = line; sub(/\r$/, "", t); if (htab[k]) sub(/^\t+/, "", t)
+ if (t == hd[k] || j == 0) break
+ }
+ }
+ nh = 0; continue
+ }
+ if (c == "<" && substr(s, i, 2) == "<<" && substr(s, i + 2, 1) != "<" && (i == 1 || substr(s, i - 1, 1) != "<")) {
+ j = i + 2; tabs = 0
+ if (substr(s, j, 1) == "-") { tabs = 1; j++ }
+ while (substr(s, j, 1) == " " || substr(s, j, 1) == "\t") j++
+ q = substr(s, j, 1); w = ""
+ if (q == "\"" || q == sq) {
+ e = index(substr(s, j + 1), q)
+ if (e > 0) { w = substr(s, j + 1, e - 1); j = j + e + 1 }
+ } else {
+ if (q == "\\") j++
+ while (j <= n && substr(s, j, 1) !~ /[ \t\n;&|()<>"\\]/ && substr(s, j, 1) != sq) { w = w substr(s, j, 1); j++ }
+ }
+ if (w != "") { hd[++nh] = w; htab[nh] = tabs }
+ out = out substr(s, i, j - i); i = j; continue
+ }
+ if (c == "\"" || c == sq) {
+ # The closing quote; a backslash escapes inside double quotes only.
+ j = i + 1
+ while (j <= n && substr(s, j, 1) != c) j += (c == "\"" && substr(s, j, 1) == "\\") ? 2 : 1
+ if (j > n) { out = out substr(s, i); break }
+ body = substr(s, i + 1, j - i - 1)
+ pre = out; sub(/.*[\n;&|(]/, "", pre)
+ if (body !~ /^([^"]*[\/\\])?[Gg][Ii][Tt](\.[Ee][Xx][Ee])?$/ \
+ && pre !~ /(^|[ \t\/\\])((ba|z|da|k)?sh|pwsh|powershell)(\.exe)?([ \t]+-[A-Za-z]+)*[ \t]+-[A-Za-z]*[Cc]([Oo][Mm][Mm][Aa][Nn][Dd])?[ \t]+$/ \
+ && pre !~ /(^|[ \t])eval[ \t]+$/)
+ gsub(/[^\n]/, "_", body)
+ out = out c body c; i = j + 1; continue
+ }
+ out = out c; i++
+ }
+ printf "%s\n", out
+ }'
+}
+
+# The git and release actions that ask first: the tag and merge segments as
+# git_segment finds them (prefixes and git's own options understood), and the
+# segments that run a release tool, read from the command with its quoted
+# arguments masked. write-guard.sh says which of them act (`git tag -l` lists,
+# `git merge --abort` undoes; neither asks).
+ACT_CMD=$(mask_quoted "$COMMAND" 2>/dev/null) || ACT_CMD="$COMMAND"
+[ -n "$ACT_CMD" ] || ACT_CMD="$COMMAND"
+ACT_SEGS=$( { git_segment '(tag|merge)' "$ACT_CMD"
+ command_segments "$ACT_CMD" | grep -E '(^|[[:space:]/\\])(gh|butler|steamcmd)(\.exe|\.sh)?[[:space:]]'; } 2>/dev/null )
+ACT_MSG=""
+if [ -n "$ACT_SEGS" ]; then
+ if [ -f .claude/scripts/write-guard.sh ]; then
+ ACTIONS=$(printf '%s\n' "$ACT_SEGS" | bash .claude/scripts/write-guard.sh --root . git 2>/dev/null \
+ | awk -F '\t' '$1 == "GIT_ACTION" && !seen[$2]++ {
+ w = ($2 == "tag") ? "git tag" : ($2 == "merge") ? "git merge" : ($2 == "release") ? "gh release" \
+ : ($2 == "deploy-itch") ? "butler push" : "steamcmd +run_app_build"
+ l = l (l == "" ? "" : ", ") w } END { print l }')
+ [ -n "$ACTIONS" ] && ACT_MSG="This command runs $ACTIONS. Tagging, merging and deploying ask first (/hotfix, /team-release): go ahead only if the user approved this step."
+ else
+ ACT_MSG="Git action check skipped: .claude/scripts/write-guard.sh is missing, so tag, merge and deploy steps were not checked."
+ fi
+fi
+
+PUSH_SEG=$(git_segment push "$COMMAND")
+if [ -z "$PUSH_SEG" ]; then
+ [ -n "$ACT_MSG" ] && printf '{"systemMessage":"%s","hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"%s"}}\n' "$ACT_MSG" "$ACT_MSG"
+ exit 0
+fi
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
MATCHED_BRANCH=""
@@ -168,10 +276,13 @@ if [ -n "$MATCHED_BRANCH" ]; then
# before it goes into the JSON string below.
SAFE_BRANCH=$(printf '%s' "$MATCHED_BRANCH" | sed 's/\\/\\\\/g; s/"/\\"/g')
MSG="Push to protected branch '$SAFE_BRANCH' detected. Reminder: Ensure build passes, unit tests pass, and no open bugs the release gate blocks (S1; S1-S3 at workflow: full)."
+ [ -n "$ACT_MSG" ] && MSG="$MSG $ACT_MSG"
printf '{"systemMessage":"%s","hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"%s"}}\n' "$MSG" "$MSG"
# To block instead, replace the printf above with:
# echo "BLOCKED: Run tests before pushing to $MATCHED_BRANCH" >&2
# exit 2
+elif [ -n "$ACT_MSG" ]; then
+ printf '{"systemMessage":"%s","hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"%s"}}\n' "$ACT_MSG" "$ACT_MSG"
fi
exit 0
diff --git a/.claude/hooks/validate-read.sh b/.claude/hooks/validate-read.sh
new file mode 100644
index 00000000..68d23dc2
--- /dev/null
+++ b/.claude/hooks/validate-read.sh
@@ -0,0 +1,109 @@
+#!/bin/bash
+
+# --- work from the project root ----------------------------------------------
+# Same precedence as validate-write.sh (see there for why): a cwd that is a
+# project root wins, then CLAUDE_PROJECT_DIR, then this script's location.
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
+ CCGS_ROOT="$PWD"
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
+ CCGS_ROOT="$CLAUDE_PROJECT_DIR"
+else
+ CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
+fi
+[ -n "$CCGS_ROOT" ] && cd "$CCGS_ROOT" 2>/dev/null || true
+
+# Claude Code PreToolUse hook: refuses a whole-file Read (no offset, no limit)
+# of a design doc over the size bar, and answers with the doc's headings by
+# line, so the retry reads the section it needs. One refused read costs a turn;
+# the read it stops can cost tens of thousands of tokens, and a ranged read
+# always passes, so nothing can get stuck behind it. Watched: design/,
+# docs/architecture/, production/session-state/; the bar is
+# features.read_guard_kb (40 KB); features.read_guard: off turns it off.
+#
+# The logic is `.claude/scripts/read-guard.sh check`, its helper twin; this
+# hook reads the payload through `.claude/scripts/hook-input.sh` and calls it.
+#
+# Exit behavior:
+# exit 2 = the read is refused; stderr goes to Claude
+# exit 0 = every other read, and every case where the guard cannot run
+# (a missing helper is named; the read goes ahead)
+#
+# Input schema (PreToolUse for Read):
+# { "tool_name": "Read", "tool_input": { "file_path": "...", "offset": 1, "limit": 200 } }
+
+INPUT=$(cat)
+
+# Most reads are of none of the watched folders. Leave before any parsing, with
+# builtins only. Only the file_path value is tested, and only its part below
+# the project root: the payload's cwd and transcript_path, and the root part of
+# an absolute path, are the project's own folder, which can be named anything
+# (~/gamedesign/proj), and matching them sent every Read through the full
+# parse. A value that may end at an escaped quote is not trusted: then the
+# whole payload is tested, as before. Leaving here when the full parse would
+# not refuse the read is what keeps the behaviour unchanged: a watched path
+# below the root always holds one of the three words.
+case "$INPUT" in
+ *'"tool_input"'*'"file_path"'*) ;;
+ *) exit 0 ;;
+esac
+_VR_P=${INPUT#*'"tool_input"'}; _VR_P=${_VR_P#*'"file_path"'}; _VR_P=${_VR_P#*'"'}; _VR_P=${_VR_P%%'"'*}
+_vr_bs='\'
+case "$_VR_P" in
+ *"$_vr_bs") _VR_P=$INPUT ;;
+ *"$_vr_bs$_vr_bs"*) _VR_P=${_VR_P//"$_vr_bs$_vr_bs"//} ;; # C:\\Users\\... as C:/Users/...
+esac
+# The root in both spellings Git Bash gives it: /c/Users/... and C:/Users/...
+# (the second read from the first; under a mount such as /tmp only pwd -W
+# knows it, which costs a subshell, so it is asked last).
+_vr_w=$PWD
+case "$PWD" in /[A-Za-z]/*) _vr_w="${PWD:1:1}:${PWD:2}" ;; esac
+shopt -s nocasematch
+case "$_VR_P" in
+ "$PWD"/*) _VR_P=${_VR_P:${#PWD}+1} ;;
+ "$_vr_w"/*) _VR_P=${_VR_P:${#_vr_w}+1} ;;
+ [A-Za-z]:/*) _vr_w=$(pwd -W 2>/dev/null)
+ case "$_VR_P" in "$_vr_w"/*) [ -n "$_vr_w" ] && _VR_P=${_VR_P:${#_vr_w}+1} ;; esac ;;
+esac
+shopt -u nocasematch
+case "$_VR_P" in
+ *design*|*architecture*|*session-state*) ;;
+ *) exit 0 ;;
+esac
+
+[ -f .claude/hooks/yaml-helper.sh ] && . .claude/hooks/yaml-helper.sh 2>/dev/null
+vr_warn() {
+ if command -v hook_warn >/dev/null 2>&1; then hook_warn PreToolUse "$1"
+ else printf '%s\n' "$1" >&2; fi
+ exit 0
+}
+[ -f .claude/scripts/hook-input.sh ] || vr_warn "Read guard skipped: the helper .claude/scripts/hook-input.sh is missing, so the read goes ahead unchecked."
+
+_VR_IN=$(printf '%s' "$INPUT" | bash .claude/scripts/hook-input.sh --root . 2>/dev/null)
+vr_row() { printf '%s\n' "$_VR_IN" | awk -F '\t' -v k="$1" '$1 == k { print $2; exit }'; }
+[ "$(vr_row tool)" = Read ] || exit 0
+[ "$(vr_row where)" = inside ] || exit 0
+_VR_PATH=$(vr_row path)
+[ -f .claude/scripts/read-guard.sh ] || vr_warn "Read guard skipped: the helper .claude/scripts/read-guard.sh is missing, so the read of $_VR_PATH goes ahead unchecked."
+
+_VR_OUT=$(bash .claude/scripts/read-guard.sh --root . check "$_VR_PATH" --bounded "$(vr_row bounded)" 2>/dev/null)
+_VR_LARGE=$(printf '%s\n' "$_VR_OUT" | awk -F '\t' '$1 == "LARGE"')
+[ -n "$_VR_LARGE" ] || exit 0
+
+_VR_KB=$(printf '%s\n' "$_VR_LARGE" | awk -F '\t' '{ printf "%d KB", int(($3 + 1023) / 1024) }')
+_VR_BAR=$(printf '%s\n' "$_VR_LARGE" | awk -F '\t' '{ printf "%d KB", int($4 / 1024) }')
+# At most this many headings: past it the list costs what the read would.
+_VR_MAX=40
+_VR_HEADS=$(bash .claude/scripts/read-guard.sh --root . sections "$_VR_PATH" 2>/dev/null \
+ | VR_MAX="$_VR_MAX" VR_PATH="$_VR_PATH" awk -F '\t' '
+ { n++; if (n <= ENVIRON["VR_MAX"]) printf "%5s %s\n", $1, $2 }
+ END {
+ if (n == 0) print " (no markdown headings: read it in ranges of a few hundred lines)"
+ if (n > ENVIRON["VR_MAX"]) print " ... and " (n - ENVIRON["VR_MAX"]) " more: find them with the Grep tool (pattern `^#`, content mode) on " ENVIRON["VR_PATH"] ", then Read that range with offset and limit"
+ }')
+
+cat >&2 <<EOF
+Read refused: $_VR_PATH is $_VR_KB, over the $_VR_BAR bar for reading a design doc whole (features.read_guard_kb). Read it by section instead: find the heading you need below, then Read with offset at its line and a limit that stops at the next heading.
+$_VR_HEADS
+If the task needs the whole doc, read it in ranges and say why. The guard is a project setting, features.read_guard (on or off).
+EOF
+exit 2
diff --git a/.claude/hooks/validate-registry.sh b/.claude/hooks/validate-registry.sh
new file mode 100644
index 00000000..e00f43e8
--- /dev/null
+++ b/.claude/hooks/validate-registry.sh
@@ -0,0 +1,123 @@
+#!/bin/bash
+
+# --- work from the project root ----------------------------------------------
+# Every path below is repo-relative, so a hook invoked with a working directory
+# that is not the repo root would silently read and write the WRONG TREE --
+# returning a near-empty result instead of the session-recovery block, and
+# creating stray trees such as docs/production/session-logs/ on write.
+#
+# PRECEDENCE IS LOAD-BEARING. A cwd that IS a project root carries real
+# information and must win: a caller sitting inside another project means that
+# project, not this one. Resolving to the script's own location first would
+# override them. So, in order:
+# 1. cwd holds project.yaml -> cwd (a project root)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
+# 4. this script's location -> <root>/.claude/hooks/../.. by construction
+# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
+# overriding a caller that legitimately means somewhere else.
+#
+# NOT an upward search: that resolves a nested project to its parent's config.
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
+ CCGS_ROOT="$PWD"
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
+ CCGS_ROOT="$CLAUDE_PROJECT_DIR"
+else
+ CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
+fi
+[ -n "$CCGS_ROOT" ] && cd "$CCGS_ROOT" 2>/dev/null || true
+
+# Claude Code PreToolUse hook: warns when a Write or Edit of the entity registry
+# (design/registry/entities.yaml) or the TR-ID registry
+# (docs/architecture/tr-registry.yaml) would break either of their two rules:
+# entries are never deleted or renumbered (append-only), and a status takes only
+# the values the file's header lists. It runs BEFORE the write, the only point
+# where the old file can still be compared with the new content.
+#
+# The logic is `.claude/scripts/registry.sh compare`, its helper twin; this hook
+# reads the payload and rebuilds the new content through
+# `.claude/scripts/hook-input.sh`, then calls it. A skill that writes a registry
+# runs `registry.sh validate` itself after writing, because hooks do not run on
+# every tool that runs the skills.
+#
+# Exit behavior:
+# exit 0 always = advisory (it warns, never blocks)
+#
+# Input schema (PreToolUse for Write|Edit):
+# { "tool_name": "Write", "tool_input": { "file_path": "...", "content": "..." } }
+# { "tool_name": "Edit", "tool_input": { "file_path": "...", "old_string": "...",
+# "new_string": "...", "replace_all": false } }
+
+INPUT=$(cat)
+
+# Most writes are to other files. Leave before any parsing, which reads the
+# whole payload: a write of either registry names its file, in either slash.
+case "$INPUT" in
+ *'"tool_input"'*entities.yaml*|*'"tool_input"'*tr-registry.yaml*) ;;
+ *) exit 0 ;;
+esac
+
+[ -f .claude/hooks/yaml-helper.sh ] && . .claude/hooks/yaml-helper.sh 2>/dev/null
+vr_warn() {
+ if command -v hook_warn >/dev/null 2>&1; then hook_warn PreToolUse "$1"
+ else printf '%s\n' "$1" >&2; fi
+ exit 0
+}
+for _vr_s in hook-input.sh registry.sh; do
+ [ -f ".claude/scripts/$_vr_s" ] || vr_warn "Registry check skipped: the helper .claude/scripts/$_vr_s is missing, so the write goes ahead unchecked."
+done
+
+_VR_NEW=$(mktemp 2>/dev/null) || exit 0
+trap 'rm -f "$_VR_NEW"' EXIT
+_VR_IN=$(printf '%s' "$INPUT" | bash .claude/scripts/hook-input.sh --root . --new "$_VR_NEW" 2>/dev/null)
+vr_row() { printf '%s\n' "$_VR_IN" | awk -F '\t' -v k="$1" '$1 == k { print $2; exit }'; }
+REL_PATH=$(vr_row path)
+[ "$(vr_row where)" = inside ] || exit 0
+
+# The two registries the rules guard (the architecture registry has no
+# append-only rule in its header).
+case "$REL_PATH" in
+ design/registry/entities.yaml) REG=entities ;;
+ docs/architecture/tr-registry.yaml) REG=tr ;;
+ *) exit 0 ;;
+esac
+
+_VR_VALIDATE="run bash .claude/scripts/registry.sh validate after writing and fix what it reports"
+vr_skip() { vr_warn "Registry check skipped for $REL_PATH: $1. The write goes ahead; $_VR_VALIDATE."; }
+_VR_TOOL=$(vr_row tool)
+case "$_VR_TOOL" in Write|Edit) ;; *) vr_skip "the hook rebuilds Write and Edit only, not $_VR_TOOL" ;; esac
+case "$(vr_row new)" in
+ ok) ;;
+ notfound) vr_skip "old_string is not in the current file, so the new content could not be rebuilt" ;;
+ empty-old) vr_skip "an empty old_string on a file that has content could not be rebuilt" ;;
+ "unread "*) vr_skip "the hook could not read $(vr_row new | sed 's/^unread //') from the tool input" ;;
+ *) vr_skip "the new content could not be rebuilt" ;;
+esac
+
+_VR_OUT=$(bash .claude/scripts/registry.sh compare "$REG" "$REL_PATH" "$_VR_NEW" 2>/dev/null)
+
+# At most this many names per rule in the warning: a longer list buries the
+# point, and validate prints them all.
+_VR_MAX=5
+_VR_MSG=$(printf '%s\n' "$_VR_OUT" | VR_NEWP="$_VR_NEW" VR_MAX="$_VR_MAX" awk -F '\t' '
+ function add(list, n, item) { return (n <= ENVIRON["VR_MAX"]) ? list (n > 1 ? ", " : "") item : list }
+ function more(n) { return (n > ENVIRON["VR_MAX"]) ? ", and " (n - ENVIRON["VR_MAX"]) " more" : "" }
+ $1 == "removed" { removed = $2 }
+ $1 == "REMOVED" { nr++; rl = add(rl, nr, $4 " (line " $5 ")") }
+ $1 == "STATUS" { ns++; sl = add(sl, ns, $3 " set to " $4 " (line " $6 ")"); allowed = $5 }
+ $1 == "LAYOUT" && $3 == ENVIRON["VR_NEWP"] { nl++; ll = add(ll, nl, "line " $6 ": " $4 "; expected " $5) }
+ $1 == "LAYOUT" && $3 != ENVIRON["VR_NEWP"] { oldbad = 1 }
+ END {
+ if (nr) print "- It removes " nr (nr == 1 ? " entry" : " entries") " of the current file: " rl more(nr) ". Entries are never deleted or renumbered: keep each one and change its status instead (the header lists the values)."
+ if (ns) print "- It sets " ns (ns == 1 ? " status" : " statuses") " outside the allowed values (" allowed "): " sl more(ns) "."
+ if (nl) print "- The registry helper cannot read the layout of the new content at " nl (nl == 1 ? " line" : " lines") ": " ll more(nl) "."
+ if (removed == "-" && oldbad) print "- Removals were not checked: the current file has lines whose layout the helper cannot read."
+ }')
+
+[ -n "$_VR_MSG" ] || exit 0
+vr_warn "Registry check on $REL_PATH (a warning; the write goes ahead):
+$_VR_MSG
+Fix it in this write, or $_VR_VALIDATE."
diff --git a/.claude/hooks/validate-skill-change.sh b/.claude/hooks/validate-skill-change.sh
index 7347f3c7..c1d1c300 100644
--- a/.claude/hooks/validate-skill-change.sh
+++ b/.claude/hooks/validate-skill-change.sh
@@ -11,16 +11,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
diff --git a/.claude/hooks/validate-write.sh b/.claude/hooks/validate-write.sh
new file mode 100644
index 00000000..9ea2609b
--- /dev/null
+++ b/.claude/hooks/validate-write.sh
@@ -0,0 +1,152 @@
+#!/bin/bash
+
+# --- work from the project root ----------------------------------------------
+# Every path below is repo-relative, so a hook invoked with a working directory
+# that is not the repo root would silently read and write the WRONG TREE --
+# returning a near-empty result instead of the session-recovery block, and
+# creating stray trees such as docs/production/session-logs/ on write.
+#
+# PRECEDENCE IS LOAD-BEARING. A cwd that IS a project root carries real
+# information and must win: a caller sitting inside another project means that
+# project, not this one. Resolving to the script's own location first would
+# override them. So, in order:
+# 1. cwd holds project.yaml -> cwd (a project root)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
+# 4. this script's location -> <root>/.claude/hooks/../.. by construction
+# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
+# overriding a caller that legitimately means somewhere else.
+#
+# NOT an upward search: that resolves a nested project to its parent's config.
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
+ CCGS_ROOT="$PWD"
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
+ CCGS_ROOT="$CLAUDE_PROJECT_DIR"
+else
+ CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
+fi
+[ -n "$CCGS_ROOT" ] && cd "$CCGS_ROOT" 2>/dev/null || true
+
+# Claude Code PreToolUse hook: warns when a Write or Edit would break one of the
+# rules skills state in prose -- a file they never overwrite, the config guard,
+# the prototype boundary, the localization freeze, or the subagent write
+# exception. It runs BEFORE the write, while the old file can still be read.
+#
+# The logic is `.claude/scripts/write-guard.sh check`, its helper twin; this
+# hook reads the payload through `.claude/scripts/hook-input.sh` and calls it.
+# A skill that writes a guarded file runs write-guard.sh itself as its last
+# step, because hooks do not run in every tool.
+#
+# Exit behavior:
+# exit 0 always = advisory (it warns, never blocks)
+#
+# Input schema (PreToolUse for Write|Edit), plus agent_type inside a subagent:
+# { "tool_name": "Write", "tool_input": { "file_path": "...", "content": "..." } }
+# { "tool_name": "Edit", "tool_input": { "file_path": "...", "old_string": "...",
+# "new_string": "...", "replace_all": false } }
+
+INPUT=$(cat)
+
+# Most writes touch none of the guarded files. Leave before any parsing, with
+# builtins only: every rule needs a subagent's agent_type in the payload, one
+# of the words below in the file's path (a guarded name or a folder the rules
+# watch), or "prototypes" in the text written (a code file reaching into
+# prototypes/ names it). The path is tested only below the project root: the
+# payload's cwd and transcript_path, and the root part of an absolute path,
+# are the project's own folder, which can be named anything (.../Source/proj),
+# and matching them sent every Write through the full parse. A path value that
+# may end at an escaped quote is not trusted: then the whole payload is tested,
+# as before.
+case "$INPUT" in
+ *'"tool_input"'*'"file_path"'*) ;;
+ *) exit 0 ;;
+esac
+_VW_T=${INPUT#*'"tool_input"'}
+_VW_P=${_VW_T#*'"file_path"'}; _VW_P=${_VW_P#*'"'}
+_VW_REST="${_VW_T%%'"file_path"'*}${_VW_P#*'"'}" # the tool_input but the path
+_VW_P=${_VW_P%%'"'*}
+_vw_bs='\'
+case "$_VW_P" in
+ *"$_vw_bs") _VW_P=$INPUT; _VW_REST=$INPUT ;;
+ *"$_vw_bs$_vw_bs"*) _VW_P=${_VW_P//"$_vw_bs$_vw_bs"//} ;; # C:\\Users\\... as C:/Users/...
+esac
+# The root in both spellings Git Bash gives it: /c/Users/... and C:/Users/...
+# (the second read from the first; under a mount such as /tmp only pwd -W
+# knows it, which costs a subshell, so it is asked last).
+_vw_w=$PWD
+case "$PWD" in /[A-Za-z]/*) _vw_w="${PWD:1:1}:${PWD:2}" ;; esac
+shopt -s nocasematch
+case "$_VW_P" in
+ "$PWD"/*) _VW_P=${_VW_P:${#PWD}+1} ;;
+ "$_vw_w"/*) _VW_P=${_VW_P:${#_vw_w}+1} ;;
+ [A-Za-z]:/*) _vw_w=$(pwd -W 2>/dev/null)
+ case "$_VW_P" in "$_vw_w"/*) [ -n "$_vw_w" ] && _VW_P=${_VW_P:${#_vw_w}+1} ;; esac ;;
+esac
+shopt -u nocasematch
+_vw_go=0
+case "$INPUT" in *'"agent_type"'*) _vw_go=1 ;; esac
+case "$_VW_P" in
+ *EPIC.md*|*project.godot*|*helpers*|*tech-debt-register*|*engine-reference*) _vw_go=1 ;;
+ *project.yaml*|*project.local.yaml*|*review-mode.txt*|*prototypes*|*strings*) _vw_go=1 ;;
+ *tests*|*.github*|*production*|*Assets*|*Source*) _vw_go=1 ;;
+esac
+case "$_VW_REST" in *prototypes*) _vw_go=1 ;; esac
+[ "$_vw_go" = 1 ] || exit 0
+
+[ -f .claude/hooks/yaml-helper.sh ] && . .claude/hooks/yaml-helper.sh 2>/dev/null
+vw_warn() {
+ if command -v hook_warn >/dev/null 2>&1; then hook_warn PreToolUse "$1"
+ else printf '%s\n' "$1" >&2; fi
+ exit 0
+}
+for _vw_s in hook-input.sh write-guard.sh; do
+ [ -f ".claude/scripts/$_vw_s" ] || vw_warn "Write check skipped: the helper .claude/scripts/$_vw_s is missing, so the write goes ahead unchecked."
+done
+
+_VW_NEW=$(mktemp 2>/dev/null) || exit 0
+trap 'rm -f "$_VW_NEW"' EXIT
+_VW_IN=$(printf '%s' "$INPUT" | bash .claude/scripts/hook-input.sh --root . --new "$_VW_NEW" 2>/dev/null)
+vw_row() { printf '%s\n' "$_VW_IN" | awk -F '\t' -v k="$1" '$1 == k { print $2; exit }'; }
+_VW_WHERE=$(vw_row where); _VW_PATH=$(vw_row path); _VW_TOOL=$(vw_row tool)
+[ "$_VW_WHERE" = inside ] || exit 0
+case "$_VW_TOOL" in Write|Edit) ;; *) exit 0 ;; esac
+_VW_AGENT=$(vw_row agent); _VW_EXISTED=$(vw_row existed); _VW_GOT=$(vw_row new)
+
+set -- check "$_VW_PATH" --tool "$_VW_TOOL" --existed "$_VW_EXISTED"
+[ "$_VW_AGENT" != "-" ] && set -- "$@" --agent "$_VW_AGENT"
+if [ "$_VW_GOT" = ok ]; then
+ _VW_OUT=$(bash .claude/scripts/write-guard.sh --root . "$@" "$_VW_NEW" 2>/dev/null)
+else
+ # The content could not be rebuilt: the rules that read it (config,
+ # prototype) say so below; the others still run on the path.
+ _VW_OUT=$(bash .claude/scripts/write-guard.sh --root . "$@" 2>/dev/null)
+fi
+
+# At most this many findings in the warning: a longer list buries the point,
+# and the helper prints them all.
+_VW_MAX=6
+_VW_MSG=$(printf '%s\n' "$_VW_OUT" | VW_MAX="$_VW_MAX" VW_GOT="$_VW_GOT" VW_TOOL="$_VW_TOOL" awk -F '\t' '
+ function say(s) { n++; if (n <= ENVIRON["VW_MAX"]) print "- " s }
+ $1 == "checked" { rules = $3 }
+ $1 == "OVERWRITE" { say("It replaces " $2 ", which is never overwritten: " $3 ". Edit it in place, or ask first.") }
+ $1 == "ENUM" { say($2 " line " $6 ": " $3 " is " $4 ", not one of " $5 ".") }
+ $1 == "NOT_LOCAL" { say($2 " line " $4 ": " $3 " cannot be set locally, so resolution ignores it; it belongs in project.yaml.") }
+ $1 == "REVIEW_MODE" { say("It sets the review mode (" $3 ") in " $2 ". That pins it past what modes.rigor would choose; fine if you set it through /settings.") }
+ $1 == "PROTOTYPE_HEADER" { say($2 " lacks its " $3 " header in its first lines.") }
+ $1 == "PROTOTYPE_IMPORT" { say($2 " line " $4 ($3 == "into-production" ? " reaches from prototypes/ into the code root: " : " reaches from the code root into prototypes/: ") $5) }
+ $1 == "FREEZE" { say("The string freeze is ACTIVE (" $3 ", called " $4 "): record this change under Post-Freeze Changes there, or lift the freeze first.") }
+ $1 == "AGENT_WRITE" { say("A subagent (" $3 ") writes " $2 ($4 == "outside" ? ", outside production/, docs/ and tests/" : ", which already exists") ": the subagent exception covers only a new file at the path its skill named.") }
+ $1 == "SKIPPED" { say("Not checked (" $2 "): " $3 ".") }
+ END {
+ if (n > ENVIRON["VW_MAX"]) print "- and " (n - ENVIRON["VW_MAX"]) " more."
+ if (ENVIRON["VW_GOT"] != "ok" && ENVIRON["VW_GOT"] != "" && rules ~ /config|prototype/)
+ print "- The content was not read (" ENVIRON["VW_GOT"] "), so the config and prototype rules did not check it."
+ }')
+
+[ -n "$_VW_MSG" ] || exit 0
+vw_warn "Write check on $_VW_PATH (a warning; the write goes ahead):
+$_VW_MSG
+To see every finding: bash .claude/scripts/write-guard.sh check $_VW_PATH"
diff --git a/.claude/hooks/yaml-helper.sh b/.claude/hooks/yaml-helper.sh
index d4e2ffc8..ac0f3069 100644
--- a/.claude/hooks/yaml-helper.sh
+++ b/.claude/hooks/yaml-helper.sh
@@ -27,7 +27,8 @@
# validate_yaml_enum <file>
# Validates known enum-typed keys in <file> against their allowed
# value sets (12 enums hardcoded below). Prints one error line per
-# invalid value to stderr. Returns 1 if any invalid value found,
+# invalid value to stderr. Also reports tab indentation and repeated
+# keys (which the parsers merge). Returns 1 if any were found,
# 0 otherwise. Unknown-key (typo) detection is a future sub-phase —
# enum errors are the critical-path block per the spec.
#
@@ -38,7 +39,7 @@
#
# is_locally_overridable <dotted.path>
# Whitelist check for the /settings --local flag. Returns 0 if the
-# setting is on the personal-experience whitelist (12 settings per
+# setting is on the personal-experience whitelist (13 settings per
# effects-map.md), 1 otherwise. Locked settings cannot be locally
# overridden because they affect on-disk artifacts.
#
@@ -105,20 +106,52 @@ import sys, re
path_file, dotted = sys.argv[1], sys.argv[2]
keys = dotted.split('.')
+# THE TEXT OF A BLOCK SCALAR IS TEXT, NEVER KEYS.
+#
+# A value of `|` or `>`, with any chomping or indentation indicator (`|-`,
+# `>+`, `|2`) and an optional comment, opens a block scalar: every following
+# line indented deeper than its key, and every blank line among them, is the
+# scalar's text. Read as keys, a note such as
+# notes: |
+# review_mode: full
+# set modes.review_mode beside a real `review_mode: lean`, overwrote it, or
+# raised an enum error at session start for a value nobody set. The value kept
+# is still the indicator itself, as before; only the text stops being keys.
+# block_indent gives the indent the text must exceed when a line opens one
+# (the key's own column, or the dash's for a `- |` list item), else None.
+# validate_yaml_enum's duplicate-key walk skips block scalars by the same rule.
+def block_indent(stripped, indent):
+ rest = stripped
+ if rest == '-' or rest.startswith('- '):
+ rest = rest[1:].lstrip(' ')
+ if re.match(r'[|>][-+0-9]*\s*(#.*)?$', rest):
+ return indent
+ indent += len(stripped) - len(rest)
+ m = re.match(r'([^:#\s][^:]*?)\s*:\s*(.*)$', rest)
+ if m and re.match(r'[|>][-+0-9]*\s*(#.*)?$', m.group(2).strip()):
+ return indent
+ return None
+
def parse(lines):
root = {}
stack = [(-1, root)] # (indent, mapping)
+ block = None # indent a block scalar's text must exceed
for raw in lines:
line = raw.rstrip('\n').rstrip('\r')
stripped = line.lstrip(' ')
if not stripped.strip() or stripped.lstrip().startswith('#'):
continue
indent = len(line) - len(stripped)
+ if block is not None:
+ if indent > block:
+ continue
+ block = None
while stack and stack[-1][0] >= indent:
stack.pop()
if not stack:
return root
parent = stack[-1][1]
+ block = block_indent(stripped, indent)
m = re.match(r'([^:#\s][^:]*?)\s*:\s*(.*)$', stripped)
if not m:
continue
@@ -139,7 +172,20 @@ def parse(lines):
if hash_pos >= 0:
value = value[:hash_pos].strip()
if value == '':
- new_map = {}
+ # A REPEATED KEY MERGES INTO THE MAP ALREADY THERE.
+ #
+ # `parent[key] = {}` replaced it: a second `modes:` block further
+ # down the file wiped the first, so `rigor` and `automation` set in
+ # the first block fell back to their defaults and nothing said so.
+ # Two blocks is a realistic file, not a contrived one -- a user or a
+ # skill adding a setting appends a new block rather than finding
+ # the old one. Merging keeps both; a key set in both still takes
+ # the last value, as a scalar always has.
+ #
+ # Merging is not silence: validate_yaml_enum reports every repeated
+ # key, because YAML allows a key once and other YAML tools keep only
+ # the last block. Every parser in this file merges the same way.
+ new_map = parent[key] if isinstance(parent.get(key), dict) else {}
parent[key] = new_map
stack.append((indent, new_map))
else:
@@ -195,9 +241,23 @@ keys = dotted.split('.')
# Block-dash detection peeks ahead at indented child lines after a key
# whose own value is empty; if those children start with "- ", they form
# an array, otherwise they form a sub-map (existing behavior).
+# The text of a block scalar is text, never keys or items (see get_yaml_key).
+def block_indent(stripped, indent):
+ rest = stripped
+ if rest == '-' or rest.startswith('- '):
+ rest = rest[1:].lstrip(' ')
+ if re.match(r'[|>][-+0-9]*\s*(#.*)?$', rest):
+ return indent
+ indent += len(stripped) - len(rest)
+ m = re.match(r'([^:#\s][^:]*?)\s*:\s*(.*)$', rest)
+ if m and re.match(r'[|>][-+0-9]*\s*(#.*)?$', m.group(2).strip()):
+ return indent
+ return None
+
def parse(lines):
root = {}
stack = [(-1, root)]
+ block = None
i = 0
while i < len(lines):
raw = lines[i]
@@ -207,11 +267,17 @@ def parse(lines):
i += 1
continue
indent = len(line) - len(stripped)
+ if block is not None:
+ if indent > block:
+ i += 1
+ continue
+ block = None
while stack and stack[-1][0] >= indent:
stack.pop()
if not stack:
return root
parent = stack[-1][1]
+ block = block_indent(stripped, indent)
m = re.match(r'([^:#\s][^:]*?)\s*:\s*(.*)$', stripped)
if not m:
i += 1
@@ -270,6 +336,7 @@ def parse(lines):
# Peek: block-dash list or sub-map?
j = i + 1
items = []
+ pblock = None # an item's block scalar: its text is skipped
while j < len(lines):
pl = lines[j].rstrip('\n').rstrip('\r')
pstripped = pl.lstrip(' ')
@@ -277,9 +344,15 @@ def parse(lines):
j += 1
continue
pindent = len(pl) - len(pstripped)
+ if pblock is not None:
+ if pindent > pblock:
+ j += 1
+ continue
+ pblock = None
if pindent <= indent:
break
if pstripped.startswith('- '):
+ pblock = block_indent(pstripped, pindent)
# INDENT IS NOT ENFORCED between items, deliberately.
#
# Requiring every item to sit at the first item's indent
@@ -319,7 +392,9 @@ def parse(lines):
i = j
continue
else:
- new_map = {}
+ # A repeated key merges (see get_yaml_key). A list is not
+ # merged: the last one is used, and validate_yaml_enum says so.
+ new_map = parent[key] if isinstance(parent.get(key), dict) else {}
parent[key] = new_map
stack.append((indent, new_map))
else:
@@ -477,10 +552,12 @@ testing.strict.visual::true|false
testing.strict.ui::true|false
testing.strict.config::true|false
features.session_state::on|off
+features.read_guard::on|off|true|false
platform.online::true|false
workflow_overrides.edge_cases::true|false
workflow_overrides.tuning_knobs::true|false
-workflow_overrides.art_bible_strict::true|false"
+workflow_overrides.art_bible_strict::true|false
+updates.check::true|false"
# The boolean keys above are enumerated for the same reason the string keys are:
# `resolve_setting` validates every hop and DROPS a value that fails, so a key
# absent from this table accepts anything. Before they were listed,
@@ -496,7 +573,9 @@ workflow_overrides.art_bible_strict::true|false"
# - `features.session_state` is an ON/OFF enum, not a boolean. It is listed
# above as `on|off` because `session_state_enabled()` disables only on the
# literal `off`, and effects-map documents `on`/`off`. Writing `false` there
-# means ENABLED, which is why validating it matters.
+# means ENABLED, which is why validating it matters. `features.read_guard`
+# is not that case: read-guard.sh reads `true` and `false` as `on` and
+# `off`, so all four are listed for it.
# - `testing.strict` (the parent) is absent because its primary shape is a MAP
# of the five type keys; the bare scalar is only a back-compat form. Its
# effects-map `**Values:**` line documents the map, so enumerating the parent
@@ -525,7 +604,10 @@ testing.strict.ui
testing.strict.config
performance.enforce
features.session_state
-features.token_budget_warn_at"
+features.token_budget_warn_at
+features.read_guard
+features.read_guard_kb
+updates.check"
is_locally_overridable() {
local path="$1"
@@ -594,20 +676,39 @@ allowed = set(l.strip() for l in allowed_table.splitlines() if l.strip())
EXEMPT_EXACT = {'schema_version'}
EXEMPT_PREFIX = ('framework.',)
+# The text of a block scalar is text, never keys (see get_yaml_key).
+def block_indent(stripped, indent):
+ rest = stripped
+ if rest == '-' or rest.startswith('- '):
+ rest = rest[1:].lstrip(' ')
+ if re.match(r'[|>][-+0-9]*\s*(#.*)?$', rest):
+ return indent
+ indent += len(stripped) - len(rest)
+ m = re.match(r'([^:#\s][^:]*?)\s*:\s*(.*)$', rest)
+ if m and re.match(r'[|>][-+0-9]*\s*(#.*)?$', m.group(2).strip()):
+ return indent
+ return None
+
def parse(lines):
root = {}
stack = [(-1, root)]
+ block = None
for raw in lines:
line = raw.rstrip('\n').rstrip('\r')
stripped = line.lstrip(' ')
if not stripped.strip() or stripped.lstrip().startswith('#'):
continue
indent = len(line) - len(stripped)
+ if block is not None:
+ if indent > block:
+ continue
+ block = None
while stack and stack[-1][0] >= indent:
stack.pop()
if not stack:
return root
parent = stack[-1][1]
+ block = block_indent(stripped, indent)
m = re.match(r'([^:#\s][^:]*?)\s*:\s*(.*)$', stripped)
if not m:
continue
@@ -624,7 +725,8 @@ def parse(lines):
if hash_pos >= 0:
value = value[:hash_pos].strip()
if value == '':
- new_map = {}
+ # A repeated key merges (see get_yaml_key).
+ new_map = parent[key] if isinstance(parent.get(key), dict) else {}
parent[key] = new_map
stack.append((indent, new_map))
else:
@@ -746,20 +848,39 @@ import sys, re
path_file, enum_table = sys.argv[1], sys.argv[2]
+# The text of a block scalar is text, never keys (see get_yaml_key).
+def block_indent(stripped, indent):
+ rest = stripped
+ if rest == '-' or rest.startswith('- '):
+ rest = rest[1:].lstrip(' ')
+ if re.match(r'[|>][-+0-9]*\s*(#.*)?$', rest):
+ return indent
+ indent += len(stripped) - len(rest)
+ m = re.match(r'([^:#\s][^:]*?)\s*:\s*(.*)$', rest)
+ if m and re.match(r'[|>][-+0-9]*\s*(#.*)?$', m.group(2).strip()):
+ return indent
+ return None
+
def parse(lines):
root = {}
stack = [(-1, root)] # (indent, mapping)
+ block = None # indent a block scalar's text must exceed
for raw in lines:
line = raw.rstrip('\n').rstrip('\r')
stripped = line.lstrip(' ')
if not stripped.strip() or stripped.lstrip().startswith('#'):
continue
indent = len(line) - len(stripped)
+ if block is not None:
+ if indent > block:
+ continue
+ block = None
while stack and stack[-1][0] >= indent:
stack.pop()
if not stack:
return root
parent = stack[-1][1]
+ block = block_indent(stripped, indent)
m = re.match(r'([^:#\s][^:]*?)\s*:\s*(.*)$', stripped)
if not m:
continue
@@ -779,7 +900,8 @@ def parse(lines):
if hash_pos >= 0:
value = value[:hash_pos].strip()
if value == '':
- new_map = {}
+ # A repeated key merges (see get_yaml_key); reported below.
+ new_map = parent[key] if isinstance(parent.get(key), dict) else {}
parent[key] = new_map
stack.append((indent, new_map))
else:
@@ -810,15 +932,102 @@ data = parse(raw_lines)
#
# YAML forbids tabs for indentation, so reporting rather than repairing is
# correct; doing neither was the defect. Comment lines are exempt: a tab in
-# front of a `#` hides nothing.
+# front of a `#` hides nothing. So is a block scalar's text (parse() skips it
+# by the same rule): a tab after its indentation spaces is part of the text.
tab_lines = []
+_block = None
for _n, _raw in enumerate(raw_lines, 1):
_line = _raw.rstrip('\n').rstrip('\r')
if not _line.strip() or _line.lstrip(' \t').startswith('#'):
continue
+ _stripped = _line.lstrip(' ')
+ _indent = len(_line) - len(_stripped)
+ if _block is not None:
+ if _indent > _block:
+ continue
+ _block = None
_lead = _line[:len(_line) - len(_line.lstrip(' \t'))]
if '\t' in _lead:
tab_lines.append(_n)
+ _block = block_indent(_stripped, _indent)
+
+# A REPEATED KEY IS REPORTED, though every parser here now reads through it.
+#
+# Before the parsers merged, a second `modes:` block replaced the first and
+# this validator passed the file: the dropped `rigor: standard` was never read,
+# so it could not be invalid. Merging fixed what the framework reads, but YAML
+# allows a key once and other YAML tools keep only the last block, so the file
+# still means different things to different readers until it is tidied. Same
+# rule as the tab check: say what the parser had to work around.
+#
+# Its own walk, not parse(): the report needs line numbers, and whether an
+# empty-valued key opens a list (the last one is used) or a map (merged).
+# Each `- ` item of a list is a map of its own, named `list[n]`, so the keys of
+# a list of maps (two `- name:` items under specialists) are not repeats of
+# each other; a key twice inside one item still is. An item that is a quoted
+# scalar is not a key, even holding a colon. The text of a block scalar (a
+# value of `|` or `>`, with any indicators) is text: a `Note:` line in it is not
+# a key.
+def repeated_keys(lines):
+ rows = []
+ for n, raw in enumerate(lines, 1):
+ line = raw.rstrip('\n').rstrip('\r')
+ stripped = line.lstrip(' ')
+ if not stripped.strip() or stripped.lstrip().startswith('#'):
+ continue
+ rows.append((n, len(line) - len(stripped), stripped))
+ seen = {}
+ stack = [(-1, '', 'map')] # (indent, dotted path, map | list | item)
+ items = {} # list path -> items seen so far
+ block = None # indent a block scalar's text must exceed
+ key_re = r'([^:#\s][^:]*?)\s*:\s*(.*)$'
+ for i, (n, indent, stripped) in enumerate(rows):
+ if block is not None:
+ if indent > block:
+ continue
+ block = None
+ if stripped == '-' or stripped.startswith('- '):
+ # A dash at a list key's own indent (a compact list) belongs to it,
+ # so only deeper entries, and the item before this one, close here.
+ while stack[-1][0] > indent or (stack[-1][0] == indent and stack[-1][2] == 'item'):
+ stack.pop()
+ owner = stack[-1][1]
+ items[owner] = items.get(owner, 0) + 1
+ item = '%s[%d]' % (owner, items[owner])
+ stack.append((indent, item, 'item'))
+ rest = stripped[1:].lstrip(' ')
+ key_indent = indent + len(stripped) - len(rest)
+ if not rest or rest[0] in '"\'' or rest.startswith('#'):
+ continue
+ if re.match(r'[|>][-+0-9]*\s*(#.*)?$', rest):
+ block = indent
+ continue
+ m = re.match(key_re, rest)
+ if not m:
+ continue
+ key, value = m.group(1).strip(), m.group(2).strip()
+ indent = key_indent
+ path = item + '.' + key
+ else:
+ while stack[-1][0] >= indent:
+ stack.pop()
+ m = re.match(key_re, stripped)
+ if not m:
+ continue
+ key, value = m.group(1).strip(), m.group(2).strip()
+ path = stack[-1][1] + '.' + key if stack[-1][1] else key
+ kind = 'value'
+ if value == '' or value.startswith('#'):
+ nxt = rows[i + 1] if i + 1 < len(rows) else None
+ if nxt and nxt[1] >= indent and (nxt[2] == '-' or nxt[2].startswith('- ')):
+ kind = 'list'
+ else:
+ kind = 'map'
+ stack.append((indent, path, kind))
+ elif re.match(r'[|>][-+0-9]*\s*(#.*)?$', value):
+ block = indent
+ seen.setdefault(path, []).append((n, kind))
+ return [(p, occ) for p, occ in seen.items() if len(occ) > 1]
def lookup(dotted):
cur = data
@@ -842,6 +1051,16 @@ if tab_lines:
"settings silently fall back to defaults. Replace leading tabs "
"with spaces." % _shown)
errors += 1
+for _path, _occ in repeated_keys(raw_lines):
+ _at = ', '.join(str(n) for n, _ in _occ)
+ if all(k == 'map' for _, k in _occ):
+ out.append("duplicate key `%s` (lines %s): read here as one merged block, "
+ "but other YAML tools keep only the last. Combine them into "
+ "one." % (_path, _at))
+ else:
+ out.append("duplicate key `%s` (lines %s): only the last one is used. "
+ "Delete the others." % (_path, _at))
+ errors += 1
for line in enum_table.splitlines():
line = line.strip()
if not line or '::' not in line:
@@ -869,6 +1088,15 @@ validate_enum_value() {
local key="$1"
local value="$2"
[ -z "$key" ] && return 0
+ # testing.strict is left out of the enum table on purpose (its shape is a map
+ # of five types; see the note below the table). Written as ONE value it is the
+ # back-compat boolean, so it is checked like each type is: anything else was
+ # written and then read as unset, waiving a gate the user believed was on.
+ if [ "$key" = "testing.strict" ]; then
+ case "$value" in true|false) return 0 ;; esac
+ echo "Invalid value '$value' for '$key'. Allowed: true|false" >&2
+ return 1
+ fi
local line enum_path enum_values v
while IFS= read -r line; do
[ -z "$line" ] && continue
@@ -1279,20 +1507,39 @@ import sys, re
path_file, dotted = sys.argv[1], sys.argv[2]
keys = dotted.split('.')
+# The text of a block scalar is text, never keys (see get_yaml_key).
+def block_indent(stripped, indent):
+ rest = stripped
+ if rest == '-' or rest.startswith('- '):
+ rest = rest[1:].lstrip(' ')
+ if re.match(r'[|>][-+0-9]*\s*(#.*)?$', rest):
+ return indent
+ indent += len(stripped) - len(rest)
+ m = re.match(r'([^:#\s][^:]*?)\s*:\s*(.*)$', rest)
+ if m and re.match(r'[|>][-+0-9]*\s*(#.*)?$', m.group(2).strip()):
+ return indent
+ return None
+
def parse(lines):
root = {}
stack = [(-1, root)]
+ block = None
for raw in lines:
line = raw.rstrip('\n').rstrip('\r')
stripped = line.lstrip(' ')
if not stripped.strip() or stripped.lstrip().startswith('#'):
continue
indent = len(line) - len(stripped)
+ if block is not None:
+ if indent > block:
+ continue
+ block = None
while stack and stack[-1][0] >= indent:
stack.pop()
if not stack:
return root
parent = stack[-1][1]
+ block = block_indent(stripped, indent)
m = re.match(r'([^:#\s][^:]*?)\s*:\s*(.*)$', stripped)
if not m:
continue
@@ -1307,7 +1554,9 @@ def parse(lines):
if hp >= 0:
value = value[:hp].strip()
if value == '':
- nm = {}; parent[key] = nm; stack.append((indent, nm))
+ # A repeated key merges (see get_yaml_key).
+ nm = parent[key] if isinstance(parent.get(key), dict) else {}
+ parent[key] = nm; stack.append((indent, nm))
else:
parent[key] = value
return root
@@ -1345,7 +1594,9 @@ PYEOF
# knobs; a block of just those knobs is the saving.
# Valid key names are the output labels: rigor, review_mode, automation, workflow,
# docs.density, story_granularity, qa.level, team.size, project.stage,
-# automation_always_ask, engine, testing.strict, system_overrides.
+# automation_always_ask, engine, testing.strict, system_overrides; and, only when
+# named, the derived lines gate_level, engine_values, specialists, review_gate,
+# input_methods, perf_budgets.
resolve_config() {
_yaml_helper_set_root
local want=""
@@ -1374,9 +1625,23 @@ resolve_config() {
# Every file below is named under $_YH_ROOT. A bare `project.yaml` is the
# WORKING directory's, so run from src/ these checks found no file and
# reported nothing, while the values above them resolved from the root.
- local enum_err
+ # A repeated key is not "ignored": its blocks were merged and read. Those
+ # lines are split off so the suffix does not contradict them. Bash only, and
+ # only when something was reported -- this runs in every skill bootstrap.
+ local enum_err dup_lines="" bad_lines="" l
enum_err=$(validate_yaml_enum "$_YH_ROOT/project.yaml" 2>&1 >/dev/null)
- [ -n "$enum_err" ] && notes="${notes:+$notes; }$(echo "$enum_err" | tr '\n' ';' | sed 's/;$//') — ignored, chain continued"
+ if [ -n "$enum_err" ]; then
+ while IFS= read -r l; do
+ case "$l" in
+ "duplicate key "*) dup_lines="${dup_lines:+$dup_lines;}$l" ;;
+ ?*) bad_lines="${bad_lines:+$bad_lines;}$l" ;;
+ esac
+ done <<EOF
+$enum_err
+EOF
+ [ -n "$dup_lines" ] && notes="${notes:+$notes; }$dup_lines"
+ [ -n "$bad_lines" ] && notes="${notes:+$notes; }$bad_lines — ignored, chain continued"
+ fi
if [ -f "$_YH_ROOT/project.local.yaml" ]; then
enum_err=$(validate_yaml_enum "$_YH_ROOT/project.local.yaml" 2>&1 >/dev/null)
[ -n "$enum_err" ] && notes="${notes:+$notes; }local: $(echo "$enum_err" | tr '\n' ';' | sed 's/;$//')"
@@ -1577,6 +1842,205 @@ EOF
fi
fi
+ # --- Derived lines: answers six steps that skills used to work out by hand ---
+ # Each is printed ONLY when asked for by name (--keys gate_level,...): a block
+ # without --keys, and every existing --keys call, prints exactly what it did
+ # before and spawns no extra interpreter. Each value carries its source in
+ # parentheses, like every other line. YAML `null` and `~` read back as those
+ # strings, which are not empty, so they are mapped to unset here once rather
+ # than in every skill (a skill once started an agent called "null").
+ _rc_named() { [ -n "$want" ] && _rc_want "$1"; }
+ _rc_tag() { if [ -n "$1" ]; then printf '%s(%s)' "$1" "$2"; else printf unset; fi; }
+ _rc_yaml() { # _rc_yaml <file> <key>: the value, with null/~ as empty
+ local rv
+ rv=$(get_yaml_key "$1" "$2" 2>/dev/null)
+ case "$rv" in null|Null|NULL|"~") rv="" ;; esac
+ printf '%s' "$rv"
+ }
+ # _rc_tp <label>: a `- **Label**: value` line of the legacy
+ # technical-preferences.md; its `[TO BE CONFIGURED]` placeholder is unset.
+ _rc_tp() {
+ local f="$_YH_ROOT/.claude/docs/technical-preferences.md"
+ [ -f "$f" ] || return 0
+ awk -v lbl="**$1**:" '{ gsub(/\r/, "") }
+ index($0, lbl) { v = substr($0, index($0, lbl) + length(lbl))
+ sub(/^[ \t]+/, "", v); sub(/[ \t]+$/, "", v)
+ if (v !~ /TO BE CONFIGURED/) print v; exit }' "$f"
+ }
+ local tp_src=".claude/docs/technical-preferences.md"
+
+ # gate_level: the gate level per story type, as coding-standards.md's table
+ # defines it: testing.strict.<type> (project.local.yaml, then project.yaml),
+ # then the legacy plain `testing.strict: true|false`, then the default
+ # (blocking, except config/data: advisory). /smoke-check's own unset default
+ # for config is blocking (a build-health gate), so it is named beside config
+ # when config fell to the default. An invalid value is skipped, as in the
+ # testing.strict line above, and that line's notes name it.
+ local gl_all gl_out="" gk gv gsrc
+ if _rc_named gate_level; then
+ gl_all=$(get_yaml_key "$_YH_ROOT/project.yaml" testing.strict 2>/dev/null)
+ if [ -n "$gl_all" ] && ! validate_enum_value testing.strict.logic "$gl_all" 2>/dev/null; then gl_all=""; fi
+ for gk in logic integration visual ui config; do
+ gv=""; gsrc=""
+ if [ -f "$_YH_ROOT/project.local.yaml" ]; then
+ gv=$(get_yaml_key "$_YH_ROOT/project.local.yaml" "testing.strict.$gk" 2>/dev/null)
+ if [ -n "$gv" ] && ! validate_enum_value "testing.strict.$gk" "$gv" 2>/dev/null; then gv=""; fi
+ [ -n "$gv" ] && gsrc="project.local.yaml"
+ fi
+ if [ -z "$gv" ]; then
+ gv=$(get_yaml_key "$_YH_ROOT/project.yaml" "testing.strict.$gk" 2>/dev/null)
+ if [ -n "$gv" ] && ! validate_enum_value "testing.strict.$gk" "$gv" 2>/dev/null; then gv=""; fi
+ [ -n "$gv" ] && gsrc="project.yaml"
+ fi
+ if [ -z "$gv" ] && [ -n "$gl_all" ]; then gv="$gl_all"; gsrc="testing.strict"; fi
+ case "$gv" in
+ true) gl_out="$gl_out $gk=blocking($gsrc)" ;;
+ false) gl_out="$gl_out $gk=advisory($gsrc)" ;;
+ *) if [ "$gk" = "config" ]; then
+ gl_out="$gl_out config=advisory(default; /smoke-check: blocking)"
+ else
+ gl_out="$gl_out $gk=blocking(default)"
+ fi ;;
+ esac
+ done
+ echo "gate_level:$gl_out"
+ fi
+
+ # engine_values: engine.name, .version and .language from project.yaml, each
+ # falling back to technical-preferences.md, the record a v1.0 project that
+ # never migrated still has. Its Engine line holds name and version together
+ # ("Godot 4.6", "Unreal Engine 5.4"): the last word is the version when it
+ # starts with a digit. Locked keys, so project.local.yaml is not read.
+ local ev_name ev_ver ev_lang ev_line ev_ns ev_vs ev_ls
+ if _rc_named engine_values || _rc_named specialists; then
+ ev_name=$(_rc_yaml "$_YH_ROOT/project.yaml" engine.name); ev_ns="project.yaml"
+ ev_ver=$(_rc_yaml "$_YH_ROOT/project.yaml" engine.version); ev_vs="project.yaml"
+ ev_lang=$(_rc_yaml "$_YH_ROOT/project.yaml" engine.language); ev_ls="project.yaml"
+ if [ -z "$ev_name" ] || [ -z "$ev_ver" ]; then
+ ev_line=$(_rc_tp Engine)
+ if [ -n "$ev_line" ]; then
+ case "${ev_line##* }" in
+ [0-9]*) [ -z "$ev_ver" ] && { ev_ver="${ev_line##* }"; ev_vs="$tp_src"; }
+ [ -z "$ev_name" ] && { ev_name="${ev_line% *}"; ev_ns="$tp_src"; } ;;
+ *) [ -z "$ev_name" ] && { ev_name="$ev_line"; ev_ns="$tp_src"; } ;;
+ esac
+ fi
+ fi
+ if [ -z "$ev_lang" ]; then
+ ev_lang=$(_rc_tp Language); ev_ls="$tp_src"
+ fi
+ fi
+ if _rc_named engine_values; then
+ echo "engine_values: name=$(_rc_tag "$ev_name" "$ev_ns") version=$(_rc_tag "$ev_ver" "$ev_vs") language=$(_rc_tag "$ev_lang" "$ev_ls")"
+ fi
+
+ # specialists: the agents a skill starts for engine work. primary is derived
+ # from the engine (Godot -> godot-specialist), else the legacy Primary line.
+ # code, shader, ui and additional come from project.yaml's specialists block;
+ # a member set to null is UNSET, never an agent name. Only when the block is
+ # absent do they fall back to technical-preferences.md (the v1.0 migration
+ # writes the whole block, with null for each member it did not know).
+ local sp_primary sp_psrc sp_src sp_code sp_shader sp_ui sp_add
+ if _rc_named specialists; then
+ case "$(printf '%s' "$ev_name" | tr '[:upper:]' '[:lower:]')" in
+ godot) sp_primary="godot-specialist" ;;
+ unity) sp_primary="unity-specialist" ;;
+ unreal*) sp_primary="unreal-specialist" ;;
+ *) sp_primary="" ;;
+ esac
+ sp_psrc="engine.name"
+ if [ -z "$sp_primary" ]; then sp_primary=$(_rc_tp Primary); sp_psrc="$tp_src"; fi
+ if [ -n "$(get_yaml_child_keys "$_YH_ROOT/project.yaml" specialists 2>/dev/null)" ]; then
+ sp_src="project.yaml"
+ sp_code=$(_rc_yaml "$_YH_ROOT/project.yaml" specialists.code)
+ sp_shader=$(_rc_yaml "$_YH_ROOT/project.yaml" specialists.shader)
+ sp_ui=$(_rc_yaml "$_YH_ROOT/project.yaml" specialists.ui)
+ sp_add=$(get_yaml_array "$_YH_ROOT/project.yaml" specialists.additional 2>/dev/null \
+ | awk '$0 != "" && $0 != "null" && $0 != "~"' | paste -sd, - | sed 's/,/, /g')
+ else
+ sp_src="$tp_src"
+ sp_code=$(_rc_tp "Language/Code Specialist")
+ sp_shader=$(_rc_tp "Shader Specialist")
+ sp_ui=$(_rc_tp "UI Specialist")
+ sp_add=$(_rc_tp "Additional Specialists")
+ [ -z "$sp_code$sp_shader$sp_ui$sp_add" ] && sp_src="no specialists block"
+ fi
+ echo "specialists: primary=$(_rc_tag "$sp_primary" "$sp_psrc") code=${sp_code:-unset} shader=${sp_shader:-unset} ui=${sp_ui:-unset} additional=${sp_add:-none} ($sp_src; unset = skip that specialist)"
+ fi
+
+ # review_gate: whether a skill's own director gate runs, and whether the
+ # PHASE-GATEs run, at the resolved review_mode (director-gates.md): solo runs
+ # none, lean only the PHASE-GATEs, full all. How many PHASE-GATEs run is
+ # /gate-check's own rule (modes.workflow), not this line's.
+ local rg rgs rg_skill rg_phase
+ if _rc_named review_gate; then
+ rg=$(resolve_setting modes.review_mode)
+ rgs="${rg#*$(printf '\t')}"; rg="${rg%%$(printf '\t')*}"
+ case "$rg" in
+ full) rg_skill=run; rg_phase=run ;;
+ lean) rg_skill=skip; rg_phase=run ;;
+ *) rg_skill=skip; rg_phase=skip ;;
+ esac
+ echo "review_gate: skill-gates=$rg_skill phase-gates=$rg_phase (review_mode ${rg:-solo}, $rgs; a --review flag overrides)"
+ fi
+
+ # input_methods: the set of supported input methods, derived from project.yaml's
+ # platform block: keyboard/mouse when PC or Web is a target, gamepad and touch
+ # when their support is Full or Partial (Full | Partial | None, in any case:
+ # `full` is how every other value in the file is written), plus the primary
+ # input. Each method is listed once: a primary input spelt Keyboard, Mouse or
+ # Keyboard & Mouse is keyboard/mouse, Controller or Joypad is gamepad,
+ # Touchscreen is touch; any other primary input is added as written, in lower
+ # case. Without a platform block, technical-preferences.md's explicit Input
+ # Methods line. Locked keys, so project.local.yaml is not read.
+ local im_set="" im_t im_g im_to im_p im_pl
+ if _rc_named input_methods; then
+ if [ -n "$(get_yaml_child_keys "$_YH_ROOT/project.yaml" platform 2>/dev/null)" ]; then
+ im_t=$(get_yaml_array "$_YH_ROOT/project.yaml" platform.targets 2>/dev/null | tr '[:upper:]' '[:lower:]')
+ im_g=$(_rc_yaml "$_YH_ROOT/project.yaml" platform.gamepad_support)
+ im_to=$(_rc_yaml "$_YH_ROOT/project.yaml" platform.touch_support)
+ im_p=$(_rc_yaml "$_YH_ROOT/project.yaml" platform.primary_input)
+ printf '%s\n' "$im_t" | grep -qxE 'pc|web' && im_set="keyboard/mouse"
+ case "$im_g" in [Ff][Uu][Ll][Ll]|[Pp][Aa][Rr][Tt][Ii][Aa][Ll]) im_set="${im_set:+$im_set, }gamepad" ;; esac
+ case "$im_to" in [Ff][Uu][Ll][Ll]|[Pp][Aa][Rr][Tt][Ii][Aa][Ll]) im_set="${im_set:+$im_set, }touch" ;; esac
+ im_pl=$(printf '%s' "$im_p" | tr '[:upper:]' '[:lower:]')
+ case "$(printf '%s' "$im_pl" | tr -d ' ')" in
+ keyboard|mouse|keyboard/mouse|mouse/keyboard|keyboard+mouse|mouse+keyboard|keyboard\&mouse|mouse\&keyboard|keyboardandmouse|mouseandkeyboard|keyboard-mouse|kbm|kb/m|kb+m|m+kb|mkb)
+ im_pl="keyboard/mouse" ;;
+ gamepad|controller|gamecontroller|joypad) im_pl="gamepad" ;;
+ touch|touchscreen) im_pl="touch" ;;
+ esac
+ if [ -n "$im_pl" ]; then
+ case ", $im_set," in *", $im_pl,"*) ;; *) im_set="${im_set:+$im_set, }$im_pl" ;; esac
+ fi
+ echo "input_methods: ${im_set:-none} (project.yaml platform; primary: ${im_p:-unset})"
+ else
+ im_set=$(_rc_tp "Input Methods"); im_p=$(_rc_tp "Primary Input")
+ if [ -n "$im_set" ]; then
+ echo "input_methods: $im_set ($tp_src; primary: ${im_p:-unset})"
+ else
+ echo "input_methods: unset (no platform block in project.yaml, no Input Methods line)"
+ fi
+ fi
+ fi
+
+ # perf_budgets: the four committed performance budgets, each spelled out in
+ # full (the dead-settings audit matches whole dotted keys). Locked keys, so
+ # project.yaml only: a budget in project.local.yaml is reported on notes as
+ # not locally overridable and never applied, like every other locked key.
+ local pb_out="" pb_v
+ if _rc_named perf_budgets; then
+ pb_v=$(_rc_yaml "$_YH_ROOT/project.yaml" performance.target_framerate)
+ pb_out="$pb_out target_framerate=${pb_v:-unset}"
+ pb_v=$(_rc_yaml "$_YH_ROOT/project.yaml" performance.frame_budget_ms)
+ pb_out="$pb_out frame_budget_ms=${pb_v:-unset}"
+ pb_v=$(_rc_yaml "$_YH_ROOT/project.yaml" performance.draw_call_limit)
+ pb_out="$pb_out draw_call_limit=${pb_v:-unset}"
+ pb_v=$(_rc_yaml "$_YH_ROOT/project.yaml" performance.memory_ceiling_mb)
+ pb_out="$pb_out memory_ceiling_mb=${pb_v:-unset}"
+ echo "perf_budgets:$pb_out (project.yaml)"
+ fi
+
if [ "$bare" = "1" ]; then
# Bare form: values only. notes still surface, because a rejected enum value
# or a missing interpreter must never be silent.
@@ -1633,8 +2097,10 @@ hook_warn() {
# skill's own `allowed-tools`. That is also what lets a Bash-less agent preload
# the skill.
#
-# Only resolve_config is dispatchable: the bootstrap is the one caller, and
-# every name added here widens what a skill grant can reach.
+# resolve_config is what the bootstrap line runs. A short list of read-only
+# lookups (the second branch below) is dispatchable too, for skills that call
+# one through the Bash tool with a narrow grant. Every name added here widens
+# what a skill grant can reach, so only read-only lookups belong in that list.
#
# ROOT. Run from a subdirectory, the skill shell's cwd has no project.yaml and
# $CLAUDE_PROJECT_DIR is the launch directory, not the repo root, so
@@ -1643,7 +2109,10 @@ hook_warn() {
# fills CLAUDE_PROJECT_DIR when that has no project.yaml, so rules 1-2 (cwd
# first, for nested projects) keep their precedence.
#
-# ALWAYS exits 0: a non-zero exit from an injected command aborts the skill.
+# resolve_config, and a usage error, ALWAYS exit 0: a non-zero exit from an
+# injected command aborts the skill. The lookups exit with their function's
+# status (2 when the project root cannot be found), which is why none of them
+# belongs in an injected line.
if [ "${BASH_SOURCE[0]}" = "$0" ]; then
case "${1:-}" in
resolve_config)
@@ -1654,8 +2123,29 @@ if [ "${BASH_SOURCE[0]}" = "$0" ]; then
fi
resolve_config "$@"
;;
+ resolve_setting|get_yaml_key|get_effective_yaml_key|validate_yaml_enum|validate_enum_value|is_locally_overridable)
+ # Read-only lookups, run as `bash <path>/yaml-helper.sh <function> <args>`,
+ # so a skill can pre-approve them with one narrow grant. A `(cd ... && source
+ # ... && fn)` call matches no specific grant. Runs from the
+ # project root, as that form did, so project.yaml arguments resolve from a
+ # subfolder too; keeps the function's exit status (validate_enum_value and
+ # is_locally_overridable answer with it). is_locally_overridable also
+ # prints its 0 or 1: a caller that appends `; echo $?` to see it builds a
+ # compound command that no grant approves.
+ _yh_fn="$1"; shift
+ _yh_self_root=$(cd "$(dirname "$0")/../.." 2>/dev/null && pwd)
+ if [ -z "$_yh_self_root" ] || ! cd "$_yh_self_root"; then
+ echo "yaml-helper.sh: cannot find the project root from $0" >&2
+ exit 2
+ fi
+ "$_yh_fn" "$@"
+ _yh_rc=$?
+ [ "$_yh_fn" = is_locally_overridable ] && echo "$_yh_rc"
+ exit "$_yh_rc"
+ ;;
*)
echo "yaml-helper.sh: usage: bash yaml-helper.sh resolve_config [--keys k1,k2,...] [<system>]"
+ echo " bash yaml-helper.sh resolve_setting|get_yaml_key|get_effective_yaml_key|validate_yaml_enum|validate_enum_value|is_locally_overridable <args>"
;;
esac
exit 0
diff --git a/.claude/rules/scene-files.md b/.claude/rules/scene-files.md
new file mode 100644
index 00000000..3dde02f8
--- /dev/null
+++ b/.claude/rules/scene-files.md
@@ -0,0 +1,41 @@
+---
+paths:
+ - "**/*.tscn"
+ - "**/*.tres"
+ - "**/*.unity"
+ - "**/*.prefab"
+ - "Assets/**/*.asset"
+---
+
+# Scene and Asset File Rules
+
+The engine's editor writes these files. A hand edit that breaks one can stop a
+scene loading, or drop references without an error. Change them in the editor
+when you can.
+
+## Godot (`.tscn`, `.tres`, `.uid`)
+
+When you edit the text by hand:
+
+- Never change the `format=` value in the `[gd_scene]` or `[gd_resource]` header.
+- Never reuse an `id`: every `[ext_resource]` and `[sub_resource]` id is unique in its file.
+- Never copy a node block with its `unique_id=` (Godot 4.6+). Drop it from the copy.
+- Never invent a `uid://` value. Leave `uid=` off a new reference and let the
+ editor or `godot --headless --path . --import` assign it.
+- Never hand-edit TileMapLayer or GridMap cell data. It is encoded, so change it in the editor.
+- Never edit or delete a `.uid` file, and commit it with its script or shader.
+ Godot 4.4+ writes one beside each; when you move or rename the script or
+ shader outside the editor, move its `.uid` with it.
+- After a hand edit, run `godot --headless --path . --import` and open or run
+ the scene once to confirm it loads without errors.
+
+## Unity (`.unity`, `.prefab`, `.asset`)
+
+- Never hand-edit `.unity`, `.prefab` or `.asset` YAML while a Unity Editor is
+ reachable: open on this project, or reachable through its command-line or MCP
+ tools. The Editor holds its own copy, and its next save can overwrite or
+ conflict with the edit. Make the change through the Editor, or hand the user
+ the steps. If you cannot tell whether an Editor is reachable, treat it as reachable.
+- With no Editor reachable, keep every `fileID` and `guid` reference intact,
+ never invent a GUID, never edit or delete a `.meta` file, and open the scene
+ in the Editor afterwards to confirm it loads.
diff --git a/.claude/scripts/adr-dep-graph.sh b/.claude/scripts/adr-dep-graph.sh
index 65574ce3..d9e34e20 100644
--- a/.claude/scripts/adr-dep-graph.sh
+++ b/.claude/scripts/adr-dep-graph.sh
@@ -1,16 +1,18 @@
#!/usr/bin/env bash
-# adr-dep-graph.sh — build the ADR dependency graph and detect cycles.
+# adr-dep-graph.sh — build the ADR dependency graph, detect cycles, and give
+# the order to implement the ADRs in.
#
# Replaces a full read of every ADR (to extract one table row each) plus a manual
# cycle trace. A model tracing A→B→C→A across a dozen ADRs will eventually miss an
-# edge; Kahn's algorithm cannot. This is the deterministic half of
-# /gate-check's pre-production "ADR Circular Dependency Check".
+# edge; a graph walk cannot. This is the deterministic half of
+# /gate-check's pre-production "ADR Circular Dependency Check" and of
+# /architecture-review's dependency ordering.
#
# EMITS OBSERVATIONS, NOT A VERDICT (per .claude/docs/context-management.md rule 2).
# The caller (gate-pre-production) decides FAIL vs CONCERNS per tier. In
-# particular NO_DEPS_SECTION is load-bearing: it makes "no cycles because the
-# graph is clean" distinguishable from "no cycles because half the ADRs have no
-# dependency section".
+# particular NO_DEPS_SECTION and UNFILLED_DEPS are load-bearing: they make "no
+# cycles because the graph is clean" distinguishable from "no cycles because
+# half the ADRs have no dependency section, or never filled it in".
#
# Usage: bash .claude/scripts/adr-dep-graph.sh [adr-dir]
# adr-dir defaults to docs/architecture (relative to repo root). An explicit
@@ -21,13 +23,33 @@
# EDGES: one "adr-A -> adr-B" per Depends-On reference
# (or " (none)")
# NO_DEPS_SECTION: adr-X, ... ADRs with no `## ADR Dependencies` / no Depends On
-# CYCLE: adr-A -> adr-B -> adr-A one line per node in a dependency cycle
-# (absent when the graph is acyclic)
+# UNFILLED_DEPS: adr-X, ... ADRs whose Depends On row is still the
+# template's [bracketed] placeholder: what they
+# depend on is unknown, not none
+# CYCLE: adr-A -> adr-B one line per ADR on a dependency cycle (an ADR
+# that depends, through its edges, on itself),
+# with its edges to the ADRs on that cycle: one
+# of those edges is the one to cut
+# BLOCKED_BY_CYCLE: adr-X, ... ADRs on no cycle that depend on one, directly
+# or through others: they wait for the cycle to
+# break, and none of their own edges is the one
+# to cut
+# ORDER: adr-A, adr-B, ... every other ADR, dependencies first: those
+# that depend on nothing, then those whose
+# dependencies are all listed before them, and so
+# on, by id within each step. An ADR in
+# NO_DEPS_SECTION or UNFILLED_DEPS is placed as
+# if it depended on nothing; a Depends On target
+# with no file of its own is listed too
+# CYCLE and BLOCKED_BY_CYCLE are absent when there are none; ORDER is
+# "(none)" when every ADR is on or behind a cycle.
#
# CORRECTNESS NOTES (mirrors review-scope.sh):
# - `while IFS= read -r` everywhere: an ADR path with a space must not split.
# - IDs are normalised to lowercase `adr-NNNN` so a `Depends On: ADR-0003`
# reference matches the file `adr-0003-*.md`.
+# - The Depends On row is read as adr-status.sh reads it: every ADR-N on the
+# row is an edge, and the value cell decides placeholder versus none.
set -u
@@ -55,28 +77,43 @@ if [ -z "$adr_files" ]; then
exit 0
fi
-n=0; edges=""; no_deps=""
+SOH=$(printf '\001')
+n=0; edges=""; nodes=""; no_deps=""; unfilled=""
while IFS= read -r f; do
[ -n "$f" ] || continue
n=$((n + 1))
from=$(adr_id "$f")
+ [ -n "$from" ] && nodes="$nodes$from"$'\n'
- # Slice the `## ADR Dependencies` section, take the `**Depends On**` row, and
- # pull every ADR-NNNN out of its value cell. `None` yields no matches.
- deps_row=$(awk '
+ # Slice the `## ADR Dependencies` section and print its `**Depends On**`
+ # rows, then, after a \001, the first row's value cell (the whole row when
+ # it is not a table row).
+ deps=$(awk '
+ { sub(/\r$/, "") }
/^## /{ insec = ($0 ~ /## ADR Dependencies/) ? 1 : 0 }
- insec && /\*\*Depends On\*\*/ { print }
+ insec && /\*\*Depends On\*\*/ {
+ print
+ if (!got) {
+ got = 1; k = split($0, c, "|"); cell = (k >= 3) ? c[3] : ""
+ sub(/^[ \t]+/, "", cell); sub(/[ \t]+$/, "", cell)
+ if (cell == "") cell = $0
+ }
+ }
+ END { if (got) printf "\001%s\n", cell }
' "$f")
- if [ -z "$deps_row" ]; then
+ if [ -z "$deps" ]; then
no_deps="$no_deps $from"
continue
fi
+ cell=${deps##*"$SOH"}
+ deps_row=${deps%"$SOH"*}
to_ids=$(printf '%s' "$deps_row" | grep -oiE 'adr-[0-9]+' | tr 'A-Z' 'a-z' | sort -u)
if [ -z "$to_ids" ]; then
- # Section present but Depends On is "None" (or empty) — a real leaf, not a
- # missing section. Not reported under NO_DEPS_SECTION.
+ # Section present but Depends On names no ADR: "None" (or empty) is a
+ # real leaf; the template's [bracketed] text was never filled in.
+ case "$cell" in '['*) unfilled="$unfilled $from" ;; esac
continue
fi
while IFS= read -r t; do
@@ -102,42 +139,54 @@ else
done
fi
-# no_deps carries a leading space per append; strip it, then comma-join.
+# no_deps and unfilled carry a leading space per append; strip it, then comma-join.
[ -n "$no_deps" ] && echo "NO_DEPS_SECTION: $(printf '%s' "${no_deps# }" | sed 's/ /, /g')"
+[ -n "$unfilled" ] && echo "UNFILLED_DEPS: $(printf '%s' "${unfilled# }" | sed 's/ /, /g')"
-# Cycle detection — Kahn's algorithm on out-degree (a node "depends on" its
-# out-neighbours; a leaf depends on nothing remaining). Whatever cannot be peeled
-# away is part of a cycle. Reported as an observation; the caller sets the verdict.
-if [ -n "$edges" ]; then
- cyc=$(printf '%s' "$edges" | awk -F'\t' '
- NF==2 {
- e_from[++ne]=$1; e_to[ne]=$2
- node[$1]=1; node[$2]=1
- od[$1]++
- }
- END {
- total=0; for (x in node) total++
- removed=0; progress=1
- while (progress) {
- progress=0
- for (x in node) {
- if (gone[x] || od[x] > 0) continue
- gone[x]=1; removed++; progress=1
- for (i=1;i<=ne;i++)
- if (e_to[i]==x && !edone[i]) { edone[i]=1; od[e_from[i]]-- }
- }
+# An ADR is on a cycle when it can reach itself, which a walk from each ADR
+# answers. Peeling leaves (Kahn's algorithm) alone cannot: what is left over is
+# the cycles AND every ADR that depends on one, and naming those as cycle
+# members told the user to cut an edge that was fine. The order is the peeling,
+# done on the ADRs neither on nor behind a cycle. Observations only; the caller
+# sets the verdict.
+{ printf '%s' "$nodes" | awk 'NF { print "N\t" $0 }'
+ printf '%s' "$edges" | awk -F'\t' 'NF == 2 { print "E\t" $1 "\t" $2 }'; } | awk -F'\t' '
+ $1 == "N" { node[$2] = 1; next }
+ $1 == "E" { ne++; ef[ne] = $2; et[ne] = $3; node[$2] = 1; node[$3] = 1; adj[$2] = adj[$2] " " $3 }
+ function join(a, k, s, i) { s = ""; for (i = 1; i <= k; i++) s = s (i > 1 ? ", " : "") a[i]; return s }
+ END {
+ nn = 0; for (x in node) nl[++nn] = x
+ for (i = 2; i <= nn; i++) { v = nl[i]; for (j = i - 1; j >= 1 && nl[j] > v; j--) nl[j + 1] = nl[j]; nl[j + 1] = v }
+ # reach[s, y]: s depends on y through one or more edges.
+ for (i = 1; i <= nn; i++) {
+ s = nl[i]; split("", seen); q = 0; h = 1
+ k = split(adj[s], o, " "); for (j = 1; j <= k; j++) if (!(o[j] in seen)) { seen[o[j]] = 1; qu[++q] = o[j] }
+ while (h <= q) {
+ u = qu[h++]; k = split(adj[u], o, " ")
+ for (j = 1; j <= k; j++) if (!(o[j] in seen)) { seen[o[j]] = 1; qu[++q] = o[j] }
}
- if (removed < total)
- for (x in node) if (!gone[x]) print x
+ for (y in seen) reach[s, y] = 1
}
- ' | sort)
- if [ -n "$cyc" ]; then
- # printf '%s\n' (not '%s') so the final node isn't dropped by read.
- printf '%s\n' "$cyc" | while IFS= read -r x; do
- [ -n "$x" ] || continue
- # Show each cycle node with the in-cycle edges it participates in.
- outs=$(printf '%s' "$edges" | awk -F'\t' -v x="$x" '$1==x{printf " -> %s", $2}')
- echo "CYCLE: $x$outs"
- done
- fi
-fi
+ for (i = 1; i <= nn; i++) { x = nl[i]; if ((x, x) in reach) on[x] = 1 }
+ nb = 0
+ for (i = 1; i <= nn; i++) {
+ x = nl[i]
+ if (x in on) { line = "CYCLE: " x
+ # Only the edges into its own cycle: y on a cycle with x reaches x back.
+ for (e = 1; e <= ne; e++) if (ef[e] == x && (et[e] in on) && ((et[e], x) in reach)) line = line " -> " et[e]
+ print line; continue }
+ for (y in on) if ((x, y) in reach) { blocked[x] = 1; bl[++nb] = x; break }
+ }
+ if (nb) print "BLOCKED_BY_CYCLE: " join(bl, nb)
+ # The rest, layer by layer. None of their edges leads to a cycle (that
+ # would block them), so every out-degree counts only ADRs in this set.
+ for (e = 1; e <= ne; e++) if (!(ef[e] in on) && !(ef[e] in blocked)) od[ef[e]]++
+ nord = 0
+ do {
+ k = 0
+ for (i = 1; i <= nn; i++) { x = nl[i]; if (!(x in on) && !(x in blocked) && !(x in placed) && od[x] + 0 == 0) layer[++k] = x }
+ for (j = 1; j <= k; j++) { placed[layer[j]] = 1; ord[++nord] = layer[j] }
+ for (j = 1; j <= k; j++) for (e = 1; e <= ne; e++) if (et[e] == layer[j]) od[ef[e]]--
+ } while (k > 0)
+ print "ORDER: " (nord ? join(ord, nord) : "(none)")
+ }'
diff --git a/.claude/scripts/adr-status.sh b/.claude/scripts/adr-status.sh
new file mode 100644
index 00000000..08b466f4
--- /dev/null
+++ b/.claude/scripts/adr-status.sh
@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+# adr-status.sh — each ADR's status, layer, dates, dependencies and missing
+# sections, in one pass, so a skill reads a table instead of opening every ADR
+# and grepping `## Status -A 3` per file.
+#
+# Replaces the hand-run ADR reads in /architecture-decision, /architecture-review,
+# /create-control-manifest, /create-epics, /create-stories, /dev-story,
+# /gate-check, /code-review, /story-readiness, /adopt, /create-architecture,
+# /propagate-design-change and /project-stage-detect. adr-dep-graph.sh still
+# owns the dependency graph and its cycles; this script reads the same
+# Depends On row the same way, so the two agree on every edge.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# Whether a Proposed ADR blocks a story, which sections an ADR must have, and
+# what a missing Layer row means are the calling skill's rules: the skills'
+# own lists of required sections disagree, so this script reports every
+# section of the shipped template that is missing and leaves the choice there.
+#
+# Usage: bash .claude/scripts/adr-status.sh [--root DIR] [ID|PATH ...]
+# ID ADR-0003, adr-0003 or 0003: the ADR whose file name carries it
+# PATH an ADR file, relative to the root or absolute
+# (none) every docs/architecture/adr-*.md (one level, as adr-dep-graph.sh)
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+# An ADR named more than once (by ID, number or path) is reported once.
+#
+# Output: TSV. Counts first, then one row per ADR:
+# adrs <n> <scope>, template_sections <n> <template path>, then the number of
+# ADRs in each status: accepted, proposed, deprecated, superseded, unfilled,
+# other, no_status
+# ADR <id> <path> <status> <layer> <date> <last_verified> <version>
+# <depends_on> <superseded_by> <missing> <unfilled>
+# NOT_FOUND <ID or PATH> for an argument that names no ADR
+# Columns (`-` means not there):
+# status Accepted | Proposed | Deprecated | Superseded: the first word
+# under `## Status`; UNFILLED while it is still the template's
+# [bracket]; OTHER for anything else
+# layer the `**Layer**` row's value, or UNFILLED
+# date, last_verified the first YYYY-MM-DD under `## Date` and `## Last
+# Verified`, or UNFILLED
+# version last_verified, else date, else `unversioned` (the rule
+# /create-stories and /dev-story stamp stories with)
+# depends_on every ADR-N on the `**Depends On**` row of `## ADR
+# Dependencies`, as adr-NNNN, comma-separated; `none` when the
+# row names none; UNFILLED while it is the template's bracket
+# superseded_by the ADR a Superseded status names
+# missing the template's `##` sections this ADR lacks, comma-separated
+# (titles compared without case or a leading number)
+# unfilled how many lines are still a [bracketed] line of the template,
+# word for word
+# An empty file is still a row: no status (`-`, counted as no_status), every
+# template section missing.
+#
+# Exit codes: 0 every ADR asked for was read; 1 the root cannot be read;
+# 2 usage error; 3 an ID or PATH named no ADR (its NOT_FOUND row is printed,
+# the others are still reported). Reads only; never writes, never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk, sort and tolower.
+LC_ALL=C
+export LC_ALL
+
+ROOT_ARG=""
+ARGS=""
+NL='
+'
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root)
+ [ $# -ge 2 ] || { echo "adr-status: --root needs a value" >&2; exit 2; }
+ ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) echo "adr-status: unknown argument: $1 (try --help)" >&2; exit 2 ;;
+ *) ARGS="$ARGS$1$NL"; shift ;;
+ esac
+done
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "adr-status: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$(dirname "$0")/../.." 2>/dev/null || { echo "adr-status: cannot reach the repo root" >&2; exit 1; }
+fi
+
+ADR_DIR="docs/architecture"
+TEMPLATE=".claude/docs/templates/architecture-decision-record.md"
+# adr_id PATH — adr-dep-graph.sh's id: the first adr-<digits> in the name, lower case.
+adr_id() { printf '%s\n' "${1##*/}" | tr '[:upper:]' '[:lower:]' | grep -oE 'adr-[0-9]+' | head -1; }
+
+FILES=""; MISSED=""; SCOPE="$ADR_DIR/adr-*.md"
+ALL=$(find "$ADR_DIR" -maxdepth 1 -type f -name 'adr-*.md' 2>/dev/null | sort)
+# add_file PATH — onto FILES unless that file is there already, under any
+# spelling (-ef: the same file, whether named by ID, ./path or absolute path).
+add_file() {
+ while IFS= read -r g; do
+ [ -n "$g" ] && [ "$g" -ef "$1" ] && return 0
+ done <<EOF
+$FILES
+EOF
+ FILES="$FILES$1$NL"
+}
+if [ -z "$ARGS" ]; then
+ FILES="$ALL"
+else
+ SCOPE="arguments"
+ while IFS= read -r a; do
+ [ -n "$a" ] || continue
+ # A Windows path's backslashes as slashes, so its file name reads alike.
+ case "$a" in [A-Za-z]:\\*) a=$(printf '%s' "$a" | sed 's|\\|/|g') ;; esac
+ if [ -f "$a" ]; then add_file "${a#./}"; continue; fi
+ # An ID: ADR-0003, adr-0003 or 0003, compared on its number.
+ want=$(printf '%s' "$a" | tr '[:upper:]' '[:lower:]' | sed 's/^adr-//')
+ hit=""
+ case "$want" in
+ ''|*[!0-9]*) ;;
+ *) while IFS= read -r f; do
+ [ -n "$f" ] || continue
+ n=$(adr_id "$f"); n="${n#adr-}"
+ # Numbers compare as numbers: 3 and 0003 are one ADR.
+ [ -n "$n" ] && [ "$((10#$n))" = "$((10#$want))" ] && { hit="$f"; break; }
+ done <<EOF
+$ALL
+EOF
+ ;;
+ esac
+ if [ -n "$hit" ]; then add_file "$hit"; else MISSED="$MISSED$a$NL"; fi
+ done <<EOF
+$ARGS
+EOF
+fi
+
+LIST=$(printf '%s' "$FILES" | awk 'NF' )
+TPL_ARG=""
+[ -f "$TEMPLATE" ] && TPL_ARG="$TEMPLATE"
+
+# One awk over the template (when there is one) and every ADR. The heading and
+# fence rules are md-section.sh's: 1-6 # and a space after at most 3 spaces of
+# indent; nothing inside a ``` or ~~~ fence or an HTML comment is a heading.
+# The template, then the ADRs, go to awk on stdin, never as arguments (a long
+# list passes the command-line limit of some systems). Each becomes an input
+# file, "./" in front of a relative one so a name like x=1.md is not read as an
+# assignment; an absolute one (/..., C:/...) is opened as it is.
+{ [ -n "$TPL_ARG" ] && printf '%s\n' "$TPL_ARG"; printf '%s\n' "$LIST"; } | awk 'NF { sub(/^\.\//, ""); print }' | \
+TPL="$TPL_ARG" SCOPE="$SCOPE" awk '
+ # Git for Windows gawk reads files in text mode; BINMODE keeps the bytes.
+ BEGIN {
+ BINMODE = 3; tpl = ENVIRON["TPL"]; nadr = 0
+ # The list arrives on /dev/stdin, named, so the main input stays the files: with
+ # a bare getline, gawk read the first file as more of stdin and skipped its FNR 1.
+ while ((getline f < "/dev/stdin") > 0) lst[++nlst] = f
+ for (i = 1; i <= nlst; i++) ARGV[ARGC++] = (lst[i] ~ /^(\/|[A-Za-z]:)/) ? lst[i] : "./" lst[i]
+ na = 1
+ }
+ function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
+ function norm(s) {
+ s = tolower(trim(s)); gsub(/[ \t]+/, " ", s)
+ if (s ~ /^[0-9]+[.)]? /) sub(/^[0-9]+[.)]? /, "", s)
+ return s
+ }
+ function fence_of(s, n, c, k) {
+ n = 0; while (n < 3 && substr(s, n + 1, 1) == " ") n++
+ s = substr(s, n + 1); c = substr(s, 1, 1)
+ if (c != "`" && c != "~") return ""
+ k = 0; while (substr(s, k + 1, 1) == c) k++
+ return (k >= 3) ? substr(s, 1, k) : ""
+ }
+ function closes(s, f, n, c, k) {
+ n = 0; while (n < 3 && substr(s, n + 1, 1) == " ") n++
+ s = substr(s, n + 1); c = substr(f, 1, 1)
+ k = 0; while (substr(s, k + 1, 1) == c) k++
+ return k >= length(f) && trim(substr(s, k + 1)) == ""
+ }
+ function first_date(s) { return match(s, /[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/) ? substr(s, RSTART, RLENGTH) : "" }
+ # Every ADR-N in s, as adr-N lower case, in order, without repeats.
+ function adr_ids(s, out, seen, id) {
+ out = ""; split("", seen)
+ while (match(s, /[Aa][Dd][Rr]-[0-9]+/)) {
+ id = tolower(substr(s, RSTART, RLENGTH)); s = substr(s, RSTART + RLENGTH)
+ if (!(id in seen)) { seen[id] = 1; out = out (out == "" ? "" : ",") id }
+ }
+ return out
+ }
+ function cell2(s, n, c) { n = split(s, c, "|"); return n >= 3 ? trim(c[3]) : "" }
+ function value_of(raw) { return (raw == "") ? "-" : raw }
+
+ function flush( st, w, sb, ver, miss, i, t) {
+ if (cur == "") return
+ st = "-"; sb = "-"
+ if (status_line != "") {
+ w = status_line; gsub(/[*_`]/, "", w); w = tolower(trim(w)); sub(/[^a-z].*$/, "", w)
+ if (w == "accepted") st = "Accepted"
+ else if (w == "proposed") st = "Proposed"
+ else if (w == "deprecated") st = "Deprecated"
+ else if (w == "superseded") { st = "Superseded"; sb = adr_ids(status_line); if (sb == "") sb = "-"; else sub(/,.*/, "", sb) }
+ else if (substr(trim(status_line), 1, 1) == "[") st = "UNFILLED"
+ else st = "OTHER"
+ } else if ("status" in has) st = "OTHER"
+ cnt[st == "-" ? "no_status" : tolower(st)]++
+ d = (date_line == "") ? (("date" in has) ? "UNFILLED" : "-") : (first_date(date_line) != "" ? first_date(date_line) : "UNFILLED")
+ lv = (lv_line == "") ? (("last verified" in has) ? "UNFILLED" : "-") : (first_date(lv_line) != "" ? first_date(lv_line) : "UNFILLED")
+ ver = (lv ~ /^[0-9]/) ? lv : ((d ~ /^[0-9]/) ? d : "unversioned")
+ # The ids come from the whole row and an ADR naming itself is dropped, as
+ # adr-dep-graph.sh builds its edges; the cell decides UNFILLED versus none.
+ if (dep_seen) {
+ dep = ""; nd = split(adr_ids(dep_row), dl, ",")
+ for (i = 1; i <= nd; i++) if (dl[i] != cur_id) dep = dep (dep == "" ? "" : ",") dl[i]
+ if (dep == "") dep = (substr(dep_cell, 1, 1) == "[") ? "UNFILLED" : "none"
+ } else dep = "-"
+ lay = (layer_seen) ? ((substr(layer_cell, 1, 1) == "[") ? "UNFILLED" : value_of(layer_cell)) : "-"
+ miss = ""
+ for (i = 1; i <= ntpl; i++) if (!(tsec[i] in has)) miss = miss (miss == "" ? "" : ",") ttitle[i]
+ nadr++
+ t = cur_path; gsub(/\t/, " ", t); gsub(/\t/, " ", lay)
+ rows[nadr] = "ADR\t" cur_id "\t" t "\t" st "\t" lay "\t" d "\t" lv "\t" ver "\t" dep "\t" sb "\t" (miss == "" ? "-" : miss) "\t" unfilled
+ cur = ""
+ }
+
+ function begin(f) {
+ flush()
+ infence = ""; incomment = 0; sec = ""
+ if (f == "./" tpl) { intpl = 1 } else {
+ intpl = 0; cur = f; cur_path = f; sub(/^\.\//, "", cur_path)
+ # The id adr-dep-graph.sh uses: the first adr-<digits> in the file name, lower case.
+ b = tolower(cur_path); sub(/^.*\//, "", b); cur_id = match(b, /adr-[0-9]+/) ? substr(b, RSTART, RLENGTH) : "-"
+ split("", has); status_line = ""; date_line = ""; lv_line = ""
+ dep_seen = 0; dep_cell = ""; dep_row = ""; layer_seen = 0; layer_cell = ""; unfilled = 0
+ }
+ }
+ # An empty file has no line, so no FNR 1: every listed file awk passed over
+ # before f (all of them, for f "") is one, and is still a row.
+ function reach(f) {
+ while (na < ARGC && ARGV[na] != f) { begin(ARGV[na]); flush(); na++ }
+ if (na < ARGC) na++
+ }
+ FNR == 1 { reach(FILENAME); begin(FILENAME) }
+ {
+ line = $0; sub(/\r$/, "", line)
+ if (infence) { if (closes(line, infence)) infence = ""; next }
+ f = fence_of(line); if (f != "") { infence = f; next }
+ cstart = incomment; rest = ""; s = line
+ while (s != "") {
+ if (incomment) { p = index(s, "-->"); if (p == 0) { s = ""; break } s = substr(s, p + 3); incomment = 0 }
+ else { p = index(s, "<!--"); if (p == 0) { rest = rest s; s = ""; break } rest = rest substr(s, 1, p - 1); s = substr(s, p + 4); incomment = 1 }
+ }
+ h = line; n = 0; while (n < 3 && substr(h, n + 1, 1) == " ") n++
+ h = substr(h, n + 1); k = 0; while (substr(h, k + 1, 1) == "#") k++
+ if (!cstart && line !~ /^[ \t]*<!--/ && k >= 1 && k <= 6 && (length(h) == k || substr(h, k + 1, 1) == " " || substr(h, k + 1, 1) == "\t")) {
+ t = trim(substr(h, k + 1)); if (t ~ /(^| )#+$/) { sub(/#+$/, "", t); t = trim(t) }
+ if (k <= 2) sec = (k == 2) ? norm(t) : ""
+ if (k == 2) {
+ if (intpl) { if (!(norm(t) in tseen)) { tseen[norm(t)] = 1; ntpl++; tsec[ntpl] = norm(t); ttitle[ntpl] = t } }
+ else has[norm(t)] = 1
+ }
+ next
+ }
+ r = trim(rest)
+ if (intpl) { if (r ~ /\[/) tbr[r] = 1; next }
+ if (r == "") next
+ if (r in tbr) unfilled++
+ # The first line of text under a field heading is its value; a > quote is
+ # the template guidance, not the value.
+ if (substr(r, 1, 1) != ">") {
+ if (sec == "status" && status_line == "") status_line = r
+ if (sec == "date" && date_line == "") date_line = r
+ if (sec == "last verified" && lv_line == "") lv_line = r
+ }
+ if (!layer_seen && r ~ /^\|[ \t]*\*\*Layer\*\*[ \t]*\|/) { layer_seen = 1; layer_cell = cell2(r) }
+ if (sec == "adr dependencies" && !dep_seen && r ~ /\*\*Depends On\*\*/) { dep_seen = 1; dep_row = r; dep_cell = cell2(r); if (dep_cell == "") dep_cell = r }
+ }
+ END {
+ flush(); reach("")
+ printf "adrs\t%d\t%s\n", nadr, ENVIRON["SCOPE"]
+ printf "template_sections\t%d\t%s\n", ntpl, (tpl == "" ? "-" : tpl)
+ split("accepted proposed deprecated superseded unfilled other no_status", names, " ")
+ for (i = 1; i <= 7; i++) printf "%s\t%d\n", names[i], cnt[names[i]] + 0
+ for (i = 1; i <= nadr; i++) print rows[i]
+ }
+'
+
+rc=0
+while IFS= read -r m; do
+ [ -n "$m" ] || continue
+ printf 'NOT_FOUND\t%s\n' "$m"; rc=3
+done <<EOF
+$MISSED
+EOF
+exit $rc
diff --git a/.claude/scripts/agent-check.sh b/.claude/scripts/agent-check.sh
new file mode 100644
index 00000000..a56234a5
--- /dev/null
+++ b/.claude/scripts/agent-check.sh
@@ -0,0 +1,390 @@
+#!/usr/bin/env bash
+# agent-check.sh — observations about the agents and about every place a skill
+# hands work to one.
+#
+# /skill-test reads agents and skills as text and judges them. Some of what it
+# needs is mechanical and easy to miss by eye across 49 agent files: frontmatter
+# that does not parse, two descriptions close enough that the wrong agent gets
+# picked, an agent body that tells it to ask the user (an agent has no question
+# tool), a setting the tool ignores. This script finds those and prints them, so
+# every later change to an agent or a delegating skill is read the same way.
+#
+# OBSERVATIONS, NEVER VERDICTS (CLAUDE.md, "Helpers emit observations"). It
+# prints what it found, with denominators first, and always exits 0 once it has
+# run. Whether a tool list is beyond the job, whether two agents really overlap,
+# whether a brief is good enough: the reader decides. The delegation markers are
+# word counts, not grades.
+#
+# Usage: bash .claude/scripts/agent-check.sh [--agent <name>] [--skill <name>] [project-root]
+# --agent <name> one agent: its block, the overlap pairs it is in, and the
+# delegation blocks that name it
+# --skill <name> one skill: its delegation blocks only
+# project-root defaults to the repo root (the test suite passes fixtures)
+#
+# Output:
+# ROOT: <path>
+# AGENTS: <n> SKILLS: <n> SKILL_FILES: <n> DELEGATION_BLOCKS: <n>
+# AGENT: <name> frontmatter=<ok|missing|unclosed> model=<v|unset> effort=<v|unset> maxTurns=<v|unset>
+# description: <text>
+# tools: <list | unset (inherits all)> disallowed: <list> skills: <list>
+# NOTE: <kind> <detail> one line per observation
+# OVERLAP: <a> <b> jaccard=<x> shared=<words> (threshold printed first)
+# DELEGATION: <skill> <file>:<line> "<heading>" agents=<names> lines=<n>
+# markers: objective=<n> output=<n> sources=<n> boundaries=<n> recheck=<n>
+#
+# NOTE kinds:
+# frontmatter a line that is not `key: value`, a list item or a continuation;
+# a duplicate key; name missing or not the file name; no description
+# agent-type-list `tools` lists Agent(...) types. In an agent file the type list
+# is ignored; only the Agent tool itself counts
+# preload-off `skills:` preloads a skill that sets disable-model-invocation:
+# true, or one that does not exist
+# disallowed-specifier a `disallowedTools` entry with a specifier, e.g.
+# Bash(git push *): it removes the whole tool, not only those calls
+# memory-grants `memory:` is set, which turns on Read, Write and Edit even when
+# `tools` leaves them out
+# asks-user a body line that tells the agent to ask the user or wait for
+# approval; an agent's questions must come back in its report
+# no-delegations printed under DELEGATION when no block was found, so "none
+# found" is never silent
+
+set -u
+
+AGENT_FILTER=""
+SKILL_FILTER=""
+ROOT_ARG=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --agent|--skill)
+ [ $# -ge 2 ] || { echo "agent-check: $1 needs a value" >&2; exit 2; }
+ if [ "$1" = "--agent" ]; then AGENT_FILTER="$2"; else SKILL_FILTER="$2"; fi
+ shift 2 ;;
+ --agent=*) AGENT_FILTER="${1#--agent=}"; shift ;;
+ --skill=*) SKILL_FILTER="${1#--skill=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0"; exit 0 ;;
+ *) ROOT_ARG="$1"; shift ;;
+ esac
+done
+
+if [ -n "$ROOT_ARG" ]; then
+ ROOT="$ROOT_ARG"
+else
+ cd "$(dirname "$0")/../.." || { echo "agent-check: cannot reach repo root" >&2; exit 1; }
+ # `pwd -W` (Git Bash) gives C:/... so the Windows Python below can open it.
+ ROOT="$(pwd -W 2>/dev/null || pwd)"
+fi
+
+if [ ! -d "$ROOT/.claude/agents" ]; then
+ echo "agent-check: no .claude/agents folder under $ROOT" >&2
+ exit 1
+fi
+
+# Python fallback chain: python -> python3 -> py (matches yaml-helper.sh).
+PYBIN=""
+for candidate in python python3 py; do
+ if command -v "$candidate" >/dev/null 2>&1; then
+ if "$candidate" -c 'import sys; sys.exit(0 if sys.version_info[0] == 3 else 1)' >/dev/null 2>&1; then
+ PYBIN="$candidate"; break
+ fi
+ fi
+done
+if [ -z "$PYBIN" ]; then
+ echo "agent-check: no python 3 interpreter found (tried python, python3, py)" >&2
+ exit 1
+fi
+
+"$PYBIN" - "$ROOT" "$AGENT_FILTER" "$SKILL_FILTER" <<'PYEOF'
+import os
+import re
+import sys
+from itertools import combinations
+
+root, agent_filter, skill_filter = sys.argv[1:4]
+
+# Descriptions carry em-dashes; a cp1252 console would raise mid-report.
+try:
+ sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except (AttributeError, ValueError):
+ pass
+
+# Jaccard over distinctive description words. Descriptions are one line, so
+# scores run low: the pairs known to be confused (game-designer and
+# systems-designer, qa-lead and qa-tester) score 0.12-0.13.
+OVERLAP_THRESHOLD = 0.12
+COMMON_SHARE = 0.25 # a word in more than this share of descriptions is not distinctive
+STOPWORDS = set("""
+about after also among and any are been before being between both but can could each
+for from has have how into its like more most must not off one only other over own same
+should such than that the their them then there these they this those through under use
+used uses using via what when where which while who will with within without your
+""".split())
+
+ASKS_USER = re.compile(
+ r"AskUserQuestion"
+ r"|\bask(?:ing)? (?:the )?user\b"
+ r"|\bask(?:ing)? (?:the user |them )?(?:clarifying |architecture |design |follow-up )?questions?\b"
+ r"|\bMay I (?:write|create|edit|save|update|proceed|delete)\b"
+ r"|\bwait(?:ing)? for (?:the user|approval|confirmation|their)\b"
+ r"|\b(?:get|seek|obtain|request) (?:user |explicit )?(?:approval|sign-off|confirmation)\b"
+ r"|\bconfirm with the user\b",
+ re.IGNORECASE)
+
+NO_TOOL = re.compile(r"AskUserQuestion`? is not\b|\bno (?:question tool|`?AskUserQuestion`?)\b|\bwithout (?:a question tool|`?AskUserQuestion`?)", re.I)
+
+CUE = re.compile(
+ r"\bspawn|\bsub-?agents?\b|`Agent`|\bAgent tool\b|\bsubagent_type\b"
+ r"|\bdelegat|\bhand (?:it|this|them|each|the [\w-]+) (?:\w+ )?to\b|\bbrief\b",
+ re.IGNORECASE)
+
+MARKERS = {
+ "objective": re.compile(r"\bask (?:them|it|each)\b|\bto (?:review|check|write|design|draft|produce|validate|assess|evaluate|audit|analy[sz]e|create|implement|identify|find)\b|\bgoal\b|\bobjective\b", re.I),
+ "output": re.compile(r"\breturn\b|\boutput\b|\breport\b|\bformat\b|\bwrite (?:your|the|its) [\w ]{0,20}to\b", re.I),
+ "sources": re.compile(r"`[\w.-]+/[\w./*-]+`|\bread\b|\bpass\b|\binputs?\b|\bsources?\b", re.I),
+ "boundaries": re.compile(r"\bdo not\b|\bdon't\b|\bnever\b|\bonly\b|\bmust not\b", re.I),
+ "recheck": re.compile(r"\bre-?check|\bre-?verify|\bdouble-check|\bsecond opinion\b|\bverify (?:your|the|its) own\b", re.I),
+}
+
+
+def read(path):
+ with open(path, encoding="utf-8", errors="replace") as fh:
+ return fh.read()
+
+
+def frontmatter(text):
+ """Return (status, fields, notes, body_start_line). Hand-parsed: no PyYAML."""
+ lines = text.splitlines()
+ if not lines or lines[0].strip() != "---":
+ return "missing", {}, ["no frontmatter block"], 0
+ end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
+ if end is None:
+ return "unclosed", {}, ["frontmatter never closes with ---"], 0
+ fields, notes, key = {}, [], None
+ for n, line in enumerate(lines[1:end], start=2):
+ if not line.strip() or line.lstrip().startswith("#"):
+ continue
+ m = re.match(r"^([A-Za-z][\w-]*):(.*)$", line)
+ if m:
+ key = m.group(1)
+ if key in fields:
+ notes.append("duplicate key %s (line %d)" % (key, n))
+ fields[key] = m.group(2).strip()
+ elif key and re.match(r"^\s+(-\s+)?\S", line):
+ item = re.sub(r"^\s+(-\s+)?", "", line).strip()
+ fields[key] = (fields[key] + ", " + item).strip(", ")
+ else:
+ notes.append("line %d is not key: value: %s" % (n, line.strip()[:80]))
+ return "ok", fields, notes, end + 1
+
+
+def unquote(v):
+ v = v.strip()
+ if len(v) >= 2 and v[0] == v[-1] and v[0] in "\"'":
+ v = v[1:-1]
+ return v
+
+
+def split_list(v):
+ """Split a tools/skills value on commas outside parentheses; accepts [a, b]."""
+ v = unquote(v)
+ if v.startswith("[") and v.endswith("]"):
+ v = v[1:-1]
+ out, depth, cur = [], 0, ""
+ for ch in v:
+ if ch == "(":
+ depth += 1
+ elif ch == ")":
+ depth -= 1
+ if ch == "," and depth == 0:
+ out.append(unquote(cur))
+ cur = ""
+ else:
+ cur += ch
+ if cur.strip():
+ out.append(unquote(cur))
+ return [x for x in (s.strip() for s in out) if x]
+
+
+def words(text):
+ return {w for w in re.findall(r"[a-z]{4,}", text.lower()) if w not in STOPWORDS}
+
+
+# --- agents ---------------------------------------------------------------
+agent_dir = os.path.join(root, ".claude", "agents")
+skill_dir = os.path.join(root, ".claude", "skills")
+agents = {}
+for fn in sorted(os.listdir(agent_dir)):
+ if fn.endswith(".md"):
+ agents[fn[:-3]] = os.path.join(agent_dir, fn)
+
+skills = {}
+if os.path.isdir(skill_dir):
+ for d in sorted(os.listdir(skill_dir)):
+ p = os.path.join(skill_dir, d, "SKILL.md")
+ if os.path.isfile(p):
+ skills[d] = os.path.join(skill_dir, d)
+
+skill_files = []
+for name, d in skills.items():
+ for dirpath, _, files in os.walk(d):
+ for f in sorted(files):
+ if f.endswith(".md"):
+ skill_files.append((name, os.path.join(dirpath, f)))
+
+
+def model_invocation_off(skill):
+ d = skills.get(skill)
+ if not d:
+ return None
+ _, fm, _, _ = frontmatter(read(os.path.join(d, "SKILL.md")))
+ return unquote(fm.get("disable-model-invocation", "")).lower() == "true"
+
+
+records = {}
+for name, path in agents.items():
+ text = read(path)
+ status, fm, notes, body_start = frontmatter(text)
+ rec = {"status": status, "fm": fm, "notes": ["frontmatter " + n for n in notes]}
+ if status == "ok":
+ if "name" not in fm:
+ rec["notes"].append("frontmatter name missing")
+ elif unquote(fm["name"]) != name:
+ rec["notes"].append("frontmatter name %s is not the file name %s" % (unquote(fm["name"]), name))
+ if not unquote(fm.get("description", "")):
+ rec["notes"].append("frontmatter description missing or empty")
+ tools = split_list(fm.get("tools", ""))
+ typed = [t for t in tools if re.match(r"^Agent\s*\(", t)]
+ if typed:
+ rec["notes"].append("agent-type-list tools lists %s; in an agent file only the Agent tool counts, the type list is ignored" % typed[0])
+ for t in split_list(fm.get("disallowedTools", "")):
+ if "(" in t:
+ rec["notes"].append("disallowed-specifier disallowedTools lists %s; a specifier still removes the whole tool, not only the matching calls" % t)
+ if unquote(fm.get("memory", "")) and tools:
+ missing = [t for t in ("Read", "Write", "Edit") if t not in tools]
+ if missing:
+ rec["notes"].append("memory-grants memory: is set, which turns on %s although tools does not list them" % ", ".join(missing))
+ for sk in split_list(fm.get("skills", "")):
+ off = model_invocation_off(sk)
+ if off is None:
+ rec["notes"].append("preload-off skills: lists %s, which is not a skill in .claude/skills/" % sk)
+ elif off:
+ rec["notes"].append("preload-off skills: lists %s, which sets disable-model-invocation: true" % sk)
+ body = text.splitlines()[body_start:]
+ for i, line in enumerate(body, start=body_start + 1):
+ # A line that says the question tool is absent is the fix, not the problem.
+ if ASKS_USER.search(line) and not NO_TOOL.search(line):
+ rec["notes"].append("asks-user line %d: %s" % (i, line.strip()[:120]))
+ records[name] = rec
+
+# --- description overlap -------------------------------------------------
+desc_words = {n: words(unquote(r["fm"].get("description", ""))) for n, r in records.items()}
+df = {}
+for ws in desc_words.values():
+ for w in ws:
+ df[w] = df.get(w, 0) + 1
+limit = max(2, int(len(desc_words) * COMMON_SHARE))
+common = {w for w, c in df.items() if c > limit}
+distinct = {n: ws - common for n, ws in desc_words.items()}
+pairs = []
+for a, b in combinations(sorted(distinct), 2):
+ union = distinct[a] | distinct[b]
+ if not union:
+ continue
+ j = len(distinct[a] & distinct[b]) / len(union)
+ if j >= OVERLAP_THRESHOLD:
+ pairs.append((j, a, b, sorted(distinct[a] & distinct[b])))
+pairs.sort(key=lambda p: (-p[0], p[1], p[2]))
+
+# --- delegation blocks in skills ------------------------------------------
+weak = {n for n in agents if "-" not in n} # e.g. writer, producer: plain words too
+
+
+def names_in(text):
+ found = []
+ for n in agents:
+ if n in weak:
+ pat = r"(?:`%s`|\*\*%s\*\*|subagent_type:\s*%s\b)" % ((re.escape(n),) * 3)
+ else:
+ pat = r"(?<![\w-])%s(?![\w-])" % re.escape(n)
+ if re.search(pat, text):
+ found.append(n)
+ return found
+
+
+blocks = []
+for sname, path in skill_files:
+ lines = read(path).splitlines()
+ # Code fences hold templates and example output: a heading there does not
+ # start a block, and an agent named there is an example, not a hand-off.
+ # The markers still count fenced text, where a brief is often written out.
+ fenced, inside = [], False
+ for l in lines:
+ if l.lstrip().startswith("```"):
+ inside = not inside
+ fenced.append(True)
+ else:
+ fenced.append(inside)
+ starts = [i for i, l in enumerate(lines) if not fenced[i] and re.match(r"^#{1,6}\s", l)] or [0]
+ if starts[0] != 0:
+ starts.insert(0, 0)
+ for k, s in enumerate(starts):
+ e = starts[k + 1] if k + 1 < len(starts) else len(lines)
+ chunk = "\n".join(lines[s:e])
+ prose = "\n".join(l for i, l in enumerate(lines[s:e], start=s) if not fenced[i])
+ if not CUE.search(prose):
+ continue
+ named = names_in(prose)
+ if not named:
+ continue
+ heading = lines[s].lstrip("#").strip() if re.match(r"^#{1,6}\s", lines[s]) else "(top of file)"
+ marks = {k2: len(rx.findall(chunk)) for k2, rx in MARKERS.items()}
+ rel = os.path.relpath(path, root).replace(os.sep, "/")
+ blocks.append((sname, rel, s + 1, heading[:70], named, e - s, marks))
+
+# --- report --------------------------------------------------------------
+show_agents = sorted(agents) if not agent_filter else [agent_filter]
+if skill_filter:
+ show_agents = []
+show_blocks = [b for b in blocks
+ if (not skill_filter or b[0] == skill_filter)
+ and (not agent_filter or agent_filter in b[4])]
+
+print("ROOT: %s" % root)
+print("AGENTS: %d SKILLS: %d SKILL_FILES: %d DELEGATION_BLOCKS: %d"
+ % (len(agents), len(skills), len(skill_files), len(blocks)))
+if agent_filter and agent_filter not in agents:
+ print("NOT FOUND: agent %s is not a file in .claude/agents/" % agent_filter)
+ show_agents = []
+if skill_filter and skill_filter not in skills:
+ print("NOT FOUND: skill %s is not a folder in .claude/skills/" % skill_filter)
+
+for name in show_agents:
+ r = records[name]
+ fm = r["fm"]
+ print("AGENT: %s frontmatter=%s model=%s effort=%s maxTurns=%s" % (
+ name, r["status"], unquote(fm.get("model", "")) or "unset",
+ unquote(fm.get("effort", "")) or "unset", unquote(fm.get("maxTurns", "")) or "unset"))
+ print(" description: %s" % (unquote(fm.get("description", "")) or "(none)"))
+ tools = split_list(fm.get("tools", ""))
+ print(" tools: %s disallowed: %s skills: %s" % (
+ ", ".join(tools) if tools else "unset (inherits all)",
+ ", ".join(split_list(fm.get("disallowedTools", ""))) or "none",
+ ", ".join(split_list(fm.get("skills", ""))) or "none"))
+ for note in r["notes"]:
+ print(" NOTE: %s" % note)
+
+if not skill_filter:
+ print("OVERLAP_THRESHOLD: jaccard >= %.2f over description words in at most %d of %d descriptions"
+ % (OVERLAP_THRESHOLD, limit, len(desc_words)))
+ shown = [p for p in pairs if not agent_filter or agent_filter in (p[1], p[2])]
+ for j, a, b, shared in shown:
+ print("OVERLAP: %s %s jaccard=%.2f shared=%s" % (a, b, j, ",".join(shared)))
+ if not shown:
+ print("OVERLAP: none at or above the threshold")
+
+for sname, rel, line, heading, named, n, marks in show_blocks:
+ print('DELEGATION: %s %s:%d "%s" agents=%s lines=%d' % (sname, rel, line, heading, ",".join(named), n))
+ print(" markers: " + " ".join("%s=%d" % kv for kv in marks.items()))
+if not show_blocks and (skill_filter or not agent_filter or agent_filter in agents):
+ print("DELEGATION: no-delegations found in the files read")
+PYEOF
+exit 0
diff --git a/.claude/scripts/asset-scan.sh b/.claude/scripts/asset-scan.sh
new file mode 100644
index 00000000..ded6e144
--- /dev/null
+++ b/.claude/scripts/asset-scan.sh
@@ -0,0 +1,644 @@
+#!/usr/bin/env bash
+# asset-scan.sh — the measurements /asset-audit takes by hand: asset names
+# against the naming rule, PNG power-of-two dimensions, file sizes against the
+# budgets you pass, audio sample rates where `file` reports one, and assets no
+# source file references (orphans) or source references to a file that is not
+# there (missing), each with the check that ran or the reason it did not.
+#
+# Replaces the hand-run asset scan: the file listing, `wc -c`, the PNG header
+# read with `od`, the sample rate read with `file`, and the orphan and
+# missing-asset searches.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# A row is a rule that matched a file; the counts under "hits" are rows, not
+# violations, and the words the skill ranks its report by (COMPLIANT,
+# WARNINGS, NON-COMPLIANT, NOT ASSESSED) stay in the skill. A check that did
+# not run says so in a `check` row and its hits are `-`, never 0: a scan that
+# measured nothing is not a scan that found nothing.
+#
+# Usage: bash .claude/scripts/asset-scan.sh [--root DIR] [--engine E] [--category C]
+# [--budget KEY=SIZE ...] [--max-dim N] [--sample-rates LIST]
+# [--name-regex ERE] [--files]
+# --root DIR the project; defaults to the repo this script is in
+# --engine E godot, unity or unreal (default: engine.name from
+# project.local.yaml, then project.yaml, as content-count.sh)
+# --category C keep one category: on godot a folder of assets/ (art,
+# audio, vfx, shaders or data); on unity and unreal the
+# first folder under the asset root (any case)
+# --budget KEY=SIZE a size budget in bytes, or with a K (1024) or M
+# (1048576) suffix. Budgets are prose in the art bible,
+# so they are flags and never read from it. KEY is `all`,
+# a type (texture, audio, data, other) or a file
+# extension (png, ogg, ...); the most specific one that
+# applies wins: extension, then type, then all. A key
+# given twice is an error. A file of exactly SIZE bytes
+# is inside its budget.
+# --max-dim N a texture whose width or height is above N pixels
+# --sample-rates L comma-separated Hz values audio may have (44100,48000)
+# --name-regex ERE the art bible's naming rule: replaces the built-in rule,
+# and is the only naming rule on unity and unreal; matched
+# against the file name with its extension
+# --files one FILE row per scanned file
+# -h, --help this text
+#
+# What is scanned (the skill's Phase 2):
+# godot assets/art, assets/audio, assets/vfx, assets/shaders, assets/data
+# (other folders of assets/ are counted as outside_scope, not scanned)
+# unity Assets/, leaving out scripts (.cs, .asmdef) and .meta files
+# unreal Content/*.uasset and Content/*.umap
+# Left out on every engine: .gitkeep placeholders. Left out on godot: .import
+# files (the importer writes one beside each source asset; it is not an asset
+# and its source_file line is not a reference) and .uid files (Godot 4.4+
+# writes one beside each script and shader). Each left-out kind is counted in
+# an `excluded` row.
+#
+# Naming (the skill's Phase 3): all file names lowercase with underscores. The
+# built-in rule is the characters a-z 0-9 and _ in the name and a-z 0-9 in the
+# extension, one dot before the extension; a NAMING row lists what broke it, in
+# order of first appearance: uppercase, space, hyphen, dot (an extra one), other.
+# The art and audio patterns ([category]_[name]_[variant]_[size].[ext] and
+# [category]_[context]_[name]_[variant].[ext]) are NOT CHECKABLE from the
+# skill: it defines no category or size values and its own examples disagree
+# on what fills the size slot, so a `check` row says so with the number of
+# files each would cover, and nothing is compared against them.
+#
+# Textures: PNG width and height are read from the IHDR header (24 bytes: 8 of
+# signature, 4 of chunk length, 4 of chunk name, 4 of width, 4 of height, all
+# big-endian) with `od`. A dimension is a power of two when halving it reaches
+# 1 without an odd step (awk here has no bitwise operators); 0 is not one. A
+# texture in another format, or a PNG with no readable header, is a NOTREAD
+# row. Compression for 3D and PNG for UI are not checked: the skill does not
+# say how to tell a UI texture from a 3D one. On unreal an asset file keeps
+# neither its source format nor its dimensions, so dimensions and sample
+# rates are not read there.
+#
+# Audio: the sample rate is the `N Hz` (or `N.N kHz`) that `file -b` prints; a
+# file `file` reports no rate for is a NOTREAD row. Duration is not measurable
+# here. File size is `wc -c`, never `stat`, which differs between GNU and BSD;
+# for the same reason the last-modified time the skill lists with its orphans
+# is not read.
+#
+# Orphans and missing (godot only): the references are the res:// paths found
+# in every .gd, .cs, .gdshader, .gdshaderinc, .tscn and .tres file of the
+# project (except under .godot/ and .git/) and in project.godot, so a scene or
+# resource that names an asset counts. A path ends at a quote, a bracket, a
+# comma, a semicolon or (when it did not start in quotes) a space. An asset is
+# an ORPHAN when no other file names its path. A path ending in / is a folder
+# prefix (DYNAMIC prefix): it covers every asset below it, and the row says how
+# many. A path with % or * or ? is a built name (DYNAMIC pattern) and covers
+# nothing. A reference to a file under assets/ that does not exist is MISSING,
+# with the first place it appears and how many places name it. Both need at
+# least one .gd, .cs or .gdshader file under src/ (the skill: no code to
+# search means not assessed), and run only on godot: on unity and unreal most
+# references live in scenes, prefabs and other assets, and no reference syntax
+# for them is defined here.
+#
+# Output: TSV, in this order.
+# engine <name> <source: flag, project.yaml, ...>, root <dir> present|absent,
+# category_filter <name> (with --category), scanned <n>, outside_scope <n> <note>
+# (godot), excluded <kind> <n> per kind, category <name> <n> per category
+# (godot: art, audio, vfx, shaders, data; others: by name, `-` for files
+# directly in the root), check <name> <ran | not_run | not_checkable> <detail>
+# for naming, art_pattern, audio_pattern, pot, size, dim, rate, orphans,
+# missing, data, format and last_modified, then hits <kind> <n | -> for
+# naming, pot, size, dim, rate, notread, orphan and missing, then the rows:
+# NAMING <path> <rule> <what broke it>
+# POT <path> <WxH> <width | height | both>
+# SIZE <path> <bytes> <budget> <overage> <key: all | type:T | ext:E>
+# DIM <path> <WxH> <max>
+# RATE <path> <hz> <allowed>
+# NOTREAD <path> <dims | rate> <reason>
+# ORPHAN <path> <bytes>
+# MISSING <expected path> <file:line of the first reference> <references>
+# DYNAMIC <prefix | pattern> <path> <file:line> <assets covered | ->
+# FILE <path> <category> <type> <bytes> <WxH | -> <hz | -> (with --files)
+# Rows of one kind are in path order (bytewise).
+#
+# Exit codes: 0 scanned (whatever it found, none included); 1 the root cannot
+# be read, or a script it needs is missing; 2 usage error; 3 no engine set, or
+# an engine without rules (prints its engine row); 4 the asset root is absent
+# (its root row says absent), so nothing was scanned. Reads only; never
+# writes, never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python. BWK awk's split() with
+# a one-character separator also splits on newlines, so split() is used here
+# only on a single line (a path, a row) or on a list whose separator is the
+# newline itself. Listings reach awk on stdin with "./" in front of every
+# file name (never as arguments), so a file called x=1.gd is not an assignment.
+
+set -u
+# Byte semantics for awk, sort and tolower.
+LC_ALL=C
+export LC_ALL
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+usage() { echo "asset-scan: $1 (try --help)" >&2; exit 2; }
+TAB=$(printf '\t')
+
+ROOT_ARG=""; ENGINE_ARG=""; CATF=""; BUDGETS=""; BUDGET_FLAGS=""; MAXDIM=""
+RATES=""; NAMERE=""; SHOWFILES=0; BSPEC=""; BGOT=0
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root) [ $# -ge 2 ] || usage "--root needs a value"; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --engine) [ $# -ge 2 ] || usage "--engine needs a name"; ENGINE_ARG="$2"; shift 2 ;;
+ --engine=*) ENGINE_ARG="${1#--engine=}"; shift ;;
+ --category) [ $# -ge 2 ] || usage "--category needs a name"; CATF="$2"; shift 2 ;;
+ --category=*) CATF="${1#--category=}"; shift ;;
+ --budget) [ $# -ge 2 ] || usage "--budget needs KEY=SIZE"; BSPEC="$2"; BGOT=1; shift 2 ;;
+ --budget=*) BSPEC="${1#--budget=}"; BGOT=1; shift ;;
+ --max-dim) [ $# -ge 2 ] || usage "--max-dim needs a number"; MAXDIM="$2"; shift 2 ;;
+ --max-dim=*) MAXDIM="${1#--max-dim=}"; shift ;;
+ --sample-rates) [ $# -ge 2 ] || usage "--sample-rates needs a list"; RATES="$2"; shift 2 ;;
+ --sample-rates=*) RATES="${1#--sample-rates=}"; shift ;;
+ --name-regex) [ $# -ge 2 ] || usage "--name-regex needs a pattern"; NAMERE="$2"; shift 2 ;;
+ --name-regex=*) NAMERE="${1#--name-regex=}"; shift ;;
+ --files) SHOWFILES=1; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) usage "unknown argument: $1" ;;
+ *) usage "unexpected argument: $1" ;;
+ esac
+ # A --budget was just read: check it and add it. (Done after the case so
+ # that both spellings share the checks.)
+ if [ "$BGOT" = 1 ]; then
+ case "$BSPEC" in *=*) ;; *) usage "--budget takes KEY=SIZE, got $BSPEC" ;; esac
+ BK="${BSPEC%%=*}"; BV="${BSPEC#*=}"
+ [ -n "$BK" ] && [ -n "$BV" ] || usage "--budget takes KEY=SIZE, got $BSPEC"
+ case "$BK" in *[!A-Za-z0-9]*) usage "--budget key must be letters and digits, got $BK" ;; esac
+ case "$BV" in *[!0-9KkMm]*) usage "--budget size is a number of bytes with an optional K or M, got $BV" ;; esac
+ BD="${BV%[KkMm]}"
+ case "$BD" in ''|*[!0-9]*) usage "--budget size is a number of bytes with an optional K or M, got $BV" ;; esac
+ # K is 1024 bytes and M is 1048576: sizes are file sizes, not marketing sizes.
+ BN=$((10#$BD))
+ case "$BV" in *[Kk]) BN=$((BN * 1024)) ;; *[Mm]) BN=$((BN * 1048576)) ;; esac
+ BL=$(printf '%s' "$BK" | tr 'A-Z' 'a-z')
+ case "$BL" in
+ all) BCAN="all" ;;
+ texture|audio|data|other) BCAN="type:$BL" ;;
+ *) BCAN="ext:$BL" ;;
+ esac
+ case "
+$BUDGETS" in *"
+$BCAN="*) usage "--budget key $BK given twice" ;; esac
+ BUDGETS="$BUDGETS$BCAN=$BN
+"
+ BUDGET_FLAGS="${BUDGET_FLAGS:+$BUDGET_FLAGS }$BSPEC"
+ BGOT=0
+ fi
+done
+if [ -n "$MAXDIM" ]; then
+ case "$MAXDIM" in ''|*[!0-9]*) usage "--max-dim takes a whole number of pixels" ;; esac
+ [ $((10#$MAXDIM)) -ge 1 ] || usage "--max-dim takes a number above 0"
+ MAXDIM=$((10#$MAXDIM))
+fi
+if [ -n "$RATES" ]; then
+ case "$RATES" in ''|*[!0-9,]*|,*|*,|*,,*) usage "--sample-rates takes comma-separated Hz values, got $RATES" ;; esac
+fi
+if [ -n "$NAMERE" ]; then
+ # An invalid pattern is a usage error here, not an awk crash halfway through.
+ R="$NAMERE" awk 'BEGIN { x = ("" ~ ENVIRON["R"]) }' >/dev/null 2>&1 || usage "--name-regex is not a valid regular expression: $NAMERE"
+fi
+CATF=$(printf '%s' "$CATF" | tr 'A-Z' 'a-z')
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "asset-scan: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "asset-scan: cannot reach the repo root" >&2; exit 1; }
+fi
+
+# ----------------------------------------------------------------------- engine
+# engine.name from project.local.yaml, then project.yaml, read by the shared
+# yaml-get.awk as content-count.sh reads it; only when neither names one,
+# project-state.sh's legacy fallback decides.
+if [ -n "$ENGINE_ARG" ]; then
+ RAW="$ENGINE_ARG"; ESRC="flag"
+else
+ RAW=""; ESRC=""
+ [ -f "$HERE/yaml-get.awk" ] || { echo "asset-scan: $HERE/yaml-get.awk is missing; pass --engine" >&2; exit 1; }
+ for yf in project.local.yaml project.yaml; do
+ if [ -z "$RAW" ] && [ -f "$yf" ]; then
+ RAW=$(YG_PATH=engine.name awk -f "$HERE/yaml-get.awk" "$yf")
+ [ -z "$RAW" ] || ESRC="$yf"
+ fi
+ done
+ if [ -z "$RAW" ] && [ -f "$HERE/project-state.sh" ]; then
+ ROW=$(bash "$HERE/project-state.sh" --root . | awk -F'\t' '$1 == "engine" { print $2 "\t" $3 }')
+ RAW="${ROW%%"$TAB"*}"; ESRC="${ROW#*"$TAB"}"
+ fi
+fi
+if [ -z "$RAW" ] || [ "$RAW" = "-" ]; then
+ printf 'engine\t-\tunset\n'
+ echo "asset-scan: no engine is set (engine.name in project.yaml); pass --engine" >&2
+ exit 3
+fi
+LOW=$(printf '%s' "$RAW" | tr '[:upper:]' '[:lower:]')
+# The asset root per engine is the skill's Phase 2: assets/ on Godot, Assets/ on
+# Unity, Content/ on Unreal.
+case "$LOW" in
+ godot) ENG=godot; ROOTDIR=assets ;;
+ unity) ENG=unity; ROOTDIR=Assets ;;
+ unreal*) ENG=unreal; ROOTDIR=Content ;;
+ *)
+ if [ "$ESRC" = flag ]; then usage "--engine takes godot, unity or unreal, got $RAW"; fi
+ printf 'engine\t%s\t%s\n' "$RAW" "$ESRC"
+ echo "asset-scan: engine $RAW has no asset rules here (godot, unity or unreal)" >&2
+ exit 3 ;;
+esac
+if [ "$ENG" = godot ] && [ -n "$CATF" ]; then
+ case "$CATF" in
+ art|audio|vfx|shaders|data) ;;
+ *) usage "--category on godot takes art, audio, vfx, shaders or data, got $CATF" ;;
+ esac
+fi
+
+printf 'engine\t%s\t%s\n' "$ENG" "$ESRC"
+# The exact name from the listing: -d would say yes to Assets for a directory
+# called assets on a case-insensitive disk.
+if [ -z "$(find . -maxdepth 1 -type d -name "$ROOTDIR" 2>/dev/null)" ]; then
+ printf 'root\t%s\tabsent\n' "$ROOTDIR"
+ echo "asset-scan: $ROOTDIR/ does not exist; nothing was scanned" >&2
+ exit 4
+fi
+printf 'root\t%s\tpresent\n' "$ROOTDIR"
+
+# --------------------------------------------------------------------- listing
+ALLF=$(find "$ROOTDIR" -type f 2>/dev/null | sort)
+CLASS=$(printf '%s\n' "$ALLF" | ENG="$ENG" CATF="$CATF" awk '
+ BEGIN { BINMODE = 3; eng = ENVIRON["ENG"]; catf = ENVIRON["CATF"] }
+ length($0) > 0 {
+ p = $0
+ n = split(p, seg, "/")
+ base = seg[n]
+ ext = ""
+ if (match(base, /\.[^.]*$/)) ext = tolower(substr(base, RSTART + 1))
+ # Every file but a .import is something a reference could name.
+ if (eng == "godot" && ext != "import") print "E\t" p
+ reason = ""
+ if (base == ".gitkeep") reason = ".gitkeep"
+ else if (eng == "godot" && ext == "import") reason = ".import"
+ else if (eng == "godot" && ext == "uid") reason = ".uid"
+ else if (eng == "unity" && ext == "meta") reason = ".meta"
+ else if (eng == "unity" && ext == "cs") reason = ".cs"
+ else if (eng == "unity" && ext == "asmdef") reason = ".asmdef"
+ else if (eng == "unreal" && ext != "uasset" && ext != "umap") reason = "not .uasset or .umap"
+ if (reason != "") { print "X\t" reason; next }
+ if (eng == "godot") {
+ # The skill scans five folders of assets/; the rest is counted, not scanned.
+ s = seg[2]
+ if (n < 3 || (s != "art" && s != "audio" && s != "vfx" && s != "shaders" && s != "data")) { print "O\t" p; next }
+ cat = s
+ } else cat = (n >= 3) ? seg[2] : "-"
+ if (catf != "" && tolower(cat) != catf) next
+ print "K\t" p
+ }
+')
+KEPT=$(printf '%s\n' "$CLASS" | awk 'substr($0, 1, 2) == "K\t" { print substr($0, 3) }')
+
+# PNG headers (godot and unity; an unreal asset file has none) and audio
+# descriptions are collected per file; sizes in one batch of wc -c.
+PNGS=""; AUDIOS=""
+if [ "$ENG" != unreal ] && [ -n "$KEPT" ]; then
+ PNGS=$(printf '%s\n' "$KEPT" | awk 'tolower($0) ~ /\.png$/')
+ AUDIOS=$(printf '%s\n' "$KEPT" | awk 'tolower($0) ~ /\.(ogg|wav|mp3|flac|opus|m4a|aac|aif|aiff)$/')
+fi
+HAVEFILE=0
+command -v file >/dev/null 2>&1 && HAVEFILE=1
+
+# The files orphans and missing search: godot only, and only when src/ holds
+# code, as the skill says.
+SRCN=0; CORPUS=""; NCORP=0
+if [ "$ENG" = godot ] && [ -d src ]; then
+ SRCN=$(find src -type f \( -name '*.gd' -o -name '*.cs' -o -name '*.gdshader' \) 2>/dev/null | wc -l | tr -d ' ')
+ if [ "$SRCN" -gt 0 ]; then
+ CORPUS=$(find . -type f \( -name '*.gd' -o -name '*.cs' -o -name '*.gdshader' -o -name '*.gdshaderinc' \
+ -o -name '*.tscn' -o -name '*.tres' -o -name 'project.godot' \) \
+ -not -path './.godot/*' -not -path './.git/*' 2>/dev/null | sed 's|^\./||' | sort)
+ NCORP=$(printf '%s\n' "$CORPUS" | awk 'length($0) > 0' | wc -l | tr -d ' ')
+ fi
+fi
+
+# ------------------------------------------------------------------ measuring
+{
+ printf '%s\n' "$CLASS"
+ if [ -n "$KEPT" ]; then
+ printf '%s\n' "$KEPT" | awk 'length($0) > 0 { printf "./%s\n", $0 }' | tr '\n' '\0' | xargs -0 wc -c 2>/dev/null | \
+ awk 'BEGIN { BINMODE = 3 } { i = index($0, "./"); if (i == 0) next; n = $1 + 0; print "S\t" n "\t" substr($0, i + 2) }'
+ fi
+ if [ -n "$PNGS" ]; then
+ printf '%s\n' "$PNGS" | while IFS= read -r p; do
+ [ -n "$p" ] || continue
+ printf 'P\t%s\t' "$p"
+ od -A n -t u1 -v -N 24 "./$p" 2>/dev/null | tr '\n' ' '
+ printf '\n'
+ done
+ fi
+ if [ -n "$AUDIOS" ]; then
+ printf '%s\n' "$AUDIOS" | awk 'length($0) > 0 { print "L\t" $0 }'
+ if [ "$HAVEFILE" = 1 ]; then
+ printf '%s\n' "$AUDIOS" | awk 'length($0) > 0 { printf "./%s\n", $0 }' | tr '\n' '\0' | xargs -0 file -b 2>/dev/null | \
+ awk 'BEGIN { BINMODE = 3 } { print "D\t" $0 }'
+ fi
+ fi
+ if [ -n "$CORPUS" ]; then
+ printf '%s\n' "$CORPUS" | awk 'length($0) > 0 { print "C\t" $0 }'
+ fi
+} | ENG="$ENG" ROOTDIR="$ROOTDIR" CATF="$CATF" BUDGETS="$BUDGETS" BUDGET_FLAGS="$BUDGET_FLAGS" MAXDIM="$MAXDIM" \
+ RATES="$RATES" NAMERE="$NAMERE" SHOWFILES="$SHOWFILES" SRCN="$SRCN" NCORP="$NCORP" HAVEFILE="$HAVEFILE" awk '
+ BEGIN {
+ BINMODE = 3
+ eng = ENVIRON["ENG"]; rootdir = ENVIRON["ROOTDIR"]; catf = ENVIRON["CATF"]
+ maxdim = ENVIRON["MAXDIM"] + 0; namere = ENVIRON["NAMERE"]; showfiles = ENVIRON["SHOWFILES"]
+ srcn = ENVIRON["SRCN"] + 0; ncorp = ENVIRON["NCORP"] + 0; havefile = ENVIRON["HAVEFILE"]
+ # Budgets arrive one per line as key=bytes. The separator is the newline
+ # itself, which BWK awk splits on anyway.
+ bs = ENVIRON["BUDGETS"]
+ nbl = split(bs, bl, "\n")
+ for (i = 1; i <= nbl; i++) if (bl[i] != "") { p = index(bl[i], "="); B[substr(bl[i], 1, p - 1)] = substr(bl[i], p + 1) + 0; hasb = 1 }
+ nra = 0
+ rs = ENVIRON["RATES"]
+ if (rs != "") { nra = split(rs, ral, ","); for (i = 1; i <= nra; i++) RA[ral[i] + 0] = 1 }
+ # The tagged listing on stdin: K kept file, X left-out kind, O outside the
+ # scanned folders, E existing file (godot), S size, P PNG header bytes,
+ # L audio file, D what file -b said about it (same order as L), C file to
+ # search for references.
+ while ((getline line < "/dev/stdin") > 0) {
+ tag = substr(line, 1, 1); rest = substr(line, 3)
+ if (tag == "K") kept[++nk] = rest
+ else if (tag == "X") xc[rest]++
+ else if (tag == "O") nout++
+ else if (tag == "E") exist[rest] = 1
+ else if (tag == "S") { t = index(rest, "\t"); size[substr(rest, t + 1)] = substr(rest, 1, t - 1) + 0 }
+ else if (tag == "P") { t = index(rest, "\t"); hdr[substr(rest, 1, t - 1)] = substr(rest, t + 1) }
+ else if (tag == "L") lst[++nl] = rest
+ else if (tag == "D") dsc[++nd] = rest
+ else if (tag == "C") corp[++nc] = rest
+ }
+ for (i = 1; i <= nl; i++) if (i <= nd) adesc[lst[i]] = dsc[i]
+ # "./" in front of a name keeps x=1.gd from reading as an awk assignment.
+ for (i = 1; i <= nc; i++) ARGV[ARGC++] = "./" corp[i]
+ }
+
+ # --- references, read from each searched file (the main input) -------------
+ FNR == 1 { curfile = substr(FILENAME, 3) }
+ {
+ t = $0; sub(/\r$/, "", t)
+ while ((i = index(t, "res://")) > 0) {
+ prev = (i > 1) ? substr(t, i - 1, 1) : ""
+ rest = substr(t, i + 6)
+ if (prev == "\"" || prev == "\047") {
+ # Opened by a quote: only the same quote ends it, so a name with a space is whole.
+ e = index(rest, prev)
+ tok = (e > 0) ? substr(rest, 1, e - 1) : rest
+ } else {
+ if (match(rest, "[ \t\"\047(){},;<>]|\\]|\\[")) tok = substr(rest, 1, RSTART - 1); else tok = rest
+ # A sentence full stop or colon after an unquoted path is not part of it.
+ sub(/[.:!?]+$/, "", tok)
+ }
+ t = substr(t, i + 6 + length(tok))
+ if (tok == "" || index(tok, rootdir "/") != 1) continue
+ loc = curfile ":" FNR
+ if (substr(tok, length(tok), 1) == "/") {
+ if (!(tok in dloc)) { dloc[tok] = loc; dkind[tok] = "prefix"; dk[++ndk] = tok }
+ } else if (index(tok, "%") > 0 || index(tok, "*") > 0 || index(tok, "?") > 0) {
+ if (!(tok in dloc)) { dloc[tok] = loc; dkind[tok] = "pattern"; dk[++ndk] = tok }
+ } else {
+ refn[tok]++
+ if (!(tok in rloc)) { rloc[tok] = loc; rk[++nrk] = tok }
+ # A file naming itself does not make itself used.
+ if (tok != curfile) other[tok] = 1
+ }
+ }
+ }
+
+ # --- helpers ---------------------------------------------------------------
+ function ftype(e) {
+ # The types the budgets and the texture checks talk about, by extension.
+ if (e ~ /^(png|jpg|jpeg|webp|tga|bmp|exr|hdr|dds|ktx|ktx2)$/) return "texture"
+ if (e ~ /^(ogg|wav|mp3|flac|opus|m4a|aac|aif|aiff)$/) return "audio"
+ if (e ~ /^(json|yaml|yml)$/) return "data"
+ return "other"
+ }
+ # Powers of two by halving: an odd number above 1 on the way down ends it.
+ function pot(n) {
+ if (n < 1) return 0
+ while (n > 1) { if (n % 2 != 0) return 0; n = n / 2 }
+ return 1
+ }
+ function addcls(k) { if (cseen[k] != cgen) { cseen[k] = cgen; cls = cls (cls == "" ? "" : ",") k } }
+ function clsof(c) {
+ if (c ~ /[A-Z]/) return "uppercase"
+ if (c == " ") return "space"
+ if (c == "-") return "hyphen"
+ if (c == ".") return "dot"
+ return "other"
+ }
+ # The kinds of break in a name: a-z 0-9 and _ in the stem, a-z 0-9 in the
+ # extension (the part after the last dot), in order of first appearance.
+ function namebreaks(b, p, i, stem, ex, c) {
+ cls = ""
+ cgen++
+ p = 0
+ for (i = length(b); i >= 1; i--) if (substr(b, i, 1) == ".") { p = i; break }
+ if (p == 0) { stem = b; ex = "" } else { stem = substr(b, 1, p - 1); ex = substr(b, p + 1) }
+ for (i = 1; i <= length(stem); i++) { c = substr(stem, i, 1); if (c !~ /[a-z0-9_]/) addcls(clsof(c)) }
+ for (i = 1; i <= length(ex); i++) { c = substr(ex, i, 1); if (c !~ /[a-z0-9]/) addcls(clsof(c)) }
+ return cls
+ }
+ # The kHz form (44.1 kHz) is turned into Hz and rounded, so 22.05 is 22050.
+ function rateof(d, r) {
+ if (match(d, /[0-9]+ Hz/)) return substr(d, RSTART, RLENGTH - 3) + 0
+ if (match(d, /[0-9]+(\.[0-9]+)? kHz/)) { r = substr(d, RSTART, RLENGTH - 4) + 0; return int(r * 1000 + 0.5) }
+ return ""
+ }
+
+ END {
+ scanned = nk
+ nodata = (scanned == 0) ? ("no assets under " rootdir) : ""
+ if (catf != "") printf "category_filter\t%s\n", catf
+ printf "scanned\t%d\n", scanned
+ if (eng == "godot") printf "outside_scope\t%d\tfiles under assets/ outside art, audio, vfx, shaders and data\n", nout
+ if (eng == "godot") { nx = split(".import .uid .gitkeep", xl, " ") }
+ else if (eng == "unity") { nx = split(".meta .cs .asmdef .gitkeep", xl, " ") }
+ else { nx = 2; xl[1] = "not .uasset or .umap"; xl[2] = ".gitkeep" }
+ for (i = 1; i <= nx; i++) printf "excluded\t%s\t%d\n", xl[i], xc[xl[i]]
+
+ # --- per-file facts, in path order (the listing arrives sorted) ---
+ for (i = 1; i <= nk; i++) {
+ p = kept[i]
+ n = split(p, seg, "/")
+ base = seg[n]
+ ex = ""
+ if (match(base, /\.[^.]*$/)) ex = tolower(substr(base, RSTART + 1))
+ cat = (eng == "godot" || n >= 3) ? seg[2] : "-"
+ ty = ftype(ex)
+ kcat[i] = cat; ktype[i] = ty
+ catn[cat]++
+ if (!(cat in catseen)) { catseen[cat] = 1; catlist[++ncat] = cat }
+ by = (p in size) ? size[p] : -1
+ kbytes[i] = by
+ if (cat == "art") nart++
+ if (cat == "audio") naud++
+ }
+ if (eng == "godot") {
+ ng = split("art audio vfx shaders data", gl, " ")
+ for (i = 1; i <= ng; i++) printf "category\t%s\t%d\n", gl[i], catn[gl[i]]
+ } else {
+ for (i = 2; i <= ncat; i++) { x = catlist[i]; for (j = i - 1; j >= 1 && catlist[j] > x; j--) catlist[j + 1] = catlist[j]; catlist[j + 1] = x }
+ for (i = 1; i <= ncat; i++) printf "category\t%s\t%d\n", catlist[i], catn[catlist[i]]
+ }
+
+ # --- which checks run ---
+ gdnaming = (eng == "godot" && namere == "")
+ if (nodata != "") { namingst = "not_run"; namingd = nodata }
+ else if (namere != "") { namingst = "ran"; namingd = "name_regex " namere }
+ else if (eng == "godot") { namingst = "ran"; namingd = "lowercase_underscore" }
+ else { namingst = "not_run"; namingd = "no naming rule for " eng "; pass the art bible\047s rule with --name-regex" }
+ unrealwhy = "asset files do not keep their source format, dimensions or sample rate"
+ if (nodata != "") { potst = "not_run"; potd = nodata }
+ else if (eng == "unreal") { potst = "not_run"; potd = unrealwhy }
+ else { potst = "ran"; potd = "PNG width and height from the IHDR bytes" }
+ if (nodata != "") { sizest = "not_run"; sized = nodata }
+ else if (!hasb) { sizest = "not_run"; sized = "no --budget flag given" }
+ else { sizest = "ran"; sized = ENVIRON["BUDGET_FLAGS"] }
+ if (nodata != "") { dimst = "not_run"; dimd = nodata }
+ else if (maxdim == 0) { dimst = "not_run"; dimd = "no --max-dim flag given" }
+ else if (eng == "unreal") { dimst = "not_run"; dimd = unrealwhy }
+ else { dimst = "ran"; dimd = "--max-dim " maxdim }
+ if (nodata != "") { ratest = "not_run"; rated = nodata }
+ else if (eng == "unreal") { ratest = "not_run"; rated = unrealwhy }
+ else if (havefile != 1) { ratest = "not_run"; rated = "file is not installed" }
+ else { ratest = "ran"; rated = (nra > 0) ? ("file -b; allowed " ENVIRON["RATES"]) : "file -b; no --sample-rates flag given, none compared" }
+ if (nodata != "") { orphst = "not_run"; orphd = nodata }
+ else if (eng != "godot") { orphst = "not_run"; orphd = "references live in scenes, prefabs and other assets, not in code" }
+ else if (srcn == 0) { orphst = "not_run"; orphd = "no source files under src/" }
+ else { orphst = "ran"; orphd = ncorp " files searched for res:// paths" }
+ if (eng != "godot") { missst = "not_run"; missd = "no reference syntax is defined for " eng }
+ else if (srcn == 0) { missst = "not_run"; missd = "no source files under src/" }
+ else { missst = "ran"; missd = ncorp " files searched for res:// paths" }
+
+ printf "check\tnaming\t%s\t%s\n", namingst, namingd
+ if (gdnaming) {
+ if (nodata != "") {
+ printf "check\tart_pattern\tnot_run\t%s\ncheck\taudio_pattern\tnot_run\t%s\n", nodata, nodata
+ } else {
+ printf "check\tart_pattern\tnot_checkable\t%d files under assets/art; the category and size values are not defined and the examples disagree\n", nart
+ printf "check\taudio_pattern\tnot_checkable\t%d files under assets/audio; the category values are not defined and the name may hold any number of words\n", naud
+ }
+ }
+ printf "check\tpot\t%s\t%s\n", potst, potd
+ printf "check\tsize\t%s\t%s\n", sizest, sized
+ printf "check\tdim\t%s\t%s\n", dimst, dimd
+ printf "check\trate\t%s\t%s\n", ratest, rated
+ printf "check\torphans\t%s\t%s\n", orphst, orphd
+ printf "check\tmissing\t%s\t%s\n", missst, missd
+ printf "check\tdata\tnot_run\tJSON and YAML validity and schemas are not checked here\n"
+ printf "check\tformat\tnot_run\tfile formats are not checked here: the skill does not say how to tell a UI or 3D texture\n"
+ printf "check\tlast_modified\tnot_run\tnot read: stat differs between GNU and BSD\n"
+
+ # --- the rows, built per kind in path order ---
+ nname = npot = nsize = ndim = nrate = nnot = norph = nmiss = nfile = 0
+ for (i = 1; i <= nk; i++) {
+ p = kept[i]; n = split(p, seg, "/"); base = seg[n]
+ ex = ""
+ if (match(base, /\.[^.]*$/)) ex = tolower(substr(base, RSTART + 1))
+ ty = ktype[i]; by = kbytes[i]
+ dims = "-"; w = -1; h = -1; rate = "-"
+ if (namingst == "ran") {
+ if (namere != "") { if (!(base ~ namere)) rname[++nname] = "NAMING\t" p "\tname_regex\tdoes not match " namere }
+ else { c = namebreaks(base); if (c != "") rname[++nname] = "NAMING\t" p "\tlowercase_underscore\t" c }
+ }
+ if (ty == "texture" && eng != "unreal") {
+ if (ex != "png") rnot[++nnot] = "NOTREAD\t" p "\tdims\tonly PNG headers are read, not " ex
+ else {
+ m = split(hdr[p], hb, " ")
+ if (m < 24) rnot[++nnot] = "NOTREAD\t" p "\tdims\ttoo short to hold a PNG header"
+ else if (hb[1] != 137 || hb[2] != 80 || hb[3] != 78 || hb[4] != 71 || hb[5] != 13 || hb[6] != 10 || hb[7] != 26 || hb[8] != 10) rnot[++nnot] = "NOTREAD\t" p "\tdims\tno PNG signature"
+ else if (hb[13] != 73 || hb[14] != 72 || hb[15] != 68 || hb[16] != 82) rnot[++nnot] = "NOTREAD\t" p "\tdims\tno IHDR chunk after the signature"
+ else {
+ w = hb[17] * 16777216 + hb[18] * 65536 + hb[19] * 256 + hb[20]
+ h = hb[21] * 16777216 + hb[22] * 65536 + hb[23] * 256 + hb[24]
+ dims = w "x" h
+ wp = pot(w); hp = pot(h)
+ if (!wp || !hp) rpot[++npot] = "POT\t" p "\t" dims "\t" ((!wp && !hp) ? "both" : ((!wp) ? "width" : "height"))
+ if (maxdim > 0 && (w > maxdim || h > maxdim)) rdim[++ndim] = "DIM\t" p "\t" dims "\t" maxdim
+ }
+ }
+ }
+ if (ty == "audio" && eng != "unreal") {
+ if (havefile != 1) rnot[++nnot] = "NOTREAD\t" p "\trate\tfile is not installed"
+ else {
+ r = rateof(adesc[p])
+ if (r == "") rnot[++nnot] = "NOTREAD\t" p "\trate\tfile reports no sample rate"
+ else {
+ rate = r
+ if (nra > 0 && !(r in RA)) rrate[++nrate] = "RATE\t" p "\t" r "\t" ENVIRON["RATES"]
+ }
+ }
+ }
+ if (hasb && by >= 0) {
+ key = ""
+ if (("ext:" ex) in B) key = "ext:" ex
+ else if (("type:" ty) in B) key = "type:" ty
+ else if ("all" in B) key = "all"
+ if (key != "" && by > B[key]) rsize[++nsize] = "SIZE\t" p "\t" by "\t" B[key] "\t" (by - B[key]) "\t" key
+ }
+ if (showfiles == 1) rfile[++nfile] = "FILE\t" p "\t" kcat[i] "\t" ty "\t" ((by >= 0) ? by : "-") "\t" dims "\t" rate
+ }
+ # Orphans and missing: one pass over the scanned files and the references.
+ if (orphst == "ran") {
+ for (i = 1; i <= nk; i++) {
+ p = kept[i]
+ if (p in other) continue
+ covered = 0
+ for (j = 1; j <= ndk; j++) if (dkind[dk[j]] == "prefix" && index(p, dk[j]) == 1) { covered = 1; break }
+ if (!covered) rorph[++norph] = "ORPHAN\t" p "\t" ((kbytes[i] >= 0) ? kbytes[i] : "-")
+ }
+ }
+ if (missst == "ran") {
+ # The references in path order, by insertion sort (there are few).
+ for (i = 1; i <= nrk; i++) srt[i] = rk[i]
+ for (i = 2; i <= nrk; i++) { x = srt[i]; for (j = i - 1; j >= 1 && srt[j] > x; j--) srt[j + 1] = srt[j]; srt[j + 1] = x }
+ for (i = 1; i <= nrk; i++) {
+ tk = srt[i]
+ if (tk in exist) continue
+ q = split(tk, tseg, "/")
+ if (catf != "" && tolower(tseg[2]) != catf) continue
+ rmiss[++nmiss] = "MISSING\t" tk "\t" rloc[tk] "\t" refn[tk]
+ }
+ }
+ ndyn = 0
+ if (orphst == "ran" || missst == "ran") {
+ for (i = 1; i <= ndk; i++) dsrt[i] = dk[i]
+ for (i = 2; i <= ndk; i++) { x = dsrt[i]; for (j = i - 1; j >= 1 && dsrt[j] > x; j--) dsrt[j + 1] = dsrt[j]; dsrt[j + 1] = x }
+ for (i = 1; i <= ndk; i++) {
+ tk = dsrt[i]
+ q = split(tk, tseg, "/")
+ if (catf != "" && tolower(tseg[2]) != catf) continue
+ cov = "-"
+ if (dkind[tk] == "prefix") { cov = 0; for (j = 1; j <= nk; j++) if (index(kept[j], tk) == 1) cov++ }
+ rdyn[++ndyn] = "DYNAMIC\t" dkind[tk] "\t" tk "\t" dloc[tk] "\t" cov
+ }
+ }
+
+ # --- hits, then the rows ---
+ printf "hits\tnaming\t%s\n", (namingst == "ran") ? nname : "-"
+ printf "hits\tpot\t%s\n", (potst == "ran") ? npot : "-"
+ printf "hits\tsize\t%s\n", (sizest == "ran") ? nsize : "-"
+ printf "hits\tdim\t%s\n", (dimst == "ran") ? ndim : "-"
+ printf "hits\trate\t%s\n", (ratest == "ran" && nra > 0) ? nrate : "-"
+ printf "hits\tnotread\t%s\n", (potst == "ran" || ratest == "ran") ? nnot : "-"
+ printf "hits\torphan\t%s\n", (orphst == "ran") ? norph : "-"
+ printf "hits\tmissing\t%s\n", (missst == "ran") ? nmiss : "-"
+ for (i = 1; i <= nname; i++) print rname[i]
+ for (i = 1; i <= npot; i++) print rpot[i]
+ for (i = 1; i <= nsize; i++) print rsize[i]
+ for (i = 1; i <= ndim; i++) print rdim[i]
+ for (i = 1; i <= nrate; i++) print rrate[i]
+ for (i = 1; i <= nnot; i++) print rnot[i]
+ for (i = 1; i <= norph; i++) print rorph[i]
+ for (i = 1; i <= nmiss; i++) print rmiss[i]
+ for (i = 1; i <= ndyn; i++) print rdyn[i]
+ for (i = 1; i <= nfile; i++) print rfile[i]
+ }
+'
+exit 0
diff --git a/.claude/scripts/bug-stats.sh b/.claude/scripts/bug-stats.sh
new file mode 100644
index 00000000..fd426e32
--- /dev/null
+++ b/.claude/scripts/bug-stats.sh
@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# bug-stats.sh — bug counts by severity, status and system, with each bug's
+# age, read from the bug files /bug-report writes, so a skill reads one table
+# instead of grepping every BUG file for its Severity and Status lines.
+#
+# Replaces the hand-run bug counts in /release-checklist, /milestone-review,
+# /bug-triage, /team-qa, /day-one-patch, /regression-suite and /team-release,
+# and the session-start note's open-bug count.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# Whether an open S2 fails a gate, which statuses a skill treats as open, and
+# when a bug is "old" stay in the skill: every status is counted as written,
+# so a skill with a different rule can still apply it.
+#
+# Usage: bash .claude/scripts/bug-stats.sh [--root DIR] [--today YYYY-MM-DD] [DIR ...]
+# DIR folders to search for bug files at any depth, relative to the
+# root or absolute; default production/qa/bugs/, one level
+# (where /bug-report writes)
+# --today D the date ages count to (default: today); fixes reruns and tests
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+#
+# A bug file is BUG-<number>.md, the name /bug-report gives it (bug-0003.md,
+# in any case, too): a /bug-triage report (bug-triage-<date>.md) or other
+# notes named bug-*.md are not bugs. A file found twice, through folders that
+# overlap, is read once; an empty one is a bug with no fields, so it is open.
+#
+# What it reads from each file (the header block /bug-report writes):
+# ID, Title, Severity, Priority, Status, Reported and System, as `**Field**:`
+# lines (`- **System**:` too). The FIRST Status line is the bug's status: a
+# Fix Record or Closure Record further down adds its own Status line, and the
+# header is the one /bug-report and /hotfix keep current.
+# Severity is the first S1-S4 in its value, whatever the spelling (S1-Critical,
+# S1 — Critical, S1 (Critical)); priority the first P1-P4. A value still in
+# the template's [brackets] is no severity (open_unrated).
+#
+# Output: TSV. Counts first:
+# bugs <n> <scope>
+# open <n> <rule> open = a status other than Closed or Verified Fixed
+# (/release-checklist's and /team-qa's rule; a bug
+# with no Status line is open)
+# closed <n>
+# open_s1 .. open_s4 <n>, open_unrated <n> (open, with no S1-S4)
+# status <value as written> <n> one row per status value, sorted
+# system <system> <open> <open S1/S2> open bugs per system, most first
+# oldest_open <id> <days> the open bug reported longest ago
+# BUG <id> <path> <severity> <priority> <state> <status> <reported> <age_days> <system> <title>
+# `-` means not there; state is OPEN or CLOSED; age_days is whole days from
+# Reported (the first YYYY-MM-DD in it) to --today.
+#
+# Exit codes: 0 read every bug file found (none is fine: bugs 0); 1 the root
+# cannot be read; 2 usage error (a bad --today, an unknown flag). Reads only;
+# never writes, never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk, sort and tolower.
+LC_ALL=C
+export LC_ALL
+
+ROOT_ARG=""; TODAY=""; DIRS=""
+NL='
+'
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --today)
+ [ $# -ge 2 ] || { echo "bug-stats: --today needs a date" >&2; exit 2; }
+ TODAY="$2"; shift 2 ;;
+ --today=*) TODAY="${1#--today=}"; shift ;;
+ --root)
+ [ $# -ge 2 ] || { echo "bug-stats: --root needs a value" >&2; exit 2; }
+ ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) echo "bug-stats: unknown argument: $1 (try --help)" >&2; exit 2 ;;
+ *) DIRS="$DIRS$1$NL"; shift ;;
+ esac
+done
+[ -n "$TODAY" ] || TODAY=$(date +%Y-%m-%d)
+case "$TODAY" in
+ [0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]) ;;
+ *) echo "bug-stats: --today must be YYYY-MM-DD, got $TODAY" >&2; exit 2 ;;
+esac
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "bug-stats: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$(dirname "$0")/../.." 2>/dev/null || { echo "bug-stats: cannot reach the repo root" >&2; exit 1; }
+fi
+
+# BUG-<number>.md: -iname keeps a lowercase bug-0003.md, the digit keeps out
+# bug-triage-<date>.md.
+if [ -z "$DIRS" ]; then
+ SCOPE="production/qa/bugs/BUG-*.md"
+ LIST=$(find production/qa/bugs -maxdepth 1 -type f -iname 'bug-[0-9]*.md' 2>/dev/null | sort)
+else
+ SCOPE=$(printf '%s' "$DIRS" | awk 'NF' | tr '\n' ',' | sed 's/,$//')
+ LIST=""
+ while IFS= read -r d; do
+ [ -n "$d" ] || continue
+ # A Windows path's backslashes as slashes, so its file names read alike.
+ case "$d" in [A-Za-z]:\\*) d=$(printf '%s' "$d" | sed 's|\\|/|g') ;; esac
+ LIST="$LIST$(find "${d%/}" -type f -iname 'bug-[0-9]*.md' 2>/dev/null)$NL"
+ done <<EOF
+$DIRS
+EOF
+ # ./ dropped before the de-duplication, so ./production and production
+ # name each file once.
+ LIST=$(printf '%s' "$LIST" | awk 'NF { sub(/^\.\//, ""); print }' | sort -u)
+fi
+
+# The file list goes to awk on stdin, never as arguments: thousands of paths
+# would pass the command-line limit of some systems. Each becomes an input
+# file, "./" in front of a relative one so a name like x=1.md is not read as an
+# assignment; an absolute one (/..., C:/...) is opened as it is.
+printf '%s\n' "$LIST" | awk 'NF { sub(/^\.\//, ""); print }' | \
+TODAY="$TODAY" SCOPE="$SCOPE" awk '
+ BEGIN {
+ BINMODE = 3; split(ENVIRON["TODAY"], t, "-"); today = days(t[1] + 0, t[2] + 0, t[3] + 0)
+ # The list arrives on /dev/stdin, named, so the main input stays the files: with
+ # a bare getline, gawk read the first file as more of stdin and skipped its FNR 1.
+ while ((getline f < "/dev/stdin") > 0) lst[++nlst] = f
+ for (i = 1; i <= nlst; i++) ARGV[ARGC++] = (lst[i] ~ /^(\/|[A-Za-z]:)/) ? lst[i] : "./" lst[i]
+ na = 1
+ }
+ # Days since a fixed origin for the Gregorian date y-m-d. Only differences
+ # are used, so the origin does not matter. The year is counted from March,
+ # so a leap day falls at the end of it and the month term needs no table.
+ function days(y, m, d) {
+ if (m <= 2) { y--; m += 12 }
+ return 365 * y + int(y / 4) - int(y / 100) + int(y / 400) + int((153 * (m - 3) + 2) / 5) + d
+ }
+ function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
+ function clean(s) { gsub(/\t/, " ", s); s = trim(s); return (s == "") ? "-" : s }
+ # The value of field `name` on line s (`**Name**:`, `- **Name**:`, `Name:`),
+ # or "\001" when s is not that field. The same normalisation as story-status.sh.
+ function fval(s, name, u) {
+ u = s; sub(/^[ \t]+/, "", u); sub(/^> /, "", u); sub(/^- /, "", u); gsub(/\*/, "", u)
+ if (tolower(substr(u, 1, length(name) + 1)) != tolower(name) ":") return "\001"
+ return trim(substr(u, length(name) + 2))
+ }
+ function flush( sev, pri, closed, age, d, s, k) {
+ if (path == "") return
+ # A value still in the template [brackets] lists every level, so it has none.
+ sev = (substr(sevv, 1, 1) != "[" && match(sevv, /[Ss][1-4]/)) ? toupper(substr(sevv, RSTART, RLENGTH)) : "-"
+ pri = (substr(priv, 1, 1) != "[" && match(priv, /[Pp][1-4]/)) ? toupper(substr(priv, RSTART, RLENGTH)) : "-"
+ s = tolower(statv)
+ closed = (s ~ /^closed([^a-z]|$)/ || s ~ /^verified fixed([^a-z]|$)/)
+ age = "-"; d = "-"
+ if (match(repv, /[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/)) {
+ d = substr(repv, RSTART, RLENGTH); split(d, p, "-"); age = today - days(p[1] + 0, p[2] + 0, p[3] + 0)
+ }
+ n++; k = (statv == "") ? "-" : clean(statv); stat[k]++
+ if (closed) nclosed++
+ else {
+ nopen++; if (sev == "-") unrated++; else opensev[sev]++
+ sy = clean(sysv); sys_open[sy]++; if (sev == "S1" || sev == "S2") sys_hi[sy]++
+ if (age != "-" && (oldest == "" || age > oldest_age)) { oldest = idv; oldest_age = age }
+ }
+ rows[n] = "BUG\t" idv "\t" path "\t" sev "\t" pri "\t" (closed ? "CLOSED" : "OPEN") "\t" k "\t" d "\t" age "\t" clean(sysv) "\t" clean(titlev)
+ path = ""
+ }
+ function begin(f) {
+ flush(); path = f; sub(/^\.\//, "", path); infence = 0
+ idv = path; sub(/^.*\//, "", idv); sub(/\.md$/, "", idv)
+ seen_id = seen_sev = seen_pri = seen_stat = seen_rep = seen_sys = seen_title = 0
+ sevv = priv = statv = repv = sysv = titlev = ""
+ }
+ # An empty file has no line, so no FNR 1: every listed file awk passed over
+ # before f (all of them, for f "") is one, and is still a bug.
+ function reach(f) {
+ while (na < ARGC && ARGV[na] != f) { begin(ARGV[na]); flush(); na++ }
+ if (na < ARGC) na++
+ }
+ FNR == 1 { reach(FILENAME); begin(FILENAME) }
+ {
+ line = $0; sub(/\r$/, "", line)
+ if (line ~ /^[ \t]*(```|~~~)/) { infence = !infence; next }
+ if (infence) next
+ if (!seen_id && (v = fval(line, "ID")) != "\001") { seen_id = 1; if (v ~ /^[A-Za-z]+-[0-9]+/) { match(v, /^[A-Za-z]+-[0-9]+/); idv = toupper(substr(v, 1, RLENGTH)) } }
+ if (!seen_title && (v = fval(line, "Title")) != "\001") { seen_title = 1; titlev = v }
+ if (!seen_sev && (v = fval(line, "Severity")) != "\001") { seen_sev = 1; sevv = v }
+ if (!seen_pri && (v = fval(line, "Priority")) != "\001") { seen_pri = 1; priv = v }
+ if (!seen_stat && (v = fval(line, "Status")) != "\001") { seen_stat = 1; statv = v }
+ if (!seen_rep && (v = fval(line, "Reported")) != "\001") { seen_rep = 1; repv = v }
+ if (!seen_sys && (v = fval(line, "System")) != "\001") { seen_sys = 1; sysv = v }
+ }
+ END {
+ flush(); reach("")
+ printf "bugs\t%d\t%s\n", n, ENVIRON["SCOPE"]
+ printf "open\t%d\tstatus other than Closed or Verified Fixed\n", nopen
+ printf "closed\t%d\n", nclosed
+ for (i = 1; i <= 4; i++) printf "open_s%d\t%d\n", i, opensev["S" i] + 0
+ printf "open_unrated\t%d\n", unrated
+ # Status rows sorted by value; system rows by open count, then name.
+ ns = 0; for (k in stat) keys[++ns] = k
+ for (i = 2; i <= ns; i++) { v = keys[i]; for (j = i - 1; j >= 1 && keys[j] > v; j--) keys[j + 1] = keys[j]; keys[j + 1] = v }
+ for (i = 1; i <= ns; i++) printf "status\t%s\t%d\n", keys[i], stat[keys[i]]
+ nn = 0; for (k in sys_open) sk[++nn] = k
+ for (i = 2; i <= nn; i++) {
+ v = sk[i]
+ for (j = i - 1; j >= 1 && (sys_open[sk[j]] < sys_open[v] || (sys_open[sk[j]] == sys_open[v] && sk[j] > v)); j--) sk[j + 1] = sk[j]
+ sk[j + 1] = v
+ }
+ for (i = 1; i <= nn; i++) printf "system\t%s\t%d\t%d\n", sk[i], sys_open[sk[i]], sys_hi[sk[i]] + 0
+ if (oldest != "") printf "oldest_open\t%s\t%d\n", oldest, oldest_age
+ else printf "oldest_open\t-\t-\n"
+ for (i = 1; i <= n; i++) print rows[i]
+ }
+'
diff --git a/.claude/scripts/code-markers.sh b/.claude/scripts/code-markers.sh
new file mode 100644
index 00000000..0a8ed9d0
--- /dev/null
+++ b/.claude/scripts/code-markers.sh
@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+# code-markers.sh — TODO, FIXME and HACK markers, debug output calls,
+# placeholder names and long files in the game's source, with how many files
+# were scanned, so a checklist reads counts with their denominator instead of
+# grepping by hand.
+#
+# Replaces the scans a release or launch checklist, a tech-debt pass or a
+# milestone review would otherwise run by hand, so they all read the same
+# counts.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# Whether a FIXME blocks a release is the checklist's rule. A scan that found
+# nothing because there was nothing to scan says so: scanned_files 0, and exit
+# 3 when the code root itself is unknown.
+#
+# Usage: bash .claude/scripts/code-markers.sh [--root DIR] [--long N] [--exclude PATTERN ...] [PATH ...]
+# PATH folders or files to scan, relative to the root or absolute;
+# default: the code root project-state.sh resolves (src/,
+# Assets/ or Source/)
+# --exclude P skip paths matching the shell pattern P (relative to the
+# root, * matching across folders), e.g. 'Assets/Plugins/*'
+# --long N a file of more than N lines is long (default 500, /tech-debt's)
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+#
+# What counts:
+# source files .gd .cs .cpp .cc .c .h .hpp .rs .py .js .ts .lua .java .kt:
+# every extension the hooks and helpers already treat as code
+# (session-start, statusline, project-state, detect-gaps,
+# validate-commit), scene and resource files left out
+# markers TODO, FIXME and HACK as whole words in capitals, anywhere in
+# the line (a marker is a marker in a comment or a string)
+# debug calls by language: GDScript print, prints, printt, printraw,
+# print_rich, print_debug; C# Debug.Log* and print; C and C++
+# UE_LOG, AddOnScreenDebugMessage, printf; JavaScript and
+# TypeScript console.log, console.debug, debugger; Python and
+# Lua print; Rust println!, eprintln!, dbg!; Java and Kotlin
+# System.out.print* and println
+# placeholders placeholder, temp_ or wip_ in any case (/launch-checklist's)
+# long files more than --long lines. Function length is not measured: no
+# skill defines how, per language.
+#
+# Output: TSV. Counts first:
+# scanned_files <n> <paths>, scanned_lines <n>, todo, fixme, hack, debug,
+# placeholder <n>, long_files <n> <rule>
+# MARK <TODO|FIXME|HACK> <path> <line>
+# DEBUG <call> <path> <line>
+# PLACEHOLDER <word> <path> <line>
+# LONG <path> <lines>
+#
+# Exit codes: 0 scanned (whatever it found, none included); 1 the root cannot
+# be read; 2 usage error; 3 no PATH given and the code root is unset (prints
+# scanned_files 0 code_root unset). Reads only; never writes, never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk, sort and tolower.
+LC_ALL=C
+export LC_ALL
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ROOT_ARG=""; LONG=500; PATHS=""; EXCL=""
+NL='
+'
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root) [ $# -ge 2 ] || { echo "code-markers: --root needs a value" >&2; exit 2; }; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --long) [ $# -ge 2 ] || { echo "code-markers: --long needs a number" >&2; exit 2; }; LONG="$2"; shift 2 ;;
+ --exclude) [ $# -ge 2 ] || { echo "code-markers: --exclude needs a pattern" >&2; exit 2; }; EXCL="$EXCL$2$NL"; shift 2 ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) echo "code-markers: unknown argument: $1 (try --help)" >&2; exit 2 ;;
+ *) PATHS="$PATHS${1%/}$NL"; shift ;;
+ esac
+done
+case "$LONG" in ''|*[!0-9]*) echo "code-markers: --long takes a whole number" >&2; exit 2 ;; esac
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "code-markers: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "code-markers: cannot reach the repo root" >&2; exit 1; }
+fi
+
+if [ -z "$PATHS" ]; then
+ [ -f "$HERE/project-state.sh" ] || { echo "code-markers: $HERE/project-state.sh is missing; pass a PATH" >&2; exit 1; }
+ CR=$(bash "$HERE/project-state.sh" --root . | awk -F'\t' '$1 == "code_root" { print $2 }')
+ if [ -z "$CR" ] || [ "$CR" = "-" ]; then
+ printf 'scanned_files\t0\tcode_root unset\n'
+ echo "code-markers: the code root is unset (no engine set and no single src/, Assets/ or Source/); pass a PATH" >&2
+ exit 3
+ fi
+ PATHS="$CR$NL"
+fi
+
+LIST=""
+while IFS= read -r p; do
+ [ -n "$p" ] || continue
+ # A Windows path's backslashes as slashes, so its file names read alike.
+ case "$p" in [A-Za-z]:\\*) p=$(printf '%s' "$p" | sed 's|\\|/|g') ;; esac
+ LIST="$LIST$(find "$p" -type f \( -name '*.gd' -o -name '*.cs' -o -name '*.cpp' -o -name '*.cc' -o -name '*.c' \
+ -o -name '*.h' -o -name '*.hpp' -o -name '*.rs' -o -name '*.py' -o -name '*.js' -o -name '*.ts' \
+ -o -name '*.lua' -o -name '*.java' -o -name '*.kt' \) 2>/dev/null)$NL"
+done <<EOF
+$PATHS
+EOF
+
+SCOPE=$(printf '%s' "$PATHS" | awk 'NF' | tr '\n' ',' | sed 's/,$//')
+# The file list goes to awk on stdin, never as arguments: a large project
+# would pass thousands of paths, past the command-line limit of some systems.
+printf '%s' "$LIST" | awk 'NF { sub(/^\.\//, ""); print }' | sort -u | \
+LONG="$LONG" SCOPE="$SCOPE" EXCL="$EXCL" awk '
+ # A shell pattern as an anchored regex; * and ? match across folders too.
+ function pat2re(g, i, c, out) {
+ out = "^"
+ for (i = 1; i <= length(g); i++) {
+ c = substr(g, i, 1)
+ if (c == "*") out = out ".*"
+ else if (c == "?") out = out "."
+ else if (index("\\.+()^$|{}", c) > 0) out = out "\\" c
+ else out = out c
+ }
+ return out "$"
+ }
+ BEGIN {
+ long = ENVIRON["LONG"] + 0
+ nx = split(ENVIRON["EXCL"], xs, "\n")
+ # Each listed file becomes an awk input file, unless an --exclude matches it.
+ # "./" in front of a relative one keeps a name like x=1.gd from reading as
+ # an awk assignment; an absolute one (/..., C:/...) is opened as it is.
+ # The file count comes from the list: an empty file has no line for awk to
+ # see, and it was still scanned.
+ # The list arrives on /dev/stdin, named, so the main input stays the files: with
+ # a bare getline, gawk read the first file as more of stdin and skipped its FNR 1.
+ while ((getline f < "/dev/stdin") > 0) lst[++nlst] = f
+ for (j = 1; j <= nlst; j++) {
+ skip = 0
+ for (i = 1; i <= nx; i++) if (xs[i] != "" && lst[j] ~ pat2re(xs[i])) skip = 1
+ if (!skip) { ARGV[ARGC++] = (lst[j] ~ /^(\/|[A-Za-z]:)/) ? lst[j] : "./" lst[j]; nfiles++ }
+ }
+ }
+ function ext(p, e) { e = p; sub(/^.*\./, "", e); return tolower(e) }
+ # The first debug call on the line for the file type, or "".
+ function debug_call(s, e) {
+ if (e == "gd") return m(s, "(^|[^A-Za-z0-9_.])(print_rich|print_debug|printraw|printt|prints|print)\\(")
+ if (e == "cs") { if (match(s, /Debug\.Log[A-Za-z]*\(/)) return substr(s, RSTART, RLENGTH - 1); return m(s, "(^|[^A-Za-z0-9_.])print\\(") }
+ if (e ~ /^(c|cc|cpp|h|hpp)$/) { if (match(s, /UE_LOG\(|AddOnScreenDebugMessage\(/)) return substr(s, RSTART, RLENGTH - 1); return m(s, "(^|[^A-Za-z0-9_.])printf\\(") }
+ if (e == "js" || e == "ts") { if (match(s, /console\.(log|debug)\(/)) return substr(s, RSTART, RLENGTH - 1); return m(s, "(^|[^A-Za-z0-9_])debugger([^A-Za-z0-9_]|$)") }
+ if (e == "py" || e == "lua") return m(s, "(^|[^A-Za-z0-9_.])print\\(")
+ if (e == "rs") { if (match(s, /(eprintln|println|dbg)!\(/)) return substr(s, RSTART, RLENGTH - 1); return "" }
+ if (e == "java" || e == "kt") { if (match(s, /System\.out\.print[a-z]*\(/)) return substr(s, RSTART, RLENGTH - 1); return m(s, "(^|[^A-Za-z0-9_.])println\\(") }
+ return ""
+ }
+ # The name in a match of re, without the boundary character or the "(".
+ function m(s, re, t) {
+ if (!match(s, re)) return ""
+ t = substr(s, RSTART, RLENGTH); sub(/^[^A-Za-z_]/, "", t); sub(/[^A-Za-z_!]$/, "", t); sub(/\($/, "", t); return t
+ }
+ function flush() {
+ if (path == "") return
+ lines += FNRlast
+ if (FNRlast > long) { nlong++; rows[++nr] = "LONG\t" path "\t" FNRlast }
+ path = ""
+ }
+ FNR == 1 { flush(); path = FILENAME; sub(/^\.\//, "", path); e = ext(path) }
+ {
+ FNRlast = FNR
+ s = $0; sub(/\r$/, "", s)
+ # Markers: whole words in capitals; every one on the line counts.
+ t = " " s " "
+ while (match(t, /[^A-Za-z0-9_](TODO|FIXME|HACK)[^A-Za-z0-9_]/)) {
+ w = substr(t, RSTART + 1, RLENGTH - 2); cnt[w]++
+ rows[++nr] = "MARK\t" w "\t" path "\t" FNR
+ t = substr(t, RSTART + RLENGTH - 1)
+ }
+ if ((c = debug_call(s, e)) != "") { ndebug++; rows[++nr] = "DEBUG\t" c "\t" path "\t" FNR }
+ if (match(tolower(s), /placeholder|temp_|wip_/)) { nph++; rows[++nr] = "PLACEHOLDER\t" substr(tolower(s), RSTART, RLENGTH) "\t" path "\t" FNR }
+ }
+ END {
+ flush()
+ printf "scanned_files\t%d\t%s\nscanned_lines\t%d\n", nfiles, ENVIRON["SCOPE"], lines
+ printf "todo\t%d\nfixme\t%d\nhack\t%d\ndebug\t%d\nplaceholder\t%d\n", cnt["TODO"], cnt["FIXME"], cnt["HACK"], ndebug, nph
+ printf "long_files\t%d\tmore than %d lines\n", nlong, long
+ for (i = 1; i <= nr; i++) print rows[i]
+ }
+'
+exit 0
diff --git a/.claude/scripts/compat-inventory.sh b/.claude/scripts/compat-inventory.sh
new file mode 100644
index 00000000..3343eb13
--- /dev/null
+++ b/.claude/scripts/compat-inventory.sh
@@ -0,0 +1,530 @@
+#!/usr/bin/env bash
+# compat-inventory.sh — every place the framework depends on something only
+# Claude Code provides, listed per file with the feature it belongs to.
+#
+# A skill, agent, hook or setting can lean on a Claude Code mechanism without
+# saying so: a question tool named in a body, a `!` line, a `${CLAUDE_...}`
+# substitution, a frontmatter key, a hook payload field, an `@` import. Read one
+# file at a time, these are easy to miss. This script finds each one and prints
+# where it is, so a change to any of them can be seen and planned for.
+#
+# OBSERVATIONS, NEVER VERDICTS (CLAUDE.md, "Helpers emit observations"). A
+# construct found here is not a defect: Claude Code runs every one of them. It
+# prints what it found, with denominators first, and always exits 0 once it has
+# run. Whether a construct should stay, move to frontmatter or be reworded is the
+# reader's call.
+#
+# Usage: bash .claude/scripts/compat-inventory.sh [--skill <name> | --agent <name>] [project-root]
+# --skill <name> one skill's files only (SKILL.md and everything in its folder)
+# --agent <name> one agent file only
+# project-root defaults to the repo root (the test suite passes fixtures)
+#
+# Files read, in groups:
+# skills .claude/skills/<name>/**/*.md
+# agents .claude/agents/*.md
+# instructions CLAUDE.md, CLAUDE.local.md, .claude/CLAUDE.md, <top-level folder>/CLAUDE.md,
+# .claude/rules/*.md
+# docs .claude/docs/**/*.md
+# hooks .claude/hooks/*.sh and .claude/statusline.sh
+# settings .claude/settings.json (settings.local.json is personal and not read)
+#
+# Output:
+# ROOT: <path>
+# FILES: skills=<n> skill_files=<n> agents=<n> instructions=<n> docs=<n> hooks=<n> settings=<n>
+# FOUND_LINES: <n> in <n> of <n> files read
+# COUNT: <feature> <construct> files=<n> hits=<n> every catalogued construct, zero included;
+# a family with nothing found prints <family>:*
+# FOUND: <feature> <construct> <file>:<line> one line per construct per source line
+#
+# Features and their constructs:
+# questions AskUserQuestion
+# subagents Agent-tool (`Agent`, "Agent tool", Agent in a tools list), Task-tool (the
+# old name, on a line about agents), subagent_type, agent-type-list (Agent(...)
+# in an agent's tools), cc-path:.claude/agents, cc-path:.claude/agent-memory
+# skill-loading var:CLAUDE_SKILL_DIR and the other skill substitutions, skillOverrides,
+# cc-path:.claude/skills, cc-path:.claude/commands
+# shell-lines shell-line (!`cmd` or a ```! block), shared-path:.claude/scripts
+# arguments $ARGUMENTS, $N (skills only: the text Claude Code substitutes them in)
+# frontmatter fm:<key> (a skill key beyond name, description, license, compatibility and
+# metadata; an agent key beyond name and description), tools-string (an
+# agent's tools written as one comma string)
+# instructions CLAUDE.md (each instruction file), @import (outside code), rule-file,
+# rule-paths, cc-path:.claude/rules, cc-path:.claude/CLAUDE.md,
+# shared-path:.claude/docs and other framework folders under .claude/
+# hooks hook:<Event>[<matcher>] (a registration in settings), hook-payload:<field>
+# and hook-answer:<token> (in hook scripts), var:CLAUDE_PROJECT_DIR,
+# shared-path:.claude/hooks
+# settings permission:<allow|deny|ask|...> (one per rule), settings:<key>,
+# statusline-payload:<field>, cc-path:.claude/settings*.json, other var:CLAUDE_*
+# tools TodoWrite, task-tools (TaskCreate, TaskGet, TaskList, TaskUpdate, ...)
+#
+# cc-path is a folder or file Claude Code itself reads; shared-path is one of the
+# framework's own folders that happens to live under .claude/. Paths are reported
+# where a skill, agent, instruction file, doc or the settings name them, not
+# inside hook scripts.
+
+set -u
+
+SKILL_FILTER=""
+AGENT_FILTER=""
+ROOT_ARG=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --skill|--agent)
+ [ $# -ge 2 ] || { echo "compat-inventory: $1 needs a value" >&2; exit 2; }
+ if [ "$1" = "--skill" ]; then SKILL_FILTER="$2"; else AGENT_FILTER="$2"; fi
+ shift 2 ;;
+ --skill=*) SKILL_FILTER="${1#--skill=}"; shift ;;
+ --agent=*) AGENT_FILTER="${1#--agent=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0"; exit 0 ;;
+ *) ROOT_ARG="$1"; shift ;;
+ esac
+done
+
+if [ -n "$SKILL_FILTER" ] && [ -n "$AGENT_FILTER" ]; then
+ echo "compat-inventory: give --skill or --agent, not both" >&2
+ exit 2
+fi
+
+if [ -n "$ROOT_ARG" ]; then
+ ROOT="$ROOT_ARG"
+else
+ cd "$(dirname "$0")/../.." || { echo "compat-inventory: cannot reach repo root" >&2; exit 1; }
+ # `pwd -W` (Git Bash) gives C:/... so the Windows Python below can open it.
+ ROOT="$(pwd -W 2>/dev/null || pwd)"
+fi
+
+if [ ! -d "$ROOT/.claude" ]; then
+ echo "compat-inventory: no .claude folder under $ROOT" >&2
+ exit 1
+fi
+
+# Python fallback chain: python -> python3 -> py (matches yaml-helper.sh).
+PYBIN=""
+for candidate in python python3 py; do
+ if command -v "$candidate" >/dev/null 2>&1; then
+ if "$candidate" -c 'import sys; sys.exit(0 if sys.version_info[0] == 3 else 1)' >/dev/null 2>&1; then
+ PYBIN="$candidate"; break
+ fi
+ fi
+done
+if [ -z "$PYBIN" ]; then
+ echo "compat-inventory: no python 3 interpreter found (tried python, python3, py)" >&2
+ exit 1
+fi
+
+"$PYBIN" - "$ROOT" "$SKILL_FILTER" "$AGENT_FILTER" <<'PYEOF'
+import json
+import os
+import re
+import sys
+
+root, skill_filter, agent_filter = sys.argv[1:4]
+
+try:
+ sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except (AttributeError, ValueError):
+ pass
+
+# Constructs that always print a COUNT line, zero included.
+STATIC = [
+ ("questions", "AskUserQuestion"),
+ ("subagents", "Agent-tool"), ("subagents", "Task-tool"), ("subagents", "subagent_type"),
+ ("subagents", "agent-type-list"),
+ ("subagents", "cc-path:.claude/agents"), ("subagents", "cc-path:.claude/agent-memory"),
+ ("skill-loading", "var:CLAUDE_SKILL_DIR"), ("skill-loading", "var:CLAUDE_SESSION_ID"),
+ ("skill-loading", "var:CLAUDE_PLUGIN_ROOT"), ("skill-loading", "var:CLAUDE_PLUGIN_DATA"),
+ ("skill-loading", "skillOverrides"),
+ ("skill-loading", "cc-path:.claude/skills"), ("skill-loading", "cc-path:.claude/commands"),
+ ("shell-lines", "shell-line"),
+ ("arguments", "$ARGUMENTS"), ("arguments", "$N"),
+ ("frontmatter", "tools-string"),
+ ("instructions", "CLAUDE.md"), ("instructions", "@import"),
+ ("instructions", "rule-file"), ("instructions", "rule-paths"),
+ ("instructions", "cc-path:.claude/rules"), ("instructions", "cc-path:.claude/CLAUDE.md"),
+ ("hooks", "var:CLAUDE_PROJECT_DIR"),
+ ("settings", "cc-path:.claude/settings.json"), ("settings", "cc-path:.claude/settings.local.json"),
+ ("settings", "cc-path:.claude/output-styles"),
+ ("tools", "TodoWrite"), ("tools", "task-tools"),
+]
+# Families whose members are named by what was found; "<family>:*" prints when none was.
+DYNAMIC = [("hooks", "hook"), ("hooks", "hook-payload"), ("hooks", "hook-answer"),
+ ("frontmatter", "fm"), ("settings", "permission"), ("settings", "settings"),
+ ("settings", "statusline-payload"), ("instructions", "shared-path"), ("settings", "var")]
+STATIC_FEATURE = dict((c, f) for f, c in STATIC)
+
+# Under .claude/: what Claude Code itself reads, and the feature each belongs to.
+CC_PATHS = {"skills": "skill-loading", "commands": "skill-loading", "agents": "subagents",
+ "agent-memory": "subagents", "rules": "instructions", "CLAUDE.md": "instructions",
+ "settings.json": "settings", "settings.local.json": "settings", "output-styles": "settings"}
+# The framework's own folders under .claude/ (anything else defaults to instructions).
+SHARED_FEATURE = {"hooks": "hooks", "scripts": "shell-lines", "statusline.sh": "settings"}
+SKILL_VARS = {"CLAUDE_SKILL_DIR", "CLAUDE_SESSION_ID", "CLAUDE_PLUGIN_ROOT", "CLAUDE_PLUGIN_DATA"}
+SKILL_PORTABLE = {"name", "description", "license", "compatibility", "metadata"}
+AGENT_PORTABLE = {"name", "description"}
+
+RX = {
+ "AskUserQuestion": re.compile(r"\bAskUserQuestion\b"),
+ "Agent-tool": re.compile(r"`Agent`|\bAgent tool\b"),
+ "subagent_type": re.compile(r"\bsubagent_type\b"),
+ "TodoWrite": re.compile(r"\bTodoWrite\b"),
+ "task-tools": re.compile(r"\bTask(?:Create|Get|List|Update|Output|Stop)\b"),
+ "shell-line": re.compile(r"(?:^|\s)!`[^`]+`|^\s*```!"),
+ "skillOverrides": re.compile(r"\bskillOverrides\b"),
+ "$ARGUMENTS": re.compile(r"\$ARGUMENTS\b"),
+ "$N": re.compile(r"(?<![\w$\\])\$\d\b"),
+}
+# `Task` is also a C# type: count it only on a line about agents.
+TASK_TOOL = re.compile(r"\bTask tool\b|\bTask\(\s*(?:subagent_type|description|prompt)\b")
+TASK_TICKED = re.compile(r"`Task`")
+TASK_CONTEXT = re.compile(r"(?i)\bsub-?agents?\b|\bagents?\b|\balias\b|\bsubagent_type\b")
+VAR = re.compile(r"\$\{?(CLAUDE_[A-Z][A-Z0-9_]*)\}?")
+PATH = re.compile(r"\.claude/([A-Za-z0-9_.-]+)")
+IMPORT = re.compile(r"(?:^|(?<=\s))@([~\w.-]*/[\w./-]+|[\w-]+\.[A-Za-z]{1,5})\b")
+CODE_SPAN = re.compile(r"`[^`]*`")
+HOOK_PAYLOAD = re.compile(
+ r"\b(tool_input|tool_name|tool_response|hook_event_name|session_id|transcript_path|agent_id"
+ r"|agent_type|agent_transcript_path|stop_hook_active|last_assistant_message|permission_mode"
+ r"|notification_type|custom_instructions)\b")
+HOOK_ANSWER = re.compile(
+ r"\b(hookSpecificOutput|permissionDecision(?:Reason)?|additionalContext|systemMessage"
+ r"|suppressOutput|stopReason)\b|\b(exit 2)\b|(\"decision\")")
+STATUS_PAYLOAD = re.compile(r"\.(model|workspace|context_window|cost|output_style)\.([a-z_]+)")
+
+
+def read_lines(path):
+ with open(path, encoding="utf-8", errors="replace") as fh:
+ return fh.read().splitlines()
+
+
+def rel(path):
+ return os.path.relpath(path, root).replace(os.sep, "/")
+
+
+def md_files(folder):
+ out = []
+ for dirpath, dirs, files in os.walk(folder):
+ dirs.sort()
+ out += [os.path.join(dirpath, f) for f in sorted(files) if f.endswith(".md")]
+ return out
+
+
+found = set() # (feature, construct, file, line)
+
+
+def add(feature, construct, path, line):
+ found.add((feature, construct.replace(" ", "_"), rel(path), line))
+
+
+def frontmatter_lines(lines):
+ """[(line number, key, value)] for the leading --- block; [] when there is none."""
+ if not lines or lines[0].strip() != "---":
+ return []
+ out = []
+ for n in range(1, len(lines)):
+ if lines[n].strip() == "---":
+ return out
+ m = re.match(r"^([A-Za-z][\w-]*):(.*)$", lines[n])
+ if m:
+ out.append((n + 1, m.group(1), m.group(2).strip()))
+ return [] # never closed: not frontmatter
+
+
+def list_entries(value):
+ v = value.strip().strip("\"'")
+ if v.startswith("[") and v.endswith("]"):
+ v = v[1:-1]
+ out, depth, cur = [], 0, ""
+ for ch in v:
+ depth += ch == "("
+ depth -= ch == ")"
+ if ch == "," and depth == 0:
+ out.append(cur.strip().strip("\"'"))
+ cur = ""
+ else:
+ cur += ch
+ if cur.strip():
+ out.append(cur.strip().strip("\"'"))
+ return [e for e in out if e]
+
+
+def imports_in(lines):
+ """[(line number, target)] for each @path import. Claude Code skips code fences and code
+ spans, and strips block HTML comments before it reads the file, so an @path in any of
+ them is text about imports, not one."""
+ out, fenced, comment = [], False, False
+ for n, line in enumerate(lines, start=1):
+ if not comment and line.lstrip().startswith("```"):
+ fenced = not fenced
+ continue
+ if fenced:
+ continue
+ text = ""
+ while line:
+ if comment:
+ end = line.find("-->")
+ if end == -1:
+ line = ""
+ else:
+ comment, line = False, line[end + 3:]
+ else:
+ start = line.find("<!--")
+ if start == -1:
+ text, line = text + line, ""
+ else:
+ text, comment, line = text + line[:start], True, line[start + 4:]
+ for target in IMPORT.findall(CODE_SPAN.sub("", text)):
+ out.append((n, target))
+ return out
+
+
+def scan_text(path, lines, skill=False, paths=True, imports=False):
+ """The line constructs every text group shares."""
+ if imports:
+ for n, target in imports_in(lines):
+ add("instructions", "@import", path, n)
+ for n, line in enumerate(lines, start=1):
+ for name, rx in RX.items():
+ if name in ("$ARGUMENTS", "$N") and not skill:
+ continue
+ if rx.search(line):
+ add(STATIC_FEATURE[name], name, path, n)
+ if TASK_TOOL.search(line) or (TASK_TICKED.search(line) and TASK_CONTEXT.search(line)):
+ add("subagents", "Task-tool", path, n)
+ for var in VAR.findall(line):
+ add(var_feature(var), "var:" + var, path, n)
+ if paths:
+ for seg in PATH.findall(line):
+ seg = seg.rstrip(".")
+ if not seg:
+ continue
+ if seg in CC_PATHS:
+ add(CC_PATHS[seg], "cc-path:.claude/" + seg, path, n)
+ else:
+ add(SHARED_FEATURE.get(seg, "instructions"), "shared-path:.claude/" + seg, path, n)
+
+
+def var_feature(var):
+ if var in SKILL_VARS:
+ return "skill-loading"
+ if var == "CLAUDE_PROJECT_DIR":
+ return "hooks"
+ return "settings"
+
+
+def import_targets(path, lines):
+ out = []
+ for _, target in imports_in(lines):
+ if target.startswith("~"):
+ out.append(os.path.normpath(os.path.join(os.path.expanduser("~"), target.lstrip("~/"))))
+ else:
+ out.append(os.path.normpath(os.path.join(os.path.dirname(path), target)))
+ return out
+
+
+claude = os.path.join(root, ".claude")
+
+# --- groups ----------------------------------------------------------------
+skill_dir = os.path.join(claude, "skills")
+skills = {}
+if os.path.isdir(skill_dir):
+ for d in sorted(os.listdir(skill_dir)):
+ if os.path.isfile(os.path.join(skill_dir, d, "SKILL.md")):
+ skills[d] = md_files(os.path.join(skill_dir, d))
+agent_dir = os.path.join(claude, "agents")
+agents = {}
+if os.path.isdir(agent_dir):
+ for f in sorted(os.listdir(agent_dir)):
+ if f.endswith(".md"):
+ agents[f[:-3]] = os.path.join(agent_dir, f)
+
+instruction_files = [p for p in (os.path.join(root, "CLAUDE.md"), os.path.join(root, "CLAUDE.local.md"),
+ os.path.join(claude, "CLAUDE.md")) if os.path.isfile(p)]
+for d in sorted(os.listdir(root)):
+ p = os.path.join(root, d, "CLAUDE.md")
+ if not d.startswith(".") and os.path.isfile(p):
+ instruction_files.append(p)
+rules_dir = os.path.join(claude, "rules")
+rule_files = [os.path.join(rules_dir, f) for f in sorted(os.listdir(rules_dir))
+ if f.endswith(".md")] if os.path.isdir(rules_dir) else []
+doc_files = md_files(os.path.join(claude, "docs")) if os.path.isdir(os.path.join(claude, "docs")) else []
+hook_dir = os.path.join(claude, "hooks")
+hook_files = [os.path.join(hook_dir, f) for f in sorted(os.listdir(hook_dir))
+ if f.endswith(".sh")] if os.path.isdir(hook_dir) else []
+statusline = os.path.join(claude, "statusline.sh")
+if os.path.isfile(statusline):
+ hook_files.append(statusline)
+settings_file = os.path.join(claude, "settings.json")
+settings_files = [settings_file] if os.path.isfile(settings_file) else []
+
+scope_note = ""
+if skill_filter:
+ picked_skills = {skill_filter: skills[skill_filter]} if skill_filter in skills else {}
+ picked_agents, read_instr, read_rules, read_docs, read_hooks, read_settings = {}, [], [], [], [], []
+ scope_note = "SCOPE: skill %s only; agents, instructions, docs, hooks and settings not read" % skill_filter
+elif agent_filter:
+ picked_agents = {agent_filter: agents[agent_filter]} if agent_filter in agents else {}
+ picked_skills, read_instr, read_rules, read_docs, read_hooks, read_settings = {}, [], [], [], [], []
+ scope_note = "SCOPE: agent %s only; skills, instructions, docs, hooks and settings not read" % agent_filter
+else:
+ picked_skills, picked_agents = skills, agents
+ read_instr, read_rules, read_docs = instruction_files, rule_files, doc_files
+ read_hooks, read_settings = hook_files, settings_files
+
+notes = []
+
+# --- skills ----------------------------------------------------------------
+for name, files in picked_skills.items():
+ for path in files:
+ lines = read_lines(path)
+ scan_text(path, lines, skill=True)
+ if os.path.basename(path) == "SKILL.md" and os.path.dirname(path) == os.path.join(skill_dir, name):
+ for n, key, value in frontmatter_lines(lines):
+ if key not in SKILL_PORTABLE:
+ add("frontmatter", "fm:" + key, path, n)
+ if key == "allowed-tools":
+ for e in list_entries(value):
+ if e == "Agent" or e.startswith("Agent("):
+ add("subagents", "Agent-tool", path, n)
+ elif e == "Task" or e.startswith("Task("):
+ add("subagents", "Task-tool", path, n)
+
+# --- agents ----------------------------------------------------------------
+for name, path in picked_agents.items():
+ lines = read_lines(path)
+ scan_text(path, lines)
+ for n, key, value in frontmatter_lines(lines):
+ if key not in AGENT_PORTABLE:
+ add("frontmatter", "fm:" + key, path, n)
+ if key == "tools":
+ v = value.strip()
+ if v and not v.startswith("["):
+ add("frontmatter", "tools-string", path, n)
+ for e in list_entries(value):
+ if e.startswith("Agent("):
+ add("subagents", "agent-type-list", path, n)
+ if e == "Agent" or e.startswith("Agent("):
+ add("subagents", "Agent-tool", path, n)
+ elif e == "Task" or e.startswith("Task("):
+ add("subagents", "Task-tool", path, n)
+
+# --- instructions and docs -------------------------------------------------
+imported, queue = set(), [(p, 0) for p in read_instr]
+while queue: # Claude Code follows imports four hops deep at most
+ path, depth = queue.pop(0)
+ if depth >= 4:
+ continue
+ for target in import_targets(path, read_lines(path)):
+ if target not in imported and os.path.isfile(target):
+ imported.add(target)
+ queue.append((target, depth + 1))
+# An imported file no other group reads (an engine reference, say) is instruction text too.
+grouped = {os.path.normpath(p) for p in read_instr + read_rules + read_docs}
+read_instr = read_instr + sorted(p for p in imported if os.path.normpath(p) not in grouped)
+
+for path in read_instr:
+ lines = read_lines(path)
+ if os.path.basename(path) in ("CLAUDE.md", "CLAUDE.local.md"):
+ add("instructions", "CLAUDE.md", path, 1)
+ scan_text(path, lines, imports=True)
+for path in read_rules:
+ lines = read_lines(path)
+ add("instructions", "rule-file", path, 1)
+ scan_text(path, lines, imports=os.path.normpath(path) in imported)
+ for n, key, value in frontmatter_lines(lines):
+ if key == "paths":
+ add("instructions", "rule-paths", path, n)
+for path in read_docs:
+ scan_text(path, read_lines(path), imports=os.path.normpath(path) in imported)
+
+# --- hooks -----------------------------------------------------------------
+for path in read_hooks:
+ is_status = os.path.normpath(path) == os.path.normpath(statusline)
+ for n, line in enumerate(read_lines(path), start=1):
+ for var in VAR.findall(line):
+ add(var_feature(var), "var:" + var, path, n)
+ if is_status:
+ for a, b in STATUS_PAYLOAD.findall(line):
+ add("settings", "statusline-payload:%s.%s" % (a, b), path, n)
+ continue
+ for field in HOOK_PAYLOAD.findall(line):
+ add("hooks", "hook-payload:" + field, path, n)
+ for token, exit2, decision in HOOK_ANSWER.findall(line):
+ add("hooks", "hook-answer:" + (token or ("exit-2" if exit2 else "decision")), path, n)
+
+# --- settings --------------------------------------------------------------
+for path in read_settings:
+ lines = read_lines(path)
+ scan_text(path, lines)
+
+ def line_of(needle, start=0):
+ for i in range(start, len(lines)):
+ if needle in lines[i]:
+ return i + 1
+ return 0
+
+ try:
+ data = json.loads("\n".join(lines))
+ except ValueError as exc:
+ notes.append("%s does not parse as JSON (%s); only its text was read" % (rel(path), exc))
+ continue
+ if not isinstance(data, dict):
+ notes.append("%s is not a JSON object; only its text was read" % rel(path))
+ continue
+ hooks_at = line_of('"hooks"')
+ for event, groups in (data.get("hooks") or {}).items():
+ at = line_of('"%s"' % event, max(hooks_at - 1, 0)) or hooks_at
+ for group in groups if isinstance(groups, list) else []:
+ matcher = (group.get("matcher") or "") if isinstance(group, dict) else ""
+ add("hooks", "hook:%s%s" % (event, "[%s]" % matcher if matcher else ""), path, at)
+ perms = data.get("permissions") or {}
+ perms_at = line_of('"permissions"')
+ cursor = max(perms_at - 1, 0)
+ for kind, value in perms.items():
+ if isinstance(value, list):
+ for rule in value:
+ at = line_of(json.dumps(rule, ensure_ascii=False), cursor) or perms_at
+ cursor = max(at, cursor)
+ add("settings", "permission:" + kind, path, at)
+ else:
+ add("settings", "permission:" + kind, path, line_of('"%s"' % kind, max(perms_at - 1, 0)) or perms_at)
+ for key in data:
+ if key not in ("$schema", "hooks", "permissions"):
+ add("skill-loading" if key == "skillOverrides" else "settings", "settings:" + key, path,
+ line_of('"%s"' % key) or 1)
+
+# --- report ----------------------------------------------------------------
+n_skill_files = sum(len(v) for v in picked_skills.values())
+read_count = (n_skill_files + len(picked_agents) + len(read_instr) + len(read_rules) + len(read_docs)
+ + len(read_hooks) + len(read_settings))
+print("ROOT: %s" % root)
+print("FILES: skills=%d skill_files=%d agents=%d instructions=%d docs=%d hooks=%d settings=%d"
+ % (len(picked_skills), n_skill_files, len(picked_agents), len(read_instr) + len(read_rules),
+ len(read_docs), len(read_hooks), len(read_settings)))
+print("FOUND_LINES: %d in %d of %d files read" % (len(found), len({f[2] for f in found}), read_count))
+if scope_note:
+ print(scope_note)
+if skill_filter and skill_filter not in skills:
+ print("NOT FOUND: skill %s is not a folder in .claude/skills/" % skill_filter)
+if agent_filter and agent_filter not in agents:
+ print("NOT FOUND: agent %s is not a file in .claude/agents/" % agent_filter)
+for note in notes:
+ print("NOTE: %s" % note)
+
+counts = {}
+for feature, construct, path, line in found:
+ c = counts.setdefault((feature, construct), [set(), 0])
+ c[0].add(path)
+ c[1] += 1
+rows = {(f, c): (len(v[0]), v[1]) for (f, c), v in counts.items()}
+for feature, construct in STATIC:
+ rows.setdefault((feature, construct), (0, 0))
+for feature, family in DYNAMIC:
+ if not any(c.startswith(family + ":") and c not in STATIC_FEATURE for (_, c) in rows):
+ rows[(feature, family + ":*")] = (0, 0)
+for (feature, construct), (nf, nh) in sorted(rows.items()):
+ print("COUNT: %s %s files=%d hits=%d" % (feature, construct, nf, nh))
+for feature, construct, path, line in sorted(found, key=lambda f: (f[2], f[3], f[0], f[1])):
+ print("FOUND: %s %s %s:%d" % (feature, construct, path, line))
+PYEOF
+exit 0
diff --git a/.claude/scripts/config-set.sh b/.claude/scripts/config-set.sh
new file mode 100644
index 00000000..e00baf34
--- /dev/null
+++ b/.claude/scripts/config-set.sh
@@ -0,0 +1,554 @@
+#!/usr/bin/env bash
+# config-set.sh — set one key in project.yaml or project.local.yaml, after the
+# checks /settings makes before a write, and read the value back.
+#
+# Replaces /settings Phases 1b, 4 and 5 done by hand: the enum check, the local
+# whitelist, the base-file check, the reserved-setting warning (a `grep -B14`
+# over effects-map.md), the shadow warning, and the edit Cases A-D.
+#
+# THE ASK STAYS IN THE SKILL. This script never prompts and never judges. Run it
+# with --dry-run first to get the check rows, show the user the warnings, ask,
+# then run it again without --dry-run. A reserved key is written, never refused
+# (storing the value a user means is legitimate; storing it silently is the
+# defect, so the `reserved` row is the skill's to say out loud).
+#
+# Usage: bash .claude/scripts/config-set.sh [--local] KEY VALUE [--dry-run] [--root DIR]
+# bash .claude/scripts/config-set.sh [--local] KEY=VALUE ...
+# KEY a dotted YAML path, for example modes.review_mode
+# VALUE the new value; quote one with spaces ("Systems Design"). KEY=VALUE
+# splits at the first `=`
+# --local write project.local.yaml (gitignored) instead of project.yaml
+# --dry-run print every row; write nothing
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+# KEY and VALUE must both be non-empty. A VALUE with a newline, one that starts
+# with `#`, or one holding ` #` would be cut or turned into a comment by YAML,
+# so it is refused (exit 2) rather than written. So is one that starts with a
+# quote: the readers drop the quotes, so give the value bare and config-set
+# quotes it where the file already quotes that key.
+#
+# Where the facts come from, so nothing here is a second copy of them:
+# enums and the local whitelist the _yaml_helper_enums and
+# _yaml_helper_locally_overridable constants in
+# .claude/hooks/yaml-helper.sh, read as text
+# reserved keys effects-map.md: the `## ` heading above each
+# `> ### RESERVED` banner, split on " and "
+# known keys those two lists, the effects-map headings
+# (a key under a heading's dotted prefix counts),
+# and the keys in effects-map's "Complete
+# example `project.yaml`" block (a key under one
+# of its scalar keys counts: an OS-aware
+# command, a system override)
+# reading a value back yaml-get.awk, as project-state.sh does
+# project.stage is not edited here: it goes through set-stage.sh, which also
+# keeps production/stage.txt in step (the stage mirror).
+#
+# What the edit does (comments, other keys, line endings and a UTF-8 BOM kept):
+# A the key is set: its value is replaced, keeping quotes and an inline comment;
+# a value holding the file's quote takes the other quote, and one holding
+# both is written bare; when the key is set more than once the LAST one is
+# edited, as every reader uses that one
+# B a parent block exists, the leaf does not: the leaf goes at the end of the
+# deepest existing block, at that block's child indent, with any missing
+# blocks between written out
+# C no top-level block holds it: a new block goes at the end of the file after
+# one blank line, or first in a file of blank lines only
+# D a layout it will not edit (exit 5): the key is a block with children or
+# holds multi-line text (a `|` or `>` value with lines under it), or one of
+# its parents is a one-line value. Nothing is written.
+# The lines of a multi-line text value are text, never keys: a `review_mode:`
+# line inside `notes: |` is neither edited nor counted as the key.
+# A missing project.local.yaml is created with a one-line header comment.
+# A file already holding the value is left byte-for-byte alone. The new text is
+# made in full and read back first, then copied over the file in place, so the
+# file keeps its mode and a symlink stays one.
+#
+# Output: TSV, in this order.
+# file <project.yaml|project.local.yaml> <present|absent>
+# enum <ok|invalid|none> <allowed values, or - when the key has no enum>
+# whitelist <overridable|locked> <yaml-helper.sh's list>
+# reserved <yes|no> <the effects-map heading, or ->
+# known <yes|no> <why>; on no, ending "; nearest: KEY" when a known
+# key is at most two single-character edits away (a typo)
+# shadow <yes|no> <the project.local.yaml value> (project.yaml writes only)
+# current <value now in the file, or -> <file>
+# edit <replaced|inserted|added-block|created|unchanged|refused|via set-stage.sh> <line or ->
+# readback <value read back from the edited text> <file>
+# Rows that cannot apply are left out (no shadow row for --local). A write that is
+# refused still prints the rows up to the one that refused it. For project.stage,
+# set-stage.sh's rows (project.yaml, stage.txt, stage_yaml, stage_txt) follow
+# `edit via set-stage.sh` in place of `readback`.
+#
+# Exit codes: 0 done (or a dry run that would be); 1 cannot read the root, the
+# yaml-helper.sh constants or a file, or cannot write; 2 usage error; 3 the value
+# is not in the key's enum; 4 --local on a key that is not on the whitelist;
+# 5 a layout it will not edit; 6 no project.yaml; 7 the value read
+# back is not the one asked for. 3 to 7 write nothing. project.stage exits with
+# set-stage.sh's code, which means the same, its 4 (the files disagree) given as 7.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk: the BOM and CR tests below compare bytes.
+LC_ALL=C
+export LC_ALL
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+LOCAL=0; DRY=0; ROOT_ARG=""; KEY=""; VALUE=""; HAVE_VALUE=0
+usage() { echo "config-set: $1 (try --help)" >&2; exit 2; }
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --local) LOCAL=1; shift ;;
+ --dry-run) DRY=1; shift ;;
+ --root) [ $# -ge 2 ] || usage "--root needs a value"; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) usage "unknown argument: $1" ;;
+ *)
+ if [ -z "$KEY" ]; then
+ case "$1" in
+ *=*) KEY="${1%%=*}"; VALUE="${1#*=}"; HAVE_VALUE=1 ;;
+ *) KEY="$1" ;;
+ esac
+ [ -n "$KEY" ] || usage "the key is empty"
+ elif [ "$HAVE_VALUE" = 0 ]; then VALUE="$1"; HAVE_VALUE=1
+ else usage "one KEY and one VALUE only (quote a value with spaces)"
+ fi
+ shift ;;
+ esac
+done
+[ -n "$KEY" ] || usage "no key given"
+[ "$HAVE_VALUE" = 1 ] && [ -n "$VALUE" ] || usage "no value given for $KEY"
+case "$KEY" in
+ *[!A-Za-z0-9_.-]*|.*|*.|*..*) usage "'$KEY' is not a dotted key (letters, digits, _ and -, joined by dots)" ;;
+esac
+NL='
+'
+case "$VALUE" in
+ *"$NL"*) usage "the value has a newline" ;;
+ "#"*|*" #"*) usage "the value starts with # or holds ' #', which YAML reads as a comment" ;;
+esac
+case "$VALUE" in
+ " "*|*" ") usage "the value has leading or trailing spaces, which YAML drops" ;;
+ \"*|\'*) usage "the value starts with a quote, which the readers drop; give it without quotes (the file's own quoting is kept)" ;;
+esac
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "config-set: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "config-set: cannot reach the repo root" >&2; exit 1; }
+fi
+YH="$HERE/../hooks/yaml-helper.sh"
+EM="$HERE/../docs/effects-map.md"
+[ -f "$YH" ] || { echo "config-set: $YH is missing; the enums and the whitelist live there" >&2; exit 1; }
+[ -f "$EM" ] || { echo "config-set: $EM is missing; the reserved settings live there" >&2; exit 1; }
+[ -f "$HERE/yaml-get.awk" ] || { echo "config-set: $HERE/yaml-get.awk is missing" >&2; exit 1; }
+
+# yh_const NAME — the lines of the shell string NAME="\ ... " in yaml-helper.sh.
+yh_const() {
+ awk -v n="$1" '
+ $0 == n "=\"\\" { on = 1; next }
+ on { l = $0; end = (l ~ /"$/); if (end) sub(/"$/, "", l); print l; if (end) exit }
+ ' "$YH"
+}
+ENUMS=$(yh_const _yaml_helper_enums)
+WHITELIST=$(yh_const _yaml_helper_locally_overridable)
+[ -n "$ENUMS" ] && [ -n "$WHITELIST" ] || { echo "config-set: found no enum or whitelist constants in $YH" >&2; exit 1; }
+
+# yget FILE KEY — the value at a dotted path, by the one shared reader.
+yget() { YG_PATH="$2" awk -f "$HERE/yaml-get.awk" "$1"; }
+
+# --- the checks --------------------------------------------------------------
+TARGET="project.yaml"; [ "$LOCAL" = 1 ] && TARGET="project.local.yaml"
+if [ -f "$TARGET" ]; then printf 'file\t%s\tpresent\n' "$TARGET"; else printf 'file\t%s\tabsent\n' "$TARGET"; fi
+
+# enum: the allowed set is whatever follows `KEY::`. testing.strict is not in
+# the table (its shape is a map of five types); one value written to it is the
+# back-compat boolean, which validate_enum_value in yaml-helper.sh checks too.
+ALLOWED=$(printf '%s\n' "$ENUMS" | awk -v k="$KEY" 'index($0, k "::") == 1 { print substr($0, length(k) + 3); exit }')
+[ "$KEY" = testing.strict ] && ALLOWED="true|false"
+EXIT=0
+if [ -z "$ALLOWED" ]; then
+ printf 'enum\tnone\t-\n'
+else
+ ENUM_OK=invalid
+ oldIFS="$IFS"; IFS='|'
+ for v in $ALLOWED; do [ "$VALUE" = "$v" ] && ENUM_OK=ok; done
+ IFS="$oldIFS"
+ printf 'enum\t%s\t%s\n' "$ENUM_OK" "$ALLOWED"
+ [ "$ENUM_OK" = ok ] || EXIT=3
+fi
+
+# whitelist
+if printf '%s\n' "$WHITELIST" | grep -qxF "$KEY"; then WL=overridable; else WL=locked; fi
+printf 'whitelist\t%s\t%s\n' "$WL" "yaml-helper.sh _yaml_helper_locally_overridable"
+[ "$LOCAL" = 1 ] && [ "$WL" = locked ] && [ "$EXIT" = 0 ] && EXIT=4
+
+# headings: every `## ` line of effects-map.md, " and " split, and which of them
+# sit under a RESERVED banner (the last heading before the banner).
+ALL_HEADS=$(awk '/^## / { h = substr($0, 4); sub(/[ \t\r]+$/, "", h); print h }' "$EM")
+HEADINGS=$(awk '/^## / { last = substr($0, 4); sub(/[ \t\r]+$/, "", last) } /^> ### RESERVED/ { print last }' "$EM")
+split_and() { printf '%s\n' "$1" | sed 's/ and /\
+/g'; }
+RES_HIT="-"
+while IFS= read -r h; do
+ [ -n "$h" ] || continue
+ while IFS= read -r one; do
+ [ "$one" = "$KEY" ] && RES_HIT="$h"
+ done <<EOF
+$(split_and "$h")
+EOF
+done <<EOF
+$HEADINGS
+EOF
+if [ "$RES_HIT" = "-" ]; then printf 'reserved\tno\t-\n'; else printf 'reserved\tyes\t%s\n' "$RES_HIT"; fi
+
+# known: an enum key, a whitelisted key, a key at or under an effects-map heading,
+# or a key of effects-map's complete example project.yaml, which is the only
+# place that names some keys skills read (engine.version, platform.targets).
+KNOWN=no; WHY="no enum, whitelist entry, effects-map heading or complete-example key names it"
+[ -n "$ALLOWED" ] && { KNOWN=yes; WHY="enum key"; }
+[ "$KNOWN" = no ] && [ "$WL" = overridable ] && { KNOWN=yes; WHY="whitelisted key"; }
+if [ "$KNOWN" = no ]; then
+ while IFS= read -r h; do
+ [ -n "$h" ] || continue
+ while IFS= read -r one; do
+ case "$KEY" in "$one"|"$one".*) KNOWN=yes; WHY="effects-map heading: $h" ;; esac
+ done <<EOF
+$(split_and "$h")
+EOF
+ done <<EOF
+$ALL_HEADS
+EOF
+fi
+if [ "$KNOWN" = no ]; then
+ # The example's key paths, each `leaf` (holds a value) or `parent` (opens a
+ # mapping), read the way yaml-get.awk reads a file; list items are skipped.
+ EXAMPLE=$(awk '
+ /^## Complete example `project\.yaml`/ { sec = 1; next }
+ sec && /^## / { exit }
+ sec && !on && /^```/ { on = 1; next }
+ on && /^```/ { exit }
+ on {
+ l = $0; sub(/\r$/, "", l)
+ n = 0; while (substr(l, n + 1, 1) == " ") n++
+ s = substr(l, n + 1); c = substr(s, 1, 1)
+ if (s == "" || c == "#" || c == "-") next
+ p = index(s, ":"); if (p == 0) next
+ k = substr(s, 1, p - 1); v = substr(s, p + 1); sub(/^[ \t]+/, "", v)
+ while (d > 0 && ind[d] >= n) d--
+ full = ""; for (i = 1; i <= d; i++) full = full keys[i] "."; full = full k
+ if (v == "" || substr(v, 1, 1) == "#") { d++; ind[d] = n; keys[d] = k; print "parent\t" full }
+ else print "leaf\t" full
+ }
+ ' "$EM")
+ if [ -z "$EXAMPLE" ]; then
+ WHY="$WHY (effects-map.md has no complete example block, so it was not read)"
+ else
+ while IFS="$(printf '\t')" read -r kind p; do
+ case "$kind:$KEY" in
+ "parent:$p"|"leaf:$p"|"leaf:$p".*) KNOWN=yes; WHY="effects-map complete example: $p"; break ;;
+ esac
+ done <<EOF
+$EXAMPLE
+EOF
+ fi
+fi
+# An unknown key is most often a typo of a known one (qa.levl), so name the
+# nearest known key when it is at most two single-character edits away. The
+# candidates are every key the checks above accept by name.
+if [ "$KNOWN" = no ]; then
+ NEAR=$( { printf '%s\n' "$ENUMS" | sed 's/::.*//'
+ printf '%s\n' "$WHITELIST"
+ printf '%s\n' "$ALL_HEADS" | sed 's/ and /\
+/g'
+ printf '%s\n' "${EXAMPLE:-}" | cut -f2; } | awk -v k="$KEY" '
+ function lev(a, b, la, lb, i, j, c, x, y, z, d) {
+ la = length(a); lb = length(b)
+ for (j = 0; j <= lb; j++) d[0, j] = j
+ for (i = 1; i <= la; i++) {
+ d[i, 0] = i
+ for (j = 1; j <= lb; j++) {
+ c = (substr(a, i, 1) == substr(b, j, 1)) ? 0 : 1
+ x = d[i - 1, j] + 1; y = d[i, j - 1] + 1; z = d[i - 1, j - 1] + c
+ d[i, j] = (x < y) ? ((x < z) ? x : z) : ((y < z) ? y : z)
+ }
+ }
+ return d[la, lb]
+ }
+ { sub(/\r$/, "") }
+ /^[a-z0-9_]+(\.[a-z0-9_]+)*$/ && !seen[$0]++ {
+ e = lev(k, $0)
+ if (e > 0 && e <= 2 && (best == "" || e < be)) { best = $0; be = e }
+ }
+ END { if (best != "") print best }')
+ [ -n "$NEAR" ] && WHY="$WHY; nearest: $NEAR"
+fi
+printf 'known\t%s\t%s\n' "$KNOWN" "$WHY"
+
+if [ "$EXIT" != 0 ]; then
+ case "$EXIT" in
+ 3) echo "config-set: Invalid value '$VALUE' for '$KEY'. Allowed: $ALLOWED" >&2 ;;
+ 4) echo "config-set: $KEY cannot be locally overridden: it is a project-wide setting. Set it in project.yaml without --local." >&2 ;;
+ esac
+ exit "$EXIT"
+fi
+
+# base check: local overrides need a base, and /settings never creates project.yaml.
+if [ ! -f project.yaml ]; then
+ echo "config-set: project.yaml is missing, so there is nothing to set or override. Run /start to create one first." >&2
+ exit 6
+fi
+
+# shadow: a local value hides the one about to be written to project.yaml.
+if [ "$LOCAL" = 0 ]; then
+ SH=""; [ -f project.local.yaml ] && SH=$(yget project.local.yaml "$KEY")
+ if [ -n "$SH" ]; then printf 'shadow\tyes\t%s\n' "$SH"; else printf 'shadow\tno\t-\n'; fi
+fi
+
+CUR="-"; [ -f "$TARGET" ] && { CUR=$(yget "$TARGET" "$KEY"); [ -n "$CUR" ] || CUR="-"; }
+printf 'current\t%s\t%s\n' "$CUR" "$TARGET"
+
+# --- project.stage goes through set-stage.sh ---------------------------------
+if [ "$KEY" = project.stage ]; then
+ [ -f "$HERE/set-stage.sh" ] || { echo "config-set: $HERE/set-stage.sh is missing" >&2; exit 1; }
+ printf 'edit\tvia set-stage.sh\t-\n'
+ # set-stage.sh's rows stand in for `readback`. Its exit codes mean what this
+ # script's do, except its 4 (the two files disagree after writing), which is
+ # this script's 7, so a 4 here always means nothing was written.
+ if [ "$DRY" = 1 ]; then bash "$HERE/set-stage.sh" "$VALUE" --dry-run --root .; else bash "$HERE/set-stage.sh" "$VALUE" --root .; fi
+ rc=$?
+ [ "$rc" = 4 ] && rc=7
+ exit "$rc"
+fi
+
+# --- the edit ----------------------------------------------------------------
+# replace_file TARGET NEWFILE — the new text, made in full in NEWFILE first,
+# copied over TARGET in place, so TARGET keeps its mode, a symlink stays a
+# symlink and a hard link sees the change (a mv would put a new file there).
+replace_file() {
+ if ! cat "$2" > "$1" 2>/dev/null; then
+ echo "config-set: could not write $1; the new text is kept in $2" >&2
+ exit 1
+ fi
+ rm -f "$2"
+}
+NEW=$(mktemp "./.ccgs-set-XXXXXX" 2>/dev/null) || { echo "config-set: cannot create a temporary file in $(pwd)" >&2; exit 1; }
+STATUS="$NEW.status"
+ACTION=""; LINE="-"; DUPS=""
+if [ ! -f "$TARGET" ]; then
+ ACTION="created"
+ # A new local file: header (the line /settings Phase 5 writes), then the key
+ # wrapped in its parent blocks, two spaces a level, as the shipped project.yaml
+ # and every new block below are indented.
+ awk -v key="$KEY" -v val="$VALUE" 'BEGIN {
+ print "# project.local.yaml — per-developer overrides (gitignored)"
+ n = split(key, s, ".")
+ for (i = 1; i <= n; i++) {
+ pad = ""; for (j = 1; j < i; j++) pad = pad " "
+ if (i < n) print pad s[i] ":"; else print pad s[i] ": " val
+ }
+ }' > "$NEW"
+ LINE=$(awk 'END { print NR }' "$NEW")
+else
+ CS_KEY="$KEY" CS_VALUE="$VALUE" CS_STATUS="$STATUS" awk '
+ # opens(s, n): when line s (at indent n, its leading spaces removed) opens
+ # a block scalar (a value of | or >, with any indicators), the indent its
+ # text must exceed; else -1. The rule yaml-get.awk reads by.
+ function opens(s, n, r, p, v) {
+ r = s
+ if (r == "-" || substr(r, 1, 2) == "- ") {
+ r = substr(r, 2); sub(/^ +/, "", r)
+ if (r ~ /^[|>][-+0-9]*[ \t]*(#.*)?$/) return n
+ n = n + length(s) - length(r)
+ }
+ if (r == "" || r ~ /^[:# \t]/) return -1
+ p = index(r, ":"); if (p == 0) return -1
+ v = substr(r, p + 1); sub(/^[ \t]+/, "", v); sub(/[ \t]+$/, "", v)
+ return (v ~ /^[|>][-+0-9]*[ \t]*(#.*)?$/) ? n : -1
+ }
+ # Git for Windows gawk reads files in text mode and drops the CR of a CRLF
+ # line; BINMODE 3 keeps every byte. Other awks treat it as a plain variable.
+ BEGIN { BINMODE = 3 }
+ { raw[NR] = $0 }
+ END {
+ key = ENVIRON["CS_KEY"]; val = ENVIRON["CS_VALUE"]; status = ENVIRON["CS_STATUS"]
+ nseg = split(key, seg, ".")
+ depth = 0; blk = -1; crlf = (raw[1] ~ /\r$/); eol = crlf ? "\r" : ""
+ # "\357\273\277" is the UTF-8 byte-order mark. It comes off line 1 here
+ # and goes back in front of the output, so an edit of line 1 cuts the
+ # key line, not the mark.
+ bom = ""
+ if (NR > 0 && substr(raw[1], 1, 3) == "\357\273\277") { bom = substr(raw[1], 1, 3); raw[1] = substr(raw[1], 4) }
+ # Parse every line the way yaml-get.awk does: indent, key, value, full path.
+ for (L = 1; L <= NR; L++) {
+ line = raw[L]
+ sub(/\r$/, "", line)
+ n = 0
+ while (substr(line, n + 1, 1) == " ") n++
+ s = substr(line, n + 1)
+ t = s
+ sub(/^[ \t]+/, "", t)
+ kind[L] = "other"
+ if (t == "") { kind[L] = "blank"; continue }
+ if (substr(t, 1, 1) == "#") { kind[L] = "comment"; continue }
+ indent[L] = n
+ # A block scalar text line stays "other": content of the block above it.
+ if (blk >= 0) { if (n > blk) continue; blk = -1 }
+ blk = opens(s, n); text[L] = (blk >= 0)
+ c = substr(s, 1, 1)
+ if (c == ":" || c == "#" || c == "\t") continue
+ p = index(s, ":")
+ if (p == 0) continue
+ k = substr(s, 1, p - 1)
+ sub(/[ \t]+$/, "", k)
+ v = substr(s, p + 1)
+ sub(/^[ \t]+/, "", v)
+ sub(/[ \t]+$/, "", v)
+ q = substr(v, 1, 1)
+ if (q == "#") v = ""
+ else if (q == "\"" || q == "\047") {
+ rest = substr(v, 2); e = index(rest, q)
+ v = (e > 0) ? substr(rest, 1, e - 1) : rest
+ } else {
+ h = index(v, " #")
+ if (h > 0) { v = substr(v, 1, h - 1); sub(/[ \t]+$/, "", v) }
+ }
+ while (depth > 0 && ind[depth] >= n) depth--
+ full = ""
+ for (i = 1; i <= depth; i++) full = full keys[i] "."
+ full = full k
+ kind[L] = "key"; hasval[L] = (v != ""); fullp[L] = full; colon[L] = n + p; curv[L] = v
+ if (v == "") { depth++; ind[depth] = n; keys[depth] = k }
+ cnt[full]++; lastat[full] = L
+ if (full == key) dupl = dupl (cnt[full] > 1 ? "," : "") L
+ }
+ # blockend(L): the last content line of the block a key line opens.
+ # Comments and blank lines after it belong to whatever comes next.
+ # hasval keys have no block.
+ action = ""; at = 0
+ T = (key in lastat) ? lastat[key] : 0
+ if (T > 0) {
+ last = T
+ for (j = T + 1; j <= NR; j++) {
+ if (kind[j] == "key" && indent[j] <= indent[T]) break
+ if (kind[j] == "other" && indent[j] <= indent[T]) break
+ if (kind[j] == "key" || kind[j] == "other") last = j
+ }
+ if (last > T && !hasval[T]) { print "unsupported\t" T "\tblock" > status; exit 0 }
+ if (last > T && text[T]) { print "unsupported\t" T "\ttext" > status; exit 0 }
+ if (curv[T] == val) action = "unchanged"
+ else {
+ action = "replaced"
+ line = raw[T]; cr = (line ~ /\r$/); sub(/\r$/, "", line)
+ pre = substr(line, 1, colon[T]); after = substr(line, colon[T] + 1)
+ lead = after; sub(/[^ \t].*$/, "", lead); if (lead == "") lead = " "
+ a = after; sub(/^[ \t]+/, "", a)
+ q = substr(a, 1, 1); nv = val
+ if (a == "") tail = ""
+ else if (q == "#") tail = " " a
+ else if (q == "\"" || q == "\047") {
+ e = index(substr(a, 2), q)
+ tail = (e > 0) ? substr(a, e + 2) : ""
+ # The readers end a quoted value at its first matching quote, so a
+ # value holding the quote the file uses takes the other one, and a
+ # value holding both is written bare (it cannot start with a quote:
+ # the usage check refuses that), which they read whole.
+ o = (q == "\"") ? "\047" : "\""
+ if (index(val, q) == 0) nv = q val q
+ else if (index(val, o) == 0) nv = o val o
+ else nv = val
+ } else {
+ # Keep an inline comment and the spaces before it; drop the old value.
+ h = index(a, " #"); tail = ""
+ if (h > 0) { tok = substr(a, 1, h - 1); sub(/[ \t]+$/, "", tok); tail = substr(a, length(tok) + 1) }
+ }
+ raw[T] = pre lead nv tail (cr ? "\r" : "")
+ }
+ at = T
+ } else {
+ # The deepest existing parent: the longest proper prefix that is a key line.
+ m = 0; path = ""; pm = ""
+ for (i = 1; i < nseg; i++) {
+ path = path (i > 1 ? "." : "") seg[i]
+ if (path in lastat) m = i
+ }
+ if (m > 0) {
+ pm = seg[1]; for (i = 2; i <= m; i++) pm = pm "." seg[i]
+ A = lastat[pm]
+ if (hasval[A]) { print "unsupported\t" A "\tscalar-parent" > status; exit 0 }
+ last = A; ci = -1
+ for (j = A + 1; j <= NR; j++) {
+ if ((kind[j] == "key" || kind[j] == "other") && indent[j] <= indent[A]) break
+ if (kind[j] == "key" || kind[j] == "other") { last = j; if (ci < 0) ci = indent[j] }
+ }
+ # An empty block has no child indent to copy: two spaces deeper, and
+ # two more for each missing block below it, as the shipped file nests.
+ if (ci < 0) ci = indent[A] + 2
+ block = ""
+ for (i = m + 1; i <= nseg; i++) {
+ pad = ""; for (j = 0; j < ci + 2 * (i - m - 1); j++) pad = pad " "
+ block = block (i > m + 1 ? "\n" : "") pad seg[i] ":" (i == nseg ? " " val : "") eol
+ }
+ ins[last] = block; action = "inserted"; at = last + 1
+ } else {
+ # No top-level block holds it: a new block after the last non-blank line.
+ last = NR
+ while (last > 0 && kind[last] == "blank") last--
+ block = ""
+ for (i = 1; i <= nseg; i++) {
+ pad = ""; for (j = 1; j < i; j++) pad = pad " "
+ block = block (i > 1 ? "\n" : "") pad seg[i] ":" (i == nseg ? " " val : "") eol
+ }
+ sep = (last > 0) ? eol "\n" : ""
+ ins[last] = sep block; action = "added-block"; at = last + (last > 0 ? 2 : 1)
+ }
+ }
+ # A new block in an empty file, or one of blank lines only, goes first
+ # (last is 0 there), before whatever blank lines it holds.
+ printf "%s", bom
+ if (0 in ins) print ins[0]
+ for (L = 1; L <= NR; L++) {
+ print raw[L]
+ if (L in ins) print ins[L]
+ }
+ printf "%s\t%s\t%s\n", action, at, dupl > status
+ }
+ ' "$TARGET" > "$NEW"
+ IFS="$(printf '\t')" read -r ACTION LINE DUPS < "$STATUS" 2>/dev/null
+ rm -f "$STATUS"
+ if [ "${ACTION:-}" = "unsupported" ]; then
+ rm -f "$NEW"
+ printf 'edit\trefused\t%s\n' "$LINE"
+ case "$DUPS" in
+ block) echo "config-set: $TARGET line $LINE: $KEY cannot be set there. It is a block with entries under it." >&2 ;;
+ text) echo "config-set: $TARGET line $LINE: $KEY cannot be set there. It holds multi-line text (a | or > value with lines under it)." >&2 ;;
+ *) echo "config-set: $TARGET line $LINE: $KEY cannot be set there. A parent of it is a one-line value." >&2 ;;
+ esac
+ echo " Nothing was written; edit the file by hand." >&2
+ exit 5
+ fi
+ [ -n "${ACTION:-}" ] || { rm -f "$NEW"; echo "config-set: could not parse $TARGET; nothing was written" >&2; exit 1; }
+ if [ -n "${DUPS:-}" ] && [ "$DUPS" != "$LINE" ]; then
+ case "$DUPS" in *,*) echo "config-set: $KEY is set more than once in $TARGET (lines $DUPS); the last is the one readers use, so that is the one edited" >&2 ;; esac
+ fi
+ [ "$ACTION" = "unchanged" ] && { rm -f "$NEW"; NEW=""; }
+fi
+
+printf 'edit\t%s\t%s\n' "$ACTION" "$LINE"
+if [ "$DRY" = 1 ]; then
+ [ -n "$NEW" ] && rm -f "$NEW"
+ exit 0
+fi
+
+# Read the value back from the new text before it replaces the file, so a
+# write whose readback is wrong never lands.
+BACK=$(yget "${NEW:-$TARGET}" "$KEY")
+printf 'readback\t%s\t%s\n' "${BACK:--}" "$TARGET"
+if [ "$BACK" != "$VALUE" ]; then
+ [ -n "$NEW" ] && rm -f "$NEW"
+ echo "config-set: the edited $TARGET would read '$BACK' for $KEY, not '$VALUE', so nothing was written. Edit the file by hand." >&2
+ exit 7
+fi
+[ -n "$NEW" ] && replace_file "$TARGET" "$NEW"
+exit 0
diff --git a/.claude/scripts/content-count.sh b/.claude/scripts/content-count.sh
new file mode 100644
index 00000000..d671f8c9
--- /dev/null
+++ b/.claude/scripts/content-count.sh
@@ -0,0 +1,399 @@
+#!/usr/bin/env bash
+# content-count.sh — the counts /content-audit works out by hand: the named
+# content the entity registry plans (entries, deprecated ones left out), the
+# content files found on disk per engine and per content type, and a
+# specified / found pair's percentage and status band, with the gap table's
+# totals.
+#
+# Replaces the hand-run counting in /content-audit (Phase 1 step 2, Phase 2
+# and Phase 3) and the "planned content" count /consistency-check and
+# /asset-spec make from the same registry.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# A band name is the rule row that matched. Whether a system is HIGH PRIORITY
+# (the skill's text does not say whether "NOT STARTED or EARLY, AND tagged MVP
+# or Vertical Slice, OR blocking" groups as (A AND B) OR C or A AND (B OR C))
+# stays in the skill: each gap row says only whether its band is a low one
+# (NOT STARTED or EARLY). The counts are of files and entries; whether a scene
+# is a gameplay level or a UI scene is not known here (see by levels).
+#
+# Usage: bash .claude/scripts/content-count.sh [--root DIR] COMMAND [ARGS]
+# registry the planned named content: the entries of design/registry/
+# entities.yaml's entities and items sections, read through
+# registry.sh, deprecated ones left out
+# found [--engine E] [--files]
+# content files on disk for the engine (godot, unity or
+# unreal; default: engine.name as project-state.sh reads it)
+# band FOUND SPECIFIED
+# the percentage and status band of one pair
+# gap rows `system<TAB>type<TAB>specified<TAB>found` on stdin:
+# the gap table, with totals
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+#
+# The status bands (the skill's, with 49.5% and 99.5% no longer in none). The
+# edges are half-open, found / specified compared exactly, never as a rounded
+# or printed percentage, so every value falls in exactly one band:
+# found = 0 NOT STARTED
+# 0 < found/specified < 50% EARLY (the skill's "1-49%")
+# 50% <= found/specified < 100% IN PROGRESS (the skill's "50-99%")
+# found >= specified COMPLETE (the skill's "100%+")
+# A specified of 0 has no percentage and no band: `-`. Percentages are
+# truncated, not rounded, to one decimal, so a printed value never sits on the
+# far side of a band edge (99.96% prints 99.9, never 100.0).
+#
+# Where `found` looks, per engine (the skill's Phase 2 globs, with the engine
+# rules it gives): assets/ and
+# godot src/ levels and characters only; no data/ needed under src/
+# unity Assets/ every type; no data/ segment needed
+# unreal Content/ every type; no data/ segment needed (Source/ holds
+# C++ only and is not searched)
+# A root is looked for by its exact name, so Assets/ and assets/ are two roots
+# even on a case-insensitive disk. Each root is printed present or absent.
+# Under assets/ the four data types (characters, items, abilities, quests)
+# need a data/ folder as the first folder, as the skill's assets/data/** globs
+# do; levels and dialogue do not.
+# levels the engine's scene files: .tscn, .unity, .umap (one extension
+# per engine, not all three); by levels counts them in folders
+# named levels, areas, maps, worlds or stages. A UI scene counts
+# too, as the skill says to count every match.
+# characters folders enemies, characters, npcs (npcs: the skill's heading
+# names NPCs but its globs do not)
+# items folders items, equipment, loot; on Unity also any file named
+# *Item*.asset (by items *Item*.asset)
+# abilities folders abilities, skills, spells
+# quests folders quests, missions, objectives (objectives likewise)
+# dialogue .dialogue, .csv, .ink files under any root but src/ (by ext)
+# Folder names compare in any case (items and Items). Files in them count when
+# their extension is one of the engine's data extensions: godot json, tres,
+# asset and, for characters, yaml, tscn and prefab, and for quests json and
+# yaml only; unity json, yaml, asset, prefab; unreal uasset. A file in two
+# folders of a type counts once in the type and once in each folder row.
+#
+# Output: TSV.
+# registry: registry <path> <entries | missing | layout>, planned
+# entities <n>, planned items <n>, planned_total <n>,
+# deprecated_skipped <n>, no_status <n> (counted, status absent),
+# status_other <n> <values> (counted, status not active or
+# deprecated), duplicate_names <n> (a name twice in a section),
+# source <gdd> <n> per source GDD of the planned entries, then
+# PLANNED <section> <name> <source> and
+# SKIPPED <section> <name> <source> deprecated, in registry order
+# found: engine <name> <source: project.yaml, project.local.yaml, flag...>,
+# root <dir> <present|absent>, found <type> <n> (six types), by
+# <type> <folder | extension> <n>, and with --files
+# FILE <type> <path>
+# band: band <F>/<S> <name | -> <percent | -> <rule>
+# gap: rows <counted> <read>, excluded <n>, total_specified,
+# total_found, total_gap (specified - found, as the skill's
+# summary has it; negative when over-built), gap_pct (that over
+# total_specified), unbuilt (the sum of each row's shortfall,
+# which an over-built row cannot hide), unbuilt_pct, systems <n>,
+# ROW <system> <type> <specified> <found> <gap> <percent>
+# <status> <low>, EXCLUDED <system> <type> <reason>
+# gap = specified - found, not below 0; percent = found / specified
+# low = yes for NOT STARTED and EARLY; a row whose specified or
+# found is not a number (Unspecified, NOT ASSESSED) is excluded
+# from the rows and totals and named
+#
+# Exit codes: 0 answered; 1 the root cannot be read, or a script it needs is
+# missing; 2 usage error; 3 found: no engine, or an engine without rules
+# (prints its engine row); gap: no row with numbers; 4 registry: the layout is
+# unsupported (registry.sh's LAYOUT rows are printed); found: none of the
+# engine's roots exists, so nothing was scanned. Reads only; never writes,
+# never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python. BWK awk's split() with
+# a one-character separator also splits on newlines, so split() is used here
+# only on a single line (a path, a TSV row).
+
+set -u
+# Byte semantics for awk, sort and tolower.
+LC_ALL=C
+export LC_ALL
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+usage() { echo "content-count: $1 (try --help)" >&2; exit 2; }
+TAB=$(printf '\t')
+
+CMD=""; ROOT_ARG=""; ENGINE_ARG=""; SHOWFILES=0; NPOS=0; P1=""; P2=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root) [ $# -ge 2 ] || usage "--root needs a value"; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --engine) [ $# -ge 2 ] || usage "--engine needs a name"; ENGINE_ARG="$2"; shift 2 ;;
+ --engine=*) ENGINE_ARG="${1#--engine=}"; shift ;;
+ --files) SHOWFILES=1; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) usage "unknown argument: $1" ;;
+ *)
+ if [ -z "$CMD" ]; then CMD="$1"
+ else
+ NPOS=$((NPOS + 1))
+ case $NPOS in 1) P1="$1" ;; 2) P2="$1" ;; *) usage "too many arguments" ;; esac
+ fi
+ shift ;;
+ esac
+done
+case "$CMD" in
+ registry|gap) [ $NPOS -eq 0 ] || usage "$CMD takes no arguments" ;;
+ found) [ $NPOS -eq 0 ] || usage "found takes no arguments" ;;
+ band) [ $NPOS -eq 2 ] || usage "band needs FOUND and SPECIFIED"
+ case "$P1$P2" in *[!0-9]*) usage "band takes whole numbers" ;; esac
+ [ -n "$P1" ] && [ -n "$P2" ] || usage "band takes whole numbers" ;;
+ "") usage "no command" ;;
+ *) usage "unknown command: $CMD" ;;
+esac
+[ "$CMD" = found ] || [ -z "$ENGINE_ARG" ] || usage "--engine belongs to found"
+[ "$CMD" = found ] || [ "$SHOWFILES" -eq 0 ] || usage "--files belongs to found"
+
+# The band and percentage arithmetic, shared by band and gap. All comparisons
+# cross-multiply whole numbers, so a value is never decided on a rounded one.
+AWK_LIB='
+ function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
+ # found as tenths of a percent of specified, truncated: 99/200 -> 49.5
+ function pct1(f, s, t) {
+ if (s == 0) return "-"
+ t = int(f * 1000 / s)
+ return sprintf("%d.%d", int(t / 10), t % 10)
+ }
+ # Sets BNAME and BRULE.
+ function band(f, s) {
+ if (s == 0) { BNAME = "-"; BRULE = "specified is 0: no percentage"; return }
+ if (f == 0) { BNAME = "NOT STARTED"; BRULE = "found = 0"; return }
+ if (f >= s) { BNAME = "COMPLETE"; BRULE = "found >= specified"; return }
+ if (f * 2 >= s) { BNAME = "IN PROGRESS"; BRULE = "50% <= found/specified < 100%"; return }
+ BNAME = "EARLY"; BRULE = "0 < found/specified < 50%"
+ }
+'
+
+if [ "$CMD" = band ]; then
+ F="$P1" S="$P2" awk "$AWK_LIB"'BEGIN {
+ f = ENVIRON["F"] + 0; s = ENVIRON["S"] + 0
+ band(f, s)
+ printf "band\t%d/%d\t%s\t%s\t%s\n", f, s, BNAME, pct1(f, s), BRULE
+ }'
+ exit 0
+fi
+
+if [ "$CMD" = gap ]; then
+ awk "$AWK_LIB"'
+ BEGIN { BINMODE = 3 }
+ {
+ line = $0; sub(/\r$/, "", line)
+ if (line == "") next
+ nread++
+ n = split(line, c, "\t")
+ sy = trim(c[1]); ty = trim(c[2]); sp = trim(c[3]); fo = trim(c[4])
+ if (n < 4) { ne++; ex[ne] = sy "\t" ty "\tfewer than 4 columns"; next }
+ if (sp !~ /^[0-9]+$/) { ne++; ex[ne] = sy "\t" ty "\tspecified is not a number: " sp; next }
+ if (fo !~ /^[0-9]+$/) { ne++; ex[ne] = sy "\t" ty "\tfound is not a number: " fo; next }
+ sp += 0; fo += 0
+ nc++
+ band(fo, sp)
+ sg = (sp > fo) ? sp - fo : 0
+ rows[nc] = sprintf("ROW\t%s\t%s\t%d\t%d\t%d\t%s\t%s\t%s", sy, ty, sp, fo, sg, pct1(fo, sp), BNAME, (BNAME == "-") ? "-" : ((BNAME == "EARLY" || BNAME == "NOT STARTED") ? "yes" : "no"))
+ ts += sp; tf += fo; ub += sg
+ if (!(sy in sysseen)) { sysseen[sy] = 1; nsys++ }
+ }
+ END {
+ printf "rows\t%d\t%d\nexcluded\t%d\n", nc, nread, ne
+ if (nc == 0) {
+ printf "total_specified\t-\ntotal_found\t-\ntotal_gap\t-\ngap_pct\t-\nunbuilt\t-\nunbuilt_pct\t-\nsystems\t0\n"
+ } else {
+ d = ts - tf
+ printf "total_specified\t%d\ntotal_found\t%d\ntotal_gap\t%d\n", ts, tf, d
+ if (ts == 0) printf "gap_pct\t-\n"
+ else if (d < 0) printf "gap_pct\t-%s\n", pct1(-d, ts)
+ else printf "gap_pct\t%s\n", pct1(d, ts)
+ printf "unbuilt\t%d\nunbuilt_pct\t%s\nsystems\t%d\n", ub, pct1(ub, ts), nsys
+ }
+ for (i = 1; i <= nc; i++) print rows[i]
+ for (i = 1; i <= ne; i++) printf "EXCLUDED\t%s\n", ex[i]
+ exit ((nc == 0) ? 3 : 0)
+ }
+ '
+ rc=$?
+ [ $rc -ne 3 ] || echo "content-count: no row with a specified and a found number" >&2
+ exit $rc
+fi
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "content-count: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "content-count: cannot reach the repo root" >&2; exit 1; }
+fi
+
+# ------------------------------------------------------------------- registry
+if [ "$CMD" = registry ]; then
+ [ -f "$HERE/registry.sh" ] || { echo "content-count: $HERE/registry.sh is missing" >&2; exit 1; }
+ OUT=$(bash "$HERE/registry.sh" --root . list entities 2>/dev/null); RC=$?
+ case $RC in 0|4) ;; *) echo "content-count: registry.sh list entities failed (exit $RC)" >&2; exit 1 ;; esac
+ printf '%s\n' "$OUT" | awk '
+ BEGIN { BINMODE = 3; FS = "\t" }
+ $1 == "registry" { rpath = $3; rstate = $4 }
+ $1 == "LAYOUT" { lay[++nlay] = $0 }
+ $1 == "ENTRY" && ($3 == "entities" || $3 == "items") {
+ sec = $3; nm = $5; stt = $6; src = $7
+ if (tolower(stt) == "deprecated") {
+ nskip++; rows[++nr] = "SKIPPED\t" sec "\t" nm "\t" src "\tdeprecated"
+ } else {
+ planned[sec]++; total++
+ rows[++nr] = "PLANNED\t" sec "\t" nm "\t" src
+ if (stt == "-") nostat++
+ else if (tolower(stt) != "active") {
+ nother++
+ if (!(stt in oseen)) { oseen[stt] = 1; olist = olist (olist == "" ? "" : ",") stt }
+ }
+ k = sec "\t" nm; nameN[k]++
+ if (nameN[k] == 2) ndup++
+ if (!(src in srcN)) so[++ns] = src
+ srcN[src]++
+ }
+ }
+ END {
+ printf "registry\t%s\t%s\n", (rpath == "") ? "design/registry/entities.yaml" : rpath, (rstate == "") ? "missing" : rstate
+ if (rstate == "layout") { for (i = 1; i <= nlay; i++) print lay[i]; exit 4 }
+ printf "planned\tentities\t%d\nplanned\titems\t%d\nplanned_total\t%d\n", planned["entities"], planned["items"], total
+ printf "deprecated_skipped\t%d\nno_status\t%d\nstatus_other\t%d\t%s\nduplicate_names\t%d\n", nskip, nostat, nother, (olist == "") ? "-" : olist, ndup
+ for (i = 2; i <= ns; i++) { x = so[i]; for (j = i - 1; j >= 1 && so[j] > x; j--) so[j + 1] = so[j]; so[j + 1] = x }
+ for (i = 1; i <= ns; i++) printf "source\t%s\t%d\n", so[i], srcN[so[i]]
+ for (i = 1; i <= nr; i++) print rows[i]
+ }
+ '
+ if [ "$RC" -eq 4 ]; then
+ echo "content-count: unsupported registry layout; the LAYOUT rows give each line and the layout expected there" >&2
+ exit 4
+ fi
+ exit 0
+fi
+
+# ---------------------------------------------------------------------- found
+if [ -n "$ENGINE_ARG" ]; then
+ RAW="$ENGINE_ARG"; ESRC="flag"
+else
+ # engine.name from project.local.yaml, then project.yaml, read by the shared
+ # yaml-get.awk as project-state.sh reads it (and much faster than running it);
+ # only when neither names one, project-state.sh's legacy fallback decides.
+ RAW=""; ESRC=""
+ [ -f "$HERE/yaml-get.awk" ] || { echo "content-count: $HERE/yaml-get.awk is missing; pass --engine" >&2; exit 1; }
+ for yf in project.local.yaml project.yaml; do
+ if [ -z "$RAW" ] && [ -f "$yf" ]; then
+ RAW=$(YG_PATH=engine.name awk -f "$HERE/yaml-get.awk" "$yf")
+ [ -z "$RAW" ] || ESRC="$yf"
+ fi
+ done
+ if [ -z "$RAW" ] && [ -f "$HERE/project-state.sh" ]; then
+ ROW=$(bash "$HERE/project-state.sh" --root . | awk -F'\t' '$1 == "engine" { print $2 "\t" $3 }')
+ RAW="${ROW%%"$TAB"*}"; ESRC="${ROW#*"$TAB"}"
+ fi
+fi
+if [ -z "$RAW" ] || [ "$RAW" = "-" ]; then
+ printf 'engine\t-\tunset\n'
+ echo "content-count: no engine is set (engine.name in project.yaml); pass --engine" >&2
+ exit 3
+fi
+LOW=$(printf '%s' "$RAW" | tr '[:upper:]' '[:lower:]')
+case "$LOW" in
+ godot) ENG=godot; ROOTS="assets src" ;;
+ unity) ENG=unity; ROOTS="assets Assets" ;;
+ unreal*) ENG=unreal; ROOTS="assets Content" ;;
+ *)
+ if [ "$ESRC" = flag ]; then usage "--engine takes godot, unity or unreal, got $RAW"; fi
+ printf 'engine\t%s\t%s\n' "$RAW" "$ESRC"
+ echo "content-count: engine $RAW has no content rules here (godot, unity or unreal)" >&2
+ exit 3 ;;
+esac
+printf 'engine\t%s\t%s\n' "$ENG" "$ESRC"
+
+PRESENT=""; NPRES=0
+for r in $ROOTS; do
+ # The exact name, from the listing: -d would say yes to Assets for a
+ # directory called assets on a case-insensitive disk.
+ if [ -n "$(find . -maxdepth 1 -type d -name "$r" 2>/dev/null)" ]; then
+ printf 'root\t%s\tpresent\n' "$r"; PRESENT="$PRESENT $r"; NPRES=$((NPRES + 1))
+ else
+ printf 'root\t%s\tabsent\n' "$r"
+ fi
+done
+LIST=""
+# shellcheck disable=SC2086
+[ -z "$PRESENT" ] || LIST=$(find $PRESENT -type f 2>/dev/null | sort)
+
+printf '%s\n' "$LIST" | ENG="$ENG" SHOWFILES="$SHOWFILES" awk '
+ BEGIN {
+ BINMODE = 3; eng = ENVIRON["ENG"]
+ ng = split("levels characters items abilities dialogue quests", G, " ")
+ nfl["levels"] = split("levels areas maps worlds stages", t1, " ")
+ nfl["characters"] = split("enemies characters npcs", t2, " ")
+ nfl["items"] = split("items equipment loot", t3, " ")
+ nfl["abilities"] = split("abilities skills spells", t4, " ")
+ nfl["dialogue"] = split(".dialogue .csv .ink", t5, " ")
+ nfl["quests"] = split("quests missions objectives", t6, " ")
+ for (i = 1; i <= 6; i++) { FL["levels", i] = t1[i]; FL["characters", i] = t2[i]; FL["items", i] = t3[i]
+ FL["abilities", i] = t4[i]; FL["dialogue", i] = t5[i]; FL["quests", i] = t6[i] }
+ if (eng == "unity") { nfl["items"]++; FL["items", nfl["items"]] = "*Item*.asset" }
+ }
+ # Is e one of the engine data extensions for type g.
+ function extok(g, e) {
+ if (eng == "unreal") return (e == "uasset")
+ if (eng == "unity") return (e == "json" || e == "yaml" || e == "asset" || e == "prefab")
+ if (g == "characters") return (e == "json" || e == "tres" || e == "asset" || e == "yaml" || e == "tscn" || e == "prefab")
+ if (g == "quests") return (e == "json" || e == "yaml")
+ return (e == "json" || e == "tres" || e == "asset")
+ }
+ function isfolder(g, name, i) {
+ for (i = 1; i <= nfl[g]; i++) if (FL[g, i] == name) return 1
+ return 0
+ }
+ NF > 0 {
+ p = $0; sub(/\r$/, "", p)
+ n = split(p, seg, "/")
+ if (n < 2) next
+ root = seg[1]; fname = seg[n]
+ ext = ""
+ if (match(fname, /\.[^.]*$/)) ext = tolower(substr(fname, RSTART + 1))
+ # The first folder to look in: under assets/ only below assets/data/.
+ first = 2; datalock = 0
+ if (root == "assets") { datalock = 1; first = (n >= 3 && tolower(seg[2]) == "data") ? 3 : n }
+ srcroot = (eng == "godot" && root == "src")
+ for (gi = 1; gi <= ng; gi++) {
+ g = G[gi]; hit = 0; nh = 0
+ if (g == "levels") {
+ sceneext = (eng == "godot") ? "tscn" : ((eng == "unity") ? "unity" : "umap")
+ if (ext != sceneext) continue
+ hit = 1
+ for (i = 2; i < n; i++) { w = tolower(seg[i]); if (isfolder(g, w) && !(w in hs)) { hs[w] = 1; hn[++nh] = w } }
+ } else if (g == "dialogue") {
+ if (srcroot) continue
+ if (ext != "dialogue" && ext != "csv" && ext != "ink") continue
+ hit = 1; hn[++nh] = "." ext
+ } else {
+ if (srcroot && g != "characters") continue
+ if (extok(g, ext)) {
+ for (i = first; i < n; i++) { w = tolower(seg[i]); if (isfolder(g, w) && !(w in hs)) { hs[w] = 1; hn[++nh] = w; hit = 1 } }
+ }
+ if (eng == "unity" && g == "items" && root == "Assets" && ext == "asset" && index(fname, "Item") > 0) { hit = 1; hn[++nh] = "*Item*.asset" }
+ }
+ if (hit) {
+ tot[g]++
+ for (i = 1; i <= nh; i++) by[g, hn[i]]++
+ if (ENVIRON["SHOWFILES"] == "1") frow[++nfr] = "FILE\t" g "\t" p
+ }
+ for (i = 1; i <= nh; i++) delete hs[hn[i]]
+ }
+ }
+ END {
+ for (gi = 1; gi <= ng; gi++) printf "found\t%s\t%d\n", G[gi], tot[G[gi]]
+ for (gi = 1; gi <= ng; gi++) {
+ g = G[gi]
+ for (i = 1; i <= nfl[g]; i++) printf "by\t%s\t%s\t%d\n", g, FL[g, i], by[g, FL[g, i]]
+ }
+ for (i = 1; i <= nfr; i++) print frow[i]
+ }
+'
+if [ "$NPRES" -eq 0 ]; then
+ echo "content-count: none of the roots ($ROOTS) exists; nothing was scanned" >&2
+ exit 4
+fi
+exit 0
diff --git a/.claude/scripts/debt-register.sh b/.claude/scripts/debt-register.sh
new file mode 100644
index 00000000..bef3500a
--- /dev/null
+++ b/.claude/scripts/debt-register.sh
@@ -0,0 +1,467 @@
+#!/usr/bin/env bash
+# debt-register.sh — the technical-debt register's arithmetic: the next TD ID,
+# the impact / effort score, open items per category, items added and resolved
+# in a window, item ages, and the Open entries that already cover a file and a
+# category, read from docs/tech-debt-register.md, so one table is read instead
+# of counting rows by hand.
+#
+# Replaces the register steps a skill would otherwise do by hand: numbering a
+# new entry, scoring and prioritizing, reporting, and the "match before
+# appending" check.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# stats prints added and resolved counts and their difference, not the words
+# growing, stable or shrinking; ages are in days, because the register records
+# dates, not sprints. What "more than 3 sprints" is in days, and which items
+# go in the next sprint, stay in the skill.
+#
+# Usage: bash .claude/scripts/debt-register.sh [--root DIR] COMMAND [ARGS]
+# next-id the next TD ID: registry.sh's `next-id td`, passed
+# through unchanged (the one ID rule in the codebase)
+# score IMPACT EFFORT the score of one pair: Low, Med (Medium), High or
+# Critical over S, M, L or XL, any case; - or an em
+# dash means not judged and gives no score
+# score every item of the register scored from its own
+# columns, in the order /tech-debt prioritize writes
+# stats [--today D] [--since D] [--until D] [--older-than N]
+# open items per category, added and resolved in the
+# window --since..--until (both days included; --until
+# defaults to --today), and the age of each open item
+# match --file PATH [--category CAT]
+# the Open entries whose Files list PATH, and whose
+# category is CAT when given (Debt dropped, any case)
+# --register PATH the register, relative to the root or absolute
+# (default docs/tech-debt-register.md); not for
+# next-id
+# --root DIR the project; defaults to the repo this script is in
+# --today D the date ages count to (default: today)
+# -h, --help this text
+# Dates are YYYY-MM-DD.
+#
+# What it reads (the format /tech-debt writes): the Markdown table whose header
+# row starts with ID. Columns are found by their header name (ID, Category,
+# Description, Files, Effort, Impact, Priority, Status, Added, Sprint), so a
+# register with the columns in another order, or some missing, still reads; a
+# missing column reads as -. A table row starting TD-n whose cell count is not
+# the header's is reported as MALFORMED and left out. A \| inside a cell is a
+# pipe. Category: the six names, with or without a trailing "Debt", any case.
+# Status: Open, Resolved YYYY-MM-DD, Accepted - reason (anything else is
+# other_status); the date of a Resolved item is the first date in its Status.
+#
+# The score (the skill's rule, with the rounding it left out):
+# score = impact / effort, Impact Low 1, Med 2, High 3, Critical 4; Effort S 1,
+# M 2, L 3, XL 4. Rounded to one decimal, a half rounding UP: Low/XL 0.25 is
+# 0.3 and High/XL 0.75 is 0.8 (printf alone would give 0.2, rounding to even).
+# Done in whole numbers: tenths = floor((20 * impact + effort) / (2 * effort)).
+# Order (register mode): higher score first, ties to the older Added date
+# (an undated item last), then register order; the order is of the
+# one-decimal scores, because the one-decimal score is what the register
+# shows. Items with no score follow, in register order, with the reason.
+#
+# Output: TSV. Every register command starts:
+# register <path> <items> items = rows read (malformed ones left out)
+# columns <names found, in header order, comma-joined | ->
+# items <n>, duplicate_ids <n>, malformed <n>
+# MALFORMED <line> <cells> <expected> <id>
+# DUPLICATE_ID <id> <lines>
+# score IMPACT EFFORT: score <value | -> <Impact>/<Effort> <i/e | reason>
+# score (register): scored <n>, not_scored <n>, open_ranked <n>, then
+# ROW <rank | -> <id> <score | -> <impact> <effort> <priority as written>
+# <added> <state> <reason | ->
+# state is OPEN, RESOLVED, ACCEPTED or OTHER; rank counts the scored OPEN
+# items only, in the printed order; rows are in that order
+# stats: open, resolved, accepted, other_status, today,
+# window <since | -> <until | ->, added_in_window, resolved_in_window,
+# net_in_window (added - resolved; - with no window), undated <added>
+# <resolved> (rows whose date could not be read), older_than <N | -> <count>,
+# category <name> <open> <S> <M> <L> <XL> <none> <other> (the six names, then
+# any other, sorted; none = Effort not judged, other = a word that is not
+# S, M, L or XL), effort_open (the same columns summed), then
+# OPEN <id> <category> <effort> <impact> <priority> <added> <age_days>
+# <sprint> <older> older is yes or no against --older-than (strictly
+# more than N days), - when not asked or no date
+# match: register <path> <items>, matches <n> file=<path> category=<cat|any>,
+# MATCH <id> <line> <category> <status> <files>
+# `-` means not there.
+#
+# Exit codes: 0 answered; 1 the root cannot be read, or registry.sh is missing;
+# 2 usage error (an unknown command or flag, a bad date or number, --until
+# without --since, a reversed window, an impact or effort that is not one);
+# 3 no register file (stats, score, match; its register row is printed).
+# next-id passes registry.sh's own codes through. Reads only; never writes,
+# never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python. BWK awk's split() with
+# a one-character separator also splits on newlines, so split() is used here
+# only on a single line (a table row, a Files cell).
+
+set -u
+# Byte semantics for awk, sort and tolower.
+LC_ALL=C
+export LC_ALL
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+usage() { echo "debt-register: $1 (try --help)" >&2; exit 2; }
+is_date() { case "$1" in [0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]) return 0 ;; esac; return 1; }
+# An em dash and an en dash, as bytes: the "not judged" marks of the register.
+EMD=$(printf '\342\200\224'); END_=$(printf '\342\200\223')
+
+CMD=""; ROOT_ARG=""; REG="docs/tech-debt-register.md"; REG_SET=0; TODAY=""
+SINCE=""; UNTIL=""; OLDER=""; FILEARG=""; CATARG=""; NPOS=0; P1=""; P2=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root) [ $# -ge 2 ] || usage "--root needs a value"; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --register) [ $# -ge 2 ] || usage "--register needs a path"; REG="$2"; REG_SET=1; shift 2 ;;
+ --today) [ $# -ge 2 ] || usage "--today needs a date"; TODAY="$2"; shift 2 ;;
+ --today=*) TODAY="${1#--today=}"; shift ;;
+ --since) [ $# -ge 2 ] || usage "--since needs a date"; SINCE="$2"; shift 2 ;;
+ --until) [ $# -ge 2 ] || usage "--until needs a date"; UNTIL="$2"; shift 2 ;;
+ --older-than) [ $# -ge 2 ] || usage "--older-than needs a number of days"; OLDER="$2"; shift 2 ;;
+ --file) [ $# -ge 2 ] || usage "--file needs a path"; FILEARG="$2"; shift 2 ;;
+ --category) [ $# -ge 2 ] || usage "--category needs a name"; CATARG="$2"; shift 2 ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) usage "unknown argument: $1" ;;
+ *)
+ if [ -z "$CMD" ]; then CMD="$1"
+ else
+ NPOS=$((NPOS + 1))
+ case $NPOS in 1) P1="$1" ;; 2) P2="$1" ;; *) usage "too many arguments" ;; esac
+ fi
+ shift ;;
+ esac
+done
+case "$CMD" in
+ next-id) [ $NPOS -eq 0 ] || usage "next-id takes no arguments"
+ [ $REG_SET -eq 0 ] || usage "next-id reads the register registry.sh knows; --register does not apply" ;;
+ score) [ $NPOS -eq 0 ] || [ $NPOS -eq 2 ] || usage "score takes IMPACT and EFFORT, or nothing" ;;
+ stats|match) [ $NPOS -eq 0 ] || usage "$CMD takes no arguments" ;;
+ "") usage "no command" ;;
+ *) usage "unknown command: $CMD" ;;
+esac
+[ -n "$TODAY" ] || TODAY=$(date +%Y-%m-%d)
+is_date "$TODAY" || usage "--today must be YYYY-MM-DD, got $TODAY"
+if [ -n "$SINCE" ] || [ -n "$UNTIL" ]; then
+ [ "$CMD" = stats ] || usage "--since and --until belong to stats"
+ [ -n "$SINCE" ] || usage "--until needs --since"
+ is_date "$SINCE" || usage "--since must be YYYY-MM-DD, got $SINCE"
+ [ -n "$UNTIL" ] || UNTIL="$TODAY"
+ is_date "$UNTIL" || usage "--until must be YYYY-MM-DD, got $UNTIL"
+ if [[ "$SINCE" > "$UNTIL" ]]; then usage "--since $SINCE is after --until $UNTIL"; fi
+fi
+if [ -n "$OLDER" ]; then
+ [ "$CMD" = stats ] || usage "--older-than belongs to stats"
+ case "$OLDER" in ''|*[!0-9]*) usage "--older-than takes a whole number of days" ;; esac
+fi
+if [ "$CMD" = match ]; then
+ [ -n "$FILEARG" ] || usage "match needs --file"
+elif [ -n "$FILEARG$CATARG" ]; then
+ usage "--file and --category belong to match"
+fi
+
+AWK_LIB='
+ function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
+ # An empty cell, -, -- , an em dash or an en dash: not judged.
+ function isdash(s) { return (s == "" || s == "-" || s == "--" || s == "\342\200\224" || s == "\342\200\223") }
+ function v(s) { gsub(/\t/, " ", s); return isdash(s) ? "-" : s }
+ function impact_n(s, l) {
+ l = tolower(s)
+ if (l == "low") return 1
+ if (l == "med" || l == "medium") return 2
+ if (l == "high") return 3
+ if (l == "critical") return 4
+ return 0
+ }
+ function impact_name(n) { return (n == 1) ? "Low" : ((n == 2) ? "Med" : ((n == 3) ? "High" : "Critical")) }
+ function effort_n(s, u) {
+ u = toupper(s)
+ if (u == "S") return 1
+ if (u == "M") return 2
+ if (u == "L") return 3
+ if (u == "XL") return 4
+ return 0
+ }
+ function effort_name(n) { return (n == 1) ? "S" : ((n == 2) ? "M" : ((n == 3) ? "L" : "XL")) }
+ # Tenths of a score, a half rounding up, in whole numbers.
+ function score10(i, e) { return int((20 * i + e) / (2 * e)) }
+ function fmt10(t) { return sprintf("%d.%d", int(t / 10), t % 10) }
+ # The category as the six names without "Debt", any case; anything else as written.
+ function canon_cat(s, l) {
+ l = tolower(trim(s)); sub(/ debt$/, "", l)
+ if (l == "architecture") return "Architecture"
+ if (l == "code quality") return "Code Quality"
+ if (l == "test") return "Test"
+ if (l == "documentation") return "Documentation"
+ if (l == "dependency") return "Dependency"
+ if (l == "performance") return "Performance"
+ s = trim(s)
+ return (s == "") ? "-" : s
+ }
+ # Days since a fixed origin for the Gregorian date y-m-d. Only differences are
+ # used. The year is counted from March, so a leap day falls at the end of it.
+ function days(d, p) {
+ split(d, p, "-")
+ return dn(p[1] + 0, p[2] + 0, p[3] + 0)
+ }
+ function dn(y, m, d) {
+ if (m <= 2) { y--; m += 12 }
+ return 365 * y + int(y / 4) - int(y / 100) + int(y / 400) + int((153 * (m - 3) + 2) / 5) + d
+ }
+ function firstdate(s) {
+ return match(s, /[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/) ? substr(s, RSTART, RLENGTH) : ""
+ }
+ # A path from a Files cell or --file: no backticks, no leading ./
+ function normpath(s) {
+ gsub(/`/, "", s); s = trim(s)
+ if (substr(s, 1, 2) == "./") s = substr(s, 3)
+ return s
+ }
+'
+
+# ----------------------------------------------------------------- score pair
+# lc STRING — lower case. impact_n and effort_n print 1-4, or 0 for a word
+# that is not one.
+lc() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
+impact_n() { case "$(lc "$1")" in low) echo 1 ;; med|medium) echo 2 ;; high) echo 3 ;; critical) echo 4 ;; *) echo 0 ;; esac; }
+effort_n() { case "$(lc "$1")" in s) echo 1 ;; m) echo 2 ;; l) echo 3 ;; xl) echo 4 ;; *) echo 0 ;; esac; }
+impact_name() { case "$1" in 1) echo Low ;; 2) echo Med ;; 3) echo High ;; 4) echo Critical ;; esac; }
+effort_name() { case "$1" in 1) echo S ;; 2) echo M ;; 3) echo L ;; 4) echo XL ;; esac; }
+not_judged() { case "$1" in ""|-|--|"$EMD"|"$END_") return 0 ;; esac; return 1; }
+
+if [ "$CMD" = score ] && [ $NPOS -eq 2 ]; then
+ ij=1; ej=1; iname="-"; ename="-"; in_=0; en=0
+ if not_judged "$P1"; then ij=0; else
+ in_=$(impact_n "$P1"); [ "$in_" != 0 ] || usage "not an impact (Low, Med, High, Critical): $P1"
+ iname=$(impact_name "$in_")
+ fi
+ if not_judged "$P2"; then ej=0; else
+ en=$(effort_n "$P2"); [ "$en" != 0 ] || usage "not an effort (S, M, L, XL): $P2"
+ ename=$(effort_name "$en")
+ fi
+ if [ $ij -eq 1 ] && [ $ej -eq 1 ]; then
+ # The same score10 and fmt10 the register mode uses: one rounding rule.
+ val=$(IN="$in_" EN="$en" awk "$AWK_LIB"'BEGIN { print fmt10(score10(ENVIRON["IN"] + 0, ENVIRON["EN"] + 0)) }')
+ printf 'score\t%s\t%s/%s\t%d/%d\n' "$val" "$iname" "$ename" "$in_" "$en"
+ elif [ $ij -eq 0 ] && [ $ej -eq 0 ]; then
+ printf 'score\t-\t%s/%s\timpact and effort not judged\n' "$iname" "$ename"
+ elif [ $ij -eq 0 ]; then
+ printf 'score\t-\t%s/%s\timpact not judged\n' "$iname" "$ename"
+ else
+ printf 'score\t-\t%s/%s\teffort not judged\n' "$iname" "$ename"
+ fi
+ exit 0
+fi
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "debt-register: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "debt-register: cannot reach the repo root" >&2; exit 1; }
+fi
+
+if [ "$CMD" = next-id ]; then
+ [ -f "$HERE/registry.sh" ] || { echo "debt-register: $HERE/registry.sh is missing" >&2; exit 1; }
+ bash "$HERE/registry.sh" --root . next-id td
+ exit $?
+fi
+
+if [ ! -f "$REG" ]; then
+ printf 'register\t%s\tmissing\n' "$REG"
+ echo "debt-register: no register at $REG" >&2
+ exit 3
+fi
+# awk reads the register by name: "./" in front of a relative one keeps a name
+# like x=1.md from reading as an assignment; an absolute one is opened as it is.
+case "$REG" in /*|[A-Za-z]:*) REG_IN="$REG" ;; *) REG_IN="./$REG" ;; esac
+
+CMD="$CMD" REGPATH="$REG" TODAY="$TODAY" SINCE="$SINCE" UNTIL="$UNTIL" OLDER="$OLDER" \
+FILEARG="$FILEARG" CATARG="$CATARG" awk "$AWK_LIB"'
+ BEGIN {
+ BINMODE = 3
+ cmd = ENVIRON["CMD"]; ncol = 0; hdr = 0; SEP = "\001"
+ nk = split("id category description files effort impact priority status added sprint", KEYS, " ")
+ split("ID Category Description Files Effort Impact Priority Status Added Sprint", NAMES, " ")
+ for (i = 1; i <= nk; i++) NAME[KEYS[i]] = NAMES[i]
+ }
+ function header(n, i, k) {
+ ncol = n; hdr = 1; colslist = ""
+ for (k in ci) delete ci[k]
+ for (i = 1; i <= n; i++) {
+ k = tolower(c[i])
+ if (k in NAME) { ci[k] = i; colslist = colslist (colslist == "" ? "" : ",") NAME[k] }
+ }
+ }
+ function get(k) { return (k in ci) ? c[ci[k]] : "" }
+ FNR >= 1 {
+ line = $0; sub(/\r$/, "", line)
+ if (FNR == 1 && substr(line, 1, 3) == "\357\273\277") line = substr(line, 4)
+ if (line !~ /^[ \t]*\|/) next
+ t = line
+ while ((p = index(t, "\\|")) > 0) t = substr(t, 1, p - 1) SEP substr(t, p + 2)
+ sub(/^[ \t]*\|/, "", t); sub(/\|[ \t]*$/, "", t)
+ n = split(t, c, "|")
+ sepr = 1
+ for (i = 1; i <= n; i++) {
+ c[i] = trim(c[i])
+ while ((p = index(c[i], SEP)) > 0) c[i] = substr(c[i], 1, p - 1) "|" substr(c[i], p + 1)
+ if (c[i] !~ /^:?-+:?$/) sepr = 0
+ }
+ if (sepr) next
+ if (tolower(c[1]) == "id") { header(n); next }
+ if (c[1] !~ /^TD-[0-9]+$/) next
+ if (!hdr) {
+ # No header before the first row: the ten columns in the order /tech-debt writes.
+ ncol = 10; hdr = 1; colslist = ""
+ for (i = 1; i <= nk; i++) { ci[KEYS[i]] = i; colslist = colslist (i == 1 ? "" : ",") NAMES[i] }
+ }
+ if (n != ncol) { nmal++; MR[nmal] = FNR "\t" n "\t" ncol "\t" c[1]; next }
+ ni++
+ id[ni] = c[1]; ln[ni] = FNR
+ idc[c[1]]++; idl[c[1]] = idl[c[1]] (idl[c[1]] == "" ? "" : ",") FNR
+ if (idc[c[1]] == 2) { ndup++; dupo[ndup] = c[1] }
+ cat[ni] = canon_cat(get("category")); eff[ni] = get("effort"); imp[ni] = get("impact")
+ pri[ni] = get("priority"); sta[ni] = get("status"); add[ni] = get("added")
+ spr[ni] = get("sprint"); fil[ni] = get("files")
+ low = tolower(sta[ni])
+ if (low ~ /^open([^a-z]|$)/) st[ni] = "OPEN"
+ else if (low ~ /^resolved([^a-z]|$)/) st[ni] = "RESOLVED"
+ else if (low ~ /^accepted([^a-z]|$)/) st[ni] = "ACCEPTED"
+ else st[ni] = "OTHER"
+ ad[ni] = firstdate(add[ni])
+ rd[ni] = (st[ni] == "RESOLVED") ? firstdate(sta[ni]) : ""
+ }
+
+ # Does item a come before item b (score order, a strict total order).
+ function dkey(k) { return (ad[k] == "") ? "9999-99-99" : ad[k] }
+ function before(a, b) {
+ if ((sc[a] >= 0) != (sc[b] >= 0)) return (sc[a] >= 0)
+ if (sc[a] >= 0) {
+ if (sc[a] != sc[b]) return (sc[a] > sc[b])
+ if (dkey(a) != dkey(b)) return (dkey(a) < dkey(b))
+ }
+ return (a < b)
+ }
+ function common( i) {
+ printf "register\t%s\t%d\n", ENVIRON["REGPATH"], ni
+ if (cmd == "match") return
+ printf "columns\t%s\n", (colslist == "") ? "-" : colslist
+ printf "items\t%d\nduplicate_ids\t%d\nmalformed\t%d\n", ni, ndup, nmal
+ for (i = 1; i <= nmal; i++) printf "MALFORMED\t%s\n", MR[i]
+ for (i = 1; i <= ndup; i++) printf "DUPLICATE_ID\t%s\t%s\n", dupo[i], idl[dupo[i]]
+ }
+
+ END {
+ common()
+ if (cmd == "score") {
+ for (k = 1; k <= ni; k++) {
+ ij = isdash(imp[k]) ? 0 : 1; ej = isdash(eff[k]) ? 0 : 1
+ in_ = ij ? impact_n(imp[k]) : 0; en = ej ? effort_n(eff[k]) : 0
+ rs = ""
+ if (!ij && !ej) rs = "impact and effort not judged"
+ else {
+ if (!ij) rs = "impact not judged"
+ else if (in_ == 0) rs = "impact unrecognised: " v(imp[k])
+ if (!ej) rs = rs (rs == "" ? "" : "; ") "effort not judged"
+ else if (en == 0) rs = rs (rs == "" ? "" : "; ") "effort unrecognised: " v(eff[k])
+ }
+ reason[k] = (rs == "") ? "-" : rs
+ sc[k] = (rs == "") ? score10(in_, en) : -1
+ iname[k] = ij ? ((in_ > 0) ? impact_name(in_) : v(imp[k])) : "-"
+ ename[k] = ej ? ((en > 0) ? effort_name(en) : v(eff[k])) : "-"
+ srt[k] = k
+ if (sc[k] >= 0) nscored++
+ }
+ for (i = 2; i <= ni; i++) {
+ x = srt[i]
+ for (j = i - 1; j >= 1 && before(x, srt[j]); j--) srt[j + 1] = srt[j]
+ srt[j + 1] = x
+ }
+ for (i = 1; i <= ni; i++) { k = srt[i]; if (st[k] == "OPEN" && sc[k] >= 0) rank[k] = ++nrank }
+ printf "scored\t%d\nnot_scored\t%d\nopen_ranked\t%d\n", nscored, ni - nscored, nrank
+ for (i = 1; i <= ni; i++) {
+ k = srt[i]
+ printf "ROW\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n", (k in rank) ? rank[k] : "-", id[k], (sc[k] >= 0) ? fmt10(sc[k]) : "-", \
+ iname[k], ename[k], v(pri[k]), (ad[k] != "") ? ad[k] : v(add[k]), st[k], reason[k]
+ }
+ exit 0
+ }
+
+ if (cmd == "stats") {
+ today = ENVIRON["TODAY"]; since = ENVIRON["SINCE"]; until = ENVIRON["UNTIL"]; older = ENVIRON["OLDER"]
+ for (k = 1; k <= ni; k++) {
+ if (st[k] == "OPEN") nopen++
+ else if (st[k] == "RESOLVED") nres++
+ else if (st[k] == "ACCEPTED") nacc++
+ else noth++
+ if (ad[k] == "") undadd++
+ if (st[k] == "RESOLVED" && rd[k] == "") undres++
+ if (since != "") {
+ if (ad[k] != "" && ad[k] >= since && ad[k] <= until) nadd++
+ if (rd[k] != "" && rd[k] >= since && rd[k] <= until) nresw++
+ }
+ }
+ printf "open\t%d\nresolved\t%d\naccepted\t%d\nother_status\t%d\ntoday\t%s\n", nopen, nres, nacc, noth, today
+ if (since != "") {
+ printf "window\t%s\t%s\nadded_in_window\t%d\nresolved_in_window\t%d\nnet_in_window\t%d\n", since, until, nadd, nresw, nadd - nresw
+ } else {
+ printf "window\t-\t-\nadded_in_window\t-\nresolved_in_window\t-\nnet_in_window\t-\n"
+ }
+ printf "undated\t%d\t%d\n", undadd, undres
+ td = days(today)
+ for (k = 1; k <= ni; k++) {
+ age[k] = (ad[k] != "") ? td - days(ad[k]) : "-"
+ old[k] = (older != "" && age[k] != "-") ? ((age[k] > older + 0) ? "yes" : "no") : "-"
+ if (old[k] == "yes" && st[k] == "OPEN") nold++
+ }
+ if (older != "") printf "older_than\t%s\t%d\n", older, nold
+ else printf "older_than\t-\t-\n"
+ # Categories: the six in the skill order, then any other, sorted.
+ split("Architecture|Code Quality|Test|Documentation|Dependency|Performance", six, "|")
+ nc = 0
+ for (i = 1; i <= 6; i++) { cn[++nc] = six[i]; known[six[i]] = 1 }
+ no = 0
+ for (k = 1; k <= ni; k++) if (!(cat[k] in known) && !(cat[k] in extra)) { extra[cat[k]] = 1; ox[++no] = cat[k] }
+ for (i = 2; i <= no; i++) { x = ox[i]; for (j = i - 1; j >= 1 && ox[j] > x; j--) ox[j + 1] = ox[j]; ox[j + 1] = x }
+ for (i = 1; i <= no; i++) cn[++nc] = ox[i]
+ for (k = 1; k <= ni; k++) {
+ if (st[k] != "OPEN") continue
+ co[cat[k]]++
+ e = isdash(eff[k]) ? 0 : effort_n(eff[k])
+ b = (e > 0) ? effort_name(e) : (isdash(eff[k]) ? "none" : "other")
+ cb[cat[k], b]++; tb[b]++
+ }
+ split("S M L XL none other", bk, " ")
+ for (i = 1; i <= nc; i++) {
+ printf "category\t%s\t%d", cn[i], co[cn[i]]
+ for (j = 1; j <= 6; j++) printf "\t%d", cb[cn[i], bk[j]]
+ printf "\n"
+ }
+ printf "effort_open"
+ for (j = 1; j <= 6; j++) printf "\t%d", tb[bk[j]]
+ printf "\n"
+ for (k = 1; k <= ni; k++) {
+ if (st[k] != "OPEN") continue
+ e = isdash(eff[k]) ? 0 : effort_n(eff[k]); ii = isdash(imp[k]) ? 0 : impact_n(imp[k])
+ printf "OPEN\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n", id[k], cat[k], (e > 0) ? effort_name(e) : v(eff[k]), \
+ (ii > 0) ? impact_name(ii) : v(imp[k]), v(pri[k]), (ad[k] != "") ? ad[k] : v(add[k]), age[k], v(spr[k]), old[k]
+ }
+ exit 0
+ }
+
+ # match
+ want = normpath(ENVIRON["FILEARG"]); wc = ENVIRON["CATARG"]
+ if (wc != "") wc = canon_cat(wc)
+ nm = 0
+ for (k = 1; k <= ni; k++) {
+ if (st[k] != "OPEN") continue
+ if (wc != "" && cat[k] != wc) continue
+ nf = split(fil[k], fp, ",")
+ hit = 0
+ for (j = 1; j <= nf; j++) if (normpath(fp[j]) == want) hit = 1
+ if (hit) { nm++; mrow[nm] = sprintf("MATCH\t%s\t%d\t%s\t%s\t%s", id[k], ln[k], cat[k], v(sta[k]), v(fil[k])) }
+ }
+ printf "matches\t%d\tfile=%s category=%s\n", nm, want, (wc == "") ? "any" : wc
+ for (i = 1; i <= nm; i++) print mrow[i]
+ exit 0
+ }
+' "$REG_IN"
+exit $?
diff --git a/.claude/scripts/flaky-stats.sh b/.claude/scripts/flaky-stats.sh
new file mode 100644
index 00000000..dc37f125
--- /dev/null
+++ b/.claude/scripts/flaky-stats.sh
@@ -0,0 +1,405 @@
+#!/usr/bin/env bash
+# flaky-stats.sh — per-test runs, passes, fails, skips, fail percentage and
+# pass/fail pattern across several test runs, with the threshold row each
+# test's rate fell in, read from the result files and logs /test-flakiness
+# parses, so one table replaces grepping every log by hand.
+#
+# Replaces the hand-run parse and tiering of a flakiness review, and the
+# "which tests failed in which runs" counting done from the same logs.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# The tier row (high, moderate, low, below-low, suspected, always-fail) is the
+# rule that matched, printed with its text. Whether to quarantine, what to tell
+# the user and what "confirmed" means stay in the skill.
+#
+# Usage: bash .claude/scripts/flaky-stats.sh [--root DIR] [--format F] [--runs] [--all] [FILE ...]
+# FILE one test run per file, in run order (the order of the pattern);
+# relative to the root. With none, the files under test-results/,
+# reports/ and Saved/Logs/ named *.xml, *.log or *.txt, sorted by
+# path: pass the files yourself when their names do not sort in
+# run order
+# --format F auto (default: found per file), junit, nunit, unreal or text
+# --runs also print one RUN row per file
+# --all also list tests with no fail and no skip (default: only tests
+# with at least one fail or skip are listed; the rest are counted)
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+#
+# What it parses (one result per test case, in file order):
+# junit gdUnit4's JUnit XML: each <testcase>; id is classname.name (name
+# alone when there is no classname); a <failure> or <error> inside it
+# is a fail, else <skipped> is a skip, else a pass
+# nunit Unity's NUnit XML: each <test-case>; id is its fullname (name when
+# none); result Passed is a pass, Failed a fail, and every other
+# value (Inconclusive, Skipped) a skip, so only Passed and Failed
+# enter the history, as /test-flakiness says
+# unreal lines holding "Test Completed. Result={W}": Success is a pass, Fail
+# a fail, any other word a skip and listed as `unrecognised`; id is
+# Path={...}, else Name={...}; a result with neither is counted as
+# no_id and kept out of the tests
+# text a line with PASSED or FAILED as a whole word (Godot), or Test passed
+# or Test failed (Unity): the id is the line without the marker, a
+# leading ISO timestamp, ANSI colour codes, timing words like 12ms or
+# (0.5s), and the punctuation [](): > | * - , around it. A line with
+# more than one marker (a summary) is not a result
+# CDATA sections and comments are skipped, XML entities in ids are decoded, a
+# tag may run over several lines.
+#
+# Output: TSV. Counts first, then rows:
+# scan <dir> <present|absent> per default folder (only when no FILE given)
+# runs <analysed> <read> files holding at least one result, files read
+# tests <n> distinct test ids
+# clean <n> <rule> tests with a counted result and no fail
+# flaky <n> <rule> tests with both a pass and a fail
+# tier <name> <n> <rule> high, moderate, low, below-low, suspected
+# always_fail <n> <rule> tests with a fail and no pass
+# no_result <n> <rule> tests with only skips
+# data_note <text | -> "fewer than 5 runs" when analysed < 5
+# no_id <n> results with no test name, kept out
+# unrecognised <format> <word> <n> result words the skill does not name
+# RUN <n> <path> <format> <results> <pass> <fail> <skip> <no_id> (--runs)
+# TEST <id> <runs> <pass> <fail> <skip> <fail_pct> <pattern> <flaky> <tier> <rule>
+# runs = pass + fail (skips are not runs); fail_pct = fail / runs,
+# truncated (not rounded) to one decimal so a printed value never sits
+# on the far side of a tier edge, or - when runs is 0; pattern = P, F or
+# S per result in file order; tier = the name above, or none (no fail) or
+# no-result; rows sorted by fail rate, highest first, then by id
+#
+# The tiers, with every edge in exactly one (the skill's text puts 5% in two
+# and says nothing below 1%). fail_pct is the exact ratio, not the printed one:
+# fail_pct > 25 high (the skill's ">25%")
+# 5 <= fail_pct <= 25 moderate (the skill's "5-25%"; 5 and 25 here)
+# 1 <= fail_pct < 5 low (the skill's "1-5%"; 1 here, 5 is moderate)
+# 0 < fail_pct < 1 below-low (named; the skill gives it no tier)
+# and before the tiers:
+# no pass, at least one fail always-fail (the skill leaves it unclassified;
+# by its own definition it is not flaky)
+# a pass and a fail, but fewer than 3 runs suspected (the skill: "with
+# fewer than 3 runs every finding is suspected"; counted per test, as the
+# skill's own example reasons from one test's data points)
+#
+# Exit codes: 0 parsed at least one result; 1 the root cannot be read; 2 usage
+# error; 3 no files to read (none given and none found, or a named file is
+# missing); 4 files were read and held no result. Reads only; never writes,
+# never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python. BWK awk's split() with
+# a one-character separator also splits on newlines, so split() is used here
+# only on a single line.
+
+set -u
+# Byte semantics for awk, sort and tolower.
+LC_ALL=C
+export LC_ALL
+
+ROOT_ARG=""; FORMAT="auto"; SHOWRUNS=0; ALL=0; FILES=""
+NL='
+'
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root) [ $# -ge 2 ] || { echo "flaky-stats: --root needs a value" >&2; exit 2; }; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --format) [ $# -ge 2 ] || { echo "flaky-stats: --format needs a value" >&2; exit 2; }; FORMAT="$2"; shift 2 ;;
+ --format=*) FORMAT="${1#--format=}"; shift ;;
+ --runs) SHOWRUNS=1; shift ;;
+ --all) ALL=1; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) echo "flaky-stats: unknown argument: $1 (try --help)" >&2; exit 2 ;;
+ *) FILES="$FILES${1#./}$NL"; shift ;;
+ esac
+done
+case "$FORMAT" in
+ auto|junit|nunit|unreal|text) ;;
+ *) echo "flaky-stats: --format takes auto, junit, nunit, unreal or text, got $FORMAT" >&2; exit 2 ;;
+esac
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "flaky-stats: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$(dirname "$0")/../.." 2>/dev/null || { echo "flaky-stats: cannot reach the repo root" >&2; exit 1; }
+fi
+
+if [ -z "$FILES" ]; then
+ # The folders the skill names: gdUnit4's reports/, the game-ci and saved
+ # test-results/, and Unreal's Saved/Logs/.
+ for d in test-results reports Saved/Logs; do
+ if [ -d "$d" ]; then
+ printf 'scan\t%s\tpresent\n' "$d"
+ FILES="$FILES$(find "$d" -type f \( -name '*.xml' -o -name '*.log' -o -name '*.txt' \) 2>/dev/null)$NL"
+ else
+ printf 'scan\t%s\tabsent\n' "$d"
+ fi
+ done
+ FILES=$(printf '%s' "$FILES" | awk 'NF' | sort -u)
+ if [ -z "$FILES" ]; then
+ echo "flaky-stats: no test result files under test-results/, reports/ or Saved/Logs/; name the files" >&2
+ exit 3
+ fi
+else
+ FILES=$(printf '%s' "$FILES" | awk 'NF')
+ while IFS= read -r f; do
+ [ -f "$f" ] || { echo "flaky-stats: no such file: $f" >&2; exit 3; }
+ done <<EOF
+$FILES
+EOF
+fi
+
+# The file list goes to awk on stdin, never as arguments (a long list passes
+# the command-line limit of some systems); each file gets "./" in front so a
+# name like x=1.log is not read as an awk assignment.
+printf '%s\n' "$FILES" | FORMAT="$FORMAT" SHOWRUNS="$SHOWRUNS" ALL="$ALL" awk '
+ BEGIN {
+ BINMODE = 3
+ fmtarg = ENVIRON["FORMAT"]
+ # The list arrives on /dev/stdin, named, so the main input stays the files.
+ while ((getline f < "/dev/stdin") > 0) {
+ if (f == "") continue
+ nf++; lst[nf] = f
+ av = (f ~ /^(\/|[A-Za-z]:)/) ? f : "./" f
+ fidx[av] = nf
+ fmt[nf] = (fmtarg == "auto") ? detect(f) : fmtarg
+ ARGV[ARGC++] = av
+ }
+ }
+ # The format of one file: NUnit if any <test-case, else JUnit if any
+ # <testcase, else Unreal if any "Test Completed. Result={", else text.
+ function detect(f, l, nu, ju, un) {
+ nu = 0; ju = 0; un = 0
+ while ((getline l < f) > 0) {
+ if (index(l, "<test-case") > 0) nu = 1
+ else if (index(l, "<testcase") > 0) ju = 1
+ if (index(l, "Test Completed. Result={") > 0) un = 1
+ }
+ close(f)
+ return nu ? "nunit" : (ju ? "junit" : (un ? "unreal" : "text"))
+ }
+ function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
+ # XML entities in an id; &amp; last so &amp;lt; stays &lt;.
+ function xd(s) {
+ gsub(/&lt;/, "<", s); gsub(/&gt;/, ">", s); gsub(/&quot;/, "\042", s); gsub(/&apos;/, "\047", s)
+ gsub(/&amp;/, "\\&", s)
+ return s
+ }
+ # The value of attribute name in tag t; the name must follow white space, so
+ # name= does not match classname= or fullname=.
+ function attr(t, name, re, q, rest, e) {
+ re = "[ \t]" name "[ \t]*=[ \t]*[\042\047]"
+ if (!match(t, re)) return ""
+ q = substr(t, RSTART + RLENGTH - 1, 1)
+ rest = substr(t, RSTART + RLENGTH)
+ e = index(rest, q)
+ return trim(xd(e ? substr(rest, 1, e - 1) : rest))
+ }
+ function unrec(f, w, k) {
+ k = f "\t" w
+ if (!(k in uc)) uo[++nu] = k
+ uc[k]++
+ }
+ function record(id, code) {
+ if (id == "") { noid++; rnoid[curj]++; return }
+ gsub(/\t/, " ", id)
+ if (!(id in seen)) { seen[id] = 1; order[++nt] = id }
+ if (code == "P") { tp[id]++; rp[curj]++ }
+ else if (code == "F") { tf[id]++; rf[curj]++ }
+ else { ts[id]++; rs[curj]++ }
+ pat[id] = pat[id] code
+ rres[curj]++
+ }
+ # The index of the > that closes the tag starting at s (a > inside quotes
+ # does not), or 0.
+ function tag_end(s, i, n, c, qc) {
+ n = length(s); qc = ""
+ for (i = 2; i <= n; i++) {
+ c = substr(s, i, 1)
+ if (qc != "") { if (c == qc) qc = ""; continue }
+ if (c == "\042" || c == "\047") qc = c
+ else if (c == ">") return i
+ }
+ return 0
+ }
+ function xml_tag(t, c2, closing, name, selfc, id, r, c) {
+ c2 = substr(t, 2, 1)
+ if (c2 == "?" || c2 == "!") return
+ closing = (c2 == "/")
+ name = substr(t, closing ? 3 : 2)
+ sub(/[ \t\/>].*$/, "", name)
+ selfc = (substr(t, length(t) - 1, 1) == "/")
+ if (cf == "nunit") {
+ if (!closing && name == "test-case") {
+ id = attr(t, "fullname"); if (id == "") id = attr(t, "name")
+ r = attr(t, "result")
+ if (r == "Passed") record(id, "P")
+ else if (r == "Failed") record(id, "F")
+ else {
+ record(id, "S")
+ if (r != "Inconclusive" && r != "Skipped") unrec("nunit", (r == "") ? "(none)" : r)
+ }
+ }
+ return
+ }
+ # junit
+ if (closing) {
+ if (name == "testcase" && jopen) { record(jid, jcode); jopen = 0 }
+ return
+ }
+ if (name == "testcase") {
+ if (jopen) { record(jid, jcode); jopen = 0 }
+ id = attr(t, "name"); c = attr(t, "classname")
+ jid = (c != "") ? c "." id : id
+ jcode = "P"
+ if (selfc) record(jid, "P"); else jopen = 1
+ return
+ }
+ if (jopen) {
+ if (name == "failure" || name == "error") jcode = "F"
+ else if (name == "skipped" && jcode != "F") jcode = "S"
+ }
+ }
+ function xml_line(s, p, q) {
+ if (pend != "") { s = pend " " s; pend = "" }
+ while (s != "") {
+ if (skipterm != "") {
+ p = index(s, skipterm)
+ if (p == 0) return
+ s = substr(s, p + length(skipterm)); skipterm = ""
+ continue
+ }
+ p = index(s, "<")
+ if (p == 0) return
+ s = substr(s, p)
+ if (substr(s, 1, 9) == "<![CDATA[") { skipterm = "]]>"; s = substr(s, 10); continue }
+ if (substr(s, 1, 4) == "<!--") { skipterm = "-->"; s = substr(s, 5); continue }
+ q = tag_end(s)
+ if (q == 0) { pend = s; return }
+ xml_tag(substr(s, 1, q)); s = substr(s, q + 1)
+ }
+ }
+ function brace(s, key, p, e) {
+ p = index(s, key "={")
+ if (p == 0) return ""
+ s = substr(s, p + length(key) + 2); e = index(s, "}")
+ return trim(e ? substr(s, 1, e - 1) : s)
+ }
+ function unreal_line(s, mk, p, rest, q, w, id, code) {
+ mk = "Test Completed. Result={"
+ p = index(s, mk)
+ if (p == 0) return
+ rest = substr(s, p + length(mk)); q = index(rest, "}")
+ if (q == 0) return
+ w = substr(rest, 1, q - 1); rest = substr(rest, q + 1)
+ id = brace(rest, "Path"); if (id == "") id = brace(rest, "Name")
+ if (w == "Success") code = "P"
+ else if (w == "Fail") code = "F"
+ else { code = "S"; unrec("unreal", w) }
+ record(id, code)
+ }
+ function text_line(s, hp, hf, tpz, tfl, code, marker, p, t, n, a, i, out) {
+ gsub(/\033\[[0-9;]*m/, "", s)
+ hp = match(s, /(^|[^A-Za-z0-9_])PASSED([^A-Za-z0-9_]|$)/) > 0
+ hf = match(s, /(^|[^A-Za-z0-9_])FAILED([^A-Za-z0-9_]|$)/) > 0
+ tpz = index(s, "Test passed") > 0
+ tfl = index(s, "Test failed") > 0
+ if (hp + hf + tpz + tfl != 1) return
+ if (hp) { code = "P"; marker = "PASSED" }
+ else if (hf) { code = "F"; marker = "FAILED" }
+ else if (tpz) { code = "P"; marker = "Test passed" }
+ else { code = "F"; marker = "Test failed" }
+ p = index(s, marker)
+ t = substr(s, 1, p - 1) " " substr(s, p + length(marker))
+ sub(/^[ \t]*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9][T ][0-9:.]+Z?[ \t]*/, "", t)
+ n = split(t, a, " "); out = ""
+ for (i = 1; i <= n; i++) {
+ if (a[i] ~ /^\(?[0-9][0-9.]*(ms|s)\)?$/) continue
+ out = (out == "") ? a[i] : out " " a[i]
+ }
+ while (out != "" && index(" []():>|*-,", substr(out, 1, 1)) > 0) out = substr(out, 2)
+ while (out != "" && index(" []():>|*-,", substr(out, length(out), 1)) > 0) out = substr(out, 1, length(out) - 1)
+ record(out, code)
+ }
+ function endfile() {
+ if (jopen) { record(jid, jcode); jopen = 0 }
+ }
+ # fail rate as tenths of a percent, truncated: 1/3 -> 33.3, 2/3 -> 66.6
+ function pct1(f, n, v) {
+ if (n == 0) return "-"
+ v = int(f * 1000 / n)
+ return sprintf("%d.%d", int(v / 10), v % 10)
+ }
+ # Sets TIER and RULE for a test with p passes and f fails. fail_pct is
+ # compared as the exact ratio f/n, by cross-multiplying, never as a printed
+ # or rounded number.
+ function classify(p, f, n) {
+ n = p + f
+ if (n == 0) { TIER = "no-result"; RULE = "only skipped results"; return }
+ if (f == 0) { TIER = "none"; RULE = "no fail in the counted results"; return }
+ if (p == 0) { TIER = "always-fail"; RULE = "no pass in the counted results"; return }
+ if (n < 3) { TIER = "suspected"; RULE = "flaky, fewer than 3 results"; return }
+ if (f * 100 > 25 * n) { TIER = "high"; RULE = "fail_pct > 25"; return }
+ if (f * 100 >= 5 * n) { TIER = "moderate"; RULE = "5 <= fail_pct <= 25"; return }
+ if (f * 100 >= n) { TIER = "low"; RULE = "1 <= fail_pct < 5"; return }
+ TIER = "below-low"; RULE = "0 < fail_pct < 1"
+ }
+ # Does test a list before test b: higher fail rate first, tests with no
+ # counted result last, then by id.
+ function before(a, b) {
+ if (kn[a] == 0 || kn[b] == 0) {
+ if (kn[a] == 0 && kn[b] == 0) return ((order[a] "") < (order[b] ""))
+ return (kn[b] == 0)
+ }
+ if (kf[a] * kn[b] != kf[b] * kn[a]) return (kf[a] * kn[b] > kf[b] * kn[a])
+ return ((order[a] "") < (order[b] ""))
+ }
+ FNR >= 1 {
+ if (FILENAME != curfn) {
+ endfile(); curfn = FILENAME; curj = fidx[FILENAME]; cf = fmt[curj]
+ pend = ""; skipterm = ""; jopen = 0
+ }
+ line = $0; sub(/\r$/, "", line)
+ if (cf == "nunit" || cf == "junit") xml_line(line)
+ else if (cf == "unreal") unreal_line(line)
+ else text_line(line)
+ }
+ END {
+ endfile()
+ analysed = 0
+ for (j = 1; j <= nf; j++) if (rres[j] > 0) analysed++
+ for (k = 1; k <= nt; k++) {
+ id = order[k]; kp[k] = tp[id] + 0; kf[k] = tf[id] + 0; ks[k] = ts[id] + 0; kn[k] = kp[k] + kf[k]
+ classify(kp[k], kf[k]); kt[k] = TIER; kr[k] = RULE
+ if (kn[k] > 0 && kf[k] == 0) nclean++
+ if (kp[k] > 0 && kf[k] > 0) nflaky++
+ tc[kt[k]]++
+ }
+ printf "runs\t%d\t%d\n", analysed, nf
+ printf "tests\t%d\n", nt
+ printf "clean\t%d\tno fail in the counted results\n", nclean
+ printf "flaky\t%d\ta pass and a fail in the counted results\n", nflaky
+ printf "tier\thigh\t%d\tfail_pct > 25\n", tc["high"]
+ printf "tier\tmoderate\t%d\t5 <= fail_pct <= 25\n", tc["moderate"]
+ printf "tier\tlow\t%d\t1 <= fail_pct < 5\n", tc["low"]
+ printf "tier\tbelow-low\t%d\t0 < fail_pct < 1\n", tc["below-low"]
+ printf "tier\tsuspected\t%d\tflaky, fewer than 3 results\n", tc["suspected"]
+ printf "always_fail\t%d\tno pass in the counted results\n", tc["always-fail"]
+ printf "no_result\t%d\tonly skipped results\n", tc["no-result"]
+ printf "data_note\t%s\n", (analysed < 5) ? "fewer than 5 runs" : "-"
+ printf "no_id\t%d\n", noid
+ for (i = 1; i <= nu; i++) printf "unrecognised\t%s\t%d\n", uo[i], uc[uo[i]]
+ if (ENVIRON["SHOWRUNS"] == "1")
+ for (j = 1; j <= nf; j++)
+ printf "RUN\t%d\t%s\t%s\t%d\t%d\t%d\t%d\t%d\n", j, lst[j], fmt[j], rres[j], rp[j], rf[j], rs[j], rnoid[j]
+ nl = 0
+ for (k = 1; k <= nt; k++) if (ENVIRON["ALL"] == "1" || kf[k] > 0 || ks[k] > 0) srt[++nl] = k
+ for (i = 2; i <= nl; i++) {
+ v = srt[i]
+ for (j = i - 1; j >= 1 && before(v, srt[j]); j--) srt[j + 1] = srt[j]
+ srt[j + 1] = v
+ }
+ for (i = 1; i <= nl; i++) {
+ k = srt[i]
+ printf "TEST\t%s\t%d\t%d\t%d\t%d\t%s\t%s\t%s\t%s\t%s\n", order[k], kn[k], kp[k], kf[k], ks[k], pct1(kf[k], kn[k]), \
+ pat[order[k]], (kp[k] > 0 && kf[k] > 0) ? "yes" : "no", kt[k], kr[k]
+ }
+ exit ((analysed == 0) ? 4 : 0)
+ }
+'
+exit $?
diff --git a/.claude/scripts/gdd-structure-check.sh b/.claude/scripts/gdd-structure-check.sh
index d60bac59..194bbcec 100644
--- a/.claude/scripts/gdd-structure-check.sh
+++ b/.claude/scripts/gdd-structure-check.sh
@@ -14,14 +14,22 @@
# COMPLETE, so an "N/8" score would actively misreport it. The caller applies the
# tier; this script only says what is on disk.
#
+# PLACEHOLDER names present sections that hold nothing yet: /design-system
+# writes every heading first with `[To be designed]` under it, so a skeleton
+# has every section PRESENT. A section counts as a placeholder when its body,
+# down to the next heading at its own level or above, holds only that marker,
+# blank lines and sub-headings. Like PRESENT, it is an observation: the
+# caller decides what it means at the project's tier.
+#
# Usage:
# bash .claude/scripts/gdd-structure-check.sh # all system GDDs
# bash .claude/scripts/gdd-structure-check.sh design/gdd/foo.md # one GDD
#
-# Output (per GDD; the ABSENT line is omitted when nothing is absent):
+# Output (per GDD; the ABSENT and PLACEHOLDER lines are omitted when empty):
# combat.md PRESENT: Overview,Player Fantasy,Detailed Rules,...
# loot.md PRESENT: Overview,Detailed Rules,Edge Cases
# loot.md ABSENT: Player Fantasy,Formulas,Tuning Knobs
+# loot.md PLACEHOLDER: Edge Cases
set -u
@@ -71,9 +79,42 @@ check_file() {
local b; b="$(basename "$f")"
echo "$b PRESENT: ${present#,}"
[ -n "$absent" ] && echo "$b ABSENT: ${absent#,}"
+ local held; held=$(placeholders < "$f")
+ [ -n "$held" ] && echo "$b PLACEHOLDER: $held"
return 0
}
+# placeholders < GDD -- the LABELs of present sections whose body is only
+# `[To be designed]`, blank lines and sub-headings, comma-separated. The first
+# heading matching each MATCH entry is the section, as for PRESENT. The file
+# comes on stdin, so awk never reads a path such as x=1.md as an assignment.
+# [ \t] not [[:space:]]: BWK awk on older macOS lacks the classes.
+placeholders() {
+ local pats="" labels="" i
+ for i in "${!MATCH[@]}"; do pats="$pats;${MATCH[$i]}"; labels="$labels;${LABEL[$i]}"; done
+ awk -v pats="${pats#;}" -v labels="${labels#;}" '
+ { sub(/\r$/, ""); line[NR] = $0 }
+ END {
+ n = split(pats, P, ";"); split(labels, L, ";"); out = ""
+ for (i = 1; i <= n; i++) {
+ re = "^##+[ \t]+([0-9]+[.)]?[ \t]*)?" tolower(P[i])
+ h = 0
+ for (j = 1; j <= NR; j++) if (tolower(line[j]) ~ re) { h = j; break }
+ if (!h) continue
+ match(line[h], /^#+/); lvl = RLENGTH
+ held = 1
+ for (j = h + 1; j <= NR; j++) {
+ t = line[j]
+ if (match(t, /^#+[ \t]/)) { if (RLENGTH - 1 <= lvl) break; continue }
+ gsub(/^[ \t]+|[ \t]+$/, "", t)
+ if (t != "" && t != "[To be designed]") { held = 0; break }
+ }
+ if (held) out = out "," L[i]
+ }
+ print substr(out, 2)
+ }'
+}
+
if [ $# -gt 0 ] && [ -n "${1:-}" ]; then
[ -f "$1" ] || { echo "Not found: $1" >&2; exit 1; }
check_file "$1"
diff --git a/.claude/scripts/hook-input.sh b/.claude/scripts/hook-input.sh
new file mode 100644
index 00000000..de0d5dbb
--- /dev/null
+++ b/.claude/scripts/hook-input.sh
@@ -0,0 +1,281 @@
+#!/usr/bin/env bash
+# hook-input.sh — what a PreToolUse payload for Write or Edit says, read one
+# way: the tool, the file it writes (made project-relative), the subagent that
+# calls it, and the content the file will hold once the call has run. The hooks
+# that check writes (validate-registry.sh, validate-write.sh) and reads
+# (validate-read.sh) read the payload through this script, so the JSON
+# decoding and the Edit rebuild exist once.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+#
+# Usage: bash .claude/scripts/hook-input.sh [--root DIR] [--new FILE] < payload.json
+# --new FILE also write the content the file will hold to FILE: Write's
+# content, or Edit's old_string replaced by new_string in the
+# current file (first match, or every one with replace_all)
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+# The payload is parsed with jq when it is on PATH, else by the awk below.
+#
+# Output: TSV, one row each, in this order:
+# tool <tool_name | ->
+# path <the file, project-relative | the absolute path when outside | ->
+# where <inside | outside | none>
+# existed <yes | no | -> the file was there before the call
+# agent <agent_type | -> set when a subagent makes the call
+# replace_all <true | false>
+# bounded <yes | no> Read only: the read gives an offset or a limit
+# (validate-read.sh)
+# new <ok | -> | new <unread FIELD> | new <notfound> | new <empty-old>
+# (only with --new): ok, the content is in FILE; unread, the payload
+# has no such string; notfound, old_string is not in the current file;
+# empty-old, an empty old_string on a file that has content
+#
+# Exit codes: 0 read (what it found is rows); 1 the root cannot be read;
+# 2 usage error. Writes only FILE; never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+LC_ALL=C
+export LC_ALL
+
+usage() { echo "hook-input: $1 (try --help)" >&2; exit 2; }
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ROOT_ARG=""; NEWF=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root) [ $# -ge 2 ] || usage "--root needs a value"; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --new) [ $# -ge 2 ] || usage "--new needs a file"; NEWF="$2"; shift 2 ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# //; s/^#//'; exit 0 ;;
+ *) usage "unknown argument: $1" ;;
+ esac
+done
+case "$NEWF" in ""|/*|[A-Za-z]:[\\/]*) ;; *) NEWF="$PWD/$NEWF" ;; esac
+INPUT=$(cat)
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "hook-input: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "hook-input: cannot reach the repo root" >&2; exit 1; }
+fi
+
+# Decodes the payload without jq. HI_MODE=head prints the tool name, the
+# replace_all flag, the file path, the agent type and "end", one per line;
+# HI_MODE=body writes the decoded content (Write) or old_string and new_string
+# (Edit) to HI_NEW, HI_OS and HI_NS and prints ok, or the field it could not read.
+DECODE='
+ BEGIN { BINMODE = 3 }
+ { buf = buf (NR > 1 ? "\n" : "") $0 }
+ function hexval(h, i, c, v) {
+ v = 0
+ for (i = 1; i <= 4; i++) {
+ c = index("0123456789abcdef", tolower(substr(h, i, 1)))
+ if (c == 0) return -1
+ v = v * 16 + c - 1
+ }
+ return v
+ }
+ # A code point as UTF-8 bytes (LC_ALL=C makes %c one byte).
+ function utf8(cp) {
+ if (cp < 128) return sprintf("%c", cp)
+ if (cp < 2048) return sprintf("%c%c", 192 + int(cp / 64), 128 + cp % 64)
+ if (cp < 65536) return sprintf("%c%c%c", 224 + int(cp / 4096), 128 + int(cp / 64) % 64, 128 + cp % 64)
+ return sprintf("%c%c%c%c", 240 + int(cp / 262144), 128 + int(cp / 4096) % 64, 128 + int(cp / 64) % 64, 128 + cp % 64)
+ }
+ # The string value of the first "k": "..." pair, decoded; FOUND says whether
+ # there was one. Inside a JSON string every quote is escaped, so "k" followed
+ # by a colon is only ever a key. The body ends at the first quote preceded
+ # by an even number of backslashes.
+ function jv(k, rest, n, q, i, t, j, body, out, cp, lo) {
+ FOUND = 0
+ if (!match(buf, "\"" k "\"[ \t\r\n]*:[ \t\r\n]*\"")) return ""
+ rest = substr(buf, RSTART + RLENGTH)
+ n = split(rest, q, "\"")
+ body = ""
+ for (i = 1; i <= n; i++) {
+ t = q[i]; j = 0
+ while (j < length(t) && substr(t, length(t) - j, 1) == "\\") j++
+ body = body t
+ if (j % 2 == 0) { FOUND = (i < n); break }
+ body = body "\""
+ }
+ if (!FOUND) return ""
+ # \\ first, through \001 (a raw control byte never appears in JSON text),
+ # so the n of an escaped backslash followed by n stays an n.
+ gsub(/\\\\/, "\001", body)
+ gsub(/\\"/, "\"", body); gsub(/\\\//, "/", body)
+ gsub(/\\n/, "\n", body); gsub(/\\t/, "\t", body); gsub(/\\r/, "\r", body)
+ gsub(/\\b/, "\b", body); gsub(/\\f/, "\f", body)
+ # \uXXXX next. Each \001 goes back to a backslash in the text between the
+ # escapes only, never in what an escape decodes to, so a \u0001 in the
+ # content stays the byte 01.
+ out = ""
+ while (match(body, /\\u[0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f]/)) {
+ out = out unbs(substr(body, 1, RSTART - 1))
+ cp = hexval(substr(body, RSTART + 2, 4)); body = substr(body, RSTART + 6)
+ # A UTF-16 surrogate pair (D800-DBFF then DC00-DFFF) is one code point.
+ if (cp >= 55296 && cp < 56320 && match(body, /^\\u[dD][c-fC-F][0-9A-Fa-f][0-9A-Fa-f]/)) {
+ lo = hexval(substr(body, 3, 4)); body = substr(body, 7)
+ cp = 65536 + (cp - 55296) * 1024 + (lo - 56320)
+ }
+ out = out utf8(cp)
+ }
+ return out unbs(body)
+ }
+ # \001 back to a backslash with index(), not split(): BWK awk splits on a
+ # newline too when the separator is one character, which turned every
+ # decoded newline into a backslash.
+ function unbs(s, out, i) {
+ out = ""
+ while ((i = index(s, "\001")) > 0) { out = out substr(s, 1, i - 1) "\\"; s = substr(s, i + 1) }
+ return out s
+ }
+ END {
+ if (ENVIRON["HI_MODE"] == "head") {
+ print jv("tool_name")
+ print (match(buf, /"replace_all"[ \t\r\n]*:[ \t\r\n]*true/) ? "true" : "false")
+ print jv("file_path")
+ print jv("agent_type")
+ print (match(buf, /"(offset|limit)"[ \t\r\n]*:[ \t\r\n]*[0-9]/) ? "yes" : "no")
+ print "end"
+ exit 0
+ }
+ t = jv("tool_name")
+ if (t == "Write") {
+ v = jv("content"); if (!FOUND) { print "content"; exit 0 }
+ printf "%s", v > ENVIRON["HI_NEW"]
+ } else {
+ v = jv("old_string"); if (!FOUND) { print "old_string"; exit 0 }
+ printf "%s", v > ENVIRON["HI_OS"]
+ v = jv("new_string"); if (!FOUND) { print "new_string"; exit 0 }
+ printf "%s", v > ENVIRON["HI_NS"]
+ }
+ print "ok"
+ }'
+
+HAVE_JQ=0; command -v jq >/dev/null 2>&1 && HAVE_JQ=1
+# -b (jq 1.7+): a native Windows jq.exe otherwise writes every newline as CRLF,
+# so the rebuilt content would differ from what the awk reader gives. An older
+# jq refuses the flag and needs none.
+JQB=""
+[ "$HAVE_JQ" = 1 ] && jq -b -n 1 >/dev/null 2>&1 && JQB=-b
+if [ "$HAVE_JQ" = 1 ]; then
+ # tr: a native Windows jq.exe ends its lines CRLF under Git Bash.
+ HEAD=$(printf '%s' "$INPUT" | jq -r '(.tool_name // ""), (.tool_input.replace_all // false), (.tool_input.file_path // ""), (.agent_type // ""), (if ((.tool_input.offset | type) == "number" or (.tool_input.limit | type) == "number") then "yes" else "no" end), "end"' 2>/dev/null | tr -d '\r')
+else
+ HEAD=$(printf '%s' "$INPUT" | HI_MODE=head awk "$DECODE")
+fi
+# Split in the shell. The closing "end" line keeps an empty field from being
+# lost with the trailing newlines.
+NL='
+'
+TOOL=${HEAD%%"$NL"*}; HEAD=${HEAD#*"$NL"}
+REPLACE_ALL=${HEAD%%"$NL"*}; HEAD=${HEAD#*"$NL"}
+FILE_PATH=${HEAD%%"$NL"*}; HEAD=${HEAD#*"$NL"}
+AGENT=${HEAD%%"$NL"*}; HEAD=${HEAD#*"$NL"}
+BOUNDED=${HEAD%%"$NL"*}
+[ "$REPLACE_ALL" = true ] || REPLACE_ALL=false
+[ "$BOUNDED" = yes ] || BOUNDED=no
+
+# Windows separators to slashes: an escaped pair from the awk path is already
+# one backslash, so one rule covers both readers. Then project-relative,
+# against the root in either spelling Git Bash gives it, and failing those, by
+# physical path: the root's `pwd -P` against the path with its deepest
+# existing directory resolved, so a root reached through a symlink (macOS
+# /tmp is /private/tmp) and a path that comes resolved, or the other way
+# round, still read as inside.
+FILE_PATH=$(printf '%s' "$FILE_PATH" | sed 's|\\|/|g')
+ROOT_P=$(pwd); ROOT_W=$(pwd -W 2>/dev/null || printf '%s' "$ROOT_P"); ROOT_PP=$(pwd -P)
+# phys PATH — PATH with its deepest existing directory resolved (symlinks
+# followed, .. folded) and the rest as it came; empty when none can be entered.
+phys() {
+ _pd=$1; _pt=""
+ while [ -n "$_pd" ] && [ ! -d "$_pd" ]; do
+ _pt="/${_pd##*/}$_pt"; _pn=${_pd%/*}
+ [ "$_pn" = "$_pd" ] && return 0
+ _pd=$_pn
+ done
+ [ -n "$_pd" ] || _pd=/
+ _pd=$(cd "$_pd" 2>/dev/null && pwd -P) || return 0
+ printf '%s%s' "${_pd%/}" "$_pt"
+}
+WHERE=inside
+shopt -s nocasematch
+case "$FILE_PATH" in
+ "") WHERE=none ;;
+ "$ROOT_P"/*) REL="${FILE_PATH:${#ROOT_P}+1}" ;;
+ "$ROOT_W"/*) REL="${FILE_PATH:${#ROOT_W}+1}" ;;
+ /*|[A-Za-z]:/*)
+ _fp=$(phys "$FILE_PATH")
+ case "$_fp" in
+ "$ROOT_PP"/*) REL="${_fp:${#ROOT_PP}+1}" ;;
+ *) WHERE=outside; REL="$FILE_PATH" ;;
+ esac ;;
+ *) REL="${FILE_PATH#./}" ;;
+esac
+shopt -u nocasematch
+EXISTED=-
+if [ "$WHERE" = inside ]; then if [ -e "$REL" ]; then EXISTED=yes; else EXISTED=no; fi; fi
+tsv() { printf '%s' "$1" | tr '\t\n' ' '; }
+printf 'tool\t%s\npath\t%s\nwhere\t%s\nexisted\t%s\nagent\t%s\nreplace_all\t%s\n' \
+ "$(tsv "${TOOL:--}")" "$(tsv "${REL:--}")" "$WHERE" "$EXISTED" "$(tsv "${AGENT:--}")" "$REPLACE_ALL"
+[ "$TOOL" = Read ] && printf 'bounded\t%s\n' "$BOUNDED"
+[ -n "$NEWF" ] || exit 0
+
+# ---------------------------------------------------- the content after the call
+if [ "$WHERE" != inside ]; then printf 'new\t-\n'; exit 0; fi
+case "$TOOL" in Write|Edit) ;; *) printf 'new\t-\n'; exit 0 ;; esac
+OS="$NEWF.old"; NS="$NEWF.new"
+trap 'rm -f "$OS" "$NS"' EXIT
+: > "$NEWF" 2>/dev/null || { echo "hook-input: cannot write $NEWF" >&2; exit 2; }
+if [ "$HAVE_JQ" = 1 ]; then
+ GOT=ok
+ # -e: a field that is absent or not a string exits non-zero instead of
+ # writing nothing, which would read as an emptied file.
+ # shellcheck disable=SC2086
+ if [ "$TOOL" = Write ]; then
+ printf '%s' "$INPUT" | jq $JQB -e -j '.tool_input.content | strings' > "$NEWF" 2>/dev/null || GOT=content
+ else
+ printf '%s' "$INPUT" | jq $JQB -e -j '.tool_input.old_string | strings' > "$OS" 2>/dev/null || GOT=old_string
+ [ "$GOT" = ok ] && { printf '%s' "$INPUT" | jq $JQB -e -j '.tool_input.new_string | strings' > "$NS" 2>/dev/null || GOT=new_string; }
+ fi
+else
+ GOT=$(printf '%s' "$INPUT" | HI_MODE=body HI_NEW="$NEWF" HI_OS="$OS" HI_NS="$NS" awk "$DECODE")
+fi
+[ "$GOT" = ok ] || { printf 'new\tunread %s\n' "$GOT"; exit 0; }
+[ "$TOOL" = Write ] && { printf 'new\tok\n'; exit 0; }
+
+# Each file read whole, CRLF made LF on both sides as the Edit tool matches;
+# first match, or every one with replace_all. RS is the byte 01, rare in text,
+# and the records are joined back with it, so a file that holds one is still
+# read whole (only a 01 as its very last byte is lost).
+SPLICE=$(HI_CUR="$REL" HI_OS="$OS" HI_NS="$NS" HI_ALL="$REPLACE_ALL" HI_OUT="$NEWF" awk '
+ function slurp(f, r, x, s, k) {
+ s = ""; k = 0
+ while ((r = (getline x < f)) > 0) { s = s (k++ ? "\001" : "") x }
+ close(f); READ = (r == 0 || k > 0)
+ return s
+ }
+ BEGIN {
+ BINMODE = 3; RS = "\001"
+ c = slurp(ENVIRON["HI_CUR"]); have = READ
+ o = slurp(ENVIRON["HI_OS"]); n = slurp(ENVIRON["HI_NS"])
+ gsub(/\r\n/, "\n", c); gsub(/\r\n/, "\n", o)
+ if (o == "") {
+ if (have && c != "") { print "empty-old"; exit 0 }
+ printf "%s", n > ENVIRON["HI_OUT"]; print "ok"; exit 0
+ }
+ p = index(c, o)
+ if (!p) { print "notfound"; exit 0 }
+ out = ""
+ while (p) {
+ out = out substr(c, 1, p - 1) n; c = substr(c, p + length(o))
+ if (ENVIRON["HI_ALL"] != "true") break
+ p = index(c, o)
+ }
+ printf "%s", out c > ENVIRON["HI_OUT"]
+ print "ok"
+ }')
+printf 'new\t%s\n' "${SPLICE:-notfound}"
+exit 0
diff --git a/.claude/scripts/inputs-check.sh b/.claude/scripts/inputs-check.sh
new file mode 100644
index 00000000..c6767f31
--- /dev/null
+++ b/.claude/scripts/inputs-check.sh
@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# inputs-check.sh — FOUND / EMPTY / ABSENT for each input a skill declares,
+# so "Insufficient input — check this before producing any report" is one
+# call instead of a Glob and a Read per input.
+#
+# Replaces the hand-run FOUND/ABSENT lists a skill builds from a Glob and a
+# Read per input.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# Which inputs are required, and whether an ABSENT one makes a section
+# NOT ASSESSED, is the calling skill's call. The exit code never says.
+#
+# Usage: bash .claude/scripts/inputs-check.sh [--root DIR] [--from FILE|-] [SPEC...]
+# SPEC a path relative to the root: a file, a folder, or a glob.
+# `*` and `?` stay inside one folder, `**/` spans folders
+# (bash 3.2 has no globstar, so globs go through find), and a
+# trailing `/` matches folders instead of files. `*` matches
+# dot-files too. A backslash is read as `/` (design\gdd\*.md is
+# design/gdd/*.md); the row keeps the spec as it was given.
+# --from F read more specs from F, one per line (`-` is stdin); blank
+# lines and lines starting with `#` are skipped
+# --root DIR the project to check; defaults to the repo this script is in
+# -h, --help this text
+#
+# Output: TSV. Four count rows first, so a reader knows how many specs were
+# checked before reading any of them, then one row per spec in the order given:
+# inputs <n> / found <n> / empty <n> / absent <n>
+# <STATUS> <spec> <matches> <first match, or ->
+# STATUS:
+# FOUND at least one match holds something other than whitespace
+# EMPTY matches exist but every one is blank: a zero-byte or
+# whitespace-only file, or a folder with no such file in it.
+# A file that exists is not yet data.
+# ABSENT nothing matched
+#
+# Exit codes: 0 checked every spec (whatever they found); 1 the root or the
+# --from file cannot be read; 2 usage error (no spec, an absolute path, a tab
+# in a spec, an unknown flag). Reads only; never writes, never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics: grep's [:space:] and sort order must not depend on the
+# user's locale, or two machines would sort and classify one tree differently.
+LC_ALL=C
+export LC_ALL
+
+TAB=$(printf '\t')
+NL='
+'
+SPECS=""
+ROOT_ARG=""
+FROM=""
+add_spec() { SPECS="$SPECS$1$NL"; }
+
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root|--from)
+ [ $# -ge 2 ] || { echo "inputs-check: $1 needs a value" >&2; exit 2; }
+ if [ "$1" = "--root" ]; then ROOT_ARG="$2"; else FROM="$2"; fi
+ shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --from=*) FROM="${1#--from=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ --) shift; while [ $# -gt 0 ]; do add_spec "$1"; shift; done ;;
+ -?*) echo "inputs-check: unknown argument: $1 (try --help)" >&2; exit 2 ;;
+ *) add_spec "$1"; shift ;;
+ esac
+done
+
+if [ -n "$FROM" ]; then
+ if [ "$FROM" = "-" ]; then FROM_TEXT=$(cat)
+ elif [ -f "$FROM" ]; then FROM_TEXT=$(cat "$FROM")
+ else echo "inputs-check: cannot read --from file $FROM" >&2; exit 1
+ fi
+ FROM_SPECS=$(printf '%s\n' "$FROM_TEXT" | awk '{ sub(/\r$/, ""); sub(/^[ \t]+/, ""); sub(/[ \t]+$/, "");
+ if ($0 != "" && substr($0, 1, 1) != "#") print }')
+ [ -n "$FROM_SPECS" ] && SPECS="$SPECS$FROM_SPECS$NL"
+fi
+
+[ -n "$SPECS" ] || { echo "inputs-check: no input spec given (try --help)" >&2; exit 2; }
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "inputs-check: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$(dirname "$0")/../.." 2>/dev/null || { echo "inputs-check: cannot reach the repo root" >&2; exit 1; }
+fi
+
+# Validate every spec before checking any, so a usage error prints no rows.
+# slashes SPEC — the spec with a backslash read as `/` (a Windows spec).
+slashes() {
+ case "$1" in *\\*) printf '%s' "$1" | tr '\\' '/' ;; *) printf '%s' "$1" ;; esac
+}
+
+while IFS= read -r spec; do
+ [ -z "$spec" ] && continue
+ case "$(slashes "$spec")" in
+ /*|[A-Za-z]:*) echo "inputs-check: specs are relative to the root, got $spec" >&2; exit 2 ;;
+ *"$TAB"*) echo "inputs-check: a spec cannot contain a tab (the output is TSV)" >&2; exit 2 ;;
+ esac
+done <<EOF
+$SPECS
+EOF
+
+# has_content PATH — a file with a non-whitespace byte, or a folder holding one.
+has_content() {
+ if [ -f "$1" ]; then
+ grep -q '[^[:space:]]' "$1" 2>/dev/null
+ return
+ fi
+ [ -d "$1" ] || return 1
+ find "$1" -type f 2>/dev/null | while IFS= read -r f; do
+ if grep -q '[^[:space:]]' "$f" 2>/dev/null; then echo y; break; fi
+ done | grep -q y
+}
+
+# glob_matches SPEC — every path under the root the glob names, sorted.
+glob_matches() {
+ local g="$1" type=f base
+ case "$g" in */) type=d; g="${g%/}" ;; esac
+ # The base folder is the part before the first component holding a glob
+ # character; find starts there so a glob never walks the whole project.
+ base=$(printf '%s\n' "$g" | awk -F/ '{ b = ""; for (i = 1; i < NF; i++) {
+ if (index($i, "*") || index($i, "?") || index($i, "[")) break
+ b = (b == "") ? $i : b "/" $i } print (b == "") ? "." : b }')
+ [ -d "$base" ] || return 0
+ find "$base" -type "$type" 2>/dev/null | GLOB="$g" awk '
+ function g2re(g, i, n, c, j, cls, out) {
+ out = "^"; n = length(g); i = 1
+ while (i <= n) {
+ c = substr(g, i, 1)
+ if (c == "*") {
+ if (substr(g, i + 1, 1) == "*") {
+ if (substr(g, i + 2, 1) == "/") { out = out "(.*/)?"; i += 3; continue }
+ out = out ".*"; i += 2; continue
+ }
+ out = out "[^/]*"
+ } else if (c == "?") out = out "[^/]"
+ else if (c == "[" && (j = index(substr(g, i + 1), "]")) > 1) {
+ cls = substr(g, i + 1, j - 1)
+ if (substr(cls, 1, 1) == "!") cls = "^" substr(cls, 2)
+ out = out "[" cls "]"; i += j + 1; continue
+ } else if (index("\\.+()^$|{}[]", c) > 0) out = out "\\" c
+ else out = out c
+ i++
+ }
+ return out "$"
+ }
+ BEGIN { re = g2re(ENVIRON["GLOB"]) }
+ { sub(/^\.\//, "") }
+ $0 ~ re
+ ' | sort
+}
+
+ROWS=""; N=0; NF_=0; NE=0; NA=0
+while IFS= read -r spec; do
+ [ -z "$spec" ] && continue
+ # What is matched: a Windows spec's backslashes as slashes (find prints
+ # slashes, so design\gdd\*.md matched nothing), then ./ dropped.
+ pat=$(slashes "$spec"); pat="${pat#./}"
+ spec="${spec#./}"; spec="${spec#.\\}"
+ N=$((N + 1))
+ case "$pat" in
+ *[][*?]*) matches=$(glob_matches "$pat") ;;
+ *) if [ -e "${pat%/}" ]; then matches="${pat%/}"; else matches=""; fi ;;
+ esac
+ if [ -z "$matches" ]; then
+ NA=$((NA + 1)); ROWS="${ROWS}ABSENT$TAB$spec${TAB}0$TAB-$NL"
+ continue
+ fi
+ count=0; first=""; status=EMPTY
+ while IFS= read -r m; do
+ count=$((count + 1))
+ [ -z "$first" ] && first="$m"
+ [ "$status" = EMPTY ] && has_content "$m" && status=FOUND
+ done <<EOF
+$matches
+EOF
+ # A plain folder spec counts the files inside it, not the folder itself.
+ if [ -d "$matches" ] && [ "$matches" = "${pat%/}" ]; then
+ count=$(find "$matches" -type f 2>/dev/null | wc -l | tr -d ' ')
+ first=$(find "$matches" -type f 2>/dev/null | sort | head -1)
+ fi
+ if [ "$status" = FOUND ]; then NF_=$((NF_ + 1)); else NE=$((NE + 1)); fi
+ ROWS="$ROWS$status$TAB$spec$TAB$count$TAB${first:--}$NL"
+done <<EOF
+$SPECS
+EOF
+
+printf 'inputs\t%s\nfound\t%s\nempty\t%s\nabsent\t%s\n' "$N" "$NF_" "$NE" "$NA"
+printf '%s' "$ROWS"
+exit 0
diff --git a/.claude/scripts/md-section.sh b/.claude/scripts/md-section.sh
new file mode 100644
index 00000000..1dd3a910
--- /dev/null
+++ b/.claude/scripts/md-section.sh
@@ -0,0 +1,376 @@
+#!/usr/bin/env bash
+# md-section.sh — find, read and edit sections of a Markdown file by heading,
+# so a skill hands over a heading and the words instead of grepping a fixed
+# number of lines (a `grep -A 15` window stops wherever 15 lines end, not where
+# the section does).
+#
+# Replaces the hand-run section steps in /create-control-manifest, /create-epics,
+# /create-stories, /dev-story, /propagate-design-change and /story-done.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# A section's status is the rule below applied to its lines; whether a
+# Placeholder section blocks anything is the calling skill's call.
+#
+# Usage: bash .claude/scripts/md-section.sh <command> FILE [args]
+# list FILE every heading: level, first and last line, title
+# status FILE [HEADING ...] COMPLETE / EMPTY / PLACEHOLDER per section
+# (every section when no HEADING is given)
+# extract FILE HEADING [--body] the section's lines (--body: without its heading)
+# replace FILE HEADING the section's body, subsections included,
+# becomes stdin; the heading stays
+# insert-before FILE HEADING stdin goes in just above the heading, a
+# blank line after it and, when text is on
+# the line above, a blank line before it
+# set-field FILE FIELD VALUE [--after FIELD2]
+# a header field line (`> **Status**: Ready`,
+# `**Status:** Ready`, `- **Status**: Ready`,
+# `Status: Ready`) gets VALUE; when the field is
+# missing, --after adds it below FIELD2 in
+# FIELD2's style
+# -h, --help this text
+#
+# HEADING is the title as written, matched without regard to case, extra
+# spaces, a leading number (`1. Overview` matches `Overview`), an HTML comment
+# (`Overview <!-- fill me -->`) or emphasis (`**Rules**`, `__Rules__`; a `_`
+# inside a word counts). Prefix it with #s (`'## Status'`) to match one level
+# only.
+#
+# The rules every command shares:
+# - A heading is 1 to 6 `#` and a space, after at most 3 spaces of indent.
+# - A section runs from its heading to the line before the next heading of
+# the same or a higher level, so `###` subsections stay inside a `##` one.
+# - Lines inside a ``` or ~~~ code fence (3 or more, closed by at least as
+# many) and inside an HTML comment are never headings. A <!-- inside a
+# code span (`<!--`) opens no comment.
+# - Status, over the section's lines below its heading, fences skipped:
+# PLACEHOLDER a line holds one of /art-bible's markers: [To be designed],
+# [TBD], [To be written], or a line starting TODO or _TODO
+# (HTML comments are not searched: a comment is not content)
+# EMPTY no line holds text: blank lines, HTML comments, `---`
+# rules and subheadings do not count
+# COMPLETE anything else
+#
+# Output: TSV.
+# list: headings <n>, then <level> <first> <last> <title>
+# status: sections, complete, empty, placeholder, not_found counts, then
+# <STATUS> <first>-<last> <title> (NOT_FOUND - <HEADING> for a miss)
+# extract: the lines themselves
+# writes: file <path> <replaced|inserted|set|added|unchanged>, line <n>
+#
+# Exit codes: 0 done; 1 cannot read or write FILE; 2 usage error (unknown
+# command, nothing on stdin, a newline in VALUE); 3 HEADING or FIELD not found;
+# 4 HEADING matches more than one heading (nothing is written; a level prefix
+# or a longer title tells them apart). A write makes the new file in full
+# first, then copies it over FILE in place, so FILE keeps its mode and a
+# symlink stays one; it keeps the file's LF or CRLF line ends, and a write
+# that changes nothing leaves the file's bytes alone. Never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk: the CR tests and tolower below compare bytes.
+LC_ALL=C
+export LC_ALL
+
+usage() { echo "md-section: $1 (try --help)" >&2; exit 2; }
+
+[ $# -gt 0 ] || usage "no command"
+case "$1" in
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ list|status|extract|replace|insert-before|set-field) CMD="$1"; shift ;;
+ *) usage "unknown command: $1" ;;
+esac
+[ $# -gt 0 ] || usage "$CMD needs a FILE"
+FILE="$1"; shift
+[ -f "$FILE" ] && [ -r "$FILE" ] || { echo "md-section: cannot read $FILE" >&2; exit 1; }
+
+HEADS=""; BODY_ONLY=0; FIELD=""; VALUE=""; AFTER=""
+NL='
+'
+case "$CMD" in
+ list) [ $# -eq 0 ] || usage "list takes only FILE" ;;
+ status) for h in "$@"; do HEADS="$HEADS$h$NL"; done ;;
+ extract|replace|insert-before)
+ [ $# -ge 1 ] || usage "$CMD needs a HEADING"
+ HEADS="$1$NL"; shift
+ if [ "$CMD" = extract ] && [ "${1:-}" = "--body" ]; then BODY_ONLY=1; shift; fi
+ [ $# -eq 0 ] || usage "unexpected argument: $1" ;;
+ set-field)
+ [ $# -ge 2 ] || usage "set-field needs FIELD and VALUE"
+ FIELD="$1"; VALUE="$2"; shift 2
+ if [ "${1:-}" = "--after" ]; then
+ [ $# -ge 2 ] || usage "--after needs a FIELD"
+ AFTER="$2"; shift 2
+ fi
+ [ $# -eq 0 ] || usage "unexpected argument: $1"
+ case "$VALUE" in *"$NL"*) usage "VALUE cannot hold a newline" ;; esac ;;
+esac
+
+DIR=$(dirname "$FILE")
+STDIN_FILE=""; NEW=""; STATUS_FILE=""
+cleanup() { rm -f "$STDIN_FILE" "$NEW" "$STATUS_FILE"; }
+trap cleanup EXIT
+if [ "$CMD" = replace ] || [ "$CMD" = insert-before ] || [ "$CMD" = set-field ]; then
+ NEW=$(mktemp "$DIR/.ccgs-md-XXXXXX" 2>/dev/null) || { echo "md-section: cannot create a temporary file in $DIR" >&2; exit 1; }
+ STATUS_FILE="$NEW.status"
+fi
+if [ "$CMD" = replace ] || [ "$CMD" = insert-before ]; then
+ STDIN_FILE="$NEW.in"
+ # CR off; blank lines at both ends dropped.
+ awk '{ sub(/\r$/, ""); l[++n] = $0; if ($0 !~ /^[ \t]*$/) { if (!f) f = n; e = n } }
+ END { for (i = f; f && i <= e; i++) print l[i] }' > "$STDIN_FILE"
+ [ -s "$STDIN_FILE" ] || usage "nothing on stdin to write"
+fi
+
+# One awk pass parses the file (headings, fences, comments, markers) into
+# arrays; END runs the command. Arguments arrive through the environment, so a
+# backslash in a title is not taken as an escape.
+AWK_PROG='
+ # Git for Windows gawk reads files in text mode and drops the CR of a CRLF
+ # line; BINMODE 3 keeps every byte. Other awks treat it as a plain variable.
+ BEGIN { BINMODE = 3 }
+
+ function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
+ # A title for matching: no HTML comment (an unclosed one runs to the end),
+ # no * emphasis and no _ at a word edge (a _ inside a word stays), lower
+ # case, single spaces, no leading "1." or "1)".
+ function norm(s, p, e) {
+ while ((p = index(s, "<!--")) > 0) {
+ e = index(substr(s, p + 4), "-->")
+ s = (e == 0) ? substr(s, 1, p - 1) : substr(s, 1, p - 1) " " substr(s, p + e + 6)
+ }
+ gsub(/\*+/, "", s)
+ s = " " s " "; gsub(/[ \t]_+/, " ", s); gsub(/_+[ \t]/, " ", s)
+ s = tolower(trim(s)); gsub(/[ \t]+/, " ", s)
+ if (s ~ /^[0-9]+[.)]? /) sub(/^[0-9]+[.)]? /, "", s)
+ return s
+ }
+ # Where a code span that opens with the k backticks ending just before t
+ # closes: the index in t of a run of exactly k backticks, or 0 when none
+ # does on this line (the opening run is then plain text).
+ function span_end(t, k, i, j) {
+ i = 1
+ while (i <= length(t)) {
+ if (substr(t, i, 1) != "`") { i++; continue }
+ j = i; while (substr(t, j, 1) == "`") j++
+ if (j - i == k) return i
+ i = j
+ }
+ return 0
+ }
+ # The fence a line opens ("```", "~~~~", ...), or "" when it opens none.
+ function fence_of(s, n, c, k) {
+ n = 0; while (n < 3 && substr(s, n + 1, 1) == " ") n++
+ s = substr(s, n + 1); c = substr(s, 1, 1)
+ if (c != "`" && c != "~") return ""
+ k = 0; while (substr(s, k + 1, 1) == c) k++
+ return (k >= 3) ? substr(s, 1, k) : ""
+ }
+ function closes(s, f, n, c, k) {
+ n = 0; while (n < 3 && substr(s, n + 1, 1) == " ") n++
+ s = substr(s, n + 1); c = substr(f, 1, 1)
+ k = 0; while (substr(s, k + 1, 1) == c) k++
+ return k >= length(f) && trim(substr(s, k + 1)) == ""
+ }
+
+ {
+ raw[NR] = $0
+ line = $0; sub(/\r$/, "", line)
+ if (NR == 1) crlf = ($0 ~ /\r$/)
+ lvl[NR] = 0; text[NR] = 0; mark[NR] = 0
+ if (infence) {
+ if (closes(line, infence)) infence = ""
+ next
+ }
+ f = fence_of(line)
+ if (f != "") { infence = f; text[NR] = 1; next }
+ # HTML comments: what is left of the line outside them. A line that starts
+ # inside a comment, or opens one, is never a heading. A <!-- inside a code
+ # span (`<!--`) is text, as Markdown reads it: a span is a run of
+ # backticks closed by a run as long on the same line.
+ cstart = incomment
+ rest = ""; s = line
+ while (s != "") {
+ if (incomment) {
+ p = index(s, "-->"); if (p == 0) { s = ""; break }
+ s = substr(s, p + 3); incomment = 0
+ } else {
+ p = index(s, "<!--"); b = index(s, "`")
+ if (b > 0 && (p == 0 || b < p)) {
+ k = 0; while (substr(s, b + k, 1) == "`") k++
+ e = span_end(substr(s, b + k), k)
+ q = (e > 0) ? b + k + e - 1 + k : b + k
+ rest = rest substr(s, 1, q - 1); s = substr(s, q)
+ continue
+ }
+ if (p == 0) { rest = rest s; s = ""; break }
+ rest = rest substr(s, 1, p - 1); s = substr(s, p + 4); incomment = 1
+ }
+ }
+ startcomment = (line ~ /^[ \t]*<!--/)
+ # A heading: up to 3 spaces, 1-6 #, then a space or the end of the line.
+ h = line; n = 0; while (n < 3 && substr(h, n + 1, 1) == " ") n++
+ h = substr(h, n + 1); k = 0; while (substr(h, k + 1, 1) == "#") k++
+ if (!cstart && !startcomment && k >= 1 && k <= 6 && (length(h) == k || substr(h, k + 1, 1) == " " || substr(h, k + 1, 1) == "\t")) {
+ t = trim(substr(h, k + 1))
+ # A closing run of # (after a space) is not part of the title.
+ if (t ~ /(^| )#+$/) { sub(/#+$/, "", t); t = trim(t) }
+ lvl[NR] = k; title[NR] = t; nh++; hl[nh] = NR
+ next
+ }
+ r = trim(rest)
+ if (r != "" && r !~ /^(---+|\*\*\*+|___+)$/) text[NR] = 1
+ if (rest ~ /\[To be designed\]|\[TBD\]|\[To be written\]/ || line ~ /^_?TODO/) mark[NR] = 1
+ }
+
+ function last_of(i, j) { # last line of the section that heading i opens
+ for (j = i + 1; j <= nh; j++) if (lvl[hl[j]] <= lvl[hl[i]]) return hl[j] - 1
+ return NR
+ }
+ function status_of(i, a, b, L, any) {
+ a = hl[i]; b = last_of(i); any = 0
+ for (L = a + 1; L <= b; L++) { if (mark[L]) return "PLACEHOLDER"; if (text[L]) any = 1 }
+ return any ? "COMPLETE" : "EMPTY"
+ }
+ # Headings that match a HEADING argument; "##" in front pins the level.
+ function find(arg, want, wl, i, m) {
+ want = trim(arg); wl = 0
+ while (substr(want, wl + 1, 1) == "#") wl++
+ want = norm(substr(want, wl + 1)); m = 0
+ for (i = 1; i <= nh; i++)
+ if (norm(title[hl[i]]) == want && (wl == 0 || lvl[hl[i]] == wl)) { m++; found[m] = i }
+ return m
+ }
+ function one(arg, m, i, s) {
+ m = find(arg)
+ if (m == 0) { printf "md-section: no heading \"%s\" in the file\n", arg > "/dev/stderr"; exit 3 }
+ if (m > 1) {
+ s = ""; for (i = 1; i <= m; i++) s = s (i > 1 ? ", " : "") hl[found[i]]
+ printf "md-section: \"%s\" matches %d headings (lines %s); add a level (\"## %s\") or a longer title. Nothing was written.\n", arg, m, s, trim(arg) > "/dev/stderr"
+ exit 4
+ }
+ return found[1]
+ }
+ function out(s) { printf "%s%s\n", s, (crlf ? "\r" : "") }
+ # A header field line: its prefix through the colon (and a closing **) and
+ # the spaces after it, so the value can be swapped and the style kept.
+ function field_prefix(line, name, norm_line, p, q, low) {
+ norm_line = line; sub(/^[ \t]*/, "", norm_line); sub(/^> ?/, "", norm_line); sub(/^- /, "", norm_line)
+ gsub(/\*/, "", norm_line)
+ low = tolower(norm_line)
+ if (substr(low, 1, length(name) + 1) != tolower(name) ":") return ""
+ p = index(tolower(line), tolower(name)); if (p == 0) return ""
+ q = p + length(name); while (substr(line, q, 1) == "*") q++
+ if (substr(line, q, 1) != ":") return ""
+ q++; while (substr(line, q, 1) == "*") q++
+ while (substr(line, q, 1) == " " || substr(line, q, 1) == "\t") q++
+ return substr(line, 1, q - 1)
+ }
+
+ END {
+ cmd = ENVIRON["CMD"]
+ if (cmd == "list") {
+ print "headings\t" nh
+ for (i = 1; i <= nh; i++) { t = title[hl[i]]; gsub(/\t/, " ", t); printf "%d\t%d\t%d\t%s\n", lvl[hl[i]], hl[i], last_of(i), t }
+ exit 0
+ }
+ if (cmd == "status") {
+ nreq = split(ENVIRON["HEADS"], req, "\n"); rows = 0; nc = ne = np = nf = 0
+ if (ENVIRON["HEADS"] == "") { for (i = 1; i <= nh; i++) pick[++rows] = i }
+ else for (r = 1; r <= nreq; r++) {
+ if (req[r] == "") continue
+ m = find(req[r])
+ if (m == 0) { rows++; pick[rows] = 0; miss[rows] = req[r]; continue }
+ for (j = 1; j <= m; j++) pick[++rows] = found[j]
+ }
+ for (r = 1; r <= rows; r++) {
+ if (pick[r] == 0) { nf++; line_[r] = "NOT_FOUND\t-\t" miss[r]; continue }
+ i = pick[r]; st = status_of(i); t = title[hl[i]]; gsub(/\t/, " ", t)
+ if (st == "COMPLETE") nc++; else if (st == "EMPTY") ne++; else np++
+ line_[r] = st "\t" hl[i] "-" last_of(i) "\t" t
+ }
+ printf "sections\t%d\ncomplete\t%d\nempty\t%d\nplaceholder\t%d\nnot_found\t%d\n", rows - nf, nc, ne, np, nf
+ for (r = 1; r <= rows; r++) print line_[r]
+ exit 0
+ }
+ if (cmd == "extract") {
+ split(ENVIRON["HEADS"], req, "\n"); i = one(req[1])
+ a = hl[i] + (ENVIRON["BODY_ONLY"] == "1" ? 1 : 0); b = last_of(i)
+ for (L = a; L <= b; L++) { s = raw[L]; sub(/\r$/, "", s); print s }
+ exit 0
+ }
+ sf = ENVIRON["STATUS_FILE"]
+ if (cmd == "replace" || cmd == "insert-before") {
+ split(ENVIRON["HEADS"], req, "\n"); i = one(req[1])
+ nb = 0; while ((getline s < ENVIRON["STDIN_FILE"]) > 0) body[++nb] = s
+ a = hl[i]; b = last_of(i)
+ if (cmd == "replace") {
+ for (L = 1; L <= a; L++) print raw[L]
+ out(""); for (k = 1; k <= nb; k++) out(body[k])
+ if (b < NR) out("")
+ for (L = b + 1; L <= NR; L++) print raw[L]
+ print "replaced\t" a > sf
+ } else {
+ same = (a - nb - 1 >= 1)
+ # Already there: the block sits on lines a-nb-1 .. a-2, a blank line at a-1.
+ for (k = 1; same && k <= nb; k++) { s = raw[a - nb - 2 + k]; sub(/\r$/, "", s); if (s != body[k]) same = 0 }
+ if (same) { s = raw[a - 1]; sub(/\r$/, "", s); if (s !~ /^[ \t]*$/) same = 0 }
+ # Text on the line above the heading gets a blank line before the
+ # block, as one already parts the block from the heading, so the
+ # block never joins the paragraph above.
+ sep = 0
+ if (!same && a > 1) { s = raw[a - 1]; sub(/\r$/, "", s); if (s !~ /^[ \t]*$/) sep = 1 }
+ for (L = 1; L < a; L++) print raw[L]
+ if (!same) { if (sep) out(""); for (k = 1; k <= nb; k++) out(body[k]); out("") }
+ for (L = a; L <= NR; L++) print raw[L]
+ print (same ? "unchanged" : "inserted") "\t" (same ? a - nb - 1 : a + sep) > sf
+ }
+ exit 0
+ }
+ if (cmd == "set-field") {
+ name = ENVIRON["FIELD"]; val = ENVIRON["VALUE"]; after = ENVIRON["AFTER"]
+ at = 0; aft = 0
+ for (L = 1; L <= NR; L++) {
+ # Only lines with text outside fences and comments: a field quoted in a
+ # code sample or a comment is not the header field.
+ if (lvl[L] > 0 || !text[L]) continue
+ s = raw[L]; sub(/\r$/, "", s)
+ if (!at && (p = field_prefix(s, name)) != "") { at = L; pre = p; cur = substr(s, length(p) + 1) }
+ if (after != "" && !aft && (p = field_prefix(s, after)) != "") { aft = L; apre = p }
+ }
+ if (at) {
+ if (cur == val) { for (L = 1; L <= NR; L++) print raw[L]; print "unchanged\t" at > sf; exit 0 }
+ cr = (raw[at] ~ /\r$/)
+ for (L = 1; L <= NR; L++) {
+ if (L == at) printf "%s%s%s\n", pre, val, (cr ? "\r" : ""); else print raw[L]
+ }
+ print "set\t" at > sf; exit 0
+ }
+ if (after == "") { printf "md-section: no \"%s\" field in the file (add --after FIELD to add it)\n", name > "/dev/stderr"; exit 3 }
+ if (!aft) { printf "md-section: no \"%s\" field, and no \"%s\" field to add it after\n", name, after > "/dev/stderr"; exit 3 }
+ # The new line copies FIELD2 line style: its prefix with the name swapped.
+ p = index(tolower(apre), tolower(after))
+ npre = substr(apre, 1, p - 1) name substr(apre, p + length(after))
+ cr = (raw[aft] ~ /\r$/)
+ for (L = 1; L <= NR; L++) { print raw[L]; if (L == aft) printf "%s%s%s\n", npre, val, (cr ? "\r" : "") }
+ print "added\t" aft + 1 > sf; exit 0
+ }
+ }
+'
+export CMD HEADS BODY_ONLY FIELD VALUE AFTER STDIN_FILE STATUS_FILE
+# Into the temp file for a write; straight to stdout otherwise, never through
+# /dev/stdout, which reopens a redirected stdout at offset 0 and overwrites it.
+if [ -n "$NEW" ]; then awk "$AWK_PROG" "$FILE" > "$NEW"; else awk "$AWK_PROG" "$FILE"; fi
+rc=$?
+[ "$rc" = 0 ] || exit "$rc"
+[ -n "$NEW" ] || exit 0
+
+IFS="$(printf '\t')" read -r ACTION LINE < "$STATUS_FILE"
+if [ "$ACTION" != "unchanged" ] && cmp -s "$NEW" "$FILE"; then ACTION="unchanged"; fi
+if [ "$ACTION" != "unchanged" ]; then
+ # Copied over FILE in place, not moved: FILE keeps its mode, a symlink stays
+ # a symlink and a hard link sees the change.
+ cat "$NEW" > "$FILE" 2>/dev/null || { echo "md-section: could not write $FILE" >&2; exit 1; }
+fi
+printf 'file\t%s\t%s\nline\t%s\t-\n' "$FILE" "$ACTION" "$LINE"
+exit 0
diff --git a/.claude/scripts/migrate-v1-config.sh b/.claude/scripts/migrate-v1-config.sh
index 353d8678..7160e962 100644
--- a/.claude/scripts/migrate-v1-config.sh
+++ b/.claude/scripts/migrate-v1-config.sh
@@ -569,7 +569,7 @@ fi
echo "schema_version: 1"
echo ""
echo "framework:"
- echo " version: 1.1.3"
+ echo " version: 1.2.0"
echo ""
# Emit `project:` only when there is a stage to put in it -- same rule as the
# `modes:` block below. Writing `stage: null` produced a file that FAILED THIS
diff --git a/.claude/scripts/plan-math.sh b/.claude/scripts/plan-math.sh
new file mode 100644
index 00000000..506af6c7
--- /dev/null
+++ b/.claude/scripts/plan-math.sh
@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+# plan-math.sh — the date and percentage arithmetic planning skills do by
+# hand: days between two dates, a percentage with a zero guard, the sprint file
+# for a sprint number in any form, and the current sprint's progress from
+# production/sprint-status.yaml.
+#
+# Replaces the arithmetic a sprint or milestone planning step would otherwise
+# do by hand.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# `progress` prints which /sprint-status band its numbers fall in, as the
+# rule row that matched; On Track, At Risk or Behind is still the skill's to
+# say. Velocity is not computed: no skill defines it yet.
+#
+# Usage: bash .claude/scripts/plan-math.sh <command> [args] [--root DIR] [--today YYYY-MM-DD]
+# days START END whole days from START to END (negative if END is earlier)
+# pct PART WHOLE [--places N]
+# PART / WHOLE * 100, rounded half up to N places
+# (default 0); a WHOLE of 0 prints - and says so
+# sprint N|latest the production/sprints/ file for sprint N, written
+# 3, 03, 003 or sprint-3; latest is the highest number
+# progress the current sprint, from production/sprint-status.yaml
+# --today D the date "today" means (default: today's date)
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+# Dates are YYYY-MM-DD and must exist: a month outside 01-12 or a day past
+# the month's end (2026-02-29, 2026-04-31) is a bad date. In
+# sprint-status.yaml such a date reads as missing.
+#
+# Output: TSV.
+# days days <n> <START>..<END>
+# pct pct <value> <PART>/<WHOLE>
+# sprint sprint <n> <path>
+# progress sprint, start, end, today; days_total (end - start), days_elapsed
+# (today - start), days_left (end - today); time_pct (elapsed /
+# total); stories, done, and one row per yaml status; done_pct;
+# gap (time_pct - done_pct, in points; below 0 is ahead);
+# band <name> <rule> from /sprint-status's bands with
+# scope-check's edges: On Track gap <= 10, At Risk 10 < gap <= 25,
+# Behind gap > 25; must_have and must_have_done; time_left_pct;
+# updated_days_ago (today - the yaml's updated date)
+# Percentages in progress are whole numbers, and the gap and band are taken
+# from those, so what a reader sees is what the band was decided on. A value
+# that cannot be worked out (no dates, no stories) is `-`.
+#
+# Exit codes: 0 done; 1 the root cannot be read; 2 usage error (a bad date or
+# number, an unknown command); 3 no such sprint file, or no sprint-status.yaml
+# for progress; 4 two files hold the same sprint number (both are named).
+# Reads only; never writes, never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk and sort.
+LC_ALL=C
+export LC_ALL
+
+usage() { echo "plan-math: $1 (try --help)" >&2; exit 2; }
+# is_date D — YYYY-MM-DD and a real day: month 01-12, day 01 to the month's
+# last (29 February only in a leap year).
+is_date() {
+ case "$1" in [0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]) ;; *) return 1 ;; esac
+ _y=$((10#${1%%-*})); _m=${1#*-}; _m=$((10#${_m%-*})); _d=$((10#${1##*-}))
+ case $_m in
+ 1|3|5|7|8|10|12) _n=31 ;;
+ 4|6|9|11) _n=30 ;;
+ 2) if [ $((_y % 4)) -eq 0 ] && { [ $((_y % 100)) -ne 0 ] || [ $((_y % 400)) -eq 0 ]; }; then _n=29; else _n=28; fi ;;
+ *) return 1 ;;
+ esac
+ [ "$_d" -ge 1 ] && [ "$_d" -le "$_n" ]
+}
+is_num() { case "$1" in ''|*[!0-9.]*|*.*.*) return 1 ;; esac; return 0; }
+
+CMD=""; ROOT_ARG=""; TODAY=""; PLACES=0; ARGS=""
+NL='
+'
+while [ $# -gt 0 ]; do
+ case "$1" in
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ --root) [ $# -ge 2 ] || usage "--root needs a value"; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --today) [ $# -ge 2 ] || usage "--today needs a date"; TODAY="$2"; shift 2 ;;
+ --today=*) TODAY="${1#--today=}"; shift ;;
+ --places) [ $# -ge 2 ] || usage "--places needs a number"; PLACES="$2"; shift 2 ;;
+ -?*) usage "unknown argument: $1" ;;
+ *) if [ -z "$CMD" ]; then CMD="$1"; else ARGS="$ARGS$1$NL"; fi; shift ;;
+ esac
+done
+[ -n "$TODAY" ] || TODAY=$(date +%Y-%m-%d)
+is_date "$TODAY" || usage "--today must be a real YYYY-MM-DD date, got $TODAY"
+case "$PLACES" in [0-9]) ;; *) usage "--places takes 0-9" ;; esac
+set --
+while IFS= read -r a; do [ -n "$a" ] && set -- "$@" "$a"; done <<EOF
+$ARGS
+EOF
+
+# The arithmetic, shared by every command. days(): days since a fixed origin
+# for the Gregorian date; only differences are used. The year is counted from
+# March, so a leap day falls at its end and the month term needs no table.
+# pct(): half up (away from zero), so 12.5 is 13 at 0 places (printf alone
+# rounds half to even), in whole numbers: PART and WHOLE are scaled to integers
+# first, so 23/40 (57.5) is 58 and not the 57 a float product gives.
+AWK_LIB='
+ function days(s, p) { split(s, p, "-"); return dn(p[1] + 0, p[2] + 0, p[3] + 0) }
+ function dn(y, m, d) {
+ if (m <= 2) { y--; m += 12 }
+ return 365 * y + int(y / 4) - int(y / 100) + int(y / 400) + int((153 * (m - 3) + 2) / 5) + d
+ }
+ # A real date: month 01-12, day within the month, leap years counted.
+ function real_date(s, p, n) {
+ if (s !~ /^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]$/) return 0
+ split(s, p, "-"); p[1] += 0; p[2] += 0; p[3] += 0
+ if (p[2] < 1 || p[2] > 12 || p[3] < 1) return 0
+ n = substr("312831303130313130313031", 2 * p[2] - 1, 2) + 0
+ if (p[2] == 2 && p[1] % 4 == 0 && (p[1] % 100 != 0 || p[1] % 400 == 0)) n = 29
+ return p[3] <= n
+ }
+ # dec(s): s as the whole number DN over 10^DP ("12.5" is 125 and 1).
+ function dec(s, i, neg) {
+ s = "" s; neg = (substr(s, 1, 1) == "-"); if (neg) s = substr(s, 2)
+ DP = 0; i = index(s, ".")
+ if (i > 0) { DP = length(s) - i; s = substr(s, 1, i - 1) substr(s, i + 1) }
+ DN = s + 0; if (neg) DN = -DN
+ }
+ function pct(part, whole, places, f, i, n, d, pd, neg, m, q, r, ip) {
+ dec(whole); if (DN == 0) return "-"
+ d = DN; dec(part); n = DN; pd = DP; dec(whole)
+ f = 1; for (i = 0; i < places; i++) f *= 10
+ # part / whole * 100 * f, as the fraction n / d of whole numbers.
+ n = n * 100 * f; for (i = 0; i < DP; i++) n *= 10
+ for (i = 0; i < pd; i++) d *= 10
+ neg = ((n < 0) != (d < 0)); if (n < 0) n = -n; if (d < 0) d = -d
+ # Half up: floor((2n + d) / 2d), the float quotient corrected exactly.
+ m = 2 * n + d; q = int(m / (2 * d)); r = m - q * 2 * d
+ if (r < 0) q--; else if (r >= 2 * d) q++
+ if (places == 0) return sprintf("%s%d", (neg && q > 0) ? "-" : "", q)
+ ip = int(q / f)
+ return sprintf("%s%d.%0" places "d", (neg && q > 0) ? "-" : "", ip, q - ip * f)
+ }
+'
+
+case "$CMD" in
+ days)
+ [ $# -eq 2 ] || usage "days needs START and END"
+ is_date "$1" && is_date "$2" || usage "dates are real YYYY-MM-DD dates"
+ awk -v a="$1" -v b="$2" "$AWK_LIB"'BEGIN { printf "days\t%d\t%s..%s\n", days(b) - days(a), a, b }'
+ exit 0 ;;
+ pct)
+ [ $# -eq 2 ] || usage "pct needs PART and WHOLE"
+ is_num "$1" && is_num "$2" || usage "PART and WHOLE are numbers"
+ awk -v p="$1" -v w="$2" -v n="$PLACES" "$AWK_LIB"'BEGIN {
+ v = pct(p + 0, w + 0, n + 0)
+ printf "pct\t%s\t%s\n", v, (v == "-") ? "zero denominator" : p "/" w }'
+ exit 0 ;;
+ sprint|progress) ;;
+ "") usage "no command" ;;
+ *) usage "unknown command: $CMD" ;;
+esac
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "plan-math: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$(dirname "$0")/../.." 2>/dev/null || { echo "plan-math: cannot reach the repo root" >&2; exit 1; }
+fi
+
+if [ "$CMD" = sprint ]; then
+ [ $# -eq 1 ] || usage "sprint needs a number or latest"
+ want=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]'); want="${want#sprint-}"; want="${want#sprint}"
+ case "$want" in latest) ;; ''|*[!0-9]*) usage "sprint takes a number (3, 03, 003, sprint-3) or latest" ;; esac
+ # Only sprint-<digits>.md is a sprint plan: retrospectives and reviews that
+ # share the folder (sprint-3-retrospective.md) are not.
+ LIST=$(find production/sprints -maxdepth 1 -type f -name 'sprint-[0-9]*.md' 2>/dev/null \
+ | awk '{ b = $0; sub(/^.*\//, "", b) } b ~ /^sprint-[0-9]+\.md$/ { n = b; gsub(/[^0-9]/, "", n); print (n + 0) "\t" $0 }' | sort -n)
+ [ -n "$LIST" ] || { echo "plan-math: no production/sprints/sprint-N.md files" >&2; exit 3; }
+ if [ "$want" = latest ]; then want=$(printf '%s\n' "$LIST" | tail -1 | cut -f1); else want=$((10#$want)); fi
+ HITS=$(printf '%s\n' "$LIST" | awk -F'\t' -v w="$want" '$1 == w { print $2 }')
+ n=$(printf '%s' "$HITS" | awk 'NF' | wc -l | tr -d ' ')
+ [ "$n" -gt 0 ] || { echo "plan-math: no sprint file for sprint $want" >&2; exit 3; }
+ if [ "$n" -gt 1 ]; then
+ echo "plan-math: sprint $want has $n files: $(printf '%s' "$HITS" | tr '\n' ' ')" >&2
+ exit 4
+ fi
+ printf 'sprint\t%s\t%s\n' "$want" "${HITS#./}"
+ exit 0
+fi
+
+# progress
+YAML="production/sprint-status.yaml"
+[ -f "$YAML" ] || { echo "plan-math: no $YAML" >&2; exit 3; }
+TODAY="$TODAY" awk "$AWK_LIB"'
+ BEGIN { BINMODE = 3 }
+ function val(s, c, e) {
+ sub(/^[^:]*:[ \t]*/, "", s); c = substr(s, 1, 1)
+ if (c == "\"" || c == "\047") { e = index(substr(s, 2), c); return (e > 0) ? substr(s, 2, e - 1) : substr(s, 2) }
+ sub(/[ \t]+#.*$/, "", s); sub(/[ \t]+$/, "", s); return s
+ }
+ function d8(s) { return real_date(s) ? s : "" }
+ { sub(/\r$/, "") }
+ /^sprint:/ { sprint = val($0) } /^start:/ { start = d8(val($0)) } /^end:/ { end_ = d8(val($0)) }
+ /^updated:/ { upd = d8(val($0)) }
+ /^stories:/ { ins = 1; next }
+ /^[^ \t#-]/ { ins = 0 }
+ ins && /^[ \t]*- / { ns++ }
+ ins && /^[ \t]*(- )?status:/ { st[ns] = val($0) }
+ ins && /^[ \t]*(- )?priority:/ { pr[ns] = val($0) }
+ END {
+ today = ENVIRON["TODAY"]
+ printf "sprint\t%s\nstart\t%s\nend\t%s\ntoday\t%s\n", (sprint == "" ? "-" : sprint), (start == "" ? "-" : start), (end_ == "" ? "-" : end_), today
+ total = elapsed = left = tp = "-"
+ if (start != "" && end_ != "") {
+ total = days(end_) - days(start); elapsed = days(today) - days(start); left = days(end_) - days(today)
+ tp = pct(elapsed, total, 0)
+ }
+ printf "days_total\t%s\ndays_elapsed\t%s\ndays_left\t%s\ntime_pct\t%s\n", total, elapsed, left, tp
+ split("backlog ready-for-dev in-progress review done blocked", names, " ")
+ for (i = 1; i <= ns; i++) { c[st[i]]++; if (pr[i] == "must-have") { mh++; if (st[i] == "done") mhd++ } }
+ printf "stories\t%d\ndone\t%d\n", ns, c["done"] + 0
+ for (i = 1; i <= 6; i++) printf "status\t%s\t%d\n", names[i], c[names[i]] + 0
+ other = ns; for (i = 1; i <= 6; i++) other -= c[names[i]]
+ printf "status\tother\t%d\n", other
+ dp = pct(c["done"] + 0, ns, 0)
+ printf "done_pct\t%s\n", dp
+ if (tp != "-" && dp != "-") {
+ gap = tp - dp; printf "gap\t%d\n", gap
+ if (gap <= 10) printf "band\tOn Track\tgap <= 10\n"
+ else if (gap <= 25) printf "band\tAt Risk\t10 < gap <= 25\n"
+ else printf "band\tBehind\tgap > 25\n"
+ } else printf "gap\t-\nband\t-\tno dates or no stories\n"
+ printf "must_have\t%d\nmust_have_done\t%d\n", mh, mhd
+ printf "time_left_pct\t%s\n", (tp == "-") ? "-" : 100 - tp
+ printf "updated_days_ago\t%s\n", (upd == "") ? "-" : days(today) - days(upd)
+ }
+' "$YAML"
+exit 0
diff --git a/.claude/scripts/project-coherence.sh b/.claude/scripts/project-coherence.sh
index 8aedc4bd..6dc581e7 100644
--- a/.claude/scripts/project-coherence.sh
+++ b/.claude/scripts/project-coherence.sh
@@ -18,10 +18,10 @@
# desktop-focused"). Prose is in place and does not hold on its own. What was
# missing was a step that reads back what was written.
#
-# F1's root cause was subtler and is fixed elsewhere: `/setup-engine` is told to
-# write an `Installed at pin time` row into VERSION.md, and no VERSION.md had
-# such a row. There was no slot, so the step vanished leaving no trace. The row
-# now ships in all three reference files, and check 1 below reads it.
+# A subtler cause is handled elsewhere: `/setup-engine` writes an `Installed at
+# pin time` row into VERSION.md, and a VERSION.md with no such row leaves that
+# step no slot, so it vanishes without a trace. The row ships in all three
+# reference files, and check 1 below reads it.
#
# OBSERVATIONS, NEVER VERDICTS
#
@@ -137,10 +137,16 @@ case "$ENGINE_LC" in
# and smoke-check use. commands.* now carries the full editor path once
# /setup-engine has run, so a bare `command -v godot` alone reported "no
# Godot binary found on PATH" even on a correctly configured project.
+ # commands.test's program counts only when its file name says godot: a
+ # wrapper such as `bash run-tests.sh` is not the editor, and probing it
+ # compared bash's version with engine.version.
+ godot_named() {
+ case "$(printf '%s' "${1##*/}" | tr 'A-Z' 'a-z')" in *godot*) printf '%s' "$1" ;; esac
+ }
GEXE=""
for GCAND in \
- "$(yaml_block_value commands test | grep -oE '"[^"]*"' | head -1 | tr -d '"')" \
- "$(yaml_block_value commands test | awk '{print $1}')" \
+ "$(godot_named "$(yaml_block_value commands test | grep -oE '"[^"]*"' | head -1 | tr -d '"')")" \
+ "$(godot_named "$(yaml_block_value commands test | awk '{print $1}')")" \
"$(yaml_block_value engine path)" \
"godot"; do
[ -n "$GCAND" ] || continue
diff --git a/.claude/scripts/project-state.sh b/.claude/scripts/project-state.sh
new file mode 100644
index 00000000..eeb0ea19
--- /dev/null
+++ b/.claude/scripts/project-state.sh
@@ -0,0 +1,240 @@
+#!/usr/bin/env bash
+# project-state.sh — the project facts several skills work out by hand: is an
+# engine set, is there a concept, where is the code root, how many design,
+# architecture and production files exist, what stage the project says it is
+# at, and which phase the files on disk point to.
+#
+# Replaces the hand-run checks in /help (stage to phase, the artifact ladder),
+# /start (engine, concept, code root, counts, origin), /adopt, /onboard,
+# /day-one-patch, /project-stage-detect and /gate-check's read-back of the stage.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# `phase_inferred` is help's artifact ladder applied to the counts, printed with
+# the rule that matched; whether it outranks `stage` is the calling skill's call.
+#
+# Usage: bash .claude/scripts/project-state.sh [--stage] [--root DIR]
+# --stage print only the four stage rows (no file counts; cheap)
+# --root DIR the project to read; defaults to the repo this script is in
+# -h, --help this text
+#
+# Output: TSV, one `key<TAB>value<TAB>source` row per fact, in this order:
+# root, engine, code_root, source_files, concept, systems_index, gdd_files,
+# adr, story, prototype, sprint, milestone, origin_url,
+# stage_yaml, stage_txt, stage, phase, phase_inferred
+# `-` means no value. Every row is always printed, so a missing row is a bug,
+# never "nothing found".
+# engine engine.name: project.local.yaml, then project.yaml, then
+# the legacy `Engine:` line of .claude/docs/technical-preferences.md
+# code_root the same answer and source label as resolve_code_root in
+# .claude/hooks/yaml-helper.sh; never defaults to src
+# source_files `unknown` when code_root is unset: unknown is not zero
+# stage_yaml project.stage in project.yaml as written (even if invalid)
+# stage_txt first non-blank line of production/stage.txt as written
+# stage the resolved stage: a valid stage_yaml, else a valid
+# stage_txt, else `-` (the resolve_setting order)
+# phase the workflow-catalog phase key for `stage`
+#
+# Exit codes: 0 printed the facts; 1 the root is missing or unreadable;
+# 2 usage error. Reads only; never writes, never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk, sort and grep. Under a UTF-8 locale gawk's substr()
+# counts characters, so the 3-byte BOM test below would differ between awks.
+LC_ALL=C
+export LC_ALL
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+STAGE_ONLY=0
+ROOT_ARG=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --stage) STAGE_ONLY=1; shift ;;
+ --root)
+ [ $# -ge 2 ] || { echo "project-state: --root needs a value" >&2; exit 2; }
+ ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ *) echo "project-state: unknown argument: $1 (try --help)" >&2; exit 2 ;;
+ esac
+done
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "project-state: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "project-state: cannot reach the repo root" >&2; exit 1; }
+fi
+[ -f "$HERE/yaml-get.awk" ] || { echo "project-state: $HERE/yaml-get.awk is missing" >&2; exit 1; }
+# `pwd -W` (Git Bash) prints C:/..., the form the other helpers report.
+ROOT="$(pwd -W 2>/dev/null || pwd)"
+
+# The seven stage names, in order. The same list as project.stage in
+# yaml-helper.sh's _yaml_helper_enums; a value outside it is not a stage.
+STAGES="Concept|Systems Design|Technical Setup|Pre-Production|Production|Polish|Release"
+
+row() { printf '%s\t%s\t%s\n' "$1" "${2:--}" "${3:--}"; }
+
+is_stage() {
+ local v="$1" s oldIFS="$IFS"
+ IFS='|'
+ for s in $STAGES; do
+ if [ "$v" = "$s" ]; then IFS="$oldIFS"; return 0; fi
+ done
+ IFS="$oldIFS"
+ return 1
+}
+
+# yaml_get FILE DOTTED.PATH — print the scalar at the path, or nothing, with
+# yaml-get.awk, the reader the bash/awk helpers share (its header has the rules).
+yaml_get() {
+ [ -f "$1" ] || return 0
+ YG_PATH="$2" awk -f "$HERE/yaml-get.awk" "$1"
+}
+
+# First non-blank line of a plain-text mirror, CR and outer spaces removed,
+# inner spaces kept ("Systems Design"), as yaml-helper.sh get_legacy_key reads it.
+first_line() {
+ [ -f "$1" ] || return 0
+ awk '{ sub(/\r$/, ""); sub(/^[ \t]+/, ""); sub(/[ \t]+$/, "");
+ if (length($0) > 0) { printf "%s", $0; exit } }' "$1"
+}
+
+stage_rows() {
+ local sy st stage="" src="" phase=""
+ sy=$(yaml_get project.yaml project.stage)
+ st=$(first_line production/stage.txt)
+ if [ -n "$sy" ] && is_stage "$sy"; then stage="$sy"; src="project.yaml"
+ elif [ -n "$st" ] && is_stage "$st"; then stage="$st"; src="production/stage.txt"
+ fi
+ # help/SKILL.md Step 2's map from a stage name to a workflow-catalog phase key.
+ case "$stage" in
+ "Concept") phase="concept" ;;
+ "Systems Design") phase="systems-design" ;;
+ "Technical Setup") phase="technical-setup" ;;
+ "Pre-Production") phase="pre-production" ;;
+ "Production") phase="production" ;;
+ "Polish") phase="polish" ;;
+ "Release") phase="release" ;;
+ esac
+ if [ -f project.yaml ]; then row stage_yaml "$sy" project.yaml; else row stage_yaml "" absent; fi
+ if [ -f production/stage.txt ]; then row stage_txt "$st" production/stage.txt; else row stage_txt "" absent; fi
+ row stage "$stage" "${src:-unset}"
+ row phase "$phase" "$( [ -n "$phase" ] && echo stage || echo unset )"
+}
+
+if [ "$STAGE_ONLY" = 1 ]; then
+ stage_rows
+ exit 0
+fi
+
+# count DIR FIND-ARGS... — files find matches under DIR; 0 when DIR is absent.
+count() {
+ local d="$1"; shift
+ [ -d "$d" ] || { echo 0; return; }
+ find "$d" "$@" 2>/dev/null | wc -l | tr -d ' '
+}
+
+# --- engine and code root: resolve_code_root's three steps -----------------
+ENGINE=""; ESRC=""; CODE_ROOT=""; CSRC=""
+if [ -f project.local.yaml ]; then
+ ENGINE=$(yaml_get project.local.yaml engine.name)
+ [ -n "$ENGINE" ] && { ESRC="project.local.yaml"; CSRC="project.local.yaml"; }
+fi
+if [ -z "$ENGINE" ] && [ -f project.yaml ]; then
+ ENGINE=$(yaml_get project.yaml engine.name)
+ [ -n "$ENGINE" ] && { ESRC="project.yaml"; CSRC="engine.name"; }
+fi
+LEGACY=".claude/docs/technical-preferences.md"
+if [ -z "$ENGINE" ] && [ -f "$LEGACY" ]; then
+ # The legacy `Engine:` line, bold or bulleted; `[TO BE CONFIGURED]` and any
+ # other bracketed placeholder mean unset. The same pipeline as resolve_code_root.
+ ENGINE=$(grep -iE '^[[:space:]]*[-*]?[[:space:]]*\*{0,2}Engine\*{0,2}[[:space:]]*:' "$LEGACY" 2>/dev/null \
+ | head -1 | sed 's/.*://' | tr -d '\r' \
+ | sed 's/^[[:space:]]*//; s/[[:space:]].*$//; s/\*//g')
+ case "$ENGINE" in
+ *"[TO BE CONFIGURED]"*|"["*) ENGINE="" ;;
+ esac
+ [ -n "$ENGINE" ] && { ESRC="$LEGACY"; CSRC="$LEGACY"; }
+fi
+# The code root each engine's own toolchain builds from
+# (.claude/docs/directory-structure.md): Godot src/, Unity Assets/, Unreal Source/.
+case "$(printf '%s' "$ENGINE" | tr '[:upper:]' '[:lower:]')" in
+ godot) CODE_ROOT="src" ;;
+ unity) CODE_ROOT="Assets" ;;
+ unreal*) CODE_ROOT="Source" ;;
+esac
+if [ -z "$CODE_ROOT" ]; then
+ # No usable engine: believe the tree only when exactly one root is present.
+ # Names are compared exactly against the listing, never with `[ -d Assets ]`,
+ # which is also true for Godot's assets/ on a case-insensitive filesystem.
+ n=0; found=""
+ for d in */; do
+ d="${d%/}"
+ case "$d" in src|Assets|Source) found="$d"; n=$((n + 1)) ;; esac
+ done
+ if [ "$n" = 1 ]; then CODE_ROOT="$found"; CSRC="detected"; else CSRC=""; fi
+fi
+
+if [ -n "$CODE_ROOT" ]; then
+ # The source extensions detect-gaps.sh check 1 counts.
+ SRC_FILES=$(count "$CODE_ROOT" -type f \( -name '*.gd' -o -name '*.cs' -o -name '*.cpp' \
+ -o -name '*.c' -o -name '*.h' -o -name '*.hpp' -o -name '*.rs' -o -name '*.py' \
+ -o -name '*.js' -o -name '*.ts' \))
+ SSRC="$CODE_ROOT"
+else
+ SRC_FILES="unknown"; SSRC="code_root unset"
+fi
+
+CONCEPT=""
+for f in design/gdd/game-concept.md design/game-brief.md; do
+ [ -f "$f" ] && { CONCEPT="$f"; break; }
+done
+SYSIDX=""
+[ -f design/gdd/systems-index.md ] && SYSIDX="design/gdd/systems-index.md"
+
+GDD=$(count design/gdd -maxdepth 1 -type f -name '*.md')
+ADR=$(count docs/architecture -maxdepth 1 -type f -name 'adr-*.md')
+STORY=$(count production/epics -type f -name 'story-*.md')
+PROTO=$(count prototypes -mindepth 1 -maxdepth 1 -type d)
+SPRINT=$(count production/sprints -maxdepth 1 -type f -name '*.md')
+MILE=$(count production/milestones -maxdepth 1 -type f -name '*.md')
+
+ORIGIN=""
+if [ -f .git/config ]; then
+ ORIGIN=$(awk '
+ { sub(/\r$/, "") }
+ /^[ \t]*\[/ { inorigin = ($0 ~ /^[ \t]*\[remote "origin"\]/); next }
+ inorigin && /^[ \t]*url[ \t]*=/ { sub(/^[ \t]*url[ \t]*=[ \t]*/, ""); sub(/[ \t]+$/, ""); print; exit }
+ ' .git/config)
+fi
+
+row root "$ROOT" -
+row engine "$ENGINE" "${ESRC:-unset}"
+row code_root "$CODE_ROOT" "${CSRC:-unset}"
+row source_files "$SRC_FILES" "$SSRC"
+row concept "$CONCEPT" "$( [ -n "$CONCEPT" ] && echo found || echo absent )"
+row systems_index "$SYSIDX" "$( [ -n "$SYSIDX" ] && echo found || echo absent )"
+row gdd_files "$GDD" "design/gdd/*.md"
+row adr "$ADR" "docs/architecture/adr-*.md"
+row story "$STORY" "production/epics/**/story-*.md"
+row prototype "$PROTO" "prototypes/*/"
+row sprint "$SPRINT" "production/sprints/*.md"
+row milestone "$MILE" "production/milestones/*.md"
+row origin_url "$ORIGIN" "$( [ -f .git/config ] && echo .git/config || echo absent )"
+stage_rows
+
+# help/SKILL.md Step 2's ladder, most advanced match first. 10 is help's own
+# threshold for "the code root has real code in it".
+SRC_MIN=10
+NOTE=""
+[ "$SRC_FILES" = "unknown" ] && NOTE=";source_files unknown"
+if [ "$SRC_FILES" != "unknown" ] && [ "$SRC_FILES" -ge "$SRC_MIN" ]; then
+ row phase_inferred production "source_files>=$SRC_MIN"
+elif [ "$STORY" -ge 1 ]; then row phase_inferred pre-production "story>=1$NOTE"
+elif [ "$ADR" -ge 1 ]; then row phase_inferred technical-setup "adr>=1$NOTE"
+elif [ -n "$SYSIDX" ]; then row phase_inferred systems-design "systems_index$NOTE"
+elif [ -n "$CONCEPT" ]; then row phase_inferred concept "concept$NOTE"
+else row phase_inferred concept "nothing$NOTE"
+fi
+exit 0
diff --git a/.claude/scripts/read-guard.sh b/.claude/scripts/read-guard.sh
new file mode 100644
index 00000000..effb580e
--- /dev/null
+++ b/.claude/scripts/read-guard.sh
@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# read-guard.sh -- whether a Read is a whole-file read of a large design doc,
+# and that doc's headings, so it can be read by section instead. The hook
+# validate-read.sh calls `check` and refuses the read when it prints a LARGE
+# row; a skill or another tool's hook can call it the same way, because hooks
+# do not run in every tool.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+#
+# Usage: bash .claude/scripts/read-guard.sh [--root DIR] <command> <path> [options]
+# check <path> [--bounded yes|no]
+# what the guard sees for a read of <path> (project-relative):
+# --bounded yes when the read gives an offset or a limit
+# sections <path>
+# each markdown heading of <path> with its line number,
+# skipping lines inside ``` or ~~~ fences (a fence closes only
+# on a run of its own character at least as long)
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+#
+# Output of check: TSV rows, in this order
+# guard <on | off> <source> features.read_guard
+# threshold <bytes> <source> features.read_guard_kb x 1024
+# watched <yes | no> under design/, docs/architecture/ or
+# production/session-state/, and not an
+# image or a PDF
+# size <bytes | -> - when the file is not there
+# bounded <yes | no>
+# LARGE <path> <bytes> <threshold> only when the guard is on, the file is
+# watched, the read is unbounded and the
+# file is over the threshold
+# Output of sections: <line> TAB <heading line as written>
+#
+# Settings are read with yaml-get.awk, as the other helpers read project.yaml:
+# project.local.yaml, then project.yaml, then the default (on, 40 KB).
+# read_guard takes on or off, and true or false, YAML's other spelling of the
+# two; another value is passed over, and when no file sets a valid one the
+# guard row names it. The bar is file size, not lines, because token cost
+# follows bytes.
+#
+# Exit codes: 0 read (what it found is rows); 1 the root cannot be read;
+# 2 usage error. Reads only; never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+LC_ALL=C
+export LC_ALL
+
+usage() { echo "read-guard: $1 (try --help)" >&2; exit 2; }
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ROOT_ARG=""; CMD=""; RPATH=""; BOUNDED=no; NPOS=0
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root) [ $# -ge 2 ] || usage "--root needs a value"; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --bounded) [ $# -ge 2 ] || usage "--bounded needs yes or no"; BOUNDED="$2"; shift 2 ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# //; s/^#//'; exit 0 ;;
+ -*) usage "unknown option: $1" ;;
+ *) NPOS=$((NPOS + 1))
+ case $NPOS in 1) CMD="$1" ;; 2) RPATH="$1" ;; *) usage "too many arguments" ;; esac
+ shift ;;
+ esac
+done
+case "$CMD" in
+ check|sections) ;;
+ "") usage "no command" ;;
+ *) usage "unknown command: $CMD" ;;
+esac
+[ -n "$RPATH" ] || usage "$CMD needs a path"
+case "$BOUNDED" in yes|no) ;; *) usage "--bounded is yes or no, not $BOUNDED" ;; esac
+[ "$CMD" = sections ] && [ "$BOUNDED" = yes ] && usage "--bounded is for check"
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "read-guard: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "read-guard: cannot reach the repo root" >&2; exit 1; }
+fi
+RPATH=$(printf '%s' "$RPATH" | sed 's|\\|/|g; s|^\./||')
+
+if [ "$CMD" = sections ]; then
+ [ -f "$RPATH" ] || exit 0
+ # A fence opens on 3 or more ` or ~ after at most 3 spaces, and closes only
+ # on a run of the same character at least as long with nothing after it,
+ # so a ``` line inside a ```` or ~~~ fence stays inside.
+ awk 'BEGIN { BINMODE = 3 }
+ function run(s, c, k) { k = 0; while (substr(s, k + 1, 1) == c) k++; return k }
+ { sub(/\r$/, ""); l = $0; n = 0; while (n < 3 && substr(l, n + 1, 1) == " ") n++; l = substr(l, n + 1) }
+ fc != "" {
+ k = run(l, fc); r = substr(l, k + 1); sub(/^[ \t]+/, "", r)
+ if (k >= fl && r == "") fc = ""
+ next
+ }
+ { c = substr(l, 1, 1) }
+ (c == "`" || c == "~") && run(l, c) >= 3 { fc = c; fl = run(l, c); next }
+ /^#+[ \t]/ { print NR "\t" $0 }' "$RPATH"
+ exit 0
+fi
+
+# ------------------------------------------------------------------ check
+GUARD=on; GSRC=default; KB=40; KSRC=default
+# rg_get FILE KEY -- the value at KEY in FILE, or nothing.
+rg_get() { [ -f "$1" ] && YG_PATH="$2" awk -f "$HERE/yaml-get.awk" "$1"; }
+if [ -f "$HERE/yaml-get.awk" ]; then
+ _rgbad=""
+ for _rgf in project.local.yaml project.yaml; do
+ _rgv=$(rg_get "$_rgf" features.read_guard)
+ case "$_rgv" in
+ on|true) GUARD=on; GSRC="$_rgf"; break ;;
+ off|false) GUARD=off; GSRC="$_rgf"; break ;;
+ "") ;;
+ *) [ -n "$_rgbad" ] || _rgbad="$_rgv" ;;
+ esac
+ done
+ [ "$GSRC" = default ] && [ -n "$_rgbad" ] && GSRC="default (read_guard is $_rgbad, not on or off)"
+ # The first file that sets read_guard_kb decides it, whole number or not.
+ for _rgf in project.local.yaml project.yaml; do
+ _rgv=$(rg_get "$_rgf" features.read_guard_kb)
+ [ -n "$_rgv" ] || continue
+ case "$_rgv" in
+ *[!0-9]*|0) KSRC="default (read_guard_kb is $_rgv, not a whole number of KB)" ;;
+ *) KB="$_rgv"; KSRC="$_rgf" ;;
+ esac
+ break
+ done
+else
+ GSRC="default (yaml-get.awk missing)"; KSRC="$GSRC"
+fi
+LIMIT=$((KB * 1024))
+
+WATCHED=no
+case "$RPATH" in
+ design/*|docs/architecture/*|production/session-state/*) WATCHED=yes ;;
+esac
+# Images and PDFs are read whole by the Read tool's own rules, not by lines.
+shopt -s nocasematch
+case "$RPATH" in *.png|*.jpg|*.jpeg|*.gif|*.webp|*.bmp|*.ico|*.pdf|*.ipynb) WATCHED=no ;; esac
+shopt -u nocasematch
+
+SIZE=-
+[ -f "$RPATH" ] && SIZE=$(wc -c < "$RPATH" | tr -d ' ')
+
+printf 'guard\t%s\t%s\nthreshold\t%s\t%s\nwatched\t%s\nsize\t%s\nbounded\t%s\n' \
+ "$GUARD" "$GSRC" "$LIMIT" "$KSRC" "$WATCHED" "$SIZE" "$BOUNDED"
+if [ "$GUARD" = on ] && [ "$WATCHED" = yes ] && [ "$BOUNDED" = no ] && [ "$SIZE" != - ] && [ "$SIZE" -gt "$LIMIT" ]; then
+ printf 'LARGE\t%s\t%s\t%s\n' "$RPATH" "$SIZE" "$LIMIT"
+fi
+exit 0
diff --git a/.claude/scripts/registry.sh b/.claude/scripts/registry.sh
new file mode 100644
index 00000000..47d4fe64
--- /dev/null
+++ b/.claude/scripts/registry.sh
@@ -0,0 +1,773 @@
+#!/usr/bin/env bash
+# registry.sh — the three registries read one way, and the next ID of every
+# kind the skills number: the entity registry (design/registry/entities.yaml),
+# the TR-ID registry (docs/architecture/tr-registry.yaml) and the architecture
+# registry (docs/registry/architecture.yaml). A skill asks this script instead
+# of writing its own grep per entity or per TR-ID, so every skill reads the
+# same entries the same way.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# validate lists what it found. Whether a missing path matters, or a story may
+# cite a deprecated TR-ID, is the calling skill's rule.
+#
+# Usage: bash .claude/scripts/registry.sh [--root DIR] COMMAND [ARGS]
+# list [REGISTRY] [--system SLUG]
+# one row per entry; REGISTRY is entities, tr or architecture
+# (all three when left out); --system keeps the TR-IDs of
+# one system slug (TR-combat-001, not TR-combat-ai-001)
+# get NAME ... each entry named NAME (an entity name, a TR-ID, or a
+# state, contract, system, purpose or pattern): its row, then
+# its lines as the file has them
+# refs NAME|PATH for a NAME, each path its entry names, and for a TR-ID each
+# story or epic line under production/epics/ that cites it;
+# for a PATH (it holds a /), every entry that names it
+# slice PATH every entry that names PATH as its source, gdd or adr or in
+# referenced_by: its row, then its lines
+# validate duplicate names, TR-IDs cited under production/epics/ that
+# the registry lacks, paths that do not exist, status values
+# outside the allowed list, and unsupported layout
+# compare REGISTRY OLD [NEW]
+# one registry before and after a change: each entry OLD
+# has that NEW lacks (the registries are append-only), each
+# status the change sets outside the allowed list, and
+# NEW's unsupported layout. OLD and NEW are files holding
+# that registry; NEW defaults to the registry itself
+# next-id KIND [SCOPE]
+# the next ID: the highest one seen plus one, so a deleted or
+# deprecated ID is never handed out again. KIND and SCOPE:
+# tr SLUG TR-SLUG-NNN, from the TR registry
+# adr ADR-NNNN, from docs/architecture/adr-NNNN-*.md
+# bug BUG-NNNN, from production/qa/bugs/BUG-*.md
+# asset ASSET-NNN, from design/assets/asset-manifest.md
+# and the spec files in design/assets/specs/
+# td TD-NNN, from docs/tech-debt-register.md
+# story EPIC story-NNN, from production/epics/EPIC/story-*.md
+# sprint sprint-NNN, from production/sprints/sprint-N.md
+# season SN, from design/live-ops/seasons/SN_*.md
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+#
+# The layout it reads (each registry's header says so on its LAYOUT line):
+# - a section is a key at column 0 holding a block list, or [] while empty
+# - an entry starts "- KEY: VALUE", the dash at column 0 or 2 and the same
+# column for every entry of a section; KEY is the section's name key
+# (name; id; state, contract, system or target_fps, purpose, pattern) and
+# VALUE is the entry's name
+# - its fields sit two columns past the dash; a deeper line belongs to the
+# field above it; a list under a field may also sit at the field's column
+# - a value holding ": " is quoted; a flow list or map stays on one line
+# - a value of | or > (with any indicators) is multi-line text: the lines
+# deeper than its key are that text, never fields or entries
+# Anything else is reported as LAYOUT, with the line and the layout expected
+# there, and that registry's entries are left out rather than guessed. One
+# unquoted value is read anyway: the architecture registry's
+# `status: superseded_by: ADR-NNNN`, as /architecture-decision wrote it before
+# 1.2.0. It is read as the status `superseded_by: ADR-NNNN`, the entries are
+# listed, and an UNQUOTED row names the line to quote.
+#
+# Output: TSV, `-` where a value is not there.
+# registry <name> <path> <entries | missing | layout> first, per registry read
+# ENTRY <registry> <section> <key> <name> <status> <source> <line>
+# source: the source field (entities), gdd (tr) or adr (architecture)
+# REF <registry> <name> <how> <path> <line>
+# how: source | gdd | adr | referenced_by, or cited (a story or epic line)
+# LAYOUT <registry> <path> <found> <expected> <line>
+# UNQUOTED <registry> <path> <value> <the line as it should read> <line>
+# the unquoted superseded status above, read as <value>; after the
+# other rows of every command but next-id, and it changes no exit code
+# NOT_FOUND <name>
+# validate: checked production/epics <files>, then the counts duplicate,
+# tr_unknown, path_missing, status and layout, then the rows
+# DUPLICATE <registry> <section> <name> <lines>
+# TR_UNKNOWN <tr-id> <path> <line>
+# PATH_MISSING <registry> <name> <field> <path> <line>
+# STATUS <registry> <name> <value> <allowed> <line>
+# LAYOUT rows, then UNQUOTED rows
+# a path is missing when test -e fails on it, so a directory exists
+# compare: the registry rows of OLD, then NEW; the counts removed (- when
+# either side is missing or has unsupported layout, so its entries are not
+# known; 0 when OLD is missing, as a new file removes nothing), status and
+# layout; then the rows
+# REMOVED <registry> <section> <name> <line in OLD>
+# STATUS rows, for an entry NEW adds or whose status NEW changes (one
+# already outside the list in OLD is validate's to report)
+# LAYOUT rows, OLD's and NEW's (the path column tells them apart),
+# then UNQUOTED rows the same way
+# next-id: next <kind> <scope | -> <id> <highest | -> <ids seen> (no other row)
+#
+# Exit codes: 0 answered; 1 the root cannot be read; 2 usage error; 3 a NAME
+# matched no entry (its NOT_FOUND row is printed); 4 a registry the command
+# reads has an unsupported layout (its LAYOUT rows are printed). validate and
+# compare exit 0 whenever they ran: what they find is rows. Reads only; never
+# writes.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk and find.
+LC_ALL=C
+export LC_ALL
+
+usage() { echo "registry: $1 (try --help)" >&2; exit 2; }
+# A system or epic slug: lowercase words joined by single hyphens, as the
+# TR-ID format and the epic folder names write them.
+is_slug() { printf '%s' "$1" | grep -Eq '^[a-z0-9]+(-[a-z0-9]+)*$'; }
+# A path made absolute against the current directory; C:/ and C:\ count as
+# absolute, the forms Git Bash and Windows callers pass.
+abs_path() {
+ case "$1" in
+ /*|[A-Za-z]:[\\/]*) printf '%s' "$1" ;;
+ *) printf '%s/%s' "$PWD" "${1#./}" ;;
+ esac
+}
+
+ROOT_ARG=""
+POS=()
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root)
+ [ $# -ge 2 ] || usage "--root needs a value"
+ ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# //; s/^#//'; exit 0 ;;
+ *) POS[${#POS[@]}]="$1"; shift ;;
+ esac
+done
+[ ${#POS[@]} -gt 0 ] || usage "no command"
+CMD="${POS[0]}"
+NARG=$((${#POS[@]} - 1))
+
+# The registries, in the order every command reports them.
+REGS="entities tr architecture"
+reg_path() {
+ case "$1" in
+ entities) echo "design/registry/entities.yaml" ;;
+ tr) echo "docs/architecture/tr-registry.yaml" ;;
+ architecture) echo "docs/registry/architecture.yaml" ;;
+ esac
+}
+
+READ="$REGS"; SCAN=0; RG_REG=""; RG_SYS=""; RG_ARG=""; RG_NAMES=""
+NL='
+'
+case "$CMD" in
+ list)
+ i=1
+ while [ $i -le $NARG ]; do
+ a="${POS[$i]}"
+ case "$a" in
+ --system)
+ [ $i -lt $NARG ] || usage "--system needs a slug"
+ i=$((i + 1)); RG_SYS="${POS[$i]}"
+ is_slug "$RG_SYS" || usage "not a system slug: $RG_SYS" ;;
+ entities|tr|architecture)
+ [ -z "$RG_REG" ] || usage "one registry at most"
+ RG_REG="$a" ;;
+ *) usage "unknown argument to list: $a" ;;
+ esac
+ i=$((i + 1))
+ done
+ if [ -n "$RG_SYS" ]; then
+ [ -z "$RG_REG" ] || [ "$RG_REG" = tr ] || usage "--system reads the tr registry only"
+ RG_REG=tr
+ fi
+ [ -z "$RG_REG" ] || READ="$RG_REG" ;;
+ get)
+ [ $NARG -ge 1 ] || usage "get needs a name"
+ i=1
+ while [ $i -le $NARG ]; do RG_NAMES="$RG_NAMES${POS[$i]}$NL"; i=$((i + 1)); done ;;
+ refs)
+ [ $NARG -eq 1 ] || usage "refs takes one name or path"
+ RG_ARG="${POS[1]}"
+ case "$RG_ARG" in */*) RG_ARG="${RG_ARG#./}" ;; *) SCAN=1 ;; esac ;;
+ slice)
+ [ $NARG -eq 1 ] || usage "slice takes one path"
+ RG_ARG="${POS[1]#./}" ;;
+ validate)
+ [ $NARG -eq 0 ] || usage "validate takes no arguments"
+ SCAN=1 ;;
+ compare)
+ { [ $NARG -ge 2 ] && [ $NARG -le 3 ]; } || usage "compare takes a registry, the old file and optionally the new one"
+ RG_REG="${POS[1]}"
+ case "$RG_REG" in entities|tr|architecture) ;; *) usage "not a registry: $RG_REG" ;; esac
+ # Read from the directory the caller is in, before --root moves it, and
+ # shown as the caller wrote them.
+ CMP_OLD=$(abs_path "${POS[2]}"); CMP_OLD_AS="${POS[2]}"; CMP_NEW=""; CMP_NEW_AS=""
+ if [ $NARG -eq 3 ]; then CMP_NEW=$(abs_path "${POS[3]}"); CMP_NEW_AS="${POS[3]}"; fi
+ [ "$CMP_OLD" != "$CMP_NEW" ] || usage "the old and new files are the same path"
+ READ="" ;;
+ next-id)
+ [ $NARG -ge 1 ] || usage "next-id needs a kind"
+ KIND="${POS[1]}"
+ case "$KIND" in
+ tr|story)
+ [ $NARG -eq 2 ] || usage "next-id $KIND takes one slug"
+ is_slug "${POS[2]}" || usage "not a slug: ${POS[2]}"
+ RG_ARG="${POS[2]}" ;;
+ adr|bug|asset|td|sprint|season)
+ [ $NARG -eq 1 ] || usage "next-id $KIND takes no scope" ;;
+ *) usage "unknown ID kind: $KIND" ;;
+ esac
+ READ="tr" ;;
+ *) usage "unknown command: $CMD" ;;
+esac
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "registry: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$(dirname "$0")/../.." 2>/dev/null || { echo "registry: cannot reach the repo root" >&2; exit 1; }
+fi
+
+# --------------------------------------------------------- next-id, file kinds
+# next_seen KIND SCOPE FORMAT MODE PATTERN FILES...
+# MODE names: PATTERN (anchored) is matched against each file's name.
+# MODE text: every PATTERN in the files' text, not inside a longer word.
+# The number is the first digit run in the match; the row gives the next
+# one in FORMAT, the highest seen and how many distinct numbers were seen.
+next_seen() {
+ _k="$1"; _s="$2"; _f="$3"; _m="$4"; _p="$5"; shift 5
+ { for _x in "$@"; do printf '%s\n' "$_x"; done; } | \
+ K="$_k" S="$_s" F="$_f" M="$_m" P="$_p" awk '
+ BEGIN {
+ BINMODE = 3; max = -1; n = 0
+ while ((getline f < "/dev/stdin") > 0) {
+ if (f == "") continue
+ if (ENVIRON["M"] == "names") { b = f; sub(/^.*\//, "", b); take(b, 1) }
+ else ARGV[ARGC++] = "./" f
+ }
+ }
+ function take(s, anchored, base, rest, abs, pre, aft, m, d) {
+ base = 0; rest = s
+ while (match(rest, ENVIRON["P"])) {
+ abs = base + RSTART
+ pre = (abs > 1) ? substr(s, abs - 1, 1) : ""
+ aft = substr(s, abs + RLENGTH, 1)
+ if ((anchored && abs == 1) || (!anchored && pre !~ /[A-Za-z0-9-]/ && aft !~ /[A-Za-z0-9]/)) {
+ m = substr(s, abs, RLENGTH); match(m, /[0-9]+/); d = substr(m, RSTART, RLENGTH) + 0
+ if (!(d in seen)) { seen[d] = 1; n++ }
+ if (d > max) max = d
+ }
+ if (anchored) return
+ base = abs + RLENGTH - 1; rest = substr(s, base + 1)
+ }
+ }
+ { line = $0; sub(/\r$/, "", line); take(line, 0) }
+ END {
+ printf "next\t%s\t%s\t" ENVIRON["F"] "\t", ENVIRON["K"], ENVIRON["S"], max + 1 + (max < 0)
+ if (max < 0) printf "-"; else printf ENVIRON["F"], max
+ printf "\t%d\n", n
+ }'
+}
+# files DIR NAME-GLOB [-i] — the files directly in DIR whose name matches, sorted.
+files() {
+ [ -d "$1" ] || return 0
+ if [ "${3:-}" = "-i" ]; then find "$1" -maxdepth 1 -type f -iname "$2" | sort
+ else find "$1" -maxdepth 1 -type f -name "$2" | sort; fi
+}
+
+if [ "$CMD" = next-id ] && [ "$KIND" != tr ]; then
+ # Padding per kind is what the skills that number them write: ADR and BUG
+ # four digits, the rest three (season none). Starting numbers are 1.
+ # (pat) with its opening paren: bash 3.2 misparses a bare pat) inside $( ).
+ NLIST=$(case "$KIND" in
+ (adr) files docs/architecture 'adr-*.md' ;;
+ (bug) files production/qa/bugs 'bug-*.md' -i ;;
+ (asset) [ -f design/assets/asset-manifest.md ] && echo design/assets/asset-manifest.md
+ files design/assets/specs '*.md' ;;
+ (td) [ -f docs/tech-debt-register.md ] && echo docs/tech-debt-register.md ;;
+ (story) files "production/epics/$RG_ARG" 'story-*.md' ;;
+ (sprint) files production/sprints 'sprint-*.md' ;;
+ (season) files design/live-ops/seasons 'S*_*' ;;
+ esac)
+ # One path per line; split on newlines only, so a name with a space holds.
+ OLDIFS=$IFS; IFS=$NL; set -f
+ # shellcheck disable=SC2086
+ set -- $NLIST
+ set +f; IFS=$OLDIFS
+ case "$KIND" in
+ adr) next_seen adr - 'ADR-%04d' names '^adr-[0-9]+' "$@" ;;
+ bug) next_seen bug - 'BUG-%04d' names '^[Bb][Uu][Gg]-[0-9]+' "$@" ;;
+ asset) next_seen asset - 'ASSET-%03d' text 'ASSET-[0-9]+' "$@" ;;
+ td) next_seen td - 'TD-%03d' text 'TD-[0-9]+' "$@" ;;
+ story) next_seen story "$RG_ARG" 'story-%03d' names '^story-[0-9]+' "$@" ;;
+ # Only sprint-<digits>.md is a plan: a retrospective sharing the folder
+ # (sprint-3-retrospective.md) is not, as plan-math.sh reads the folder.
+ sprint) next_seen sprint - 'sprint-%03d' names '^sprint-[0-9]+\.md$' "$@" ;;
+ season) next_seen season - 'S%d' names '^S[0-9]+_' "$@" ;;
+ esac
+ exit 0
+fi
+
+# ------------------------------------------------------------------ registries
+LIST=""
+for r in $READ; do
+ p=$(reg_path "$r")
+ if [ -f "$p" ]; then LIST="${LIST}R $r $p$NL"; else LIST="${LIST}M $r $p$NL"; fi
+done
+if [ "$CMD" = compare ]; then
+ # OLD first, then NEW: the awk tells them apart by that order. The fourth
+ # field is the path as shown.
+ if [ -z "$CMP_NEW" ]; then CMP_NEW=$(reg_path "$RG_REG"); CMP_NEW_AS="$CMP_NEW"; fi
+ for p in "$CMP_OLD $CMP_OLD_AS" "$CMP_NEW $CMP_NEW_AS"; do
+ if [ -f "${p%% *}" ]; then LIST="${LIST}R $RG_REG $p$NL"; else LIST="${LIST}M $RG_REG $p$NL"; fi
+ done
+fi
+if [ "$SCAN" = 1 ] && [ -d production/epics ]; then
+ while IFS= read -r f; do
+ [ -n "$f" ] && LIST="${LIST}S - ${f#./}$NL"
+ done <<EOF
+$(find production/epics -type f -name '*.md' | sort)
+EOF
+fi
+
+# One awk: each registry is read once, line by line, into entries; the story
+# and epic files are scanned for TR-IDs; END answers the command. The file list
+# goes in on stdin, never as arguments (a long list passes the command-line
+# limit of some systems); "./" in front keeps a name like x=1.md a file name.
+# An absolute path (compare's files) goes in as it is: a name starting with /
+# or C: cannot read as an assignment.
+printf '%s' "$LIST" | \
+RG_CMD="$CMD" RG_REG="$RG_REG" RG_SYS="$RG_SYS" RG_ARG="$RG_ARG" RG_NAMES="$RG_NAMES" awk '
+ BEGIN {
+ # Git for Windows gawk reads files in text mode; BINMODE keeps the bytes.
+ BINMODE = 3
+ # The field that holds each registry entry'"'"'s authoritative path.
+ SRCF["entities"] = "source"; SRCF["tr"] = "gdd"; SRCF["architecture"] = "adr"
+ # The name key an entry of each documented section starts with; a section
+ # not listed here (one a project added) may start with any key.
+ split("entities items formulas constants", t, " ")
+ for (i = 1; i <= 4; i++) NK["entities", t[i]] = "name"
+ NK["tr", "requirements"] = "id"
+ NK["architecture", "state_ownership"] = "state"
+ NK["architecture", "interfaces"] = "contract"
+ NK["architecture", "performance_budgets"] = "system target_fps"
+ NK["architecture", "api_decisions"] = "purpose"
+ NK["architecture", "forbidden_patterns"] = "pattern"
+ # The status values each registry documents in its header.
+ ALLOWED["entities"] = "active|deprecated"
+ ALLOWED["tr"] = "active|deprecated|\"superseded-by: TR-<system>-NNN\""
+ ALLOWED["architecture"] = "active|\"superseded_by: ADR-NNNN\""
+ # A TR-ID: TR-, a slug of lowercase words joined by hyphens, -, digits.
+ TRID = "TR-[a-z0-9]+(-[a-z0-9]+)*-[0-9]+"
+ SQ = sprintf("%c", 39)
+ cmd = ENVIRON["RG_CMD"]; nreg = 0; nscan = 0; ne = 0; nlay = 0; ncite = 0; nunq = 0
+ while ((getline l < "/dev/stdin") > 0) {
+ split(l, p, "\t")
+ a = (p[3] ~ /^\// || p[3] ~ /^[A-Za-z]:/) ? p[3] : "./" p[3]
+ if (p[1] == "S") { nscan++; KIND[a] = "S"; ARGV[ARGC++] = a; continue }
+ nreg++; RN[nreg] = p[2]; RP[nreg] = (4 in p) ? p[4] : p[3]; RMISS[nreg] = (p[1] == "M")
+ if (p[1] == "R") { KIND[a] = "R"; RIDX[a] = nreg; ARGV[ARGC++] = a }
+ }
+ cur_r = 0
+ }
+
+ function layout(found, expected, ln) {
+ nlay++; LR[nlay] = cur_r; LF[nlay] = found; LE[nlay] = expected; LL[nlay] = (ln == "") ? FNR : ln
+ BAD[cur_r] = 1
+ }
+ # The closing quote q in s (a backslash escapes a double quote; two single
+ # quotes are one), or 0.
+ function qclose(s, q, i, c) {
+ for (i = 1; i <= length(s); i++) {
+ c = substr(s, i, 1)
+ if (q == "\"" && c == "\\") { i++; continue }
+ if (c == q) { if (q == "'"'"'" && substr(s, i + 1, 1) == "'"'"'") { i++; continue } return i }
+ }
+ return 0
+ }
+ # "key: value" or "key:" -> K and V; 0 when s does not start with a plain key.
+ function keysplit(s, p) {
+ p = index(s, ": ")
+ if (p == 0 && substr(s, length(s)) == ":") p = length(s)
+ if (p <= 1) return 0
+ K = substr(s, 1, p - 1); V = substr(s, p + 1)
+ sub(/^[ \t]+/, "", V); sub(/[ \t]+$/, "", V)
+ return (K ~ /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/)
+ }
+ # A value -> PV (its text), PQ (its quote, if quoted), PUNCL (the quote does
+ # not close on this line), PFLOW / PFLOWOPEN (a [..] or {..} and whether it
+ # runs past the line), PBLOCK (| or >), PCOLON (plain, holding ": ").
+ function pval(v, c, rest, i, h, closer) {
+ PV = ""; PQ = ""; PUNCL = 0; PFLOW = 0; PFLOWOPEN = 0; PBLOCK = 0; PCOLON = 0
+ if (v == "") return
+ c = substr(v, 1, 1)
+ if (c == "#") return
+ if (c == "\"" || c == "'"'"'") {
+ PQ = c; rest = substr(v, 2); i = qclose(rest, c)
+ if (i == 0) { PUNCL = 1; PV = rest; return }
+ PV = substr(rest, 1, i - 1)
+ if (c == "'"'"'") gsub(/'"''"'/, "'"'"'", PV); else gsub(/\\"/, "\"", PV)
+ return
+ }
+ if (c == "[" || c == "{") {
+ PFLOW = 1; h = v; i = index(h, " #"); if (i > 0) h = substr(h, 1, i - 1)
+ sub(/[ \t]+$/, "", h); closer = (c == "[") ? "]" : "}"
+ if (substr(h, length(h)) != closer) PFLOWOPEN = 1
+ PV = h; return
+ }
+ if (v ~ /^[|>][-+0-9]*([ \t]+#.*)?$/) { PBLOCK = 1; return }
+ i = index(v, " #"); if (i > 0) v = substr(v, 1, i - 1)
+ sub(/[ \t]+$/, "", v); PV = v
+ if (index(v, ": ") > 0 || substr(v, length(v)) == ":") PCOLON = 1
+ }
+ function addref(e, how, path, ln) {
+ if (path == "") return
+ NR_[e]++; RFP[e, NR_[e]] = path; RFH[e, NR_[e]] = how; RFL[e, NR_[e]] = ln
+ if (how == SRCF[RN[cur_r]] && ESRC[e] == "") ESRC[e] = path
+ }
+ function close_entry() { inentry = 0; cf = ""; cflist = 0; cfplain = 0 }
+ function open_entry() {
+ ne++; ER[ne] = cur_r; ES[ne] = sec; EL[ne] = FNR; EE[ne] = FNR
+ EK[ne] = ""; EN[ne] = ""; ESRC[ne] = ""; NR_[ne] = 0; ESTSET[ne] = 0
+ cur = ne; inentry = 1; cf = ""; cflist = 0; cfplain = 0; listcol = -1
+ }
+ function start_reg(r) {
+ cur_r = r; sec = ""; secempty = 0; dcol = -1; fcol = -1; inq = ""; inq_line = 0; blk = -1; close_entry()
+ }
+ # opens(s, n): when line s (at indent n, its leading spaces removed) opens a
+ # block scalar (a value of | or >, with any indicators), the indent its text
+ # must exceed; else -1. The text is never a section, an entry, a field or a
+ # tab in the indent: yaml-get.awk reads by the same rule.
+ function opens(s, n, r, p, v) {
+ r = s
+ if (r == "-" || substr(r, 1, 2) == "- ") {
+ r = substr(r, 2); sub(/^ +/, "", r)
+ if (r ~ /^[|>][-+0-9]*[ \t]*(#.*)?$/) return n
+ n = n + length(s) - length(r)
+ }
+ if (r == "" || r ~ /^[:# \t]/) return -1
+ p = index(r, ":"); if (p == 0) return -1
+ v = substr(r, p + 1); sub(/^[ \t]+/, "", v); sub(/[ \t]+$/, "", v)
+ return (v ~ /^[|>][-+0-9]*[ \t]*(#.*)?$/) ? n : -1
+ }
+ function end_reg() {
+ if (cur_r && inq != "") layout("a quote that never closes", "the closing quote", inq_line)
+ inq = ""
+ }
+ # The superseded status 1.1.x wrote into the architecture registry without
+ # quotes: status: superseded_by: <id>, with no other ": " after it.
+ function legacy_status(v, rest) {
+ if (RN[cur_r] != "architecture" || K != "status" || substr(v, 1, 15) != "superseded_by: ") return 0
+ rest = substr(v, 16)
+ return rest != "" && index(rest, ": ") == 0 && substr(rest, length(rest)) != ":"
+ }
+ # A field line: KEY (K) and its raw value (V) at the field column.
+ function field(ln) {
+ pval(V)
+ cf = K; listcol = -1
+ cflist = (PV == "" && PQ == "" && !PFLOW && !PBLOCK)
+ cfplain = (!cflist && !PBLOCK && !PUNCL)
+ EE[cur] = ln
+ if (PCOLON && legacy_status(PV)) { nunq++; UR[nunq] = cur_r; UV[nunq] = PV; UL[nunq] = ln }
+ else if (PCOLON) layout("an unquoted value holding \": \"", "the value in quotes")
+ if (PFLOWOPEN) layout("a flow list or map that runs past its line", "[a, b] on one line, or a block list")
+ if (PUNCL) { inq = PQ; inq_line = ln }
+ if (K == "status") { EST[cur] = PV; ESTL[cur] = ln; ESTSET[cur] = 1 }
+ if (K == SRCF[RN[cur_r]]) addref(cur, K, PV, ln)
+ if (K == "referenced_by" && PFLOW && !PFLOWOPEN) flow_refs(PV, ln)
+ }
+ function flow_refs(v, ln, n, a, i, it) {
+ v = substr(v, 2, length(v) - 2)
+ n = split(v, a, ",")
+ for (i = 1; i <= n; i++) {
+ it = a[i]; sub(/^[ \t]+/, "", it); sub(/[ \t]+$/, "", it)
+ pval(it); addref(cur, "referenced_by", PV, ln)
+ }
+ }
+ function list_item(s, ln) {
+ if (cf != "referenced_by") return
+ pval(substr(s, 3)); addref(cur, "referenced_by", PV, ln)
+ }
+ # A line deeper than the field column: part of the field above it.
+ function deeper(n, s) {
+ EE[cur] = FNR
+ if (cflist) {
+ if (s == "-" || substr(s, 1, 2) == "- ") {
+ if (listcol == -1) listcol = n
+ if (n == listcol) list_item(s, FNR)
+ }
+ return
+ }
+ if (cfplain && (index(s, ": ") > 0 || substr(s, length(s)) == ":"))
+ layout("a key at column " n " under the value of " cf ":", "a field at column " fcol ", or the value in quotes")
+ }
+ function top_line(s, known) {
+ close_entry(); sec = ""; secempty = 0; dcol = -1
+ if (s == "---" || s == "...") return
+ if (!keysplit(s)) { layout("text with no key", "key: value at column 0"); return }
+ pval(V)
+ if (PV == "" && PQ == "" && !PFLOW && !PBLOCK) { sec = K; return }
+ if (PFLOW && PV == "[]") { sec = K; secempty = 1; return }
+ if ((RN[cur_r], K) in NK) layout("a value after " K ":", "[] or nothing after " K ":, the entries below")
+ }
+ function dash_line(n, s, rest, nk, first) {
+ if (sec == "") { close_entry(); layout("a list item outside a section", "a section key at column 0 above it"); return }
+ if (secempty) { layout("a list item under " sec ": []", "nothing after " sec ": when it has entries"); return }
+ if (inentry && n > dcol) {
+ if (n > fcol) { deeper(n, s); return }
+ if (n == fcol && cflist && (listcol == -1 || listcol == fcol)) { listcol = fcol; EE[cur] = FNR; list_item(s, FNR); return }
+ if (n == fcol) { layout("a list item at column " fcol, "a field at column " fcol ", or a list under a field with no value"); return }
+ layout("a list item at column " n, "column " dcol " for the next entry, or deeper than column " fcol); return
+ }
+ close_entry()
+ if (dcol == -1) {
+ # The two columns the shipped registries use: 0 (tr-registry.yaml) and
+ # 2 (entities.yaml, architecture.yaml). Another column is reported, then
+ # taken, so the lines below it are still checked.
+ if (n != 0 && n != 2) layout("a list item at column " n, "column 0 or 2")
+ dcol = n; fcol = n + 2
+ } else if (n != dcol) {
+ layout("a list item at column " n, "column " dcol ", like the first entry of " sec); return
+ }
+ open_entry()
+ rest = (s == "-") ? "" : substr(s, 3)
+ if (!keysplit(rest)) { layout("an entry with no key", "- key: value"); return }
+ nk = ((RN[cur_r], sec) in NK) ? NK[RN[cur_r], sec] : ""
+ if (nk != "" && index(" " nk " ", " " K " ") == 0) {
+ first = nk; sub(/ .*/, "", first)
+ layout("an entry that starts with " K ":", "- " first ": as the first line of each entry")
+ }
+ pval(V)
+ if (PV == "" && PQ == "" && !PFLOW && !PUNCL) layout("an entry with an empty " K, "- " K ": <name>")
+ EK[cur] = K; EN[cur] = PV
+ field(FNR)
+ }
+ function plain_line(n, s) {
+ if (sec == "") { layout("an indented line outside a section", "a section key at column 0 above it"); return }
+ if (!inentry) { layout("a line at column " n " before any entry", "- key: value at column 0 or 2"); return }
+ if (n > fcol) { deeper(n, s); return }
+ if (n < fcol) { layout("a line at column " n, "a field at column " fcol ", two past the dash"); return }
+ if (!keysplit(s)) { layout("text with no key at column " fcol, "key: value"); return }
+ field(FNR)
+ }
+ function reg_line(line, t, n, s) {
+ RAW[cur_r, FNR] = line
+ if (inq != "") { if (qclose(line, inq)) inq = ""; if (inentry) EE[cur] = FNR; return }
+ t = line; sub(/^[ \t]+/, "", t)
+ if (t == "" || substr(t, 1, 1) == "#") return
+ n = 0; while (substr(line, n + 1, 1) == " ") n++
+ if (blk >= 0) { if (n > blk) { if (inentry) EE[cur] = FNR; return } blk = -1 }
+ if (line ~ /^ *\t/) { layout("a tab in the indent", "spaces only"); return }
+ s = substr(line, n + 1)
+ blk = opens(s, n)
+ if (s == "-" || substr(s, 1, 2) == "- ") { dash_line(n, s); return }
+ if (n == 0) { top_line(s); return }
+ plain_line(n, s)
+ }
+ function scan_line(line, file, base, rest, abs, pre, aft) {
+ base = 0; rest = line
+ while (match(rest, TRID)) {
+ abs = base + RSTART
+ pre = (abs > 1) ? substr(line, abs - 1, 1) : ""
+ aft = substr(line, abs + RLENGTH, 1)
+ if (pre !~ /[A-Za-z0-9-]/ && aft !~ /[A-Za-z0-9]/) { ncite++; CI[ncite] = substr(line, abs, RLENGTH); CF[ncite] = file; CL[ncite] = FNR }
+ base = abs + RLENGTH - 1; rest = substr(line, base + 1)
+ }
+ }
+
+ FNR == 1 {
+ end_reg(); cur_r = 0
+ fk = KIND[FILENAME]; fname = substr(FILENAME, 3)
+ if (fk == "R") start_reg(RIDX[FILENAME])
+ }
+ {
+ line = $0; sub(/\r$/, "", line)
+ # "\357\273\277" is the UTF-8 byte-order mark.
+ if (FNR == 1 && substr(line, 1, 3) == "\357\273\277") line = substr(line, 4)
+ if (fk == "R") reg_line(line); else scan_line(line, fname)
+ }
+
+ function tsv(s) { gsub(/\t/, " ", s); return (s == "") ? "-" : s }
+ function ok(e) { return !BAD[ER[e]] }
+ function entry_row(e) {
+ printf "ENTRY\t%s\t%s\t%s\t%s\t%s\t%s\t%d\n", RN[ER[e]], tsv(ES[e]), tsv(EK[e]), tsv(EN[e]), \
+ (ESTSET[e] ? tsv(EST[e]) : "-"), tsv(ESRC[e]), EL[e]
+ }
+ function block(e, i) { entry_row(e); for (i = EL[e]; i <= EE[e]; i++) print RAW[ER[e], i] }
+ function layout_rows( i) {
+ for (i = 1; i <= nlay; i++)
+ printf "LAYOUT\t%s\t%s\t%s\t%s\t%d\n", RN[LR[i]], RP[LR[i]], LF[i], LE[i], LL[i]
+ }
+ function unquoted_rows( i) {
+ for (i = 1; i <= nunq; i++)
+ printf "UNQUOTED\t%s\t%s\t%s\tstatus: \"%s\"\t%d\n", RN[UR[i]], RP[UR[i]], tsv(UV[i]), tsv(UV[i]), UL[i]
+ }
+ function anybad( r) { for (r = 1; r <= nreg; r++) if (BAD[r]) return 1; return 0 }
+ # The TR-ID anchored on slug s: TR-<s>-<digits> and nothing more.
+ function on_slug(id, s, rest) {
+ if (substr(id, 1, length(s) + 4) != "TR-" s "-") return 0
+ rest = substr(id, length(s) + 5)
+ return (rest != "" && rest !~ /[^0-9]/)
+ }
+ # Whether each path the entries name exists, file or directory, by test -e
+ # in the shell: getline cannot read a directory (and some awks stop on one).
+ # One shell per hundred paths, each path in single quotes.
+ function shq(s, out, i) {
+ out = ""
+ while ((i = index(s, SQ)) > 0) { out = out substr(s, 1, i - 1) SQ "\\" SQ SQ; s = substr(s, i + 1) }
+ return SQ out s SQ
+ }
+ function check_paths( e, j, p, n, a, b, i, sh, r) {
+ n = 0
+ for (e = 1; e <= ne; e++) if (ok(e)) for (j = 1; j <= NR_[e]; j++) {
+ p = RFP[e, j]
+ if (!(p in QUEUED)) { QUEUED[p] = 1; QP[++n] = p }
+ }
+ for (a = 1; a <= n; a += 100) {
+ b = (a + 99 < n) ? a + 99 : n
+ sh = "for p in"; for (i = a; i <= b; i++) sh = sh " " shq(QP[i])
+ sh = sh "; do if [ -e \"$p\" ]; then echo y; else echo n; fi; done"
+ i = a
+ while ((sh | getline r) > 0) { if (i <= b) EXISTS[QP[i]] = (r == "y"); i++ }
+ close(sh)
+ # A path the shell gave no answer for is not reported missing.
+ for (; i <= b; i++) EXISTS[QP[i]] = 1
+ }
+ }
+ function exists(p) { return (p in EXISTS) ? EXISTS[p] : 1 }
+ function status_ok(reg, v, n, a, i, it) {
+ if (v == "active") return 1
+ if (reg == "entities") return v == "deprecated"
+ if (reg == "architecture") return v ~ /^superseded_by: ADR-[0-9]+$/
+ if (v == "deprecated") return 1
+ if (substr(v, 1, 15) != "superseded-by: ") return 0
+ n = split(substr(v, 16), a, ",")
+ for (i = 1; i <= n; i++) { it = a[i]; sub(/^ +/, "", it); sub(/ +$/, "", it); if (it !~ ("^" TRID "$")) return 0 }
+ return n > 0
+ }
+
+ END {
+ end_reg()
+ for (e = 1; e <= ne; e++) CNT[ER[e]]++
+ if (cmd != "next-id")
+ for (r = 1; r <= nreg; r++)
+ printf "registry\t%s\t%s\t%s\n", RN[r], RP[r], RMISS[r] ? "missing" : (BAD[r] ? "layout" : CNT[r] + 0)
+ rc = 0
+
+ if (cmd == "list") {
+ sys = ENVIRON["RG_SYS"]
+ for (e = 1; e <= ne; e++) if (ok(e) && (sys == "" || on_slug(EN[e], sys))) entry_row(e)
+ }
+
+ else if (cmd == "get") {
+ nn = split(ENVIRON["RG_NAMES"], names, "\n"); nmiss = 0
+ for (i = 1; i <= nn; i++) {
+ if (names[i] == "") continue
+ hit = 0
+ for (e = 1; e <= ne; e++) if (ok(e) && EN[e] == names[i]) { block(e); hit = 1 }
+ if (!hit) MISS[++nmiss] = names[i]
+ }
+ }
+
+ else if (cmd == "refs") {
+ a = ENVIRON["RG_ARG"]
+ if (index(a, "/")) {
+ for (e = 1; e <= ne; e++) if (ok(e))
+ for (j = 1; j <= NR_[e]; j++) if (RFP[e, j] == a)
+ printf "REF\t%s\t%s\t%s\t%s\t%d\n", RN[ER[e]], tsv(EN[e]), RFH[e, j], RFP[e, j], RFL[e, j]
+ } else {
+ hit = 0
+ for (e = 1; e <= ne; e++) if (ok(e) && EN[e] == a) {
+ hit = 1
+ for (j = 1; j <= NR_[e]; j++)
+ printf "REF\t%s\t%s\t%s\t%s\t%d\n", RN[ER[e]], tsv(EN[e]), RFH[e, j], RFP[e, j], RFL[e, j]
+ if (RN[ER[e]] == "tr")
+ for (c = 1; c <= ncite; c++) if (CI[c] == a)
+ printf "REF\ttr\t%s\tcited\t%s\t%d\n", a, CF[c], CL[c]
+ }
+ if (!hit) MISS[++nmiss] = a
+ }
+ }
+
+ else if (cmd == "slice") {
+ a = ENVIRON["RG_ARG"]
+ for (e = 1; e <= ne; e++) if (ok(e))
+ for (j = 1; j <= NR_[e]; j++) if (RFP[e, j] == a) { block(e); break }
+ }
+
+ else if (cmd == "validate") {
+ nd = 0; nt = 0; np = 0; ns = 0
+ for (e = 1; e <= ne; e++) {
+ if (!ok(e) || EN[e] == "") continue
+ k = ER[e] SUBSEP ES[e] SUBSEP EN[e]
+ if (k in DL) DL[k] = DL[k] "," EL[e]; else { DL[k] = EL[e]; DORD[++ndk] = e }
+ }
+ for (i = 1; i <= ndk; i++) {
+ e = DORD[i]; k = ER[e] SUBSEP ES[e] SUBSEP EN[e]
+ if (index(DL[k], ",")) DROW[++nd] = sprintf("DUPLICATE\t%s\t%s\t%s\t%s", RN[ER[e]], ES[e], tsv(EN[e]), DL[k])
+ }
+ trr = 0; for (r = 1; r <= nreg; r++) if (RN[r] == "tr") trr = r
+ if (!(trr && BAD[trr])) {
+ for (e = 1; e <= ne; e++) if (RN[ER[e]] == "tr") TRK[EN[e]] = 1
+ for (c = 1; c <= ncite; c++) if (!(CI[c] in TRK)) TROW[++nt] = sprintf("TR_UNKNOWN\t%s\t%s\t%d", CI[c], CF[c], CL[c])
+ }
+ check_paths()
+ for (e = 1; e <= ne; e++) if (ok(e))
+ for (j = 1; j <= NR_[e]; j++) if (!exists(RFP[e, j]))
+ PROW[++np] = sprintf("PATH_MISSING\t%s\t%s\t%s\t%s\t%d", RN[ER[e]], tsv(EN[e]), RFH[e, j], RFP[e, j], RFL[e, j])
+ for (e = 1; e <= ne; e++) if (ok(e) && ESTSET[e] && !status_ok(RN[ER[e]], EST[e]))
+ SROW[++ns] = sprintf("STATUS\t%s\t%s\t%s\t%s\t%d", RN[ER[e]], tsv(EN[e]), (EST[e] == "" ? "\"\"" : tsv(EST[e])), ALLOWED[RN[ER[e]]], ESTL[e])
+ printf "checked\tproduction/epics\t%d\nduplicate\t%d\ntr_unknown\t%d\npath_missing\t%d\nstatus\t%d\nlayout\t%d\n", nscan, nd, nt, np, ns, nlay
+ for (i = 1; i <= nd; i++) print DROW[i]
+ for (i = 1; i <= nt; i++) print TROW[i]
+ for (i = 1; i <= np; i++) print PROW[i]
+ for (i = 1; i <= ns; i++) print SROW[i]
+ layout_rows(); unquoted_rows()
+ exit 0
+ }
+
+ else if (cmd == "compare") {
+ # Registry 1 is OLD and 2 is NEW, the order the file list gave them. An
+ # entry is its section and name, as validate keys a duplicate.
+ for (e = 1; e <= ne; e++) {
+ k = ES[e] SUBSEP EN[e]
+ if (ER[e] == 2) NEWK[k] = 1
+ else if (ESTSET[e] && !(k in OLDST)) OLDST[k] = EST[e]
+ }
+ nrm = 0; nst = 0
+ if (RMISS[1]) removed = 0
+ else if (RMISS[2] || BAD[1] || BAD[2]) removed = "-"
+ else {
+ for (e = 1; e <= ne; e++) if (ER[e] == 1 && EN[e] != "") {
+ k = ES[e] SUBSEP EN[e]
+ if ((k in NEWK) || (k in GONE)) continue
+ GONE[k] = 1
+ RROW[++nrm] = sprintf("REMOVED\t%s\t%s\t%s\t%d", RN[1], tsv(ES[e]), tsv(EN[e]), EL[e])
+ }
+ removed = nrm
+ }
+ if (!BAD[2]) for (e = 1; e <= ne; e++) if (ER[e] == 2 && ESTSET[e] && !status_ok(RN[2], EST[e])) {
+ k = ES[e] SUBSEP EN[e]
+ if ((k in OLDST) && OLDST[k] == EST[e]) continue
+ SROW[++nst] = sprintf("STATUS\t%s\t%s\t%s\t%s\t%d", RN[2], tsv(EN[e]), (EST[e] == "" ? "\"\"" : tsv(EST[e])), ALLOWED[RN[2]], ESTL[e])
+ }
+ printf "removed\t%s\nstatus\t%d\nlayout\t%d\n", removed, nst, nlay
+ for (i = 1; i <= nrm; i++) print RROW[i]
+ for (i = 1; i <= nst; i++) print SROW[i]
+ layout_rows(); unquoted_rows()
+ exit 0
+ }
+
+ else if (cmd == "next-id") {
+ if (anybad()) { layout_rows(); exit 4 }
+ s = ENVIRON["RG_ARG"]; max = -1; n = 0
+ for (e = 1; e <= ne; e++) if (on_slug(EN[e], s)) {
+ d = substr(EN[e], length(s) + 5) + 0
+ if (!(d in SEEN)) { SEEN[d] = 1; n++ }
+ if (d > max) max = d
+ }
+ # Three digits: the TR-ID format, TR-[system]-[NNN].
+ printf "next\ttr\t%s\tTR-%s-%03d\t%s\t%d\n", s, s, (max < 0 ? 1 : max + 1), (max < 0 ? "-" : sprintf("TR-%s-%03d", s, max)), n
+ exit 0
+ }
+
+ if (anybad()) { layout_rows(); rc = 4 }
+ unquoted_rows()
+ for (i = 1; i <= nmiss; i++) printf "NOT_FOUND\t%s\n", MISS[i]
+ if (!rc && nmiss) rc = 3
+ exit rc
+ }
+'
+rc=$?
+[ "$rc" = 4 ] && echo "registry: unsupported layout; the LAYOUT rows give each line and the layout expected there" >&2
+exit $rc
diff --git a/.claude/scripts/review-receipts.sh b/.claude/scripts/review-receipts.sh
index 12686641..7bf01f2d 100644
--- a/.claude/scripts/review-receipts.sh
+++ b/.claude/scripts/review-receipts.sh
@@ -14,11 +14,19 @@
# which makes everything read CHANGED and says so on stderr.
#
# ONE EXCEPTION, and it is deliberate. `check` stays silent on an absent
-# LITERAL path, because a caller may name an optional input on every run
-# (/design-review does exactly this with the entity registry) and reporting it
-# would block a legitimate skip. That silence is a false negative only if a
-# caller passes a literal path it believes must exist — so callers name
-# optional inputs and nothing else.
+# LITERAL path that the receipt never stamped, because a caller may name an
+# optional input on every run (/design-review does exactly this with the
+# entity registry) and reporting it would block a legitimate skip. That
+# silence is a false negative only if a caller passes a literal path it
+# believes must exist — so callers name optional inputs and nothing else. A
+# path the receipt DID stamp and that is now absent is not optional: the last
+# review read it, and it reads GONE.
+#
+# THE RECEIPT IS ALSO A LIST. `check` compares every path the receipt stamps,
+# not only the ones the caller names. The receipt records what the
+# last review actually read; a caller's list can fall behind what its phases
+# load, and a file it leaves out would otherwise never be compared -- which is
+# how /architecture-review stood on an old report after an engine upgrade.
#
# An unexpanded GLOB is the case the same code path can swallow, and is NOT
# covered by the above: it means a whole document class was
@@ -36,13 +44,20 @@
# Reviewed-Content-Hash: <path> <hash>
# The calling skill pastes these lines into the review report / log
# entry it is writing. Paths are normalised to forward slashes.
+# An absent literal path is left out with a note on stderr and does not
+# fail the run, so one command can name the optional inputs; a glob that
+# matched nothing, or a file that could not be hashed, exits 2.
#
-# bash .claude/scripts/review-receipts.sh check <receipt-file> <file> [<file>...]
+# bash .claude/scripts/review-receipts.sh check <receipt-file> [<file>...]
# First line: RECEIPT: <receipt-file> (or RECEIPT: NONE if missing/empty)
-# Then, per file:
+# Then, once per path -- the files named, in order, then every other
+# path the receipt stamps, in the order first stamped (with no files
+# named, only those: how /story-done reads an evidence stamp):
# UNCHANGED: <path> hash matches the LATEST stamp for that path
# CHANGED: <path> hash differs from the latest stamp
# NEW: <path> no stamp for that path in the receipt file
+# GONE: <path> the receipt stamps it and it no longer exists:
+# the last review read a file since deleted or moved
# UNRESOLVED: <pat> the argument is a glob the shell never expanded,
# so a whole class of documents was asked for and
# none was examined. NOT the same as an absent
@@ -51,8 +66,8 @@
# With RECEIPT: NONE, every file is reported NEW (nothing to compare).
#
# A caller that skips work on "everything UNCHANGED" MUST treat an
-# UNRESOLVED line as disqualifying: the set it compared was not the set
-# it asked for.
+# UNRESOLVED or GONE line as disqualifying: the set it compared was not
+# the set it asked for, or not the set the last review read.
#
# bash .claude/scripts/review-receipts.sh sections-hash <file>
# Per ^## section of the file (plus __preamble__ for content before the
@@ -123,6 +138,27 @@ norm_path() {
printf '%s\n' "$1" | sed 's|\\|/|g'
}
+# compare_stamp <file> <normalised path> <receipt>: one UNCHANGED / CHANGED /
+# NEW line for a file that exists. The LATEST stamp for the path wins
+# (append-only log); grep -F on the path avoids regex surprises from
+# dots/dashes in filenames.
+compare_stamp() {
+ # The CR of a CRLF receipt goes first: on Linux and macOS it would stay on
+ # the hash, and every path would read CHANGED.
+ _stored=$(grep -F "Reviewed-Content-Hash: $2 " "$3" 2>/dev/null | tail -1 | awk '{ sub(/\r$/, ""); print $NF }')
+ if [ -z "$_stored" ]; then
+ printf 'NEW: %s\n' "$2"
+ return 0
+ fi
+ _current=$(hash_file "$1")
+ [ -n "$_current" ] || warn_no_hash
+ if [ "$_current" = "$_stored" ]; then
+ printf 'UNCHANGED: %s\n' "$2"
+ else
+ printf 'CHANGED: %s\n' "$2"
+ fi
+}
+
# An argument that does not name a file is one of two very different things,
# and `check` must NOT treat them alike:
#
@@ -133,8 +169,8 @@ norm_path() {
# registry "doesn't appear in the output
# and doesn't block the skip". Reporting
# it would break that skip and force a
-# full re-review (~46k tokens, measured)
-# on every project without a registry.
+# full re-review on every project
+# without a registry.
# Staying silent here is DELIBERATE.
#
# a pattern the shell never -> the caller asked for a whole class of
@@ -204,8 +240,12 @@ case "$mode" in
rc=0
for f in "$@"; do
if [ ! -f "$f" ]; then
- echo "review-receipts: no such file: $f" >&2
- rc=2
+ if is_unexpanded_glob "$f"; then
+ echo "review-receipts: matched no file: $f" >&2
+ rc=2
+ else
+ echo "review-receipts: not stamped, no such file: $f" >&2
+ fi
continue
fi
h=$(hash_file "$f")
@@ -219,7 +259,8 @@ case "$mode" in
shift
receipt="${1:-}"
shift 2>/dev/null || true
- [ $# -ge 1 ] || { echo "review-receipts: check mode needs a receipt file and at least one file" >&2; exit 2; }
+ # No files named: every path the receipt stamps (an evidence stamp).
+ [ -n "$receipt" ] || { echo "review-receipts: check mode needs a receipt file" >&2; exit 2; }
if [ ! -s "${receipt:-}" ]; then
echo "RECEIPT: NONE"
@@ -234,27 +275,43 @@ case "$mode" in
fi
echo "RECEIPT: $(norm_path "$receipt")"
+ # Every path the receipt stamps, once, in the order first stamped. The
+ # path is everything between the prefix and the last space, so a name
+ # with a space survives.
+ stamped=$(sed -n 's/.*Reviewed-Content-Hash: \(.*\) [^ ]*$/\1/p' "$receipt" 2>/dev/null | awk '!seen[$0]++')
+ # Newline-delimited set of paths already reported: no `declare -A`, which
+ # is bash 4 (see sections-check below).
+ _RR_NL='
+'
+ reported="$_RR_NL"
for f in "$@"; do
- if [ ! -f "$f" ]; then
- is_unexpanded_glob "$f" && printf 'UNRESOLVED: %s\n' "$(norm_path "$f")"
- continue
- fi
p=$(norm_path "$f")
- # Last occurrence wins (append-only log). grep -F on the path avoids
- # regex surprises from dots/dashes in filenames.
- stored=$(grep -F "Reviewed-Content-Hash: $p " "$receipt" 2>/dev/null | tail -1 | awk '{print $NF}')
- if [ -z "$stored" ]; then
- printf 'NEW: %s\n' "$p"
+ if [ ! -f "$f" ]; then
+ if is_unexpanded_glob "$f"; then
+ printf 'UNRESOLVED: %s\n' "$p"
+ elif printf '%s\n' "$stamped" | grep -qxF -- "$p"; then
+ printf 'GONE: %s\n' "$p"
+ reported="$reported$p$_RR_NL"
+ fi
continue
fi
- current=$(hash_file "$f")
- [ -n "$current" ] || warn_no_hash
- if [ "$current" = "$stored" ]; then
- printf 'UNCHANGED: %s\n' "$p"
+ case "$reported" in *"$_RR_NL$p$_RR_NL"*) continue ;; esac
+ reported="$reported$p$_RR_NL"
+ compare_stamp "$f" "$p" "$receipt"
+ done
+ # The paths the last review read that the caller did not name.
+ while IFS= read -r p; do
+ [ -n "$p" ] || continue
+ case "$reported" in *"$_RR_NL$p$_RR_NL"*) continue ;; esac
+ reported="$reported$p$_RR_NL"
+ if [ -f "$p" ]; then
+ compare_stamp "$p" "$p" "$receipt"
else
- printf 'CHANGED: %s\n' "$p"
+ printf 'GONE: %s\n' "$p"
fi
- done
+ done <<EOF_ST
+$stamped
+EOF_ST
exit 0
;;
@@ -295,11 +352,12 @@ EOF_SH
# Safe as a delimited string because a section key is heading text, which
# cannot contain a TAB or a newline. Matching is field-exact via awk, never
# a substring grep, so one heading cannot match another that contains it.
- _RR_TAB=$(printf '\t')
+ _RR_TAB=$(printf '\t'); _RR_CR=$(printf '\r')
STORED=""
STORED_N=0
if [ -s "${receipt:-}" ]; then
while IFS= read -r line; do
+ line=${line%"$_RR_CR"} # a CRLF receipt's CR, as in compare_stamp
case "$line" in
"Reviewed-Section-Hash: $p#"*) ;;
*) continue ;;
diff --git a/.claude/scripts/rotate-session-state.sh b/.claude/scripts/rotate-session-state.sh
index a0665ed8..3512ba54 100644
--- a/.claude/scripts/rotate-session-state.sh
+++ b/.claude/scripts/rotate-session-state.sh
@@ -32,7 +32,7 @@ DRY=0
case "${1:-}" in
--help|-h)
- sed -n '2,30p' "$0" | sed 's/^# \?//'
+ sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'
exit 0 ;;
--dry-run) DRY=1 ;;
"") ;;
@@ -44,7 +44,14 @@ if [ ! -f "$STATE" ]; then
exit 0
fi
-if ! grep -q '<!-- /CHECKPOINT -->' "$STATE"; then
+# The marker is a line holding only `<!-- /CHECKPOINT -->` (spaces and a CR
+# around it allowed). The same words inside a sentence are not one: the
+# template's own HOW comment quotes the marker, and matching that quote split
+# every file made from the template inside the comment, moving the live
+# checkpoint into the session log.
+MARKER='^[[:space:]]*<!-- /CHECKPOINT -->[[:space:]]*$'
+
+if ! grep -q "$MARKER" "$STATE"; then
echo "REFUSED: $STATE has no <!-- /CHECKPOINT --> marker."
echo " Rotation splits the file at that marker, so without it this script"
echo " cannot tell the checkpoint from the narrative and would move both."
@@ -53,7 +60,7 @@ if ! grep -q '<!-- /CHECKPOINT -->' "$STATE"; then
fi
# Everything through the marker is the checkpoint; everything after is narrative.
-SPLIT=$(grep -n '<!-- /CHECKPOINT -->' "$STATE" | head -1 | cut -d: -f1)
+SPLIT=$(grep -n "$MARKER" "$STATE" | head -1 | cut -d: -f1)
TOTAL=$(wc -l < "$STATE" | tr -d ' ')
NARRATIVE=$((TOTAL - SPLIT))
diff --git a/.claude/scripts/session-state.sh b/.claude/scripts/session-state.sh
new file mode 100644
index 00000000..ef55147a
--- /dev/null
+++ b/.claude/scripts/session-state.sh
@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+# session-state.sh — read and write production/session-state/active.md in the
+# layout .claude/docs/templates/session-state.md defines, so a skill hands
+# over the words and this script places them.
+#
+# Replaces the hand-run checkpoint steps in /story-done and /dev-story.
+#
+# rotate-session-state.sh owns the layout: the file splits at the
+# `<!-- /CHECKPOINT -->` marker, the checkpoint above it, the narrative below.
+# A marker here is a line holding only the marker (spaces and CR ignored);
+# the same words inside a sentence, as in the template's own HOW comment, are
+# not a marker.
+#
+# Usage: bash .claude/scripts/session-state.sh <command> [--root DIR]
+# show print the STATUS block (when there is one) through the end of
+# the CHECKPOINT block
+# checkpoint replace what is between the CHECKPOINT markers with stdin.
+# No file: create it from the template first. A file with no
+# CHECKPOINT markers: add the block after the STATUS block, or,
+# with no STATUS block either, put the template's STATUS and
+# CHECKPOINT blocks at the top and leave the rest as it was.
+# append add stdin at the end of the file (after the narrative), unless
+# the file already ends with exactly those lines. No file: create
+# it from the template first.
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+# Stdin may include or leave out the two CHECKPOINT marker lines; blank lines
+# at its start and end are dropped. The file's line endings (LF or CRLF) are
+# kept for every line written. The new file is made in full first, then copied
+# over active.md in place, so it keeps its mode and a symlink stays one.
+#
+# Output (checkpoint, append): TSV
+# file production/session-state/active.md <created|replaced|inserted|appended|unchanged>
+# lines <lines written from stdin> -
+# show prints the block lines themselves.
+#
+# Exit codes: 0 done; 1 cannot read the root, find the template, or write the
+# file; 2 usage error (no command, nothing on stdin); 3 the file has one
+# CHECKPOINT marker without the other, or they are out of order (nothing is
+# written: the same refusal rotate-session-state.sh gives, with the same code);
+# 4 `show` found no active.md. Never prompts. Observations only: what goes in
+# the checkpoint is the skill's to write.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk: the CR tests below compare bytes.
+LC_ALL=C
+export LC_ALL
+
+STATE="production/session-state/active.md"
+TEMPLATE=".claude/docs/templates/session-state.md"
+# The template asks for a checkpoint under ~25 lines because session-start.sh
+# shows it whole in every new session; longer is allowed but warned about.
+MAX_LINES=25
+
+CMD=""
+ROOT_ARG=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ show|checkpoint|append)
+ [ -z "$CMD" ] || { echo "session-state: one command only" >&2; exit 2; }
+ CMD="$1"; shift ;;
+ --root)
+ [ $# -ge 2 ] || { echo "session-state: --root needs a value" >&2; exit 2; }
+ ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ *) echo "session-state: unknown argument: $1 (try --help)" >&2; exit 2 ;;
+ esac
+done
+[ -n "$CMD" ] || { echo "session-state: no command; use show, checkpoint or append (try --help)" >&2; exit 2; }
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "session-state: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$(dirname "$0")/../.." 2>/dev/null || { echo "session-state: cannot reach the repo root" >&2; exit 1; }
+fi
+
+# locate FILE — print "so sc co cc": the line numbers of the STATUS opener and
+# closer and the CHECKPOINT opener and the first closer after it (0 = none).
+# `co` with `cc` 0, or a closer with no opener, means a broken block.
+locate() {
+ awk '
+ function is(m) { return line == m }
+ { line = $0; sub(/\r$/, "", line); sub(/^[ \t]+/, "", line); sub(/[ \t]+$/, "", line) }
+ is("<!-- STATUS -->") && !so { so = NR }
+ is("<!-- /STATUS -->") && so && !sc { sc = NR }
+ is("<!-- CHECKPOINT -->") && !co { co = NR }
+ is("<!-- /CHECKPOINT -->") { if (co && !cc) cc = NR; else if (!co) stray = NR }
+ END { if (stray && !co) cc = stray; printf "%d %d %d %d\n", so, sc, co, cc }
+ ' "$1"
+}
+
+if [ "$CMD" = "show" ]; then
+ [ -f "$STATE" ] || { echo "session-state: no $STATE" >&2; exit 4; }
+ set -- $(locate "$STATE")
+ so=$1; sc=$2; co=$3; cc=$4
+ if [ "$co" = 0 ] || [ "$cc" = 0 ] || [ "$cc" -lt "$co" ]; then
+ echo "session-state: $STATE has no complete CHECKPOINT block (<!-- CHECKPOINT --> ... <!-- /CHECKPOINT -->)" >&2
+ exit 3
+ fi
+ start=$co
+ [ "$so" -gt 0 ] && [ "$sc" -gt "$so" ] && [ "$so" -lt "$co" ] && start=$so
+ awk -v a="$start" -v b="$cc" 'NR >= a && NR <= b { sub(/\r$/, ""); print }' "$STATE"
+ exit 0
+fi
+
+# --- checkpoint / append: read stdin -----------------------------------------
+STATE_DIR=$(dirname "$STATE")
+mkdir -p "$STATE_DIR" 2>/dev/null || { echo "session-state: cannot create $STATE_DIR" >&2; exit 1; }
+BODY=$(mktemp "$STATE_DIR/.ccgs-body-XXXXXX" 2>/dev/null) || { echo "session-state: cannot create a temporary file in $STATE_DIR" >&2; exit 1; }
+NEW=$(mktemp "$STATE_DIR/.ccgs-state-XXXXXX" 2>/dev/null) || { rm -f "$BODY"; echo "session-state: cannot create a temporary file in $STATE_DIR" >&2; exit 1; }
+trap 'rm -f "$BODY" "$NEW"' EXIT
+# CR off, marker lines out, blank lines at both ends dropped.
+awk '
+ { sub(/\r$/, ""); t = $0; sub(/^[ \t]+/, "", t); sub(/[ \t]+$/, "", t) }
+ t == "<!-- CHECKPOINT -->" || t == "<!-- /CHECKPOINT -->" { next }
+ { l[++n] = $0; if (t != "") { if (!first) first = n; last = n } }
+ END { for (i = first; first && i <= last; i++) print l[i] }
+' > "$BODY"
+NBODY=$(wc -l < "$BODY" | tr -d ' ')
+[ "$NBODY" -gt 0 ] || { echo "session-state: nothing on stdin to write" >&2; exit 2; }
+
+ACTION=""
+if [ ! -f "$STATE" ]; then
+ [ -f "$TEMPLATE" ] || { echo "session-state: no $STATE and no template at $TEMPLATE to create it from" >&2; exit 1; }
+ BASE="$TEMPLATE"; ACTION="created"
+else
+ BASE="$STATE"
+fi
+# Git for Windows gawk reads files in text mode and drops the CR of a CRLF
+# line, so the two awks below that must see or keep a CR set BINMODE 3 (every
+# byte as it is). Other awks treat BINMODE as a plain variable.
+CR=$(awk 'BEGIN { BINMODE = 3 } NR == 1 { print ($0 ~ /\r$/) ? 1 : 0; exit }' "$BASE")
+[ -n "$CR" ] || CR=0
+
+# emit FILE — FILE's lines with the base file's line ending.
+emit() { awk -v cr="$CR" '{ sub(/\r$/, ""); printf "%s%s\n", $0, (cr == 1 ? "\r" : "") }' "$1"; }
+emit_text() { printf '%s\n' "$@" > "$NEW.txt"; emit "$NEW.txt"; rm -f "$NEW.txt"; }
+# lines FILE A B — lines A..B of FILE as they are (B 0 = to the end).
+lines() { awk -v a="$2" -v b="$3" 'BEGIN { BINMODE = 3 } NR >= a && (b == 0 || NR <= b)' "$1"; }
+
+if [ "$CMD" = "checkpoint" ]; then
+ set -- $(locate "$BASE")
+ so=$1; sc=$2; co=$3; cc=$4
+ if [ "$co" -gt 0 ] && [ "$cc" -gt "$co" ]; then
+ [ -z "$ACTION" ] && ACTION="replaced"
+ { lines "$BASE" 1 "$co"; emit "$BODY"; lines "$BASE" "$cc" 0; } > "$NEW"
+ elif [ "$co" = 0 ] && [ "$cc" = 0 ]; then
+ [ -z "$ACTION" ] && ACTION="inserted"
+ if [ "$so" -gt 0 ] && [ "$sc" -gt "$so" ]; then
+ { lines "$BASE" 1 "$sc"; emit_text "" "<!-- CHECKPOINT -->"; emit "$BODY"
+ emit_text "<!-- /CHECKPOINT -->"; lines "$BASE" $((sc + 1)) 0; } > "$NEW"
+ else
+ [ -f "$TEMPLATE" ] || { echo "session-state: $STATE has no markers and there is no template at $TEMPLATE to take them from" >&2; exit 1; }
+ set -- $(locate "$TEMPLATE")
+ if [ "$1" -gt 0 ] && [ "$2" -gt "$1" ]; then
+ lines "$TEMPLATE" "$1" "$2" > "$NEW.status"
+ else
+ : > "$NEW.status"
+ fi
+ { [ -s "$NEW.status" ] && { emit "$NEW.status"; emit_text ""; }
+ emit_text "<!-- CHECKPOINT -->"; emit "$BODY"; emit_text "<!-- /CHECKPOINT -->" ""
+ cat "$BASE"; } > "$NEW"
+ rm -f "$NEW.status"
+ fi
+ else
+ if [ "$cc" = 0 ]; then why="<!-- CHECKPOINT --> at line $co has no <!-- /CHECKPOINT --> after it"
+ else why="<!-- /CHECKPOINT --> at line $cc has no <!-- CHECKPOINT --> before it"; fi
+ echo "session-state: $BASE: $why. Nothing was written." >&2
+ echo " Fix the markers by hand (layout: $TEMPLATE); guessing where the block ends could swallow the narrative." >&2
+ exit 3
+ fi
+ [ "$NBODY" -gt "$MAX_LINES" ] && echo "session-state: the checkpoint is $NBODY lines; the template asks for under ~$MAX_LINES, because session-start.sh shows it whole in every new session" >&2
+else
+ # append: skip when the file already ends with exactly these lines.
+ if [ "$ACTION" != "created" ] && awk '
+ FNR == NR { b[++nb] = $0; next }
+ { sub(/\r$/, ""); f[++nf] = $0 }
+ END {
+ e = nf; while (e > 0 && f[e] ~ /^[ \t]*$/) e--
+ if (e < nb) exit 1
+ for (i = 1; i <= nb; i++) if (f[e - nb + i] != b[i]) exit 1
+ exit 0
+ }' "$BODY" "$BASE"; then
+ ACTION="unchanged"; cp "$BASE" "$NEW"
+ else
+ [ -z "$ACTION" ] && ACTION="appended"
+ { cat "$BASE"
+ # Close an unterminated last line, then leave one blank line before the block.
+ # ($(...) drops a trailing newline, so a non-empty result is a last byte
+ # that is not one.)
+ [ -n "$(tail -c 1 "$BASE")" ] && emit_text ""
+ [ -s "$BASE" ] && [ -n "$(tail -n 1 "$BASE" | tr -d ' \t\r')" ] && emit_text ""
+ emit "$BODY"; } > "$NEW"
+ fi
+fi
+
+if [ -f "$STATE" ] && cmp -s "$NEW" "$STATE"; then
+ ACTION="unchanged"
+else
+ # Copied over the file in place, not moved: the file keeps its mode, a
+ # symlink stays a symlink and a hard link sees the change.
+ cat "$NEW" > "$STATE" 2>/dev/null || { echo "session-state: could not write $STATE" >&2; exit 1; }
+fi
+printf 'file\t%s\t%s\nlines\t%s\t-\n' "$STATE" "$ACTION" "$NBODY"
+exit 0
diff --git a/.claude/scripts/set-stage.sh b/.claude/scripts/set-stage.sh
new file mode 100644
index 00000000..8aaa2196
--- /dev/null
+++ b/.claude/scripts/set-stage.sh
@@ -0,0 +1,311 @@
+#!/usr/bin/env bash
+# set-stage.sh — write the project stage to project.yaml and the legacy
+# production/stage.txt, read both back, and say whether they agree.
+#
+# Replaces the hand-run stage write: the primary write to project.yaml, the
+# legacy fallback write to production/stage.txt, and the check that both
+# landed. /start and /gate-check call it.
+#
+# THE ASK STAYS IN THE SKILL. A stage moves only on a /gate-check PASS (or a
+# CONCERNS whose risks the user accepted) with the user's yes; this script
+# never decides that and never prompts. Run it after the yes.
+#
+# Usage: bash .claude/scripts/set-stage.sh <Stage> [--dry-run] [--root DIR]
+# <Stage> one of: Concept, Systems Design, Technical Setup,
+# Pre-Production, Production, Polish, Release (quote the
+# two-word names)
+# --dry-run say what would change; write nothing
+# --root DIR the project to write; defaults to the repo this script is in
+# -h, --help this text
+#
+# What it writes in project.yaml (comments, other keys and line endings kept):
+# - a `stage:` line under `project:` gets the new value, keeping its quotes
+# and any inline comment; when project.stage is set more than once, the
+# last one is edited, because that is the one every reader uses
+# - a `project:` block with no `stage:` gets one as its first line
+# - no `project:` block: one is added after the `framework:` block, or at the
+# end of the file when there is no `framework:` block
+# - no project.yaml: it is created from /gate-check's minimal template
+# production/stage.txt gets the stage name with no trailing newline.
+# A file already holding the stage is left byte-for-byte alone. Each file's new
+# text is made in full first, then copied over it in place, so it keeps its
+# mode and a symlink stays one.
+#
+# Output: TSV.
+# project.yaml <replaced|inserted|added-block|created|unchanged> <line or ->
+# stage.txt <written|unchanged> -
+# stage_yaml <value read back> project.yaml
+# stage_txt <value read back> production/stage.txt
+#
+# Exit codes: 0 both files hold the stage; 1 cannot read the root, write a file,
+# or find project-state.sh or the framework version; 2 usage error; 3 <Stage>
+# is not a stage name; 4 the two files disagree after writing; 5 project.yaml
+# has a layout this script will not edit (`project:` as a one-line value).
+# A 3 or a 5 writes nothing.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk: the BOM and CR tests below compare bytes.
+LC_ALL=C
+export LC_ALL
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+STAGE=""
+DRY=0
+ROOT_ARG=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --dry-run) DRY=1; shift ;;
+ --root)
+ [ $# -ge 2 ] || { echo "set-stage: --root needs a value" >&2; exit 2; }
+ ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) echo "set-stage: unknown argument: $1 (try --help)" >&2; exit 2 ;;
+ *)
+ [ -z "$STAGE" ] || { echo "set-stage: one stage only (quote two-word names: \"Systems Design\")" >&2; exit 2; }
+ STAGE="$1"; shift ;;
+ esac
+done
+[ -n "$STAGE" ] || { echo "set-stage: no stage given (try --help)" >&2; exit 2; }
+
+# The seven stage names: project.stage's enum in yaml-helper.sh.
+STAGES="Concept|Systems Design|Technical Setup|Pre-Production|Production|Polish|Release"
+ok=1; oldIFS="$IFS"; IFS='|'
+for s in $STAGES; do [ "$STAGE" = "$s" ] && ok=0; done
+IFS="$oldIFS"
+if [ "$ok" != 0 ]; then
+ echo "set-stage: '$STAGE' is not a stage. Allowed: $STAGES" >&2
+ exit 3
+fi
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "set-stage: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "set-stage: cannot reach the repo root" >&2; exit 1; }
+fi
+[ -f "$HERE/project-state.sh" ] || { echo "set-stage: $HERE/project-state.sh is missing; cannot read the stage back" >&2; exit 1; }
+
+# replace_file TARGET NEWFILE — the new text, made in full in NEWFILE first,
+# copied over TARGET in place, so TARGET keeps its mode, a symlink stays a
+# symlink and a hard link sees the change (a mv would put a new file there).
+replace_file() {
+ if ! cat "$2" > "$1" 2>/dev/null; then
+ echo "set-stage: could not write $1; the new text is kept in $2" >&2
+ exit 1
+ fi
+ rm -f "$2"
+}
+
+# --- project.yaml ----------------------------------------------------------
+Y_ACTION=""; Y_LINE="-"; Y_NEW=""
+if [ ! -f project.yaml ]; then
+ Y_ACTION="created"
+ # The framework version these scripts ship with; update-check.sh holds the
+ # one copy a release bumps.
+ VERSION=$(sed -n 's/^UPDATE_CHECK_VERSION="\([^"]*\)".*/\1/p' "$HERE/../hooks/update-check.sh" 2>/dev/null | head -1)
+ [ -n "$VERSION" ] || { echo "set-stage: no framework version in $HERE/../hooks/update-check.sh; project.yaml not created" >&2; exit 1; }
+ Y_NEW=$(mktemp "./.ccgs-stage-XXXXXX" 2>/dev/null) || { echo "set-stage: cannot create a temporary file in $(pwd)" >&2; exit 1; }
+ # /gate-check's minimal template (references/6-update-stage.md, 6.1).
+ {
+ echo "# CCGS project configuration — single source of truth for project settings."
+ echo "# Schema: grep the \`## <key>\` section of .claude/docs/effects-map.md —"
+ echo "# it is ~31k tokens whole, ~900 per section. Do not open it entire."
+ echo ""
+ echo "schema_version: 1"
+ echo ""
+ echo "framework:"
+ echo " version: $VERSION"
+ echo " last_upgraded: $(date +%Y-%m-%d)"
+ echo ""
+ echo "project:"
+ echo " stage: $STAGE"
+ } > "$Y_NEW"
+else
+ Y_NEW=$(mktemp "./.ccgs-stage-XXXXXX" 2>/dev/null) || { echo "set-stage: cannot create a temporary file in $(pwd)" >&2; exit 1; }
+ Y_STATUS="$Y_NEW.status"
+ # Parse every line the way project-state.sh's yaml_get does, note where
+ # project.stage and the `project:` and `framework:` blocks are, then print
+ # the file with one line replaced or a few lines inserted.
+ STAGE="$STAGE" STATUS="$Y_STATUS" awk '
+ # opens(s, n): when line s (at indent n, its leading spaces removed) opens
+ # a block scalar (a value of | or >, with any indicators), the indent its
+ # text must exceed; else -1. Its text is never a key, as in yaml-get.awk.
+ function opens(s, n, r, p, v) {
+ r = s
+ if (r == "-" || substr(r, 1, 2) == "- ") {
+ r = substr(r, 2); sub(/^ +/, "", r)
+ if (r ~ /^[|>][-+0-9]*[ \t]*(#.*)?$/) return n
+ n = n + length(s) - length(r)
+ }
+ if (r == "" || r ~ /^[:# \t]/) return -1
+ p = index(r, ":"); if (p == 0) return -1
+ v = substr(r, p + 1); sub(/^[ \t]+/, "", v); sub(/[ \t]+$/, "", v)
+ return (v ~ /^[|>][-+0-9]*[ \t]*(#.*)?$/) ? n : -1
+ }
+ # Git for Windows gawk reads files in text mode and drops the CR of a CRLF
+ # line; BINMODE 3 keeps every byte. Other awks treat it as a plain variable.
+ BEGIN { BINMODE = 3 }
+ { raw[NR] = $0 }
+ END {
+ stage = ENVIRON["STAGE"]; depth = 0; nst = 0; laststage = 0; blk = -1
+ projkind = ""; projline = 0; fwline = 0; crlf = (raw[1] ~ /\r$/)
+ for (L = 1; L <= NR; L++) {
+ line = raw[L]
+ # "\357\273\277" is the UTF-8 byte-order mark.
+ if (L == 1 && substr(line, 1, 3) == "\357\273\277") line = substr(line, 4)
+ sub(/\r$/, "", line)
+ n = 0
+ while (substr(line, n + 1, 1) == " ") n++
+ s = substr(line, n + 1)
+ t = s
+ sub(/^[ \t]+/, "", t)
+ kind[L] = "other"
+ if (t == "") { kind[L] = "blank"; continue }
+ if (substr(t, 1, 1) == "#") { kind[L] = "comment"; continue }
+ # A block scalar text line stays "other": content of the block above it.
+ if (blk >= 0) { if (n > blk) continue; blk = -1 }
+ blk = opens(s, n)
+ c = substr(s, 1, 1)
+ if (c == ":" || c == "#" || c == "\t") continue
+ p = index(s, ":")
+ if (p == 0) continue
+ key = substr(s, 1, p - 1)
+ sub(/[ \t]+$/, "", key)
+ v = substr(s, p + 1)
+ sub(/^[ \t]+/, "", v)
+ sub(/[ \t]+$/, "", v)
+ q = substr(v, 1, 1)
+ if (q == "#") v = ""
+ else if (q == "\"" || q == "\047") {
+ rest = substr(v, 2); e = index(rest, q)
+ v = (e > 0) ? substr(rest, 1, e - 1) : rest
+ } else {
+ h = index(v, " #")
+ if (h > 0) { v = substr(v, 1, h - 1); sub(/[ \t]+$/, "", v) }
+ }
+ while (depth > 0 && ind[depth] >= n) depth--
+ full = ""
+ for (i = 1; i <= depth; i++) full = full keys[i] "."
+ full = full key
+ kind[L] = "key"; indent[L] = n; top[L] = (depth == 0)
+ if (v == "") { depth++; ind[depth] = n; keys[depth] = key }
+ if (full == "project") {
+ projkind = (v == "") ? "map" : "scalar"; projline = L
+ # A one-line value replaces the block, and the stage inside it.
+ if (v != "") laststage = 0
+ }
+ if (full == "framework" && v == "") fwline = L
+ if (full == "project.stage") {
+ nst++; stlines = stlines (nst > 1 ? "," : "") L
+ laststage = L; curval = v; colon[L] = n + p
+ }
+ }
+ eol = crlf ? "\r" : ""
+ action = ""; at = 0
+ if (projkind == "scalar") {
+ print "unsupported\t" projline > ENVIRON["STATUS"]; exit 0
+ }
+ if (laststage > 0) {
+ at = laststage
+ if (curval == stage) action = "unchanged"
+ else {
+ action = "replaced"
+ line = raw[at]; cr = (line ~ /\r$/); sub(/\r$/, "", line)
+ pre = substr(line, 1, colon[at]); after = substr(line, colon[at] + 1)
+ lead = after; sub(/[^ \t].*$/, "", lead); if (lead == "") lead = " "
+ a = after; sub(/^[ \t]+/, "", a)
+ q = substr(a, 1, 1)
+ if (a == "") tail = ""
+ else if (q == "#") tail = " " a
+ else if (q == "\"" || q == "\047") {
+ e = index(substr(a, 2), q)
+ tail = (e > 0) ? substr(a, e + 2) : ""
+ stage = q stage q
+ } else {
+ # Keep an inline comment and the spaces before it; drop the old value.
+ h = index(a, " #"); tail = ""
+ if (h > 0) { tok = substr(a, 1, h - 1); sub(/[ \t]+$/, "", tok); tail = substr(a, length(tok) + 1) }
+ }
+ raw[at] = pre lead stage tail (cr ? "\r" : "")
+ }
+ } else if (projkind == "map") {
+ action = "inserted"; at = projline
+ ci = indent[projline] + 2
+ for (L = projline + 1; L <= NR; L++) {
+ if (kind[L] != "key") continue
+ if (indent[L] > indent[projline]) ci = indent[L]
+ break
+ }
+ pad = ""; for (i = 0; i < ci; i++) pad = pad " "
+ ins[projline] = pad "stage: " stage eol
+ at = projline + 1
+ } else {
+ action = "added-block"
+ if (fwline > 0) {
+ last = fwline
+ for (L = fwline + 1; L <= NR; L++) {
+ if (kind[L] == "key" && top[L]) break
+ if (kind[L] != "blank" && kind[L] != "comment") last = L
+ }
+ } else last = NR
+ sep = (last > 0 && kind[last] != "blank") ? eol "\n" : ""
+ ins[last] = sep "project:" eol "\n stage: " stage eol
+ at = last + (sep != "" ? 3 : 2)
+ }
+ for (L = 1; L <= NR; L++) {
+ print raw[L]
+ if (L in ins) print ins[L]
+ }
+ if (NR == 0 && (0 in ins)) print ins[0]
+ printf "%s\t%s\t%s\n", action, at, (nst > 1 ? stlines : "") > ENVIRON["STATUS"]
+ }
+ ' project.yaml > "$Y_NEW"
+ IFS="$(printf '\t')" read -r Y_ACTION Y_LINE Y_DUPS < "$Y_STATUS" 2>/dev/null
+ rm -f "$Y_STATUS"
+ if [ "${Y_ACTION:-}" = "unsupported" ]; then
+ rm -f "$Y_NEW"
+ echo "set-stage: project.yaml line $Y_LINE sets \`project:\` to a one-line value, so it has no \`stage:\` to edit." >&2
+ echo " Expected layout: a block, \`project:\` on its own line and \` stage: <Stage>\` under it. Nothing was written." >&2
+ exit 5
+ fi
+ [ -n "${Y_ACTION:-}" ] || { rm -f "$Y_NEW"; echo "set-stage: could not parse project.yaml; nothing was written" >&2; exit 1; }
+ if [ -n "${Y_DUPS:-}" ]; then
+ echo "set-stage: project.stage is set more than once in project.yaml (lines $Y_DUPS); line $Y_LINE is the one readers use, so that is the one edited" >&2
+ fi
+ [ "$Y_ACTION" = "unchanged" ] && { rm -f "$Y_NEW"; Y_NEW=""; }
+fi
+
+# --- production/stage.txt --------------------------------------------------
+T_ACTION="written"
+if [ -f production/stage.txt ] && printf '%s' "$STAGE" | cmp -s - production/stage.txt; then
+ T_ACTION="unchanged"
+fi
+
+if [ "$DRY" = 1 ]; then
+ [ -n "$Y_NEW" ] && rm -f "$Y_NEW"
+ printf 'project.yaml\t%s\t%s\nstage.txt\t%s\t-\n' "$Y_ACTION" "$Y_LINE" "$T_ACTION"
+ exit 0
+fi
+
+[ -n "$Y_NEW" ] && replace_file project.yaml "$Y_NEW"
+if [ "$T_ACTION" = "written" ]; then
+ mkdir -p production 2>/dev/null
+ T_NEW=$(mktemp "production/.ccgs-stage-XXXXXX" 2>/dev/null) || { echo "set-stage: cannot create a temporary file in production/" >&2; exit 1; }
+ printf '%s' "$STAGE" > "$T_NEW" || { rm -f "$T_NEW"; echo "set-stage: could not write production/stage.txt" >&2; exit 1; }
+ replace_file production/stage.txt "$T_NEW"
+fi
+
+# --- read back through the one reader -------------------------------------
+BACK=$(bash "$HERE/project-state.sh" --stage --root .)
+SY=$(printf '%s\n' "$BACK" | awk -F'\t' '$1 == "stage_yaml" { print $2 }')
+ST=$(printf '%s\n' "$BACK" | awk -F'\t' '$1 == "stage_txt" { print $2 }')
+printf 'project.yaml\t%s\t%s\nstage.txt\t%s\t-\n' "$Y_ACTION" "$Y_LINE" "$T_ACTION"
+printf 'stage_yaml\t%s\tproject.yaml\nstage_txt\t%s\tproduction/stage.txt\n' "$SY" "$ST"
+if [ "$SY" != "$STAGE" ] || [ "$ST" != "$STAGE" ]; then
+ echo "set-stage: after writing, project.yaml reads '$SY' and production/stage.txt reads '$ST', not '$STAGE'." >&2
+ echo " A split stage misleads every reader; fix the file that differs before going on." >&2
+ exit 4
+fi
+exit 0
diff --git a/.claude/scripts/skill-lint.sh b/.claude/scripts/skill-lint.sh
new file mode 100644
index 00000000..828053c7
--- /dev/null
+++ b/.claude/scripts/skill-lint.sh
@@ -0,0 +1,267 @@
+#!/usr/bin/env bash
+# skill-lint.sh — the facts a static skill check reads off a skill by eye: which
+# frontmatter fields are there, how many phase headings, which verdict words,
+# whether it asks before writing, how it ends, whether it sets a fork context,
+# and what its argument hint says. Checks 1-7 of /skill-test static.
+#
+# Replaces the by-hand reading of checks 1-7 over a skill's SKILL.md and its
+# references/, the counting that goes wrong across 74 skills.
+#
+# OBSERVATIONS, NEVER VERDICTS (CLAUDE.md, "Helpers in .claude/scripts/"). It
+# prints what it found, check by check, and nothing here is a PASS, WARN or
+# FAIL: whether three phase headings are enough, whether `HIGH` in a skill is a
+# severity or a word, whether a hint matches its modes, and the one verdict the
+# skill reports (COMPLIANT, WARNINGS, NON-COMPLIANT, NOT ASSESSED) stay with
+# /skill-test. The rows hold the numbers and words those calls need.
+#
+# Usage: bash .claude/scripts/skill-lint.sh <name>|all [--root DIR]
+# <name> one skill, the folder name under .claude/skills/
+# all every folder under .claude/skills/ that holds a SKILL.md
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+#
+# Output: TSV. First `skills <n> .claude/skills`, then for each skill
+# skill <name> files=<SKILL.md + references read> lines=<n>
+# check1 <name> frontmatter=<ok|missing|unclosed|bad@LINE> missing=<list|-> name=<match|mismatch:<v>|absent>
+# check2 <name> phases=<distinct numbered phase headings> h2=<distinct ## headings> h2_total=<all of them>
+# check3 <name> verdicts=<WORD:count,...|-> assessment_words=<in the description|->
+# check4 <name> may_i_write=<n> before_writing=<n> approval=<n> ask_write_lines=<n> write_tools=<Write,Edit|->
+# check5 <name> last_section=<heading|-> skills_named=<in that section|-> next_phrases=<whole skill>/<last section>
+# check6 <name> context_fork=<yes|no> phases=<n> h2=<n>
+# check7 <name> hint=<text|empty|absent> args_section=<first Arguments/Parse heading@line|->
+# and last `checked <N> of <M>`: skills read, skills found. A folder with no
+# SKILL.md, or a SKILL.md that cannot be read, prints `NOT_READ <name> <reason>`
+# and is not counted as read, so a skill that was not linted never looks clean.
+# A references file that cannot be read is left out of files= and the counts.
+# Every check row is printed for every skill, including check6 for a skill that
+# sets no fork context: a skipped check says so (context_fork=no).
+#
+# How things are counted:
+# - headings are `## ` lines outside fenced code; a numbered phase is
+# `## Phase N...` or `## N.`; each heading text counts once, so a phase
+# repeated across SKILL.md and a reference file is one
+# - frontmatter is SKILL.md's, between the first two `---` lines; fields are
+# top-level `key:` lines
+# - verdict words are whole uppercase words from /skill-test check 3's three
+# lists, in SKILL.md and references together
+# - the Check 4 phrases are matched ignoring case; ask_write_lines counts lines
+# holding both "ask" and "writ"
+# - the last section is the last `## ` heading of SKILL.md and the text after
+# it; skills_named lists the /names in it that are skill folders
+#
+# Exit codes: 0 done; 1 cannot read the root or find .claude/skills; 2 usage
+# error; 3 no such skill. Reads only; never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk and sort.
+LC_ALL=C
+export LC_ALL
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+usage() { echo "skill-lint: $1 (try --help)" >&2; exit 2; }
+WHICH=""; ROOT_ARG=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ --root) [ $# -ge 2 ] || usage "--root needs a value"; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ -?*) usage "unknown argument: $1" ;;
+ *) [ -z "$WHICH" ] || usage "one skill name or all"; WHICH="$1"; shift ;;
+ esac
+done
+[ -n "$WHICH" ] || usage "no skill name given"
+case "$WHICH" in */*|*\\*|.*) usage "'$WHICH' is not a skill folder name" ;; esac
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "skill-lint: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "skill-lint: cannot reach the repo root" >&2; exit 1; }
+fi
+SK=".claude/skills"
+[ -d "$SK" ] || { echo "skill-lint: no $SK folder under $(pwd)" >&2; exit 1; }
+
+# Every folder under .claude/skills/, so skills_named can tell a skill from a path.
+NAMES="|"
+for d in "$SK"/*/; do
+ [ -d "$d" ] || continue
+ d=${d%/}; NAMES="$NAMES${d##*/}|"
+done
+
+if [ "$WHICH" = all ]; then
+ LIST_NAMES=""
+ for d in "$SK"/*/; do
+ [ -d "$d" ] || continue
+ d=${d%/}; LIST_NAMES="$LIST_NAMES${d##*/}
+"
+ done
+else
+ [ -d "$SK/$WHICH" ] || { echo "skill-lint: no skill folder $SK/$WHICH" >&2; exit 3; }
+ LIST_NAMES="$WHICH
+"
+fi
+
+printf 'skills\t%s\t%s\n' "$(printf '%s' "$LIST_NAMES" | grep -c .)" "$SK"
+
+# One line per file, SKILL.md first: name TAB path. A folder with no SKILL.md
+# gets a line with an empty path, which the awk reports as NOT_READ.
+{
+ while IFS= read -r n; do
+ [ -n "$n" ] || continue
+ if [ -f "$SK/$n/SKILL.md" ]; then
+ printf '%s\t%s\n' "$n" "$SK/$n/SKILL.md"
+ for r in "$SK/$n/references/"*.md; do [ -f "$r" ] && printf '%s\t%s\n' "$n" "$r"; done
+ else
+ printf '%s\t\n' "$n"
+ fi
+ done <<EOF
+$LIST_NAMES
+EOF
+} | SK_NAMES="$NAMES" awk -F'\t' '
+ # VERDICTS: /skill-test Check 3 three lists, as written there: the gate and
+ # review verdicts, the go and no-go verdicts, the severity scale.
+ BEGIN {
+ BINMODE = 3; split("", rs)
+ VERDICTS = "PASS FAIL CONCERNS APPROVED BLOCKED COMPLETE READY COMPLIANT NON-COMPLIANT PROCEED PIVOT KILL GO NO-GO CRITICAL HIGH MEDIUM LOW"
+ }
+ # cnt(s, w): whole-word occurrences of w in s (no letter, digit, _ or - on either side).
+ function cnt(s, w, re, n) {
+ re = "(^|[^A-Za-z0-9_-])" w "([^A-Za-z0-9_-]|$)"; n = 0
+ while (match(s, re)) { n++; s = substr(s, RSTART + RLENGTH - 1) }
+ return n
+ }
+ function occ(s, p, n, i) {
+ n = 0
+ while ((i = index(s, p)) > 0) { n++; s = substr(s, i + length(p)) }
+ return n
+ }
+ function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t\r]+$/, "", s); return s }
+ function unq(s, q) {
+ q = substr(s, 1, 1)
+ if ((q == "\"" || q == "\047") && substr(s, length(s), 1) == q && length(s) >= 2) return substr(s, 2, length(s) - 2)
+ return s
+ }
+ function reset() {
+ split("", fmv); split("", h2seen); split("", phseen); split("", vcount); split("", named)
+ fmstate = "missing"; badline = 0; h2total = 0; h2dist = 0; phdist = 0
+ may = 0; bef = 0; apr = 0; askw = 0; nextall = 0; nextlast = 0; lastsec = ""; lastskills = ""
+ argsh = ""; argsat = 0; nfiles = 0; nlines = 0; skillread = 0; unreadable = ""
+ nextsec = 0; secskills = ""
+ }
+ function flush( i, k, req, miss, nm, vs, wt, tools, fm, hint, aw, w, ctx) {
+ if (cur == "") return
+ if (!skillread) {
+ printf "NOT_READ\t%s\t%s\n", cur, (unreadable != "" ? unreadable : "no SKILL.md")
+ return
+ }
+ read++
+ printf "skill\t%s\tfiles=%d\tlines=%d\n", cur, nfiles, nlines
+ # check 1: the five fields Check 1 requires
+ req = "name description argument-hint user-invocable allowed-tools"
+ n = split(req, ra, " "); miss = ""
+ for (i = 1; i <= n; i++) if (!(ra[i] in fmv)) miss = miss (miss == "" ? "" : ",") ra[i]
+ if (fmstate == "bad") fm = "bad@" badline; else fm = fmstate
+ if (!("name" in fmv)) nm = "absent"
+ else if (unq(fmv["name"]) == cur) nm = "match"
+ else nm = "mismatch:" unq(fmv["name"])
+ printf "check1\t%s\tfrontmatter=%s\tmissing=%s\tname=%s\n", cur, fm, (miss == "" ? "-" : miss), nm
+ # check 2
+ printf "check2\t%s\tphases=%d\th2=%d\th2_total=%d\n", cur, phdist, h2dist, h2total
+ # check 3
+ vs = ""
+ n = split(VERDICTS, va, " ")
+ for (i = 1; i <= n; i++) if (vcount[va[i]] > 0) vs = vs (vs == "" ? "" : ",") va[i] ":" vcount[va[i]]
+ aw = ""
+ # The judgements Check 3 names (a review, audit, check, gate or readiness
+ # judgement) and three words descriptions use for the same promise (ready,
+ # validate, assess). Whole words, so "Reviews" is not counted as "review".
+ n = split("review audit check gate ready readiness validate assess", wa, " ")
+ for (i = 1; i <= n; i++) if (cnt(tolower(fmv["description"]), wa[i]) > 0) aw = aw (aw == "" ? "" : ",") wa[i]
+ printf "check3\t%s\tverdicts=%s\tassessment_words=%s\n", cur, (vs == "" ? "-" : vs), (aw == "" ? "-" : aw)
+ # check 4
+ tools = ""
+ if (cnt(fmv["allowed-tools"], "Write") > 0) tools = "Write"
+ if (cnt(fmv["allowed-tools"], "Edit") > 0) tools = tools (tools == "" ? "" : ",") "Edit"
+ printf "check4\t%s\tmay_i_write=%d\tbefore_writing=%d\tapproval=%d\task_write_lines=%d\twrite_tools=%s\n", cur, may, bef, apr, askw, (tools == "" ? "-" : tools)
+ # check 5
+ printf "check5\t%s\tlast_section=%s\tskills_named=%s\tnext_phrases=%d/%d\n", cur, (lastsec == "" ? "-" : lastsec), (lastskills == "" ? "-" : lastskills), nextall, nextlast
+ # check 6
+ ctx = ("context" in fmv && unq(fmv["context"]) == "fork") ? "yes" : "no"
+ printf "check6\t%s\tcontext_fork=%s\tphases=%d\th2=%d\n", cur, ctx, phdist, h2dist
+ # check 7
+ if (!("argument-hint" in fmv)) hint = "absent"
+ else { hint = unq(trim(fmv["argument-hint"])); if (hint == "") hint = "empty" }
+ printf "check7\t%s\thint=%s\targs_section=%s\n", cur, hint, (argsh == "" ? "-" : argsh "@" argsat)
+ }
+ function scan(path, isskill, l, ll, n, infm, infence, key, v, h, sec, p, nmx, rc, started, nm2, cut, curkey, x) {
+ n = 0; infm = 0; infence = 0; started = 0; curkey = ""
+ while ((rc = (getline l < path)) > 0) {
+ n++; nlines++
+ sub(/\r$/, "", l)
+ if (isskill && n == 1) {
+ if (l == "---") { infm = 1; fmstate = "unclosed"; continue }
+ fmstate = "missing"
+ }
+ # Verdict words count in the frontmatter too: /prototype advertises PROCEED,
+ # PIVOT and KILL in its description.
+ if (l ~ /[A-Z][A-Z]/) {
+ nm2 = split(VERDICTS, va2, " ")
+ for (x = 1; x <= nm2; x++) vcount[va2[x]] += cnt(l, va2[x])
+ }
+ if (infm) {
+ if (l == "---") { infm = 0; fmstate = (fmstate == "bad" ? "bad" : "ok"); continue }
+ if (trim(l) == "" || substr(trim(l), 1, 1) == "#") continue
+ if (substr(l, 1, 1) == " " || substr(l, 1, 1) == "\t" || substr(l, 1, 2) == "- ") {
+ if (curkey != "") fmv[curkey] = fmv[curkey] " " trim(l)
+ continue
+ }
+ p = index(l, ":")
+ if (p < 2 || substr(l, 1, 1) == "#") { if (fmstate != "bad") { badline = n; fmstate = "bad" } ; continue }
+ curkey = substr(l, 1, p - 1); sub(/[ \t]+$/, "", curkey)
+ fmv[curkey] = trim(substr(l, p + 1))
+ continue
+ }
+ if (l ~ /^[ \t]*(```|~~~)/) infence = !infence
+ ll = tolower(l)
+ # Check 4 phrases, then Check 5 phrases, as those checks list them.
+ may += occ(ll, "may i write"); bef += occ(ll, "before writing"); apr += occ(ll, "approval")
+ if (ll ~ /(^|[^a-z])ask/ && ll ~ /(^|[^a-z])writ/) askw++
+ p = occ(ll, "next step") + occ(ll, "recommended next") + occ(ll, "follow-up") + occ(ll, "follow up") + occ(ll, "after this")
+ nextall += p
+ if (isskill) nextsec += p
+ if (!infence && substr(l, 1, 3) == "## ") {
+ h = trim(substr(l, 4)); h2total++
+ if (!(h in h2seen)) { h2seen[h] = 1; h2dist++ }
+ if ((h ~ /^Phase [0-9]/ || h ~ /^[0-9]+\./) && !(h in phseen)) { phseen[h] = 1; phdist++ }
+ if (isskill) {
+ lastsec = h; nextsec = p; secskills = ""
+ if (argsh == "" && h ~ /([Aa]rgument|Parse)/) { argsh = h; argsat = n }
+ }
+ }
+ if (isskill && lastsec != "") {
+ # /names in the last section that are skill folders
+ cut = l
+ while (match(cut, /(^|[^A-Za-z0-9_\/.~-])\/[a-z][a-z0-9-]*/)) {
+ nm3 = substr(cut, RSTART, RLENGTH); sub(/^[^\/]*\//, "", nm3)
+ if (index(ENVIRON["SK_NAMES"], "|" nm3 "|") > 0 && index("," secskills ",", "," nm3 ",") == 0) secskills = secskills (secskills == "" ? "" : ",") nm3
+ cut = substr(cut, RSTART + RLENGTH)
+ }
+ lastskills = secskills; nextlast = nextsec
+ }
+ }
+ if (rc < 0) { unreadable = "cannot read " path; return 0 }
+ close(path)
+ nfiles++
+ if (isskill) skillread = 1
+ return 1
+ }
+ BEGIN { cur = ""; total = 0; read = 0; reset() }
+ {
+ if ($1 != cur) { flush(); cur = $1; total++; reset() }
+ if ($2 == "") next
+ scan($2, ($2 ~ /\/SKILL\.md$/))
+ }
+ END { flush(); printf "checked\t%d of %d\n", read, total }
+'
+exit 0
diff --git a/.claude/scripts/story-facts.sh b/.claude/scripts/story-facts.sh
new file mode 100644
index 00000000..af477717
--- /dev/null
+++ b/.claude/scripts/story-facts.sh
@@ -0,0 +1,326 @@
+#!/usr/bin/env bash
+# story-facts.sh — the facts skills read off story files by hand, one row per
+# story, and with --lint the story-readiness rules each story trips.
+#
+# Replaces the hand-run story reads in /story-readiness, /story-done and
+# /dev-story. story-status.sh still prints the route order /help and
+# /sprint-status inject; the status column here applies its rule word for
+# word, so the two never disagree.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# A LINT row is a rule that matched, with the numbers that made it match;
+# READY, NEEDS WORK or BLOCKED is still the skill's to say.
+#
+# Usage: bash .claude/scripts/story-facts.sh [--root DIR] [--all | --sprint | PATH ...] [--lint]
+# [--granularity coarse|balanced|fine]
+# --all every production/epics/**/story-*.md (the default)
+# --sprint the stories production/sprint-status.yaml lists in its file:
+# entries, the only place a sprint names story paths
+# PATH ... these story files, relative to the root
+# --lint also print the rules each story trips
+# --granularity the AC minimums --lint applies (below); default coarse
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+#
+# Output: TSV. Counts first (stories <n> <scope>, then one count per state, and
+# lint <n> with --lint), then
+# STORY <path> <state> <status> <type> <layer> <estimate> <tr_ids> <adrs>
+# <ac> <qa_cases> <test_evidence> <depends_on> <sprint_status>
+# LINT <path> <rule> <detail>
+# NOT_FOUND <path> a PATH or a sprint file: entry that is not a file
+# Columns (`-` means not there; UNFILLED means still the template's [bracket]):
+# state story-status.sh's grouping of the first `Status:` line:
+# COMPLETE, IN_REVIEW, IN_PROGRESS, TODO (Ready or Not Started),
+# BLOCKED, OTHER or NO_STATUS
+# status that line's value as written
+# type, layer, estimate the header fields (`> **Type**: Logic` and the
+# other forms story-status.sh reads)
+# tr_ids every TR-<system>-<number> in the file, comma-separated
+# adrs the ADR ids on the governing-ADR line (`ADR Governing
+# Implementation`, `Governing ADRs`, `ADR`), or n/a
+# ac `- [ ]` and `- [x]` items under `## Acceptance Criteria`
+# qa_cases `- **AC-N**` items under `## QA Test Cases`
+# test_evidence the `Status:` line under `## Test Evidence`
+# depends_on the `Depends on:` line under `## Dependencies`
+# sprint_status the story's status in sprint-status.yaml (--sprint only)
+# LINT rules (from /story-readiness):
+# no_status, type_missing, type_unknown <value>, unfilled <field>,
+# no_tr_id, no_ac_section, ac_below_min <count> < <minimum> (<type>),
+# marker <TBD|TODO|UNRESOLVED> line <n>
+# The AC minimums by type are story-readiness's, and follow
+# --granularity (story_granularity, the AC load /create-stories writes to):
+# coarse (the default) Logic 3, Integration 3, Visual/Feel 2, UI 2, Config/Data 1
+# balanced Logic 2, Integration 2, Visual/Feel 2, UI 2, Config/Data 1
+# fine 1 for every type
+# A marker counts as a whole word in capitals, outside code fences and HTML
+# comments. A <!-- inside a code span (`<!--`) opens no comment.
+#
+# Exit codes: 0 every story asked for was read; 1 the root cannot be read;
+# 2 usage error; 3 --sprint with no sprint-status.yaml, or a PATH or file:
+# entry that is not a file (its NOT_FOUND row is printed, the rest are still
+# reported). Reads only; never writes, never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk, sort and tolower.
+LC_ALL=C
+export LC_ALL
+
+SCOPE="all"; LINT=0; ROOT_ARG=""; PATHS=""; GRAN="coarse"
+NL='
+'
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --all) SCOPE="all"; shift ;;
+ --sprint) SCOPE="sprint"; shift ;;
+ --lint) LINT=1; shift ;;
+ --root)
+ [ $# -ge 2 ] || { echo "story-facts: --root needs a value" >&2; exit 2; }
+ ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --granularity)
+ [ $# -ge 2 ] || { echo "story-facts: --granularity needs a value" >&2; exit 2; }
+ GRAN="$2"; shift 2 ;;
+ --granularity=*) GRAN="${1#--granularity=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) echo "story-facts: unknown argument: $1 (try --help)" >&2; exit 2 ;;
+ *) PATHS="$PATHS$1$NL"; SCOPE="paths"; shift ;;
+ esac
+done
+case "$GRAN" in
+ coarse|balanced|fine) ;;
+ *) echo "story-facts: --granularity takes coarse, balanced or fine, not: $GRAN" >&2; exit 2 ;;
+esac
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "story-facts: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$(dirname "$0")/../.." 2>/dev/null || { echo "story-facts: cannot reach the repo root" >&2; exit 1; }
+fi
+
+YAML="production/sprint-status.yaml"
+SPRINT="" # "path<TAB>status" per story, from the yaml
+case "$SCOPE" in
+ all) LIST=$(find production/epics -type f -name 'story-*.md' 2>/dev/null | sort) ;;
+ sprint)
+ [ -f "$YAML" ] || { echo "story-facts: no $YAML; --sprint has no story paths to read (try --all)" >&2; exit 3; }
+ # Each `- ` entry under stories: gives one story; its file: and status:
+ # values, quotes and trailing comments removed.
+ SPRINT=$(Q="'" awk '
+ # A value: quoted (to its closing quote) or bare (to a " #" comment).
+ function val(s, c, e) {
+ sub(/^[^:]*:[ \t]*/, "", s); c = substr(s, 1, 1)
+ if (c == "\"" || c == ENVIRON["Q"]) { e = index(substr(s, 2), c); return (e > 0) ? substr(s, 2, e - 1) : substr(s, 2) }
+ sub(/[ \t]+#.*$/, "", s); sub(/[ \t]+$/, "", s); return s
+ }
+ { sub(/\r$/, "") }
+ /^stories:/ { in_s = 1; next }
+ /^[^ \t#-]/ { if (in_s) { emit(); in_s = 0 } }
+ function emit() { if (f != "") printf "%s\t%s\n", f, (st == "" ? "-" : st); f = ""; st = "" }
+ in_s && /^[ \t]*- / { emit() }
+ in_s && /^[ \t]*(- )?file:/ { f = val($0) }
+ in_s && /^[ \t]*(- )?status:/ { st = val($0) }
+ END { if (in_s) emit() }
+ ' "$YAML")
+ LIST=$(printf '%s\n' "$SPRINT" | cut -f1 | awk 'NF') ;;
+ paths) LIST=$(printf '%s' "$PATHS" | awk 'NF') ;;
+esac
+
+FILES=""; MISSED=""
+while IFS= read -r f; do
+ [ -n "$f" ] || continue
+ f="${f#./}"
+ if [ -f "$f" ]; then FILES="$FILES$f$NL"; else MISSED="$MISSED$f$NL"; fi
+done <<EOF
+$LIST
+EOF
+
+
+SCOPE_LABEL="$SCOPE"
+[ "$SCOPE" = all ] && SCOPE_LABEL="production/epics/**/story-*.md"
+[ "$SCOPE" = sprint ] && SCOPE_LABEL="$YAML"
+
+# The file list goes to awk on stdin, never as arguments: thousands of paths
+# would pass the command-line limit of some systems. Each becomes an input
+# file, "./" in front so a name like x=1.md is not read as an assignment.
+printf '%s' "$FILES" | awk 'NF { sub(/^\.\//, ""); print }' | \
+LINT="$LINT" GRAN="$GRAN" SPRINT="$SPRINT" SCOPE_LABEL="$SCOPE_LABEL" awk '
+ BEGIN {
+ BINMODE = 3 # Git for Windows gawk reads in text mode otherwise; harmless elsewhere
+ # The list arrives on /dev/stdin, named, so the main input stays the files: with
+ # a bare getline, gawk read the first file as more of stdin and skipped its FNR 1.
+ while ((getline f < "/dev/stdin") > 0) lst[++nlst] = f
+ for (i = 1; i <= nlst; i++) ARGV[ARGC++] = "./" lst[i]
+ lint = (ENVIRON["LINT"] == "1")
+ n = split(ENVIRON["SPRINT"], sl, "\n")
+ for (i = 1; i <= n; i++) if (sl[i] != "") { split(sl[i], kv, "\t"); k = kv[1]; sub(/^\.\//, "", k); ystat[k] = kv[2] }
+ # The header fields read as columns or checked for an unfilled [bracket].
+ nfl = split("Type,Layer,Estimate,Epic,Manifest Version", fl, ",")
+ # story-readiness: the fewest acceptance criteria each story type needs, at
+ # the granularity the stories were written to (/create-stories writes 5-10
+ # ACs a story at coarse, 2-4 at balanced, 1 at fine).
+ acmin["logic"] = 3; acmin["integration"] = 3; acmin["visual/feel"] = 2; acmin["ui"] = 2; acmin["config/data"] = 1
+ if (ENVIRON["GRAN"] == "balanced") { acmin["logic"] = 2; acmin["integration"] = 2 }
+ if (ENVIRON["GRAN"] == "fine") for (k in acmin) acmin[k] = 1
+ ntypes = split("Logic Integration Visual/Feel UI Config/Data", tnames, " ")
+ }
+ function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
+ function clean(s) { gsub(/\t/, " ", s); s = trim(s); return (s == "") ? "-" : s }
+ # story-status.sh normalisation: trim, one "> " and one "- " off, every * out.
+ function fnorm(s) { sub(/^[ \t]+/, "", s); sub(/^> /, "", s); sub(/^- /, "", s); gsub(/\*/, "", s); return s }
+ function fval(s, name, t) { # value of field `name` on line s, or "\001" when it is not that field
+ t = fnorm(s)
+ if (tolower(substr(t, 1, length(name) + 1)) != tolower(name) ":") return "\001"
+ return trim(substr(t, length(name) + 2))
+ }
+ function bracketed(v) { return substr(v, 1, 1) == "[" }
+ # Where a code span that opens with the k backticks ending just before t
+ # closes: the index in t of a run of exactly k backticks, or 0 when none
+ # does on this line (the opening run is then plain text).
+ function span_end(t, k, i, j) {
+ i = 1
+ while (i <= length(t)) {
+ if (substr(t, i, 1) != "`") { i++; continue }
+ j = i; while (substr(t, j, 1) == "`") j++
+ if (j - i == k) return i
+ i = j
+ }
+ return 0
+ }
+ function fence_of(s, n, c, k) {
+ n = 0; while (n < 3 && substr(s, n + 1, 1) == " ") n++
+ s = substr(s, n + 1); c = substr(s, 1, 1)
+ if (c != "`" && c != "~") return ""
+ k = 0; while (substr(s, k + 1, 1) == c) k++
+ return (k >= 3) ? substr(s, 1, k) : ""
+ }
+ function closes(s, f, n, c, k) {
+ n = 0; while (n < 3 && substr(s, n + 1, 1) == " ") n++
+ s = substr(s, n + 1); c = substr(f, 1, 1)
+ k = 0; while (substr(s, k + 1, 1) == c) k++
+ return k >= length(f) && trim(substr(s, k + 1)) == ""
+ }
+ function add_ids(list, s, pat, id) {
+ while (match(s, pat)) {
+ id = substr(s, RSTART, RLENGTH); s = substr(s, RSTART + RLENGTH)
+ if (index("," list ",", "," id ",") == 0) list = list (list == "" ? "" : ",") id
+ }
+ return list
+ }
+ function lintrow(rule, detail) { nl++; lrows[nl] = "LINT\t" path "\t" rule "\t" detail }
+
+ function flush( s, state, t, tl, i, known, m) {
+ if (path == "") return
+ s = tolower(status)
+ if (!has_status) state = "NO_STATUS"
+ else if (s ~ /^(complete|done)([^a-z]|$)/) state = "COMPLETE"
+ else if (s ~ /^in progress([^a-z]|$)/) state = "IN_PROGRESS"
+ else if (s ~ /^in review([^a-z]|$)/) state = "IN_REVIEW"
+ else if (s ~ /^(ready|not started)([^a-z]|$)/) state = "TODO"
+ else if (s ~ /^blocked([^a-z]|$)/) state = "BLOCKED"
+ else state = "OTHER"
+ cnt[state]++
+ t = (type == "") ? "-" : (bracketed(type) ? "UNFILLED" : type)
+ adrv = "-"
+ if (adr_line != "") { adrv = add_ids("", tolower(adr_line), "adr-[0-9]+"); if (adrv == "") adrv = (tolower(adr_line) ~ /n\/a/) ? "n/a" : (bracketed(adr_line) ? "UNFILLED" : "-") }
+ nst++
+ rows[nst] = "STORY\t" path "\t" state "\t" clean(status) "\t" t "\t" clean(bracketed(layer) ? "UNFILLED" : layer) "\t" \
+ clean(bracketed(estimate) ? "UNFILLED" : estimate) "\t" (trs == "" ? "-" : trs) "\t" adrv "\t" \
+ (has_ac ? ac : "-") "\t" (has_qa ? qa : "-") "\t" clean(te) "\t" clean(dep) "\t" ((path in ystat) ? ystat[path] : "-")
+ if (lint) {
+ if (!has_status) lintrow("no_status", "-")
+ if (type == "") lintrow("type_missing", "-")
+ else if (!bracketed(type)) {
+ known = ""; tl = tolower(type)
+ for (i = 1; i <= ntypes; i++) if (tl == tolower(tnames[i])) known = tl
+ if (known == "") lintrow("type_unknown", clean(type))
+ else if (has_ac && ac < acmin[known]) lintrow("ac_below_min", ac " < " acmin[known] " (" type ")")
+ }
+ for (i = 1; i <= nunf; i++) lintrow("unfilled", unf[i])
+ if (trs == "") lintrow("no_tr_id", "-")
+ if (!has_ac) lintrow("no_ac_section", "-")
+ for (m = 1; m <= nmark; m++) lintrow("marker", marks[m])
+ }
+ path = ""
+ }
+
+ FNR == 1 {
+ flush()
+ path = substr(FILENAME, 3); infence = ""; incomment = 0; sec = ""
+ status = ""; has_status = 0; type = ""; layer = ""; estimate = ""; trs = ""; adr_line = ""
+ ac = 0; has_ac = 0; qa = 0; has_qa = 0; te = ""; dep = ""; nunf = 0; nmark = 0
+ split("", seenf)
+ }
+ {
+ line = $0; sub(/\r$/, "", line)
+ # The Status line exactly as story-status.sh finds it: the first anywhere.
+ if (!has_status) { v = fval(line, "Status"); if (v != "\001" && substr(fnorm(line), 1, 7) == "Status:") { status = v; has_status = 1 } }
+ if (infence) { if (closes(line, infence)) infence = ""; next }
+ f = fence_of(line); if (f != "") { infence = f; next }
+ # What is left of the line outside HTML comments. A <!-- inside a code
+ # span (`<!--`) is text: a span is a run of backticks closed by a run as
+ # long on the same line.
+ cstart = incomment; rest = ""; s = line
+ while (s != "") {
+ if (incomment) { p = index(s, "-->"); if (p == 0) { s = ""; break } s = substr(s, p + 3); incomment = 0; continue }
+ p = index(s, "<!--"); bq = index(s, "`")
+ if (bq > 0 && (p == 0 || bq < p)) {
+ bk = 0; while (substr(s, bq + bk, 1) == "`") bk++
+ be = span_end(substr(s, bq + bk), bk)
+ bn = (be > 0) ? bq + bk + be - 1 + bk : bq + bk
+ rest = rest substr(s, 1, bn - 1); s = substr(s, bn)
+ continue
+ }
+ if (p == 0) { rest = rest s; s = ""; break }
+ rest = rest substr(s, 1, p - 1); s = substr(s, p + 4); incomment = 1
+ }
+ if (!cstart && line ~ /^ ? ? ?#+[ \t]/) {
+ h = line; sub(/^ */, "", h); k = 0; while (substr(h, k + 1, 1) == "#") k++
+ if (k <= 6) { if (k <= 2) { t = tolower(substr(h, k + 1)); gsub(/^[ \t]+|[ \t#]+$/, "", t); sec = (k == 2) ? t : "" } ; next }
+ }
+ r = trim(rest)
+ if (r == "") next
+ # Header fields: the first line of each, anywhere outside fences.
+ for (i = 1; i <= nfl; i++) {
+ nm = fl[i]
+ if (!(nm in seenf) && (v = fval(r, nm)) != "\001") {
+ seenf[nm] = 1
+ if (nm == "Type") type = v; else if (nm == "Layer") layer = v; else if (nm == "Estimate") estimate = v
+ if (bracketed(v)) unf[++nunf] = nm
+ }
+ }
+ if (adr_line == "") {
+ if ((v = fval(r, "ADR Governing Implementation")) != "\001" || (v = fval(r, "Governing ADRs")) != "\001" || (v = fval(r, "ADR")) != "\001") adr_line = (v == "") ? "-" : v
+ }
+ trs = add_ids(trs, r, "TR-[A-Za-z0-9][A-Za-z0-9-]*-[0-9]+")
+ if (sec == "acceptance criteria") { has_ac = 1; if (r ~ /^[-*] \[[ xX]\]/) ac++ }
+ if (sec == "qa test cases") { has_qa = 1; if (r ~ /^[-*] \*\*AC-[0-9]+\*\*/) qa++ }
+ if (sec == "test evidence" && te == "" && (v = fval(r, "Status")) != "\001") te = v
+ if (sec == "dependencies" && dep == "" && (v = fval(r, "Depends on")) != "\001") dep = v
+ # TBD, TODO and UNRESOLVED as whole words in capitals.
+ s = " " r " "
+ while (match(s, /[^A-Za-z0-9_](TBD|TODO|UNRESOLVED)[^A-Za-z0-9_]/)) {
+ marks[++nmark] = substr(s, RSTART + 1, RLENGTH - 2) " line " FNR
+ s = substr(s, RSTART + RLENGTH - 1)
+ }
+ }
+ END {
+ flush()
+ printf "stories\t%d\t%s\n", nst, ENVIRON["SCOPE_LABEL"]
+ split("COMPLETE IN_REVIEW IN_PROGRESS TODO BLOCKED OTHER NO_STATUS", st, " ")
+ for (i = 1; i <= 7; i++) printf "%s\t%d\n", tolower(st[i]), cnt[st[i]] + 0
+ if (lint) printf "lint\t%d\n", nl
+ for (i = 1; i <= nst; i++) print rows[i]
+ for (i = 1; i <= nl; i++) print lrows[i]
+ }
+'
+
+rc=0
+while IFS= read -r m; do
+ [ -n "$m" ] || continue
+ printf 'NOT_FOUND\t%s\n' "$m"; rc=3
+done <<EOF
+$MISSED
+EOF
+exit $rc
diff --git a/.claude/scripts/story-status.sh b/.claude/scripts/story-status.sh
index 98159d76..fdcdc79d 100644
--- a/.claude/scripts/story-status.sh
+++ b/.claude/scripts/story-status.sh
@@ -7,9 +7,9 @@
#
# WHY A SCRIPT. The route's rule is "an In Review story is next (its work is
# written; close it), else an In Progress one, else the first Ready or Not
-# Started one in build order". Given every status line at once, a small model
-# ranked them by file order and got the Ready/Not Started case wrong; listing the
-# stories already in the route's order leaves nothing to rank. (In Review comes
+# Started one in build order". Ranking every status line by hand drifts toward
+# file order and gets the Ready/Not Started case wrong; listing the stories
+# already in the route's order leaves nothing to rank. (In Review comes
# first: its work is already written, /story-done is quick, and closing it
# keeps finished work from piling up behind started work.)
#
diff --git a/.claude/scripts/test-run.sh b/.claude/scripts/test-run.sh
new file mode 100644
index 00000000..57301500
--- /dev/null
+++ b/.claude/scripts/test-run.sh
@@ -0,0 +1,435 @@
+#!/usr/bin/env bash
+# test-run.sh — run a project's automated tests the way /smoke-check Phase 2
+# does, under a timeout, and read the result with that phase's exit-code ladder
+# for the engine: the command, the timeout, the exit code, the zero-tests
+# marker, the counts, and the ladder row that matched.
+#
+# Replaces the hand-run test command, `timeout`, exit-code reading and "looks
+# like success and is not" cases.
+#
+# OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/"). The
+# `rule` row says which row of the ladder the exit code and output fall on, in
+# plain words; PASS, FAIL, NOT ASSESSED and "PASS WITH WARNINGS" stay with
+# /smoke-check, which also decides what an unmatched exit code means.
+#
+# Usage: bash .claude/scripts/test-run.sh <engine> [options]
+# <engine> godot, unity or unreal (any case)
+# --cmd COMMAND the test command to run, instead of project.yaml's
+# commands.test or the engine's default
+# --exe PATH the editor executable (default: the one commands.test
+# names, for godot only when its name says godot, else
+# engine.path, else godot / Unity on PATH); for unreal,
+# the UE root
+# --platform P unity only: editmode (default) or playmode
+# --timeout SECONDS default 900; 1800 for unreal
+# --os windows|linux|macos
+# unreal only: default is read from `uname -s`
+# --filter ROOT unreal only: the automation test root (default: the
+# .uproject's name); read one test name when unsure
+# --no-build unreal only: skip the build that comes first
+# --tool T force the timeout tool: timeout, gtimeout, perl or none (the
+# tests use this to reach the perl and no-tool paths)
+# --log FILE keep the runner's output here (default: a temp file); the
+# import's or the build's output goes to FILE.pre
+# --dry-run print what would run; run nothing
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+#
+# The timeout is `timeout`, else `gtimeout`, else perl (the command in its own
+# process group, which gets TERM at the timeout and KILL five seconds on, as
+# coreutils timeout does), whichever exists first; the `timeout` row names it,
+# or `none` when no timeout tool exists and the run is unbounded. An exit of
+# 124 (timeout, gtimeout) or 142 (perl) is a timeout.
+#
+# Before the test run, per engine: godot checks addons/gdUnit4/bin/GdUnitCmdTool.gd,
+# then runs the import (`--headless --path . --import`) with the editor
+# executable, whether the test command is commands.test or the default; unity
+# checks Packages/manifest.json names com.unity.test-framework and deletes the
+# old results file; unreal builds the editor target first (it needs the UE root),
+# and a build that fails or times out runs no test, because the tests would run
+# against the last good binaries or not load at all. A check that fails runs
+# nothing and prints why. The import and the build each have a row saying what
+# runs, or why it does not, and their output goes to its own log (pre_log), so
+# nothing they print is read as the tests' output.
+#
+# Output: TSV, in this order (a row that cannot apply is left out).
+# engine <Godot|Unity|Unreal>
+# exe <path|-> <commands.test|engine.path|path|--exe|->
+# command <--cmd|commands.test|default> <the command>
+# import <command> | - <skipped: why> godot, before the tests
+# build <command> | - <skipped: why> unreal, before the tests
+# timeout <seconds> <timeout|gtimeout|perl|none>
+# precheck <what> <present|absent>
+# import_exit, build_exit <code> when it ran
+# import_timed_out, build_timed_out <yes|no> when it ran
+# ran <yes|no> <why not, or ->
+# exit <code of the test command>
+# timed_out <yes|no>
+# results_file <path> <present|absent> unity
+# zero_tests <yes|no|unknown> <the marker line, or -> godot, unity, unreal
+# tests total=<n> passed=<n> failed=<n> unity (the <test-run> element),
+# unreal (Result={...} lines);
+# godot: `- not sourced`
+# failed <a line naming a failing test> (up to 10, then `failed_more <n>`)
+# evidence <a line that backs the rule>
+# rule <id> <what that row of the ladder says> `-` when no row fits
+# pre_log <path> when the import or build ran
+# log <path>
+# Rule ids: timeout, runner-unavailable, godot:no-gdunit4, godot:0, godot:0-zero,
+# godot:101, godot:100, godot:105, godot:103, godot:104, godot:1, godot:1-no-import,
+# unity:no-test-framework, unity:0, unity:zero-tests, unity:no-count,
+# unity:no-results, unity:2, unity:1, unity:3, unity:4, unity:other,
+# unreal:mac-unsourced, unreal:build-failed, unreal:result-fail,
+# unreal:no-tests-matched, unreal:pass, unreal:other-nonzero.
+#
+# Exit codes: 0 the helper finished (whatever the tests did: read the rows);
+# 1 cannot read the root or write the log; 2 usage error; 3 unknown engine.
+# It runs the project's own test command and writes under the project (Unity's
+# results file, the engine's caches); it never prompts and never edits
+# project.yaml.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk and sort.
+LC_ALL=C
+export LC_ALL
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+usage() { echo "test-run: $1 (try --help)" >&2; exit 2; }
+ENGINE_ARG=""; CMD_ARG=""; EXE_ARG=""; PLATFORM="editmode"; TIMEOUT=""; OS_ARG=""; FILTER=""
+NOBUILD=0; LOG=""; DRY=0; ROOT_ARG=""; TOOL_ARG=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ --dry-run) DRY=1; shift ;;
+ --no-build) NOBUILD=1; shift ;;
+ --cmd|--exe|--platform|--timeout|--os|--filter|--log|--root|--tool)
+ [ $# -ge 2 ] || usage "$1 needs a value"
+ case "$1" in
+ --cmd) CMD_ARG="$2" ;; --exe) EXE_ARG="$2" ;; --platform) PLATFORM="$2" ;;
+ --timeout) TIMEOUT="$2" ;; --os) OS_ARG="$2" ;; --filter) FILTER="$2" ;;
+ --log) LOG="$2" ;; --root) ROOT_ARG="$2" ;; --tool) TOOL_ARG="$2" ;;
+ esac
+ shift 2 ;;
+ -?*) usage "unknown argument: $1" ;;
+ *) [ -z "$ENGINE_ARG" ] || usage "one engine only"; ENGINE_ARG="$1"; shift ;;
+ esac
+done
+[ -n "$ENGINE_ARG" ] || usage "no engine given"
+case "$(printf '%s' "$ENGINE_ARG" | tr 'A-Z' 'a-z')" in
+ godot) ENGINE=godot; ENAME=Godot ;;
+ unity) ENGINE=unity; ENAME=Unity ;;
+ unreal) ENGINE=unreal; ENAME=Unreal ;;
+ *) echo "test-run: '$ENGINE_ARG' is not an engine this knows (godot, unity, unreal)" >&2; exit 3 ;;
+esac
+case "$PLATFORM" in editmode|playmode) ;; *) usage "--platform is editmode or playmode" ;; esac
+case "$OS_ARG" in ""|windows|linux|macos) ;; *) usage "--os is windows, linux or macos" ;; esac
+# /smoke-check Phase 2's limits: `timeout 900` for a test run, `timeout 1800` for
+# Unreal, whose editor build and start-up come before any test.
+if [ -z "$TIMEOUT" ]; then if [ "$ENGINE" = unreal ]; then TIMEOUT=1800; else TIMEOUT=900; fi; fi
+case "$TIMEOUT" in ''|*[!0-9]*) usage "--timeout is whole seconds" ;; esac
+[ "$TIMEOUT" -gt 0 ] || usage "--timeout must be above 0"
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "test-run: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "test-run: cannot reach the repo root" >&2; exit 1; }
+fi
+[ -f "$HERE/yaml-get.awk" ] || { echo "test-run: $HERE/yaml-get.awk is missing" >&2; exit 1; }
+yget() { [ -f project.yaml ] && YG_PATH="$1" awk -f "$HERE/yaml-get.awk" project.yaml; }
+
+printf 'engine\t%s\n' "$ENAME"
+
+# --- the editor executable ----------------------------------------------------
+CFG_TEST=$(yget commands.test); ENGINE_PATH=$(yget engine.path)
+# exe_ok P — an existing file, or a command found on PATH.
+exe_ok() { [ -n "$1" ] && { [ -f "$1" ] || command -v "$1" >/dev/null 2>&1; }; }
+EXE=""; EXE_SRC="-"
+if [ -n "$EXE_ARG" ]; then
+ EXE="$EXE_ARG"; EXE_SRC="--exe"
+else
+ # The executable commands.test names: its quoted path, else its first word.
+ # For Godot it counts only when its file name says godot (godot, godot4,
+ # Godot_v4.7-stable_win64.exe): a wrapper such as `bash run-tests.sh` is not
+ # the editor, and the import would run it with the editor's flags.
+ first=""
+ if [ -n "$CFG_TEST" ]; then
+ case "$CFG_TEST" in
+ \"*) first=${CFG_TEST#\"}; first=${first%%\"*} ;;
+ \'*) first=${CFG_TEST#\'}; first=${first%%\'*} ;;
+ *) first=${CFG_TEST%% *} ;;
+ esac
+ fi
+ if [ "$ENGINE" = godot ]; then
+ _base=${first##*/}; _base=$(printf '%s' "${_base##*\\}" | tr 'A-Z' 'a-z')
+ case "$_base" in *godot*) ;; *) first="" ;; esac
+ fi
+ if [ "$ENGINE" != unreal ] && exe_ok "$first"; then EXE="$first"; EXE_SRC="commands.test"
+ elif [ -n "$ENGINE_PATH" ] && { [ "$ENGINE" = unreal ] && [ -d "$ENGINE_PATH" ] || { [ "$ENGINE" != unreal ] && exe_ok "$ENGINE_PATH"; }; }; then EXE="$ENGINE_PATH"; EXE_SRC="engine.path"
+ elif [ "$ENGINE" = godot ] && exe_ok godot; then EXE="godot"; EXE_SRC="path"
+ elif [ "$ENGINE" = unity ] && exe_ok Unity; then EXE="Unity"; EXE_SRC="path"
+ fi
+fi
+printf 'exe\t%s\t%s\n' "${EXE:--}" "$EXE_SRC"
+
+# --- timeout tool -------------------------------------------------------------
+if [ -n "$TOOL_ARG" ]; then
+ case "$TOOL_ARG" in timeout|gtimeout|perl|none) TOOL="$TOOL_ARG" ;; *) usage "--tool is timeout, gtimeout, perl or none" ;; esac
+elif command -v timeout >/dev/null 2>&1; then TOOL=timeout
+elif command -v gtimeout >/dev/null 2>&1; then TOOL=gtimeout
+elif command -v perl >/dev/null 2>&1; then TOOL=perl
+else TOOL=none; fi
+# The perl fallback does what coreutils timeout does: the command runs in a
+# process group of its own, and at the timeout the whole group gets TERM, then
+# KILL five seconds on, so an editor that a compound command started (cd x &&
+# godot ...) ends with it. It exits 142 (128 + SIGALRM's 14) on a timeout,
+# else with the command's own code.
+PERL_TIMEOUT='
+ my $t = shift @ARGV;
+ my $pid = fork;
+ defined $pid or die "test-run: fork failed: $!\n";
+ if ($pid == 0) { setpgrp(0, 0); exec @ARGV or exit 127; }
+ setpgrp($pid, $pid);
+ my $timed = 0;
+ $SIG{ALRM} = sub { if ($timed++) { kill "KILL", -$pid } else { kill "TERM", -$pid; alarm 5 } };
+ for my $s (qw(INT TERM HUP)) { $SIG{$s} = sub { kill $_[0], -$pid } }
+ alarm $t;
+ my $st = 0;
+ while (1) {
+ my $w = waitpid($pid, 0);
+ if ($w == $pid) { $st = $?; last }
+ last if $w == -1;
+ }
+ alarm 0;
+ if ($timed) {
+ for (1 .. 50) { last unless kill 0, -$pid; select(undef, undef, undef, 0.1) }
+ kill "KILL", -$pid if kill 0, -$pid;
+ exit 142;
+ }
+ exit(($st & 127) ? 128 + ($st & 127) : $st >> 8);
+'
+# run_timed SECONDS COMMAND — COMMAND under the timeout tool, output on stdout and stderr.
+run_timed() {
+ case "$TOOL" in
+ timeout|gtimeout) "$TOOL" "$1" bash -c "$2" ;;
+ perl) perl -e "$PERL_TIMEOUT" "$1" bash -c "$2" ;;
+ *) bash -c "$2" ;;
+ esac
+}
+# is_timeout CODE — whether CODE is the tool's timeout exit: 124 from timeout and
+# gtimeout, 142 (128 + SIGALRM's 14) from the perl alarm.
+is_timeout() {
+ case "$TOOL" in
+ timeout|gtimeout) [ "$1" = 124 ] ;;
+ perl) [ "$1" = 142 ] ;;
+ *) return 1 ;;
+ esac
+}
+
+# --- the commands -------------------------------------------------------------
+ABS=$(pwd -W 2>/dev/null || pwd)
+RESULTS=""; BUILD=""; CMD=""; CMD_SRC="default"; PRE_FAIL=""; PRE_ID=""; PRE_WHY=""
+case "$ENGINE" in
+ godot)
+ CMD="\"${EXE:-godot}\" --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode 2>&1"
+ ;;
+ unity)
+ if [ "$PLATFORM" = playmode ]; then P=PlayMode; RESULTS=test-results/playmode.xml; else P=EditMode; RESULTS=test-results/editmode.xml; fi
+ CMD="\"${EXE:-Unity}\" -batchmode -runTests -projectPath . -testPlatform $P -testResults $RESULTS"
+ ;;
+ unreal)
+ if [ -n "$OS_ARG" ]; then OSN=$OS_ARG
+ else case "$(uname -s)" in Linux) OSN=linux ;; Darwin) OSN=macos ;; *) OSN=windows ;; esac; fi
+ PROJ=""
+ for u in ./*.uproject; do [ -f "$u" ] && { PROJ=${u#./}; PROJ=${PROJ%.uproject}; break; }; done
+ [ -n "$FILTER" ] || FILTER="$PROJ"
+ case "$OSN" in
+ windows)
+ BUILD="\"$EXE/Engine/Binaries/DotNET/UnrealBuildTool/UnrealBuildTool.exe\" ${PROJ}Editor Win64 Development -Project=\"$ABS/$PROJ.uproject\" 2>&1"
+ CMD="\"$EXE/Engine/Binaries/Win64/UnrealEditor-Cmd.exe\" \"$ABS/$PROJ.uproject\" -ExecCmds=\"Automation RunTests $FILTER.; Quit\" -unattended -nullrhi -stdout -FullStdOutLogOutput 2>&1" ;;
+ linux)
+ BUILD="\"$EXE/Engine/Build/BatchFiles/Linux/Build.sh\" ${PROJ}Editor Linux Development -Project=\"$ABS/$PROJ.uproject\" 2>&1"
+ CMD="\"$EXE/Engine/Binaries/Linux/UnrealEditor\" \"$ABS/$PROJ.uproject\" -ExecCmds=\"Automation RunTests $FILTER.; Quit\" -unattended -nullrhi -stdout -FullStdOutLogOutput 2>&1" ;;
+ macos)
+ BUILD="\"$EXE/Engine/Build/BatchFiles/Mac/Build.sh\" ${PROJ}Editor Mac Development -Project=\"$ABS/$PROJ.uproject\" 2>&1"
+ CMD="" ;;
+ esac
+ ;;
+esac
+# commands.test and --cmd win over the default. Unreal keeps the build first.
+if [ -n "$CMD_ARG" ]; then CMD="$CMD_ARG"; CMD_SRC="--cmd"
+elif [ -n "$CFG_TEST" ]; then CMD="$CFG_TEST"; CMD_SRC="commands.test"; fi
+# A Unity results file named in the command is the one to read and to delete first.
+if [ "$ENGINE" = unity ] && [ "$CMD_SRC" != default ]; then
+ # -E: BSD sed has no \| in a basic regex.
+ named=$(printf '%s\n' "$CMD" | sed -n -E 's/.*-testResults[ =]*("[^"]*"|[^ ]*).*/\1/p' | head -1)
+ named=${named#\"}; named=${named%\"}
+ [ -n "$named" ] && RESULTS="$named"
+fi
+# The step before the tests: Godot's import, Unreal's build.
+PRE_NAME=""; PRE_CMD=""; PRE_WHY=""
+case "$ENGINE" in
+ godot)
+ PRE_NAME=import
+ if [ -n "$EXE" ]; then PRE_CMD="\"$EXE\" --headless --path . --import"
+ else PRE_WHY="skipped: no Godot executable (--exe, commands.test, engine.path, PATH)"; fi ;;
+ unreal)
+ PRE_NAME=build
+ if [ "$NOBUILD" = 1 ]; then PRE_WHY="skipped: --no-build"
+ elif [ -z "$EXE" ]; then PRE_WHY="skipped: no UE root (--exe or engine.path)"
+ else PRE_CMD="$BUILD"; fi ;;
+esac
+[ -n "$CMD" ] && printf 'command\t%s\t%s\n' "$CMD_SRC" "$CMD"
+if [ -n "$PRE_CMD" ]; then printf '%s\t%s\n' "$PRE_NAME" "$PRE_CMD"
+elif [ -n "$PRE_NAME" ]; then printf '%s\t-\t%s\n' "$PRE_NAME" "$PRE_WHY"; fi
+printf 'timeout\t%s\t%s\n' "$TIMEOUT" "$TOOL"
+
+# --- prechecks ----------------------------------------------------------------
+ran_no() { printf 'ran\tno\t%s\n' "$2"; printf 'rule\t%s\t%s\n' "$1" "$3"; exit 0; }
+case "$ENGINE" in
+ godot)
+ if [ -f addons/gdUnit4/bin/GdUnitCmdTool.gd ]; then printf 'precheck\taddons/gdUnit4/bin/GdUnitCmdTool.gd\tpresent\n'
+ else
+ printf 'precheck\taddons/gdUnit4/bin/GdUnitCmdTool.gd\tabsent\n'
+ ran_no godot:no-gdunit4 "gdUnit4 is not installed at addons/gdUnit4/" "gdUnit4 not installed, so no runner was started"
+ fi ;;
+ unity)
+ if [ -f Packages/manifest.json ] && grep -q 'com.unity.test-framework' Packages/manifest.json; then printf 'precheck\tcom.unity.test-framework\tpresent\n'
+ else
+ printf 'precheck\tcom.unity.test-framework\tabsent\n'
+ ran_no unity:no-test-framework "Unity Test Framework is not in Packages/manifest.json" "the Unity Test Framework is not installed; the editor would hang, so it was not started"
+ fi ;;
+ unreal)
+ if [ "$OSN" = macos ] && [ -z "$CMD_ARG" ] && [ -z "$CFG_TEST" ]; then
+ printf 'precheck\tmacos test command\tabsent\n'
+ ran_no unreal:mac-unsourced "no sourced Unreal test command on macOS and no commands.test" "no sourced Unreal test command on macOS: set commands.test"
+ fi ;;
+esac
+if [ -z "$EXE" ] && [ "$CMD_SRC" = default ]; then
+ ran_no runner-unavailable "no editor executable (commands.test, engine.path, PATH)" "the engine executable was not found, so the tests could not be run here"
+fi
+if [ "$DRY" = 1 ]; then printf 'ran\tno\tdry run\n'; exit 0; fi
+
+# --- run ----------------------------------------------------------------------
+if [ -z "$LOG" ]; then
+ LOG=$(mktemp "${TMPDIR:-/tmp}/test-run-XXXXXX" 2>/dev/null) || { echo "test-run: cannot create a log file" >&2; exit 1; }
+fi
+: > "$LOG" 2>/dev/null || { echo "test-run: cannot write the log $LOG" >&2; exit 1; }
+[ "$ENGINE" = unity ] && [ -n "$RESULTS" ] && rm -f "$RESULTS"
+PRE_LOG=""; PRE_CODE=""; PRE_TIMED=no
+if [ -n "$PRE_CMD" ]; then
+ PRE_LOG="$LOG.pre"
+ : > "$PRE_LOG" 2>/dev/null || { echo "test-run: cannot write the log $PRE_LOG" >&2; exit 1; }
+ run_timed "$TIMEOUT" "$PRE_CMD" > "$PRE_LOG" 2>&1
+ PRE_CODE=$?
+ is_timeout "$PRE_CODE" && PRE_TIMED=yes
+ printf '%s_exit\t%s\n' "$PRE_NAME" "$PRE_CODE"
+ printf '%s_timed_out\t%s\n' "$PRE_NAME" "$PRE_TIMED"
+fi
+# A build that did not finish cleanly runs no test (/smoke-check: a failed build
+# is a failure): the editor would load the last good binaries, or none.
+if [ "$PRE_NAME" = build ] && [ -n "$PRE_CMD" ] && [ "$PRE_CODE" != 0 ]; then
+ if [ "$PRE_TIMED" = yes ]; then
+ printf 'ran\tno\tthe editor build timed out after %ss\n' "$TIMEOUT"
+ printf 'rule\ttimeout\tthe build did not complete: timed out after %ss, so nothing was verified\n' "$TIMEOUT"
+ else
+ printf 'ran\tno\tthe editor build failed (exit %s)\n' "$PRE_CODE"
+ printf 'rule\tunreal:build-failed\tthe editor build failed, so no test ran\n'
+ fi
+ printf 'pre_log\t%s\n' "$PRE_LOG"
+ exit 0
+fi
+run_timed "$TIMEOUT" "$CMD" > "$LOG" 2>&1
+CODE=$?
+printf 'ran\tyes\t-\n'
+printf 'exit\t%s\n' "$CODE"
+TIMED=no
+is_timeout "$CODE" && TIMED=yes
+printf 'timed_out\t%s\n' "$TIMED"
+
+# --- read ---------------------------------------------------------------------
+# first_line PATTERN — the first output line matching the extended regex, or empty.
+first_line() { grep -E -m 1 "$1" "$LOG" 2>/dev/null | head -1 | tr -d '\r'; }
+# list_failed PATTERN FILE — up to 10 matching lines as `failed` rows, then the
+# overflow (Phase 2: "names of any failing tests (up to 10; if more, note the count)").
+list_failed() {
+ n=$(grep -E -c "$1" "$2" 2>/dev/null); n=${n:-0}
+ grep -E "$1" "$2" 2>/dev/null | head -10 | tr -d '\r' | while IFS= read -r l; do printf 'failed\t%s\n' "$(printf '%s' "$l" | sed 's/^[[:blank:]]*//')"; done
+ [ "$n" -gt 10 ] && printf 'failed_more\t%s\n' "$((n - 10))"
+ return 0
+}
+RULE_ID="-"; RULE_TXT="no row of the ladder fits"
+set_rule() { RULE_ID="$1"; RULE_TXT="$2"; }
+case "$ENGINE" in
+ godot)
+ marker=$(first_line 'No test cases found')
+ if [ -n "$marker" ]; then printf 'zero_tests\tyes\t%s\n' "$marker"; else printf 'zero_tests\tno\t-\n'; fi
+ printf 'tests\t-\tnot sourced: the gdUnit4 summary format is not documented here\n'
+ case "$CODE" in
+ 0) if [ -n "$marker" ]; then set_rule godot:0-zero "exit 0 over zero tests: the runner found no test cases"
+ else set_rule godot:0 "exit 0: every test passed"; fi ;;
+ 101) set_rule godot:101 "every test passed, but a test leaked nodes (orphans)"
+ e=$(first_line '[Oo]rphan'); [ -n "$e" ] && printf 'evidence\t%s\n' "$e" ;;
+ 100) set_rule godot:100 "a test failed" ;;
+ 105) set_rule godot:105 "a test script does not parse" ;;
+ 103) set_rule godot:103 "gdUnit4 refused to run headless (--ignoreHeadlessMode missing)" ;;
+ 104) set_rule godot:104 "Godot is older than 4.3" ;;
+ # The ladder reads exit 1 by whether the import ran first: usually it was
+ # skipped (the runner needs the class cache it builds); after it, exit 1
+ # is Godot's own error.
+ 1) if [ "$PRE_CODE" = 0 ]; then
+ set_rule godot:1 "Godot's own error: GdUnitCmdTool.gd did not load after the import, so no test ran"
+ else
+ if [ -z "$PRE_CMD" ]; then why="skipped: no Godot executable"
+ elif [ "$PRE_TIMED" = yes ]; then why="timed out"
+ else why="exit $PRE_CODE"; fi
+ set_rule godot:1-no-import "GdUnitCmdTool.gd did not load, so no test ran, and the import did not complete first ($why)"
+ fi
+ e=$(first_line 'Failed to load script'); [ -n "$e" ] && printf 'evidence\t%s\n' "$e" ;;
+ 126|127) set_rule runner-unavailable "the editor did not start (command not found or not executable)" ;;
+ esac ;;
+ unity)
+ if [ -f "$RESULTS" ]; then
+ printf 'results_file\t%s\tpresent\n' "$RESULTS"
+ run_el=$(grep -E -m 1 '<test-run' "$RESULTS" | tr -d '\r')
+ attr() { printf '%s\n' "$run_el" | sed -n "s/.*[ <]$1=\"\\([0-9]*\\)\".*/\\1/p" | head -1; }
+ total=$(attr testcasecount); passed=$(attr passed); failed=$(attr failed)
+ printf 'tests\ttotal=%s passed=%s failed=%s\n' "${total:--}" "${passed:--}" "${failed:--}"
+ if [ -z "$total" ]; then printf 'zero_tests\tunknown\tno testcasecount on a <test-run> element\n'
+ elif [ "$total" = 0 ]; then printf 'zero_tests\tyes\ttestcasecount="0"\n'; else printf 'zero_tests\tno\t-\n'; fi
+ list_failed '<test-case[^>]*result="Failed"' "$RESULTS"
+ else
+ printf 'results_file\t%s\tabsent\n' "$RESULTS"; total=""
+ fi
+ case "$CODE" in
+ 0) if [ ! -f "$RESULTS" ]; then set_rule unity:no-results "exit 0 but no results file was written"
+ elif [ -z "$total" ]; then set_rule unity:no-count "exit 0, but the results file has no <test-run> testcasecount, so no test was counted"
+ elif [ "$total" = 0 ]; then set_rule unity:zero-tests "testcasecount is 0: no test was compiled or run"
+ else set_rule unity:0 "exit 0: every test passed"; fi ;;
+ 2) set_rule unity:2 "a test failed" ;;
+ 1) set_rule unity:1 "the project did not compile (see the editor log for error CS lines)" ;;
+ 3) set_rule unity:3 "the run itself failed" ;;
+ 4) set_rule unity:4 "an unknown -testPlatform" ;;
+ 126|127) set_rule runner-unavailable "the editor did not start (command not found or not executable)" ;;
+ *) set_rule unity:other "any other non-zero exit" ;;
+ esac ;;
+ unreal)
+ nok=$(grep -E -c 'Result=\{Success\}' "$LOG"); nfail=$(grep -E -c 'Result=\{Fail\}' "$LOG")
+ nok=${nok:-0}; nfail=${nfail:-0}
+ printf 'tests\ttotal=%s passed=%s failed=%s\n' "$((nok + nfail))" "$nok" "$nfail"
+ marker=$(first_line 'No automation tests matched')
+ if [ -n "$marker" ]; then printf 'zero_tests\tyes\t%s\n' "$marker"; else printf 'zero_tests\tno\t-\n'; fi
+ list_failed 'Result=\{Fail\}' "$LOG"
+ if [ "$nfail" -gt 0 ]; then set_rule unreal:result-fail "Result={Fail} on a line of the output"
+ elif [ -n "$marker" ]; then set_rule unreal:no-tests-matched "No automation tests matched (a failing test and a run that matched nothing both exit 255)"
+ elif [ "$CODE" = 126 ] || [ "$CODE" = 127 ]; then set_rule runner-unavailable "the editor did not start (command not found or not executable)"
+ elif [ "$CODE" = 0 ] && [ "$nok" -gt 0 ]; then set_rule unreal:pass "exit 0 with Result={Success} lines"
+ elif [ "$CODE" != 0 ]; then set_rule unreal:other-nonzero "a non-zero exit with no Result={Fail} line and no 'no tests matched': no test ran"
+ fi ;;
+esac
+if [ "$TIMED" = yes ]; then set_rule timeout "the run did not complete: timed out after ${TIMEOUT}s, so nothing was verified"; fi
+printf 'rule\t%s\t%s\n' "$RULE_ID" "$RULE_TXT"
+[ -n "$PRE_LOG" ] && printf 'pre_log\t%s\n' "$PRE_LOG"
+printf 'log\t%s\n' "$LOG"
+exit 0
diff --git a/.claude/scripts/test-scaffold.sh b/.claude/scripts/test-scaffold.sh
new file mode 100644
index 00000000..56c9eba1
--- /dev/null
+++ b/.claude/scripts/test-scaffold.sh
@@ -0,0 +1,746 @@
+#!/usr/bin/env bash
+# test-scaffold.sh — creates the files /test-setup scaffolds for one engine,
+# never overwriting one that exists, and prints per path whether it was
+# created, already there or skipped, then the inputs it still needs.
+#
+# Replaces the file-by-file creation of a test setup: the README, the evidence
+# folder's .gitkeep, the engine's test folders or assembly definitions, the CI
+# workflow and the smoke-test seed.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# It reports what it did with each path and what is still missing; whether
+# the project may advance a gate on the strength of it is the skill's call.
+#
+# Usage: bash .claude/scripts/test-scaffold.sh ENGINE [--dry-run | --list] [--root DIR]
+# [--module NAME] [--project NAME] [--date YYYY-MM-DD]
+# ENGINE godot, unity or unreal (the engine.name values, in any case;
+# UE5 is not one)
+# --dry-run print what would be created (WOULD_CREATE), write nothing
+# --list print the project-relative paths this engine's scaffold
+# creates, one per line and nothing else, whatever already
+# exists (the write guard reads it for its never-overwrite rule)
+# --root DIR the project; defaults to the repo this script is in
+# --module NAME unreal: the game module (Source/NAME/Private/Tests/); default
+# the name of the one .uproject file in the root
+# --project NAME unreal: the project name, which is also the test root unless
+# /setup-engine chose another; default the .uproject name, else
+# the module name
+# --date D the setup date for the README (default: today)
+# -h, --help this text
+#
+# Files per engine, in this order (the skill's Phases 3 to 5):
+# all tests/README.md, production/qa/evidence/.gitkeep
+# godot tests/unit/.gitkeep, tests/integration/.gitkeep
+# unity Assets/Tests/EditMode/EditModeTests.asmdef,
+# Assets/Tests/PlayMode/PlayModeTests.asmdef
+# unreal Source/<Module>/Private/Tests/README.md
+# all .github/workflows/tests.yml, tests/smoke/critical-paths.md
+# The skill asks Godot's two test folders to hold a .gdignore_placeholder file;
+# Godot knows no such name (.gdignore would hide the folder from the editor and
+# from the test runner), so they hold an empty .gitkeep, which keeps the empty
+# folder in git. Unity and Unreal tests live in the engine's test root because
+# neither compiles code under tests/.
+# The README carries the setup date and the engine version (engine.version of
+# project.local.yaml, then project.yaml). The CI workflow carries the full
+# Godot version where engine.version has three numbers; a value that is not
+# known stays as the skill writes it in square brackets and is listed as an
+# input still needed. Local and CI commands are the skill's, and they differ
+# on Godot (CI runs tests/unit and tests/integration, the local command runs
+# everything under tests/); the README says so.
+#
+# Output: TSV.
+# engine <name>, mode write|dry-run, then per path
+# CREATED <path> | WOULD_CREATE <path> | EXISTS <path> | SKIPPED <path> <reason>
+# | FAILED <path> <reason>, then created (or would_create) <n>, exists <n>,
+# skipped <n> (and failed <n> when above 0), then
+# NEEDS <id> <file> <what> for each input still needed.
+# EXISTS means the path was there (a file, a folder or a link) and was not
+# touched. A file is written with the shell's noclobber on, so one that
+# appears between the check and the write is left alone too.
+#
+# Exit codes: 0 every path created or already there; 1 the root cannot be read;
+# 2 usage error; 3 a path was skipped (its reason is in the row); 4 a file or
+# folder could not be created (FAILED). Never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for sed and the YAML reader.
+LC_ALL=C
+export LC_ALL
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+usage() { echo "test-scaffold: $1 (try --help)" >&2; exit 2; }
+TAB=$(printf '\t')
+
+ENGINE=""; MODE=write; ROOT_ARG=""; MODULE_ARG=""; PROJECT_ARG=""; DATE_ARG=""
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --dry-run) [ "$MODE" != list ] || usage "--list and --dry-run cannot be combined"; MODE=dry-run; shift ;;
+ --list) [ "$MODE" != dry-run ] || usage "--list and --dry-run cannot be combined"; MODE=list; shift ;;
+ --root) [ $# -ge 2 ] || usage "--root needs a value"; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --module) [ $# -ge 2 ] || usage "--module needs a name"; MODULE_ARG="$2"; shift 2 ;;
+ --module=*) MODULE_ARG="${1#--module=}"; shift ;;
+ --project) [ $# -ge 2 ] || usage "--project needs a name"; PROJECT_ARG="$2"; shift 2 ;;
+ --project=*) PROJECT_ARG="${1#--project=}"; shift ;;
+ --date) [ $# -ge 2 ] || usage "--date needs a value"; DATE_ARG="$2"; shift 2 ;;
+ --date=*) DATE_ARG="${1#--date=}"; shift ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -?*) usage "unknown argument: $1" ;;
+ *) [ -z "$ENGINE" ] || usage "one engine at a time, got $ENGINE and $1"; ENGINE="$1"; shift ;;
+ esac
+done
+[ -n "$ENGINE" ] || usage "no engine: godot, unity or unreal"
+ENG=$(printf '%s' "$ENGINE" | tr '[:upper:]' '[:lower:]')
+case "$ENG" in
+ godot|unity|unreal) ;;
+ *) usage "engine must be godot, unity or unreal (the engine.name values), got $ENGINE" ;;
+esac
+# A module or project name goes into paths and file text: letters, digits and _ only.
+for _n in "$MODULE_ARG" "$PROJECT_ARG"; do
+ case "$_n" in *[!A-Za-z0-9_]*) usage "a module or project name takes letters, digits and _, got $_n" ;; esac
+done
+if [ -n "$DATE_ARG" ]; then
+ case "$DATE_ARG" in
+ [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) ;;
+ *) usage "--date takes YYYY-MM-DD, got $DATE_ARG" ;;
+ esac
+fi
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "test-scaffold: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "test-scaffold: cannot reach the repo root" >&2; exit 1; }
+fi
+
+# ------------------------------------------------------------ names and version
+# Unreal names: the flags, else the one .uproject in the root (the skill: for a
+# C++ project the module is the .uproject name).
+UPROJ=""
+if [ "$ENG" = unreal ]; then
+ _u=$(find . -maxdepth 1 -type f -name '*.uproject' 2>/dev/null | sed 's|^\./||' | sort)
+ if [ -n "$_u" ] && [ "$(printf '%s\n' "$_u" | wc -l | tr -d ' ')" = 1 ]; then
+ UPROJ="${_u%.uproject}"
+ case "$UPROJ" in *[!A-Za-z0-9_]*) UPROJ="" ;; esac
+ fi
+fi
+PROJ_NAME="${PROJECT_ARG:-${UPROJ:-$MODULE_ARG}}"
+MOD_NAME="${MODULE_ARG:-${UPROJ:-$PROJECT_ARG}}"
+
+# The engine version, as project-state.sh reads project.yaml: the shared reader.
+VER=""
+if [ -f "$HERE/yaml-get.awk" ]; then
+ for _yf in project.local.yaml project.yaml; do
+ if [ -z "$VER" ] && [ -f "$_yf" ]; then
+ VER=$(YG_PATH=engine.version awk -f "$HERE/yaml-get.awk" "$_yf")
+ fi
+ done
+fi
+# A version goes into file text: keep it to the characters a version has.
+case "$VER" in ''|-|*[!A-Za-z0-9._+-]*) VER="" ;; esac
+
+case "$ENG" in
+ godot) ENGNAME=Godot ;;
+ unity) ENGNAME=Unity ;;
+ unreal) ENGNAME=Unreal ;;
+esac
+if [ -n "$VER" ]; then ENGTXT="$ENGNAME $VER"; else ENGTXT="$ENGNAME [version]"; fi
+# Godot CI needs a full release such as 4.7.2; "4.7" is not one.
+GODOTVER="[FULL GODOT VERSION, e.g. 4.7.2]"
+case "$VER" in
+ [0-9]*.[0-9]*.[0-9]*) [ "$ENG" != godot ] || GODOTVER="$VER" ;;
+esac
+DATE="${DATE_ARG:-$(date +%Y-%m-%d)}"
+MODTXT="${MOD_NAME:-<Module>}"
+DOCPROJ="${PROJ_NAME:-<Project>}"
+CIPROJ="${PROJ_NAME:-[ProjectName]}"
+
+# ---------------------------------------------------------------------- paths
+README=tests/README.md
+EVID=production/qa/evidence/.gitkeep
+CI=.github/workflows/tests.yml
+SMOKE=tests/smoke/critical-paths.md
+UNREAL_README="Source/$MODTXT/Private/Tests/README.md"
+list_paths() {
+ echo "$README"
+ echo "$EVID"
+ case "$ENG" in
+ godot) echo tests/unit/.gitkeep; echo tests/integration/.gitkeep ;;
+ unity) echo Assets/Tests/EditMode/EditModeTests.asmdef; echo Assets/Tests/PlayMode/PlayModeTests.asmdef ;;
+ unreal) echo "$UNREAL_README" ;;
+ esac
+ echo "$CI"
+ echo "$SMOKE"
+}
+if [ "$MODE" = list ]; then
+ list_paths
+ exit 0
+fi
+
+# ------------------------------------------------------------------- contents
+# Each file is a function printing it; @TOKENS@ are filled by render.
+tpl_readme_godot() {
+ cat <<'TPL_README_GODOT'
+# Test Infrastructure
+
+**Engine**: @ENGINE@
+**Test Framework**: GdUnit4
+**CI**: `.github/workflows/tests.yml`
+**Setup date**: @DATE@
+
+## Directory Layout
+
+```
+tests/
+ unit/ # Isolated unit tests (formulas, state machines, logic)
+ integration/ # Cross-system and save/load tests
+ smoke/ # Critical path test list for /smoke-check gate
+```
+
+```
+production/qa/
+ evidence/ # Screenshot logs and manual test sign-off records
+```
+
+> **Manual evidence lives under `production/qa/evidence/`, not `tests/`** — that
+> is where every consumer reads it.
+
+## Running Tests
+
+```bash
+godot --headless --path . --import
+godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode
+```
+
+Run the import first: a fresh clone has no `.godot/` class cache, and a run
+without one exits 1 (`GdUnitCmdTool.gd` did not load, so no test ran). Exit 0:
+every test passed. Exit 100: a test failed. Exit 101: every test passed but a
+test leaked nodes (a warning). Exit 103 or 104: gdUnit4 could not run. Exit 105:
+a test script does not parse. A run that finds no tests prints `No test cases
+found` and exits 0, which is not a pass. The folder is `addons/gdUnit4/` with a
+capital U.
+
+CI runs `tests/unit` and `tests/integration`; the command above runs every suite
+under `tests/`.
+
+## Installing GdUnit4
+
+```
+1. Open Godot → Asset Store (AssetLib before Godot 4.7) → search "GdUnit4" → install it
+2. Enable the plugin: Project → Project Settings → Plugins → GdUnit4 ✓
+3. Restart the editor
+4. Verify: res://addons/gdUnit4/bin/GdUnitCmdTool.gd exists (capital U)
+```
+
+## Test Naming
+
+Names follow the engine's language (`.claude/rules/test-standards.md`):
+- **Godot**: file `[system]_[feature]_test.gd`, function `test_[scenario]_[expected]`
+ — `combat_damage_test.gd` → `test_base_attack_returns_expected_damage()`
+
+## Story Type → Test Evidence
+
+| Story Type | Required Evidence | Location |
+|---|---|---|
+| Logic | Automated unit test — must pass | `tests/unit/[system]/` |
+| Integration | Integration test OR playtest doc | `tests/integration/[system]/` |
+| Visual/Feel | Screenshot + lead sign-off | `production/qa/evidence/` |
+| UI | Retained screenshot of each screen touched | `production/qa/evidence/` |
+| Config/Data | Smoke check pass | `production/qa/smoke-*.md` |
+
+## CI
+
+Tests run automatically on every push to `main` and on every pull request.
+A failed test suite blocks merging.
+TPL_README_GODOT
+}
+
+tpl_readme_unity() {
+ cat <<'TPL_README_UNITY'
+# Test Infrastructure
+
+**Engine**: @ENGINE@
+**Test Framework**: Unity Test Framework
+**CI**: `.github/workflows/tests.yml`
+**Setup date**: @DATE@
+
+## Directory Layout
+
+Unity compiles only `Assets/` and `Packages/`, so unit and integration tests
+live under the engine's test root, not in `tests/`: a test under `tests/` is never
+compiled, and the run reports 0 tests and `Passed`, a false pass.
+
+```
+Assets/Tests/
+ EditMode/ # Isolated unit tests (formulas, state machines, logic)
+ PlayMode/ # Integration tests in a running scene
+```
+
+`tests/` keeps this README and `smoke/`. Every `tests/unit/` path below means
+that test root.
+
+```
+tests/
+ smoke/ # Critical path test list for /smoke-check gate
+```
+
+```
+production/qa/
+ evidence/ # Screenshot logs and manual test sign-off records
+```
+
+> **Manual evidence lives under `production/qa/evidence/`, not `tests/`** — that
+> is where every consumer reads it.
+
+## Running Tests
+
+Use the editor executable: `Unity` on `PATH` may be Unity's separate CLI, not
+the editor.
+
+```
+"<Unity editor>" -batchmode -runTests -projectPath . -testPlatform EditMode -testResults test-results/editmode.xml
+"<Unity editor>" -batchmode -runTests -projectPath . -testPlatform PlayMode -testResults test-results/playmode.xml
+```
+
+Exit 0: every test passed. Exit 2: a test failed. Exit 1, 3 and 4 (a compile
+error, a failed run, an unknown `-testPlatform`) and any other non-zero exit
+are failures too; a compile error writes no results file. Delete each results
+file before its run so an old file is never read as a new result. Read the
+`<test-run>` element of the results file: `testcasecount="0"` means nothing was
+compiled or found, which is not a pass. Do not add `-quit`; `-runTests` exits by
+itself. An Edit Mode run never runs the tests in `Assets/Tests/PlayMode/`, so
+run both.
+
+## Test Naming
+
+Names follow the engine's language (`.claude/rules/test-standards.md`):
+- **Unity**: class `[System]Tests` in `[System]Tests.cs`, method `[Scenario]_[Expected]`
+ — `CombatTests.cs` → `BaseAttack_ReturnsExpectedDamage()`
+
+## Story Type → Test Evidence
+
+| Story Type | Required Evidence | Location |
+|---|---|---|
+| Logic | Automated unit test — must pass | `tests/unit/[system]/` |
+| Integration | Integration test OR playtest doc | `tests/integration/[system]/` |
+| Visual/Feel | Screenshot + lead sign-off | `production/qa/evidence/` |
+| UI | Retained screenshot of each screen touched | `production/qa/evidence/` |
+| Config/Data | Smoke check pass | `production/qa/smoke-*.md` |
+
+## CI
+
+Tests run automatically on every push to `main` and on every pull request.
+A failed test suite blocks merging. Unity CI needs the `UNITY_LICENSE`
+repository secret.
+TPL_README_UNITY
+}
+
+tpl_readme_unreal() {
+ cat <<'TPL_README_UNREAL'
+# Test Infrastructure
+
+**Engine**: @ENGINE@
+**Test Framework**: UE Automation
+**CI**: `.github/workflows/tests.yml`
+**Setup date**: @DATE@
+
+## Directory Layout
+
+UnrealBuildTool compiles only module folders, so unit and integration tests
+live inside the game module, not in `tests/`: a test directly under `Source/`
+is silently never built.
+
+```
+Source/@MODULE@/Private/Tests/ # Unit and integration tests, compiled with the module
+```
+
+`tests/` keeps this README and `smoke/`. Every `tests/unit/` path below means
+that test root.
+
+```
+tests/
+ smoke/ # Critical path test list for /smoke-check gate
+```
+
+```
+production/qa/
+ evidence/ # Screenshot logs and manual test sign-off records
+```
+
+> **Manual evidence lives under `production/qa/evidence/`, not `tests/`** — that
+> is where every consumer reads it.
+
+## Running Tests
+
+The commands are in `Source/@MODULE@/Private/Tests/README.md`. Read the output,
+not the exit code: a failing test and a run that matched nothing both exit 255.
+`Result={Fail}` is a failure; `No automation tests matched` means no test was
+built or named `@DOCPROJECT@.…`.
+
+## Test Naming
+
+Names follow the engine's language (`.claude/rules/test-standards.md`):
+- **Unreal**: class `F[System][Scenario]Test`, test name `@DOCPROJECT@.[System].[Scenario]`
+ — `FCombatBaseAttackTest` → `@[email protected]`
+
+## Story Type → Test Evidence
+
+| Story Type | Required Evidence | Location |
+|---|---|---|
+| Logic | Automated unit test — must pass | `tests/unit/[system]/` |
+| Integration | Integration test OR playtest doc | `tests/integration/[system]/` |
+| Visual/Feel | Screenshot + lead sign-off | `production/qa/evidence/` |
+| UI | Retained screenshot of each screen touched | `production/qa/evidence/` |
+| Config/Data | Smoke check pass | `production/qa/smoke-*.md` |
+
+## CI
+
+Tests run automatically on every push to `main` and on every pull request.
+A failed test suite blocks merging. Unreal CI needs a self-hosted Windows
+runner with Unreal Editor installed and `UE_ROOT` set.
+TPL_README_UNREAL
+}
+
+tpl_ci_godot() {
+ cat <<'TPL_CI_GODOT'
+name: Automated Tests
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ branches: [main]
+
+jobs:
+ test:
+ name: Run GdUnit4 Tests
+ runs-on: ubuntu-latest
+ # The action publishes its results as a check run. A new repository's
+ # token is read-only, and without checks: write the job fails even when
+ # every test passes. If you protect main, require the `Run GdUnit4 Tests` job
+ # check, not `test-results`: that check run concludes success even when a
+ # test fails.
+ permissions:
+ contents: read
+ checks: write
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v7
+ with:
+ lfs: true
+
+ # godot-version must be a full release such as 4.7.2 (`godot --version`
+ # shows it); VERSION.md's "4.7" is not one. version: installed runs the
+ # gdUnit4 committed in addons/ -- without it the action deletes that
+ # copy and installs the latest release, which may not match your tests.
+ - name: Run GdUnit4 Tests
+ uses: godot-gdunit-labs/gdUnit4-action@v1
+ with:
+ godot-version: '@GODOTVER@'
+ version: 'installed'
+ paths: |
+ tests/unit
+ tests/integration
+ report-name: test-results
+
+ - name: Upload Test Results
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: test-results
+ path: reports/
+TPL_CI_GODOT
+}
+
+tpl_ci_unity() {
+ cat <<'TPL_CI_UNITY'
+name: Automated Tests
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ branches: [main]
+
+jobs:
+ test:
+ name: Run Unity Tests
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v7
+ with:
+ lfs: true
+
+ - name: Run Edit Mode Tests
+ uses: game-ci/unity-test-runner@v4
+ env:
+ UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
+ with:
+ testMode: editmode
+ artifactsPath: test-results/editmode
+
+ - name: Run Play Mode Tests
+ uses: game-ci/unity-test-runner@v4
+ env:
+ UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
+ with:
+ testMode: playmode
+ artifactsPath: test-results/playmode
+
+ - name: Upload Test Results
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: test-results
+ path: test-results/
+TPL_CI_UNITY
+}
+
+tpl_ci_unreal() {
+ cat <<'TPL_CI_UNREAL'
+name: Automated Tests
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ branches: [main]
+
+jobs:
+ test:
+ name: Run UE Automation Tests
+ runs-on: [self-hosted, windows] # UE requires a local runner with the editor installed
+
+ # The quoted "{0}" in each `shell:` below: the Windows runner passes bash
+ # its script path unquoted, so with plain `shell: bash` every step fails
+ # ("No such file or directory") when the runner's folder has a space.
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v7
+ with:
+ lfs: true
+
+ # Binaries/ is gitignored, so a fresh checkout has no compiled game
+ # module: without this step the editor stops with "The game module could
+ # not be found" before running any test. UnrealBuildTool.exe, not
+ # Build.bat -- from bash, Build.bat fails on an engine path with spaces.
+ - name: Build Editor Target
+ run: |
+ "$UE_ROOT/Engine/Binaries/DotNET/UnrealBuildTool/UnrealBuildTool.exe" @CIPROJECT@Editor Win64 Development \
+ -Project="${{ github.workspace }}/@[email protected]"
+ shell: bash --noprofile --norc -eo pipefail "{0}"
+
+ # -stdout -FullStdOutLogOutput: without them the editor prints nothing
+ # here, and the results are only in Saved/Logs/.
+ - name: Run Automation Tests
+ run: |
+ "$UE_ROOT/Engine/Binaries/Win64/UnrealEditor-Cmd.exe" "${{ github.workspace }}/@[email protected]" \
+ -nullrhi -nosound \
+ -ExecCmds="Automation RunTests @CIPROJECT@.; Quit" \
+ -unattended -stdout -FullStdOutLogOutput
+ shell: bash --noprofile --norc -eo pipefail "{0}"
+
+ - name: Upload Logs
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: test-logs
+ path: Saved/Logs/
+TPL_CI_UNREAL
+}
+
+tpl_smoke() {
+ cat <<'TPL_SMOKE'
+# Smoke Test: Critical Paths
+
+**Purpose**: Run these 10-15 checks in under 15 minutes before any QA hand-off.
+**Run via**: `/smoke-check` (which reads this file)
+**Update**: Add new entries when new core systems are implemented.
+
+## Core Stability (always run)
+
+1. Game launches to main menu without crash
+2. New game / session can be started from the main menu
+3. Main menu responds to all inputs without freezing
+
+## Core Mechanic (update per sprint)
+
+<!-- Add the primary mechanic for each sprint here as it is implemented -->
+<!-- Example: "Player can move, jump, and the camera follows correctly" -->
+4. [Primary mechanic — update when first core system is implemented]
+
+## Data Integrity
+
+5. Save game completes without error (once save system is implemented)
+6. Load game restores correct state (once load system is implemented)
+
+## Performance
+
+7. No visible frame rate drops on target hardware (60fps target)
+8. No memory growth over 5 minutes of play (once core loop is implemented)
+TPL_SMOKE
+}
+
+tpl_asmdef_edit() {
+ cat <<'TPL_ASMDEF_EDIT'
+{
+ "name": "EditModeTests",
+ "references": ["UnityEngine.TestRunner", "UnityEditor.TestRunner"],
+ "includePlatforms": ["Editor"],
+ "overrideReferences": true,
+ "precompiledReferences": ["nunit.framework.dll"],
+ "autoReferenced": false,
+ "defineConstraints": ["UNITY_INCLUDE_TESTS"]
+}
+TPL_ASMDEF_EDIT
+}
+
+tpl_asmdef_play() {
+ cat <<'TPL_ASMDEF_PLAY'
+{
+ "name": "PlayModeTests",
+ "references": ["UnityEngine.TestRunner", "UnityEditor.TestRunner"],
+ "includePlatforms": [],
+ "overrideReferences": true,
+ "precompiledReferences": ["nunit.framework.dll"],
+ "autoReferenced": false,
+ "defineConstraints": ["UNITY_INCLUDE_TESTS"]
+}
+TPL_ASMDEF_PLAY
+}
+
+tpl_unreal_tests_readme() {
+ cat <<'TPL_UNREAL_TESTS'
+# Unreal Automation Tests
+Tests use the UE Automation Testing Framework and compile with this module.
+Wrap each test file in `#if WITH_DEV_AUTOMATION_TESTS` … `#endif`.
+Flags: `EAutomationTestFlags::EditorContext | EAutomationTestFlags::ProductFilter`
+(there is no `GameFilter` flag).
+
+Run via: Session Frontend → Automation → select "@DOCPROJECT@." tests
+Or headlessly from the project root, after building the editor target — on a
+fresh checkout the editor exits before any test runs:
+"<UE root>/Engine/Binaries/DotNET/UnrealBuildTool/UnrealBuildTool.exe" @DOCPROJECT@Editor Win64 Development -Project="$(pwd -W 2>/dev/null || pwd)/@[email protected]"
+"<UE root>/Engine/Binaries/Win64/UnrealEditor-Cmd.exe" "$(pwd -W 2>/dev/null || pwd)/@[email protected]" -ExecCmds="Automation RunTests @DOCPROJECT@.; Quit" -unattended -nullrhi -stdout -FullStdOutLogOutput
+The project path must be absolute: UE does not find a relative one (exit 1,
+"Project file not found"). Those two lines are Windows'. On Linux build with
+`Engine/Build/BatchFiles/Linux/Build.sh @DOCPROJECT@Editor Linux Development -Project="$(pwd -W 2>/dev/null || pwd)/@[email protected]"` and run
+the tests with `Engine/Binaries/Linux/UnrealEditor` and the same arguments; on
+macOS build with `Engine/Build/BatchFiles/Mac/Build.sh @DOCPROJECT@Editor Mac Development -Project="$(pwd -W 2>/dev/null || pwd)/@[email protected]"`
+— Epic documents no command-line editor inside `UnrealEditor.app` for the test
+run (see `docs/engine-reference/unreal/current-best-practices.md`, "Command Line").
+
+Read the output, not the exit code: a failing test and a run that matched nothing both exit 255.
+`Result={Fail}` is a failure; `No automation tests matched` means no test was
+built or named `@DOCPROJECT@.…`.
+
+Test class naming: F[System][Scenario]Test — one class per test; a second
+test reusing a class name fails to link
+Test name: "@DOCPROJECT@.[System].[Scenario]"
+TPL_UNREAL_TESTS
+}
+
+
+render() {
+ sed -e "s|@ENGINE@|$ENGTXT|g" -e "s|@DATE@|$DATE|g" -e "s|@GODOTVER@|$GODOTVER|g" \
+ -e "s|@MODULE@|$MODTXT|g" -e "s|@DOCPROJECT@|$DOCPROJ|g" -e "s|@CIPROJECT@|$CIPROJ|g"
+}
+# content_of <path> -- the file's text, ready to write.
+content_of() {
+ case "$1" in
+ "$README")
+ case "$ENG" in godot) tpl_readme_godot ;; unity) tpl_readme_unity ;; unreal) tpl_readme_unreal ;; esac | render ;;
+ "$CI")
+ case "$ENG" in godot) tpl_ci_godot ;; unity) tpl_ci_unity ;; unreal) tpl_ci_unreal ;; esac | render ;;
+ "$SMOKE") tpl_smoke ;;
+ Assets/Tests/EditMode/EditModeTests.asmdef) tpl_asmdef_edit ;;
+ Assets/Tests/PlayMode/PlayModeTests.asmdef) tpl_asmdef_play ;;
+ Source/*/Private/Tests/README.md) tpl_unreal_tests_readme | render ;;
+ *) : ;;
+ esac
+}
+# write_new <path> -- stdin becomes the file; fails (and writes nothing) if it exists.
+write_new() {
+ mkdir -p "$(dirname "$1")" 2>/dev/null || return 1
+ ( set -C; cat > "$1" ) 2>/dev/null
+}
+
+# ----------------------------------------------------------------------- run
+printf 'engine\t%s\n' "$ENG"
+printf 'mode\t%s\n' "$MODE"
+NCREATE=0; NEXIST=0; NSKIP=0; NFAIL=0
+CREATED_LIST=""
+while IFS= read -r p; do
+ if [ -e "$p" ] || [ -L "$p" ]; then
+ printf 'EXISTS\t%s\n' "$p"; NEXIST=$((NEXIST + 1)); continue
+ fi
+ case "$p" in
+ Source/*/Private/Tests/README.md)
+ if [ -z "$MOD_NAME" ]; then
+ printf 'SKIPPED\t%s\tno module name: pass --module or keep one .uproject in the root\n' "$p"
+ NSKIP=$((NSKIP + 1)); continue
+ fi ;;
+ esac
+ if [ "$MODE" = dry-run ]; then
+ printf 'WOULD_CREATE\t%s\n' "$p"; NCREATE=$((NCREATE + 1)); CREATED_LIST="$CREATED_LIST|$p|"; continue
+ fi
+ if content_of "$p" | write_new "$p"; then
+ printf 'CREATED\t%s\n' "$p"; NCREATE=$((NCREATE + 1)); CREATED_LIST="$CREATED_LIST|$p|"
+ else
+ printf 'FAILED\t%s\tcould not create the folder or the file\n' "$p"; NFAIL=$((NFAIL + 1))
+ fi
+done <<EOF
+$(list_paths)
+EOF
+if [ "$MODE" = dry-run ]; then printf 'would_create\t%d\n' "$NCREATE"; else printf 'created\t%d\n' "$NCREATE"; fi
+printf 'exists\t%d\nskipped\t%d\n' "$NEXIST" "$NSKIP"
+[ "$NFAIL" -eq 0 ] || printf 'failed\t%d\n' "$NFAIL"
+
+# --------------------------------------------------------------------- needs
+# A need belongs to a file this run creates (its placeholders are in it), or
+# is a check of the project that no file of ours can satisfy.
+made() { case "$CREATED_LIST" in *"|$1|"*) return 0 ;; esac; return 1; }
+need() { printf 'NEEDS\t%s\t%s\t%s\n' "$1" "$2" "$3"; }
+if made "$README" && [ -z "$VER" ]; then
+ need engine_version "$README" "set the engine version on the Engine line (project.yaml has no engine.version)"
+fi
+case "$ENG" in
+ godot)
+ if made "$CI" && [ "$GODOTVER" != "$VER" ]; then
+ need godot_version "$CI" "replace [FULL GODOT VERSION, e.g. 4.7.2] with the full release (godot --version)"
+ fi
+ if [ ! -f addons/gdUnit4/bin/GdUnitCmdTool.gd ]; then
+ need gdunit4 addons/gdUnit4/bin/GdUnitCmdTool.gd "install GdUnit4 (Asset Store, AssetLib before Godot 4.7, then enable the plugin); the folder has a capital U"
+ fi ;;
+ unity)
+ if [ ! -f Packages/manifest.json ] || ! grep -q 'com.unity.test-framework' Packages/manifest.json; then
+ need unity_test_framework Packages/manifest.json 'add "com.unity.test-framework" to dependencies at the version your editor bundles'
+ fi
+ if made "$CI"; then
+ need unity_license "$CI" "add the UNITY_LICENSE secret to the repository (manual)"
+ fi
+ if made Assets/Tests/EditMode/EditModeTests.asmdef || made Assets/Tests/PlayMode/PlayModeTests.asmdef; then
+ # The test assemblies see only other .asmdef files; any outside Assets/Tests is the game's.
+ if [ -z "$(find Assets -name '*.asmdef' -not -path 'Assets/Tests/*' 2>/dev/null | head -1)" ]; then
+ need game_asmdef Assets/Tests "the test assemblies see only other .asmdef files: with none for the game scripts, ask before adding one and list it in both test assemblies' references"
+ fi
+ fi ;;
+ unreal)
+ if made "$UNREAL_README"; then
+ need test_root "$UNREAL_README" "$DOCPROJ. is the test root of commands.test: confirm it is the project name, or the distinct root /setup-engine chose"
+ fi
+ if made "$CI" && [ -z "$PROJ_NAME" ]; then
+ need project_name "$CI" "replace [ProjectName] with the project name (the .uproject name)"
+ fi
+ if made "$CI"; then
+ need ue_root "$CI" "set UE_ROOT on the self-hosted Windows runner"
+ fi ;;
+esac
+
+[ "$NFAIL" -eq 0 ] || exit 4
+[ "$NSKIP" -eq 0 ] || exit 3
+exit 0
diff --git a/.claude/scripts/write-guard.sh b/.claude/scripts/write-guard.sh
new file mode 100644
index 00000000..156dea6f
--- /dev/null
+++ b/.claude/scripts/write-guard.sh
@@ -0,0 +1,455 @@
+#!/usr/bin/env bash
+# write-guard.sh — the rules that must hold on every write, read as
+# observations: the files skills never overwrite, the config guard, the
+# prototype boundary, the localization freeze, the subagent write exception
+# (and the artifact a return contract names), and the git and release actions
+# that ask first. A skill states these rules in prose today; this script is
+# the one place they are checked.
+#
+# The helper twin of three warn-only hooks: validate-write.sh (Write and Edit),
+# validate-agent-artifact.sh (SubagentStop) and validate-push.sh (git and
+# release actions). The hooks only call it. A skill that writes a guarded file
+# runs it itself as its last step, because hooks do not run in every tool.
+#
+# EMITS OBSERVATIONS, NOT A VERDICT (CLAUDE.md, "Helpers in .claude/scripts/").
+# Whether a row stops the work is the calling skill's call, or the user's.
+#
+# Usage: bash .claude/scripts/write-guard.sh [--root DIR] COMMAND [ARGS]
+# check PATH [NEW] [--tool Write|Edit] [--agent TYPE] [--existed yes|no]
+# every rule below that applies to PATH. NEW is a file
+# holding the content about to be written; without it the
+# content of PATH itself is read (the check after writing)
+# overwrite PATH [--tool Write|Edit]
+# PATH is a file skills never overwrite and it exists; an
+# Edit changes a file in place, so only a Write (the
+# default) is reported
+# config PATH [NEW]
+# project.yaml or project.local.yaml: values outside a
+# setting's allowed list, keys project.local.yaml cannot
+# override, and modes.review_mode set; production/
+# review-mode.txt: written at all. With NEW, a value the
+# current file already holds is not reported again
+# prototype PATH [NEW]
+# a file under prototypes/ without its PROTOTYPE or
+# VERTICAL SLICE header, or reaching into the code root;
+# a file under the code root reaching into prototypes/
+# freeze PATH a string table under assets/data/strings/ while
+# production/localization/freeze-status.md says ACTIVE
+# agent PATH --agent TYPE [--existed yes|no]
+# a subagent's write outside the exception: only a new file
+# under production/, docs/ or tests/
+# artifact PATH... each path a return contract named: there or missing
+# git stdin: one shell command segment per line; each whose
+# command (after VAR=value words and sudo-like wrappers) is
+# git tag (not a listing), git merge (not --abort or
+# --quit), gh release create/upload/edit/delete, butler push
+# or steamcmd with +run_app_build
+# --root DIR the project; defaults to the repo this script is in
+# -h, --help this text
+# PATH is project-relative (an absolute path inside the root is made relative;
+# backslashes are read as slashes). NEW is read from where the caller stands.
+#
+# Output: TSV, `-` where a value is not there.
+# checked <path> <rules that applied, comma-separated | -> (not for git)
+# OVERWRITE <path> <why it is never overwritten>
+# ENUM <path> <key> <value> <allowed> <line>
+# NOT_LOCAL <path> <key> <line> a key resolution ignores locally
+# REVIEW_MODE <path> <value> <line>
+# PROTOTYPE_HEADER <path> <the header the first lines lack>
+# PROTOTYPE_IMPORT <path> <into-production | into-prototypes> <line> <text>
+# FREEZE <path> <freeze file> <called on | ->
+# AGENT_WRITE <path> <agent> <existing-file | outside>
+# ARTIFACT <path> <present | missing>
+# GIT_ACTION <action> <segment> action: tag, merge, release, deploy-itch, deploy-steam
+# SKIPPED <rule> <why> a part of a rule that could not run
+#
+# Exit codes: 0 ran (what it finds is rows); 1 the root cannot be read;
+# 2 usage error. Reads only; never writes, never prompts.
+#
+# bash 3.2 and BWK awk safe, no Python.
+
+set -u
+# Byte semantics for awk.
+LC_ALL=C
+export LC_ALL
+
+usage() { echo "write-guard: $1 (try --help)" >&2; exit 2; }
+HERE="$(cd "$(dirname "$0")" && pwd)"
+abs_path() {
+ case "$1" in
+ /*|[A-Za-z]:[\\/]*) printf '%s' "$1" ;;
+ *) printf '%s/%s' "$PWD" "${1#./}" ;;
+ esac
+}
+
+ROOT_ARG=""; TOOL=Write; AGENT=""; EXISTED=""; POS=()
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --root) [ $# -ge 2 ] || usage "--root needs a value"; ROOT_ARG="$2"; shift 2 ;;
+ --root=*) ROOT_ARG="${1#--root=}"; shift ;;
+ --tool) [ $# -ge 2 ] || usage "--tool needs Write or Edit"; TOOL="$2"; shift 2 ;;
+ --agent) [ $# -ge 2 ] || usage "--agent needs a type"; AGENT="$2"; shift 2 ;;
+ --existed) [ $# -ge 2 ] || usage "--existed needs yes or no"; EXISTED="$2"; shift 2 ;;
+ -h|--help) sed -n '2,/^$/p' "$0" | sed 's/^# //; s/^#//'; exit 0 ;;
+ *) POS[${#POS[@]}]="$1"; shift ;;
+ esac
+done
+case "$TOOL" in Write|Edit) ;; *) usage "--tool takes Write or Edit, not $TOOL" ;; esac
+case "$EXISTED" in ""|yes|no) ;; *) usage "--existed takes yes or no" ;; esac
+[ ${#POS[@]} -gt 0 ] || usage "no command"
+CMD="${POS[0]}"; NARG=$((${#POS[@]} - 1))
+NEW=""
+case "$CMD" in
+ check|config|prototype)
+ { [ $NARG -ge 1 ] && [ $NARG -le 2 ]; } || usage "$CMD takes a path and optionally the new content's file"
+ [ $NARG -eq 2 ] && NEW=$(abs_path "${POS[2]}") ;;
+ overwrite|freeze)
+ [ $NARG -eq 1 ] || usage "$CMD takes one path" ;;
+ agent)
+ [ $NARG -eq 1 ] || usage "agent takes one path"
+ [ -n "$AGENT" ] || usage "agent needs --agent TYPE" ;;
+ artifact)
+ [ $NARG -ge 1 ] || usage "artifact takes one or more paths" ;;
+ git)
+ [ $NARG -eq 0 ] || usage "git reads its segments on stdin and takes no arguments" ;;
+ *) usage "unknown command: $CMD" ;;
+esac
+[ -z "$NEW" ] || [ -f "$NEW" ] || usage "no such file: ${POS[2]}"
+
+if [ -n "$ROOT_ARG" ]; then
+ cd "$ROOT_ARG" 2>/dev/null || { echo "write-guard: cannot read root $ROOT_ARG" >&2; exit 1; }
+else
+ cd "$HERE/../.." 2>/dev/null || { echo "write-guard: cannot reach the repo root" >&2; exit 1; }
+fi
+
+# rel PATH — project-relative, slashes forward, ./ dropped; an absolute path
+# outside the root is printed as it came. The root is tried in either
+# spelling Git Bash gives it, then by physical path: its `pwd -P` against the
+# path with its deepest existing directory resolved, so a root reached through
+# a symlink (macOS /tmp is /private/tmp) and a path that comes resolved, or
+# the other way round, still match.
+ROOT_P=$(pwd); ROOT_W=$(pwd -W 2>/dev/null || printf '%s' "$ROOT_P"); ROOT_PP=$(pwd -P)
+# phys PATH — PATH with its deepest existing directory resolved (symlinks
+# followed, .. folded) and the rest as it came; empty when none can be entered.
+phys() {
+ _pd=$1; _pt=""
+ while [ -n "$_pd" ] && [ ! -d "$_pd" ]; do
+ _pt="/${_pd##*/}$_pt"; _pn=${_pd%/*}
+ [ "$_pn" = "$_pd" ] && return 0
+ _pd=$_pn
+ done
+ [ -n "$_pd" ] || _pd=/
+ _pd=$(cd "$_pd" 2>/dev/null && pwd -P) || return 0
+ printf '%s%s' "${_pd%/}" "$_pt"
+}
+rel() {
+ _p=$(printf '%s' "$1" | sed 's|\\|/|g')
+ shopt -s nocasematch
+ case "$_p" in
+ "$ROOT_P"/*) _p="${_p:${#ROOT_P}+1}" ;;
+ "$ROOT_W"/*) _p="${_p:${#ROOT_W}+1}" ;;
+ /*|[A-Za-z]:/*)
+ _pf=$(phys "$_p")
+ case "$_pf" in "$ROOT_PP"/*) _p="${_pf:${#ROOT_PP}+1}" ;; esac ;;
+ esac
+ shopt -u nocasematch
+ printf '%s' "${_p#./}"
+}
+tsv() { printf '%s' "$1" | tr '\t\n' ' '; }
+
+# The engine names project.yaml may hold, and each engine's code root
+# (directory-structure.md, "The code root is engine-specific").
+engine_name() {
+ [ -f project.yaml ] || return 0
+ [ -f "$HERE/yaml-get.awk" ] || return 0
+ YG_PATH=engine.name awk -f "$HERE/yaml-get.awk" project.yaml
+}
+ENGINE=$(engine_name | tr 'A-Z' 'a-z')
+case "$ENGINE" in
+ godot) ROOTS="src" ;;
+ unity) ROOTS="Assets" ;;
+ unreal) ROOTS="Source" ;;
+ # Unset or unknown: the three roots, so no rule is skipped for want of one.
+ *) ROOTS="src Assets Source" ;;
+esac
+
+APPLIED=""
+applied() { APPLIED="${APPLIED:+$APPLIED,}$1"; }
+
+# ------------------------------------------------------------------ overwrite
+# Each never-overwrite rule and the skill that states it.
+overwrite_why() {
+ case "$1" in
+ production/epics/*/EPIC.md) echo "/create-epics updates an existing EPIC.md in place and never rewrites it" ;;
+ project.godot) echo "/setup-engine never replaces an existing Godot project file" ;;
+ tests/helpers/*) echo "/test-helpers never overwrites existing helpers, which may hold hand-written code" ;;
+ docs/tech-debt-register.md) echo "/tech-debt appends to the register and never rewrites it" ;;
+ docs/engine-reference/*) echo "/setup-engine never overwrites an engine reference doc without asking" ;;
+ esac
+}
+rule_overwrite() {
+ applied overwrite
+ [ "$TOOL" = Write ] || return 0
+ [ -f "$1" ] || return 0
+ _w=$(overwrite_why "$1")
+ # Where /test-setup writes: the test roots of the three engines, CI and the
+ # QA evidence folder. Other paths never ask test-scaffold.sh.
+ case "$1" in tests/*|.github/*|production/qa/*|Assets/Tests/*|Source/*) ;; *) _w="${_w:--}" ;; esac
+ [ "$_w" = "-" ] && return 0
+ if [ -z "$_w" ]; then
+ # The files /test-setup creates, as test-scaffold.sh lists them per engine.
+ if [ ! -f "$HERE/test-scaffold.sh" ]; then
+ printf 'SKIPPED\toverwrite\ttest-scaffold.sh is missing, so the files /test-setup creates were not checked\n'
+ return 0
+ fi
+ _engines="$ENGINE"
+ case "$_engines" in godot|unity|unreal) ;; *) _engines="godot unity unreal" ;; esac
+ for _e in $_engines; do
+ if bash "$HERE/test-scaffold.sh" --root . "$_e" --list 2>/dev/null | grep -qxF "$1"; then
+ _w="/test-setup only creates the files that are missing"; break
+ fi
+ done
+ fi
+ [ -z "$_w" ] || printf 'OVERWRITE\t%s\t%s\n' "$(tsv "$1")" "$_w"
+}
+
+# --------------------------------------------------------------------- config
+YH="$HERE/../hooks/yaml-helper.sh"
+# yh_const NAME — the lines of the shell string NAME="\ ... " in yaml-helper.sh
+# (config-set.sh reads the same constants the same way).
+yh_const() {
+ awk -v n="$1" '
+ $0 == n "=\"\\" { on = 1; next }
+ on { l = $0; end = (l ~ /"$/); if (end) sub(/"$/, "", l); print l; if (end) exit }
+ ' "$YH"
+}
+# The scalar leaves of a YAML file, read by yaml-get.awk's rules: dotted path,
+# value, line. List items are skipped; a key with no value opens a mapping; the
+# text of a block scalar (a value of | or >, with any indicators) is never keys.
+yaml_leaves() {
+ awk '
+ # opens(s, n): the indent the text of a block scalar opened by line s (at
+ # indent n) must exceed, as in yaml-get.awk; else -1.
+ function opens(s, n, r, p, v) {
+ r = s
+ if (r == "-" || substr(r, 1, 2) == "- ") {
+ r = substr(r, 2); sub(/^ +/, "", r)
+ if (r ~ /^[|>][-+0-9]*[ \t]*(#.*)?$/) return n
+ n = n + length(s) - length(r)
+ }
+ if (r == "" || r ~ /^[:# \t]/) return -1
+ p = index(r, ":"); if (p == 0) return -1
+ v = substr(r, p + 1); sub(/^[ \t]+/, "", v); sub(/[ \t]+$/, "", v)
+ return (v ~ /^[|>][-+0-9]*[ \t]*(#.*)?$/) ? n : -1
+ }
+ BEGIN { BINMODE = 3; d = 0; blk = -1 }
+ {
+ l = $0; sub(/\r$/, "", l)
+ if (NR == 1 && substr(l, 1, 3) == "\357\273\277") l = substr(l, 4)
+ n = 0; while (substr(l, n + 1, 1) == " ") n++
+ s = substr(l, n + 1); c = substr(s, 1, 1)
+ t = s; sub(/^[ \t]+/, "", t)
+ if (t == "" || substr(t, 1, 1) == "#") next
+ if (blk >= 0) { if (n > blk) next; blk = -1 }
+ blk = opens(s, n)
+ if (c == "-" || c == "\t") next
+ p = index(s, ":"); if (p <= 1) next
+ k = substr(s, 1, p - 1); v = substr(s, p + 1); sub(/^[ \t]+/, "", v)
+ while (d > 0 && ind[d] >= n) d--
+ full = ""; for (i = 1; i <= d; i++) full = full keys[i] "."; full = full k
+ if (v == "" || substr(v, 1, 1) == "#") { d++; ind[d] = n; keys[d] = k; next }
+ q = substr(v, 1, 1)
+ if (q == "\"" || q == "'"'"'") { v = substr(v, 2); e = index(v, q); if (e) v = substr(v, 1, e - 1) }
+ else { e = index(v, " #"); if (e) v = substr(v, 1, e - 1); sub(/[ \t]+$/, "", v) }
+ printf "%s\t%s\t%d\n", full, v, NR
+ }' "$1"
+}
+rule_config() {
+ _path="$1"; _new="${2:-$1}"
+ case "$_path" in
+ production/review-mode.txt)
+ applied config
+ [ -f "$_new" ] || return 0
+ _v=$(awk 'BEGIN { BINMODE = 3 } { sub(/\r$/, ""); sub(/^[ \t]+/, ""); sub(/[ \t]+$/, "") } $0 != "" { print $0 "\t" NR; exit }' "$_new")
+ printf 'REVIEW_MODE\t%s\t%s\t%s\n' "$_path" "${_v%% *}" "${_v##* }"
+ [ -n "$_v" ] || printf 'REVIEW_MODE\t%s\t-\t-\n' "$_path"
+ return 0 ;;
+ project.yaml|project.local.yaml) applied config ;;
+ *) return 0 ;;
+ esac
+ [ -f "$_new" ] || return 0
+ if [ ! -f "$YH" ]; then
+ printf 'SKIPPED\tconfig\tyaml-helper.sh is missing; the allowed values and the local whitelist live there\n'
+ return 0
+ fi
+ _old=""
+ [ "$_new" != "$_path" ] && [ -f "$_path" ] && _old=$(yaml_leaves "$_path")
+ { printf 'E\t%s\n' "$(yh_const _yaml_helper_enums)" | sed '1!s/^/E /'
+ printf 'W\t%s\n' "$(yh_const _yaml_helper_locally_overridable)" | sed '1!s/^/W /'
+ printf '%s\n' "$_old" | sed '/^$/d; s/^/O /'
+ yaml_leaves "$_new" | sed 's/^/N /'
+ } | P="$_path" awk -F '\t' '
+ $1 == "E" { i = index($2, "::"); if (i) AL[substr($2, 1, i - 1)] = substr($2, i + 2); next }
+ $1 == "W" { if ($2 != "") WL[$2] = 1; next }
+ $1 == "O" { OV[$2] = $3; HAD[$2] = 1; next }
+ $1 == "N" {
+ k = $2; v = $3; ln = $4; p = ENVIRON["P"]
+ changed = !(k in HAD) || OV[k] != v
+ # testing.strict as one scalar is the back-compat boolean (yaml-helper.sh).
+ al = (k in AL) ? AL[k] : (k == "testing.strict" ? "true|false" : "")
+ if (al != "" && changed && index("|" al "|", "|" v "|") == 0)
+ printf "ENUM\t%s\t%s\t%s\t%s\t%d\n", p, k, v, al, ln
+ # schema_version and framework.* are file metadata, not settings, so the
+ # local file may carry them (validate_local_scope exempts the same two).
+ if (p == "project.local.yaml" && !(k in WL) && k != "schema_version" && k !~ /^framework\./ && !(k in HAD))
+ printf "NOT_LOCAL\t%s\t%s\t%d\n", p, k, ln
+ if (k == "modes.review_mode" && changed)
+ printf "REVIEW_MODE\t%s\t%s\t%d\n", p, v, ln
+ }'
+}
+
+# ------------------------------------------------------------------ prototype
+# The file types that can hold a comment line (/prototype, Phase 5: JSON,
+# scene and project files are exempt).
+COMMENTABLE=" gd py cs cpp cc cxx h hpp js mjs ts tsx lua html htm md gdshader shader hlsl glsl sh "
+rule_prototype() {
+ _path="$1"; _new="${2:-$1}"; _dir=""
+ case "$_path" in
+ prototypes/*) _dir=into-production ;;
+ *) for _r in $ROOTS; do case "$_path" in "$_r"/*) _dir=into-prototypes ;; esac; done ;;
+ esac
+ [ -n "$_dir" ] || return 0
+ applied prototype
+ [ -f "$_new" ] || return 0
+ if [ "$_dir" = into-production ]; then
+ _ext="${_path##*.}"; [ "$_ext" = "$_path" ] && _ext=""
+ _ext=$(printf '%s' "$_ext" | tr 'A-Z' 'a-z')
+ case "$COMMENTABLE" in
+ *" $_ext "*)
+ # The header is the file's first lines; five leaves room for a shebang
+ # or an engine's own first line above it.
+ if ! awk 'BEGIN { BINMODE = 3 } NR > 5 { exit } /PROTOTYPE - NOT FOR PRODUCTION|VERTICAL SLICE - NOT FOR PRODUCTION/ { f = 1; exit } END { exit !f }' "$_new"; then
+ case "$_path" in
+ prototypes/*-vertical-slice/*) _h="VERTICAL SLICE - NOT FOR PRODUCTION" ;;
+ *) _h="PROTOTYPE - NOT FOR PRODUCTION" ;;
+ esac
+ printf 'PROTOTYPE_HEADER\t%s\t%s\n' "$(tsv "$_path")" "$_h"
+ fi ;;
+ esac
+ fi
+ # A reference that climbs out of prototypes/ into a code root (../src/,
+ # Godot's res://src/), or one from the code root into prototypes/.
+ ROOTS="$ROOTS" D="$_dir" P="$(tsv "$_path")" awk '
+ BEGIN {
+ BINMODE = 3
+ n = split(ENVIRON["ROOTS"], r, " "); alt = ""
+ for (i = 1; i <= n; i++) alt = alt (alt == "" ? "" : "|") r[i]
+ if (ENVIRON["D"] == "into-production") re = "(res://|\\.\\./)(\\.\\./)*(" alt ")/"
+ else re = "(res://|\\.\\./|[\"'"'"'(<])(\\.\\./)*prototypes/"
+ }
+ { l = $0; sub(/\r$/, "", l) }
+ l ~ re { gsub(/\t/, " ", l); printf "PROTOTYPE_IMPORT\t%s\t%s\t%d\t%s\n", ENVIRON["P"], ENVIRON["D"], NR, l }
+ ' "$_new"
+}
+
+# --------------------------------------------------------------------- freeze
+FREEZE_FILE=production/localization/freeze-status.md
+rule_freeze() {
+ case "$1" in assets/data/strings/*) applied freeze ;; *) return 0 ;; esac
+ [ -f "$FREEZE_FILE" ] || return 0
+ # /localize writes **Status**: ACTIVE or LIFTED; "Active" is spelled both
+ # ways in the skill, so the match ignores case.
+ _c=$(awk 'BEGIN { BINMODE = 3 }
+ { l = $0; sub(/\r$/, "", l); u = toupper(l) }
+ u ~ /^\*\*STATUS\*\*:[ \t]*ACTIVE([ \t]|$)/ || u ~ /^STATUS:[ \t]*ACTIVE([ \t]|$)/ { act = 1 }
+ u ~ /^\*\*CALLED\*\*:/ { c = l; sub(/^\*\*[Cc][Aa][Ll][Ll][Ee][Dd]\*\*:[ \t]*/, "", c) }
+ END { if (act) print (c == "" ? "-" : c) }' "$FREEZE_FILE")
+ [ -z "$_c" ] || printf 'FREEZE\t%s\t%s\t%s\n' "$(tsv "$1")" "$FREEZE_FILE" "$(tsv "$_c")"
+}
+
+# ---------------------------------------------------------------------- agent
+rule_agent() {
+ [ -n "$AGENT" ] || return 0
+ applied agent
+ case "$1" in
+ # Agent memory and session-state appends need no approval
+ # (.claude/rules/agent-memory.md); they are not the subagent exception.
+ .claude/agent-memory/*|production/session-state/active.md) return 0 ;;
+ esac
+ case "$1" in
+ production/*|docs/*|tests/*) ;;
+ *) printf 'AGENT_WRITE\t%s\t%s\toutside\n' "$(tsv "$1")" "$(tsv "$AGENT")"; return 0 ;;
+ esac
+ _e="$EXISTED"; [ -n "$_e" ] || { [ -e "$1" ] && _e=yes || _e=no; }
+ [ "$_e" = yes ] && printf 'AGENT_WRITE\t%s\t%s\texisting-file\n' "$(tsv "$1")" "$(tsv "$AGENT")"
+ return 0
+}
+
+# ------------------------------------------------------------------------ git
+rule_git() {
+ awk '
+ BEGIN {
+ BINMODE = 3
+ # A segment runs a tool when the tool is its command: first, or after
+ # VAR=value words and the wrappers validate-push.sh allows, by name or
+ # by a path ending in it. "echo git tag" runs echo.
+ PRE = "^([A-Za-z_][A-Za-z0-9_]*=[^ ]* |(sudo|doas|env|nice|nohup|time|exec|command|xargs|stdbuf|winpty) |timeout [0-9.]+[smhd]? )*([^ ]*[/\\\\])?"
+ # The options git itself takes before the subcommand, as validate-push.sh
+ # reads them: -C, -c and six long options take a value; others stand alone.
+ GOPT = "( -[Cc] [^ ]+| --(git-dir|work-tree|namespace|super-prefix|config-env|attr-source) [^ ]+| -[A-Za-z]| --[A-Za-z-]+(=[^ ]+)?)*"
+ }
+ function words(s, n) { gsub(/[ \t]+/, " ", s); sub(/^ /, "", s); sub(/ $/, "", s); return s }
+ {
+ seg = $0; sub(/\r$/, "", seg); s = words(seg)
+ if (s == "") next
+ act = ""
+ if (match(s, PRE "[Gg][Ii][Tt](\\.exe)?" GOPT " tag( |$)")) {
+ rest = substr(s, RSTART + RLENGTH); a = " " rest " "
+ # git tag alone, or with a list, verify or filter option, only reads.
+ if (rest != "" && a !~ / (-l|--list|-v|--verify|-n[0-9]*|--contains|--no-contains|--points-at|--merged|--no-merged|--sort(=[^ ]*)?|--format(=[^ ]*)?|--column|--no-column) /) act = "tag"
+ }
+ else if (match(s, PRE "[Gg][Ii][Tt](\\.exe)?" GOPT " merge( |$)")) {
+ a = " " substr(s, RSTART + RLENGTH) " "
+ if (a !~ / --(abort|quit) /) act = "merge"
+ }
+ else if (s ~ (PRE "gh(\\.exe)? release (create|upload|edit|delete)( |$)")) act = "release"
+ else if (s ~ (PRE "butler(\\.exe)? push( |$)")) act = "deploy-itch"
+ else if (s ~ (PRE "steamcmd(\\.exe|\\.sh)?( |$)") && s ~ /\+run_app_build( |$)/) act = "deploy-steam"
+ if (act != "") { gsub(/\t/, " ", seg); printf "GIT_ACTION\t%s\t%s\n", act, seg }
+ }'
+}
+
+# ----------------------------------------------------------------------- main
+case "$CMD" in
+ git) rule_git; exit 0 ;;
+ artifact)
+ i=1
+ while [ $i -le $NARG ]; do
+ _p=$(rel "${POS[$i]}")
+ if [ -e "$_p" ]; then printf 'ARTIFACT\t%s\tpresent\n' "$(tsv "$_p")"; else printf 'ARTIFACT\t%s\tmissing\n' "$(tsv "$_p")"; fi
+ i=$((i + 1))
+ done
+ exit 0 ;;
+esac
+
+PATH_REL=$(rel "${POS[1]}")
+OUT=$(case "$CMD" in
+ (check)
+ rule_overwrite "$PATH_REL"
+ rule_config "$PATH_REL" "$NEW"
+ rule_prototype "$PATH_REL" "$NEW"
+ rule_freeze "$PATH_REL"
+ rule_agent "$PATH_REL"
+ printf 'APPLIED\t%s\n' "$APPLIED" ;;
+ (overwrite) rule_overwrite "$PATH_REL"; printf 'APPLIED\t%s\n' "$APPLIED" ;;
+ (config) rule_config "$PATH_REL" "$NEW"; printf 'APPLIED\t%s\n' "$APPLIED" ;;
+ (prototype) rule_prototype "$PATH_REL" "$NEW"; printf 'APPLIED\t%s\n' "$APPLIED" ;;
+ (freeze) rule_freeze "$PATH_REL"; printf 'APPLIED\t%s\n' "$APPLIED" ;;
+ (agent) rule_agent "$PATH_REL"; printf 'APPLIED\t%s\n' "$APPLIED" ;;
+esac)
+# The checked row first: the rules ran inside $( ), so their list comes back
+# as the last line.
+_applied=$(printf '%s\n' "$OUT" | sed -n 's/^APPLIED //p')
+printf 'checked\t%s\t%s\n' "$(tsv "$PATH_REL")" "${_applied:--}"
+printf '%s\n' "$OUT" | grep -v '^APPLIED ' | grep -v '^$'
+exit 0
diff --git a/.claude/scripts/yaml-get.awk b/.claude/scripts/yaml-get.awk
new file mode 100644
index 00000000..c9c99f92
--- /dev/null
+++ b/.claude/scripts/yaml-get.awk
@@ -0,0 +1,88 @@
+# yaml-get.awk — print the scalar at one dotted path of a YAML file, or nothing.
+# The one YAML reader the bash/awk helpers share (project-state.sh,
+# config-set.sh), so they read a file the same way:
+#
+# YG_PATH=project.stage awk -f .claude/scripts/yaml-get.awk project.yaml
+#
+# The rules are get_yaml_key's (yaml-helper.sh, which needs Python), so the
+# two readers give one answer for one file; the test suite holds them to it:
+# - indentation is leading spaces; a tab-led line is skipped, not nested
+# - blank lines and lines whose first non-space is `#` are skipped
+# - the key runs to the first `:`; it may not start with `:`, `#` or a space
+# - a value starting with `#` is empty; a quoted value is the text up to the
+# closing quote of the same kind (rest of the line if unclosed); otherwise
+# the value is cut at the first ` #`
+# - an empty value opens a mapping, and a repeated key merges into it; a
+# scalar assigned to a key replaces everything under that key
+# - a value of `|` or `>`, with any indicators (`|-`, `>+`, `|2`) and an
+# optional comment, opens a block scalar: the lines after it indented
+# deeper than its key (or than the dash, for a `- |` list item), and the
+# blank lines among them, are its text, never keys; the value is the
+# indicator itself
+# - CR line ends and a UTF-8 BOM on line 1 are ignored
+# A path that ends on a mapping prints nothing, as get_yaml_key does.
+# BWK awk safe: no gawk extensions. Run it under LC_ALL=C (byte semantics for
+# the BOM test).
+
+# opens(s, n) -- when line s (at indent n, its leading spaces removed) opens
+# a block scalar, the indent its text must exceed; else -1.
+function opens(s, n, r, p, v) {
+ r = s
+ if (r == "-" || substr(r, 1, 2) == "- ") {
+ r = substr(r, 2); sub(/^ +/, "", r)
+ if (r ~ /^[|>][-+0-9]*[ \t]*(#.*)?$/) return n
+ n = n + length(s) - length(r)
+ }
+ if (r == "" || r ~ /^[:# \t]/) return -1
+ p = index(r, ":"); if (p == 0) return -1
+ v = substr(r, p + 1); sub(/^[ \t]+/, "", v); sub(/[ \t]+$/, "", v)
+ return (v ~ /^[|>][-+0-9]*[ \t]*(#.*)?$/) ? n : -1
+}
+
+BEGIN { want = ENVIRON["YG_PATH"]; depth = 0; val = ""; blk = -1 }
+{
+ line = $0
+ # "\357\273\277" is the UTF-8 byte-order mark.
+ if (NR == 1 && substr(line, 1, 3) == "\357\273\277") line = substr(line, 4)
+ sub(/\r$/, "", line)
+ n = 0
+ while (substr(line, n + 1, 1) == " ") n++
+ s = substr(line, n + 1)
+ t = s
+ sub(/^[ \t]+/, "", t)
+ if (t == "" || substr(t, 1, 1) == "#") next
+ if (blk >= 0) { if (n > blk) next; blk = -1 }
+ blk = opens(s, n)
+ c = substr(s, 1, 1)
+ if (c == ":" || c == "#" || c == "\t") next
+ p = index(s, ":")
+ if (p == 0) next
+ key = substr(s, 1, p - 1)
+ sub(/[ \t]+$/, "", key)
+ v = substr(s, p + 1)
+ sub(/^[ \t]+/, "", v)
+ sub(/[ \t]+$/, "", v)
+ q = substr(v, 1, 1)
+ if (q == "#") v = ""
+ else if (q == "\"" || q == "'") {
+ rest = substr(v, 2)
+ e = index(rest, q)
+ v = (e > 0) ? substr(rest, 1, e - 1) : rest
+ } else {
+ h = index(v, " #")
+ if (h > 0) { v = substr(v, 1, h - 1); sub(/[ \t]+$/, "", v) }
+ }
+ while (depth > 0 && ind[depth] >= n) depth--
+ full = ""
+ for (i = 1; i <= depth; i++) full = full keys[i] "."
+ full = full key
+ if (v == "") {
+ depth++; ind[depth] = n; keys[depth] = key
+ if (full == want) val = ""
+ } else {
+ if (full == want) val = v
+ # A scalar replaces the mapping it lands on, and every value under it.
+ else if (substr(want, 1, length(full) + 1) == full ".") val = ""
+ }
+}
+END { printf "%s", val }
diff --git a/.claude/settings.json b/.claude/settings.json
index c4672535..a6ce1b0a 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -4,6 +4,9 @@
"type": "command",
"command": "bash \"$CLAUDE_PROJECT_DIR/.claude/statusline.sh\""
},
+ "worktree": {
+ "baseRef": "head"
+ },
"permissions": {
"defaultMode": "default",
"allow": [
@@ -84,11 +87,10 @@
"Bash(git *clean* -Xqdf*)",
"Bash(sudo *)",
"Bash(chmod 777*)",
- "Bash(*>.env*)",
- "Bash(cat *.env*)",
- "Bash(type *.env*)",
"Read(**/.env*)",
"Edit(**/.env*)",
+ "Edit(**/*.uasset)",
+ "Edit(**/*.umap)",
"PowerShell(Remove-Item *-Recurse*)",
"PowerShell(Remove-Item * -r*)",
"PowerShell(Remove-Item -r*)",
@@ -178,6 +180,31 @@
"timeout": 10
}
]
+ },
+ {
+ "matcher": "Write|Edit",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-registry.sh\"",
+ "timeout": 15
+ },
+ {
+ "type": "command",
+ "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-write.sh\"",
+ "timeout": 15
+ }
+ ]
+ },
+ {
+ "matcher": "Read",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-read.sh\"",
+ "timeout": 10
+ }
+ ]
}
],
"PostToolUse": [
@@ -199,7 +226,7 @@
],
"Notification": [
{
- "matcher": "",
+ "matcher": "permission_prompt|idle_prompt",
"hooks": [
{
"type": "command",
@@ -221,18 +248,6 @@
]
}
],
- "PostCompact": [
- {
- "matcher": "",
- "hooks": [
- {
- "type": "command",
- "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-compact.sh\"",
- "timeout": 10
- }
- ]
- }
- ],
"Stop": [
{
"matcher": "",
@@ -240,7 +255,8 @@
{
"type": "command",
"command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-stop.sh\"",
- "timeout": 10
+ "timeout": 10,
+ "async": true
}
]
}
@@ -265,6 +281,11 @@
"type": "command",
"command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/log-agent-stop.sh\"",
"timeout": 5
+ },
+ {
+ "type": "command",
+ "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-agent-artifact.sh\"",
+ "timeout": 10
}
]
}
diff --git a/.claude/skills/adopt/SKILL.md b/.claude/skills/adopt/SKILL.md
index a0a877ff..718436bc 100644
--- a/.claude/skills/adopt/SKILL.md
+++ b/.claude/skills/adopt/SKILL.md
@@ -3,7 +3,7 @@ name: adopt
description: "Brownfield audit — do existing artifacts actually work? Numbered migration plan. Unlike /project-stage-detect, checks compliance not existence."
argument-hint: "[focus: full | gdds | adrs | stories | infra]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash, Write, AskUserQuestion, Bash(bash "*/.claude/skills/adopt/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, AskUserQuestion, Bash(bash "*/.claude/skills/adopt/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/gdd-structure-check.sh *), Bash(bash .claude/scripts/migrate-v1-config.sh --dry-run*)
model: sonnet
---
diff --git a/.claude/skills/adopt/references/1-detect.md b/.claude/skills/adopt/references/1-detect.md
index 7f5ab618..069262c0 100644
--- a/.claude/skills/adopt/references/1-detect.md
+++ b/.claude/skills/adopt/references/1-detect.md
@@ -37,8 +37,35 @@ If the project appears fresh (no artifacts at all), use `AskUserQuestion`:
- "My artifacts are in a non-standard location — help me find them"
- "Cancel"
-Then stop — do not proceed with the audit regardless of which option the user picks
-(each option leads to a different skill or manual investigation).
+`/start` and Cancel end this skill: say which, and stop.
+
+**If they pick "help me find them"**, search before asking anything else:
+
+1. Search the folder they named, if they named one; otherwise the whole
+ project, skipping `.claude/`, `.git/`, `docs/engine-reference/`,
+ `studio-tests/`, `node_modules/` and the engine's build and
+ cache folders.
+2. Glob `**/*.md` there, then Grep the matches for the headings each artifact
+ carries: a GDD has `## Overview` with `## Detailed Rules` or
+ `## Detailed Design`; an ADR `## Status` with `## Decision`; a story
+ `## Acceptance Criteria` with a `Status` line; a concept doc
+ `## Elevator Pitch` or `## Game Pillars`; a brief `## Core loop` with
+ `## MVP`.
+3. Show what was found, grouped by type, each with the place every skill reads
+ it from: GDD → `design/gdd/[name].md`; ADR →
+ `docs/architecture/adr-NNNN-[name].md`; story →
+ `production/epics/[epic]/story-NNN-[name].md`; concept →
+ `design/gdd/game-concept.md`; brief → `design/game-brief.md`. If nothing
+ matched, say so, name the folders and headings searched, and offer `/start`.
+4. Ask before moving anything — a move takes the file away from its old path,
+ so it is a `file_deletions` decision: "May I move these [N] files to the
+ standard folders?" — `[A] Move them all` / `[B] Let me pick which` /
+ `[C] Don't move them — I'll do it myself`. Move with `git mv` in a git
+ repository (the file's history follows it), plain `mv` otherwise. Never
+ overwrite a file already at the target: name the clash and skip that file.
+ Files are moved, never edited.
+5. After the moves, run Phase 1 again from the top, so the audit reads the files
+ where every other skill will. With [C], print the moves as a list and stop.
Report: "Detected phase: [phase]. Found: [N] GDDs, [M] ADRs, [P] stories."
diff --git a/.claude/skills/adopt/references/2-format-audit.md b/.claude/skills/adopt/references/2-format-audit.md
index a0d43100..6334fc29 100644
--- a/.claude/skills/adopt/references/2-format-audit.md
+++ b/.claude/skills/adopt/references/2-format-audit.md
@@ -62,8 +62,9 @@ Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria.
A section reported PRESENT can still be an empty heading. For each GDD, also
record with a targeted grep (not a full read):
-- Placeholder-only sections — `Grep pattern="\[To be designed\]"` (or an
- equivalent empty/single-line body) marks a present-but-unwritten section.
+- Placeholder-only sections — the script's `PLACEHOLDER:` line names the
+ present sections that hold only `[To be designed]` or nothing; a
+ single-line stub body is the same in effect, so spot-check short sections.
- The `**Status**:` header field — `Grep pattern="^>?[[:space:]]*\*\*Status\*\*:"`.
Valid values: `Draft`, `In Design`, `Designed`, `In Review`, `Approved`,
`Implemented`, `Needs Revision`.
@@ -151,7 +152,8 @@ real values.
Language, Rendering, Physics, the naming, platform and performance fields,
Framework, or the specialists. Not merely "some bullet is filled in": the
shipped template ships one prose default (`- **Required Tests**: …`) that is
-never migrated, and counting it made every fresh clone read as a v1.0 project.
+never migrated, and counting it would make every fresh clone read as a v1.0
+project.
Do not hand-migrate. Run the converter, which is deterministic and covered by
the framework's own test suite:
diff --git a/.claude/skills/architecture-decision/SKILL.md b/.claude/skills/architecture-decision/SKILL.md
index cdca26ae..a368961c 100644
--- a/.claude/skills/architecture-decision/SKILL.md
+++ b/.claude/skills/architecture-decision/SKILL.md
@@ -3,7 +3,7 @@ name: architecture-decision
description: "Create an ADR documenting a technical decision: context, alternatives considered, consequences."
argument-hint: "[title | retrofit <path> | accept <ADR-id>] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(wc -c *), Bash(bash "*/.claude/skills/architecture-decision/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(wc -c *), Bash(bash "*/.claude/skills/architecture-decision/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/registry.sh *)
model: sonnet
---
@@ -91,7 +91,7 @@ Scan `docs/architecture/` for existing ADRs to find the next number.
After the ADR is written (and registry optionally updated), close with `AskUserQuestion`.
Before generating the widget:
-1. Read `docs/registry/architecture.yaml` — check if any priority ADRs are still unwritten (look for ADRs flagged in technical-preferences.md or systems-index.md as prerequisites)
+1. Read the `## Required ADRs` section of `docs/architecture/architecture.md` (by section) and list `docs/architecture/adr-*.md`: a required ADR with no file is still unwritten. Without `architecture.md`, look for ADRs flagged in technical-preferences.md or systems-index.md as prerequisites
2. Check if all prerequisite ADRs are now written. If yes, include a "Start writing GDDs" option.
3. List ALL remaining priority ADRs as individual options — not just the next one or two.
@@ -117,9 +117,8 @@ If there are no remaining priority ADRs and no undesigned GDD systems, offer onl
**Do NOT unblock stories here.** This ADR is `Proposed` — Step 5 guarantees it,
and a story blocked *pending this decision* is still pending it. Unblocking on
-authoring is how the deadlock stayed invisible: it defeated the guard at the
-moment the guard became relevant, so the pipeline appeared to flow while running
-on decisions nobody had accepted.
+authoring defeats the guard at the moment it becomes relevant: the pipeline
+appears to flow while running on decisions nobody has accepted.
Instead, tell the user what is now waiting on acceptance:
diff --git a/.claude/skills/architecture-decision/references/0-accept.md b/.claude/skills/architecture-decision/references/0-accept.md
index 6b6029df..9069e3ed 100644
--- a/.claude/skills/architecture-decision/references/0-accept.md
+++ b/.claude/skills/architecture-decision/references/0-accept.md
@@ -11,8 +11,8 @@ Enter **acceptance mode**. This is the *only* path in the framework that moves a
ADR from `Proposed` to `Accepted`. Authoring always produces `Proposed`
(Step 5), while
`/create-control-manifest`, `/create-epics`, `/create-stories` and `/gate-check`
-all require `Accepted` — so without this mode the pipeline had a state it could
-enter and never leave.
+all require `Accepted` — so without this mode an ADR would enter a state it
+never leaves.
1. **Resolve the id to a file, then read it.** Glob
`docs/architecture/adr-NNNN-*.md` for the given number. If **no** file matches,
diff --git a/.claude/skills/architecture-decision/references/0-retrofit.md b/.claude/skills/architecture-decision/references/0-retrofit.md
index 20b25dfa..476a7a59 100644
--- a/.claude/skills/architecture-decision/references/0-retrofit.md
+++ b/.claude/skills/architecture-decision/references/0-retrofit.md
@@ -9,11 +9,15 @@
Enter **retrofit mode**:
-1. Read the existing ADR file completely.
+1. Read the existing ADR file completely. This step needs the whole ADR: read it
+ in ranges by its headings (found with the Grep tool: pattern `^#`, content
+ mode), since a whole-file Read over 40 KB is refused.
2. Identify which template sections are present by scanning headings:
- `## Status` — **BLOCKING if missing**: `/story-readiness` cannot check ADR acceptance
- `## ADR Dependencies` — HIGH if missing: dependency ordering breaks
- - `## Engine Compatibility` — HIGH if missing: post-cutoff risk unknown
+ - `## Engine Compatibility` — HIGH if missing: post-cutoff risk unknown. A
+ present table with no **Layer** row is HIGH too: the ADR counts as critical
+ wherever it is read, so at `standard` its advisory items become blockers
- `## GDD Requirements Addressed` — MEDIUM if missing: traceability lost
- `## Date` — MEDIUM if missing, and no `## Last Verified` either: `/create-stories`
stamps stories with it and `/dev-story` compares against it, so without it a
@@ -44,7 +48,11 @@ Enter **retrofit mode**:
- For **ADR Dependencies**: ask — "Does this decision depend on any other ADR?
Does it enable or block any other ADR or epic?" Accept "None" for each field.
- For **Engine Compatibility**: read the engine reference docs (same as Step 1 below)
- and ask the user to confirm the domain. Then generate the table with verified data.
+ and ask the user to confirm the domain. Then generate the table with verified data,
+ its Layer row included.
+ - For a present Engine Compatibility table with no **Layer** row: find the
+ layer as `references/5-generate.md` says under "Always write the Layer row",
+ and add the row under **Domain**. It adds a row and changes none.
- For **GDD Requirements Addressed**: ask — "Which GDD systems motivated this decision?
What specific requirement in each GDD does this ADR address?"
- Append each missing section to the ADR file using the Edit tool.
diff --git a/.claude/skills/architecture-decision/references/3-gather-context.md b/.claude/skills/architecture-decision/references/3-gather-context.md
index c5088c96..94f5fb41 100644
--- a/.claude/skills/architecture-decision/references/3-gather-context.md
+++ b/.claude/skills/architecture-decision/references/3-gather-context.md
@@ -52,16 +52,18 @@ or explicitly accepted as an intentional exception.
The registry (3a) covers *what* prior decisions bind — not always *why*. If the
registry surfaced a directly relevant ADR and its reasoning matters here (not
just its stated facts), read that specific ADR — never glob-and-read every
-ADR in `docs/architecture/` on the chance one is relevant:
+ADR in `docs/architecture/` on the chance one is relevant. Read it by section:
+find the headings you need with the Grep tool (pattern `^#`, content mode)
+and Read those ranges with offset and limit.
1. **Map its headings first** (cheap):
```
Grep pattern="^## " path="docs/architecture/[adr-file].md" output_mode="content" -n
```
-2. **Under ~50KB** (`Bash: wc -c "docs/architecture/[adr-file].md"`) — one full
+2. **Under ~40KB** (`Bash: wc -c "docs/architecture/[adr-file].md"`) — one full
`Read` is fine; per-call overhead exceeds the savings from bounded reads at
this size.
-3. **~50KB or larger** — bounded-read only `## Context`, `## Decision`, and
+3. **~40KB or larger** — bounded-read only `## Context`, `## Decision`, and
`## Consequences` (the sections that carry reasoning, not just facts) via
`Read(offset, limit)` from the heading map.
diff --git a/.claude/skills/architecture-decision/references/5-generate.md b/.claude/skills/architecture-decision/references/5-generate.md
index 967adb50..20b67f16 100644
--- a/.claude/skills/architecture-decision/references/5-generate.md
+++ b/.claude/skills/architecture-decision/references/5-generate.md
@@ -43,8 +43,9 @@ chosen approach.]
| Field | Value |
|-------|-------|
-| **Engine** | [e.g. Godot 4.6] |
+| **Engine** | [e.g. Godot 4.7] |
| **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input] |
+| **Layer** | [Foundation / Core / Feature / Presentation] |
| **Knowledge Risk** | [LOW / MEDIUM / HIGH — from VERSION.md] |
| **References Consulted** | [List engine-reference docs read, e.g. `docs/engine-reference/godot/modules/physics.md`] |
| **Post-Cutoff APIs Used** | [Any APIs from post-LLM-cutoff versions this decision depends on, or "None"] |
@@ -140,6 +141,15 @@ to implement it.]
- [Links to related design documents]
```
+**Always write the Layer row.** An ADR with no Layer row counts as critical
+(Foundation) wherever it is read, so at `standard` its advisory items become
+blockers. The value is the ADR's own layer, how early in the build it must
+exist: the layer `docs/architecture/architecture.md`'s layer map gives the
+system this decision governs. With no layer map, or no system in it, ask the
+user, with the four values as options. Never take it from an epic that
+references the ADR, and never reuse a `Domain` value (the template's note under
+Engine Compatibility says why).
+
5.5. **Engine Specialist Validation** — Before saving, spawn the **primary engine specialist** via `Agent` to validate the drafted ADR:
- Resolve the primary specialist: `<engine>-specialist` derived from `engine.name` in `project.yaml` (Godot→`godot-specialist`, Unity→`unity-specialist`, Unreal→`unreal-specialist`); if `engine.name` is absent or empty, read the Primary line of the `## Engine Specialists` section in `.claude/docs/technical-preferences.md`
- If no engine is configured (neither source yields an engine), skip this step **Record ``Engine validation: NOT ASSESSED — no engine configured (`engine.name` unset in `project.yaml`)`` in this run's output.** A skipped check that says nothing is indistinguishable from a check that passed; the reader cannot tell engine guidance was never sought.
@@ -178,8 +188,8 @@ developers reading the GDD from implementing the wrong interface.
```
**This check has three outcomes, not two.** The two above are "found" and "none
-found"; the third is **could not check**, and until now it fell through the
-silent branch and rendered exactly like a clean result.
+found"; the third is **could not check**, which must never take the silent
+branch and render like a clean result.
- **None found** — print one line, do not stay silent:
`GDD sync: checked [N] referenced GDD(s), no naming inconsistencies.`
@@ -231,7 +241,7 @@ Registry candidates from this ADR:
**Registry append logic**: When writing to `docs/registry/architecture.yaml`, do NOT assume sections are empty. The file may already have entries from previous ADRs written in this session. Before each Edit call:
1. Read the current state of `docs/registry/architecture.yaml`
2. Find the correct section (state_ownership, interfaces, forbidden_patterns, api_decisions)
-3. Append the new entry AFTER the last existing entry in that section — do not try to replace a `[]` placeholder that may no longer exist
+3. If the section is still the empty list (`state_ownership: []`), replace `[]` with the first entry: the key alone on its line, the entry below it indented two spaces as in the file's commented example. An entry appended after `[]` makes the file invalid YAML. Otherwise append the new entry AFTER the last existing entry in that section
4. If the section has entries already, use the closing content of the last entry as the `old_string` anchor, and append the new entry after it
**BLOCKING — do not write to `docs/registry/architecture.yaml` without explicit user approval.**
@@ -241,6 +251,12 @@ Ask using `AskUserQuestion`:
- Options: "Yes — update the registry", "Not yet — I want to review the candidates", "Skip registry update"
Only proceed if the user selects yes. If yes: append new entries. Never modify existing entries — if a stance is
-changing, set the old entry to `status: superseded_by: ADR-[NNNN]` and add the new entry.
+changing, set the old entry to `status: "superseded_by: ADR-[NNNN]"` and add the new entry. Keep the quotes:
+unquoted, the second colon makes the file invalid YAML.
+
+After writing, run `bash .claude/scripts/registry.sh validate` and fix every row about an entry this write added
+or changed (a DUPLICATE, STATUS or LAYOUT row, an UNQUOTED row (quote the value it names), or a PATH_MISSING row for a path it named) before you go on; name
+rows about other entries to the user rather than fixing them unasked. If the script is missing or prints nothing,
+say the registry check did not run, then re-read the entries you wrote against the rules in the file's header.
---
diff --git a/.claude/skills/architecture-review/SKILL.md b/.claude/skills/architecture-review/SKILL.md
index 7463dc11..1a9d28aa 100644
--- a/.claude/skills/architecture-review/SKILL.md
+++ b/.claude/skills/architecture-review/SKILL.md
@@ -1,9 +1,9 @@
---
name: architecture-review
description: "Traceability matrix mapping GDD requirements to ADRs. Finds gaps, cross-ADR conflicts, engine compatibility. PASS/CONCERNS/NOT ASSESSED/FAIL."
-argument-hint: "[focus: full | coverage | consistency | engine | single-gdd path/to/gdd.md]"
+argument-hint: "[focus: full | coverage | consistency | engine | rtm | single-gdd path/to/gdd.md]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash, Write, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/architecture-review/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/architecture-review/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/review-receipts.sh check *), Bash(bash .claude/scripts/review-receipts.sh hash *), Bash(bash .claude/scripts/adr-dep-graph.sh*), Bash(bash .claude/scripts/registry.sh validate*)
model: opus
---
diff --git a/.claude/skills/architecture-review/references/1-load.md b/.claude/skills/architecture-review/references/1-load.md
index 26abe796..9a65759e 100644
--- a/.claude/skills/architecture-review/references/1-load.md
+++ b/.claude/skills/architecture-review/references/1-load.md
@@ -16,31 +16,67 @@
### Phase 1a — L0: Summary Scan (fast, low tokens)
-**Freshness check before any scan.** Locate the latest prior report — Glob
-`docs/architecture/architecture-review-*.md` and take the newest — then:
+**Freshness check before any scan.** A prior report can stand in for this run
+only if nothing it rests on has changed: the documents, the engine reference,
+the project config, this skill, and the kind of review that produced it.
+
+In `rtm` mode, skip the check and say so — *"Freshness check: not run — rtm
+builds the matrix fresh, because stories and tests change without any review
+input changing."*
+
+Otherwise locate the latest prior report — Glob
+`docs/architecture/architecture-review-*.md` and take the newest — and check
+**the review inputs**: every file the phases below read that can change a
+finding or the verdict. `[engine]` is the lowercased `engine.name` from
+`project.yaml`, the value Phase 5 uses; with no engine configured, leave the two
+engine-reference paths out.
```
-Bash: bash .claude/scripts/review-receipts.sh check "[latest-report]" docs/architecture/adr-*.md design/gdd/*.md
+Bash: bash .claude/scripts/review-receipts.sh check "[latest-report]" docs/architecture/adr-*.md design/gdd/*.md docs/architecture/tr-registry.yaml docs/architecture/architecture.md docs/engine-reference/[engine]/*.md docs/engine-reference/[engine]/modules/*.md project.yaml .claude/docs/technical-preferences.md docs/consistency-failures.md .claude/skills/architecture-review/SKILL.md .claude/skills/architecture-review/references/*.md
```
+Phase 8 stamps the same list into this run's report; keep the two identical,
+and add any file a phase starts reading to both. The check also compares every
+file the prior report stamped, named here or not, and prints `GONE:` for one
+that no longer exists.
+
+Then read the prior report's `Mode:` and `Workflow:` lines. It **covers** this
+run only when its Mode is this run's mode (for `single-gdd`, the same path) or
+`full`, and its Workflow is this run's resolved `workflow` or `full`. A report
+without those lines was written before they existed and covers nothing.
+
- **Any `UNRESOLVED`** — check this FIRST; it disqualifies every option
- below. One of the two globs matched no file, so that whole document class
- was never examined and the comparison covered less than it appears to.
- Say which pattern came back unresolved and stop: an ADR or GDD directory
- that is empty, renamed or misspelled is a finding about the project, not a
- reason to stand on a prior report. Never read a set of `UNCHANGED` lines as
+ below. A glob matched no file, so that whole document class was never
+ examined and the comparison covered less than it appears to. Say which
+ pattern came back unresolved, and neither stand on the prior report nor
+ scope a re-run from it: an ADR or GDD directory that is empty, renamed or
+ misspelled is a finding about the project. Run the review as asked; its
+ verdict is NOT ASSESSED for the missing class (Phase 7), never a stop with
+ no report. Never read a set of `UNCHANGED` lines as
"everything is current" while an `UNRESOLVED` line is present — the set
compared was not the set requested.
-- **Everything `UNCHANGED`** (and no `UNRESOLVED`) — nothing this review
- reads has changed since that report; re-running reproduces it. Surface the
- prior report's date and verdict and offer via `AskUserQuestion`: `[A] Stand
- on the prior report (Recommended)` / `[B] Re-run the full review anyway` —
- `guided` proceeds with [A] and notes it; `autonomous` logs via
- `log_decision` and stands on the prior report.
-- **Some `CHANGED`/`NEW`** — name them, then scope instead of re-running
- everything: recommend `/architecture-review [system]` (single-system mode)
- for just the changed systems. A full re-run stays available on request,
- and structural changes (a `NEW` ADR, a deleted file) warrant one.
+- **The prior report does not cover this run** — check this second, whatever
+ the other lines say. Say why: *"The last report was a [mode] review at
+ workflow [tier]; it does not cover this run."* Run the review as asked.
+ Never offer to stand on it or to scope a re-run from it.
+- **Everything `UNCHANGED`** — nothing this review reads has changed since
+ that report; re-running reproduces it. Surface the prior report's date,
+ mode and verdict and offer via `AskUserQuestion`: `[A] Stand on the prior
+ report (Recommended)` / `[B] Re-run the full review anyway` — `guided`
+ proceeds with [A] and notes it; `autonomous` logs via `log_decision` and
+ stands on the prior report.
+- **Only GDDs or ADRs `CHANGED`/`NEW`** — name them, then scope instead of
+ re-running everything: recommend `/architecture-review single-gdd [path]`
+ for just the changed systems. A full re-run stays available on request, and
+ a `NEW` ADR warrants one.
+- **Anything else `CHANGED`, `NEW` or `GONE`** — a deleted GDD or ADR, the TR
+ registry, `architecture.md`, the engine reference, `project.yaml`,
+ `technical-preferences.md`, `consistency-failures.md`, or this skill's own
+ files. These reach every phase, so recommend re-running the review as
+ asked, never a `single-gdd` scope, and name each input with what it
+ affects — e.g. *"The engine reference changed after the
+ last report: its deprecated-API audit, which `/gate-check` reads, was made
+ against the old one."*
- **`RECEIPT: NONE`** — no prior report, or one written before receipts
existed. Proceed with the full review; this run's report will carry the
first stamps.
diff --git a/.claude/skills/architecture-review/references/2-extract-requirements.md b/.claude/skills/architecture-review/references/2-extract-requirements.md
index cb929aca..d08ea0b0 100644
--- a/.claude/skills/architecture-review/references/2-extract-requirements.md
+++ b/.claude/skills/architecture-review/references/2-extract-requirements.md
@@ -11,14 +11,25 @@ Before extracting any requirements, read `docs/architecture/tr-registry.yaml`
if it exists. Index existing entries by `id` and by normalized `requirement`
text (lowercase, trimmed). This prevents ID renumbering across review runs.
+Then read the Technical Requirements Baseline in `docs/architecture/architecture.md`
+if it exists. `/create-architecture` numbers each requirement the registry did not
+hold as `(provisional)`, from the registry's next free ID, and ADRs written from
+the baseline may already cite those IDs.
+
For each requirement you extract, the matching rule is:
1. **Exact/near match** to an existing registry entry for the same system →
reuse that entry's TR-ID unchanged. Update the `requirement` text in the
registry only if the GDD wording changed (same intent, clearer phrasing) —
add a `revised: [date]` field.
-2. **No match** → assign a new ID: next available `TR-[system]-NNN` for that
- system, starting from the highest existing sequence + 1.
-3. **Ambiguous** (partial match, intent unclear) → ask the user:
+2. **Match to a provisional baseline row** (same system, same intent) → keep that
+ ID when the registry holds no entry with it, active or retired: registering it
+ is what makes it permanent. When the ID is taken, assign the next available one
+ and list the rename (`TR-[system]-004 (provisional) → TR-[system]-006`) in the
+ report, so the ADRs and stories that cite it can be updated.
+3. **No match** → assign a new ID: next available `TR-[system]-NNN` for that
+ system, starting from the highest existing sequence + 1, skipping any ID a
+ provisional baseline row holds.
+4. **Ambiguous** (partial match, intent unclear) → ask the user:
> "Does '[new requirement text]' refer to the same requirement as
> `TR-[system]-NNN: [existing text]'`, or is it a new requirement?"
User answers: "Same requirement" (reuse ID) or "New requirement" (new ID).
diff --git a/.claude/skills/architecture-review/references/4-conflicts.md b/.claude/skills/architecture-review/references/4-conflicts.md
index 11e356f4..0d30f817 100644
--- a/.claude/skills/architecture-review/references/4-conflicts.md
+++ b/.claude/skills/architecture-review/references/4-conflicts.md
@@ -43,19 +43,24 @@ After conflict detection, analyse the dependency graph across all ADRs.
Bash: bash .claude/scripts/adr-dep-graph.sh
```
-It collects every `Depends On` edge, runs Kahn's algorithm, and emits
-`ADRS:` / `EDGES:` / `NO_DEPS_SECTION:` / `CYCLE:`. A model tracing A→B→C→A across
+It collects every `Depends On` edge, finds the cycles and the order, and emits
+`ADRS:` / `EDGES:` / `NO_DEPS_SECTION:` / `UNFILLED_DEPS:` / `CYCLE:` /
+`BLOCKED_BY_CYCLE:` / `ORDER:`. A model tracing A→B→C→A across
a dozen ADRs eventually misses an edge; the algorithm cannot. It reports
observations, not a verdict — you apply the meaning below.
-**`NO_DEPS_SECTION` is load-bearing**: it makes "no cycles because the graph is
-clean" distinguishable from "no cycles because half the ADRs declare no
-dependencies". Report the second case as a structural gap, never as a clean graph.
+**`NO_DEPS_SECTION` and `UNFILLED_DEPS` are load-bearing**: they make "no cycles
+because the graph is clean" distinguishable from "no cycles because half the ADRs
+declare no dependencies, or left the template's placeholder in the row". Report
+the second case as a structural gap, never as a clean graph, and name each
+`UNFILLED_DEPS` ADR as unfilled: what it depends on is unknown, not none.
Then interpret:
-1. **Topological sort**: the emitted order — ADRs with no
+1. **Topological sort**: the `ORDER:` row, as emitted — ADRs with no
dependencies come first (Foundation), ADRs that depend on those come next, etc.
+ Do not re-sort it by hand. An ADR in `NO_DEPS_SECTION` or `UNFILLED_DEPS` sits
+ in it as if it depended on nothing: mark it so.
2. **Flag unresolved dependencies**: cross the `EDGES:` list against the `## Status`
values already scanned in Phase 1b. If ADR-A depends on an ADR that is still
`Proposed` or does not exist, flag it:
@@ -64,7 +69,10 @@ Then interpret:
ADR-0005 cannot be safely implemented until ADR-0002 is Accepted.
```
3. **Cycle detection**: every `CYCLE:` line the script emitted is a
- `DEPENDENCY CYCLE` — report each one. Do not re-derive them by hand:
+ `DEPENDENCY CYCLE` — report each one, with the edges its line shows (one of
+ them is the edge to cut). A `BLOCKED_BY_CYCLE:` ADR is on no cycle: it waits
+ for one to break, so list it as blocked, never as part of the cycle, and never
+ suggest cutting its own edges. Do not re-derive them by hand:
```
🔴 DEPENDENCY CYCLE: ADR-0003 → ADR-0006 → ADR-0003
This cycle must be broken before either can be implemented.
diff --git a/.claude/skills/architecture-review/references/6-document-coverage.md b/.claude/skills/architecture-review/references/6-document-coverage.md
index a3e25a35..dcce7848 100644
--- a/.claude/skills/architecture-review/references/6-document-coverage.md
+++ b/.claude/skills/architecture-review/references/6-document-coverage.md
@@ -7,12 +7,9 @@
**If `docs/architecture/architecture.md` does not exist, say so in the report** —
`Architecture document coverage: NOT ASSESSED — no docs/architecture/architecture.md`
-— and carry it into the Phase 7 verdict per the trigger list below. Phase 5
-already models this for the engine consultation (*"A skipped check that says
-nothing is indistinguishable from a check that passed"*); this phase is the one
-that did not. Silently producing no Phase 6 findings reads as an architecture
-document that was checked and found clean, which is the opposite of what
-happened.
+— and carry it into the Phase 7 verdict per the trigger list below. Silently
+producing no Phase 6 findings reads as an architecture document that was checked
+and found clean, which is the opposite of what happened.
If it exists, validate it against GDDs:
diff --git a/.claude/skills/architecture-review/references/7-report.md b/.claude/skills/architecture-review/references/7-report.md
index 41fab541..a007fd66 100644
--- a/.claude/skills/architecture-review/references/7-report.md
+++ b/.claude/skills/architecture-review/references/7-report.md
@@ -8,13 +8,15 @@
```
## Architecture Review Report
Date: [date]
-Engine: [name + version]
+Mode: [full / coverage / consistency / engine / single-gdd path/to/gdd.md]
+Workflow: [the resolved workflow tier]
+Engine: [name + version, or "none configured"]
GDDs Reviewed: [N]
ADRs Reviewed: [M]
-[output of: Bash: bash .claude/scripts/review-receipts.sh hash docs/architecture/adr-*.md design/gdd/*.md
- — one Reviewed-Content-Hash line per file reviewed; Phase 1a's freshness
- check reads these on the next run to skip or scope an unchanged re-review]
+[the receipt — one Reviewed-Content-Hash line per review input, taken in
+ Phase 8 when the report is written, never in this draft. Phase 1a's freshness
+ check reads them, with the Mode and Workflow lines, on the next run]
---
diff --git a/.claude/skills/architecture-review/references/8-write.md b/.claude/skills/architecture-review/references/8-write.md
index ee5c4bbf..bf6d8946 100644
--- a/.claude/skills/architecture-review/references/8-write.md
+++ b/.claude/skills/architecture-review/references/8-write.md
@@ -7,6 +7,7 @@
**In this file:**
+- The receipt is taken last
- RTM Output (rtm mode only)
- TR Registry Update
- Reflexion Log Update
@@ -18,11 +19,38 @@ Use `AskUserQuestion` for the write approval:
- [B] Write review report only — `docs/architecture/architecture-review-[date].md`
- [C] Don't write anything yet — I need to review the findings first
+**A `single-gdd` run saw one system**, so in that mode [A] writes the review
+report and only that system's share of the other two files. Name it so in the
+option: "…update [system]'s rows in the traceability index and its TR registry
+entries". In `requirements-traceability.md`, replace that system's matrix rows
+and recompute the Coverage Summary, keeping every other system's rows as they
+are. When the index does not exist yet, write the report and the registry only,
+and say a full review creates the index. In the TR registry, append, update and
+deprecate only that system's entries: another system's GDD was not read, so its
+entries are never proposed for deprecation.
+
When Phase 4 found a 🔴 conflict and `docs/consistency-failures.md` exists, name
that file in option [A] as well — "…and append [N] conflict entr(y/ies) to
`docs/consistency-failures.md`". Only [A] appends there (see Reflexion Log
Update); [B] writes the report and nothing else.
+### The receipt is taken last
+
+Write the review report after the TR registry update and the
+`consistency-failures.md` entries, and take its receipt lines at that moment —
+never from the Phase 7 draft. Both files are review inputs: a receipt taken
+before this run edited them records the old content, and the next run reads
+this run's own edit as `CHANGED`.
+
+```
+Bash: bash .claude/scripts/review-receipts.sh hash docs/architecture/adr-*.md design/gdd/*.md docs/architecture/tr-registry.yaml docs/architecture/architecture.md docs/engine-reference/[engine]/*.md docs/engine-reference/[engine]/modules/*.md project.yaml .claude/docs/technical-preferences.md docs/consistency-failures.md .claude/skills/architecture-review/SKILL.md .claude/skills/architecture-review/references/*.md
+```
+
+It is the same list as Phase 1a's check, with `[engine]` filled in the same way.
+An optional input that does not exist prints `not stamped, no such file` and is
+left out; that is expected. Paste the stamp lines into the report under its
+header, where the Phase 7 template shows them.
+
### RTM Output (rtm mode only)
For `rtm` mode, use `AskUserQuestion`:
@@ -99,13 +127,21 @@ and keep every entry already in it. Then:
- **Update** `requirement` text and `revised` date for any entries whose GDD
wording changed (ID stays the same)
- **Mark** `status: deprecated` for any registry entries whose GDD requirement
- no longer exists (confirm with user before marking deprecated)
+ no longer exists (confirm with user before marking deprecated; in `single-gdd`
+ mode, only the reviewed system's entries)
- **Mark** `status: "superseded-by: TR-[system]-NNN"` for an entry whose
requirement was split or replaced, naming the new TR-ID(s). Keep the quotes:
unquoted, the second colon makes the file invalid YAML
- **Never** renumber or delete existing entries
- Update the `last_updated` and `version` fields at the top
+After writing, run `bash .claude/scripts/registry.sh validate` and fix every row
+about an entry this write added or changed (a DUPLICATE, STATUS or LAYOUT row,
+or a PATH_MISSING row for a path it named) before you go on; name rows about
+other entries to the user rather than fixing them unasked. If the script is
+missing or prints nothing, say the registry check did not run, then re-read the
+entries you wrote against the rules in the file's header.
+
This ensures all future story files can reference stable TR-IDs that persist
across every subsequent architecture review.
@@ -113,7 +149,7 @@ across every subsequent architecture review.
When the user chose Phase 8's [A] — the option that named this file — append
any 🔴 CONFLICT entries found in Phase 4 to `docs/consistency-failures.md` (if
-the file exists), after writing the review report:
+the file exists), before writing the review report (its receipt is taken last):
```markdown
### [YYYY-MM-DD] — /architecture-review — 🔴 CONFLICT
diff --git a/.claude/skills/art-bible/SKILL.md b/.claude/skills/art-bible/SKILL.md
index 8776e8bb..dca9084a 100644
--- a/.claude/skills/art-bible/SKILL.md
+++ b/.claude/skills/art-bible/SKILL.md
@@ -40,7 +40,9 @@ rationale per choice. Apply it to every section you author.
- `minimal` — not required. Can still be run voluntarily.
Read `design/gdd/game-concept.md` — or `design/game-brief.md`, the one-page brief
-that replaces it at `rigor: minimal`. If neither exists, fail with:
+that replaces it at `rigor: minimal`. Read it by section: find the headings you need
+with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset
+and limit. If neither exists, fail with:
> "No game concept found. Run `/brainstorm` first — the art bible is authored after the game concept is approved."
Extract from game-concept.md (from the brief: working title, pitch, "Who it's for /
@@ -151,9 +153,9 @@ These four sections define the core visual language. **All other sections flow f
> else can build on it. Sections 2–4 are then delegated in **one** `art-director`
> call, not three: they are the same agent receiving the same inputs (Visual
> Identity Statement + pillars), and mood, shape and colour are interdependent —
-> an art director defines them together, not in isolation. Three separate calls
-> re-sent the same context three times and asked the agent to reason about
-> colour without knowing the shape language it had just written.
+> an art director defines them together, not in isolation. Separate calls would
+> ask the agent to reason about colour without knowing the shape language it
+> had just written.
>
> **This is not reduced specialist involvement** — every section is still
> authored by the specialist, which is the point `.claude/docs/effects-map.md`
@@ -245,10 +247,9 @@ These sections translate the visual identity into concrete production rules. The
### Section 5: Character Design Direction
**Agent delegation for Sections 5–6 — one call, issued here.** Both sections
-were separate spawns of the **same agent with the same input** (`sections 1–4`),
-which is pure duplication: the second call re-sent the whole visual identity to
-an agent that had just been given it. Spawn `art-director` once with sections
-1–4 and ask for both:
+need the **same agent with the same input** (`sections 1–4`), so a second call
+would only re-send the whole visual identity. Spawn `art-director` once with
+sections 1–4 and ask for both:
1. **Character design direction** — "Cover: visual archetype for the player character (if any), distinguishing feature rules per character type (how do players tell enemies/NPCs/allies apart at a glance?), expression/pose style targets (stiff/expressive/realistic/exaggerated), and LOD philosophy (how much detail is preserved at game camera distance?)."
2. **Environment design language** — "Cover: architectural style and its relationship to the world's culture/history, texture philosophy (painted vs. PBR vs. stylized — why this choice for this game?), prop density rules (sparse/dense — what drives the choice per area type?), and environmental storytelling guidelines (what visual details should tell the story without text?)."
diff --git a/.claude/skills/asset-audit/SKILL.md b/.claude/skills/asset-audit/SKILL.md
index 840ffc53..94494e0e 100644
--- a/.claude/skills/asset-audit/SKILL.md
+++ b/.claude/skills/asset-audit/SKILL.md
@@ -61,7 +61,9 @@ the two happened — a reader cannot tell from a green result.
Read the art bible's Asset Standards section (`design/art/art-bible.md`) and any
asset standards in the relevant design docs — size budgets and format rules come
from there. The naming patterns are the ones in Phase 3 below, unless the art
-bible states its own.
+bible states its own. Read the art bible by section: find the heading with
+the Grep tool (pattern `^#`, content mode) and Read that range with offset
+and limit.
If neither states a size budget — or there is no art bible — the Size section is
`NOT ASSESSED — no size budget set`, and the report names `/art-bible`, whose
diff --git a/.claude/skills/asset-spec/SKILL.md b/.claude/skills/asset-spec/SKILL.md
index 946dbabd..5bf55732 100644
--- a/.claude/skills/asset-spec/SKILL.md
+++ b/.claude/skills/asset-spec/SKILL.md
@@ -37,7 +37,9 @@ This flow produces `design/assets/entity-inventory.md` — the master list of ev
the game needs visually. Run once before asset spec work begins.
### Step 1 — Gather from docs
-Read all available source material in parallel:
+Read all available source material in parallel, each doc by section: find the
+headings you need with the Grep tool (pattern `^#`, content mode) and Read those
+ranges with offset and limit.
- `design/gdd/systems-index.md` — extract every system listed
- GDD asset content — do **not** full-read every GDD. The two wanted sections are
standard headings, and named entities live in the registry:
@@ -148,7 +150,9 @@ run only.
## Phase 1: Gather Context
-Read all source material **before** asking the user anything.
+Read all source material **before** asking the user anything. Read the art bible and
+the GDD by section: find the headings you need with the Grep tool (pattern `^#`,
+content mode) and Read those ranges with offset and limit.
### Required reads:
- **Art bible**: Read `design/art/art-bible.md` — fail if missing:
diff --git a/.claude/skills/balance-check/SKILL.md b/.claude/skills/balance-check/SKILL.md
index f15ea62a..90956452 100644
--- a/.claude/skills/balance-check/SKILL.md
+++ b/.claude/skills/balance-check/SKILL.md
@@ -84,7 +84,9 @@ populates it), skip this and use the GDD alone.
Then read the GDD for the system from `design/gdd/` to understand intended design
targets, tuning knobs, and expected value ranges — for anything the registry did
-not already supply. This is the baseline for "correct" behaviour.
+not already supply. This is the baseline for "correct" behaviour. Read it by section:
+find the headings you need with the Grep tool (pattern `^#`, content mode) and
+Read those ranges with offset and limit.
If the data files are FOUND but neither source gives targets for this domain,
the sections that judge against targets (Outliers Detected, and Progression
@@ -186,6 +188,11 @@ After presenting the report, use `AskUserQuestion`:
- `[B] Save report to design/balance/balance-check-[system]-[date].md`
- `[C] Stop here — I'll review the findings manually`
+**Run as a subagent?** `game-designer` preloads this skill, and a subagent has
+no `AskUserQuestion`. End your reply with the question and these three options
+as a short list, and stop: whoever called you asks the user and passes the
+answer back.
+
If [A]:
- Ask which issue to address first (refer to the Recommendations table by priority row)
- Guide the user to update the relevant data file in `assets/data/` or formula in `design/balance/`
diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md
index 90c3d197..8b28bfc2 100644
--- a/.claude/skills/brainstorm/SKILL.md
+++ b/.claude/skills/brainstorm/SKILL.md
@@ -1,6 +1,6 @@
---
name: brainstorm
-description: "Guided concept ideation using professional studio techniques, player psychology, creative exploration."
+description: "Guides the user through finding and choosing a game concept. Use when the user wants game ideas, a new concept, a game jam idea, or to explore other directions, including dropping the current idea and starting over."
argument-hint: "[genre or theme hint, or 'open'] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, WebSearch, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/brainstorm/../../hooks/yaml-helper.sh" resolve_config *)
@@ -9,465 +9,74 @@ model: sonnet
!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,docs.density,workflow`
-Resolved above — use as-is. No block → defaults in
-`.claude/docs/config-resolution.md`.
+Resolved above; use as-is. No block → the defaults in `.claude/docs/config-resolution.md`
+(`workflow: minimal`, `review_mode: solo`, `automation: collaborative`, `docs.density: terse`), and
+say that the settings were not read.
# Brainstorm
-
-`--review` overrides `review_mode`; store it for all gate spawns this run. See
-`.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.
-
-Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
-(collaborative asks always · guided major-only · autonomous logs and proceeds;
-`automation_always_ask` categories always prompt).
-
-**`docs.density`** — it controls per-section *depth*, where `workflow`
-controls which sections exist. `modes.rigor` sets both together; set
-`docs.density` explicitly to vary depth alone: `terse` (the default, via `rigor: minimal`) = pillar bullets + concept bullets;
-`balanced` = pillars + concept with brief rationale (`rigor: standard`); `thorough` =
-pillars + concept + extensive rationale + alternatives. Apply it to every section
-you author.
-
----
-
-## Tier branch — check `workflow` FIRST
-
-The `workflow` tier resolved above governs this skill's output:
-
-- **`standard` / `full`** → run the full flow ("When this skill is invoked" through
- Phase 5 and the concept-document generation). No change.
-- **`minimal`** → run the **Lean Brief flow** immediately below and **STOP** — skip
- Phases 1–5, the director gates (CD-PILLARS / AD-CONCEPT-VISUAL / TD-FEASIBILITY /
- PR-SCOPE), and the full-length concept document entirely. Output is the one-page
- `design/game-brief.md`, not `game-concept.md`.
-
-### Lean Brief flow (`workflow: minimal` only)
-
-A jam / small-scope session: capture the load-bearing thinking in one page, then get
-to code. Keep prompting light — a few exchanges, not fifteen. Author from the
-one-page template `.claude/docs/templates/game-brief.md` (6 required fields + 3
-one-liners). If `design/game-brief.md` already exists, read it and resume/refine
-rather than restart.
-
-1. **Concept** — from the argument hint (or one quick open question if none), propose
- **2–3 one-line concepts** (verb-first or mashup, per Phase 2's techniques). One
- `AskUserQuestion` to pick or combine — the only guaranteed creative prompt.
-2. **Fill the brief fields** conversationally (not one prompt each):
- - **One-sentence pitch** — the excited one-liner.
- - **Core loop** — the 2–4 step cycle the player repeats.
- - **Player goal & fail state** — what the player is trying to do, and how they
- lose or fail. `/create-stories` turns it into each story's acceptance criteria.
- - **MVP** — the ruthlessly short feature list that makes it *the game* (each becomes
- a story downstream). If it runs past ~7, push back on scope.
- - **Out of scope** — what they're deliberately NOT building.
- - **Build order** — sequence to build the MVP, risky / core-fun thing first.
- - **Who it's for / what they feel**, **Art & audio direction** and **Reference
- game** (the shipped game it is closest to, and the ~10% of it the MVP keeps) —
- one line each (offer, don't force).
- Present the filled brief back in full for a single confirmation.
-3. **Write approval** — `AskUserQuestion`: "Brief is ready. May I write it to
- `design/game-brief.md`?" → `[A] Yes — write it` / `[B] Revise a field first`. On
- [B], revise the named field, show before/after, re-ask; repeat until [A]. Then
- write `design/game-brief.md` from the template, creating directories as needed.
- Honor `modes.automation` for this write as elsewhere in the framework.
-4. **Next steps** (short — this is the point). **Read `engine.name` from
- `project.yaml` first and list `/setup-engine` only if it is absent or empty:**
- 1. *(only when `engine.name` is absent or empty)* "`/setup-engine` — configure
- the engine (required before code)"
- 2. "`/create-stories` — turn the brief's MVP list into implementable stories. The
- epic is implicit at `minimal`; there is no separate `/create-epics` or
- `/sprint-plan` — the brief's build order is the plan."
- 3. "`/dev-story` — first line of game code"
-
- > **Why the condition.** `/start`'s `minimal` path runs `/setup-engine`
- > *before* `/brainstorm`, and `/setup-engine` Section 2 states that a missing
- > brief is expected because the brief is authored afterwards. Listing engine
- > setup unconditionally here tells a user who just followed that path to go
- > back and redo step one — the only skill in the four-step path that assumes
- > it runs first.
- Then output a one-line summary (pitch + MVP feature count + `design/game-brief.md`).
-
-Verdict: **COMPLETE** — game brief created; next stop is code. Do NOT run Phases 1–5,
-spawn any director gate, or write `game-concept.md` at this tier.
-
----
-
-When this skill is invoked (`standard` / `full` tier — `minimal` uses the Lean Brief
-flow above):
-
-1. **Parse the argument** for an optional genre/theme hint (e.g., `roguelike`,
- `space survival`, `cozy farming`). If `open` or no argument, start from
- scratch.
-
-2. **Check for existing concept work**:
- - Read `design/gdd/game-concept.md` if it exists (resume, don't restart)
- - Read `design/gdd/game-pillars.md` if it exists (build on established pillars)
-
-3. **Run through ideation phases** interactively, asking the user questions at
- each phase. Do NOT generate everything silently — the goal is **collaborative
- exploration** where the AI acts as a creative facilitator, not a replacement
- for the human's vision.
-
- **Use `AskUserQuestion`** at key decision points throughout brainstorming:
- - Constrained taste questions (genre preferences, scope, team size)
- - Concept selection ("Which 2-3 concepts resonate?") after presenting options
- - Direction choices ("Develop further, explore more, or prototype?")
- - Pillar ranking after concepts are refined
- Write full creative analysis in conversation text first, then use
- `AskUserQuestion` to capture the decision with concise labels.
-
- Professional studio brainstorming principles to follow:
- - Withhold judgment — no idea is bad during exploration
- - Encourage unusual ideas — outside-the-box thinking sparks better concepts
- - Build on each other — "yes, and..." responses, not "but..."
- - Use constraints as creative fuel — limitations often produce the best ideas
- - Time-box each phase — keep momentum, don't over-deliberate early
-
----
-
-### Phase 1: Creative Discovery
-
-Start by understanding the person, not the game. Ask these questions
-conversationally (not as a checklist):
-
-**Emotional anchors**:
-- What's a moment in a game that genuinely moved you, thrilled you, or made
- you lose track of time? What specifically created that feeling?
-- Is there a fantasy or power trip you've always wanted in a game but never
- quite found?
-
-**Taste profile**:
-- What 3 games have you spent the most time with? What kept you coming back?
- *(Ask this as plain text — the user must be able to type specific game names freely.
- Do NOT put this in an AskUserQuestion with preset options.)*
-- Are there genres you love? Genres you avoid? Why?
-- Do you prefer games that challenge you, relax you, tell you stories,
- or let you express yourself? *(Use `AskUserQuestion` for this — constrained choice.)*
-
-**Practical constraints** (shape the sandbox before brainstorming).
-Bundle these into a single multi-tab `AskUserQuestion` with these exact tab labels:
-- Tab "Experience" — "What kind of experience do you most want players to have?" (Challenge & Mastery / Story & Discovery / Expression & Creativity / Relaxation & Flow)
-- Tab "Timeline" — "What's your realistic development timeline?" (Weeks / Months / 1-2 years / Multi-year)
-- Tab "Dev level" — "Where are you in your dev journey?" (First game / Shipped before / Professional background)
-
-Use exactly these tab names — do not rename or duplicate them.
-
-**Synthesize** the answers into a **Creative Brief** — a 3-5 sentence
-summary of the person's emotional goals, taste profile, and constraints.
-Read the brief back and confirm it captures their intent.
-
----
-
-### Phase 2: Concept Generation
-
-Using the creative brief as a foundation, generate **3 distinct concepts**
-that each take a different creative direction. Use these ideation techniques:
-
-**Technique 1: Verb-First Design**
-Start with the core player verb (build, fight, explore, solve, survive,
-create, manage, discover) and build outward from there. The verb IS the game.
-
-**Technique 2: Mashup Method**
-Combine two unexpected elements: [Genre A] + [Theme B]. The tension between
-the two creates the unique hook. (e.g., "farming sim + cosmic horror",
-"roguelike + dating sim", "city builder + real-time combat")
-
-**Technique 3: Experience-First Design (MDA Backward)**
-Start from the desired player emotion (aesthetic goal from MDA framework:
-sensation, fantasy, narrative, challenge, fellowship, discovery, expression,
-submission) and work backward to the dynamics and mechanics that produce it.
-
-For each concept, present:
-- **Working Title**
-- **Elevator Pitch** (1-2 sentences — must pass the "10-second test")
-- **Core Verb** (the single most common player action)
-- **Core Fantasy** (the emotional promise)
-- **Unique Hook** (passes the "and also" test: "Like X, AND ALSO Y")
-- **Primary MDA Aesthetic** (which emotion dominates?)
-- **Estimated Scope** (small / medium / large)
-- **Why It Could Work** (1 sentence on market/audience fit)
-- **Biggest Risk** (1 sentence on the hardest unanswered question)
-
-Present all three. Then use `AskUserQuestion` to capture the selection.
-
-**This decision asks regardless of `modes.automation`.** Concept selection
-is the creative heart of `/brainstorm` and has no defensible autonomous
-default — there is no algorithmic way to pick which creative direction
-resonates with the user. Per `.claude/docs/automation-modes.md`, treat
-this site as exempt (it overrides the mode the same way
-`automation_always_ask` categories do).
-
-**CRITICAL**: This MUST be a plain list call — no tabs, no form fields. Use exactly this structure:
-
-```
-AskUserQuestion(
- prompt: "Which concept resonates with you? You can pick one, combine elements, or ask for fresh directions.",
- options: [
- "Concept 1 — [Title]",
- "Concept 2 — [Title]",
- "Concept 3 — [Title]",
- "Combine elements across concepts",
- "Generate fresh directions"
- ]
-)
-```
-
-Do NOT use a `tabs` field here. The `tabs` form is for multi-field input only — using it here causes an "Invalid tool parameters" error. This is a plain `prompt` + `options` call.
-
-Never pressure toward a choice — let them sit with it.
-
----
-
-### Phase 3: Core Loop Design
-
-For the chosen concept, use structured questioning to build the core loop.
-The core loop is the beating heart of the game — if it isn't fun in
-isolation, no amount of content or polish will save the game.
-
-**30-Second Loop** (moment-to-moment):
-
-Ask these as `AskUserQuestion` calls — derive the options from the chosen concept, don't hardcode them:
-
-1. **Core action feel** — prompt: "What's the primary feel of the core action?" Generate 3-4 options that fit the concept's genre and tone, plus a free-text escape (`I'll describe it`).
-
-2. **Key design dimension** — identify the most important design variable for this specific concept (e.g., world reactivity, pacing, player agency) and ask about it. Generate options that match the concept. Always include a free-text escape.
-
-After capturing answers, analyze: Is this action intrinsically satisfying? What makes it feel good? (Audio feedback, visual juice, timing satisfaction, tactical depth?)
-
-**5-Minute Loop** (short-term goals):
-- What structures the moment-to-moment play into cycles?
-- Where does "one more turn" / "one more run" psychology kick in?
-- What choices does the player make at this level?
-
-**Session Loop** (30-120 minutes):
-- What does a complete session look like?
-- Where are the natural stopping points?
-- What's the "hook" that makes them think about the game when not playing?
-
-**Progression Loop** (days/weeks):
-- How does the player grow? (Power? Knowledge? Options? Story?)
-- What's the long-term goal? When is the game "done"?
-
-**Player Motivation Analysis** (based on Self-Determination Theory):
-- **Autonomy**: How much meaningful choice does the player have?
-- **Competence**: How does the player feel their skill growing?
-- **Relatedness**: How does the player feel connected (to characters,
- other players, or the world)?
-
----
-
-### Phase 4: Pillars and Boundaries
-
-Game pillars are used by real AAA studios (God of War, Hades, The Last of
-Us) to keep hundreds of team members making decisions that all point the
-same direction. Even for solo developers, pillars prevent scope creep and
-keep the vision sharp.
-
-Collaboratively define **3-5 pillars**:
-- Each pillar has a **name** and **one-sentence definition**
-- Each pillar has a **design test**: "If we're debating between X and Y,
- this pillar says we choose __"
-- Pillars should feel like they create tension with each other — if all
- pillars point the same way, they're not doing enough work
-
-Then define **3+ anti-pillars** (what this game is NOT):
-- Anti-pillars prevent the most common form of scope creep: "wouldn't it
- be cool if..." features that don't serve the core vision
-- Frame as: "We will NOT do [thing] because it would compromise [pillar]"
-
-**Pillar confirmation**: After presenting the full pillar set, use `AskUserQuestion`:
-- Prompt: "Do these pillars feel right for your game?"
-- Options: `[A] Lock these in` / `[B] Rename or reframe one` / `[C] Swap a pillar out` / `[D] Something else`
-
-If the user selects B, C, or D, make the revision, then use `AskUserQuestion` again:
-- Prompt: "Pillars updated. Ready to lock these in?"
-- Options: `[A] Lock these in` / `[B] Revise another pillar` / `[C] Something else`
-
-**At `collaborative`** — repeat until the user selects [A] Lock these in.
-**At `guided`** — pillars are a major decision, so ask once; apply the chosen
-revision and lock them in without a second confirmation round.
-**At `autonomous`** — do not ask. Lock in the drafted pillars and record them via
-`log_decision` with the alternatives considered.
-
-> An `autonomous` run never issues the question, so "repeat until [A]" has no
-> exit condition (`automation-modes.md:56`).
-
-**Review mode check** — apply before spawning CD-PILLARS and AD-CONCEPT-VISUAL:
-- `solo` → skip both. Note: "CD-PILLARS skipped — Solo mode. AD-CONCEPT-VISUAL skipped — Solo mode." Proceed to Phase 5.
-- `lean` → skip both (not PHASE-GATEs). Note: "CD-PILLARS skipped — Lean mode. AD-CONCEPT-VISUAL skipped — Lean mode." Proceed to Phase 5.
-- `full` → spawn as normal.
-
-**After pillars and anti-pillars are agreed, spawn BOTH `creative-director` AND `art-director` via `Agent` in parallel before moving to Phase 5. Issue both `Agent` calls simultaneously — do not wait for one before starting the other.**
-
-- **`creative-director`** — gate **CD-PILLARS** (`.claude/docs/director-gates/cd-pillars.md`)
- Pass: full pillar set with design tests, anti-pillars, core fantasy, unique hook.
-
-- **`art-director`** — gate **AD-CONCEPT-VISUAL** (`.claude/docs/director-gates/ad-concept-visual.md`)
- Pass: game concept elevator pitch, full pillar set with design tests, target platform (if known), any reference games or visual touchstones the user mentioned.
-
-Collect both verdicts. When CD-PILLARS returns APPROVE, present them together using a two-tab `AskUserQuestion`:
-- Tab **"Pillars"**: present creative-director feedback. Options mirror the standard CD-PILLARS handling — `Lock in as-is` / `Revise [specific pillar]` / `Discuss further`.
-- Tab **"Visual anchor"**: present the art-director's 2-3 named visual direction options. Options: each named direction (one per option) + `Combine elements across directions` + `Describe my own direction`. On **STRONG**, mark the dominant direction `(Recommended)`. On **CONCERNS** (the pillars do not yet differentiate a visual identity), show the art-director's reason instead of directions and offer `Revise pillars` / `Describe my own direction`.
-
-The user's selected visual anchor (the named direction or their custom description) is stored as the **Visual Identity Anchor** — it will be written into the game-concept document and becomes the foundation of the art bible.
-
-If the creative-director returns CONCERNS or REJECT on pillars, resolve pillar issues before asking for the visual anchor selection — visual direction should flow from confirmed pillars. Ask the Pillars question on its own first (same options, no Visual anchor tab); once the pillars are resolved, ask the Visual anchor question on its own. **NOT ASSESSED** from either gate (it lacked an input — `.claude/docs/director-gates.md`) is not an approval: name what was missing, and supply it and re-run that gate; failing that, treat a CD-PILLARS NOT ASSESSED like CONCERNS, and with no art-director directions offer only `Describe my own direction`.
-
----
-
-### Phase 5: Player Type Validation
-
-Using the Bartle taxonomy and Quantic Foundry motivation model, validate
-who this game is actually for:
-
-- **Primary player type**: Who will LOVE this game? (Achievers, Explorers,
- Socializers, Competitors, Creators, Storytellers)
-- **Secondary appeal**: Who else might enjoy it?
-- **Who is this NOT for**: Being clear about who won't like this game is as
- important as knowing who will
-- **Market validation**: Are there successful games that serve a similar
- player type? What can we learn from their audience size?
-
----
-
-### Phase 6: Scope and Feasibility
-
-Ground the concept in reality:
-
-- **Target platform**: Use `AskUserQuestion` — "What platforms are you targeting for this game?"
- Options: `PC (Steam / Epic)` / `Mobile (iOS / Android)` / `Console` / `Web / Browser` / `Multiple platforms`
- Record the answer — it directly shapes the engine recommendation and will be passed to `/setup-engine`.
- Note platform implications if relevant (e.g., mobile means Unity is strongly preferred; console means Godot has limitations; web means Godot exports cleanly).
-
-- **Engine experience**: Use `AskUserQuestion` — "Do you already have an engine you work in?"
- Options: `Godot` / `Unity` / `Unreal Engine 5` / `No preference — help me decide`
- - **This decision always prompts regardless of `modes.automation` —
- including `autonomous` mode.** Engine choice is a project-wide
- architectural commitment that downstream tooling depends on and is
- effectively irreversible mid-project, so this skill guards it
- unconditionally (it is NOT left to the configurable
- `automation_always_ask` list). The model must NOT silently pick an engine.
- - If they pick an engine → record it as their preference and move on. Do NOT second-guess it.
- - If "No preference" → tell them: "Run `/setup-engine` after this session — it will walk you through the full decision based on your concept and platform target." Do not make a recommendation here.
-- **Art pipeline**: What's the art style and how labor-intensive is it?
-- **Content scope**: Estimate level/area count, item count, gameplay hours
-- **MVP definition**: What's the absolute minimum build that tests "is the
- core loop fun?"
-- **Biggest risks**: Technical risks, design risks, market risks
-- **Scope tiers**: What's the full vision vs. what ships if time runs out?
-
-**Review mode check** — apply before spawning TD-FEASIBILITY:
-- `solo` → skip. Note: "TD-FEASIBILITY skipped — Solo mode." Proceed directly to scope tier definition.
-- `lean` → skip (not a PHASE-GATE). Note: "TD-FEASIBILITY skipped — Lean mode." Proceed directly to scope tier definition.
-- `full` → spawn as normal.
-
-**After identifying biggest technical risks, spawn `technical-director` via `Agent` using gate TD-FEASIBILITY (`.claude/docs/director-gates/td-feasibility.md`) before scope tiers are defined.**
-
-Pass: core loop description, platform target, engine choice (or "undecided"), list of identified technical risks.
-
-Present the assessment to the user. If HIGH RISK, offer to revisit scope before finalising. If CONCERNS, note them and continue. If NOT ASSESSED, name the missing input and record feasibility as not assessed in the concept's risks — never as VIABLE.
-
-**Review mode check** — apply before spawning PR-SCOPE:
-- `solo` → skip. Note: "PR-SCOPE skipped — Solo mode." Proceed to document generation.
-- `lean` → skip (not a PHASE-GATE). Note: "PR-SCOPE skipped — Lean mode." Proceed to document generation.
-- `full` → spawn as normal.
-
-**After scope tiers are defined, spawn `producer` via `Agent` using gate PR-SCOPE (`.claude/docs/director-gates/pr-scope.md`).**
-
-Pass: full vision scope, MVP definition, the scope tiers (what ships if time runs out), timeline estimate, team size.
-
-Present the assessment to the user. PR-SCOPE answers REALISTIC / OPTIMISTIC /
-UNREALISTIC. If UNREALISTIC, ask via `AskUserQuestion` whether to adjust the MVP
-definition or scope tiers before writing the document or keep them — the user
-decides; the concept is never rejected for it. If OPTIMISTIC, show the
-producer's suggested adjustments and ask whether to apply them before writing. If NOT ASSESSED, name
-the missing input (a timeline or team size, say) and ask for it and re-run the
-gate, or record scope as not assessed — never as REALISTIC.
-
----
-
-4. **Generate the game concept document** using the template at
- `.claude/docs/templates/game-concept.md`. Fill in ALL sections from the
- brainstorm conversation, including the MDA analysis, player motivation
- profile, and flow state design sections.
-
- **Include a Visual Identity Anchor section** in the game concept document with:
- - The selected visual direction name
- - The one-line visual rule
- - The 2-3 supporting visual principles with their design tests
- - The color philosophy summary
-
- This section is the seed of the art bible — it captures the "everything must
- move" decision before it can be forgotten between sessions.
-
-5. Use `AskUserQuestion` for write approval:
-- Prompt: "Game concept is ready. May I write it to `design/gdd/game-concept.md`?"
-- Options: `[A] Yes — write it` / `[B] Not yet — revise a section first`
-
-If [B]: ask which section to revise using `AskUserQuestion` with options: `Elevator Pitch` / `Core Fantasy & Unique Hook` / `Pillars` / `Core Loop` / `MVP Definition` / `Scope Tiers` / `Risks` / `Something else — I'll describe`
-
-After revising, show the updated section as a diff or clear before/after, then use `AskUserQuestion` — "Ready to write the updated concept document?"
-Options: `[A] Yes — write it` / `[B] Revise another section`
-**At `collaborative`** — repeat until the user selects [A].
-**At `guided`** — ask once; apply the requested revision and write the document
-without a further confirmation round.
-**At `autonomous`** — do not ask; write the document and record the decision via
-`log_decision`.
-
-> Same exit-condition problem as the pillars loop above (`automation-modes.md:56`).
-
-If yes, generate the document using the template at `.claude/docs/templates/game-concept.md`, fill in ALL sections from the brainstorm conversation, and write the file, creating directories as needed.
-
-**Scope consistency rule**: The "Estimated Scope" field in the Core Identity table must match the full-vision timeline from the Scope Tiers section — not just say "Large (9+ months)". Write it as "Large (X–Y months, solo)" or "Large (X–Y months, team of N)" so the summary table is accurate.
-
-6. **Suggest next steps** (in this order — this is the professional studio
- pre-production pipeline). List ALL steps — do not abbreviate or truncate:
-
-**Path A — Design-First** (recommended if the concept is well-defined):
- 1. "Run `/setup-engine` to configure the engine and populate version-aware reference docs"
- 2. "Run `/art-bible` to create the visual identity specification — do this BEFORE writing GDDs. **The art bible is required before the Technical Setup gate.** It gates asset production and shapes technical architecture decisions (rendering, VFX, UI systems)."
- 3. "Use `/design-review design/gdd/game-concept.md` to validate concept completeness before going downstream"
- 4. "Discuss vision with the `creative-director` agent for pillar refinement"
- 5. "Decompose the concept into individual systems with `/map-systems` — maps dependencies, assigns priorities, and creates the systems index"
- 6. "Author per-system GDDs with `/design-system` — guided, section-by-section GDD writing for each system identified in step 5"
- 7. "Plan the technical architecture with `/create-architecture` — produces the master architecture blueprint and Required ADR list"
- 8. "Record key architectural decisions with `/architecture-decision (×N)` — write one ADR per decision in the Required ADR list from `/create-architecture`"
- 9. "Run `/architecture-review` — bootstraps the TR registry and Requirements Traceability Matrix from your GDDs and ADRs (required before the Pre-Production gate)"
- 10. "Validate readiness to advance with `/gate-check` — phase gate before committing to production"
-
-**Path B — Prototype-First** (use if the core mechanic is unproven or the concept needs validation):
- 1. "Run `/setup-engine` to configure the engine"
- 2. "Run `/prototype [core-mechanic]` — validate the core idea is fun before writing any GDDs (1–3 days throwaway code)"
- 3. "If prototype PROCEEDS: run `/art-bible`, then continue with Path A steps 5–10 above, using prototype learnings to inform your GDDs"
- 4. "If prototype PIVOTS: return to `/brainstorm` with the learnings and reshape the concept"
- 5. "After full design and architecture, build the `/vertical-slice` to validate production readiness before committing to sprints"
-
-7. **Output a summary** with the chosen concept's elevator pitch, pillars,
- primary player type, engine recommendation, biggest risk, and file path.
-
-Verdict: **COMPLETE** — game concept created and handed off for next steps.
-
----
-
-## Context Window Awareness
-
-This is a multi-phase skill. If context reaches or exceeds 70% during any phase,
-append this notice to the current response before continuing:
-
-> **Context is approaching the limit (≥70%).** The game concept document is saved
-> to `design/gdd/game-concept.md`. Open a fresh Claude Code session to continue
-> if needed — progress is not lost.
-
----
-
-## Recommended Next Steps
-
-After the game concept is written, follow the pre-production pipeline in order:
-1. `/setup-engine` — configure the engine and populate version-aware reference docs
-2. `/art-bible` — establish visual identity before writing any GDDs
-3. `/map-systems` — decompose the concept into individual systems with dependencies
-4. `/design-system [first-system]` — author per-system GDDs in dependency order
-5. `/create-architecture` — produce the master architecture blueprint
-6. `/architecture-review` — bootstrap TR registry and Requirements Traceability Matrix
-7. `/gate-check pre-production` — validate readiness for Pre-Production (the `systems-design` and `technical-setup` gates come first, at their own phase boundaries)
+Turns no idea, or a rough one, into a written design the next step builds from. How much it writes
+depends on `workflow`:
+
+- **`minimal`:** the Lean Brief flow below: a one-page `design/game-brief.md`, then stop. No
+ discovery questions, pillars, director gates or `game-concept.md`, and do not load
+ `references/full-concept.md`.
+- **`standard` or `full`:** read `references/full-concept.md` and follow it. It writes
+ `design/gdd/game-concept.md` from `.claude/docs/templates/game-concept.md`. Its gates follow
+ `.claude/docs/director-gates.md`; each director agent is given its own gate file,
+ `.claude/docs/director-gates/<gate-id in lower case>.md` (`cd-pillars.md`,
+ `ad-concept-visual.md`, `td-feasibility.md`, `pr-scope.md`), and you do not read those files
+ yourself.
+
+`--review` in the text typed after the skill name overrides `review_mode` for this run.
+`docs.density` sets each section's depth: `terse` = bullets; `balanced` = with brief rationale;
+`thorough` = rationale and alternatives. Questions follow `.claude/docs/automation-modes.md`
+(collaborative asks, guided asks only for major decisions, autonomous logs and proceeds; the
+always-ask categories always ask).
+
+Ask with the question tool. Without one, list the options numbered and end your turn to wait. The
+question is the last thing in the reply: no advice or lean after it. A skipped or dismissed
+question is not an answer: ask again in plain text.
+
+## Lean Brief flow (`workflow: minimal`)
+
+A few exchanges, not fifteen: capture the thinking that carries the game on one page, then get to
+code. Write from the template `.claude/docs/templates/game-brief.md` (six required fields, three
+one-liners). If `design/game-brief.md` exists, read it and refine it instead of starting over.
+
+1. **Concept.** From the hint typed after the skill name (or one quick open question if there is
+ none), propose **2 or 3 one-line concepts** (verb-first or a mashup of genre and theme), not
+ full concept cards. Ask the user to pick or combine them. This is the one creative question
+ every run asks.
+2. **Fill the brief** in conversation, several fields per exchange:
+ - **Working title:** the brief's title line. Offer one from the chosen concept and let the user
+ change it; `/create-stories` names the epic folder after it.
+ - **Pitch:** the excited one-liner.
+ - **Core loop:** the 2 to 4 steps the player repeats.
+ - **Player goal & fail state**: what the player tries to do, and how they lose.
+ `/create-stories` turns it into acceptance criteria.
+ - **MVP:** the short list that makes it the game; each item becomes a story. **More than 7
+ items: push back.** Say it is too long for an MVP, propose which items to cut (the ones the
+ core loop works without), and keep the brief to 7 or fewer.
+ - **Out of scope:** what they are deliberately not building (the cut items go here).
+ - **Build order:** the riskiest or least proven part first.
+ - **Who it's for and what they feel**, **Art & audio direction**, **Reference game** (the
+ closest shipped game, and the part of it the MVP keeps): one line each; offer, don't force.
+3. **Show the filled brief in full.** Then ask, as its own question: "Brief is ready. May I write it
+ to `design/game-brief.md`?" `Yes — write it` / `Revise a field first`. Write only on an explicit
+ yes to this question; agreeing to a cut or saying "go on" is not a yes to the write. On a
+ revision, change the named field, show it before and after, and ask again. Then write
+ `design/game-brief.md`, creating folders as needed. Never write `design/gdd/game-concept.md`
+ at this tier.
+4. **Next steps.** Read `engine.name` in `project.yaml`:
+ 1. `/setup-engine`: configure the engine. List it **only** when `engine.name` is absent or
+ empty: on the minimal path it usually ran before this skill.
+ 2. `/create-stories`: turn the MVP list into stories. At `minimal` there is no separate
+ `/create-epics` or `/sprint-plan`; the build order is the plan.
+ 3. `/dev-story`: the first line of game code.
+
+ Then one summary line: the pitch, the number of MVP items, and `design/game-brief.md`. End with
+ the line `Verdict: COMPLETE — game brief written; next stop is code.`
+
+If the user stops before the write, say the brief was not written, so it lives only in this
+conversation.
diff --git a/.claude/skills/brainstorm/references/full-concept.md b/.claude/skills/brainstorm/references/full-concept.md
new file mode 100644
index 00000000..4ceb496b
--- /dev/null
+++ b/.claude/skills/brainstorm/references/full-concept.md
@@ -0,0 +1,195 @@
+# Full concept flow (`workflow: standard` or `full`)
+
+**In this file:** start · Phase 1 Creative discovery · Phase 2 Concept generation · Phase 3 Core loop ·
+Phase 4 Pillars and boundaries · Phase 5 Player types · Phase 6 Scope and feasibility · Phase 7
+Write the concept · Phase 8 Next steps
+
+The output is `design/gdd/game-concept.md`, written from the game-concept template SKILL.md names.
+Ask at each phase; never generate the whole concept silently. You facilitate, the user decides.
+Write the analysis in your reply first, then ask with short option labels.
+
+## Start
+
+1. The text typed after the skill name may hold a genre or theme hint (`roguelike`, `cozy
+ farming`). `open` or nothing: start from scratch.
+2. If `design/gdd/game-concept.md` or `design/gdd/game-pillars.md` exists, read it by section (find
+ the headings with the Grep tool with pattern `^#` in content mode, then read those ranges)
+ and resume or build on it instead of restarting.
+
+## Phase 1: Creative discovery
+
+Start with the person, not the game. Ask conversationally:
+- A moment in a game that moved or thrilled them, and what created it.
+- A fantasy they have always wanted in a game and never found.
+- The three games they spent the most time with, and why. Ask this as plain text, never with
+ preset options: they must be able to type any game.
+- Genres they love or avoid. Then ask: challenge, relax, story or self-expression?
+
+Then ask these three questions together:
+- "What kind of experience do you most want players to have?" Challenge & Mastery / Story &
+ Discovery / Expression & Creativity / Relaxation & Flow
+- "What's your realistic development timeline?" Weeks / Months / 1-2 years / Multi-year
+- "Where are you in your dev journey?" First game / Shipped before / Professional background
+
+Sum the answers up as a **Creative Brief** of 3 to 5 sentences (emotional goals, taste,
+constraints), read it back and confirm it.
+
+## Phase 2: Concept generation
+
+Generate **three** distinct concepts from the brief, each in a different direction, using:
+- **Verb-first:** start from the core verb (build, fight, explore, solve, survive, manage).
+- **Mashup:** genre A + theme B; the tension is the hook ("farming sim + cosmic horror").
+- **Experience-first (MDA backward):** start from the aesthetic (sensation, fantasy, narrative,
+ challenge, fellowship, discovery, expression, submission) and work back to mechanics.
+
+Each concept has: Working Title · Elevator Pitch (1-2 sentences, passes the 10-second test) · Core
+Verb · Core Fantasy · Unique Hook ("like X, and also Y") · Primary MDA Aesthetic · Estimated Scope
+(small / medium / large) · Why It Could Work (one sentence) · Biggest Risk (one sentence).
+
+Present all three, then ask one question with these five options: "Which concept resonates with
+you? You can pick one, combine elements, or ask for fresh directions." `Concept 1 — [Title]` /
+`Concept 2 — [Title]` / `Concept 3 — [Title]` / `Combine elements across concepts` / `Generate
+fresh directions`. Ask it in every automation mode: no rule can pick the user's creative
+direction. Do not push toward a choice.
+
+## Phase 3: Core loop
+
+For the chosen concept, ask with options derived from the concept, each with an `I'll describe it`
+option:
+1. "What's the primary feel of the core action?" (3-4 options that fit the genre and tone)
+2. The concept's most important design variable (world reactivity, pacing, agency), as a question.
+
+Then work through, in the reply:
+- **30-second loop:** is the action satisfying in itself, and why (feedback, timing, depth)?
+- **5-minute loop:** what turns moments into cycles; where "one more run" starts; the choices made.
+- **Session loop (30-120 minutes):** a full session, its stopping points, the hook between sessions.
+- **Progression loop:** how the player grows, the long-term goal, when the game is done.
+- **Motivation (self-determination theory):** autonomy, competence, relatedness.
+
+## Phase 4: Pillars and boundaries
+
+Draft **3 to 5 pillars**, each with a name, a one-sentence definition and a design test ("debating
+X or Y, this pillar picks __"). Pillars should pull against each other a little. Add **3 or more
+anti-pillars**: "We will NOT do [thing] because it would compromise [pillar]."
+
+Ask: "Do these pillars feel right for your game?" `Lock these in` / `Rename or reframe one` /
+`Swap a pillar out` / `Something else`. After a revision ask: "Pillars updated. Ready to lock these
+in?" `Lock these in` / `Revise another pillar` / `Something else`.
+- `collaborative`: repeat until the user picks `Lock these in`.
+- `guided`: ask once, apply the revision, lock them in.
+- `autonomous`: do not ask; lock the draft in and log the decision with the alternatives.
+
+**Review mode** (from the settings block or `--review`):
+- `solo` or `lean`: print these two lines, with the mode's name, and go on to Phase 5:
+ `CD-PILLARS skipped — Solo mode.` and `AD-CONCEPT-VISUAL skipped — Solo mode.`
+- `full`: hand the pillar review to the `creative-director` agent (gate CD-PILLARS; brief: the
+ pillars with design tests, anti-pillars, core fantasy and hook) and the visual review to the
+ `art-director` agent (gate AD-CONCEPT-VISUAL; brief: the pitch, pillars, target platform if
+ known, reference games mentioned). Each reads its own gate file and returns its verdict; neither
+ edits files. They are independent: hand them out together where you can, otherwise one after
+ another.
+
+With both reports, when CD-PILLARS returns APPROVE, ask these two questions together:
+- **Pillars:** the creative-director's feedback. `Lock in as-is` / `Revise [pillar]` / `Discuss
+ further`.
+- **Visual anchor:** the art-director's 2-3 named directions, one option each, plus `Combine
+ elements across directions` / `Describe my own direction`. On STRONG mark the dominant one
+ `(Recommended)`. On CONCERNS show its reason and offer `Revise pillars` / `Describe my own
+ direction`.
+
+If CD-PILLARS returns CONCERNS or REJECT, settle the pillars first (the Pillars question alone),
+then ask the Visual anchor question alone. NOT ASSESSED from either gate is not an approval: name
+the missing input, supply it and run that gate again; failing that, treat CD-PILLARS NOT ASSESSED
+as CONCERNS, and with no art-director directions offer only `Describe my own direction`.
+
+The chosen direction is the **Visual Identity Anchor**: it goes into the concept and seeds the art
+bible.
+
+## Phase 5: Player types
+
+Using Bartle's types and the Quantic Foundry model: the primary player who will love it
+(Achievers, Explorers, Socializers, Competitors, Creators, Storytellers), the secondary appeal, who
+it is not for, and successful games that serve the same player.
+
+## Phase 6: Scope and feasibility
+
+- **Platform.** Ask: "What platforms are you targeting?" `PC (Steam / Epic)` / `Mobile (iOS /
+ Android)` / `Console` / `Web / Browser` / `Multiple platforms`. Record it for `/setup-engine`.
+ Note what the platform implies, without recommending an engine: `/setup-engine` makes that call
+ against the pinned engine reference.
+- **Engine.** Ask in every automation mode, `autonomous` included: "Do you already have an engine
+ you work in?" `Godot` / `Unity` / `Unreal Engine 5` / `No preference — help me decide`. Never
+ pick an engine for the user. A named engine is recorded as their preference without second
+ guessing. No preference: "Run `/setup-engine` after this session; it walks through the choice
+ with your concept and platform." Make no recommendation here.
+- Art pipeline and how labour-heavy it is; content scope (levels, items, hours); the MVP (the
+ smallest build that tests whether the core loop is fun); the biggest technical, design and market
+ risks; scope tiers (full vision, and what ships if time runs out).
+
+**Review mode** before TD-FEASIBILITY: `solo` or `lean` prints `TD-FEASIBILITY skipped — Solo
+mode.` (or `Lean mode`) and goes on to the scope tiers. `full`: after the technical risks, hand the
+feasibility review to the `technical-director` agent (gate TD-FEASIBILITY; brief: the core loop,
+platform, engine or "undecided", the technical risks). Show its report. HIGH RISK: offer to revisit
+scope. CONCERNS: note and go on. NOT ASSESSED: name the missing input and record feasibility as not
+assessed in the concept's risks, never as VIABLE.
+
+**Review mode** before PR-SCOPE: `solo` or `lean` prints `PR-SCOPE skipped — Solo mode.` (or `Lean
+mode`) and goes on to Phase 7. `full`: hand the scope review to the `producer` agent (gate PR-SCOPE;
+brief: full vision, MVP, scope tiers, timeline, team size). It answers REALISTIC, OPTIMISTIC or
+UNREALISTIC. UNREALISTIC: ask whether to adjust the MVP or scope tiers or keep them; the user
+decides and the concept is never rejected for it. OPTIMISTIC: show the producer's adjustments and
+ask whether to apply them. NOT ASSESSED: ask for the missing input (timeline, team size) and run it
+again, or record scope as not assessed, never as REALISTIC.
+
+## Phase 7: Write the concept
+
+Fill every section of the template from the conversation, including the MDA analysis, motivation
+profile and flow design, plus a **Visual Identity Anchor** section: the direction's name, its
+one-line visual rule, 2-3 supporting principles with design tests, and the colour philosophy.
+
+The Core Identity table's Estimated Scope matches the full-vision timeline in Scope Tiers: write
+"Large (X–Y months, solo)" or "Large (X–Y months, team of N)", not "Large".
+
+Ask, as its own question: "Game concept is ready. May I write it to `design/gdd/game-concept.md`?"
+`Yes — write it` / `Not yet — revise a section first`. Write only on an explicit yes to this
+question. A revision: ask which section (`Elevator Pitch` / `Core Fantasy & Unique Hook` /
+`Pillars` / `Core Loop` / `MVP Definition` / `Scope Tiers` / `Risks` / `Something else — I'll
+describe`), show it before and after, then ask "Ready to write the updated concept document?"
+`Yes — write it` / `Revise another section`.
+- `collaborative`: repeat until the yes.
+- `guided`: ask once, apply the revision and write.
+- `autonomous`: do not ask; write and log the decision.
+
+Write the file, creating folders as needed. Never write `design/game-brief.md` at this tier.
+
+## Phase 8: Next steps
+
+List every step, in order.
+
+**Design-first** (the concept is well defined):
+1. `/setup-engine`: configure the engine and its version-aware reference docs
+2. `/art-bible`: the visual identity, before any GDD. Required before the Technical Setup gate at
+ `full`; at `standard` only when the game has visual-asset stories
+3. `/design-review design/gdd/game-concept.md`: check the concept is complete
+4. The `creative-director` agent: refine the pillars
+5. `/map-systems`: the systems, their dependencies and priorities, in the systems index
+6. `/design-system`: one GDD per system from step 5
+7. `/create-architecture`: the architecture blueprint and its Required ADR list
+8. `/architecture-decision`: one ADR per decision on that list
+9. `/architecture-review`: the TR registry and traceability matrix (needed before the
+ Pre-Production gate)
+10. `/gate-check`: the stage gate before Production
+
+**Prototype-first** (the core mechanic is unproven):
+1. `/setup-engine`
+2. `/prototype [core mechanic]`: is it fun, in a day at most, throwaway code
+3. PROCEED: `/art-bible`, then design-first steps 5-10 with what the prototype taught
+4. PIVOT: `/brainstorm` again with the learnings
+5. After design and architecture, `/vertical-slice` before committing to sprints
+
+Then a summary: the pitch, pillars, primary player type, engine preference, biggest risk and the
+file path. End with the line `Verdict: COMPLETE — game concept written.`
+
+If the conversation is getting long before Phase 7, say that anything not yet written to
+`design/gdd/game-concept.md` lives only in this conversation, and write the concept before a fresh
+session.
diff --git a/.claude/skills/bug-report/SKILL.md b/.claude/skills/bug-report/SKILL.md
index 2623ef36..72677db5 100644
--- a/.claude/skills/bug-report/SKILL.md
+++ b/.claude/skills/bug-report/SKILL.md
@@ -3,7 +3,7 @@ name: bug-report
description: "Structured bug report from a description, or analyze code for potential bugs. Reproduction steps, severity."
argument-hint: "[description] | analyze [path-to-file] | verify [BUG-ID] | close [BUG-ID]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion, Bash(bash "*/.claude/skills/bug-report/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Bash(bash "*/.claude/skills/bug-report/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
@@ -17,6 +17,11 @@ every file write follows `.claude/docs/automation-modes.md`
# Bug Report
+**Drafts only.** This skill writes reports to `production/qa/bugs/`. When the
+cause is in the engine, a plugin or another vendor's code, add a draft for their
+tracker under **Notes** and stop there: never file, open or comment on an issue
+or pull request in their repository. The user submits it.
+
## Phase 1: Parse Arguments
Determine the mode from the argument:
@@ -122,6 +127,10 @@ Read that file. Extract the reproduction steps and expected result.
4. **Manual verification** — when no related test ran (none covers the bug — the usual case where `qa.level` waives tests — `commands.test` is unset, or the run did not complete), or the bug's Category is Visual or UI, whose look no automated test checks, ask via `AskUserQuestion`: "Did you play the reproduction steps in [bug file] on a build with the fix? Which build?" —
`[No longer occurs]` / `[Still occurs]` / `[Not played yet]`.
Record the answer and the build as the user gives them; a changed code path is never taken as their answer.
+ **Run as a subagent?** `qa-lead` preloads this skill, and a subagent has no
+ `AskUserQuestion`. End your reply with the question and its three options as
+ a short list, and give no verdict yet: whoever called you asks the user, and
+ the verdict waits for the answer.
Produce a verification verdict:
diff --git a/.claude/skills/changelog/SKILL.md b/.claude/skills/changelog/SKILL.md
index 202eeaee..b3f7b19f 100644
--- a/.claude/skills/changelog/SKILL.md
+++ b/.claude/skills/changelog/SKILL.md
@@ -3,7 +3,7 @@ name: changelog
description: "Auto-generate a changelog from git commits and sprint data. Internal and player-facing versions."
argument-hint: "[version|sprint-number]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash, Write, Bash(bash "*/.claude/skills/changelog/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/changelog/../../hooks/yaml-helper.sh" resolve_config *), Bash(git log *), Bash(git tag --list*), Bash(git rev-parse *)
model: sonnet
---
@@ -47,9 +47,8 @@ check governs is whether that output is usable, not whether it is fetched.
> **Filter per commit; a repo containing maintenance work is not a wrong repo.**
> Every project on this framework accumulates commits touching hooks, CI and
-> skills — the game repo *is* the framework repo. Listing those as a hard STOP
-> fires on virtually every real project and contradicts step 2 whenever the
-> history is mostly the game's. The harm is those commits becoming release copy,
+> skills — the game repo *is* the framework repo, so stopping on them would fire
+> on virtually every real project. The harm is those commits becoming release copy,
> and excluding them prevents that precisely.
>
> This rule is kept identical to `/patch-notes`' on purpose — the two read the
@@ -69,13 +68,11 @@ If **no** commit in the range is this game's, say so and stop:
Verdict: **BLOCKED** — stop here without generating a changelog.
-**Why this is a hard stop, not a warning.** This exact failure is real, not
-hypothetical: a batch of framework-internal commits produced player-facing copy
-reading *"Fixed an issue where progress from your last session could be lost on
-launch"* — a
-session-hook timeout rendered as a gameplay fix for a game with **no save
-system**. It was fluent, plausible, and entirely false. A reader cannot tell the
-difference; only this check can.
+**Why this is a hard stop, not a warning.** Framework-internal commits rendered
+as player copy read as real changes: a session-hook timeout becomes *"Fixed an
+issue where progress from your last session could be lost on launch"* in a game
+with **no save system**. That copy is fluent, plausible, and entirely false. A
+reader cannot tell the difference; only this check can.
**Do not treat the preamble's existence as evidence.** Injected output means the
command ran, never that its subject is your game.
@@ -118,7 +115,7 @@ rather than widening blindly.
Read sprint reports from `production/sprints/` for the relevant period to understand planned work and context behind changes.
-Read completed design documents from `design/gdd/` for any new features implemented during this period.
+Read completed design documents from `design/gdd/` for any new features implemented during this period. Read them by section: find the headings you need with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit.
---
diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.md
index 6d224fc1..9c1ed4fd 100644
--- a/.claude/skills/code-review/SKILL.md
+++ b/.claude/skills/code-review/SKILL.md
@@ -160,12 +160,10 @@ Spawn all applicable specialists simultaneously via `Agent` — do not wait for
> promoted to a defect on the strength of confident phrasing.
>
> **Why this is mandatory.** Agents are reliable when deriving and unreliable when
-> diagnosing existing code. In practice, three separate agents
-> produced three different **wrong** claims about the same six-line function,
-> every one fluent enough to pass a skim — including a spawned specialist here
-> alleging a float-precision bug that enumerating the inputs disproves. Without
-> this step the parent review is a laundering channel: a guess enters as a
-> specialist finding and leaves as a reviewed defect.
+> diagnosing existing code: a **wrong** claim about a short function can be fluent
+> enough to pass a skim, and a claimed bug can fall apart once you enumerate the
+> inputs. Without this step the parent review is a laundering channel: a guess
+> enters as a specialist finding and leaves as a reviewed defect.
### Engine Specialists
diff --git a/.claude/skills/consistency-check/SKILL.md b/.claude/skills/consistency-check/SKILL.md
index e9ca39b6..f57de89d 100644
--- a/.claude/skills/consistency-check/SKILL.md
+++ b/.claude/skills/consistency-check/SKILL.md
@@ -3,7 +3,7 @@ name: consistency-check
description: "Scan GDDs against the entity registry for cross-document conflicts. Grep-first approach targets conflicting sections, different stats."
argument-hint: "[full | since-last-review | entity:<name> | item:<name>]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, Bash(bash "*/.claude/skills/consistency-check/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Bash(bash "*/.claude/skills/consistency-check/../../hooks/yaml-helper.sh" resolve_config *), Bash(git log *), Bash(bash .claude/scripts/registry.sh validate*)
model: sonnet
---
@@ -194,6 +194,9 @@ Read path="design/gdd/[conflicting_gdd].md"
```
(Or use Grep with wider context if the file is large)
+Read it by section: find the conflicting section's heading with the Grep tool
+(pattern `^#`, content mode) and Read that range with offset and limit.
+
Confirm the conflict with full context. Determine:
1. **Which GDD is correct?** Check the `source:` field in the registry — the
source GDD is the authoritative owner. Any other GDD that contradicts it
@@ -294,6 +297,13 @@ Only add entries that appear in more than one GDD (true cross-system facts).
**Never delete registry entries.** Set `status: deprecated` if an entry is removed
from all GDDs.
+After writing, run `bash .claude/scripts/registry.sh validate` and fix every row
+about an entry this write added or changed (a DUPLICATE, STATUS or LAYOUT row,
+or a PATH_MISSING row for a path it named) before the verdict; name rows about
+other entries to the user rather than fixing them unasked. If the script is
+missing or prints nothing, say the registry check did not run, then re-read the
+entries you wrote against the rules in the file's header.
+
After writing: Verdict: **COMPLETE** — consistency check finished.
If conflicts remain unresolved: Verdict: **BLOCKED** — [N] conflicts need manual resolution before architecture begins.
diff --git a/.claude/skills/content-audit/SKILL.md b/.claude/skills/content-audit/SKILL.md
index 93c4b476..1e0af3f1 100644
--- a/.claude/skills/content-audit/SKILL.md
+++ b/.claude/skills/content-audit/SKILL.md
@@ -19,11 +19,10 @@ Resolved above — use as-is. No block → defaults in `.claude/docs/config-reso
# Content Audit
-> This skill declares tier-dependent behaviour ("audit only specs in the required
-> sections"), which is unreachable unless the tier is actually resolved — without
-> it the skill applies whatever tier it assumed. Resolve `modes.workflow` before
-> auditing, and
-> when a required input such as `design/gdd/systems-index.md` is absent, report
+> Resolve `modes.workflow` before auditing: this skill's tier-dependent behaviour
+> ("audit only specs in the required sections") follows the resolved tier, never
+> an assumed one. When a required input such as `design/gdd/systems-index.md` is
+> absent, report
> **`NOT ASSESSED — NO DATA`** rather than computing a gap percentage (which
> divides by zero when nothing is specified).
@@ -75,7 +74,9 @@ the two happened — a reader cannot tell from a green result.
## Phase 1 — Context Gathering
1. **Read `design/gdd/systems-index.md`** for the full list of systems, their
- categories, and MVP/priority tier.
+ categories, and MVP/priority tier. Read it by section: find the headings you need
+ with the Grep tool (pattern `^#`, content mode) and Read those ranges with
+ offset and limit.
2. **Registry-first count**: If `design/registry/entities.yaml` exists, read it
first. Its `entities` and `items` sections are the cross-GDD named content
@@ -125,7 +126,9 @@ the two happened — a reader cannot tell from a green result.
read.
4. **Full-read in-scope GDD files** (or the single system GDD if a system
- name was given).
+ name was given). This step needs the whole GDD: read it in ranges by its
+ headings (found with the Grep tool: pattern `^#`, content mode), since a
+ whole-file Read over 40 KB is refused.
5. **For each GDD, extract explicit content counts or lists**, noting the `##` section each sits under — at `standard`, a count outside the required sections (`.claude/docs/workflow-modes.md`) goes on the "Not audited at this tier" list, never into the inventory. Look for patterns
like:
diff --git a/.claude/skills/create-architecture/SKILL.md b/.claude/skills/create-architecture/SKILL.md
index f451be46..f2cb63f0 100644
--- a/.claude/skills/create-architecture/SKILL.md
+++ b/.claude/skills/create-architecture/SKILL.md
@@ -3,7 +3,7 @@ name: create-architecture
description: "Author the architecture blueprint before code is written. Validates decisions against the pinned engine, flags knowledge gaps."
argument-hint: "[focus-area: full | layers | data-flow | api-boundaries | adr-audit] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/create-architecture/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/create-architecture/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/registry.sh *)
model: sonnet
---
@@ -118,7 +118,7 @@ unsure, present 2-4 options with pros/cons before asking them to decide.
## Recommended Next Steps
- Run `/architecture-decision [title]` for each required ADR listed in Phase 6 — Foundation layer ADRs first
-- Run `/architecture-review` — bootstraps the Requirements Traceability Matrix and TR registry from the ADRs just written. Required before the Pre-Production gate.
+- Run `/architecture-review` — bootstraps the Requirements Traceability Matrix and TR registry from the ADRs just written, and gives each provisional TR-ID its permanent one. Required before the Pre-Production gate.
- Run `/test-setup` to scaffold `tests/unit/`, `tests/integration/`, CI workflow, and an example test (required for gate-check)
- Run `/ux-design` to initialize `design/ux/interaction-patterns.md` and `design/accessibility-requirements.md` (required for gate-check)
- Run `/create-control-manifest` once the required ADRs are written to produce the layer rules manifest
diff --git a/.claude/skills/create-architecture/references/0-load-context.md b/.claude/skills/create-architecture/references/0-load-context.md
index 565a17ed..c8a0f9dd 100644
--- a/.claude/skills/create-architecture/references/0-load-context.md
+++ b/.claude/skills/create-architecture/references/0-load-context.md
@@ -51,7 +51,9 @@ If no engine is configured, stop and prompt:
### 0b. Design Context + Technical Requirements Extraction
-Load the approved design documents and extract technical requirements from each:
+Load the approved design documents and extract technical requirements from each.
+Read each one by section: find the headings you need with the Grep tool (pattern
+`^#`, content mode) and Read those ranges with offset and limit.
1. `design/gdd/game-concept.md` — game pillars, genre, core loop
2. `design/gdd/systems-index.md` — all systems, dependencies, priority tiers
@@ -64,7 +66,7 @@ matter just as much:
> "No systems index found. Run `/map-systems` first. An architecture written
> without it invents layers for systems nobody mapped, and every ADR, epic and
> story downstream inherits that invention."
- At `minimal` the index is not required (§ tier note above) — say so and proceed
+ At `minimal` the index is not required (the `workflow` list in SKILL.md) — say so and proceed
from the brief instead.
- **`game-concept.md` absent** — at `standard`/`full`, stop and point at
`/brainstorm`. At `minimal`, read `design/game-brief.md` in its place; if that
@@ -107,17 +109,36 @@ everything downstream rather than re-checked.
Build a **Technical Requirements Baseline** — a flat list of all extracted
requirements across all GDDs, numbered `TR-[system]-[NNN]`, the TR registry's
ID format. This is the
-complete set of what the architecture must cover. Present it as:
+complete set of what the architecture must cover.
+
+**The IDs come from the TR registry, not from a fresh count.** Stories and ADRs
+cite TR-IDs, and `/architecture-review` keeps them permanent in
+`docs/architecture/tr-registry.yaml`. A baseline numbered from 001 on a re-run
+gives a requirement a different ID from the one stories already cite. So, before
+numbering:
+
+- **Registry present with entries:** read `docs/architecture/tr-registry.yaml`.
+ A requirement that matches an `active` entry for the same system (same intent,
+ wording may differ) keeps that entry's ID. Skip `deprecated` and
+ `superseded-by` entries; they were retired on purpose. Every other requirement
+ is **provisional**: number it from `bash .claude/scripts/registry.sh next-id tr
+ <system>` onwards, so it cannot reuse a registered or retired ID, and mark it
+ `(provisional)`. `/architecture-review` registers it and gives the permanent ID.
+- **Registry absent, or `requirements: []`:** every ID is provisional. Say so in
+ the baseline's header line, so nobody cites them as permanent.
+
+Present it as:
```
## Technical Requirements Baseline
-Extracted from [N] GDDs | [X] total requirements
+Extracted from [N] GDDs | [X] total requirements | [R] registered, [P] provisional
+(TR registry: [read, E entries | absent | empty])
| Req ID | GDD | System | Requirement | Domain |
|--------|-----|--------|-------------|--------|
| TR-combat-001 | combat.md | Combat | Hitbox detection per-frame | Physics |
| TR-combat-002 | combat.md | Combat | Combo state machine | Core |
-| TR-inventory-001 | inventory.md | Inventory | Item persistence | Save/Load |
+| TR-inventory-001 (provisional) | inventory.md | Inventory | Item persistence | Save/Load |
```
This baseline feeds into every subsequent phase. No GDD requirement should be
@@ -135,7 +156,9 @@ Grep pattern="\*\*Domain\*\*" glob="docs/architecture/adr-*.md" output_mode="con
Compatibility `Domain` field are exactly "what was decided and its domain". List
the ADRs found, their status, and their domains from the scan. Full-read a
specific ADR only when a new decision this session would collide with it and you
-need its reasoning — not to build the inventory.
+need its reasoning — not to build the inventory. Read it by section: find the
+headings with the Grep tool (pattern `^#`, content mode) and Read those
+ranges with offset and limit.
### 0d. Generate Knowledge Gap Inventory
diff --git a/.claude/skills/create-architecture/references/1-layers.md b/.claude/skills/create-architecture/references/1-layers.md
index ce9cc0fc..a1d0c191 100644
--- a/.claude/skills/create-architecture/references/1-layers.md
+++ b/.claude/skills/create-architecture/references/1-layers.md
@@ -23,6 +23,10 @@ game architecture layers are:
└─────────────────────────────────────────────┘
```
+The Platform layer is the engine and OS the game runs on, not code the project
+writes. No GDD system goes in it, so it has no epic, stories or control-manifest
+rules: a system that wraps a platform or engine API belongs in Foundation.
+
For each GDD system, ask:
- Which layer does it belong to?
- What are its module boundaries?
diff --git a/.claude/skills/create-architecture/references/2-module-ownership.md b/.claude/skills/create-architecture/references/2-module-ownership.md
index 0083c498..b787dfd7 100644
--- a/.claude/skills/create-architecture/references/2-module-ownership.md
+++ b/.claude/skills/create-architecture/references/2-module-ownership.md
@@ -19,7 +19,7 @@ Format as a table per layer, then as an ASCII dependency diagram.
relevant module reference doc. If an API is post-cutoff, flag it:
```
-⚠️ [ClassName.method()] — Godot 4.6 (post-cutoff, HIGH risk)
+⚠️ [ClassName.method()] — Godot 4.7 (post-cutoff, HIGH risk)
Verified against: docs/engine-reference/godot/modules/[domain].md
Behaviour confirmed: [yes / NEEDS VERIFICATION]
```
diff --git a/.claude/skills/create-control-manifest/SKILL.md b/.claude/skills/create-control-manifest/SKILL.md
index 6d4465ee..b4628934 100644
--- a/.claude/skills/create-control-manifest/SKILL.md
+++ b/.claude/skills/create-control-manifest/SKILL.md
@@ -1,220 +1,189 @@
---
name: create-control-manifest
-description: "Flat must-do/never-do rules sheet per system and layer, extracted from Accepted ADRs. ADRs explain why; this is actionable."
+description: "Builds a short list of must-do and never-do coding rules per system from accepted ADRs. Use when the user wants programmer rules or a cheat sheet from the ADRs, or needs it regenerated after ADR changes."
argument-hint: "[update — regenerate from current ADRs] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/create-control-manifest/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/create-control-manifest/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/adr-status.sh*), Bash(bash .claude/scripts/md-section.sh *)
model: sonnet
---
-!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation`
+!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation`
Resolved above — use as-is; `--review` overrides `review_mode` for this run. No
block → defaults in `.claude/docs/config-resolution.md`.
-# Create Control Manifest
+Ask with the question tool. Without one, list the options numbered and end your turn
+to wait. A skipped or dismissed question is not an answer: ask again in plain text.
-The Control Manifest is a flat, actionable rules sheet for programmers. It
-answers "what do I do?" and "what must I never do?" — organized by architectural
-layer, extracted from all Accepted ADRs, technical preferences, and engine
-reference docs. Where ADRs explain *why*, the manifest tells you *what*.
+# Create Control Manifest
-**Output:** `docs/architecture/control-manifest.md`
+The control manifest is a flat rules sheet for programmers: what to do and what
+never to do, by architectural layer, taken from the Accepted ADRs, the project's
+technical preferences and the engine reference docs. The ADRs say *why*; the
+manifest says *what*.
-**When to run:** After `/architecture-review` passes and ADRs are in Accepted
-status. Re-run whenever new ADRs are accepted or existing ADRs are revised.
+**Writes:** `docs/architecture/control-manifest.md`, after the user's yes.
+**When:** after `/architecture-review` passes and the ADRs are Accepted. Run it
+again whenever an ADR is accepted or revised.
----
+Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided
+asks on major choices, autonomous logs and goes on; `automation_always_ask`
+categories always ask).
-Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
-(collaborative asks always · guided major-only · autonomous logs and proceeds;
-`automation_always_ask` categories always prompt).
-
-## 1. Load All Inputs
+## Phase 1: Load the inputs
### ADRs
-**Establish the denominator first.** Glob `docs/architecture/adr-*.md`. Call the
-count **N**. If N is 0: "No ADRs found — run `/architecture-decision` before
-building a control manifest." Stop.
-**Resolve status without reading the ADRs** — the filter must precede the read,
-not follow it:
-```
-Grep pattern="^## Status" glob="docs/architecture/adr-*.md" output_mode="content" -A 3
-```
-Interpret against N:
+`bash .claude/scripts/adr-status.sh` reads every `docs/architecture/adr-*.md` in one
+pass: the counts first (`adrs`, then `accepted`, `proposed`, `deprecated`,
+`superseded`, `unfilled`, `other`, `no_status`), then one row per ADR with its
+status and layer. Establish the denominator first: decide from the counts, before
+reading any ADR:
-| Result | Meaning | Action |
+| Counts | Meaning | Action |
|---|---|---|
-| **N matches, some read `Accepted`** | Normal. | The Accepted set is **A**; proceed with A. Name every ADR left out, with its status, in the Phase 4 preview — the user approves a manifest knowing what it does not cover. |
-| **N matches, none `Accepted`** | Genuinely no Accepted ADRs. | "[N] ADRs found, none Accepted. A manifest built from Proposed ADRs would encode decisions that may still change." Ask whether to proceed with Proposed or stop. **Do not silently emit an empty manifest.** |
-| **0 matches, N > 0** | **Malformed ADRs — not an empty Accepted set.** `## Status` is BLOCKING-if-missing. | "[N] ADRs found, none has a `## Status` section — acceptance cannot be determined. Run `/architecture-decision retrofit [file]` on each." **Stop.** Do not treat all ADRs as Accepted; do not emit a manifest. |
-
-- Note the ADR number and title for every rule sourced.
-
-### Project Config
-- Read `naming.*` and `performance.*` from `project.yaml`; for any key absent or
- empty, fall back to `.claude/docs/technical-preferences.md`
-- Read approved libraries/addons and forbidden patterns from
- `.claude/docs/technical-preferences.md` (not migrated to project.yaml)
-
-### Engine Reference
-- Read `docs/engine-reference/[engine]/VERSION.md` for engine + version
-- Read `docs/engine-reference/[engine]/deprecated-apis.md` — these become
- forbidden API entries
-- Read `docs/engine-reference/[engine]/current-best-practices.md` if it exists
-
-### Existing Artifacts
-- Glob `docs/architecture/control-manifest.md` (present → this run is a
- regeneration; Read it before the Phase 5 write, which overwrites it) and
- `production/epics/*/EPIC.md` (present → epics exist). Phase 6 picks its next
- step from both.
+| `adrs 0` | No ADRs. | "No ADRs found — run `/architecture-decision` before building a control manifest." Stop. |
+| `accepted` ≥ 1 | Normal. | The Accepted rows are the set **A**. Name every other ADR, with its status, in the Phase 4 preview: the user approves a manifest knowing what it leaves out. |
+| `accepted 0`, some with a status | No Accepted ADRs. | "[N] ADRs found, none Accepted. A manifest built from Proposed ADRs would encode decisions that may still change." Ask whether to go on with the Proposed ones or stop. **Never write an empty manifest silently.** |
+| every ADR `no_status` | **Malformed ADRs, not an empty Accepted set.** | "[N] ADRs found, none has a `## Status` section, so acceptance cannot be told. Run `/architecture-decision retrofit [file]` on each." Stop. Never treat them as Accepted. |
-Report: "Loaded [N] Accepted ADRs, engine: [name + version]."
+Each stop above ends with `Verdict: BLOCKED — [the reason]`. Note the number and
+title of every ADR a rule comes from.
----
-
-## 2. Extract Rules from Each ADR
-
-Read **only these four sections** per Accepted ADR — not the whole file. Context,
-Consequences, Migration Plan and Validation Criteria explain *why* a decision was
-made; the manifest records *what to do*, so they are not needed here:
-```
-Grep pattern="^## (Decision|Alternatives Considered|Performance Implications|Engine Compatibility)" glob="docs/architecture/adr-*.md" output_mode="content" -A 30
-```
-Filter the results to the Accepted set **A** resolved above. If a section is
-absent for a given ADR, note it per ADR and continue; if a section is absent
-across **all** of A, report "No Accepted ADR contains a `[section]` section — the
-manifest's [category] rules will be empty. Verify this is intended." Escalate to
-a full read of one ADR only when its scanned sections cross-reference material
-outside them (e.g. a Decision that says "subject to the constraints in Context").
-
-For each Accepted ADR, extract:
-
-### Required Patterns (from the `## Decision` section)
-- Every "must", "should", "required to", "always" statement in the Decision body
- — including any `### Implementation Guidelines` sub-heading when the ADR has one
- (newer ADRs emit it; older ones state mandates directly in `## Decision`). Never
- scan for `### Implementation Guidelines` alone — it is absent from many
- skill-authored ADRs, and scanning for it yields an empty Required Patterns
- section on a manifest that should have been full.
-- Every specific pattern or approach mandated
-
-### Forbidden Approaches (from "Alternatives Considered" sections)
-- Every alternative that was explicitly rejected — *why* it was rejected becomes
- the rule ("never use X because Y")
-- Any anti-patterns explicitly called out
-
-### Performance Guardrails (from "Performance Implications" section)
-- Budget constraints: "max N ms per frame for this system"
-- Memory limits: "this system must not exceed N MB"
-
-### Engine API Constraints (from "Engine Compatibility" section)
-- Post-cutoff APIs that require verification
-- Verified behaviours that differ from default LLM assumptions
-- API fields or methods that behave differently in the pinned engine version
-
-### Layer Classification
-Classify each rule by the architectural layer of the system it governs:
-- **Foundation**: Scene management, event architecture, save/load, engine init
-- **Core**: Core gameplay loops, main player systems, physics/collision
-- **Feature**: Secondary systems, secondary mechanics, AI
-- **Presentation**: Rendering, audio, UI, VFX, shaders
-
-If an ADR spans multiple layers, duplicate the rule into each relevant layer.
+### Project config
----
+- `naming.*` and `performance.*` from `project.yaml`; for any key absent or empty,
+ `.claude/docs/technical-preferences.md`.
+- Approved libraries and forbidden patterns from
+ `.claude/docs/technical-preferences.md` (not migrated to `project.yaml`).
-## 3. Add Global Rules
+### Engine reference
-Combine rules that apply to all layers. Each carries its source into the manifest, as a layer rule does — the `project.yaml` key, `technical-preferences.md`, or the engine-reference file:
+- `docs/engine-reference/[engine]/VERSION.md` for the engine and version.
+- `docs/engine-reference/[engine]/deprecated-apis.md`: these become forbidden APIs.
+- `docs/engine-reference/[engine]/current-best-practices.md`, when it exists.
-### From project config (`project.yaml`, else `technical-preferences.md`):
-- Naming conventions — `naming.*`: classes, variables, signals/events, files, constants
-- Performance budgets — `performance.*`: target framerate, frame budget, draw call limits, memory ceiling
+### What exists already
-### From deprecated-apis.md:
-- Deprecated APIs → Forbidden API entries, **filtered for relevance to this
- project**. Do not copy the deprecation table wholesale.
- > Each entry must apply to what this project actually builds. `deprecated-apis.md`
- > mixes dimensions and subsystems: its `GodotPhysics3D → Jolt Physics 3D` row is
- > **3D-only**, so emitting it unqualified gives a 2D project a global rule about
- > a physics engine it never uses. If you cannot tell whether an entry applies —
- > 2D vs 3D, a module the project does not include — either scope the rule
- > ("when using 3D physics: ...") or omit it and note it as unresolved. A manifest
- > of rules that do not apply is one nobody reads, and `/create-stories` consumes
- > this file.
+`docs/architecture/control-manifest.md` present: this run regenerates it; read it
+before the Phase 5 write, which replaces it. `production/epics/*/EPIC.md` present:
+epics exist. Phase 6 picks its next step from both.
-### From current-best-practices.md (if available):
-- Engine-recommended patterns → Required entries
+Report: "Loaded [A] Accepted ADRs of [N], engine: [name + version]."
-### From technical-preferences.md forbidden patterns:
-- Copy any "Forbidden Patterns" entries directly
+## Phase 2: Extract the rules from each ADR
----
+For each ADR in **A**, read only four sections, never the whole file:
-## 4. Present Rules Summary Before Writing
+```
+bash .claude/scripts/md-section.sh extract docs/architecture/[adr-file].md "Decision"
+```
-Before writing the manifest, present a summary to the user:
+and the same for `Alternatives Considered`, `Performance Implications` and `Engine
+Compatibility`. Context, Consequences, Migration Plan and Validation Criteria say why
+a decision was made; the manifest records what to do. A section an ADR lacks: note
+it for that ADR and go on. A section missing from **every** ADR in A: report "No
+Accepted ADR has a `[section]` section — the manifest's [category] rules will be
+empty. Verify this is intended." Read beyond the four only when a section points
+outside itself ("subject to the constraints in Context"), and then that one section.
+
+From each ADR:
+
+- **Required patterns** (Decision): every "must", "should", "required to",
+ "always", and every pattern or approach it mandates, including any `### Implementation
+ Guidelines` inside it. Never look for that sub-heading alone: many ADRs state
+ their mandates directly under Decision, and a scan for the sub-heading alone
+ yields an empty section.
+- **Forbidden approaches** (Alternatives Considered): every rejected alternative,
+ with why it was rejected as the rule ("never use X because Y"), and any named
+ anti-pattern.
+- **Performance guardrails** (Performance Implications): budgets ("max N ms per
+ frame for this system") and memory limits.
+- **Engine API constraints** (Engine Compatibility): post-cutoff APIs that need
+ verifying, behaviour that differs from what a model would assume, fields or
+ methods that changed in the pinned version.
+
+**Layer.** Each rule goes under the layer of the system it governs, the ADR's
+`layer` column where it has one:
+
+- **Foundation:** scene management, event architecture, save/load, engine start-up
+- **Core:** core gameplay loop, main player systems, physics and collision
+- **Feature:** secondary systems and mechanics, AI
+- **Presentation:** rendering, audio, UI, VFX, shaders
+
+An ADR that spans layers puts its rule in each one.
+
+## Phase 3: Add the global rules
+
+Rules for every layer, each with its source (the `project.yaml` key,
+`technical-preferences.md`, or the engine-reference file), as a layer rule has:
+
+- **Naming** from `naming.*`: classes, variables, signals and events, files,
+ constants.
+- **Performance budgets** from `performance.*`: target frame rate, frame budget,
+ draw calls, memory ceiling.
+- **Forbidden APIs** from `deprecated-apis.md`, **only those that apply to what this
+ project builds.** Never copy the table whole: its `GodotPhysics3D → Jolt Physics
+ 3D` row is 3D-only, and a 2D project does not use that engine. When you cannot
+ tell whether an entry applies (2D or 3D, a module the project may not include),
+ scope the rule ("when using 3D physics: …") or leave it out and list it as
+ unresolved. `/create-stories` reads this file, and rules that do not apply are
+ rules nobody reads.
+- **Required patterns** from `current-best-practices.md`, when it exists.
+- **Forbidden patterns** from `technical-preferences.md`, copied as written.
+
+## Phase 4: Show the summary, then the review
```
## Control Manifest Preview
Engine: [name + version]
-ADRs covered: [list ADR numbers]
-ADRs excluded: [ADR-NNNN ([status]), … — every ADR not in the Accepted set, or "None"]
-Total rules extracted:
+ADRs covered: [ADR numbers]
+ADRs left out: [ADR-NNNN ([status]), … — every ADR not in A, or "None"]
+Rules extracted:
- Foundation layer: [N] required, [M] forbidden, [P] guardrails
- Core layer: [N] required, [M] forbidden, [P] guardrails
- - Feature layer: ...
- - Presentation layer: ...
+ - Feature layer: …
+ - Presentation layer: …
- Global: [N] naming conventions, [M] forbidden APIs, [P] approved libraries
+Unresolved: [engine entries left out because whether they apply is unclear, or "None"]
```
-Use `AskUserQuestion`:
-- Prompt: "Does this rule summary look complete?"
-- Options:
- - `[A] Yes — looks good, run the director review and write the manifest`
- - `[B] Add rules — I have additional rules to include before writing`
- - `[C] Remove rules — some extracted rules should be dropped`
- - `[D] Stop here — I need to review the ADRs first`
-
----
-
-## 4b. Director Gate — Technical Review
-
-**Review mode check** — apply before spawning TD-MANIFEST:
-- `solo` → skip. Note: "TD-MANIFEST skipped — Solo mode." Proceed to Phase 5.
-- `lean` → skip. Note: "TD-MANIFEST skipped — Lean mode." Proceed to Phase 5.
-- `full` → spawn as normal.
-
-Spawn `technical-director` via `Agent` using gate **TD-MANIFEST** (`.claude/docs/director-gates/td-manifest.md`).
-
-Pass: the Control Manifest Preview from Phase 4 (rule counts per layer, full extracted rule list), the list of ADRs covered, engine version, and any rules sourced from technical-preferences.md or engine reference docs.
-
-The technical-director reviews whether:
-- All mandatory ADR patterns are captured and accurately stated
-- Forbidden approaches are complete and correctly attributed
-- No rules were added that lack a source ADR or preference document
-- Performance guardrails are consistent with the ADR constraints
-
-Apply the verdict:
-- **APPROVE** → proceed to Phase 5
-- **CONCERNS** → surface via `AskUserQuestion` with options: `Revise flagged rules` / `Accept and proceed` / `Discuss further`
-- **REJECT** → do not write the manifest; fix the flagged rules and re-present the summary
-- **NOT ASSESSED** [missing input] → not an approval (`.claude/docs/director-gates.md`): name what was missing, then supply it and re-run the gate — or, if the user chooses to go on without it, continue to Phase 5 and state `TD-MANIFEST: NOT ASSESSED — [input]` in the output and the final Verdict line
-
----
-
-## 5. Write the Control Manifest
-
-Use `AskUserQuestion`:
-- Prompt: "May I write the Control Manifest?"
-- Options:
- - `[A] Yes — write to docs/architecture/control-manifest.md`
- - `[B] Show me the full draft first, then ask again`
- - `[C] Not yet — I want to make more changes`
-
-Format:
+Ask: "Does this rule summary look complete?" Options: Yes — review and write it /
+Add rules — I have more to include / Remove rules — some should be dropped / Stop —
+I need to review the ADRs first.
+
+**The technical review.** Read the `review_gate` line above. `skill-gates=skip`
+(solo or lean): no agent; note `TD-MANIFEST skipped — [Solo | Lean] mode`.
+`skill-gates=run`: hand the review to the `technical-director` agent with gate
+**TD-MANIFEST** (`.claude/docs/director-gates/td-manifest.md`; the agent reads it
+itself). Brief:
+
+- **Objective:** check the extracted rules before they are written.
+- **Give it:** the preview above with the full rule list, the ADRs covered, the
+ engine version, and the rules taken from technical preferences or the engine
+ reference.
+- **Check:** every mandatory ADR pattern is captured and stated accurately; the
+ forbidden approaches are complete and correctly attributed; no rule lacks a source
+ ADR or preference document; the guardrails agree with the ADRs' constraints.
+- **Return:** APPROVE, CONCERNS, REJECT, or NOT ASSESSED naming a missing input.
+- **Boundaries:** it writes no file.
+
+Act on the verdict:
+
+- **APPROVE:** go to Phase 5.
+- **CONCERNS:** ask: "The technical director raised concerns. How do you want to go
+ on?" Options: Revise the flagged rules / Accept and go on / Discuss further.
+- **REJECT:** write nothing; fix the flagged rules and show the summary again.
+- **NOT ASSESSED:** it is not an approval (`.claude/docs/director-gates.md`). Name
+ what was missing, then supply it and run the review again; or, when the user
+ chooses to go on without it, go to Phase 5 and state `TD-MANIFEST: NOT ASSESSED —
+ [input]` in the reply and the final verdict line.
+
+## Phase 5: Write the control manifest
+
+Ask: "May I write the control manifest to `docs/architecture/control-manifest.md`?"
+Options: Yes, write it / Show me the full draft first, then ask again / Not yet — I
+want more changes. Write only on an explicit yes.
```markdown
# Control Manifest
@@ -223,26 +192,25 @@ Format:
> **Last Updated**: [date]
> **Manifest Version**: [date]
> **ADRs Covered**: [ADR-NNNN, ADR-MMMM, ...]
-> **Status**: [Active — regenerate with `/create-control-manifest update` when ADRs change]
+> **Status**: Active — regenerate with `/create-control-manifest update` when ADRs change
-`Manifest Version` is the date this manifest was generated. Story files embed
-this date when created. `/story-readiness` compares a story's embedded version
-to this field to detect stories written against stale rules. Always matches
-`Last Updated` — they are the same date, serving different consumers.
+`Manifest Version` is the date this manifest was generated. Stories embed it when
+they are written, and `/story-readiness` compares a story's version with this one
+to find stories written against old rules. It always equals `Last Updated`: the
+same date, for different readers.
-This manifest is a programmer's quick-reference extracted from all Accepted ADRs,
-technical preferences, and engine reference docs. For the reasoning behind each
-rule, see the referenced ADR.
+This manifest is a programmer's quick reference taken from the Accepted ADRs, the
+technical preferences and the engine reference docs. For the reason behind a rule,
+read its ADR.
---
## Foundation Layer Rules
-*Applies to: scene management, event architecture, save/load, engine initialisation*
+*Applies to: scene management, event architecture, save/load, engine start-up*
### Required Patterns
- **[rule]** — source: [ADR-NNNN]
-- **[rule]** — source: [ADR-NNNN]
### Forbidden Approaches
- **Never [anti-pattern]** — [brief reason] — source: [ADR-NNNN]
@@ -296,19 +264,19 @@ rule, see the referenced ADR.
### Naming Conventions
| Element | Convention | Example | Source |
|---------|-----------|---------|--------|
-| Classes | [from naming.* in project.yaml, else technical-preferences.md] | [example] | [`naming.classes` in project.yaml, or technical-preferences.md] |
-| Variables | [from naming.* in project.yaml, else technical-preferences.md] | [example] | [`naming.variables` in project.yaml, or technical-preferences.md] |
-| Signals/Events | [from naming.* in project.yaml, else technical-preferences.md] | [example] | [`naming.signals` in project.yaml, or technical-preferences.md] |
-| Files | [from naming.* in project.yaml, else technical-preferences.md] | [example] | [`naming.files` in project.yaml, or technical-preferences.md] |
-| Constants | [from naming.* in project.yaml, else technical-preferences.md] | [example] | [`naming.constants` in project.yaml, or technical-preferences.md] |
+| Classes | [convention] | [example] | [`naming.classes` in project.yaml, or technical-preferences.md] |
+| Variables | [convention] | [example] | [`naming.variables` in project.yaml, or technical-preferences.md] |
+| Signals/Events | [convention] | [example] | [`naming.signals` in project.yaml, or technical-preferences.md] |
+| Files | [convention] | [example] | [`naming.files` in project.yaml, or technical-preferences.md] |
+| Constants | [convention] | [example] | [`naming.constants` in project.yaml, or technical-preferences.md] |
### Performance Budgets
| Target | Value | Source |
|--------|-------|--------|
-| Framerate | [from performance.* in project.yaml, else technical-preferences.md] | [`performance.target_framerate` in project.yaml, or technical-preferences.md] |
-| Frame budget | [from performance.* in project.yaml, else technical-preferences.md] | [`performance.frame_budget_ms` in project.yaml, or technical-preferences.md] |
-| Draw calls | [from performance.* in project.yaml, else technical-preferences.md] | [`performance.draw_call_limit` in project.yaml, or technical-preferences.md] |
-| Memory ceiling | [from performance.* in project.yaml, else technical-preferences.md] | [`performance.memory_ceiling_mb` in project.yaml, or technical-preferences.md] |
+| Framerate | [value] | [`performance.target_framerate` in project.yaml, or technical-preferences.md] |
+| Frame budget | [value] | [`performance.frame_budget_ms` in project.yaml, or technical-preferences.md] |
+| Draw calls | [value] | [`performance.draw_call_limit` in project.yaml, or technical-preferences.md] |
+| Memory ceiling | [value] | [`performance.memory_ceiling_mb` in project.yaml, or technical-preferences.md] |
### Approved Libraries / Addons
- [library] — approved for [purpose] — source: technical-preferences.md
@@ -319,32 +287,17 @@ These APIs are deprecated or unverified for [engine + version]:
- Source: `docs/engine-reference/[engine]/deprecated-apis.md`
### Cross-Cutting Constraints
-- [constraint that applies everywhere, regardless of layer] — source: [ADR-NNNN, preference key or engine-reference file]
+- [constraint that applies in every layer] — source: [ADR-NNNN, preference key or engine-reference file]
```
----
-
-## 6. Suggest Next Steps
-
-After writing the manifest:
-
-- If epics/stories don't exist yet: "Run `/create-epics layer: foundation` then `/create-stories [epic-slug]` — programmers
- can now use this manifest when writing story implementation notes."
-- If this is a regeneration (manifest already existed): "Updated. Recommend
- notifying the team of changed rules — especially any new Forbidden entries."
-
----
-
-## Collaborative Protocol
+## Phase 6: Next steps
-**Applies in `collaborative` mode (the default).** For `guided` and
-`autonomous` modes, see `.claude/docs/automation-modes.md` — the rules below
-describe what collaborative mode requires, not universal behavior.
+- No epics yet: "Run `/create-epics layer: foundation`, then `/create-stories
+ [epic-slug]`: stories embed this manifest's rules and version."
+- A regeneration: "Updated. Tell the team about the changed rules, above all any
+ new Forbidden entries."
-1. **Load silently** — read all inputs before presenting anything
-2. **Show the summary first** — let the user see the scope before writing
-3. **Ask before writing** — always confirm before creating or overwriting the manifest. On write: Verdict: **COMPLETE** — control manifest written. On decline: Verdict: **BLOCKED** — user declined write.
-4. **Source every rule** — never add a rule that doesn't trace to an ADR, a
- technical preference, or an engine reference doc
-5. **No interpretation** — extract rules as stated in ADRs; do not paraphrase
- in ways that change meaning
+Every rule traces to an ADR, a technical preference or an engine reference doc;
+none is invented, and none is paraphrased in a way that changes its meaning. End
+with `Verdict: COMPLETE — control manifest written` after the write, or `Verdict:
+BLOCKED — user declined the write` when declined.
diff --git a/.claude/skills/create-epics/CONTRACT.md b/.claude/skills/create-epics/CONTRACT.md
index cb483d9b..ca738244 100644
--- a/.claude/skills/create-epics/CONTRACT.md
+++ b/.claude/skills/create-epics/CONTRACT.md
@@ -23,10 +23,13 @@ traceability — sits between architecture review and story decomposition.
> sections (+ conditional Formulas), only critical (Foundation-layer) ADRs are
> expected and traced, and the control manifest is read if present, not required.
> At `minimal` the skill is optional and off the path (`/create-stories`
-> synthesizes the epic itself); if run, it skips Steps 2a and 2b, reads only
-> `design/game-brief.md` (stopping if that is missing), takes its order from the
-> brief's Build order instead of `systems-index.md`, and requires no GDD, ADR,
-> architecture document, TR registry or control manifest.
+> synthesizes the epic itself), and it says so first; if run, it skips the GDD and
+> architecture reads, reads only `design/game-brief.md` (stopping if that is
+> missing), takes its order from the brief's Build order instead of
+> `systems-index.md`, and requires no GDD, ADR, architecture document, TR registry
+> or control manifest. A short brief is one epic slugged from the brief's working
+> title, the slug `/create-stories` uses when nothing is typed; a user who asks for
+> the work grouped gets one epic per group of MVP features.
### Preconditions
- `/create-control-manifest` has been run and `docs/architecture/control-manifest.md` exists
@@ -44,12 +47,12 @@ traceability — sits between architecture review and story decomposition.
### Output Guarantees
- Every EPIC.md contains a `## Governing ADRs` table with at least one row (or a documented note if none apply)
-- Every EPIC.md contains a `## GDD Requirements` table where each row has a `TR-ID` and an `ADR Coverage` cell (either `ADR-NNNN ✅` or `❌ No ADR`)
+- Every EPIC.md contains a `## GDD Requirements` table where each row has a `TR-ID` and an `ADR Coverage` cell: `ADR-NNNN ✅` (an Accepted ADR), `❌ No ADR`, or `❌ No ADR (ADR-NNNN Proposed)` when the only ADR addressing it is not Accepted, so `/create-stories` still sees that ADR and blocks its story
- The `GDD:` field in the EPIC.md header is a valid relative path to the source GDD
- The `Layer:` field is one of: Foundation, Core, Feature, Presentation
- The `Status:` field is set to `Ready`
- The `Stories:` field reads `Not yet created — run /create-stories [epic-slug]` on a new epic; an EPIC.md that already existed is updated in place (after an update-or-skip ask) and keeps its `Stories:` line and `## Stories` table
-- Untraced requirements (TR-IDs with no ADR) are flagged in the GDD Requirements table with `❌ No ADR`
+- Untraced requirements (TR-IDs with no Accepted ADR) are flagged in the GDD Requirements table with `❌ No ADR` and listed under Untraced Requirements; the ⚠️ warning fires for each at `full`, and at `standard` only for Foundation-layer ones
- `production/epics/index.md` has an entry for every epic written in this run
- A PR-EPIC review that could not judge the epics (no milestone timeline or team capacity) is reported as `PR-EPIC: NOT ASSESSED — [input]` and never read as REALISTIC
@@ -62,7 +65,7 @@ traceability — sits between architecture review and story decomposition.
- Never invent content not sourced from GDDs, ADRs, or architecture docs
- Never skip the per-epic approval prompt before writing
- Never write an EPIC.md without first presenting the epic definition to the user
-- Never overwrite an existing EPIC.md or reset its `## Stories` table — update it in place, or skip it
+- Never overwrite an existing EPIC.md or reset its `## Stories` table — update it in place, or skip it. `write-guard.sh overwrite` runs right before each new write and stops it when the file exists
- Never mark a TR-ID as covered by an ADR unless that ADR's `Status:` is `Accepted`
- Never create epics for a layer whose dependency layer is not yet substantially complete
@@ -83,6 +86,6 @@ It assumes:
## Known Fragile Points
- If the EPIC.md template structure changes (section names, header field names, table column order), `/create-stories` will silently fail to parse governance data and may produce incomplete or incorrect stories
- If `tr-registry.yaml` is regenerated with renumbered IDs after EPIC.md files are written, the TR-IDs in existing EPIC.md files become stale and mislead `/create-stories`
-- If an ADR is retroactively changed from `Accepted` to `Proposed` after the epic is written, the EPIC.md will still show it as governing — `/create-stories` will embed it without a BLOCKED flag
+- If an ADR is retroactively changed from `Accepted` to `Proposed` after the epic is written, the EPIC.md still shows it as governing. `/create-stories` reads every named ADR's current status with `adr-status.sh` and blocks the stories, but the epic's coverage column stays stale until `/create-epics` updates the epic in place
- If `systems-index.md` layer assignments change after epics are created, the `Layer:` field in existing EPIC.md files will be incorrect and `/create-stories` will use the wrong layer context
- `production/epics/index.md` rows are matched to epics by slug — an epic whose slug changes gets a new row, and the old row stays behind
diff --git a/.claude/skills/create-epics/SKILL.md b/.claude/skills/create-epics/SKILL.md
index b4bb7123..e61a921e 100644
--- a/.claude/skills/create-epics/SKILL.md
+++ b/.claude/skills/create-epics/SKILL.md
@@ -1,369 +1,267 @@
---
name: create-epics
-description: "Turn GDDs plus architecture into epics — one per architectural module, with untraced requirements. Then /create-stories [epic-slug]."
+description: "Turns the GDDs and architecture into epics, one per architectural module. Use when the user wants to break the game into epics or plan the work before writing stories. Not for splitting one epic into stories."
argument-hint: "[system-name | layer: foundation|core|feature|presentation | all] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/create-epics/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/create-epics/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/gdd-structure-check.sh*), Bash(bash .claude/scripts/adr-status.sh*), Bash(bash .claude/scripts/md-section.sh *), Bash(bash .claude/scripts/write-guard.sh overwrite *)
model: sonnet
---
-!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,docs.density,story_granularity,system_overrides`
+!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,workflow,docs.density,engine_values,system_overrides`
Resolved above — use as-is; `--review` overrides `review_mode`. No block →
defaults in `.claude/docs/config-resolution.md`.
+Ask with the question tool. Without one, list the options numbered and end your turn
+to wait. A skipped or dismissed question is not an answer: ask again in plain text.
# Create Epics
-An epic is a named, bounded body of work that maps to one architectural module.
-It defines **what** needs to be built and **who owns it architecturally**. It
-does not prescribe implementation steps — that is the job of stories.
+An epic is a bounded body of work for one architectural module: **what** gets built
+and which decisions govern it. How to build it is for the stories. Run it once per
+layer as development reaches that layer: Feature epics written before Core is
+nearly done describe a design that will have changed.
-**Run this skill once per layer** as you approach that layer in development.
-Do not create Feature layer epics until Core is nearly complete — the design
-will have changed.
+**Writes:** `production/epics/[epic-slug]/EPIC.md` per epic and its row in
+`production/epics/index.md`, each after its own yes.
+**Next:** `/create-stories [epic-slug]` per epic. This skill never writes a story.
-**Output:** `production/epics/[epic-slug]/EPIC.md` + `production/epics/index.md`
+Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided
+asks on major choices, autonomous logs and goes on; `automation_always_ask`
+categories always ask).
-**Next step after each epic:** `/create-stories [epic-slug]`
+Checklist (copy it and tick as you go):
-**When to run:** After `/create-control-manifest` and `/architecture-review` pass
-(at `full`). At `standard`, critical ADRs suffice, and a control manifest is
-read if present. At
-`minimal`, this skill is **optional and not part of the path** — `/create-stories`
-synthesizes the epic from `design/game-brief.md` itself (Option A). If run anyway,
-it decomposes directly from the brief with no GDD/ADR/manifest prerequisite.
-
-> **At `minimal`, this skill is optional — `/create-stories` synthesizes the epic**
-> (Option A). At that tier `/create-stories` reads `design/game-brief.md`
-> directly, writes a lightweight implicit `production/epics/<slug>/EPIC.md`, and
-> generates stories from the MVP list — so the path is `/brainstorm` →
-> `/create-stories` → `/dev-story`, with no separate `/create-epics` or
-> `/sprint-plan` step. **At `standard`/`full` an epic IS required**:
-> `/create-stories` reads `production/epics/[slug]/EPIC.md`, and skipping this
-> skill there leaves `/dev-story` with no story to implement — a dead end, not a
-> shortcut.
-
----
-
-## 1. Parse Arguments
-
-
-See `.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.
-
-
-Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
-(collaborative asks always · guided major-only · autonomous logs and proceeds;
-`automation_always_ask` categories always prompt).
-
-**`workflow`** (per `.claude/docs/workflow-modes.md`):
-
-create-epics runs project-wide: it uses the project-level tier for its
-prerequisite expectations and consults
-`workflow_overrides.system_overrides.<system>` per-system when reading each
-in-scope GDD. See "Workflow tier adjustment" in Step 2.
+```
+- [ ] Phase 1: scope and tier
+- [ ] Phase 2: inputs loaded and reported
+- [ ] Phase 3: each epic shown, "Shall I create Epic: …?" asked one at a time
+- [ ] Phase 4: producer review run, or its skip noted
+- [ ] Phase 5: each EPIC.md and index row written after its own yes
+- [ ] Phase 6: closing block printed
+```
-**`story_granularity`** — it sizes the
-epic's story breakdown: expect **3–5** child stories per epic at `coarse` (the default, via `rigor: minimal`), **5–10**
-at `balanced` (`rigor: standard`), **10–20** at `fine`.
+## Phase 1: Scope and tier
-**`docs.density`** — it controls the *depth* of each epic's written scope and
-rationale, not the story count (that is `story_granularity`). `modes.rigor` sets
-it alongside `workflow`; set `docs.density` explicitly to vary epic prose alone:
-`terse` (the default, via `rigor: minimal`) = scope as bullets, one-line rationale; `balanced` = a scope paragraph
-with light rationale (`rigor: standard`); `thorough` = full scope prose with governing-ADR
-rationale and risk discussion. The EPIC.md tables (GDD requirements, governing
-ADRs) are structural and stay whole at every density.
+The text typed after the skill name, with any `--review <mode>` pair removed:
-**Modes:**
-- `/create-epics all` — process all systems in layer order
-- `/create-epics layer: foundation` — Foundation layer only
-- `/create-epics layer: core` — Core layer only
-- `/create-epics layer: feature` — Feature layer only
-- `/create-epics layer: presentation` — Presentation layer only
-- `/create-epics [system-name]` — one specific system
-- No argument — ask: "Which layer or system would you like to create epics for?"
+- `all`: every system, in layer order.
+- `layer: foundation` (or `core`, `feature`, `presentation`): that layer only.
+- a system name: that system only.
+- nothing: the request's own words when they name a layer or system ("foundation
+ and core"); else ask "Which layer or system would you like epics for?"
----
+**Tier.** The project's `workflow` value sets what is required (Phase 2). Each
+in-scope system's own GDD bar comes from its `system_overrides` row, when it has one.
-## 2. Load Inputs
+**At `minimal`, tell the user first:** this step is optional at this tier, because
+`/create-stories` builds the epic from `design/game-brief.md` by itself. Then go on
+when they asked for epics.
-### Step 2a — Summary scan (fast, fail-open)
+## Phase 2: Load the inputs
-**At `minimal`, skip Steps 2a and 2b** — that tier decomposes from
-`design/game-brief.md` and has no GDDs by design (see the tier note below). Read
-the brief instead; if it is missing, report "No `design/game-brief.md` — run
-`/start` or `/brainstorm` first" and stop.
+### `minimal`: the brief
-**At `standard` and `full`, establish the denominator first.** Glob `design/gdd/*.md`, excluding the
-non-system docs — `game-concept.md`, `systems-index.md`, `game-pillars.md`,
-`gameplay-tags.md`, `entity-registry.md`, `fixture-swap-ledger.md`, any
-`gdd-cross-review-*.md`, `sound-bible.md` — the set `gdd-structure-check.sh`
-skips (the sound bible belongs in `design/audio/`; it is listed for projects
-that still keep it at the earlier location). Call the
-count **N**. If N is 0, there are no system GDDs — report "No system GDDs found
-in `design/gdd/` — run `/design-system` first" and stop.
+Read `design/game-brief.md`. None: stop, "No `design/game-brief.md` — run `/start`
+or `/brainstorm` first." Never ask for GDDs, a systems index, an architecture
+document, ADRs, a TR registry or a control manifest, and never send the user to
+`/design-system`, `/map-systems` or `/create-architecture` first: this tier has none
+by design.
-Scan for Summary sections:
+Report first, word for word:
```
-Grep pattern="^## Summary" glob="design/gdd/*.md" output_mode="content" -A 5
+Loaded: design/game-brief.md · engine [name version from the engine_values line]
+At minimal this step is optional: /create-stories builds the epic from the brief by itself.
```
-Interpret the **M** matches against N. These are three different outcomes, and
-a zero-match scan is **never** the same as "nothing in scope":
-
-| Result | Meaning | Action |
-|---|---|---|
-| **M = N** | Every GDD has a Summary. | For `layer:`/`[system-name]` modes, use the Summary Quick-reference (Layer/Priority) to pick the in-scope set; skip full-reading the rest. |
-| **0 < M < N** | Partial adoption — older GDDs predate `## Summary`. | Scope the M by their Summaries; determine the scope of the **N − M** unmatched from `systems-index.md` (layer/priority) and full-read those. |
-| **0 matches, N > 0** | Expected for GDDs authored before `/design-system` emitted `## Summary`. | Determine scope for **all N** from `systems-index.md` and full-read the in-scope set. This is the pre-optimization behaviour — correct, only more expensive. Note once: "No `## Summary` sections found across [N] GDDs — scoping from `systems-index.md` instead of Summary." |
-
-**Never treat an absent `## Summary` as an absent system.** The scan narrows the
-*read* set when it succeeds; it never shrinks the *in-scope* set. In `all` mode
-every system is in scope regardless of Summary, so the scan is a convenience
-only — never a filter.
-
-### Step 2b — Full document load (in-scope systems only)
-
-Using the Step 2a grep results, identify which systems are in scope. Read full documents **only for in-scope systems** — do not read GDDs or ADRs for out-of-scope systems or layers.
-
-Read for in-scope systems:
-
-- `design/gdd/systems-index.md` — authoritative system list, layers, priority
-- In-scope GDDs only (Approved or Designed status, filtered by Step 2a results)
-- `docs/architecture/architecture.md` — module ownership and API boundaries
-- Accepted ADRs **whose domains cover in-scope systems only** — skip ADRs for
- unrelated domains entirely. For each in-scope ADR, load only the "GDD
- Requirements Addressed", "Decision", and "Engine Compatibility" sections —
- never an unbounded full read:
- ```
- Grep pattern="^## (GDD Requirements Addressed|Decision|Engine Compatibility)" path="docs/architecture/[adr-file].md" output_mode="content" -n
- ```
- then `Read(offset, limit)` bounded to each match through the next `## `
- heading (or to end of file for the last match). This matters most on a
- large ADR.
-- `docs/architecture/control-manifest.md` — manifest version date from header
-- `docs/architecture/tr-registry.yaml` — for tracing requirements to ADR coverage
-- `docs/engine-reference/[engine]/VERSION.md` — engine name, version, risk levels
-
-Report: "Loaded [N] GDDs, [M] ADRs, engine: [name + version]."
-
-> **Workflow tier adjustment** (resolved in Step 1; per-system via
-> `system_overrides`). The inputs above are the `full` baseline:
-> - **`full`** — every in-scope GDD must be Approved with all 8 sections; TR
-> registry + control manifest are required inputs; untraced requirements
-> (Step 4) are flagged before proceeding.
-> - **`standard`** — GDDs need the 5 required sections (+ conditional Formulas)
-> approved; only **critical (Foundation-layer) ADRs** are expected; the control
-> manifest is read if present, not required. A system pinned higher via
-> `system_overrides` must still meet its higher bar.
-> - **`minimal`** — decompose against `design/game-brief.md` +
-> acceptance criteria. Do not require GDDs, ADRs, the TR registry, or the
-> manifest; skip the untraced-requirement gate. If run, the epic is still
-> produced — but note `/create-stories` also synthesizes one from the brief when
-> this skill is skipped (the default `minimal` path).
-
----
-
-## 3. Processing Order
-
-Process in dependency-safe layer order:
-1. **Foundation** (no dependencies)
-2. **Core** (depends on Foundation)
-3. **Feature** (depends on Core)
-4. **Presentation** (depends on Feature + Core)
+The epics come from the brief's MVP feature list, in its **Build order**. A short
+brief is one epic, slugged from the brief's working title (the slug `/create-stories`
+uses when nothing is typed). When the user asks for the work grouped, make one epic
+per group of MVP features that ship together. Every epic names its slug, since
+`/create-stories` needs it typed.
+
+### `standard` and `full`: the design and the architecture
+
+1. **The system GDDs.** `bash .claude/scripts/gdd-structure-check.sh` lists every
+ system GDD; the game concept, systems index, pillars, cross-reviews and the other
+ non-system documents are left out for you. Their count is **N**. N is 0: stop,
+ "No system GDDs found in `design/gdd/` — run `/design-system` first."
+2. **What is in scope.** Each GDD's `## Summary` quick reference gives its layer and
+ priority. A GDD with no Summary (older GDDs predate it) takes its layer from
+ `design/gdd/systems-index.md`. Never treat an absent `## Summary` as an absent system:
+ it never drops one from scope.
+3. **The architecture.** `docs/architecture/architecture.md` is required at both
+ tiers: missing, stop with
+ "No `docs/architecture/architecture.md` — run `/create-architecture` first." Never invent module boundaries.
+4. **For in-scope systems only**, by section, never whole:
+ - each GDD's Overview and Acceptance Criteria
+ (`bash .claude/scripts/md-section.sh extract design/gdd/<file>.md "Overview"`);
+ - `bash .claude/scripts/adr-status.sh` for every ADR's status, layer and missing
+ sections; then the GDD Requirements Addressed, Decision and Engine
+ Compatibility sections of the ADRs that cover in-scope systems;
+ - `docs/architecture/tr-registry.yaml`: the entries whose `system:` is an
+ in-scope system;
+ - the control manifest's `Manifest Version` line (read if present at `standard`,
+ required at `full`);
+ - `docs/engine-reference/<engine>/VERSION.md` for the engine's risk levels.
+
+Report before defining anything, with the real state:
-Within each layer, use the order from `systems-index.md`.
+```
+Loaded: [N] system GDDs, [n] in scope ([names]) · [M] ADRs ([A] Accepted, [P] Proposed) · manifest v[date | absent] · engine [name version from the engine_values line]
+```
-> **At `minimal` there is no `systems-index.md`** — `/map-systems` is not required
-> at that tier, so nothing has produced one. Derive the layer split and ordering
-> from `design/game-brief.md` instead: its **Build order** field names what must
-> exist first. Do not stop, and do not send the user to `/map-systems` to satisfy
-> an ordering hint — the tier deliberately skips it.
+At `full`, every in-scope GDD needs all 8 sections and Approved status, and the TR
+registry and control manifest are required. At `standard`, the GDDs need their 5
+required sections, and only critical (Foundation-layer) ADRs are expected.
----
+## Phase 3: Define each epic, ask one at a time
-## 4. Define Each Epic
+Process by layer: Foundation, then Core, Feature, Presentation; within a layer, the
+systems index order (at `minimal`, the brief's Build order). For each system, its
+module from `architecture.md` (at `minimal`, the brief's feature group).
-For each system, map it to an architectural module from `architecture.md`.
+**Requirement coverage** (not at `minimal`). Each TR-ID of the system is:
-Check ADR coverage against the TR registry **per the resolved tier** (Step 1):
-- **`full`** — trace every TR-ID; warn on each untraced requirement (below).
-- **`standard`** — only **critical (Foundation-layer) ADRs** are expected; trace
- those. Treat untraced non-critical requirements as informational (list them, do
- not block or emit the untraced-requirements warning).
-- **`minimal`** — skip this check entirely (no TR registry / ADR expected).
+- **covered** when an **Accepted** ADR addresses it;
+- **untraced** otherwise. A requirement whose only ADR is `Proposed` (or any other
+ status) is untraced, never covered: its row reads `❌ No ADR (ADR-NNNN Proposed)`,
+ so `/create-stories` still sees that ADR and blocks its story.
-- **Traced requirements**: TR-IDs that have an Accepted ADR covering them
-- **Untraced requirements**: TR-IDs with no ADR — warn before proceeding (full only)
-
-Present to user before writing anything:
+Untraced requirements are listed under **Untraced Requirements**. The ⚠️ warning
+below is for each untraced requirement at `full`, and only for untraced
+Foundation-layer requirements at `standard`; any other untraced requirement at
+`standard` is listed as information, with no warning.
```
## Epic: [System Name]
-
-**Layer**: [Foundation / Core / Feature / Presentation]
-**GDD**: design/gdd/[filename].md
-**Architecture Module**: [module name from architecture.md]
-**Governing ADRs**: [ADR-NNNN, ADR-MMMM]
-**Engine Risk**: [LOW / MEDIUM / HIGH — highest risk among governing ADRs]
-**GDD Requirements Covered by ADRs**: [N / total]
-**Untraced Requirements**: [list TR-IDs with no ADR, or "None"]
+**Layer**: [Foundation | Core | Feature | Presentation]
+**GDD**: design/gdd/[file].md (at minimal: design/game-brief.md, MVP features [list])
+**Architecture Module**: [module]
+**Governing ADRs**: [Accepted ADRs, or "none"]
+**Engine Risk**: [LOW | MEDIUM | HIGH — the highest among governing ADRs, else VERSION.md's]
+**Requirements covered by Accepted ADRs**: [n / total]
+**Untraced Requirements**: [TR-IDs with why, or "None"]
```
-If there are untraced requirements:
-> "⚠️ [N] requirements in [system] have no ADR. The epic can be created, but
-> `/create-stories` will write their stories with no governing ADR (`ADR: N/A`)
-> and `Status: Ready` — nothing downstream blocks them, so they would be
-> implemented without architectural guidance. Run `/architecture-decision` first
-> if they need a decision, or proceed and accept the gap."
+The warning, when it applies: "⚠️ [N] requirements in [system] have no Accepted ADR.
+Their stories will be written with no governing ADR, or Blocked on a Proposed one.
+Run `/architecture-decision` first if they need a decision, or go on and accept the
+gap."
-Use `AskUserQuestion`:
-- Prompt: "Shall I create Epic: [name]?"
-- Options:
- - `[A] Yes, create it`
- - `[B] Skip this epic`
- - `[C] Pause — I need to write ADRs first`
+Then ask, **for this epic alone**: "Shall I create Epic: [name]?" Options: Yes,
+create it / Skip this epic / Pause — I need to write ADRs first. Show and ask the
+next epic only after this answer. Never fold several epics into one question.
----
-
-## 4b. Producer Epic Structure Gate
-
-**Review mode check** — apply before spawning PR-EPIC:
-- `solo` → skip. Note: "PR-EPIC skipped — Solo mode." Proceed to Step 5 (write epic files).
-- `lean` → skip (not a PHASE-GATE). Note: "PR-EPIC skipped — Lean mode." Proceed to Step 5 (write epic files).
-- `full` → spawn as normal.
-
-After all epics for the current layer are defined (Step 4 completed for all in-scope systems), and before writing any files, spawn `producer` via `Agent` using gate **PR-EPIC** (`.claude/docs/director-gates/pr-epic.md`).
-
-Pass: the full epic structure summary (all epics, their scope summaries, governing ADR counts), the layer being processed, milestone timeline and team capacity.
-
-Present the producer's assessment.
+A yes covers the epic it answers, and only that one, even when it is worded for all
+("all of it", "go ahead with everything"): an epic is approved on sight. Show the
+next epic's block and ask again, until every epic in scope has been shown and
+answered.
-If UNREALISTIC: offer to revise epic boundaries (split overscoped or merge underscoped epics). Revise, present the revised epics again, and re-run the gate before writing.
+## Phase 4: Producer review
-If CONCERNS, use `AskUserQuestion`:
-- Prompt: "Producer raised concerns about the epic structure. How do you want to proceed?"
-- Options:
- - `[A] Proceed as planned — I accept the producer's concerns`
- - `[B] Revise epic boundaries — split or merge as recommended`
- - `[C] Stop — I want to reconsider the scope`
-
-If [A]: proceed to Step 5.
-If [B]: revise epic definitions from Step 4, present the revised epics to the user again, then re-run the producer gate.
-If [C]: stop. Verdict: **BLOCKED** — user wants to reconsider epic scope.
-
-If NOT ASSESSED [missing input] — e.g. no milestone timeline or team capacity — it
-is not a REALISTIC (`.claude/docs/director-gates.md`): name what was missing, then
-supply it and re-run the gate, or, if the user chooses to go on without it,
-proceed to Step 5 and state `PR-EPIC: NOT ASSESSED — [input]` in the output and
-the final Verdict line.
-
-Do not write epic files until the producer gate resolves.
-
----
+Read the `review_gate` line above. `skill-gates=skip` (solo or lean): no agent; note
+`PR-EPIC skipped — [Solo | Lean] mode` in the reply and the closing block.
+`skill-gates=run`: read `references/pr-epic-gate.md` and
+`.claude/docs/director-gates.md`, and run it now, after every epic in scope is
+defined and before any write. On a skip, do not load it.
-## 5. Write Epic Files
+## Phase 5: Write each epic
-**If `production/epics/[epic-slug]/EPIC.md` already exists, never overwrite it.**
-Ask instead: "An EPIC.md already exists for [name]. Update it in place, or skip
-it?" — `[A] Update in place — keep its Stories table, and update its index.md row` / `[B] Skip this epic`. An
-update rewrites only what this skill owns — the header fields other than
-`Stories`, `## Overview`, `## Governing ADRs`, `## GDD Requirements` and
-`## Definition of Done` — and leaves the `**Stories**` header line and any
-`## Stories` table exactly as they are: `/create-stories` wrote them, and
-resetting them to "Not yet created" orphans every story already in the directory.
+For each epic the user said yes to, in order:
-For a new epic, after approval, ask: "May I write `production/epics/[epic-slug]/EPIC.md` and add its row to `production/epics/index.md` (creating it if absent)?"
+**Already has an `EPIC.md`:** never overwrite it. Ask "An EPIC.md already exists for
+[name]. Update it in place, or skip it?" Options: Update in place / Skip this epic.
+An update edits only what this skill owns (the header fields other than Stories,
+Overview, Governing ADRs, GDD Requirements, Definition of Done) and leaves the
+`**Stories**` line and any `## Stories` table as they are: `/create-stories` wrote
+them, and resetting them orphans the stories already there.
-After user confirms, write:
+**New:** ask "May I write `production/epics/[epic-slug]/EPIC.md` and add its row to
+`production/epics/index.md`[, creating it]?" This is its own ask, one per epic, after
+the Phase 3 yes: that yes approved the epic, not the write. Write only on an explicit
+yes to it. Right
+before writing, run `bash .claude/scripts/write-guard.sh overwrite
+production/epics/[epic-slug]/EPIC.md`. It always prints a `checked` row; an
+`OVERWRITE` row back means the file exists after all, so write nothing and ask the
+update question instead.
-### `production/epics/[epic-slug]/EPIC.md`
+`docs.density` sets the depth of the Overview (`terse` bullets, `balanced` a short
+paragraph, `thorough` full prose with ADR rationale and risks); the tables stay
+whole at every density.
```markdown
# Epic: [System Name]
-> **Layer**: [Foundation / Core / Feature / Presentation]
-> **GDD**: design/gdd/[filename].md
-> **Architecture Module**: [module name]
+> **Layer**: [Foundation | Core | Feature | Presentation]
+> **GDD**: design/gdd/[file].md
+> **Architecture Module**: [module]
> **Status**: Ready
> **Stories**: Not yet created — run `/create-stories [epic-slug]`
## Overview
-[1 paragraph describing what this epic implements, derived from the GDD Overview
-and the architecture module's stated responsibilities]
+[What this epic implements, from the GDD Overview and the module's responsibilities]
## Governing ADRs
| ADR | Decision Summary | Engine Risk |
-|-----|-----------------|-------------|
-| ADR-NNNN: [title] | [1-line summary] | LOW/MEDIUM/HIGH |
+|-----|------------------|-------------|
+| ADR-NNNN: [title] | [one line] | LOW/MEDIUM/HIGH |
## GDD Requirements
| TR-ID | Requirement | ADR Coverage |
|-------|-------------|--------------|
-| TR-[system]-001 | [requirement text from registry] | ADR-NNNN ✅ |
-| TR-[system]-002 | [requirement text] | ❌ No ADR |
+| TR-[system]-001 | [requirement text from the registry] | ADR-NNNN ✅ |
+| TR-[system]-002 | [requirement text] | ❌ No ADR (ADR-NNNN Proposed) |
## Definition of Done
-This epic is complete when:
-- All stories are implemented, reviewed, and closed via `/story-done`
-- All acceptance criteria from `design/gdd/[filename].md` are verified
-- All Logic and Integration stories have passing test files in [the test root — `tests/` on Godot, `Assets/Tests/` on Unity, `Source/<Module>/Private/Tests/` on Unreal]
-- All Visual/Feel and UI stories have retained screenshots in `production/qa/evidence/` — each screen touched for UI, plus a lead sign-off for Visual/Feel
-
-## Next Step
-
-Run `/create-stories [epic-slug]` to break this epic into implementable stories.
+- Every story implemented, reviewed and closed with `/story-done`
+- Every acceptance criterion of design/gdd/[file].md verified
+- Logic and Integration stories have passing tests in the test root
+- Visual/Feel and UI stories have retained screenshots in `production/qa/evidence/`
+ (a lead sign-off too for Visual/Feel)
```
-### Update `production/epics/index.md`
+At `minimal`, the GDD line names `design/game-brief.md`, the Governing ADRs and GDD
+Requirements tables are left out, and a **Scope** list holds the epic's MVP
+features in Build order.
-Create or update the master index. An epic that already has a row keeps it:
-update that row in place and keep its `Stories` value — never append a second
-row, and never reset `Stories` to `Not yet created`:
+**`production/epics/index.md`:** one row per epic. An epic that already has a row
+keeps it: update it in place, never add a second row, never reset its Stories cell.
```markdown
# Epics Index
Last Updated: [date]
-Engine: [name + version]
+Engine: [name version]
| Epic | Layer | System | GDD | Stories | Status |
|------|-------|--------|-----|---------|--------|
-| [name] | Foundation | [system] | [file] | Not yet created | Ready |
+| [name] | [layer] | [system] | [file] | Not yet created | Ready |
```
----
-
-## 6. Gate-Check Reminder
-
-After writing all epics for the requested scope:
+## Phase 6: Close
-- **Foundation + Core complete**: These are required for the Pre-Production →
- Production gate. Run `/gate-check production` to check readiness.
-- **Reminder**: Epics define scope. Stories define implementation steps. Run
- `/create-stories [epic-slug]` for each epic before developers can pick up work.
+At `standard` and `full`, once Foundation and Core epics exist, add: "Foundation and
+Core epics are what the Pre-Production → Production gate needs. `/gate-check
+production` checks readiness." Never at `minimal`.
----
-
-## Collaborative Protocol
-
-**Applies in `collaborative` mode (the default).** For `guided` and
-`autonomous` modes, see `.claude/docs/automation-modes.md` — the rules below
-describe what collaborative mode requires, not universal behavior.
+Every epic's content comes from the GDDs, ADRs and architecture docs (the brief at
+`minimal`); none is invented.
-1. **One epic at a time** — present each epic definition before asking to create it
-2. **Warn on gaps** — flag untraced requirements before proceeding
-3. **Ask before writing** — per-epic approval before writing any file
-4. **No invention** — all content comes from GDDs, ADRs, and architecture docs
-5. **Never create stories** — this skill stops at the epic level
+**The run's last reply ends with this block** (repeat it if you showed it earlier):
-After all requested epics are processed:
+```
+Verdict: COMPLETE — [N] epics written: [slugs]
+Review: [PR-EPIC skipped — Solo mode | skipped — Lean mode | its verdict]
+Index: production/epics/index.md [created | updated]
+Next step: /create-stories [first-epic-slug]
+```
-- **Verdict: COMPLETE** — [N] epic(s) written. Run `/create-stories [epic-slug]` per epic.
-- **Verdict: BLOCKED** — user declined all epics, or no eligible systems found.
+When the user skipped or declined every epic: `Verdict: BLOCKED — no epic written
+([why])`. No in-scope system found: `Verdict: BLOCKED — no eligible systems in
+[scope]`.
diff --git a/.claude/skills/create-epics/references/pr-epic-gate.md b/.claude/skills/create-epics/references/pr-epic-gate.md
new file mode 100644
index 00000000..d648b873
--- /dev/null
+++ b/.claude/skills/create-epics/references/pr-epic-gate.md
@@ -0,0 +1,33 @@
+# Phase 4: Producer review (PR-EPIC)
+
+Read only when the `review_gate` line says `skill-gates=run` (`review_mode: full`).
+Run it once every epic in scope is defined and before any write. The agent reads its
+own gate file; do not read it here.
+
+Hand the review to the `producer` agent with gate **PR-EPIC**. Brief:
+
+- **Objective:** judge whether the epic structure for this layer is realistic to
+ deliver.
+- **Give it:** every epic defined in Phase 3 with its scope summary and governing
+ ADR count, the layer being processed, the milestone timeline and the team's
+ capacity (from `production/milestones/` and `project.yaml`'s `team.size`, or
+ "none recorded").
+- **Return:** REALISTIC, CONCERNS, UNREALISTIC, or NOT ASSESSED naming a missing
+ input, with reasons.
+- **Boundaries:** it writes no file.
+
+Act on the verdict:
+
+- **REALISTIC:** go to Phase 5.
+- **CONCERNS:** ask "The producer raised concerns about the epic structure. How do
+ you want to go on?" Options: Go on as planned — I accept the concerns / Revise the
+ epic boundaries / Stop — I want to rethink the scope. Revise: change the epics,
+ show them again, and run the review again. Stop: `Verdict: BLOCKED — user is
+ rethinking the epic scope`.
+- **UNREALISTIC:** offer to split overscoped epics or merge underscoped ones,
+ show the revised epics, and run the review again before writing.
+- **NOT ASSESSED:** it is not REALISTIC. Name what was missing, then supply it and
+ run it again; or, when the user chooses to go on without it, go to Phase 5 and
+ state `PR-EPIC: NOT ASSESSED — [input]` in the reply and the closing block.
+
+Write no epic until the review resolves.
diff --git a/.claude/skills/create-stories/CONTRACT.md b/.claude/skills/create-stories/CONTRACT.md
index 7906932f..83bc2951 100644
--- a/.claude/skills/create-stories/CONTRACT.md
+++ b/.claude/skills/create-stories/CONTRACT.md
@@ -11,8 +11,8 @@ and `/story-readiness` + `/dev-story`.
| File | Required Fields / Sections | Read-Only? |
|------|---------------------------|-----------|
| `production/epics/[epic-slug]/EPIC.md` | `Layer:`, `GDD:` path, `Architecture Module:`, `## Governing ADRs` table, `## GDD Requirements` table with TR-IDs | Yes |
-| `design/gdd/[filename].md` | All 8 required sections, especially `## Acceptance Criteria`, `## Formulas`, `## Edge Cases` | Yes |
-| `docs/architecture/adr-NNNN-[slug].md` (all governing ADRs) | `Status:`, `Decision`, `Implementation Guidelines`, `Engine Compatibility`, `Engine Notes` | Yes |
+| `design/gdd/[filename].md` | The sections required at the system's tier (all 8 at `full`; the 5 required + conditional Formulas at `standard`), especially `## Acceptance Criteria`, `## Formulas`, `## Edge Cases` | Yes |
+| `docs/architecture/adr-NNNN-[slug].md` (all governing ADRs) | `## Status`, `## Summary`, `## Decision` (incl. `### Implementation Guidelines`), `## Engine Compatibility`, `## Last Verified` / `## Date`, the `**Depends On**` row (read through `adr-status.sh`) | Yes |
| `docs/architecture/control-manifest.md` | Layer rules (required patterns, forbidden patterns, guardrails), `Manifest Version:` date in header | Yes |
| `docs/architecture/tr-registry.yaml` | All TR-IDs for the epic's system, with stable `id` values | Yes |
@@ -22,8 +22,8 @@ and `/story-readiness` + `/dev-story`.
> exists there, never rewriting it), needs no `/create-epics`
> run, and reads no GDD, ADR, control manifest or TR registry. Each story traces to
> `Brief MVP feature N` instead of a TR-ID, and its ADR lines read
-> `N/A (minimal — no ADRs)` (SKILL.md, the `minimal` branch of Step 2 and the
-> `minimal` field mapping in Step 6).
+> `N/A (minimal — no ADRs)` (SKILL.md, the `minimal` branch of Phase 2 and the
+> `minimal` field mapping in Phase 7).
### Preconditions
- `/create-epics` has been run and the target `EPIC.md` has `Status: Ready`
@@ -36,23 +36,24 @@ and `/story-readiness` + `/dev-story`.
### Files Written
| File | Guaranteed Fields / Sections | Notes |
|------|------------------------------|-------|
-| `production/epics/[epic-slug]/story-NNN-[slug].md` | `Epic:`, `Status:`, `Layer:`, `Type:`, `Manifest Version:`, `## Context` (GDD path + `TR-[system]-NNN` + ADR reference + ADR Decision Summary + Engine/Risk + Engine Notes + Control Manifest Rules), `## Acceptance Criteria`, `## Implementation Notes`, `## Out of Scope`, `## Test Evidence`, `## Dependencies` | Created per story |
+| `production/epics/[epic-slug]/story-NNN-[slug].md` | `Epic:`, `Status:`, `Layer:`, `Type:`, `Manifest Version:`, `## Context` (GDD path + `TR-[system]-NNN` + ADR reference + ADR Decision Summary + Engine/Risk + Engine Notes + Control Manifest Rules), `## Acceptance Criteria`, `## Implementation Notes`, `## Out of Scope`, `## Files`, `## Test Evidence`, `## Dependencies` | Created per story |
| `production/epics/[epic-slug]/EPIC.md` | `## Stories` table replacing the "Not yet created" placeholder | Updated in-place; a return visit appends rows for new stories only. At `minimal`, when none exists yet, the skill creates it from the brief, after the write ask names it |
| `production/epics/index.md` | The epic's `Stories` column set to `[N] stories` | Only when the index exists; otherwise the run prints `Epics index not updated: production/epics/index.md absent` |
### Output Guarantees
- Every story file contains a `TR-[system]-NNN` reference in its `## Context` section (or `TR-[system]-???` with a warning if the registry has no match) — at `minimal`, `Brief MVP feature N` instead
-- Every story file contains an `ADR Governing Implementation:` line referencing at least one ADR, or an explicit `No ADR applies` note
-- Every story file has a `Status:` field — either `Ready` or `Blocked` (if the governing ADR is `Proposed`, `Deprecated` or `Superseded`)
+- Every story file contains an `ADR Governing Implementation:` line referencing at least one ADR, or an explicit `ADR: N/A — [reason]` line
+- Every story file has a `Status:` field — either `Ready` or `Blocked` (if the governing ADR is `Proposed`, `Deprecated` or `Superseded`, or an ADR it depends on is not `Accepted`)
- Every story file has a `Type:` field — one of: Logic, Integration, Visual/Feel, UI, Config/Data
- Every story file has a `Manifest Version:` field matching the date from `docs/architecture/control-manifest.md`'s header at time of writing — at `minimal`, `N/A (minimal — no control manifest)`
- Every story file has a `## Test Evidence` section stating the expected evidence location for its type
- Every story file has a `## Acceptance Criteria` section with at least one checkbox item copied from the GDD — at `minimal`, derived from `design/game-brief.md` (its Player goal & fail state and the MVP feature the story implements)
-- Every story file has a `## Dependencies` section (may say "None" but is never omitted)
+- Every story file has a `## Dependencies` section naming each story it needs by path (may say "None" but is never omitted)
+- Every story file has a `## Files` section listing the code and test files it is planned to create or change; `/dev-story` replaces the list with the files it changed, and `/story-done` checks scope against it
- The EPIC.md `## Stories` table is updated with a row per story including `#`, `Story` title, `Type`, `Status`, and `ADR`
- Stories with a `Proposed` ADR have `Status: Blocked` and a note: `BLOCKED: ADR-NNNN is Proposed — accept it with /architecture-decision accept ADR-NNNN once decided`; a `Deprecated` or `Superseded` ADR blocks the same way, naming its successor
- Every story file has an `Engine` and a `Risk` field. `Risk` is taken from `docs/engine-reference/<engine>/VERSION.md`; when that file is missing or assigns no level, `Risk` is **`NOT ASSESSED (no VERSION.md risk rating)`** — never a guessed level
-- **`NOT ASSESSED` is an emittable value of the `Risk` field**, and downstream readers must handle it. `/dev-story` treats it as HIGH when deciding whether to spawn the engine specialist: an unknown risk is not a low one
+- **`NOT ASSESSED` is an emittable value of the `Risk` field**, and downstream readers must handle it. `/dev-story` treats it as HIGH when deciding whether to hand work to the engine specialist: an unknown risk is not a low one
## Immutability Rules
- READS but does NOT modify: the epic's GDD, all ADR files, `docs/architecture/tr-registry.yaml`, `docs/architecture/control-manifest.md`
@@ -88,4 +89,4 @@ It assumes:
- If `control-manifest.md` is regenerated with a new `Manifest Version:` date after stories are written, all existing stories will show a stale manifest version and fail the readiness manifest check — every story in the epic will need its `Manifest Version:` updated
- If a governing ADR is renumbered or its file is renamed after stories are written, the `ADR Governing Implementation:` reference in story files will point to a missing file and `/story-readiness` will BLOCK those stories
- If `tr-registry.yaml` deprecates or supersedes a TR-ID that is already embedded in story files, `/story-readiness` will flag those stories as NEEDS WORK
-- The EPIC.md Stories table update is append-style — if `/create-stories` is run twice for the same epic, duplicate rows will appear in the table
+- The EPIC.md Stories table update is append-style: a return visit appends rows only for new stories, so a hand-edited table that drops the story numbers can gain duplicate rows
diff --git a/.claude/skills/create-stories/SKILL.md b/.claude/skills/create-stories/SKILL.md
index cda1eea1..4640fa10 100644
--- a/.claude/skills/create-stories/SKILL.md
+++ b/.claude/skills/create-stories/SKILL.md
@@ -1,499 +1,325 @@
---
name: create-stories
-description: "Break one epic into implementable stories embedding TR-ID, ADR guidance, acceptance criteria. Reads the control manifest. After /create-epics."
+description: "Breaks one epic into implementable stories with acceptance criteria. Use when the user wants stories for an epic or the next batch of work to build. Not for turning the whole design into epics."
argument-hint: "[epic-slug | epic-path] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/create-stories/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/create-stories/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/adr-status.sh *), Bash(bash .claude/scripts/md-section.sh extract *), Bash(bash .claude/scripts/md-section.sh list *)
model: sonnet
---
-!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,docs.density,story_granularity,qa.level,system_overrides`
+!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,workflow,docs.density,story_granularity,qa.level,system_overrides`
Resolved above — use as-is; `--review` overrides `review_mode`. No block →
defaults in `.claude/docs/config-resolution.md`.
+Ask with the question tool. Without one, list the options numbered and end your turn
+to wait. A skipped or dismissed question is not an answer: ask again in plain text.
# Create Stories
-A story is a single implementable behaviour — small enough to complete in one
-focused session, self-contained, and fully traceable to a GDD requirement and
-an ADR decision. Stories are what developers pick up. Epics are what architects
-define.
+A story is one implementable behaviour: small enough for the size
+`story_granularity` sets, self-contained, and traced to a requirement and the
+decision that governs it. Run this skill once per epic, in dependency order:
+Foundation epics first, then Core, Feature, Presentation.
-**Run this skill per epic**, not per layer. Run it for Foundation epics first,
-then Core, and so on — matching the dependency order.
+**Writes:** `production/epics/[epic-slug]/story-NNN-[slug].md`, the epic's
+`EPIC.md` Stories table, and its row in `production/epics/index.md`.
+**Next:** `/dev-story [story-path]` at `workflow: minimal`; otherwise
+`/story-readiness [story-path]`, then `/dev-story`.
-**Output:** `production/epics/[epic-slug]/story-NNN-[slug].md` files
+Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided
+asks on major choices, autonomous logs and goes on; `automation_always_ask`
+categories always ask).
-**Previous step:** `/create-epics [system]`
-**Next step after stories exist:** `/story-readiness [story-path]` then `/dev-story [story-path]` —
-at `workflow: minimal`, `/dev-story [story-path]` directly (`/story-readiness` is not on the minimal path)
+Checklist (copy it and tick as you go):
----
-
-## 1. Parse Argument
-
-
-See `.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.
-
-
-Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
-(collaborative asks always · guided major-only · autonomous logs and proceeds;
-`automation_always_ask` categories always prompt).
-
-**`workflow`** for this epic's system (per `.claude/docs/workflow-modes.md`) —
-use the `system_overrides` row for `<system>` if the block lists one, else the
-project value. `<system>` is the epic slug / its GDD system. The tier sets which prerequisites block — see the note in Step 2.
-
-**`story_granularity`** — it sets each
-story's AC load: **5–10 ACs covering a whole feature** at `coarse` (the default, via `rigor: minimal`), **2–4 ACs
-covering one task** at `balanced` (`rigor: standard`), **1 AC** at `fine` (the story name is
-the AC restatement). Group or split ACs into stories to hit the target.
-
-**`docs.density`** — it controls the *depth* of each story's prose (context,
-implementation notes, ADR summary), not the AC count (that is
-`story_granularity`) and never the AC text itself. `modes.rigor` sets it
-alongside `workflow`; set `docs.density` explicitly to vary story prose alone:
-`terse` (the default, via `rigor: minimal`) = notes as bullets, no preamble; `balanced` = short context paragraph +
-notes (`rigor: standard`); `thorough` = full context, implementation guidance, and ADR
-rationale. The embedded TR-ID reference, ADR Version stamp, and acceptance
-criteria are structural and are never trimmed by density.
-
-- `/create-stories [epic-slug]` — e.g. `/create-stories combat`
-- `/create-stories production/epics/combat/EPIC.md` — full path also accepted
-- **A named epic that does not exist** — if `production/epics/[slug]/EPIC.md`
- (or the given path) is missing, stop at `standard`/`full`: "No epic at
- `production/epics/[slug]/EPIC.md`. Run `/create-epics` to create it, or check
- the slug with `ls production/epics/`." Do not decompose from a guess. At
- `minimal` there are no `/create-epics` epics to name and that skill is not on
- the path — say so, take Step 2's `minimal` branch, and name the slug it uses.
-- No argument — at `minimal` there are no epics yet (Option A): skip to Step 2's
- `minimal` branch and synthesize the epic from `design/game-brief.md`. At
- `standard`/`full`, ask "Which epic would you like to break into stories?" and
- Glob `production/epics/*/EPIC.md` to list available epics with their status.
-
- > **If that glob returns nothing at `standard`/`full`, stop — do not build a
- > question with no options.** Report:
- > "No epics found under `production/epics/`. Run `/create-epics layer: foundation`
- > first — an epic is what this skill decomposes."
- >
- > **The zero-epic path is load-bearing.** Asking which epic *and* globbing to
- > list them leaves an `AskUserQuestion` with nothing to offer when the glob is
- > empty. Route to `/create-epics` instead — it is named as **Previous step**
- > in this skill's own header.
- >
- > Note what this skill guarded and what it did not. Step 2's ADR validation is
- > thorough: three tiers, each with its own stop condition, and an explicit
- > message naming the missing file. That is the **deepest** input. The **first**
- > input — does an epic exist at all — went unchecked. Guarding the far end of a
- > chain while leaving the near end open is the shape to watch for.
- >
- > At `minimal` this does not apply: there are deliberately no epics, and the
- > branch above synthesizes one from the brief.
-
----
+```
+- [ ] Phase 1: epic found, tier resolved
+- [ ] Phase 2: inputs loaded, each ADR's status reported
+- [ ] Phase 3-4: stories drafted, typed, Ready or Blocked
+- [ ] Phase 5: QA lead review run, or its skip noted
+- [ ] Phase 6: story list shown, one ask to write
+- [ ] Phase 7: stories, EPIC.md and index.md written (or index absence said)
+- [ ] Phase 8: next step asked, closing block printed
+```
-## 2. Load Everything for This Epic
-
-> **`minimal` tier — synthesize the epic from the brief** (Option A). At
-> `minimal` there is no `/create-epics` step and usually no `EPIC.md`. Instead:
-> 0. **No `design/game-brief.md`?** Stop: "There is no brief to build stories
-> from yet — run `/brainstorm` first; it writes the one-page brief."
-> **An `EPIC.md` already at `production/epics/<slug>/`** — the named epic, or
-> the brief-title slug (`/create-epics` run anyway, or an earlier run of this
-> skill) — is the epic: use its scope, still traced to the brief, and never
-> rewrite it; Step 6 only appends its Stories table, and the Step 5 ask says
-> *update* `EPIC.md`.
-> **Stories already in `production/epics/<slug>/`?** This is a return visit —
-> `/help` sends a finished build order back here. Never rewrite an existing
-> `story-*.md` or the `EPIC.md`: read them, add stories only for brief items
-> they do not yet cover (or the new ones the user names), and number on from
-> the highest existing `story-NNN`. The one change `EPIC.md` gets is Step 6's:
-> a row per new story appended to its Stories table — existing rows and the
-> rest of the file stay as they are.
-> 1. Read `design/game-brief.md` in full (it is one page).
-> 2. Synthesize an implicit epic (first run only — a return visit keeps the
-> existing one): draft a lightweight
-> `production/epics/<slug>/EPIC.md`, where `<slug>` is the brief's slugified
-> working title (`mvp` if untitled) — goal = the brief's one-sentence pitch,
-> scope = its MVP feature list, ordering = its **Build order**. Keep it terse;
-> this is the container `/dev-story` and `/sprint-status` expect. It is written
-> in Step 6, with the stories, after the Step 5 ask names it — never before.
-> 3. Generate **one coarse story per MVP feature** (Step 3+), in Build-order
-> sequence, each traced to the brief (not a GDD/TR-ID). Leave stories unblocked
-> on ADR grounds — none exist at this tier.
-> Skip the GDD, control-manifest, TR-registry, and ADR reads below (none exist at
-> `minimal`), then continue to Step 3 with the synthesized epic.
-
-For `standard`/`full` (a `/create-epics` epic exists), read in full (these are small):
-
-- `production/epics/[epic-slug]/EPIC.md` — epic overview, governing ADRs, GDD requirements table
-- The epic's GDD (`design/gdd/[filename].md`) — at `full` read all 8 sections; at `standard` the 5 required sections (+ conditional Formulas); at `minimal` the GDD may not exist — work from the epic brief + acceptance criteria. Always prioritise Acceptance Criteria, Formulas, and Edge Cases where present.
-- `docs/architecture/control-manifest.md` — grep only this epic's layer (`Grep pattern="^## <layer> Layer Rules" path="docs/architecture/control-manifest.md" output_mode="content" -A 40`) plus the header Manifest Version date, not a full read of all layers
-- `docs/architecture/tr-registry.yaml` — grep only this system's entries (`Grep pattern="system: <slug>\s*$" path="docs/architecture/tr-registry.yaml" output_mode="content" -B1 -A5`, or `id: TR-<slug>-[0-9]`; the anchors keep `combat` from matching `combat-ai`), not the whole cross-system registry
-
-**Load each governing ADR by section — never with an unbounded full read.** A
-substantial ADR exceeds the 25k-token `Read` cap, and a capped read's only
-recovery is paging through the remainder — the most expensive possible way to
-read a file. Per ADR:
-
-1. **Map the headings** (cheap — line numbers only):
- ```
- Grep pattern="^## |^### Implementation Guidelines" path="docs/architecture/[adr-file].md" output_mode="content" -n
+## Phase 1: Epic and settings
+
+**Tier.** `workflow` for the epic's system: the `system_overrides` row for the epic
+slug (its GDD system) if there is one, else the project value.
+
+**`story_granularity`** sets each story's acceptance-criteria load. Group or split
+criteria to hit it:
+
+| `story_granularity` | ACs per story | Size |
+|---|---|---|
+| `coarse` (default, `rigor: minimal`) | 5-10 | a whole feature, multi-day |
+| `balanced` (`rigor: standard`) | 2-4 | one task, about one session |
+| `fine` | 1 | one criterion; the story name restates it |
+
+**`docs.density`** sets the depth of each story's prose (context, implementation
+notes, ADR summary), never the AC count or the AC text: `terse` (default) = bullet
+notes, no preamble; `balanced` = a short context paragraph plus notes; `thorough` =
+full context, guidance and ADR rationale. The TR-ID, ADR Version and acceptance
+criteria are never trimmed.
+
+**Which epic.** The text typed after the skill name, with any `--review <mode>`
+pair removed: an epic slug (`combat`) or a path (`production/epics/combat/EPIC.md`).
+With nothing typed, the epic the user's request names ("the loot epic") counts as
+named.
+
+- **Named, but no `EPIC.md` there:** at `standard` and `full`, stop: "No epic at
+ `production/epics/[slug]/EPIC.md`. Run `/create-epics` to create it, or check the
+ slug with `ls production/epics/`." Never decompose from a guess. At `minimal`,
+ say this tier needs no `/create-epics` epic, take Phase 2's `minimal` branch, and
+ name the slug it uses.
+- **Blank, at `minimal`:** take Phase 2's `minimal` branch.
+- **Blank, at `standard` or `full`:** list `production/epics/*/EPIC.md` with each
+ status, then ask: "Which epic would you like to break into stories?" with one
+ option per epic. **No epics found:** stop and say "No epics found under
+ `production/epics/`. Run `/create-epics layer: foundation` first." Never ask a
+ question with no options.
+
+## Phase 2: Load the inputs
+
+### `minimal`: build the epic from the brief
+
+1. **No `design/game-brief.md`:** stop. "There is no brief to build stories from
+ yet: run `/brainstorm` first; it writes the one-page brief." When the code root
+ already holds the game (10 or more source files), name `/reverse-document design
+ [code root]` instead.
+2. Read `design/game-brief.md` in full (one page).
+3. **The epic.** `<slug>` is the brief's working title, slugified (`mvp` if it has
+ none), or the epic the user named.
+ - `production/epics/<slug>/EPIC.md` exists: it is the epic. Use its scope, still
+ traced to the brief, and never rewrite it.
+ - It does not: draft one, written in Phase 7 only after the Phase 6 ask names
+ it. Goal = the brief's one-sentence pitch; scope = its MVP feature list;
+ order = its **Build order**. Keep it terse.
+ - Stories already in the folder (a return visit): never rewrite an existing
+ `story-*.md`. Add stories only for brief items they do not cover, or new ones
+ the user names, and number on from the highest existing `story-NNN`.
+4. **One story per MVP feature, in Build order**, each traced to the brief. No
+ story is blocked on ADR grounds: this tier has none.
+
+Read no GDD, control manifest, TR registry or ADR at `minimal`. Go to Phase 3.
+
+### `standard` and `full`: the epic and what governs it
+
+1. **The epic:** `production/epics/[epic-slug]/EPIC.md` in full (its layer, GDD,
+ governing ADRs, and the GDD Requirements table with TR-IDs).
+2. **The GDD:** its sections by heading, never the whole file:
+ `bash .claude/scripts/md-section.sh extract design/gdd/[file].md "Acceptance Criteria"`,
+ and the same for `Formulas`, `Edge Cases` and `Detailed Design` (exit 3: try
+ `Detailed Rules`, the design standard's name for the same section); at `full`
+ the other required sections too (`list` shows the headings).
+3. **The control manifest:** the epic's layer only, and the version:
+ `bash .claude/scripts/md-section.sh extract docs/architecture/control-manifest.md "[Layer] Layer Rules"`,
+ plus its `Manifest Version` line.
+4. **The TR registry:** this system's entries only: in
+ `docs/architecture/tr-registry.yaml`, the lines matching `system: <slug>\s*$`,
+ with each entry's `id` above and its text below. The anchor keeps `combat` from
+ matching `combat-ai`; `\s*` takes a Windows line ending.
+5. **The ADRs**, every one the epic names (governing, or in its requirements table,
+ Proposed ones included), in one call:
```
-2. **Bounded-read exactly the sections this skill consumes**, using the line
- numbers from the map to set `Read(offset, limit)` spans that end where the
- next section begins:
- - `## Summary` and `## Decision` (including its `### Implementation
- Guidelines` subsection) — these feed the story's ADR Decision Summary
- and Implementation Notes.
- - `## Engine Compatibility` — feeds the story's Engine, Risk, and Engine
- Notes fields. (Engine Notes is a *story* field derived from this
- section — it is not an ADR section name; do not search for one.)
-3. **Capture the `## Status` and the `## Last Verified` date** in one call:
+ bash .claude/scripts/adr-status.sh ADR-0001 ADR-0003 ...
```
- Grep pattern="^## (Status|Last Verified|Date)" path="docs/architecture/[adr-file].md" output_mode="content" -A 2
- ```
- The Status (Accepted / Proposed / …) is what Step 4 decides `Ready` vs
- `Blocked` on — never assume it. For the version, use `Last Verified`,
- falling back to `Date`, then to `unversioned` if both are absent. This becomes the story's `ADR Version` stamp — `/dev-story`
- uses it to decide whether it can trust this story's distilled summary
- instead of re-opening the ADR.
-
-Skip Context, Alternatives Considered, Consequences, Risks, and any
-Amendments Log unless a section you loaded explicitly cross-references one of
-their entries — then take only the referenced entry with one more bounded
-read. If the heading map comes back empty (a nonstandard ADR predating the
-template), fall back to one full `Read` — and if that read truncates at the
-cap, do **not** page through the remainder; grep for the story-relevant
-content directly and flag the ADR for
-`/architecture-decision retrofit [file]`.
-
-**ADR existence validation** (tier-gated — resolved in Step 1): After reading the governing ADRs list from the epic, confirm each referenced ADR file exists on disk.
-
-- **`full`** — if **any** referenced ADR file cannot be found, **stop immediately** before decomposing any story.
-- **`standard`** — stop only if a **critical (Foundation-layer) ADR** is missing; for a missing non-critical ADR, **warn and continue** (the story embeds the ADR reference and is set `Status: Blocked` until the ADR exists).
-- **`minimal`** — no ADR requirement; do **not** stop. Embed any ADR references that do exist; otherwise decompose against the brief + acceptance criteria and leave stories unblocked on ADR grounds.
-
-When stopping (full / standard-critical):
-
-> "Epic references [ADR-NNNN: title] but `docs/architecture/[adr-file].md` was not found.
-> Check the filename in the epic's Governing ADRs list, or run `/architecture-decision`
-> to create it. Cannot create stories until all referenced ADR files are present."
-
-At `full`, do not proceed to Step 3 until all referenced ADR files are confirmed present.
-
-Report: "Loaded epic [name], GDD [filename], [N] governing ADRs [ADR status], [manifest status]." State the **actual** situation for the resolved tier — e.g. "all confirmed present, control manifest v[date]" at full; "M present, K missing non-critical (embedded + Blocked)" at standard; "no ADRs / manifest required" at minimal. Do not assert "all confirmed present" if any referenced ADR was missing, or name a manifest version when none exists.
-
----
-
-## 3. Classify Stories by Type
-
-**Story Type Classification** — assign each story a type based on its acceptance criteria:
-
-| Story Type | Assign when criteria reference... |
-|---|---|
-| **Logic** | Formulas, numerical thresholds, state transitions, AI decisions, calculations |
-| **Integration** | Two or more systems interacting, signals crossing boundaries, save/load round-trips |
-| **Visual/Feel** | Animation behaviour, VFX, "feels responsive", timing, screen shake, audio sync |
-| **UI** | Menus, HUD elements, buttons, screens, dialogue boxes, tooltips |
-| **Config/Data** | Balance tuning values, data file changes only — no new code logic |
-
-Mixed stories: assign the type that carries the highest implementation risk.
-The type determines what test evidence is required before `/story-done` can close the story.
-
----
-
-## 4. Decompose the GDD into Stories
+ Each row gives the status, layer, `version` (the story's ADR Version stamp),
+ `depends_on`, and missing sections. Then read only `Summary`, `Decision` (its
+ Implementation Guidelines inside) and `Engine Compatibility` of each, with
+ `md-section.sh extract`. Engine Notes is a story field taken from Engine
+ Compatibility, not an ADR section. An ADR with none of these sections predates
+ the template: read it once, and flag it for `/architecture-decision retrofit
+ [file]`.
+
+**A named ADR with no file** (`NOT_FOUND`):
+
+- `full`: stop before decomposing any story.
+- `standard`: stop only when it is critical (Foundation layer); otherwise warn, go
+ on, and write the stories it governs as `Blocked` until it exists.
+- On stopping: "Epic references [ADR-NNNN: title] but no file for it was found in
+ `docs/architecture/`. Check the epic's Governing ADRs list, or run
+ `/architecture-decision` to create it. Cannot create stories until the
+ referenced ADR files exist."
+
+**Report before drafting**, with the real state, every ADR on its own with its
+status:
-For each GDD acceptance criterion:
-
-1. Group related criteria that require the same core implementation
-2. Each group = one story
-3. Order stories: foundational behaviour first, edge cases last, UI last
-
-**Story sizing rule:** size each story to the resolved `modes.story_granularity`
-target (above). The "~2-4 hours / one focused session" heuristic is the
-`balanced` target (`rigor: standard`) — at `coarse`, the default, a story spans a whole feature (5–10 ACs,
-multi-day), at `fine` a story is a single AC. Split or group criteria to hit the
-resolved target, not a fixed session length.
-
-For each story, determine:
-- **GDD requirement**: which acceptance criterion(ia) does this satisfy?
-- **TR-ID**: look up in `tr-registry.yaml`. Use the stable ID. If no match, use `TR-[system]-???` and warn.
-- **Governing ADR**: which ADR governs how to implement this?
- - `Status: Accepted` → embed normally
- - `Status: Proposed` → set story `Status: Blocked` with note: "BLOCKED: ADR-NNNN is Proposed — accept it with `/architecture-decision accept ADR-NNNN` once decided"
- - `Deprecated` or `Superseded by ADR-XXXX` → set story `Status: Blocked` with note: "BLOCKED: ADR-NNNN is [status] — point the story at [successor] (edit its ADR field — `/create-stories` never rewrites an existing story) before implementing"
- - **Multiple ADRs apply**: List all governing ADRs in the story's `Governing ADRs:` field. Designate the one most directly controlling the implementation pattern as primary (first in the list). Others are listed as secondary references.
- - **No ADR applies at all**: Write `ADR: N/A — [brief reason, e.g. "pure data configuration, no architectural pattern required"]` in the story's ADR field. Do NOT leave the field blank — a blank ADR field means "not checked", not "not applicable".
-- **Story Type**: from Step 3 classification
-- **Engine risk**: from the ADR's Knowledge Risk field
-
----
-
-## 4b. QA Lead Story Readiness Gate
-
-**Review mode check** — apply before spawning QL-STORY-READY:
-- `solo` → skip. Note: "QL-STORY-READY skipped — Solo mode." Proceed to Step 5 (present stories for review).
-- `lean` → skip (not a PHASE-GATE). Note: "QL-STORY-READY skipped — Lean mode." Proceed to Step 5 (present stories for review).
-- `full` → spawn as normal.
-
-After decomposing all stories (Step 4 complete) but before presenting them for write approval, spawn `qa-lead` **once** via `Agent` using gate **QL-STORY-READY** (`.claude/docs/director-gates/ql-story-ready.md`). A single call returns **both** the readiness verdict and the test-case specs — do not spawn `qa-lead` a second time to generate specs.
-
-Pass: the full story list inline — no story file exists yet, so the stories themselves stand in for the gate's story paths — with each story's acceptance criteria, story type, and TR-IDs with their requirement text from `tr-registry.yaml`; the epic's GDD acceptance criteria for reference. Require in the return:
-1. The QL-STORY-READY verdict per story (ADEQUATE / GAPS / INADEQUATE, or NOT ASSESSED naming a missing input).
-2. For every story it marks **ADEQUATE**, its test-case spec block (formats below) — one Given/When/Then per acceptance criterion for Logic and Integration stories, or manual verification steps for Visual/Feel and UI stories.
-
-Present the assessment, then act on each story's verdict — the gate's own words, handled per `.claude/docs/director-gates.md`:
-
-- **ADEQUATE** — keep the returned specs.
-- **GAPS** — use `AskUserQuestion`: `Revise flagged criteria` / `Accept and proceed` / `Discuss further`. Do not revise before the user chooses. On *Revise*, draft the revised criteria, show them, and re-request specs for just those stories in one follow-up call. On *Accept*, the criteria stay as written and the story carries no qa-lead specs — its `## QA Test Cases` reads `*Test cases not yet defined — run /qa-plan to generate them.*`
-- **INADEQUATE** — blocking: the story is not written as it stands. Revise its criteria with the user (draft, show, confirm), then re-request its specs; if the user will not revise it, drop it from this run and name it as dropped in the Step 5 list.
-- **NOT ASSESSED** [missing input] — not an ADEQUATE: name what was missing, then supply it and re-request that story's verdict, or write the story without qa-lead specs (the `/qa-plan` line above in its `## QA Test Cases`) and mark it `QL-STORY-READY: NOT ASSESSED — [input]` in the Step 5 list.
-
-Untestable criteria cannot be implemented correctly, so a story carries qa-lead specs only once it is ADEQUATE.
-
-**Prefer an existing QA plan when one already covers a story** — this substitutes for the qa-lead's specs, it does not add a spawn. Glob `production/qa/qa-plan-*.md` for the most recent file; if it holds test specs for stories in this epic (match titles/slugs in its Automated Tests Required section) that differ from the qa-lead's, use `AskUserQuestion` (Use QA-plan specs / Use qa-lead specs / Skip and leave `*Test cases not yet defined — run /qa-plan to generate them.*`). Either way no additional `qa-lead` spawn occurs.
-
-The spec block formats — Logic/Integration:
-
-```
-Test: [criterion text]
- Given: [precondition]
- When: [action]
- Then: [expected result / assertion]
- Edge cases: [boundary values or failure states to test]
-```
-
-For Visual/Feel and UI stories, produce manual verification steps instead:
```
-Manual check: [criterion text]
- Setup: [how to reach the state]
- Verify: [what to look for]
- Pass condition: [unambiguous pass description]
+Loaded: epic [name] · GDD [file] · manifest v[date], [layer] rules
+ADRs: ADR-0001 Accepted · ADR-0002 Accepted · ADR-0003 Accepted · ADR-0004 Proposed · [ADR-NNNN missing]
```
-These test case specs are embedded directly into each story's `## QA Test Cases` section. The developer implements against these cases. The programmer does not write tests from scratch — QA has already defined what "done" looks like.
+Never say "all present" when one is missing, or name a manifest version when there
+is none.
----
-
-## 5. Present Stories for Review
+## Phase 3: Type each story
-Before writing any files, present the full story list:
+| Type | When its criteria reference |
+|---|---|
+| **Logic** | formulas, thresholds, state transitions, AI decisions, calculations |
+| **Integration** | two or more systems, signals across boundaries, save/load round-trips |
+| **Visual/Feel** | animation, VFX, "feels responsive", timing, screen shake, audio sync |
+| **UI** | menus, HUD, buttons, screens, dialogue boxes, tooltips |
+| **Config/Data** | balance values and data files only, no new logic |
+
+A mixed story takes the type with the highest implementation risk. The type sets
+the evidence `/story-done` needs.
+
+## Phase 4: Draft the stories
+
+Group the requirements that need the same core implementation into one story, at
+the `story_granularity` load. Order: foundation behaviour first, edge cases later,
+UI last. For each story:
+
+- **Requirement:** the TR-ID from the registry, matched through the epic's GDD
+ Requirements table. Only when no entry matches, write `TR-[system]-???` and say
+ so.
+- **ADR:** the one that governs how to build it (the requirements table names it).
+ - `Accepted`: embed it.
+ - `Proposed`: `Status: Blocked`, with "BLOCKED: ADR-NNNN is Proposed — accept it
+ with `/architecture-decision accept ADR-NNNN` once decided".
+ - `Deprecated` or `Superseded`: `Status: Blocked`, with "BLOCKED: ADR-NNNN is
+ [status] — point the story at [successor] (edit its ADR field;
+ `/create-stories` never rewrites an existing story) before implementing".
+ - An `Accepted` ADR whose `depends_on` names an ADR that is not Accepted: Blocked
+ the same way, naming that ADR.
+ - Several apply: list them all, the most direct first.
+ - None applies: `ADR: N/A — [reason]`, e.g. "pure data configuration". Never
+ blank: blank means unchecked.
+- **ADR Version:** the story's **ADR Version** is the ADR's `## Last Verified`
+ date, else its `## Date`, else `unversioned` (the `version` column). `/dev-story`
+ trusts the story's ADR summary while this still matches the ADR.
+- **Engine risk:** from the ADR's Engine Compatibility (its knowledge risk).
+- **Estimate:** propose a t-shirt size from the criteria and the files the story
+ touches: `S` (a few hours), `M` (about a day) or `L` (several days). It is a
+ proposal: Phase 6 shows it and the user can change it. `/story-readiness` fails
+ a story whose Estimate is still the template's bracket, so never leave it.
+
+## Phase 5: QA lead review
+
+Read the `review_gate` line above. `skill-gates=skip` (solo or lean): no review;
+note "QL-STORY-READY skipped — [Solo | Lean] mode" in the Phase 6 list and the
+closing block. `skill-gates=run`: read `references/qa-lead-gate.md` and
+`.claude/docs/director-gates.md`, and run it now, before the Phase 6 ask. On a skip,
+do not load it.
+
+## Phase 6: Show the stories, ask once
```
## Stories for Epic: [name]
+ADRs: ADR-0001 Accepted · ADR-0002 Accepted · ADR-0004 Proposed (every ADR, from Phase 2)
-Story 001: [title] — Logic — ADR-NNNN
- Covers: TR-[system]-001 ([1-line summary of requirement])
+Story 001: [title] — Logic — ADR-0001 — Ready — Estimate M
+ Covers: TR-[system]-001 ([one-line requirement])
Test required: tests/unit/[system]/[slug]_test.[ext]
-Story 002: [title] — Integration — ADR-MMMM
+Story 002: [title] — Integration — ADR-0004 — BLOCKED (ADR-0004 is Proposed) — Estimate L
Covers: TR-[system]-002, TR-[system]-003
Test required: tests/integration/[system]/[slug]_test.[ext]
-Story 003: [title] — Visual/Feel — ADR-NNNN
+Story 003: [title] — Visual/Feel — ADR-0001 — Ready — Estimate S
Covers: TR-[system]-004
- Evidence required: retained screenshot in production/qa/evidence/ + sign-off in production/qa/evidence/[slug]-evidence.md
+ Evidence required: retained screenshot + sign-off in production/qa/evidence/[slug]-evidence.md
-[N stories total: N Logic, N Integration, N Visual/Feel, N UI, N Config/Data]
+[N stories: N Logic, N Integration, N Visual/Feel, N UI, N Config/Data; N Blocked]
+QL-STORY-READY: [skipped — Solo mode | its verdicts]
```
-Use `AskUserQuestion`:
-- Prompt: "May I write these [N] stories to `production/epics/[epic-slug]/`, and update `production/epics/[epic-slug]/EPIC.md` and `production/epics/index.md`?" — name every file Step 6 touches: at `minimal` say *create* `EPIC.md` only when none exists yet (the Step 2 draft, shown with the stories), and leave `index.md` out when it does not exist.
-- Options: `[A] Yes — write all [N] stories` / `[B] Not yet — I want to review or adjust first`
-
----
-
-## 6. Write Story Files
-
-For each story, write `production/epics/[epic-slug]/story-[NNN]-[slug].md`:
-
-> **At `minimal` tier the Context/traceability inputs do not exist** (no GDD, ADR,
-> TR registry, or control manifest). Fill the template from the brief instead —
-> apply this mapping exactly, so every run is deterministic rather than improvised:
-> - **GDD** → `design/game-brief.md`
-> - **Requirement** → `Brief MVP feature N` (the feature this story implements — NOT a `TR-[system]-NNN` ID)
-> - **ADR Governing Implementation / ADR Decision Summary / ADR Version** → `N/A (minimal — no ADRs)`
-> - **Manifest Version** and **Control Manifest Rules (this layer)** → `N/A (minimal — no control manifest)`
-> - **Engine** and **Risk** → read `docs/engine-reference/<engine>/VERSION.md`
-> (engine from `engine.name`). **Engine** is `engine.name` + `engine.version`.
-> **Risk** is the risk level that file assigns to the pinned version — its
-> post-cutoff timeline row, or its stated overall risk. If the file is missing
-> or assigns no level, write `NOT ASSESSED (no VERSION.md risk rating)` — never
-> guess a level.
->
-> > **This field is load-bearing and had no rule, so it was improvised.**
-> > `/dev-story` Phase 3 spawns the engine specialist as a mandatory secondary
-> > "when engine risk is HIGH (from the ADR or VERSION.md)". At `minimal` there
-> > is no ADR, so `VERSION.md` is the *only* source — and nothing here told this
-> > skill to read it. A story written with an invented `Risk: MEDIUM` against a
-> > `VERSION.md` rating of HIGH silently disables the specialist review.
-> > Treat `NOT ASSESSED` as HIGH for the spawn decision: an unknown risk is not
-> > a low one.
-> - **Engine Notes** → `none (no ADR engine-compatibility analysis at minimal)`
-> - The Acceptance-Criteria source line → "From `design/game-brief.md` (the **Player goal & fail state** field + the MVP feature this story implements), scoped to this story" — derive concrete, testable ACs from what the user wrote there rather than inventing them from a bare MVP bullet
-> - The **`## QA Test Cases`** section → at any tier where the QL-STORY-READY / qa-lead gate is skipped (`minimal`, or `lean`/`solo` review mode) no qa-lead specs are authored; write "*N/A — no qa-lead specs at this tier; implement against the Acceptance Criteria above*" rather than improvising test cases.
-> - Any **Test Evidence / DoD** line is governed by `qa.level`, not this template — at `qa.level: minimal` tests are **waived** (advisory, never "must exist and pass"), but a Visual/Feel or UI story's retained screenshot is not.
+At `minimal`, each line traces to `Brief MVP feature N`, there is no ADRs line, and
+there is one story per MVP feature: no extra stories for brief items outside the
+MVP list. Then
+ask: "May I write these [N] stories to `production/epics/[epic-slug]/`, and
+[create | update] `production/epics/[epic-slug]/EPIC.md` and update
+`production/epics/index.md`?" Options: Yes, write all [N] / Not yet, I want to
+adjust first; an adjustment can change any estimate. Name every file Phase 7 touches: *create* `EPIC.md` only when it
+does not exist, and leave `index.md` out when it does not exist. Write nothing
+before the yes.
-```markdown
-# Story [NNN]: [title]
-
-> **Epic**: [epic name]
-> **Status**: Ready
-> **Layer**: [Foundation / Core / Feature / Presentation]
-> **Type**: [Logic | Integration | Visual/Feel | UI | Config/Data]
-> **Estimate**: [hours or t-shirt size — fill before sprint planning]
-> **Manifest Version**: [date from control-manifest.md header]
-> **Last Updated**: [set by /dev-story when implementation begins]
-
-## Context
-
-**GDD**: `design/gdd/[filename].md`
-**Requirement**: `TR-[system]-NNN`
-*(Requirement text lives in `docs/architecture/tr-registry.yaml` — read fresh at review time)*
-
-**ADR Governing Implementation**: [ADR-NNNN: title]
-**ADR Decision Summary**: [1-2 sentence summary of what the ADR decided]
-**ADR Version**: [the ADR's `## Last Verified` date, else its `## Date`, else `unversioned`]
-
-**Engine**: [name + version] | **Risk**: [LOW / MEDIUM / HIGH]
-**Engine Notes**: [from ADR Engine Compatibility section — post-cutoff APIs, verification required]
-
-**Control Manifest Rules (this layer)**:
-- Required: [relevant required pattern]
-- Forbidden: [relevant forbidden pattern]
-- Guardrail: [relevant performance guardrail]
-
----
-
-## Acceptance Criteria
-
-*From GDD `design/gdd/[filename].md`, scoped to this story:*
-
-- [ ] [criterion 1 — directly from GDD]
-- [ ] [criterion 2]
-- [ ] [performance criterion if applicable]
-
----
-
-## Implementation Notes
-
-*Derived from ADR-NNNN Implementation Guidelines:*
-
-[Specific, actionable guidance from the ADR. Do not paraphrase in ways that
-change meaning. This is what the programmer reads instead of the ADR.]
-
----
-
-## Out of Scope
-
-*Handled by neighbouring stories — do not implement here:*
-
-- [Story NNN+1]: [what it handles]
-
----
-
-## QA Test Cases
+## Phase 7: Write
-*Written by qa-lead at story creation. The developer implements against these — do not invent new test cases during implementation. (At tiers where the QL-STORY-READY gate is skipped — `minimal`, or `lean`/`solo` review mode — no qa-lead specs exist; see the `minimal` mapping note above.)*
+### The story files
-**[For Logic / Integration stories — automated test specs]:**
+**Each story** is `production/epics/[epic-slug]/story-[NNN]-[slug].md`, laid out
+as `.claude/docs/templates/story.md`. Never reuse a story number. Write each file
+as a file, never through a shell command: a shell write skips the project's write
+checks.
-- **AC-1**: [criterion text]
- - Given: [precondition]
- - When: [action]
- - Then: [assertion]
- - Edge cases: [boundary values / failure states]
+At `minimal` there is no GDD, ADR, TR registry or manifest. Fill these fields
+exactly:
-**[For Visual/Feel / UI stories — manual verification steps]:**
-
-- **AC-1**: [criterion text]
- - Setup: [how to reach the state]
- - Verify: [what to look for]
- - Pass condition: [unambiguous pass description]
-
----
-
-## Test Evidence
-
-*Governed by `qa.level`: at `qa.level: minimal` tests are **waived** (advisory, never "must exist and pass"), but a Visual/Feel or UI story's retained screenshot is not.*
-
-**Story Type**: [type]
-**Required evidence**:
-- Logic: `tests/unit/[system]/[story-slug]_test.[ext]` — must exist and pass (`/story-done` checks that it EXISTS; pass/fail is established by `/gate-check` and `/smoke-check`, both later)
-- Integration: `tests/integration/[system]/[story-slug]_test.[ext]` OR playtest doc
-- Visual/Feel: a retained screenshot in `production/qa/evidence/` + sign-off in `production/qa/evidence/[story-slug]-evidence.md`
-- UI: a retained screenshot of each screen touched, in `production/qa/evidence/`
-- Config/Data: smoke check pass (`production/qa/smoke-*.md`)
-
-**Status**: [ ] Not yet created
-
----
-
-## Dependencies
-
-- Depends on: [Story NNN-1 must be DONE, or "None"]
-- Unlocks: [Story NNN+1, or "None"]
-```
-
-### Also update `production/epics/[epic-slug]/EPIC.md`
-
-At `minimal` with no `EPIC.md` yet, this is where the Step 2 draft is written, with the
-table below. Otherwise replace the "Stories: Not yet created" line with a
-populated table; if the table already exists (a return visit), append a row per
-new story and leave the existing rows as they are:
+| Field | Value at `minimal` |
+|---|---|
+| GDD | `design/game-brief.md` |
+| Requirement | `Brief MVP feature N`, never a TR-ID |
+| ADR Governing Implementation, ADR Decision Summary, ADR Version | `N/A (minimal — no ADRs)` |
+| Manifest Version, Control Manifest Rules | `N/A (minimal — no control manifest)` |
+| Engine | `engine.name` + `engine.version` |
+| Risk | the level `docs/engine-reference/<engine>/VERSION.md` gives the pinned version (its timeline row, or its overall rating). No file or no level: `NOT ASSESSED (no VERSION.md risk rating)`, never a guess. `/dev-story` reads NOT ASSESSED as HIGH |
+| Engine Notes | `none (no ADR engine-compatibility analysis at minimal)` |
+| Acceptance Criteria | from the brief's **Player goal & fail state** and the MVP feature, made concrete and testable; never invented from a bare bullet |
+
+At every tier:
+- **QA Test Cases:** when the review was skipped, write
+ `*N/A — no qa-lead specs at this tier; implement against the Acceptance Criteria above*`.
+ Never improvise test cases.
+- **Test Evidence:** `qa.level` governs it. At `qa.level: minimal` tests are
+ waived (advisory), but a Visual/Feel or UI story's retained screenshot is not.
+- **Estimate:** the size from Phase 6, with any change the user made.
+- **Dependencies:** name each story this one needs by its path.
+- **Files:** the code and test files the story is planned to create or change,
+ under the code root and test root. `/dev-story` replaces them with the real list.
+
+### `EPIC.md`
+
+At `minimal` with none yet, write the Phase 2 draft with the table
+below. Otherwise replace its "Stories: Not yet created" line with the table, or on
+a return visit append one row per new story and leave the rest of the file as it
+is:
```markdown
## Stories
| # | Story | Type | Status | ADR |
|---|-------|------|--------|-----|
-| 001 | [title] | Logic | Ready | ADR-NNNN |
-| 002 | [title] | Integration | Ready | ADR-MMMM |
+| 001 | [title] | Logic | Ready | ADR-0001 |
+| 002 | [title] | Integration | Blocked | ADR-0004 |
```
-### Also update `production/epics/index.md`
-
-Find the row in the index table matching this epic (by epic name or slug). Set its `Stories` column to `[N] stories`, where N is the epic's total story count after this run — the existing rows plus the ones just written, not only the new ones. If the index file does not exist, say so in one line — `Epics index not updated: production/epics/index.md absent` — and continue. Do not skip silently: the index is what a reader consults to learn which epics have stories, so an un-updated one keeps reporting `Not yet created` for work that now exists, and nothing else would ever reveal the gap.
-
----
-
-## 7. After Writing
-
-Use `AskUserQuestion` to close with context-aware next steps:
-
-Check:
-- Are there other epics in `production/epics/` without stories yet? List them.
-- Is this the last epic? If so, include `/sprint-plan` as an option — except at `workflow: minimal`, which has no sprints: the brief's build order is the plan.
+### `production/epics/index.md`
-Widget:
-- Prompt: "[N] stories written to `production/epics/[epic-slug]/`. What next?"
-- Options (include all that apply):
- - `[A] Start implementing — run /dev-story [first-story-path]` at `minimal`, `/story-readiness [first-story-path]` otherwise (Recommended)
- - `[B] Create stories for [next-epic-slug] — run /create-stories [slug]` (only if other epics have no stories yet)
- - `[C] Plan the sprint — run /sprint-plan new` (only if all epics have stories, and never at `minimal`)
- - `[D] Stop here for this session`
+Set the epic's `Stories` cell to `[N] stories`,
+the epic's total after this run. When the file does not exist, say so:
+`Epics index not updated: production/epics/index.md absent`.
-Note in output: "Work through stories in order — each story's `Depends on:` field tells you what must be DONE before you can start it."
+## Phase 8: Close
----
+If other epics in `production/epics/` have no stories, list them. Then ask:
+"[N] stories written to `production/epics/[epic-slug]/`. What next?" Options, those
+that apply:
-## Collaborative Protocol
+- Start implementing: `/dev-story [first-story-path]` at `minimal`,
+ `/story-readiness [first-story-path]` otherwise (recommended)
+- Create stories for [next epic]: `/create-stories [slug]` (only when an epic has
+ none)
+- Plan the sprint: `/sprint-plan new` (only when every epic has stories; never at
+ `minimal`, where the brief's build order is the plan)
+- Stop here for this session
-**Applies in `collaborative` mode (the default).** For `guided` and
-`autonomous` modes, see `.claude/docs/automation-modes.md` — the rules below
-describe what collaborative mode requires, not universal behavior.
+Never start implementation or write code: this skill stops at the story files.
+Acceptance criteria come from the GDD (the brief at `minimal`), implementation
+notes from the ADRs, rules from the manifest; none are invented.
-1. **Read before presenting** — load all inputs silently before showing the story list
-2. **Ask once** — present all stories for the epic in one summary, not one at a time
-3. **Warn on blocked stories** — flag any story with a Proposed ADR before writing
-4. **Ask before writing** — get approval for the full story set before writing files
-5. **No invention** — acceptance criteria come from GDDs, implementation notes from ADRs, rules from the manifest
-6. **Never start implementation** — this skill stops at the story file level
+**The run's last reply ends with this block**, after the question above is
+answered (repeat it if you showed it earlier):
-After writing (or declining):
+```
+Verdict: COMPLETE — [N] stories written to production/epics/[epic-slug]/ ([N] Ready, [N] Blocked)
+Review: [QL-STORY-READY skipped — Solo mode | skipped — Lean mode | its verdicts]
+Index: [production/epics/index.md updated | Epics index not updated: production/epics/index.md absent]
+Next step: [/dev-story [first-story-path] | /story-readiness [first-story-path]]
+```
-- **Verdict: COMPLETE** — [N] stories written to `production/epics/[epic-slug]/`. Run `/dev-story` (at `minimal`) or `/story-readiness` → `/dev-story` to begin implementation.
-- **Verdict: BLOCKED** — user declined. No story files written.
+When the user declines the write: `Verdict: BLOCKED — user declined. No story
+files written.`
diff --git a/.claude/skills/create-stories/references/qa-lead-gate.md b/.claude/skills/create-stories/references/qa-lead-gate.md
new file mode 100644
index 00000000..1c6b7148
--- /dev/null
+++ b/.claude/skills/create-stories/references/qa-lead-gate.md
@@ -0,0 +1,68 @@
+# Phase 5: QA lead review (QL-STORY-READY)
+
+Read only when the `review_gate` line says `skill-gates=run` (`review_mode: full`).
+Run it after the stories are drafted and before the Phase 6 write ask.
+
+**An existing QA plan first.** Look for the newest `production/qa/qa-plan-*.md`. If
+its Automated Tests Required section holds specs for stories in this epic (match by
+title or slug), they can stand in for the agent's specs. Where the two differ, ask:
+"Which test specs should these stories carry?" Options: The QA plan's / The QA
+lead's / None yet. "None yet" writes
+`*Test cases not yet defined — run /qa-plan to generate them.*` This never adds a
+second hand-off.
+
+**Hand the review to the `qa-lead` agent, once,** with gate **QL-STORY-READY**. The
+agent reads its own gate file; do not read it here. One report carries both the
+verdicts and the specs: never hand it a second job for the specs.
+
+Brief:
+- **Objective:** judge each drafted story's acceptance criteria for testability, and
+ write test specs for the ones that pass.
+- **Give it:** the full story list inline (no story file exists yet, so the stories
+ stand in for the gate's paths), each with its acceptance criteria, type, and
+ TR-IDs with their requirement text from `tr-registry.yaml`; and the epic GDD's
+ acceptance criteria for reference.
+- **Return:** per story, ADEQUATE, GAPS, INADEQUATE, or NOT ASSESSED naming a
+ missing input. For each ADEQUATE story, its spec block in the formats below: one
+ Given/When/Then per criterion for Logic and Integration, manual steps for
+ Visual/Feel and UI.
+- **Boundaries:** it writes no file.
+
+Act on each story's verdict:
+
+- **ADEQUATE:** keep its specs.
+- **GAPS:** ask: "How do you want to handle the flagged criteria?" Options: Revise
+ them / Accept and go on / Discuss further. Revise nothing before the answer. On
+ Revise: draft the new criteria, show them, and send just those stories back to
+ the agent in one follow-up brief. On Accept: the criteria stay, and the story's
+ QA Test Cases read `*Test cases not yet defined — run /qa-plan to generate them.*`
+- **INADEQUATE:** the story is not written as it stands. Revise its criteria with
+ the user (draft, show, confirm), then ask the agent for its specs. If the user
+ will not revise it, drop it from this run and name it as dropped in the Phase 6
+ list.
+- **NOT ASSESSED:** not an ADEQUATE. Name the missing input, then supply it and ask
+ again, or write the story without specs (the `/qa-plan` line) and mark it
+ `QL-STORY-READY: NOT ASSESSED — [input]` in the Phase 6 list.
+
+A story carries specs only once it is ADEQUATE: untestable criteria cannot be built
+correctly. The specs go in the story's `## QA Test Cases`; the user builds
+against them and does not invent new ones.
+
+Logic and Integration:
+
+```
+Test: [criterion text]
+ Given: [precondition]
+ When: [action]
+ Then: [expected result]
+ Edge cases: [boundary values or failure states]
+```
+
+Visual/Feel and UI:
+
+```
+Manual check: [criterion text]
+ Setup: [how to reach the state]
+ Verify: [what to look for]
+ Pass condition: [an unambiguous pass]
+```
diff --git a/.claude/skills/day-one-patch/SKILL.md b/.claude/skills/day-one-patch/SKILL.md
index dd7883aa..ec0f179f 100644
--- a/.claude/skills/day-one-patch/SKILL.md
+++ b/.claude/skills/day-one-patch/SKILL.md
@@ -4,7 +4,7 @@ description: "Day-one launch patch — focused fix for known issues found after
argument-hint: "[scope: known-bugs | cert-feedback | all]"
user-invocable: true
disable-model-invocation: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion
model: sonnet
---
diff --git a/.claude/skills/design-review/SKILL.md b/.claude/skills/design-review/SKILL.md
index d6347dcb..a63d8fba 100644
--- a/.claude/skills/design-review/SKILL.md
+++ b/.claude/skills/design-review/SKILL.md
@@ -3,7 +3,7 @@ name: design-review
description: "Reviews one design document for completeness, internal consistency, implementability, and design standards. Before handing to programmers."
argument-hint: "[path-to-design-doc] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/design-review/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/design-review/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/review-receipts.sh check *), Bash(bash .claude/scripts/review-receipts.sh hash *), Bash(bash .claude/scripts/gdd-structure-check.sh *), Bash(grep -E '^ - name:' design/registry/entities.yaml), Bash(grep -n -i -E *)
model: sonnet
---
@@ -53,40 +53,55 @@ Resolved mode controls how thorough this review is:
price and reproduces the same verdict.** Run:
```
-Bash: bash .claude/scripts/review-receipts.sh check "design/gdd/reviews/[doc-name]-review-log.md" "[target-doc-path]" "design/registry/entities.yaml"
+Bash: bash .claude/scripts/review-receipts.sh check "design/gdd/reviews/[doc-name]-review-log.md" "[target-doc-path]" "design/registry/entities.yaml" ".claude/skills/design-review/SKILL.md"
```
The registry is in the check because this review consults it for
cross-document facts — an unchanged GDD reviewed against a *changed*
registry can reach different conclusions, so the skip is only safe when
-**every** listed line reads `UNCHANGED` (an absent registry simply doesn't
-appear in the output and doesn't block the skip).
+**every** line reads `UNCHANGED` (a registry that never existed doesn't
+appear in the output and doesn't block the skip). This skill's file is in it
+because a changed skill reviews differently. The check also compares every
+other file the log stamps — the related GDDs, concept or brief and narrative
+files earlier reviews read — and prints `GONE:` for one that no longer exists.
+
+Then read the latest entry's `Review mode:` line. That review **covers** this
+run only when its mode is the same as or deeper than the mode resolved now
+(`full` > `lean` > `solo`) and its workflow is the same or deeper (`full` >
+`standard` > `minimal`). An entry without the line was written before it
+existed and covers nothing.
- **All `UNCHANGED`** and the log's latest entry carries a verdict — surface it:
- *"This document is byte-identical to its last review on [date] (verdict:
- [verdict])."* If that verdict was APPROVED, offer via `AskUserQuestion`:
+ *"This document is byte-identical to its last review on [date] ([mode]
+ review, verdict: [verdict])."* If that verdict was APPROVED and that review
+ covers this run, offer via `AskUserQuestion`:
`[A] Use the prior verdict (Recommended)` / `[B] Re-review anyway` —
`guided` proceeds with [A] and notes it; `autonomous` logs via
- `log_decision` and uses the prior verdict. If it was NEEDS REVISION or
+ `log_decision` and uses the prior verdict. If it was APPROVED but the
+ review asked for now is deeper than the logged one, say so — *"That was a
+ [mode] review at workflow [tier]; this run asks for [mode] at [tier]."* —
+ and offer `[A] Re-review at [mode] (Recommended)` / `[B] Use the prior
+ [mode] verdict`; `guided` and `autonomous` re-review (`autonomous` logs it
+ via `log_decision`). If it was NEEDS REVISION or
MAJOR REVISION NEEDED, say so plainly: the document has not changed since
it failed review — the prior findings stand; revising the document is the
next step, not re-reviewing it. Offer to display the prior findings from
the log.
-- **Only the registry line reads `CHANGED`** (doc `UNCHANGED`) — the prior
- verdict stands except for cross-document facts: re-verify the doc's
- registry-sourced values against the new registry and re-issue the verdict;
- escalate to a full re-review only if a conflict appears.
-- **Target doc `CHANGED` or `NEW`, or `RECEIPT: NONE`** — proceed with the
- full review below. **Do not offer a partial/delta re-review that skips
+- **The target doc and this skill's file `UNCHANGED`, and only the registry or
+ another stamped cross-document file `CHANGED`, `NEW` or `GONE`** — the prior
+ verdict stands except for cross-document facts: re-verify the doc's values
+ against the changed files and re-issue the verdict; escalate to a full
+ re-review if a conflict appears or that review does not cover this run.
+- **Target doc or this skill's file `CHANGED` or `NEW`, or `RECEIPT: NONE`** —
+ proceed with the full review below. **Do not offer a partial/delta re-review that skips
reading or re-analyzing unchanged sections.** A section-scoped re-review
misses defects a full review finds, and saves little or nothing.
"Unchanged since last review" only means
byte-identical to what was reviewed then — it says nothing about whether
- that prior pass was itself complete, and no amount of "scan everything
- anyway" instruction reliably overcame a model's attention naturally
- narrowing to the flagged change.
+ that prior pass was itself complete, and attention narrows to the flagged
+ change even under an instruction to scan everything anyway.
-Read the target design document in full. Read CLAUDE.md to understand project context and standards.
+Read the target design document in full. This step needs the whole GDD: read it in ranges by its headings (found with the Grep tool: pattern `^#`, content mode), since a whole-file Read over 40 KB is refused. Read CLAUDE.md to understand project context and standards.
**For cross-document facts, prefer the registry over sibling GDDs.** If
`design/registry/entities.yaml` exists **and lists entries for this system**,
@@ -124,7 +139,9 @@ everything "implied". Do not glob-read all of `design/gdd/`.
Bash: bash .claude/scripts/gdd-structure-check.sh [target-doc-path]
```
-It prints a `PRESENT:` list and, when applicable, an `ABSENT:` list. It reports
+It prints a `PRESENT:` list and, when applicable, an `ABSENT:` list and a
+`PLACEHOLDER:` list (present sections holding only `[To be designed]`: not yet
+written, so treat them as missing for the checklist). It reports
**presence only** and makes no REQUIRED/ADVISORY judgment — that is Step 2b's
job. It already accepts `## Detailed Design` as satisfying the `Detailed Rules`
requirement, so do not flag that as missing.
@@ -171,6 +188,25 @@ spot-read any section the verdict actually turns on.
- Does this create unintended interactions with other systems?
- Is this consistent with the game's established tone and pillars?
+**Registry values, wherever the GDD states them.** A value restated in a table,
+a catalogue entry or a variant note contradicts the registry as surely as one in
+Detailed Rules, and reading by section makes those bodies easy to skim. List the
+registry's entry names (`grep -E '^ - name:' design/registry/entities.yaml`),
+then search the whole target document once for all of them plus the numeric
+keys they carry, case-insensitive, writing each `_` as `[_ ]` so `goblin_scout`
+also matches "Goblin scouts":
+
+```
+grep -n -i -E 'goblin[_ ]scout|iron[_ ]sword|health|value[_ ]gold' [target-doc-path]
+```
+
+Check every line it prints against the registry, whatever section it sits in.
+A line that gives an entry a different value, even for one room, variant, level
+or exception, contradicts the owning GDD: list it under Required Before
+Implementation with its line number, this document's value and the registry's.
+With no registry entries, run the same search for the entities and values the
+related GDDs define.
+
---
## Phase 3b: Adversarial Specialist Review (full mode only)
@@ -222,7 +258,9 @@ Issue all `Agent` calls simultaneously. Do NOT spawn one at a time.
> Your job is NOT to validate this design — your job is to find problems.
> Challenge the design choices from your domain expertise. What is wrong,
> underspecified, likely to cause problems, or missing entirely?
-> Be specific and critical. Disagreement with the main review is welcome."
+> Be specific and critical. Disagreement with the main review is welcome.
+> Read the GDD by section: find the headings with the Grep tool (pattern `^#`,
+> content mode) and Read those ranges with offset and limit."
**Additional instructions per agent type:**
@@ -260,18 +298,21 @@ separately as "advisory at `standard`" — do not list them as missing.]
> **N is not 8 unless `workflow: full`.** The tier table earlier in this skill is
> authoritative: 8 required at `full`, 5 at `standard` (+ Formulas when the system
-> defines numeric rules), 0 at `minimal`. Hardcoding `/8` here
-> reintroduces the tier confusion in the presentation layer after the logic
-> layer already handles it — reporting a `standard` project as "5/8 missing Player
-> Fantasy, Formulas, Tuning Knobs" warns about three sections that project's own
-> configuration says it does not need, which trains the reader to ignore the
-> review.
+> defines numeric rules), 0 at `minimal`. Do not hardcode `/8` here: reporting a
+> `standard` project as "5/8 missing Player Fantasy, Formulas, Tuning Knobs"
+> warns about three sections that project's own configuration says it does not
+> need, which trains the reader to ignore the review.
### Dependency Graph
[List each declared dependency and whether its GDD file exists on disk]
- ✓ enemy-definition-data.md — exists
- ✗ loot-system.md — NOT FOUND (file does not exist yet)
+### Registry Values
+[The whole-document search from Phase 3: the terms searched, how many lines it
+printed, and each conflict with its line number. With nothing to search, say so:
+"No registry entries or related-GDD values: values not cross-checked."]
+
### Required Before Implementation
[Numbered list — blocking issues only. Each item tagged with source agent.]
@@ -377,6 +418,7 @@ Use a third `AskUserQuestion`:
If yes, append an entry in this format:
```
## Review — [YYYY-MM-DD] — Verdict: [APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED]
+Review mode: [full / lean / solo] · Workflow: [full / standard / minimal]
Scope signal: [S/M/L/XL]
Specialists: [list]
Blocking items: [count] | Recommended: [count]
@@ -385,19 +427,19 @@ Prior verdict resolved: [Yes / No / First review]
Findings:
- [BLOCKING] [section]: [one-line finding]
- [RECOMMENDED] [section]: [one-line finding]
-[output of: Bash: bash .claude/scripts/review-receipts.sh hash "[target-doc-path]" — plus "design/registry/entities.yaml" if the registry file exists]
+[output of: Bash: bash .claude/scripts/review-receipts.sh hash "[target-doc-path]" "design/registry/entities.yaml" ".claude/skills/design-review/SKILL.md" [every other file this review read for cross-document facts: the related GDDs in design/gdd/, design/gdd/game-concept.md or design/game-brief.md, the design/narrative/ files] — a file that does not exist prints `not stamped, no such file` and is left out]
```
Findings rules: one line per finding, named by the section it lives in;
write `- none` when the verdict carried no findings. This is documentation
for a human reader of the revision history, not a mechanism the skill reads
-back — a delta re-review that skipped re-analyzing unchanged sections was
-tried and reverted (see Phase 1) after measuring it against a full review.
+back.
The hash line is the receipt Phase 1 reads on the next run to detect a
byte-identical re-review — the one form of skip that's actually safe,
because the input is provably the same, not merely believed to be adequately
-covered by a prior pass. Always include it, whatever the verdict — an
+covered by a prior pass. Stamp every file the review read: Phase 1's check
+compares each stamped file on the next run, whether or not it names it. Always include it, whatever the verdict — an
unchanged document that previously FAILED review is exactly the case where
skipping a redundant re-review saves the most (the prior findings stand
verbatim).
@@ -409,7 +451,7 @@ verbatim).
Once the systems-index and review-log widgets are answered, check project state and show one final `AskUserQuestion`:
Before building options, read:
-- `design/gdd/systems-index.md` — find any system with Status: In Review or Needs Revision (other than the one just reviewed)
+- `design/gdd/systems-index.md` — find any system with Status: In Review or Needs Revision (other than the one just reviewed). Read it by section: find the headings with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit.
- Count `.md` files in `design/gdd/` (excluding game-concept.md, systems-index.md) to determine if `/review-all-gdds` is worth offering (≥2 GDDs)
- Find the next system with Status: Not Started in design order
diff --git a/.claude/skills/design-system/SKILL.md b/.claude/skills/design-system/SKILL.md
index 2132fac3..d5e37b13 100644
--- a/.claude/skills/design-system/SKILL.md
+++ b/.claude/skills/design-system/SKILL.md
@@ -3,7 +3,7 @@ name: design-system
description: "Section-by-section GDD authoring for one system — walks through each required section, cross-references dependencies."
argument-hint: "<system-name> [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/design-system/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/design-system/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/registry.sh *)
model: sonnet
---
@@ -94,7 +94,9 @@ If the session is interrupted (compaction, crash, new session):
1. Read `production/session-state/active.md` — it records the current system and
which sections are complete
2. Read `design/gdd/[system-name].md` — sections with real content are done;
- sections with `[To be designed]` still need work
+ sections with `[To be designed]` still need work. Read it by section: find the
+ headings with the Grep tool (pattern `^#`, content mode) and Read those
+ ranges with offset and limit.
3. Resume from the next incomplete section — no need to re-discuss completed ones
This is why incremental writing matters: every approved section survives any
diff --git a/.claude/skills/design-system/references/1-parse-arguments.md b/.claude/skills/design-system/references/1-parse-arguments.md
index 5143cd2a..cc6d5637 100644
--- a/.claude/skills/design-system/references/1-parse-arguments.md
+++ b/.claude/skills/design-system/references/1-parse-arguments.md
@@ -45,7 +45,9 @@ A system name or retrofit path is **required**. If missing:
If the argument starts with `retrofit` or the argument is a file path to an
existing `.md` file in `design/gdd/`, enter **retrofit mode**:
-1. Read the existing GDD file.
+1. Read the existing GDD file. Read it by section: find the headings with
+ the Grep tool (pattern `^#`, content mode) and Read those ranges with
+ offset and limit.
2. Identify which of the 8 **possible** sections are present (scan for section
headings): Overview, Player Fantasy, Detailed Design/Rules, Formulas,
Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria.
@@ -87,11 +89,10 @@ value.
The resolved tier determines which GDD sections are **required** (applied in §4).
**`## Summary` is required at every tier and is not one of the 8** — §5-pre
-authors it unconditionally (*"This runs at every tier"*), but it appeared in none
-of the per-tier lists below, and these lists are what other skills and gates
-apply. A GDD checked against a tier list alone would pass with no Summary, the
-one section `/review-all-gdds` and the tiered-loading readers depend on. Read
-every list below as "`## Summary`, plus:".
+authors it unconditionally (*"This runs at every tier"*). The per-tier lists
+below do not repeat it, and a GDD checked against a tier list alone would pass
+with no Summary, the one section `/review-all-gdds` and the tiered-loading
+readers depend on. Read every list below as "`## Summary`, plus:".
- `full` — all 8 sections
- `standard` — Overview, Detailed Design, Edge Cases, Dependencies, Acceptance
Criteria (5 required); **Formulas conditional** — required when the system
@@ -104,14 +105,13 @@ every list below as "`## Summary`, plus:".
of the engine, Formulas is required. **Player Fantasy and Tuning Knobs skipped**
unless `workflow_overrides` force them (`tuning_knobs: true` forces Tuning Knobs)
- > **Do not gate this on a category token.** A rule of the form "required when
- > the system category is combat / economy / progression / AI" does not work:
- > those four tokens are not what `/map-systems` writes — `templates/systems-index.md`
- > defines the categories as `Core · Gameplay · Progression · Economy ·
- > Persistence · UI · Audio · Narrative · Meta` and lists **combat and AI as
- > example systems under `Gameplay`**. A combat system categorised exactly as the
- > template instructs matches none of the four, and Formulas would be dropped for
- > the system most likely to need it.
+ > **Do not gate this on a category token.** A test such as "the category is
+ > combat / economy / progression / AI" matches tokens `/map-systems` does not
+ > write — `templates/systems-index.md` defines the categories as `Core ·
+ > Gameplay · Progression · Economy · Persistence · UI · Audio · Narrative ·
+ > Meta` and lists **combat and AI as example systems under `Gameplay`**. A
+ > combat system categorised exactly as the template instructs matches none of
+ > the four, and Formulas would be dropped for the system most likely to need it.
- `minimal` — a GDD is not required (the game brief replaces it). If invoked
voluntarily at minimal, author exactly the 5 standard sections (Overview,
Detailed Design, Edge Cases, Dependencies, Acceptance Criteria) — the
diff --git a/.claude/skills/design-system/references/2-gather-context.md b/.claude/skills/design-system/references/2-gather-context.md
index 0ddd1161..1da73b3b 100644
--- a/.claude/skills/design-system/references/2-gather-context.md
+++ b/.claude/skills/design-system/references/2-gather-context.md
@@ -14,7 +14,9 @@
- 2e: Technical Feasibility Pre-Check
Read all relevant context **before** asking the user anything. This is the skill's
-primary advantage over ad-hoc design — it arrives informed.
+primary advantage over ad-hoc design — it arrives informed. Read each GDD and ADR
+by section: find the headings you need with the Grep tool (pattern `^#`, content
+mode) and Read those ranges with offset and limit.
### 2a: Required Reads
@@ -55,10 +57,9 @@ primary advantage over ad-hoc design — it arrives informed.
> does not mistake a derivation for an indexed fact. Do **not** write a systems
> index to hold them: `/map-systems` owns that file (§5d).
>
-> Read literally without this rule, an overridden system resolves to `full`, falls
-> through to the fail-fast reads below, and aborts with *"No game concept found.
-> Run `/brainstorm` first"* — killing the escape hatch on step one of the very
-> configuration it was built for.
+> Without this rule, an overridden system resolves to `full`, falls through to
+> the fail-fast reads below, and aborts on its first step with *"No game concept
+> found. Run `/brainstorm` first"*.
- **Game concept**: Read `design/gdd/game-concept.md` — fail if missing:
> "No game concept found. Run `/brainstorm` first."
@@ -67,15 +68,14 @@ primary advantage over ad-hoc design — it arrives informed.
- **Target system**: Find the system in the index. If not listed, warn:
> "[system-name] is not in the systems index. Would you like to add it, or
> design it as an off-index system?"
-- **Entity registry**: If `design/registry/entities.yaml` exists, grep it for
- the entries this system owns and the entries that reference it:
+- **Entity registry**: If `design/registry/entities.yaml` exists, list the
+ entries this system owns and the entries that reference it, each whole:
```
- Grep pattern="source: design/gdd/[system-name].md" path="design/registry/entities.yaml" output_mode="content" -A 6
- Grep pattern="design/gdd/[system-name].md" path="design/registry/entities.yaml" output_mode="content" -B 8
+ bash .claude/scripts/registry.sh slice design/gdd/[system-name].md
```
`referenced_by:` is a block list (the key and its paths are on separate
- lines), so match the path with `-B 8` context to see the owning entry; a
- `referenced_by.*[system-name]` one-liner never matches it. Hold these
+ lines), so a grep for the path finds the line but not the entry that owns
+ it; `slice` prints the owning entry however long its list is. Hold these
in context as **known facts** — values that other GDDs have already
established and this GDD must not contradict.
- **Reflexion log**: Read `docs/consistency-failures.md` if it exists.
@@ -189,9 +189,7 @@ which you picked.
> `Gameplay` and `Core`. The Godot reference ships `animation, audio, input,
> navigation, networking, physics, rendering, ui` — **there is no
> `scripting.md` and no `core.md`**. So the majority of non-`Gameplay` systems
- > hit the absent branch every time, and `if it exists` turned that into
- > silence. Either the reference gains those two files or the check reports it;
- > until the former, do the latter.
+ > hit the absent branch every time: report it every time.
- Read `docs/engine-reference/[engine]/breaking-changes.md` for domain-relevant entries
- Find the domain-matching ADRs without reading every ADR to learn the field you
filter on — grep the Domain field first, then read only the matches:
diff --git a/.claude/skills/design-system/references/3-file-skeleton.md b/.claude/skills/design-system/references/3-file-skeleton.md
index 99b92ec3..edf0251e 100644
--- a/.claude/skills/design-system/references/3-file-skeleton.md
+++ b/.claude/skills/design-system/references/3-file-skeleton.md
@@ -106,15 +106,6 @@ Use the template structure from `.claude/docs/templates/game-design-document.md`
[To be designed]
```
-> **This skeleton and the template must stay identical in section set and
-> order.** They diverged once and it was invisible: the skeleton omitted
-> `## Game Feel` and `## Cross-References`, so §3's own rule — *"§4 cannot fill a
-> section §3 never created"* — made both unreachable **at every tier, `full`
-> included**, while §3's prose above still said *"every other section in the
-> template is scaffolded"*. Two agents authoring a combat GDD noticed the gap
-> only by opening the template. If you add a section to one file, add it to the
-> other in the same commit.
-
Ask: "May I create the skeleton file at `design/gdd/[system-name].md`?"
If the user declines: Stop with the following message:
diff --git a/.claude/skills/design-system/references/4-section-design.md b/.claude/skills/design-system/references/4-section-design.md
index a152a9b1..717678a2 100644
--- a/.claude/skills/design-system/references/4-section-design.md
+++ b/.claude/skills/design-system/references/4-section-design.md
@@ -259,10 +259,8 @@ The [formula_name] formula is defined as:
Do NOT write `[Formula TBD]` or describe a formula in prose without the variable
table. A formula without defined variables cannot be implemented without guesswork.
-> **These columns must match `templates/game-design-document.md` exactly.** They
-> did not: this block said `Symbol` where the template says `Source`, so a
-> correctly-authored GDD was wrong against whichever of the two its reader
-> happened to hold. `Source` is the column that stays, because it is what carries
+> **These columns match `templates/guidance/game-design-document-guide.md`
+> exactly; do not rename them.** The `Source` column carries
> the coding-standards rule *"gameplay values must be data-driven (external
> config), never hardcoded"* into the design document — a variable marked
> `data file` is a tuning knob, one marked `constant` is a deliberate exception,
@@ -357,9 +355,8 @@ system]". Flag any one-directional dependencies for correction.
**Agent delegation**: If formulas are complex, delegate to `systems-designer`
to derive tuning knobs from the formula variables.
-> The guard above was missing here while Sections B, C, D, E and H all carried
-> one — and this delegation names `systems-designer`, the same agent Section D's
-> guard has already told a `solo` run to skip. Read without it, `solo` skips the
+> This delegation names `systems-designer`, the same agent Section D's guard
+> already tells a `solo` run to skip. Without the guard above, `solo` skips the
> specialist for the formulas and then consults it for the knobs derived from
> those same formulas.
@@ -439,11 +436,8 @@ exactly once, so nothing falls through:
- `Narrative` — dialogue, quests, cutscenes, lore delivery
- `Audio` — by definition
-> **`Gameplay` is the row this table was missing.** It is the category
-> `/map-systems` assigns to combat, AI and movement — the largest bucket in most
-> action games. If it appears in **neither** this list nor the "all other" list
-> below, the skill has no defined behaviour for it and the author has to guess.
-> All nine categories must be covered between the two lists.
+> **`Gameplay` belongs in this list.** It is the category `/map-systems` assigns
+> to combat, AI and movement — the largest bucket in most action games.
For required systems: **spawn `art-director` via `Agent`** before drafting this section. Provide: system name, game concept, game pillars, art bible sections 1–4 if they exist. Ask them to specify: (1) VFX and visual feedback requirements for this system's events, (2) any animation or visual style constraints, (3) which art bible principles most directly apply to this system. Present their output; do NOT leave this section as `[To be designed]` for visual systems.
@@ -452,17 +446,15 @@ For required systems: **spawn `art-director` via `Agent`** before drafting this
- `lean` → skip unless this system's visual feedback is central to it (a `Gameplay` or `UI` system whose events the player reads to play). Otherwise draft without the agent.
- `full` → spawn as described above.
-> Sections B, C, D, E and H each carry this block and this spawn did not, while
-> being worded as mandatory (*"do NOT leave this section as `[To be designed]`"*).
-> Two agents in `solo` skipped it anyway, on the strength of the other five, and
-> both flagged the guess. `director-gates.md`'s *"solo → no director gates
-> anywhere"* governs director **gates**, not specialist spawns, so it did not
-> settle it — this block does.
+> This block applies even though the spawn above is worded as mandatory (*"do
+> NOT leave this section as `[To be designed]`"*). `director-gates.md`'s *"solo
+> → no director gates anywhere"* governs director **gates**, not specialist
+> spawns, so it does not settle this spawn — this block does.
**Game Feel is REQUIRED (mandatory — do not offer to skip) for `Gameplay` and
`UI`** — the categories whose systems the player directly operates, where
responsiveness, weight and snap are design targets rather than polish. It is
-optional for the other seven. The template argues the point itself: feel *"drives
+optional for the other seven. The template's guide argues the point itself: feel *"drives
animation budgets, input handling architecture, and hitbox timing. Retrofitting
feel targets after implementation is expensive."*
@@ -480,8 +472,7 @@ after the required sections.
> **At `minimal`, force nothing.** §1 says a voluntary `minimal` GDD is *"exactly
> the 5 standard sections"*, which contradicts a category rule that makes
> Visual/Audio or Game Feel mandatory. §1 wins: at `minimal` both drop to
-> optional and the whole set goes through the widget below. The contradiction is
-> real — an agent authoring a `minimal` inventory GDD hit it and had to choose.
+> optional and the whole set goes through the widget below.
Use `AskUserQuestion`:
- "The required sections for this workflow tier are complete. Which of the
@@ -494,15 +485,14 @@ Use `AskUserQuestion`:
skipped.
- **Recommended option**: "All of them" when the system has any dependency,
UI surface or player-facing feedback; "Just Cross-References and open
- questions" otherwise. `autonomous` needs a marked recommendation to pick —
- the three options previously carried none, unlike the Section A/B widgets,
- so an unattended run had nothing to choose by and defaulted to skipping.
+ questions" otherwise. `autonomous` needs a marked recommendation to pick:
+ without one an unattended run has nothing to choose by and skips.
Do **not** state a section count here. The required set is tier-dependent
(§1: 8 at `full`, 5 + conditional Formulas at `standard`, 5 at a voluntary
- `minimal`), so the previous hardcoded "8 required sections are complete" was
- false on every run below `full` — it told a `standard`-tier user that 8
- sections existed when 6 had been authored.
+ `minimal`), so a fixed "8 required sections are complete" is false on every
+ run below `full` — it tells a `standard`-tier user that 8 sections exist when
+ 6 have been authored.
For **Visual/Audio** (non-required systems): Coordinate with `art-director` and `audio-director` if detail is needed. Often a brief note suffices at the GDD stage.
diff --git a/.claude/skills/design-system/references/5-post-design.md b/.claude/skills/design-system/references/5-post-design.md
index d0f0dae9..9ada421d 100644
--- a/.claude/skills/design-system/references/5-post-design.md
+++ b/.claude/skills/design-system/references/5-post-design.md
@@ -40,13 +40,14 @@ the section cycle's Write step as for any other section.
### 5a: Self-Check
Read back the complete GDD from file (not from conversation memory — the file is
-the source of truth). Verify:
+the source of truth). This step needs the whole GDD: read it in ranges by its
+headings (found with the Grep tool: pattern `^#`, content mode), since a whole-file
+Read over 40 KB is refused. Verify:
- The `## Summary` and its Quick reference are populated (not the placeholder)
- Every section **required at this system's effective tier** has real content
(not placeholders) — §1: 8 at `full`, 5 + conditional Formulas at `standard`,
5 at a voluntary `minimal`. Do not verify against a fixed count of 8: below
- `full` that reports a correctly-authored GDD as incomplete, which is the same
- error already corrected in the optional-sections prompt above
+ `full` that reports a correctly-authored GDD as incomplete
- Formulas reference defined variables
- Edge cases have resolutions
- Dependencies are listed with interfaces
@@ -84,7 +85,7 @@ Scan the completed GDD for cross-system facts that should be registered:
- Named constants referenced by value in more than one place
**First check the registry exists** — §2a reads it *"if it exists"*, and this
-step never carried the same guard. At `standard` and below the file is often
+step needs the same guard. At `standard` and below the file is often
absent, and a grep against a missing path returns nothing, which is
indistinguishable from "no candidate is registered yet":
@@ -126,6 +127,13 @@ there are no `referenced_by` arrays to merge.)
If yes: append new entries and update `referenced_by` arrays. Never modify
existing `value` / attribute fields without surfacing it as a conflict first.
+After writing, run `bash .claude/scripts/registry.sh validate` and fix every row
+about an entry this write added or changed (a DUPLICATE, STATUS or LAYOUT row,
+or a PATH_MISSING row for a path it named) before you go on; name rows about
+other entries to the user rather than fixing them unasked. If the script is
+missing or prints nothing, say the registry check did not run, then re-read the
+entries you wrote against the rules in the file's header.
+
### 5c: Offer Design Review
Present a completion summary:
@@ -149,8 +157,8 @@ Present a completion summary:
After the GDD is complete (and optionally reviewed):
**First check the systems index exists.** §2a skips it at `minimal` because it is
-never written at that tier, and this step never carried the same guard — the same
-class of bug §5b was patched for. It bites hardest on a `minimal` project with a
+never written at that tier, and this step needs the same guard as §5b. It
+matters most on a `minimal` project with a
`system_overrides` bump, where the effective tier is `standard` or `full` and
nothing else in §5 hints the file may be absent.
@@ -160,7 +168,9 @@ nothing else in §5 hints the file may be absent.
index listing exactly one system.
- **Present** — continue:
-- Read the systems index
+- Read the systems index by section: find the headings you need with
+ the Grep tool (pattern `^#`, content mode) and Read those ranges with
+ offset and limit
- Update the target system's row:
- If design-review was run and verdict is APPROVED: Status → "Approved"
- If design-review was run and verdict is NEEDS REVISION or MAJOR REVISION NEEDED: Status → "Needs Revision" (that exact string — `/design-review` sets "In Review" only once the revisions are applied)
diff --git a/.claude/skills/dev-story/CONTRACT.md b/.claude/skills/dev-story/CONTRACT.md
index d8dbb9c5..06aeb3c7 100644
--- a/.claude/skills/dev-story/CONTRACT.md
+++ b/.claude/skills/dev-story/CONTRACT.md
@@ -8,9 +8,9 @@ Bridges planning and code by loading the full context for a single story (story
### Files That Must Exist
| File | Required Fields / Sections | Read-Only? |
|------|---------------------------|-----------|
-| `production/epics/**/*.md` (the story file) | `Status: Ready`, `TR-ID`, `Governing ADR`, `Manifest Version`, `## Acceptance Criteria`, `## Test Evidence`, `## Dependencies`, `## Out of Scope` | **Partially mutable.** This skill sets `Status:` to `In Progress` and updates `Last Updated:` before spawning any agent (Phase 2) — at `minimal` the story file is the only record of progress, since `sprint-status.yaml` is absent. On an ADR version mismatch answered `[A]` it sets `ADR Version` to the ADR's current version and refreshes `**ADR Decision Summary**` and `## Implementation Notes`; on a manifest mismatch answered `[A]`/`[B]` it sets `Manifest Version:` (and on `[B]` adds `Manifest-Note:`). Everything else in the story file is read-only to this skill |
+| `production/epics/**/*.md` (the story file) | `Status: Ready`, `TR-ID`, `Governing ADR`, `Manifest Version`, `## Acceptance Criteria`, `## Test Evidence`, `## Dependencies`, `## Out of Scope` | **Partially mutable.** This skill sets `Status:` to `In Progress` and updates `Last Updated:` before any agent runs (Phase 3), and at the end replaces `## Files` with the files changed — at `minimal` the story file is the only record of progress, since `sprint-status.yaml` is absent. On an ADR version mismatch answered "Re-read the changed ADR" it sets `ADR Version` to the ADR's current version and refreshes `**ADR Decision Summary**` and `## Implementation Notes`; on a manifest mismatch answered "Update" or "Use the old rules" it sets `Manifest Version:` (and on the latter adds `Manifest-Note:`). Everything else in the story file is read-only to this skill |
| `docs/architecture/tr-registry.yaml` | Entry matching the story's TR-ID with current `requirement` text | Yes |
-| `docs/architecture/adr-NNNN-[slug].md` (referenced ADR) | `## Status`, `## Last Verified` (else `## Date`) — grepped; `## Decision` (with its `### Implementation Guidelines`), `## Engine Compatibility`, `## ADR Dependencies` — read only on a version mismatch answered `[A]` | Yes — the ADR is never edited; a mismatch updates the story's stamp, not the ADR |
+| `docs/architecture/adr-NNNN-[slug].md` (referenced ADR) | `## Status`, `## Last Verified` (else `## Date`) — from `adr-status.sh`; `## Decision` (with its `### Implementation Guidelines`), `## Engine Compatibility`, `## ADR Dependencies` — read only on a version mismatch answered "Re-read the changed ADR" | Yes — the ADR is never edited; a mismatch updates the story's stamp, not the ADR |
| `docs/architecture/control-manifest.md` | `Manifest Version:` header, layer rules (required patterns, forbidden patterns, performance guardrails) | Yes |
| `project.yaml` | `engine.name`, `engine.version`, `naming.*`, `performance.*` — the primary source for each of these fields | Yes |
| `.claude/docs/technical-preferences.md` | Legacy fallback for any field above that is absent or empty in `project.yaml`; **sole** source for forbidden patterns and allowed libraries (deliberately never migrated), plus the `Engine Specialists` section | Yes — required only for fields absent from `project.yaml`, and always for forbidden patterns |
@@ -20,7 +20,8 @@ Bridges planning and code by loading the full context for a single story (story
> **Tier.** SKILL.md Phase 2 decides by `workflow`: the TR registry is required at
> `full`, optional at `standard` and not expected at `minimal`; a missing control
> manifest warns at `full`/`standard` and is not expected at `minimal`; an ADR
-> blocks only when the story references one that is missing or `Proposed`.
+> blocks when the story references one that is missing, `Proposed`, `Deprecated`
+> or `Superseded`.
### Preconditions
- The target story must have `Status: Ready` (validated by `/story-readiness` at `standard`/`full`; at `minimal`, `/create-stories` writes stories `Ready` and `/story-readiness` is not on the path)
@@ -35,9 +36,10 @@ Bridges planning and code by loading the full context for a single story (story
### Files Written
| File | Guaranteed Fields / Sections | Notes |
|------|------------------------------|-------|
-| `<code root>/[system]/[file].[ext]` | Doc-commented public APIs; no hardcoded gameplay values; follows ADR Implementation Guidelines and control-manifest required patterns | created or modified by sub-agent; code root resolved per `.claude/docs/code-root-resolution.md` |
-| `tests/unit/[system]/[story-slug]_test.[ext]` OR `tests/integration/[system]/[story-slug]_test.[ext]` | One test function per acceptance criterion (Logic/Integration stories only); naming per engine (`.claude/rules/test-standards.md`); no random seeds; no external I/O | created by sub-agent; path matches `## Test Evidence` in story |
-| `production/session-state/active.md` | `<!-- CHECKPOINT -->` block: current task (story path), next step, blocker, files in progress, run result | block overwritten, never appended (file created from `.claude/docs/templates/session-state.md` if absent) |
+| `<code root>/[system]/[file].[ext]` | Doc-commented public APIs; no hardcoded gameplay values; follows ADR Implementation Guidelines and control-manifest required patterns | created or modified by the programmer agent; code root resolved per `.claude/docs/code-root-resolution.md` |
+| `tests/unit/[system]/[story-slug]_test.[ext]` OR `tests/integration/[system]/[story-slug]_test.[ext]` | One test function per acceptance criterion (Logic/Integration stories only); naming per engine (`.claude/rules/test-standards.md`); no random seeds; no external I/O | created by the programmer agent; path matches `## Test Evidence` in story |
+| The story file's `## Files` section | The code and test files the programmer agent created or changed, one per line | replaced through `md-section.sh replace` (the section is added at the end when the story has none); named in the one In Progress ask, skipped when that ask is declined. `/story-done` checks scope against it |
+| `production/session-state/active.md` | `<!-- CHECKPOINT -->` block: current task (story path), next step, blocker, files in progress, run result | written on every outcome by `session-state.sh checkpoint`: the block is replaced, never appended (the file is created from `.claude/docs/templates/session-state.md` if absent) |
### Output Guarantees
- All source files follow the naming conventions in `project.yaml` (`naming.*`), falling back to `.claude/docs/technical-preferences.md` for any convention absent there
@@ -48,28 +50,28 @@ Bridges planning and code by loading the full context for a single story (story
- The implementation summary states a **verification** result — what was run against the written code (Godot: `.claude/scripts/godot-parse-check.gd` over the changed scripts; Unity: `commands.smoke`; Unreal: the editor-target build) and its exit code. When the engine binary is unavailable this is **`NOT VERIFIED — <reason>`**, never an inference that the code is fine because it reads correctly
- The implementation summary states a **run result** — `OBSERVED — <what was on screen>` with a retained screenshot under `production/qa/evidence/[story-slug]/`, `NOT VERIFIED — <reason>`, or `N/A — <reason>` (only for a story with genuinely nothing observable). `NOT VERIFIED` is a blocker at the default gate level for Visual/Feel and UI stories. The run is **not waived at `qa.level: minimal`** — tests are, the look is not. Procedure: `.claude/docs/run-and-observe.md`
- At `qa.level: minimal` no test file is written, and for a Logic or Integration story the summary says so explicitly (`Test evidence: waived at qa.level: minimal`); UI and Visual/Feel stories get no waiver line, because their screenshot still applies. A waived run and a run where tests were forgotten must not produce the same artifact
-- **`NOT ASSESSED` is an accepted inbound value of the story's `Risk` field** (`/create-stories` emits it when `VERSION.md` assigns no level). This skill treats it as HIGH for the engine-specialist spawn decision
+- **`NOT ASSESSED` is an accepted inbound value of the story's `Risk` field** (`/create-stories` emits it when `VERSION.md` assigns no level). The engine specialist checks every code story, so no Risk value can skip that check
- **Completion is not assumed.** If the programmer agent stopped early or its output fails to parse, the story is reported **INCOMPLETE** with the specific breakage named, and `Implementation Complete` is not emitted
## Immutability Rules
- READS but does NOT modify: `project.yaml`, `docs/architecture/tr-registry.yaml`, `docs/architecture/adr-NNNN-[slug].md`, all GDD files in `design/gdd/`, `docs/architecture/control-manifest.md`, `.claude/docs/technical-preferences.md` (legacy fallback), `docs/engine-reference/[engine]/VERSION.md`
-- MODIFIES, via sub-agent: `<code root>/**` (new/updated source files; code root resolved per `.claude/docs/code-root-resolution.md`) and the engine's test root (the new test file; `tests/` on Godot)
-- MODIFIES, itself, each after an ask that names the file (in `collaborative` mode; `.claude/docs/automation-modes.md` governs the others): the story file's `Status:`, `Last Updated:`, `ADR Version`, `**ADR Decision Summary**`, `## Implementation Notes`, `Manifest Version:` and `Manifest-Note:` (see the story row above); the story's entry in `production/sprint-status.yaml` (`status: in-progress`, top-level `updated`); a dependency story's `Status:` (dependency option `[C]` only); a Config/Data story's data file; on Unity, `Assets/Scripts/ScreenshotOnArg.cs`, written verbatim from `.claude/docs/run-and-observe.md` when the project has none
+- MODIFIES, through the programmer agents: `<code root>/**` (new/updated source files; code root resolved per `.claude/docs/code-root-resolution.md`) and the engine's test root (the new test file; `tests/` on Godot)
+- MODIFIES, itself, each after an ask that names the file (in `collaborative` mode; `.claude/docs/automation-modes.md` governs the others): the story file's `Status:`, `Last Updated:`, `## Files`, `ADR Version`, `**ADR Decision Summary**`, `## Implementation Notes`, `Manifest Version:` and `Manifest-Note:` (see the story row above); the story's entry in `production/sprint-status.yaml` (`status: in-progress`, top-level `updated`); a dependency story's `Status:` (that dependency answer only); a Config/Data story's data file; on Unity, `Assets/Scripts/ScreenshotOnArg.cs`, written verbatim from `.claude/docs/run-and-observe.md` when the project has none
- MODIFIES without an ask: `production/session-state/active.md` — its `<!-- CHECKPOINT -->` block is overwritten, never appended
-- Sets the story file's own `Status` field to `In Progress` only (Phase 2, before
- spawning any agent). Closing the story being implemented is the exclusive
+- Sets the story file's own `Status` field to `In Progress` only (Phase 3, before
+ any agent runs). Closing the story being implemented is the exclusive
responsibility of `/story-done`; the one other `Status` this skill writes is a
- dependency's `Complete` under option `[C]` (Hard Constraints)
+ dependency's `Complete` under that dependency answer (Hard Constraints)
## Hard Constraints (Never Violate)
-- Never marks a story `Status: Done` or `Status: Complete` on its own judgement — that belongs to `/story-done`. The one exception is a dependency the user states is already done (Phase 2 dependency option `[C]`): its `Status` is set to `Complete` only after "May I update [dependency path] Status to Complete?" is approved
-- Never begins implementation without loading the full context package (story, TR-ID from registry, ADR Decision + Implementation Guidelines — as distilled in the story, or re-read from the ADR after a mismatch answered `[A]` — control-manifest layer rules, engine prefs)
+- Never marks a story `Status: Done` or `Status: Complete` on its own judgement — that belongs to `/story-done`. The one exception is a dependency the user states is already done (the Phase 2 dependency answer "It is done, the status was never updated"): its `Status` is set to `Complete` only after "May I update [dependency path] Status to Complete?" is approved
+- Never begins implementation without loading the full context package (story, TR-ID from registry, ADR Decision + Implementation Guidelines — as distilled in the story, or re-read from the ADR after that mismatch answer — control-manifest layer rules, engine prefs)
- Never implements a story whose referenced ADR has `Status: Proposed`, `Deprecated` or `Superseded` — surface as a blocker
- Never writes a Logic or Integration story as complete without a test file at the path declared in `## Test Evidence`
- Never touches files listed in the story's `## Out of Scope` section without explicit user approval
- Never deviates from the ADR's Implementation Guidelines silently — deviations must be flagged in the summary
- Never modifies ADR files or GDD files under any circumstances
-- Source and test files are written by sub-agents via `Agent`; this orchestrator writes none directly, except the verbatim `ScreenshotOnArg.cs` capture script on Unity, after an ask
+- Source and test files are written by the programmer agents; this skill writes none directly, except the verbatim `ScreenshotOnArg.cs` capture script on Unity, after an ask
## Downstream Skill Expects
**Next skill:** `/story-done`
@@ -82,5 +84,5 @@ Bridges planning and code by loading the full context for a single story (story
- If the story's embedded `Manifest Version` differs from the current `docs/architecture/control-manifest.md` header date, rules may have changed since the story was authored — the skill surfaces this, but silently proceeding would produce code that violates newer manifest rules
- The test file path in `## Test Evidence` must be exact: `/story-done` uses that literal path for Glob checks; a typo here causes a false BLOCKING result downstream
- If `docs/architecture/tr-registry.yaml` has a stale `requirement` text that diverges from the GDD, the implementation may satisfy the registry but fail the GDD — always treat the registry as authoritative per design, but flag if a visible discrepancy is noticed
-- Sub-agent task failures are non-fatal by design (partial reports are surfaced), but a blocked programmer sub-agent means no source files are written — `/story-done` will then fail its file-existence checks
+- Agent failures are non-fatal by design (partial reports are surfaced), but a blocked programmer agent means no source files are written — `/story-done` will then fail its file-existence checks
- Config/Data stories produce no test file; `/story-done` must see `Type: Config/Data` in the story header to classify the story correctly — otherwise it resolves the test-evidence gate for the wrong type (e.g. Logic, which is BLOCKING by default) and may flag a missing test
diff --git a/.claude/skills/dev-story/SKILL.md b/.claude/skills/dev-story/SKILL.md
index 95da9b46..e7fd26f8 100644
--- a/.claude/skills/dev-story/SKILL.md
+++ b/.claude/skills/dev-story/SKILL.md
@@ -1,161 +1,316 @@
---
name: dev-story
-description: "Implement a story: ADR guidelines, right programmer agent, code plus test. Then /story-done (/story-readiness before, /code-review after, at standard/full)."
+description: "Implements one story in code with tests, following its ADRs. Use when the user says to build, implement or start working on a story. Not for checking readiness beforehand or closing the story after."
argument-hint: "[story-path]"
user-invocable: true
disable-model-invocation: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/dev-story/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/dev-story/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/story-facts.sh *), Bash(bash .claude/scripts/adr-status.sh *), Bash(bash .claude/scripts/md-section.sh *), Bash(bash .claude/scripts/session-state.sh *), Bash(bash .claude/scripts/review-receipts.sh hash *), Bash(godot *), Bash(mkdir -p production/qa/evidence/*)
model: sonnet
---
-!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,story_granularity,qa.level,testing.strict,system_overrides`
+!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,qa.level,gate_level,engine_values,specialists,perf_budgets,system_overrides`
Resolved above — use as-is. No block → defaults in
`.claude/docs/config-resolution.md`.
-# Dev Story
-
-This skill bridges planning and code. It reads a story file in full, assembles
-all the context a programmer needs, routes to the correct specialist agent, and
-drives implementation to completion — including writing the test.
-
-**The loop for every story:**
-```
-/qa-plan sprint ← define test requirements before sprint begins
-/story-readiness [path] ← validate before starting
-/dev-story [path] ← implement it (this skill)
-/code-review [files] ← review it
-/story-done [path] ← verify and close it
-```
-
-**At `workflow: minimal`** the loop is `/dev-story [path]` → `/story-done [path]`:
-no QA plan, readiness check or sprint. `/story-done` names the next story.
-
-**With a sprint plan, after all sprint stories are done:** run `/team-qa sprint` to execute the full QA cycle and get a sign-off verdict before advancing the project stage.
-
-**Output:** Source code under the project's **code root** + test file under the engine's **test root** (`tests/` Godot, `Assets/Tests/` Unity, `Source/<Module>/Private/Tests/` Unreal — `.claude/docs/directory-structure.md`). Resolve the code root from `engine.name` (`src/` Godot, `Assets/` Unity, `Source/<Module>/` Unreal) per `.claude/docs/code-root-resolution.md`.
-
----
-
-Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
-(collaborative asks always · guided major-only · autonomous logs and proceeds;
-`automation_always_ask` categories always prompt).
-
-**Workflow tier**: resolved per the story's system (per
-`.claude/docs/workflow-modes.md`) — **the GDD filename stem** of the story's
-`GDD:` path (`design/gdd/<stem>.md` → `<stem>`), with the `[system]` segment of
-its `TR-[system]-NNN` ID accepted only as a fallback alias: use the
-`system_overrides` row for that system if the block lists one, else the
-project value. Resolve it at the start of Phase 2 (the story header is
-read there) and apply it to the prerequisite gate.
-
-**`story_granularity`** — it sets the
-expected implementation cycle: **multi-day** at `coarse` (the default, via `rigor: minimal`; give the programmer
-subagent longer working context), **1–2 days** at `balanced` (`rigor: standard`), **hours**
-at `fine` (tighter context). It does not change the prerequisite gate.
-
-**`qa.level`**: controls whether the programmer brief carries
-a test requirement. At `minimal`, omit the "Test requirement" line (Phase 4 item 7)
-— tests are not required; at `standard`, include the per-type test requirement; at
-`full`, also pass a coverage target. Distinct from `workflow: minimal`. When tests
-are not required (`minimal`), the Phase 5 `testing.strict` gate is a no-op.
-
-## Phase 1: Find the Story
-
-**If a path is provided**: read that file directly.
-
-**If no argument**: check `production/session-state/active.md` for the active
-story. If found, confirm: "Continuing work on [story title] — is that correct?"
-If not found, ask: "Which story are we implementing?" Glob
-`production/epics/**/*.md` and list stories with Status: Ready.
-
----
+Ask with the question tool. Without one, list the options numbered and end your turn
+to wait. A skipped or dismissed question is not an answer: ask again in plain text.
-## Phase 2: Load Full Context
-
-**Read `references/2-load-context.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
-
-## Phase 3: Route to the Right Programmer
-
-**Read `references/3-route.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
-
-## Phase 4: Implement
-
-**Read `references/4-implement.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
-
-## Phase 5: Test Evidence Requirements
-
-**Read `references/5-test-evidence.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
-
-## Phase 6: Collect and Summarise
-
-**Read `references/6-collect.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
+# Dev Story
-## Phase 7: Update Session State
+Implements one story: checks it can start, marks it In Progress, hands the code to
+the right programmer agent with a brief built from the story, then checks the
+result parses and looks right, and hands off.
-**Read `references/7-session-state.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
+**Writes** (each after an ask that names it): the story's `Status`, `Last Updated`
+and `## Files`, and its `production/sprint-status.yaml` entry. The programmer agents
+write the code and tests under the code root and test root
+(`.claude/docs/code-root-resolution.md`). The session checkpoint and the evidence
+stamp are written without an ask.
+**Next:** `/story-done [story-path]`; at `standard` and `full`, `/code-review
+[files]` first.
-## Error Recovery Protocol
+Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided
+asks on major choices, autonomous logs and goes on; `automation_always_ask`
+categories always ask).
-**First, verify the artifact.** If the return contract named a path, check the
-path exists before treating the phase as done — **a named artifact that is not
-on disk is a failed phase, however fluent the response reads.** An agent can
-burn a full phase and return a plausible preamble having written nothing, which
-is neither BLOCKED nor an error nor "cannot complete", so the trigger below
-never fires. Resume it naming the unmet contract; the context is
-usually still there.
+Checklist (copy it and tick as you go):
-If any spawned agent returns BLOCKED, errors, or cannot complete: **surface it
-immediately, don't proceed past a dependency it blocks, and always produce a
-partial report.** Full procedure: `.claude/docs/error-recovery-protocol.md`.
+```
+- [ ] Phase 1: story found, tier resolved
+- [ ] Phase 2: prerequisites checked (ADR, manifest, dependencies)
+- [ ] Phase 3: story marked In Progress (one ask)
+- [ ] Phase 4: programmer and engine specialist chosen
+- [ ] Phase 5: work handed out with a full brief
+- [ ] Phase 6: finished? parse check, run and look, one Run result line
+- [ ] Phase 7: summary, ## Files, checkpoint, closing block
+```
-Common blockers:
-- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
-- A *referenced* ADR's status is Proposed → do not implement; accept it with `/architecture-decision accept ADR-NNNN` once decided (a story that references no ADR is not blocked on this — see Phase 2)
-- Scope too large → split into two stories via `/create-stories`
-- Conflicting instructions between ADR and story → surface the conflict, do not guess
-- Manifest version mismatch → show diff to user, ask whether to proceed with old rules or update story first
+## Phase 1: The story
+
+The text typed after the skill name is the story path. With nothing typed, take the
+story the checkpoint in `production/session-state/active.md` names and confirm it:
+"Continuing work on [title] — is that correct?" None there: ask "Which story are we
+implementing?" with the `TODO` rows of `bash .claude/scripts/story-facts.sh --all`
+as options. No story file under `production/epics/` at all: stop with
+"No stories found in `production/epics/` — run `/create-stories [epic-slug]` to make them (at `standard` and `full`, run `/create-epics` first if there is no epic yet)."
+
+`bash .claude/scripts/story-facts.sh <story-path>` gives its type, layer, TR-IDs,
+ADRs and dependencies. Then read the story in full.
+
+**Tier.** `workflow` for the story's system, keyed on the GDD filename stem of its
+`GDD:` path (`design/gdd/<stem>.md` → `<stem>`; the `[system]` of its TR-ID only when
+there is no GDD path): that system's `system_overrides` row if there is one, else the
+project value. Say it in your first reply: `Tier: workflow [value]`. That value, never
+`rigor` or `qa.level`, picks the Phase 2 column and the closing Next step.
+
+## Phase 2: Can it start?
+
+| Input | `full` | `standard` | `minimal` |
+|---|---|---|---|
+| TR registry `docs/architecture/tr-registry.yaml` | missing: **stop**, "Run `/architecture-review` to bootstrap it" | optional | not expected |
+| The ADR the story names | missing, `Proposed`, `Deprecated` or `Superseded`: **stop** | the same, only when the story names one | the same, only when the story names one |
+| Control manifest `docs/architecture/control-manifest.md` | missing: warn, go on | missing: warn, go on | not expected |
+
+A story whose ADR field reads `N/A — [reason]` names none.
+
+**The ADR.** `bash .claude/scripts/adr-status.sh <ADR id>` gives its status and
+`version`. Stop messages: `Proposed` — "ADR-NNNN is still Proposed. Accept it with
+`/architecture-decision accept ADR-NNNN` before implementing." `Deprecated` or
+`Superseded` — "ADR-NNNN is [status]; point the story at [successor] (edit its ADR
+field; `/create-stories` never rewrites an existing story) before implementing."
+`NOT_FOUND` — "ADR file not found. Run `/architecture-decision`, or correct the
+story's ADR field."
+
+**Do not open the ADR.** The story's ADR Decision Summary and Implementation Notes
+are what the programmer reads instead. Compare the ADR's `version` with the story's
+`ADR Version`:
+
+- equal, or the story has no `ADR Version` (written before the stamp), or both are
+ `unversioned`: trust the story. Note the last two in the summary ("summary
+ trusted unverified").
+- they differ, or the ADR is `unversioned` but the story names a date: read
+ `references/version-mismatch.md`. On a match, do not load it.
+
+Never treat an absent stamp as a stale one: unknown falls back to the story, and
+`/story-readiness` and `/code-review` are the checks that catch drift later.
+
+**The manifest.** When it exists, compare its `Manifest Version` line with the
+story's. They differ: read `references/version-mismatch.md`.
+
+**Dependencies.** For each path on the story's Depends on line,
+`bash .claude/scripts/story-facts.sh <path>`. Not `COMPLETE`: ask "[this story]
+depends on [dependency], which is [status], not Complete. How do you want to go
+on?" Options: Proceed anyway — I accept the risk / Stop — I'll finish the
+dependency first / It is done, the status was never updated — mark it Complete.
+Stop: the story is BLOCKED (Phase 7), no agent. Mark it: ask "May I set [path]
+Status to Complete?" first. Proceed: note it under Deviations. `NOT_FOUND`: warn
+"Dependency story not found: [path]".
+
+Any stop above: no agent runs. Go to Phase 7 and write the BLOCKED checkpoint.
+
+## Phase 3: Mark it In Progress
+
+Before any agent, ask once: "May I mark this story In Progress? This sets `Status`
+and `Last Updated` in [story path] and its entry in `production/sprint-status.yaml`,
+and at the end lists the files changed under its `## Files`." Leave the sprint file
+out of the question when it does not exist. Put what you will do next before the
+question: the question is the last thing in the reply. On yes:
+
+- `bash .claude/scripts/md-section.sh set-field <story> Status "In Progress"`, then
+ `set-field <story> "Last Updated" <YYYY-MM-DD> --after Status`. At `minimal` the
+ story file is the only record of progress.
+- `production/sprint-status.yaml`: this story's entry gets `status: in-progress` and
+ the top-level `updated` today. No file: say `Sprint status not updated:
+ production/sprint-status.yaml absent`.
+
+Declined: change neither, print `Story not marked In Progress — declined` in the
+summary, and go on.
+
+## Phase 4: Who implements it
+
+**Config/Data stories need no agent.** Show each value change as from → to, ask "May
+I write [data file]?", and edit it. Go to Phase 6.
+
+| Story | Programmer agent |
+|---|---|
+| Foundation layer, any type | `engine-programmer` |
+| Type UI | `ui-programmer` |
+| Type Visual/Feel | `gameplay-programmer` |
+| Core or Feature, gameplay | `gameplay-programmer` |
+| Core or Feature, AI or pathfinding | `ai-programmer` |
+| Core or Feature, networking | `network-programmer` |
+
+**The engine specialist, for every code story.** From the `specialists` line above:
+`code` (`specialists.code`, the language specialist: it tells a Godot C# project
+from a GDScript one, which `engine.name` cannot), plus `shader` when the story
+touches shaders or materials and `ui` for a UI story; `primary` (the generic engine
+specialist) when `code` is `unset`. Name no specialist from memory: the line is the project's
+choice. Every value `unset` and no `primary`: say "No engine specialist configured"
+and go on without one.
+
+## Phase 5: Hand out the work
+
+Hand the implementation to the programmer agent. The brief points at files; never
+paste whole documents into it.
+
+- **Objective:** implement [story path] against its acceptance criteria, within its
+ Out of Scope boundaries.
+- **Sources:**
+ 1. The story file. It carries the criteria, the boundaries and the QA test cases.
+ 2. Each TR-ID (`TR-[system]-NNN`) to look up: in
+ `docs/architecture/tr-registry.yaml`, the lines matching `id: <TR-ID>\s*$`.
+ Its `requirement` text is the source of truth, not text quoted in the story.
+ 3. The ADR guidance, **inline**: the story's ADR Decision Summary and
+ Implementation Notes. Never the ADR path.
+ 4. The control manifest's [Layer] Layer Rules, by section.
+ 5. `naming.*` in `project.yaml` and the `perf_budgets` line above.
+ 6. The test file path from the story's Test Evidence section.
+- **Tests,** by `qa.level`, for Logic and Integration stories:
+ - `minimal`: "Do not write a test file for this story — test evidence is waived at
+ `qa.level: minimal`." Say it: an omitted line and a forgotten one look the same
+ to the agent.
+ - `standard`: "Write the test at [path] with the code. Each acceptance criterion
+ needs at least one test function." Naming per engine from
+ `.claude/rules/test-standards.md`. No random seeds, no time-dependent
+ assertions, no external I/O.
+ - `full`: the same, and "every criterion must be covered: `/story-done` blocks on
+ any untested one."
+- **Output:** the files created or changed, the test functions written, any
+ question or blocker, and whether it finished.
+- **Boundaries:** write code only under the resolved code root and tests only under
+ the test root. Code root unresolved: write nothing and report it. Touch no file
+ outside the story's scope: report the need instead. Doc comments on public APIs.
+ An architectural choice the ADR does not cover: report the plan, don't decide it.
+ No helper or abstraction for a one-time use, no error handling for cases that
+ cannot happen (validate at input and data-file boundaries only), and general logic,
+ never a value special-cased so a test passes.
+
+**Say what the brief leaves out, to both readers.** Inputs Phase 2 found absent
+(the TR registry, an ADR, the manifest) are left out: tell the agent "No [input] is
+passed — it does not exist at this tier; do not go looking for it", and tell the
+user one line before handing out: `Briefing omits: [inputs] — implementing against
+the acceptance criteria and the [GDD | brief].`
+
+**Then hand the engine check to the specialist** once the programmer reports.
+Brief: check the changed files for engine-API use that is wrong or changed in
+[engine + version], against `docs/engine-reference/<engine>/`; return a list of
+file, line, problem, fix; edit nothing. A problem that breaks a criterion goes back
+to the programmer once; the rest go in the summary.
+
+## Phase 6: Check the result
+
+**Did the agent finish?** It stopped early, hit a limit, or its report ends
+mid-task: the story is **INCOMPLETE**. Say so as the headline, list what exists,
+name the breakage, offer to resume the agent. Never print "Implementation Complete"
+over it, and leave the status as it is.
+
+**Did it write what it said?** First verify the artifact: a file the agent's report
+names that is not on disk is a failed step, however fluent the report: resume the agent and name the missing
+file. A report of BLOCKED, an error, or "cannot complete": say so at once, go no
+further past what it blocks, and give a partial report
+(`.claude/docs/error-recovery-protocol.md`). Scope too large: split it with
+`/create-stories`. The ADR and the story disagree: report the conflict; never guess.
+
+**Is the test there?** At `qa.level: standard` and `full`, for a Logic or Integration
+story, look for the file at the Test Evidence path. Missing: at the type's BLOCKING
+level on the `gate_level` line, flag "story unverifiable — test required before
+`/story-done`"; at ADVISORY, note it as a recommendation. At `minimal` there is
+nothing to check: tests are waived.
+
+**Does it parse?** Run the check whose exit code answers it, and report the
+command, the exit code and any error lines:
+
+- **Godot:** `godot --headless --path . --import` once, then
+ `godot --headless --path . -s res://.claude/scripts/godot-parse-check.gd -- res://<each changed .gd>`.
+ Exit 1 means a script did not load; its `PARSE FAIL:` line names it. Never use
+ `--check-only`, and `--import` alone is no parse check. The executable is the one
+ `commands.test` names when its file name says godot (a wrapper such as `bash
+ run-tests.sh` is not the editor), else `engine.path`, else `godot`. Never search the disk for
+ one: when none of the three runs, the check is not verified.
+- **Unity, Unreal:** read `references/engine-checks.md`.
+- **No engine executable:** `parse NOT VERIFIED — engine binary not available`.
+ Never infer from reading the code that it parses.
+
+**Run it and look** (`.claude/docs/run-and-observe.md`). For every story a player
+can see (every Visual/Feel and UI story, and any other with a surface): launch
+straight into the scene the story touched, capture a screenshot straight into
+`production/qa/evidence/[story-slug]/` (`[story-slug]` is the story file's name
+without `.md`; `mkdir -p` the folder first), stamp it with
+`bash .claude/scripts/review-receipts.sh hash <each changed file> > production/qa/evidence/[story-slug]/stamp.txt`,
+then open the image and compare it with the criteria. Not waived at `qa.level:
+minimal`. Report exactly one line, plain text starting `Run result:` (no bold:
+`/story-done` reads it as written):
+
+- `Run result: OBSERVED — <what was on screen>` with the retained path;
+- `Run result: NOT VERIFIED — <reason>` (no engine, nothing captured); at the
+ default gate level this blocks a Visual/Feel or UI story at `/story-done`;
+- `Run result: N/A — <reason>` for a story with nothing observable; the reason says
+ why nothing is (`/story-done` does not accept "it's a Logic story").
+
+Only the feel half of a Visual/Feel criterion (timing, weight) is DEFERRED to
+`/team-qa`: a still cannot show it.
+
+This skill pre-approves `godot` on PATH. An engine run through `engine.path` or
+the executable `commands.test` names asks first: the user approves it once, or
+adds `Bash(<that executable> *)` to `.claude/settings.local.json`.
+
+## Phase 7: Summary, files, checkpoint
-## Collaborative Protocol
+```
+## Implementation Complete: [title]
+
+**Files changed**:
+- `[code root path]` — created / modified ([what])
+- `[test path]` — [N] test functions
+**Test evidence**: waived at `qa.level: minimal` — no test was required or written (Logic/Integration at minimal, instead of the test line)
+**Verification**: [command] — [exit code and result | parse NOT VERIFIED — <reason>]
+
+**Acceptance criteria**:
+- [x] [criterion] — [file:function | test name | OBSERVED in <image path>]
+- [ ] [criterion] — DEFERRED: feel, needs a playtest
+**Deviations**: [None | files outside scope, an accepted dependency or version risk]
+**Engine risks**: [None | the specialist's findings]
+**Blockers**: [None | each]
+```
-**Applies in `collaborative` mode (the default).** For `guided` and
-`autonomous` modes, see `.claude/docs/automation-modes.md` — the rules below
-describe what collaborative mode requires, not universal behavior.
+At `qa.level: standard` and `full`, add: "Run your test suite and confirm the new
+tests pass before `/story-done`: it checks that the test file exists, and runs
+nothing." At `minimal` leave that out: there are no tests to run. For a Visual/Feel
+or UI story with no retained image, add: "A retained screenshot under
+`production/qa/evidence/[story-slug]/` is required before `/story-done`" (and, for
+Visual/Feel, the sign-off in `production/qa/evidence/[story-slug]-evidence.md`).
-- **File writes are delegated** — all source code, test files, and evidence docs are written by sub-agents spawned via `Agent`. Each sub-agent enforces the "May I write to [path]?" protocol individually. This orchestrator writes only the following, each after an ask that names it:
- - the story's `Status:` / `Last Updated:` and its `production/sprint-status.yaml` entry — the one "May I mark this story In Progress?" ask (Phase 2)
- - the story's `ADR Version`, `**ADR Decision Summary**` and `## Implementation Notes` (ADR mismatch option [A]), and its `Manifest Version:` / `Manifest-Note:` (manifest option [A] or [B]) — each option names that edit, so choosing it is the ask
- - a dependency story's `Status: Complete` (dependency option [C], then "May I update [dependency path] Status to Complete?")
- - a Config/Data story's data file ("May I write to [path]?")
- - on Unity, `Assets/Scripts/ScreenshotOnArg.cs`, written verbatim from `.claude/docs/run-and-observe.md` ("May I write `Assets/Scripts/ScreenshotOnArg.cs`?", Phase 6)
+**`## Files`.** Replace the section's body with the list of changed code and test
+files, one per line, as the Phase 3 ask said:
+`bash .claude/scripts/md-section.sh replace <story> "Files"` with the list on stdin.
+A story with no such section: add `## Files` and the list at its end, with a file
+edit, never a shell command (a shell write skips the project's write checks). Skip
+this when the Phase 3 ask was declined.
- The session-state checkpoint in `production/session-state/active.md` is the one write made without an ask.
-- **Load before implementing** — do not start coding until all context is loaded
- (story, TR-ID, ADR, manifest, engine prefs). Incomplete context produces code
- that drifts from design.
-- **The ADR is the law** — implementation must follow the ADR's Implementation
- Guidelines. If the guidelines conflict with what seems "better," flag it in the
- summary rather than silently deviating.
-- **Stay in scope** — the Out of Scope section is a contract. If implementing
- the story requires touching an out-of-scope file, stop and surface it:
- "Implementing [criterion] requires modifying [file], which is out of scope.
- Shall I proceed or create a separate story?"
-- **Test is not optional for Logic/Integration** (at `qa.level: standard`/`full`) —
- do not mark implementation complete without the test file existing. At
- `qa.level: minimal` tests are not required and this does not apply.
-- **Visual/Feel and UI looks are observed, not deferred** — the Phase 6 run
- retains the screenshot (each screen touched for UI; Visual/Feel also needs a
- lead sign-off before `/story-done`), and `qa.level` never waives either. Only
- the *feel* half of a Visual/Feel criterion — timing, weight, responsiveness —
- is marked DEFERRED, for `/team-qa`
-- **Ask before large structural decisions** — if the story requires an
- architectural pattern not covered by the ADR, surface it before implementing:
- "The ADR doesn't specify how to handle [case]. My plan is [X]. Proceed?"
+**The checkpoint**, on every outcome. Pipe the block to
+`bash .claude/scripts/session-state.sh checkpoint`, which replaces the old one:
----
+```
+**Updated:** [date]
+**Branch:** `[current git branch]`
+**Current task:** /dev-story — [story path] ([title])
+**Next step:** [the Next step below]
+**Blocked on:** [nothing, or the blocker]
+**Files in progress:** [changed files, comma-separated]
+**Run result:** [OBSERVED — … | NOT VERIFIED — … | N/A — …, as in the closing block: /story-done reads it here]
+**Open questions:** [none, or one line each]
+```
-## Recommended Next Steps
+**The run's last reply ends with this block**, the only place the `Run result:` line
+is printed: print it nowhere else in the reply. The Next step goes by the tier you stated in Phase 1 (the `workflow` line,
+never `rigor` or `qa.level`). The Next step: at `minimal`, `/story-done [path]`. At `standard` and `full`,
+`/code-review [files]`, then `/story-done [path]`. INCOMPLETE: `/dev-story [path]`
+to resume. BLOCKED: the action that unblocks it (`/architecture-decision accept
+ADR-NNNN`, the dependency to finish, the diff to review).
-- At `standard`/`full`, run `/code-review [file1] [file2]` to review the implementation before closing the story (not part of the minimal loop)
-- Run `/story-done [story-path]` to verify acceptance criteria and mark the story complete
-- With a sprint plan, after all sprint stories are done: run `/team-qa sprint` for the full QA cycle before advancing the project stage. At `minimal`, `/story-done` names the next story instead
+```
+Story: [path] — [Implemented | INCOMPLETE — <breakage> | BLOCKED — <reason>]
+Run result: [OBSERVED — … | NOT VERIFIED — … | N/A — …]
+Next step: [Implemented, Tier: workflow minimal → /story-done [path] | Implemented, Tier: workflow standard or full → /code-review [changed files], then /story-done [path] | INCOMPLETE → /dev-story [path] to resume | BLOCKED → the unblocking action]
+```
diff --git a/.claude/skills/dev-story/references/2-load-context.md b/.claude/skills/dev-story/references/2-load-context.md
deleted file mode 100644
index 9f328302..00000000
--- a/.claude/skills/dev-story/references/2-load-context.md
+++ /dev/null
@@ -1,193 +0,0 @@
-# /dev-story — Phase 2: Load Full Context
-
-> Part of `/dev-story`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 2: Load Full Context
-
-**In this file:**
-
-- The story file
-- The TR registry
-- The governing ADR
-- The control manifest
-- Dependency validation
-- Engine reference
-- Mark Story In Progress
-
-**Before loading any context, resolve the workflow tier for this story's system** (see the Workflow tier note above), then **verify required files exist.** Extract the ADR path from the story's `ADR Governing Implementation` field. The "If missing — `full`" column is the baseline; the tier columns relax it:
-
-| File | Path | If missing — `full` | `standard` | `minimal` |
-|------|------|---------------------|-----------|-----------|
-| TR registry | `docs/architecture/tr-registry.yaml` | **STOP** — "TR registry not found at `docs/architecture/tr-registry.yaml`. Run `/architecture-review` to bootstrap the registry from your GDDs and ADRs." | optional — proceed without it | not expected — proceed |
-| Governing ADR | path from story's ADR field | **STOP** — "ADR file [path] not found. Run `/architecture-decision` to create it, or correct the filename in the story's ADR field." Also STOP if its `## Status` is `Proposed` — "ADR [path] is still Proposed. Accept it with `/architecture-decision accept [ADR-id]` before implementing." A story whose ADR field reads `N/A` (`N/A — [reason]`) references none — proceed. | **STOP only if the story references an ADR** and its file is missing/Proposed/Deprecated/Superseded; if it references none, proceed | no ADR required — proceed; **STOP only if the story references an ADR** whose file is missing/Proposed/Deprecated/Superseded |
-| Control manifest | `docs/architecture/control-manifest.md` | **WARN and continue** — "Control manifest not found — layer rules cannot be checked. Run `/create-control-manifest`." | WARN and continue | skip — not expected |
-
-At `full`, if the TR registry is missing, or a referenced governing ADR is missing or `Proposed`, set the story status to **BLOCKED** in the session state and do not spawn any programmer agent. At `standard`/`minimal`, only a story that references an ADR whose file is **missing, `Proposed`, `Deprecated` or `Superseded`** is set BLOCKED; a missing TR registry, or an absent-by-design ADR, does **not** block — implement against the story's acceptance criteria + the GDD/brief.
-
-Read the story file and the TR registry simultaneously — these two are
-genuinely independent, unconditional reads. **The governing ADR is not part
-of this batch — do not include it in the same parallel tool-call group as
-these two.** Its own section below is a gate, not a read: whether the ADR
-gets opened at all depends on a freshness check that itself depends on the
-story file already being read. Do not start implementation until this phase
-is fully resolved:
-
-### The story file
-Extract and hold:
-- **Story title, ID, layer, type** (Logic / Integration / Visual/Feel / UI / Config/Data)
-- **TR-ID** — the GDD requirement identifier
-- **Governing ADR** reference
-- **ADR Version** stamp embedded in story header (absent on pre-stamp stories)
-- **ADR Decision Summary** and **Implementation Notes** — the distilled ADR
- guidance; this is the primary source for what the ADR decided
-- **Manifest Version** embedded in story header
-- **Acceptance Criteria** — every checkbox item, verbatim
-- **Implementation Notes** — the ADR guidance section in the story
-- **Out of Scope** boundaries
-- **Test Evidence** — the required test file path
-- **Dependencies** — what must be DONE before this story
-
-### The TR registry
-Grep the story's TR-ID from `docs/architecture/tr-registry.yaml`
-(`Grep pattern="id: <TR-ID>\s*$" path="docs/architecture/tr-registry.yaml" output_mode="content" -A 6`)
-rather than reading the whole cross-system registry. Read the matched entry's current
-`requirement` text — this is the source of truth for what the GDD requires now. Do not
-rely on any inline text in the story file (may be stale).
-
-### The governing ADR
-
-**Do not open the ADR by default.** `/create-stories` already distilled it into
-this story's `**ADR Decision Summary**` + `## Implementation Notes`, and its
-template states the contract outright: *"This is what the programmer reads
-instead of the ADR."* Re-reading the source here discards that work and, on an
-ADR past the 25k `Read` cap, costs a failed read plus offset/limit retries
-before implementation even starts.
-
-**Check status and freshness with one line, not one file.** Resolve the ADR path
-from the story, then:
-
-```
-Grep pattern="^## (Status|Last Verified|Date)" path="docs/architecture/[adr-file].md" output_mode="content" -A 2
-```
-
-The `## Status` line decides first: if it reads `Proposed`, the story is BLOCKED
-per the file-check table above — stop here, before any freshness comparison.
-`Deprecated` or `Superseded by ADR-XXXX` blocks the same way, at every tier:
-"ADR [path] is [status]; point the story at [successor] (edit its ADR field —
-`/create-stories` never rewrites an existing story) before implementing."
-
-Then resolve the ADR's **current version** the way `/create-stories` stamped it:
-its `## Last Verified` date, else its `## Date`, else `unversioned`. Compare that
-value against the story's `**ADR Version**` field:
-
-| Result | Meaning | Action |
-|---|---|---|
-| Versions **match** (a date on both sides) | The summary was distilled from the ADR as it stands. | **Trust the story.** Do not read the ADR. |
-| Story has **no `ADR Version`** field | A story written before the stamp existed — *not* evidence of staleness. | **Trust the story**, and note in the Phase 6 summary: "Story predates the ADR Version stamp; summary trusted unverified." |
-| Both read `unversioned` | The ADR has neither `## Last Verified` nor `## Date`. Consistent, not stale — but nothing to compare. | **Trust the story**; note "ADR carries no date; summary trusted unverified." in the Phase 6 summary, and recommend `/architecture-decision retrofit [file]`, which adds a missing `## Date`. |
-| The ADR resolves to `unversioned` but the story names a date | Ambiguous — the ADR lost the field the story was stamped from. | Treat as **mismatch** (below). |
-| Versions **differ** | The ADR changed after this story was written. | **Mismatch** — resolve below. |
-
-**Never treat an absent stamp as a stale one.** A missing field means "unknown",
-and the fallback for unknown is the story, not a 35k-token re-read — the two
-staleness gates that already exist (`/story-readiness` on Manifest Version,
-`/code-review` post-implementation) are what make that safe.
-
-**On mismatch**, use `AskUserQuestion` — same shape as the Manifest Version
-check below:
-- Prompt: "Story was written against ADR v[story-date]. The ADR is now
- v[current-date]. Its decision may have changed. How do you want to proceed?"
-- Options:
- - `[A] Re-read the changed ADR sections, implement against current guidance, and refresh this story's ADR summary and ADR Version (Recommended)`
- - `[B] Implement from the story's summary — I accept the drift risk`
- - `[C] Stop — I want to review the ADR diff first`
-
-If **[A]**: first check the ADR's size — `Bash: wc -c "docs/architecture/[adr-file].md"`:
-
-- **Under ~50KB** — read the whole file with one `Read` call. At this size one
- read is *cheaper* than the multi-grep path — per-call overhead outweighs the
- content saved. Targeted reading only pays for itself on files big enough
- to threaten the 25k-token `Read` cap.
-- **~50KB or larger** — read *only* the sections that govern implementation,
- never the whole file:
- ```
- Grep pattern="^## (Decision|Engine Compatibility|ADR Dependencies)" path="docs/architecture/[adr-file].md" output_mode="content" -A 40
- ```
- Escalate to a bounded `Read(offset, limit)` on one section only if a scanned
- section cross-references material outside itself.
-
-Then make the story edit that option [A] names: set its `ADR Version` to the ADR's
-current version resolved above — not today's date, or the next run mismatches
-again — and replace its `**ADR Decision Summary**` and `## Implementation Notes`
-with the guidance you just read, so a later run that trusts the stamp is trusting
-current guidance.
-If **[B]**: proceed on the summary; record it in the Phase 6 "Deviations" summary.
-If **[C]**: stop. Do not spawn any agent.
-
-### The control manifest
-Read only this story's layer from `docs/architecture/control-manifest.md` — grep that one
-section (`Grep pattern="^## <layer> Layer Rules" path="docs/architecture/control-manifest.md" output_mode="content" -A 40`) rather than a full read of every layer. Extract the rules for this story's layer:
-- Required patterns
-- Forbidden patterns
-- Performance guardrails
-
-Check: does the story's embedded Manifest Version match the current manifest header date?
-If they differ, use `AskUserQuestion` before proceeding:
-- Prompt: "Story was written against manifest v[story-date]. Current manifest is v[current-date]. New rules may apply. How do you want to proceed?"
-- Options:
- - `[A] Update story manifest version and implement with current rules (Recommended)`
- - `[B] Implement with old rules — I accept the risk of non-compliance (the story records the current Manifest Version and a Manifest-Note)`
- - `[C] Stop here — I want to review the manifest diff first`
-
-If [A]: edit the story file's `Manifest Version:` field to the current manifest date before spawning the programmer. Then read the manifest carefully for new rules.
-If [B]: edit the story file's `Manifest Version:` field to the current manifest date AND add a `Manifest-Note: Proceeded with old manifest rules on [date] — non-compliance risk accepted.` line to the story header. Read the manifest for new rules anyway. Note the decision in the Phase 6 summary under "Deviations". `/story-done` will include the Manifest-Note in its deviations section without re-checking staleness.
-If [C]: stop. Do not spawn any agent. Let the user review and re-run `/dev-story`.
-
-### Dependency validation
-
-After extracting the **Dependencies** list from the story file, validate each:
-
-1. Glob `production/epics/**/*.md` to find each dependency story file.
-2. Read its `Status:` field.
-3. If any dependency has Status other than `Complete` or `Done`:
- - Use `AskUserQuestion`:
- - Prompt: "Story '[current story]' depends on '[dependency title]' which is currently [status], not Complete. How do you want to proceed?"
- - Options:
- - `[A] Proceed anyway — I accept the dependency risk`
- - `[B] Stop — I'll complete the dependency first`
- - `[C] The dependency is done but status wasn't updated — mark it Complete and continue`
- - If [B]: set story status to **BLOCKED** in session state and stop. Do not spawn any programmer agent.
- - If [C]: ask "May I update [dependency path] Status to Complete?" before continuing.
- - If [A]: note in Phase 6 summary under "Deviations": "Implemented with incomplete dependency: [dependency title] — [status]."
-
-If a dependency file cannot be found: warn "Dependency story not found: [path]. Verify the path or create the story file."
-
----
-
-### Engine reference
-Read from `project.yaml` first, falling back to `.claude/docs/technical-preferences.md` for any key absent or empty:
-- `specialists.*` — the project's chosen specialist agents; **read before**
- `engine.name` when selecting an agent (see Phase 3)
-- `engine.name` (else the `Engine:` value) — the generic engine specialist, and
- the fallback when `specialists` is absent
-- `naming.*` (else Naming conventions) — class names, file names, signal/event names
-- `performance.*` (else Performance budgets) — frame budget, memory ceiling
-- Forbidden patterns — from `.claude/docs/technical-preferences.md` (not migrated to project.yaml)
-
-### Mark Story In Progress
-
-Before spawning any agent, mark the story In Progress. In `collaborative` mode
-ask once first — "May I mark this story In Progress? This sets `Status:` and
-`Last Updated:` in `[story-path]` and its entry in `production/sprint-status.yaml`."
-(leave the sprint-status file out of the question when it does not exist);
-`guided` and `autonomous` update these existing files without asking
-(`.claude/docs/automation-modes.md`). If the user declines, change neither file,
-print `Story not marked In Progress — declined` in the Phase 6 summary, and
-continue. Otherwise update two things:
-
-1. **`production/sprint-status.yaml`** (if it exists): find the entry matching this story's file path and set `status: in-progress`. Update the top-level `updated` field to today's date. If the file does not exist, say so in one line — `Sprint status not updated: production/sprint-status.yaml absent` — and continue. Do not skip silently: `/sprint-status` reads that file to report progress, so a story that never gets marked `in-progress` is invisible to the very command a producer uses to ask what is moving.
-
-2. **The story file itself**: set the story header's `Status:` field to `In Progress`, and edit its `Last Updated:` field to today's date (format: `YYYY-MM-DD`; if the field does not exist, add it after the `Status:` line). Setting `Status:` here is what actually marks the story In Progress — at `minimal` the `sprint-status.yaml` in step 1 is absent, so the story file is the only record of progress at that tier.
-
----
diff --git a/.claude/skills/dev-story/references/3-route.md b/.claude/skills/dev-story/references/3-route.md
deleted file mode 100644
index 0a6be1b3..00000000
--- a/.claude/skills/dev-story/references/3-route.md
+++ /dev/null
@@ -1,89 +0,0 @@
-# /dev-story — Phase 3: Route to the Right Programmer
-
-> Part of `/dev-story`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 3: Route to the Right Programmer
-
-Based on the story's **Layer**, **Type**, and **system name**, determine which
-specialist to spawn via `Agent`.
-
-**Config/Data stories — skip agent spawning entirely:**
-If the story's Type is `Config/Data`, no programmer agent or engine specialist is needed. Jump directly to Phase 4 (Config/Data note). The implementation is a data file edit — no routing table evaluation, no engine specialist.
-
-### Primary agent routing table
-
-| Story context | Primary agent |
-|---|---|
-| Foundation layer — any type | `engine-programmer` |
-| Any layer — Type: UI | `ui-programmer` |
-| Any layer — Type: Visual/Feel | `gameplay-programmer` (implements) |
-| Core or Feature — gameplay mechanics | `gameplay-programmer` |
-| Core or Feature — AI behaviour, pathfinding | `ai-programmer` |
-| Core or Feature — networking, replication | `network-programmer` |
-| Config/Data — no code | No agent needed (see Phase 4 Config note) |
-
-### Engine specialist — always spawn as secondary for code stories
-
-**Read the `specialists` block from `project.yaml` directly — it is not in
-the `resolve_config` output at the top of this skill..** `resolve_config` does not emit
-`specialists.*`; the five skills that already consume it (`/adopt`,
-`/code-review`, `/design-system`, `/gate-check`, `/team-ui`) all read the block
-out of `project.yaml` themselves, and so does this one. Adding it to the
-frontmatter key list would fail the gate that asserts every requested key is one
-`resolve_config` actually emits.
-
-`/setup-engine` writes the block, and it is the project's own answer to "which
-specialist implements here" — resolved from the engine *and the language*, which
-`engine.name` alone cannot tell you. Resolve in this order:
-
-1. **`specialists.code`** — the language/code specialist, and the right secondary
- for an implementation story. This is the value that distinguishes a Godot C#
- project (`godot-csharp-specialist`) from a Godot GDScript one
- (`godot-gdscript-specialist`); `engine.name` is `Godot` for both.
-2. **`specialists.shader`** when the story touches shaders or materials, and
- **`specialists.ui`** when the story's Type is `UI` — in addition to, not
- instead of, `specialists.code`.
-3. **The generic `<engine>-specialist`** — derived from `engine.name`
- (Godot→`godot-specialist`, Unity→`unity-specialist`,
- Unreal→`unreal-specialist`) — for architecture-level and broad engine
- concerns, and as the fallback when the `specialists` block is absent.
-4. If `engine.name` is also absent or empty, read the Primary line of the
- `## Engine Specialists` section of `.claude/docs/technical-preferences.md`.
-
-**A value of `null` means UNSET — treat that key as absent and fall through to
-the generic specialist. Never spawn it as an agent name.** The config reader
-returns the four-character string `"null"`, which is not empty and therefore
-reads as configured; `null`, empty and missing are the same state here. (This is
-the same caveat `/code-review` Phase 2 carries, for the same reason.)
-
-Spawn the resolved specialist alongside the primary agent when the story involves
-engine-specific APIs, patterns, or the ADR has HIGH engine risk.
-
-The full roster, for reference when no `specialists` block exists:
-
-| Engine | Specialist agents available |
-|--------|----------------------------|
-| Godot 4 | `godot-specialist`, `godot-gdscript-specialist`, `godot-csharp-specialist`, `godot-shader-specialist`, `godot-gdextension-specialist` |
-| Unity | `unity-specialist`, `unity-ui-specialist`, `unity-shader-specialist`, `unity-dots-specialist`, `unity-addressables-specialist` |
-| Unreal Engine | `unreal-specialist`, `ue-gas-specialist`, `ue-blueprint-specialist`, `ue-umg-specialist`, `ue-replication-specialist` |
-
-> **Do not pick from this table when `specialists` is set.** The table lists what
-> *exists* for an engine; the block records what this project *chose*. Reading the
-> table instead of the block is how a Godot C# project ends up reviewed by the
-> GDScript specialist.
-
-**When engine risk is HIGH** (from the ADR or VERSION.md): always spawn the engine
-specialist, even for non-engine-facing stories. High risk means the ADR records
-assumptions about post-cutoff engine APIs that need expert verification.
-
-> **Read the risk, do not trust the story card alone.** If the story's `Risk`
-> field is absent, or says `NOT ASSESSED`, **or disagrees with
-> `docs/engine-reference/<engine>/VERSION.md`, the VERSION.md rating wins** and an
-> unknown counts as HIGH. At `minimal` there is no ADR, so VERSION.md is the only
-> source; a story card carrying an improvised `MEDIUM` against a VERSION.md
-> rating of HIGH would skip this spawn without saying so. `/create-stories` now derives the field
-> from the same file, so the two should agree; this check is what catches it when
-> they do not.
-
----
diff --git a/.claude/skills/dev-story/references/4-implement.md b/.claude/skills/dev-story/references/4-implement.md
deleted file mode 100644
index e9230cd4..00000000
--- a/.claude/skills/dev-story/references/4-implement.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# /dev-story — Phase 4: Implement
-
-> Part of `/dev-story`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 4: Implement
-
-Spawn the chosen programmer agent(s) via `Agent` with the full context package:
-
-Brief the agent with file paths and targeted reading instructions — do not serialize document content into the `Agent` prompt. The agent reads what it needs directly.
-
-> **Tier note (from Phase 2):** items 2–4 below assume the `full` baseline. At
-> `standard`, include the TR registry only if it exists and the governing ADR
-> only where the story references one — at any tier, a story whose ADR field
-> reads `N/A` has no item 3. At `minimal`, the TR registry, ADR, and
-> control manifest are typically absent — **omit items 2–4 and brief the agent to
-> implement against the story's Acceptance Criteria and the GDD/brief** (the
-> story file from item 1). Never instruct the agent to read a file Phase 2
-> confirmed missing.
->
-> **Say which items you dropped, and say it to both readers.** The rule item 7
-> already carries applies unchanged to items 2–4: *an omitted item and a
-> forgotten one are indistinguishable to the agent.* They are equally
-> indistinguishable to the user reading the Phase 6 summary.
-> - **To the agent**, in the prompt: *"No TR registry entry is passed for this
-> story — `docs/architecture/tr-registry.yaml` does not exist at this tier.
-> Implement against the story's Acceptance Criteria and the GDD/brief. Do not
-> go looking for it."* Same form for an absent ADR or control manifest.
-> - **To the user**, one line before spawning: `Briefing omits: TR registry
-> (absent), ADR guidance (story references no ADR), control manifest
-> (absent) — implementing against acceptance criteria + GDD.`
->
-> Without this, a `standard` run where the registry legitimately does not exist
-> and one where `/architecture-review` was supposed to bootstrap it and nobody
-> did produce **identical output**.
-
-1. **Story file**: `[story-path]` — the agent reads this one file; it carries the acceptance criteria, Out of Scope boundaries, and QA test cases
-2. **GDD requirement**: look up TR-ID `[TR-XXX-NNN]` in `docs/architecture/tr-registry.yaml` — use the `requirement` field as source of truth
-3. **ADR guidance**: pass the story's `**ADR Decision Summary**` and `## Implementation Notes` **inline in the prompt** — do not pass the ADR path. Phase 2 already established that this summary is current; handing the agent a path makes it re-read the whole ADR in its own context, paying the cost this skill just avoided. After mismatch option `[A]`, pass the guidance freshly read from the ADR's `## Decision` (the text [A] just wrote into the story), never the stale summary the story carried before; after `[B]`, pass the story's summary and tell the agent it predates the current ADR.
-4. **Control manifest**: `docs/architecture/control-manifest.md` — read rules for the **[layer]** layer only
-5. **Engine preferences**: `naming.*` and `performance.*` from `project.yaml` (for any key absent or empty, fall back to `.claude/docs/technical-preferences.md`)
-6. **Test file path**: `[path from story's Test Evidence section]` — this file must be created as part of implementation
-7. **Test requirement** (Logic and Integration stories only; **omit this entire item at `qa.level: minimal`** — tests are not required there. When you omit it for a Logic or Integration story, tell the agent so explicitly — never a UI, Visual/Feel or Config/Data story, which this item never covered: *"Do not write a test file for this story — test evidence is waived at `qa.level: minimal`."* An omitted item and a forgotten one are indistinguishable to the agent, and a programmer briefed with no test instruction may write tests anyway, or may silently assume they were meant to): The test file MUST be created at `[path from the story's Test Evidence section]`. Write the test alongside the implementation — do not defer it. At `qa.level: standard`/`full` the story cannot be closed via `/story-done` without this file present. Each acceptance criterion must have at least one test function covering it. Test naming per engine, from `.claude/rules/test-standards.md`: Godot `test_[scenario]_[expected]` in `[system]_[feature]_test.gd`; Unity `[Scenario]_[Expected]` in a `[System]Tests` class; Unreal `<Project>.[System].[Scenario]`. No random seeds, no time-dependent assertions, no external I/O.
-8. **Explicit instruction**: implement this story following the ADR guidelines, respect the manifest rules, stay within the story's Out of Scope boundaries. Write clean, doc-commented public APIs.
-
-The agent should:
-- Create or modify files under the **resolved code root** following the ADR guidelines. Resolve it per `.claude/docs/code-root-resolution.md` — `src/` is the Godot row, `Assets/Scripts/<System>/` is Unity's, `Source/<Module>/<System>/` is Unreal's. **If the code root cannot be resolved, do not write: report it and stop.** Selecting the engine specialist above is NOT the same as resolving the code root
-- Respect all Required and Forbidden patterns from the control manifest
-- Stay within the story's Out of Scope boundaries (do not touch unrelated files)
-- Write clean, doc-commented public APIs
-
-### Config/Data stories (no agent needed)
-
-For Type: Config/Data stories, no programmer agent is required. The implementation
-is editing a data file. Read the story's acceptance criteria, show the specified
-changes as from → to values, and ask "May I write to [data file path]?" before
-editing it directly. Note which values were changed and what they changed from/to.
-
-### Visual/Feel stories
-
-Spawn `gameplay-programmer` to implement the code/animation calls. The *look*
-half of the acceptance criteria — layout, clipping, presence, colour — is
-verified in Phase 6 step 4 by launching the build and retaining a screenshot;
-it is not deferred. The *feel* half — timing, weight, responsiveness — is not
-something a still can show: say which half the run covered, and leave feel to
-`/team-qa`.
-
----
diff --git a/.claude/skills/dev-story/references/5-test-evidence.md b/.claude/skills/dev-story/references/5-test-evidence.md
deleted file mode 100644
index acf67ee9..00000000
--- a/.claude/skills/dev-story/references/5-test-evidence.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# /dev-story — Phase 5: Test Evidence Requirements
-
-> Part of `/dev-story`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 5: Test Evidence Requirements
-
-The test requirement was included in the Phase 4 programmer agent brief (item 7). This phase summarizes what evidence each story type requires — used when collecting the Phase 6 summary.
-
-**Skip this phase at `qa.level: minimal`** (resolved earlier) — no test evidence
-is required, so there is nothing to gate; do not flag the story unverifiable for a
-missing test. **The Visual/Feel and UI screenshot line at the end of this phase
-still applies** — `qa.level` waives tests, never the look.
-
-> **Say so in the Phase 6 summary.** A skipped phase must announce itself in the
-> output, not only in this file (`.claude/rules/skill-authoring.md`, obligation
-> 3). For a Logic or Integration story — the types Phase 4 item 7 briefs a test
-> for — emit the line:
->
-> > *Test evidence: **waived** at `qa.level: minimal` — no test was required or
-> > written for this story.*
->
-> Without it, a minimal-tier summary that simply lacks a tests row is
-> indistinguishable from a `standard`-tier run where the programmer forgot to
-> write them — and the permissive reading is the one that gets believed.
-
-Otherwise:
-
-**Resolve the gate level for this story's type** from `testing.strict` in
-`project.yaml`. BLOCKING means a missing test marks the story unverifiable;
-ADVISORY means a missing test is noted but does not block:
-
-1. Map the Story Type to a `testing.strict` key — Logic→`logic`,
- Integration→`integration`, Visual/Feel→`visual`, UI→`ui`, Config/Data→`config`.
- Take `testing.strict.<key>` from the **the resolved-config block at the top of this skill**, not from
- `project.yaml` directly. If its value is `true` (case-insensitive) →
- BLOCKING; if `false` → ADVISORY; `unset` → fall through.
-
-> `testing.strict.*` is locally overridable (`/settings --local
-> testing.strict.logic=false`). Reading `project.yaml` on its own ignores
-> `project.local.yaml` entirely, so the override is accepted and then does
-> nothing. `resolve_config` merges the two.
-2. Else read `testing.strict` as a plain boolean (legacy single-value form) — if
- its value is `true` or `false`, it applies to every type.
-3. Else use the **Default Gate Level** column below.
-
-Only `true` and `false` (case-insensitive) are recognized at steps 1–2. A key
-that is present but holds any other value — `maybe`, `1`, `yes`, etc. — is
-treated as unset: continue to the next step, and surface the unrecognized value
-to the user.
-
-| Story Type | Required Evidence | Default Gate Level |
-|---|---|---|
-| **Logic** | Automated unit test at path from story's Test Evidence section | BLOCKING |
-| **Integration** | Integration test OR documented playtest record | BLOCKING |
-| **Visual/Feel** | Retained screenshot + evidence doc at `production/qa/evidence/[slug]-evidence.md` | BLOCKING |
-| **UI** | Retained screenshot of each screen touched, in `production/qa/evidence/` | BLOCKING |
-| **Config/Data** | None — smoke check serves as evidence | ADVISORY |
-
-The test is written alongside the implementation (Phase 4, item 7) regardless of
-the gate level — strictness controls only how a *missing* test is reported in the
-Phase 6 summary. At a BLOCKING level, a missing test is flagged "story
-unverifiable — test required before `/story-done`". At an ADVISORY level it is
-noted as a recommendation. The **Default Gate Level** column applies when
-`testing.strict` is unset.
-
-Visual/Feel and UI default to **BLOCKING**: for a game the rendered result is the
-product, and an advisory visual gate gets deferred in favour of whatever does
-block. A project that genuinely does not need it sets `testing.strict.visual` or
-`testing.strict.ui` to `false`.
-
-For Visual/Feel and UI stories, include in the Phase 6 summary: "Retained screenshot required under `production/qa/evidence/[story-slug]/` before this story can be closed — at the default BLOCKING level a story with no screenshot on disk is unverifiable." For Visual/Feel, add that the sign-off in `production/qa/evidence/[slug]-evidence.md` is also required.
-
----
diff --git a/.claude/skills/dev-story/references/6-collect.md b/.claude/skills/dev-story/references/6-collect.md
deleted file mode 100644
index faaa937d..00000000
--- a/.claude/skills/dev-story/references/6-collect.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# /dev-story — Phase 6: Collect and Summarise
-
-> Part of `/dev-story`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 6: Collect and Summarise
-
-**In this file:**
-
-- First: did the agent actually finish?
-- Then collect:
-
-### First: did the agent actually finish?
-
-**Do not assume completion.** A programmer agent can stop at its turn limit
-mid-edit, and the work it leaves behind can be syntactically broken — a helper
-called but never defined, an import half-moved. Its partial report reads like
-progress, and this phase's summary would print "Implementation Complete" over
-code that does not load.
-
-Before collecting anything:
-
-1. **Check the agent's own terminal state.** If it reported stopping early, hit a
- turn/step limit, or its report ends mid-task, treat the story as **INCOMPLETE**.
-2. **Verify the output parses.** Run the check whose **exit code** answers the
- question — an exit 0 from a command that does not check is how broken code
- gets reported as clean:
- - **Godot:** `godot --headless --path . --import` once (it builds the class
- cache), then one run over every `.gd` the story added or changed:
- `godot --headless --path . -s res://.claude/scripts/godot-parse-check.gd -- res://<file>.gd …`.
- For `godot`, use the executable `commands.test` names, else the editor
- `engine.path` records, else `godot` on `PATH`; if none resolves, write
- `parse NOT VERIFIED — Godot executable not found`.
- Exit 1 means a script did not load — its `PARSE FAIL:` line names it, with
- Godot's error above. Do not use `--check-only`: it fails valid code that
- names an autoload. `--import` and `--quit-after` on their own exit 0 on a
- parse error — they are not parse checks.
- - **Unity:** `commands.smoke` (`-batchmode -quit -projectPath . -logFile -`)
- — exit 1 with `error CS…` lines when a script does not compile.
- - **Unreal:** build the editor target —
- `"<UE root>/Engine/Binaries/DotNET/UnrealBuildTool/UnrealBuildTool.exe" <Project>Editor Win64 Development -Project="<absolute path>/<Project>.uproject"`
- on Windows; on Linux `"<UE root>/Engine/Build/BatchFiles/Linux/Build.sh" <Project>Editor Linux Development -Project=…`,
- on macOS `…/Mac/Build.sh <Project>Editor Mac Development -Project=…` (from Epic's
- documentation — `docs/engine-reference/unreal/current-best-practices.md`, "Command Line").
- A compile error fails the build (`Result: Failed`, non-zero exit).
- Report what you ran, its exit code, and any error lines.
-3. If the engine binary is unavailable, write **`parse NOT VERIFIED — engine
- binary not available`**. Do not infer that the code is fine because it reads
- correctly; that inference is exactly what this step exists to replace.
-4. **Run it and look.** A parse check is not a run. For every story that
- changes something a player can see — every Visual/Feel and UI story, and any
- Logic, Integration or Config/Data story with a surface — launch the build
- via `commands.run`, straight into the scene or map the story touched, and
- retain a screenshot under `production/qa/evidence/[story-slug]/`. Then
- `Read` the image and compare it to the acceptance criteria: clipped text,
- an overflowing panel, a missing element are defects, and this is the only
- step that finds them. Procedure per engine, including how to capture
- unattended in Godot, Unity and Unreal: `.claude/docs/run-and-observe.md`.
- **On Unity** the capture needs the `ScreenshotOnArg.cs` script that file gives
- verbatim. If the project has none (Glob `Assets/**/ScreenshotOnArg.cs`), ask
- "May I write `Assets/Scripts/ScreenshotOnArg.cs`?" and write it exactly as
- given there before launching; if the user declines, nothing can capture —
- report `Run result: NOT VERIFIED — ScreenshotOnArg.cs not written`.
- Report exactly one line — `Run result: OBSERVED — <what was on screen>`
- with the retained path, `Run result: NOT VERIFIED — <reason>`, or
- `Run result: N/A — <reason>` for a story with genuinely nothing observable.
- **`NOT VERIFIED` is a blocker at the default gate level for Visual/Feel and
- UI, not a note** — `/story-done` reads this line. This step is **not waived
- at `qa.level: minimal`**; tests are, the look is not.
-
-**If INCOMPLETE:** say so as the headline, list what exists so far, name the
-specific breakage, and offer to resume the agent. Do **not** emit
-"Implementation Complete", and do not advance the story's status.
-
-### Then collect:
-
-- Files created or modified (with paths)
-- **Verification result** — what was run, and its outcome (or why it could not run)
-- Test file created (path and number of test functions written) — **or**, at
- `qa.level: minimal`, the waiver line from Phase 5
-- Any deviations from the story's Out of Scope boundary (flag these)
-- Any questions or blockers the agent surfaced
-- Any engine-specific risks the specialist flagged
-
-Present a concise implementation summary:
-
-```
-## Implementation Complete: [Story Title]
-
-**Files changed**:
-- `<code root>/[path]` — created / modified ([brief description])
-- `tests/[path]` — test file ([N] test functions) — *omit this line at
- `qa.level: minimal` and print the Phase 5 waiver line instead (Logic/Integration)*
-
-**Verification**: [what was run] — [result, or `NOT VERIFIED — <reason>`]
-**Run result**: [`OBSERVED — <what was on screen>` + retained path | `NOT VERIFIED — <reason>` | `N/A — <reason>`] — see `.claude/docs/run-and-observe.md`
-
-**Acceptance criteria covered**:
-- [x] [criterion] — implemented in [file:function]
-- [x] [criterion] — covered by test [test_name]
-- [x] [criterion] — OBSERVED in `production/qa/evidence/[slug]/01-[what].png` (Visual/UI look)
-- [ ] [criterion] — DEFERRED: requires playtest (Visual/Feel *feel* — timing, weight; a still cannot show it)
-
-**Deviations from scope**: [None] or [list files touched outside story boundary]
-**Engine risks flagged**: [None] or [specialist finding]
-**Blockers**: [None] or [describe]
-
-**Before running `/story-done`:** run your test suite locally and confirm the tests you wrote pass. *(At `qa.level: minimal` no tests were written — print the Phase 5 waiver line here instead of this paragraph for a Logic or Integration story, and omit both for any other type. Telling a user to confirm the passing of tests that do not exist is worse than saying nothing.)* **`/story-done` does NOT re-run them** — its Phase 3 checks that the test FILE exists, with `Glob`, and nothing executes it. A test that exists and fails satisfies that gate. Nothing downstream makes the local run safe to skip. Pass/fail is established by `/gate-check` and `/smoke-check`, both of which execute a suite — and both come later than story closure.
-
-Ready for: `/story-done [story-path]` — at `standard`/`full`, `/code-review [file1] [file2]` first
-```
-
----
diff --git a/.claude/skills/dev-story/references/7-session-state.md b/.claude/skills/dev-story/references/7-session-state.md
deleted file mode 100644
index 62943c93..00000000
--- a/.claude/skills/dev-story/references/7-session-state.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# /dev-story — Phase 7: Update Session State
-
-> Part of `/dev-story`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 7: Update Session State
-
-Silently update the checkpoint in `production/session-state/active.md` —
-**overwrite the `<!-- CHECKPOINT -->` … `<!-- /CHECKPOINT -->` block, never
-append** (schema: `.claude/docs/templates/session-state.md`). `session-start.sh`
-shows exactly that block when the next session opens, so it is what a cold
-resume starts from:
-
-```
-<!-- CHECKPOINT -->
-**Updated:** [date]
-**Branch:** `[current git branch]`
-**Current task:** /dev-story — [story-path] ([story title])
-**Next step:** /story-done [story-path] (at standard/full: /code-review [files] first)
-**Blocked on:** [nothing, or the blocker]
-**Files in progress:** [files changed, comma-separated; test file included]
-**Run result:** [the Phase 6 `Run result:` line, verbatim — `/story-done` reads it here]
-**Open questions:** [none, or one line each]
-<!-- /CHECKPOINT -->
-```
-
-**Next step** follows the Phase 6 result — the line above is the Implementation
-Complete one. On **INCOMPLETE** write
-`**Next step:** /dev-story [story-path] — resume: [the breakage Phase 6 named]`.
-On **BLOCKED** (Phase 2) write the unblocking action instead —
-`/architecture-decision accept ADR-NNNN`, the dependency story to finish, the
-manifest diff to review — and fill **Blocked on**. `/help` reads this line: a
-checkpoint that says `/story-done` tells it the work is written.
-
-If `active.md` does not exist, create it from the template. If it exists with no
-markers (a file from before the schema), insert the template's STATUS and
-CHECKPOINT blocks at the top and leave the rest untouched. Confirm: "Session
-state updated."
-
----
diff --git a/.claude/skills/dev-story/references/engine-checks.md b/.claude/skills/dev-story/references/engine-checks.md
new file mode 100644
index 00000000..806758b2
--- /dev/null
+++ b/.claude/skills/dev-story/references/engine-checks.md
@@ -0,0 +1,32 @@
+# Phase 6: Parse check and capture on Unity and Unreal
+
+Read only when the engine is Unity or Unreal. Report the command, its exit code
+and any error lines. No executable: `parse NOT VERIFIED — engine binary not
+available`.
+
+## Unity
+
+**Parse check:** the `commands.smoke` command (`-batchmode -quit -projectPath .
+-logFile -`). Exit 1 with `error CS…` lines means a script does not compile.
+
+**Capture** needs `Assets/Scripts/ScreenshotOnArg.cs`, given word for word in
+`run-and-observe.md` (named in `SKILL.md`, Phase 6). When the project has none
+(look for `Assets/**/ScreenshotOnArg.cs`), ask "May I write
+`Assets/Scripts/ScreenshotOnArg.cs`?" and write it exactly as given before
+launching. Declined: nothing can capture, so report
+`Run result: NOT VERIFIED — ScreenshotOnArg.cs not written`.
+
+## Unreal
+
+**Parse check:** build the editor target. A compile error fails it (`Result:
+Failed`, non-zero exit).
+
+- Windows: `"<UE root>/Engine/Binaries/DotNET/UnrealBuildTool/UnrealBuildTool.exe" <Project>Editor Win64 Development -Project="<absolute path>/<Project>.uproject"`
+- Linux: `"<UE root>/Engine/Build/BatchFiles/Linux/Build.sh" <Project>Editor Linux Development -Project=…`
+- macOS: `"<UE root>/Engine/Build/BatchFiles/Mac/Build.sh" <Project>Editor Mac Development -Project=…`
+
+The commands are from Epic's documentation, as recorded in
+`docs/engine-reference/unreal/current-best-practices.md` ("Command Line").
+
+**Capture:** launch straight into the map the story touched, as
+`run-and-observe.md` gives it.
diff --git a/.claude/skills/dev-story/references/version-mismatch.md b/.claude/skills/dev-story/references/version-mismatch.md
new file mode 100644
index 00000000..b04698de
--- /dev/null
+++ b/.claude/skills/dev-story/references/version-mismatch.md
@@ -0,0 +1,41 @@
+# Phase 2: When the ADR or the manifest changed after the story was written
+
+Read only when Phase 2 found a version mismatch.
+
+## The ADR
+
+The ADR's `version` (from `adr-status.sh`: its Last Verified date, else its Date,
+else `unversioned`) differs from the story's `ADR Version`, or the ADR is
+`unversioned` while the story names a date. Its decision may have changed.
+
+Ask: "Story was written against ADR v[story date]. The ADR is now v[current].
+How do you want to go on?" Options:
+
+- **Re-read the changed ADR and refresh the story (Recommended).** Read the ADR's
+ Decision, Engine Compatibility and ADR Dependencies sections with
+ `bash .claude/scripts/md-section.sh extract <adr> "Decision"` and the same for
+ the other two. Then edit the story: `ADR Version` becomes the ADR's `version`
+ (never today's date, or the next run mismatches again), and the ADR Decision
+ Summary and `## Implementation Notes` are replaced with the guidance you read.
+ The programmer's brief carries the new guidance, never the old summary.
+- **Implement from the story's summary — I accept the drift.** The brief carries the
+ summary and tells the agent it predates the current ADR. Note it under Deviations.
+- **Stop — I want to review the ADR first.** No agent runs.
+
+## The control manifest
+
+The story's `Manifest Version` differs from the manifest's. New rules may apply.
+
+Ask: "Story was written against manifest v[story date]. The current manifest is
+v[current]. How do you want to go on?" Options:
+
+- **Update the story's manifest version and use the current rules (Recommended).**
+ Set the story's `Manifest Version` to the current date, then read the layer's
+ rules for the brief.
+- **Use the old rules — I accept the risk.** Set `Manifest Version` to the current
+ date and add `Manifest-Note: Proceeded with old manifest rules on [date] —
+ non-compliance risk accepted.` to the story header. Note it under Deviations;
+ `/story-done` carries the note into its deviations.
+- **Stop — I want to review the manifest first.** No agent runs.
+
+Each option names the story edit it makes, so choosing it is the ask.
diff --git a/.claude/skills/estimate/SKILL.md b/.claude/skills/estimate/SKILL.md
index 1b0723f9..4087d927 100644
--- a/.claude/skills/estimate/SKILL.md
+++ b/.claude/skills/estimate/SKILL.md
@@ -15,7 +15,7 @@ Read the task description from the argument. If the description is too vague to
Read CLAUDE.md for project context: tech stack, coding standards, architectural patterns, and any estimation guidelines.
-Read relevant design documents from `design/gdd/` if the task relates to a documented feature or system.
+Read relevant design documents from `design/gdd/` if the task relates to a documented feature or system. Read them by section: find the headings you need with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit.
---
@@ -23,7 +23,18 @@ Read relevant design documents from `design/gdd/` if the task relates to a docum
Identify files and modules that would need to change:
-- Assess complexity (size, dependency count, cyclomatic complexity)
+- Measure size and branching with Grep, per affected file — Read, Glob and Grep
+ are this skill's only tools, so these counts are the measurement:
+ - **Size:** `Grep pattern="[^[:space:]]" path="[file]" output_mode="count"` —
+ non-blank lines.
+ - **Branching:** `Grep pattern="(^|[^A-Za-z0-9_])(if|elif|for|foreach|while|match|switch|case|catch)([^A-Za-z0-9_]|$)|&&|[|][|]" path="[file]" output_mode="count"` —
+ lines holding a branch or a boolean operator. The count
+ approximates cyclomatic complexity (comments and strings count too); report
+ it as that, never as a measured complexity.
+ - **Dependencies:** what each file pulls in — `preload`/`load(` (GDScript),
+ `using` (C#), `#include` (C++) — and which other files reference it.
+ - Name any file Grep could not count (missing, binary, unreadable) under Notes
+ and Assumptions rather than leaving it out of the totals.
- Identify integration points with other systems
- Check for existing test coverage in the affected areas
- Read past sprint data from `production/sprints/` for similar completed tasks and historical velocity.
@@ -36,7 +47,7 @@ Identify files and modules that would need to change:
## Phase 3: Analyze Complexity Factors
**Code Complexity:**
-- Lines of code in affected files
+- Size and branching of the affected files (Phase 2's Grep counts)
- Number of dependencies and coupling level
- Whether this touches core/engine code vs leaf/feature code
- Whether existing patterns can be followed or new patterns are needed
@@ -71,6 +82,7 @@ Generated: [Date]
|--------|-----------|-------|
| Systems affected | [List] | [Core, gameplay, UI, etc.] |
| Files likely modified | [Count] | [Key files listed below] |
+| Size of affected files | [N non-blank lines; M branch lines] | Grep counts; branch lines approximate complexity |
| New code vs modification | [Ratio] | |
| Integration points | [Count] | [Which systems interact] |
| Test coverage needed | [Low / Medium / High] | |
diff --git a/.claude/skills/gate-check/CONTRACT.md b/.claude/skills/gate-check/CONTRACT.md
index 32c85e3b..b1e3fb16 100644
--- a/.claude/skills/gate-check/CONTRACT.md
+++ b/.claude/skills/gate-check/CONTRACT.md
@@ -75,7 +75,7 @@ Validates whether the project is ready to advance from one development phase to
## Known Fragile Points
- `project.stage` in `project.yaml` (with legacy `production/stage.txt` as fallback) is the authoritative stage indicator — if either is manually edited to a wrong value outside of `/gate-check`, auto-detection in future sessions will be incorrect; never edit them outside `/gate-check`'s stage write
-- The Production → Polish gate runs the test suite via Bash. If the test runner command is not configured or fails to start (e.g. gdUnit4 is not installed at `addons/gdUnit4/`), the test check now yields `NOT ASSESSED`, which outranks PASS — so the gate cannot advance a stage on the strength of a suite that never ran. Without the `NOT ASSESSED` branch this masks silent test regressions: Section 3 runs the suite "if a test runner is configured", and with no else an unconfigured runner simply contributes nothing to the verdict
+- The Production → Polish gate runs the test suite via Bash. If the test runner command is not configured or fails to start (e.g. gdUnit4 is not installed at `addons/gdUnit4/`), the test check yields `NOT ASSESSED`, which outranks PASS — so the gate cannot advance a stage on the strength of a suite that never ran. With a concern also found, the verdict is CONCERNS, and its override is not offered while that check is NOT ASSESSED
- The Pre-Production → Production gate has a hard Vertical Slice validation block; any subjective checklist item (e.g., "core mechanic feels good") requires a user response via `AskUserQuestion` — if the user answers without playing the build, a false PASS is possible
- Gate report files in `production/gate-checks/` are not validated for completeness by any downstream skill; a partial report written due to a session interruption will look identical to a complete one
- `docs/consistency-failures.md` is optional context that adjusts scrutiny but does not change the formal checklist; if this file exists but is stale, the increased-scrutiny signals may point at resolved issues
diff --git a/.claude/skills/gate-check/SKILL.md b/.claude/skills/gate-check/SKILL.md
index 565c2065..ae3d0fec 100644
--- a/.claude/skills/gate-check/SKILL.md
+++ b/.claude/skills/gate-check/SKILL.md
@@ -3,7 +3,7 @@ name: gate-check
description: "Ready to advance between development phases? PASS/CONCERNS/NOT ASSESSED/FAIL with blockers and required artifacts. 'Can we move to production?'"
argument-hint: "[target-phase: systems-design | technical-setup | pre-production | production | polish | release] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/gate-check/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/gate-check/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/artifact-check.sh *), Bash(bash .claude/scripts/gdd-structure-check.sh*), Bash(bash .claude/scripts/adr-dep-graph.sh*), Bash(bash .claude/scripts/set-stage.sh *)
model: opus
---
@@ -75,7 +75,7 @@ width is `workflow`'s axis (Section 4b). This value affects only the
**specialist depth within each director's review**.
`individual` uses the core specialist set; `small` the standard set; `studio`
adds engine sub-specialists. It never skips a director — skipping directors is
-`review_mode`'s job. Both `review_mode` and `team.size` are now fronted by
+`review_mode`'s job. Both `review_mode` and `team.size` are set by
`modes.rigor` — one rigor choice sets both — and each still overrides that axis
when set explicitly (a full-rigor project gets the `studio` set; lighter tiers
get `individual`).
diff --git a/.claude/skills/gate-check/references/2b-workflow-tier.md b/.claude/skills/gate-check/references/2b-workflow-tier.md
index 432c3df1..91abf201 100644
--- a/.claude/skills/gate-check/references/2b-workflow-tier.md
+++ b/.claude/skills/gate-check/references/2b-workflow-tier.md
@@ -40,10 +40,10 @@ across all of them:
> a per-story evidence gate ... This divergence is intentional"). So a gate file
> that requires a smoke report keeps requiring it at every `qa.level`.
>
-> Without that exclusion the Production → Polish gate had **zero required
-> artifacts at `rigor: minimal`** and could not fail on artifacts by
-> construction: `minimal` reduced the gate to the smoke check alone, `qa.level`
-> then dropped the smoke check too, and one `modes.rigor` setting fires both.
+> Without that exclusion the Production → Polish gate would have **zero
+> required artifacts at `rigor: minimal`** and could not fail on artifacts by
+> construction: `minimal` reduces the gate to the smoke check alone, `qa.level`
+> would then drop the smoke check too, and one `modes.rigor` setting fires both.
> **A gate with no required artifacts left must say so, and may not return
> PASS.** After applying the tier reduction and the `qa.level` relaxation, count
@@ -70,10 +70,9 @@ across all of them:
> `off` is the only thing that makes budgets informational, and it is a
> deliberate choice the user makes on the same key.
>
-> Without this, `performance.enforce: block` is **inert on every `rigor: minimal`
-> project** — the Polish gate's `minimal` reduction drops everything outside its
-> floor, and "Performance is within budget" sits in the dropped remainder. A
-> setting that works only when a rule is disregarded is not wired.
+> This matters most on a `rigor: minimal` project: the Polish gate's `minimal`
+> reduction drops everything outside its floor, and "Performance is within
+> budget" sits in that dropped remainder. Run the check anyway.
### Per-system overrides (`workflow_overrides.system_overrides`)
diff --git a/.claude/skills/gate-check/references/3-run-gate-check.md b/.claude/skills/gate-check/references/3-run-gate-check.md
index 97db9669..c59b54e7 100644
--- a/.claude/skills/gate-check/references/3-run-gate-check.md
+++ b/.claude/skills/gate-check/references/3-run-gate-check.md
@@ -100,6 +100,8 @@ check the verdict line: a FAIL verdict means the cross-GDD consistency check fai
and must be resolved before advancing. A NOT ASSESSED verdict means that review
could not compare the GDDs, so it satisfies nothing here: mark the item NOT
ASSESSED for this gate, never passed.
+A report whose `Focus:` line names one pass only (a `consistency` or
+`design-theory` run) is treated the same way: the other pass never ran.
### Quality Checks
- For test checks: Run the test suite via `Bash` if a test runner is configured.
@@ -133,7 +135,10 @@ ASSESSED for this gate, never passed.
Bash: bash .claude/scripts/gdd-structure-check.sh
```
- It prints a `PRESENT:` / `ABSENT:` pair per GDD and already accepts
+ It prints a `PRESENT:` / `ABSENT:` pair per GDD, plus a `PLACEHOLDER:` line
+ naming present sections that hold only `[To be designed]` (present but
+ unwritten: `5-verdict.md`'s rule for template placeholders applies), and
+ already accepts
`## Detailed Design` as satisfying the `Detailed Rules` requirement. It reports
presence only and makes no REQUIRED/ADVISORY judgment.
@@ -142,7 +147,9 @@ ASSESSED for this gate, never passed.
Formulas) at `standard`. A missing *required* section blocks; a missing section
that is optional at the effective tier is advisory. A section reported PRESENT
can still fail review if it is an empty heading — spot-read any section the
- verdict actually turns on.
+ verdict actually turns on. Read GDDs by section: find the headings with
+ the Grep tool (pattern `^#`, content mode) and Read those ranges with offset
+ and limit.
- For performance checks: read the budgets (`performance.target_framerate`,
`frame_budget_ms`, `draw_call_limit`, `memory_ceiling_mb`) from `project.yaml`
(else technical-preferences.md) and compare against any profiling data in
diff --git a/.claude/skills/gate-check/references/4-assessment.md b/.claude/skills/gate-check/references/4-assessment.md
index 23d803f4..fe5e796c 100644
--- a/.claude/skills/gate-check/references/4-assessment.md
+++ b/.claude/skills/gate-check/references/4-assessment.md
@@ -92,6 +92,10 @@ gate files:
Anchor (from `design/gdd/game-concept.md`, else the "Art & audio direction"
line of `design/game-brief.md`), and the art bible path.
+Tell each director to read any GDD, ADR or the art bible by section: find the
+headings with the Grep tool (pattern `^#`, content mode) and Read those
+ranges with offset and limit.
+
Pass each context item as one of three things, so no director has to guess:
- **Present** — its path or value (`0` blocked stories is a value).
- **"none"** — the target gate (or an earlier one) requires or recommends it at
diff --git a/.claude/skills/gate-check/references/5-verdict.md b/.claude/skills/gate-check/references/5-verdict.md
index 03d914b6..3cbd8f7f 100644
--- a/.claude/skills/gate-check/references/5-verdict.md
+++ b/.claude/skills/gate-check/references/5-verdict.md
@@ -58,9 +58,9 @@ readable.
**Verdict precedence — first matching rule wins**, evaluated in this order:
**FAIL**, then **CONCERNS**, then **NOT ASSESSED**, then **PASS**. A gate with
both a real blocker and an unassessable check is FAIL: the blocker is the
-actionable finding. Stating the order mechanically removes the inference — the
-rank sentence above says what outranks what, but only an ordered list says what
-to do when two conditions hold at once.
+actionable finding. A CONCERNS verdict with an unassessable check still names
+that check under Blockers, as NOT ASSESSED with its reason: it is what keeps the
+stage from advancing (Section 6), so a reader must see it next to the concerns.
Emit it when any of:
@@ -82,7 +82,7 @@ Emit it when any of:
could still reach PASS. Meanwhile `testing.strict.logic` and
`.integration` both default to `true`, so the project's own configuration
called those gates BLOCKING. A blocking gate that never ran is the unknown this
- verdict exists to name. Remediation is already listed under Common Gaps
+ verdict exists to name. Remediation is already listed under Section 8's follow-up actions
(`/test-setup`); this is what the verdict does with it.
> **Scope this to tiers that require tests.** At `qa.level: minimal` no test
@@ -92,10 +92,8 @@ Emit it when any of:
> over-broad reading the director trigger below warns against. Fires only where
> the resolved tier actually asked for the test check.
- A **`MANUAL CHECK NEEDED` item the user never resolved**. Section 4 already
- refuses to assume PASS for unverifiable items and marks them this way — but
- until now the verdict vocabulary had nowhere to put one, so an unresolved
- manual check had to land inside PASS, CONCERNS or FAIL anyway. This is where it
- goes.
+ refuses to assume PASS for unverifiable items and marks them this way, and an
+ unresolved one lands here, never inside PASS, CONCERNS or FAIL.
- A director the **resolved tier was supposed to spawn** did not return — it
errored, produced no verdict, or was interrupted.
@@ -154,8 +152,8 @@ Do NOT reference the draft verdict text — re-check specific files or ask the u
- If any answer reveals a check that **could not be run** rather than one that
ran and passed → PASS→NOT ASSESSED. The first two PASS-draft questions above
("verified by actually reading a file, vs. inferring", "MANUAL CHECK NEEDED
- items I marked PASS") exist to find exactly this, and until now a yes to either
- had no verdict to move to
+ items I marked PASS") exist to find exactly this, and a yes to either moves
+ the verdict here
- If any answer reveals an over-stated blocker → downgrade only if citing specific evidence
- Never revise NOT ASSESSED down to PASS by re-reasoning about the missing input.
Only obtaining the input clears it
diff --git a/.claude/skills/gate-check/references/6-update-stage.md b/.claude/skills/gate-check/references/6-update-stage.md
index 62e4fc04..ef910c76 100644
--- a/.claude/skills/gate-check/references/6-update-stage.md
+++ b/.claude/skills/gate-check/references/6-update-stage.md
@@ -16,59 +16,38 @@ ask: "The gate returned CONCERNS. Accept these risks — [list] — and may I up
section to the gate report (each concern, accepted by the user, with the date)
and write the stage as below. **A FAIL is never overridden into a stage change, and
neither is NOT ASSESSED** — the blockers must be fixed, or the missing input
-produced, and the gate re-run.
-
-### 6.1 Primary write — `project.yaml`
-
-Set `project.stage` to the new stage name in `project.yaml` at the repo root.
-
-- **If a `project:` block already exists**: Read `project.yaml` first (the Edit
- tool requires the file to have been read in this session), then use the Edit
- tool to change its `stage:` value.
-- **If `project.yaml` exists but has no `project:` block**: Read `project.yaml`
- first, then use the Edit tool to insert the block immediately after the
- `framework:` block (before `modes:`). Insert exactly (replace `<new-stage>`):
- ```yaml
- project:
- stage: <new-stage>
- ```
-- **If `project.yaml` does not exist at all**: create it with the Write tool using
- this v1.1 minimal template (replace `<new-stage>` and the date):
- ```yaml
- # CCGS project configuration — single source of truth for project settings.
- # Schema: grep the `## <key>` section of .claude/docs/effects-map.md —
- # it is ~31k tokens whole, ~900 per section. Do not open it entire.
-
- schema_version: 1
-
- framework:
- version: 1.1.3
- last_upgraded: <YYYY-MM-DD>
-
- project:
- stage: <new-stage>
- ```
- Do not seed `modes.review_mode` here. It is a rigor-fronted knob — `modes.rigor`
- supplies its value, so an explicit value would shadow the rigor expansion and pin
- the review mode regardless of the project's rigor.
-
-### 6.2 Legacy fallback write — `production/stage.txt`
-
-Also write the single-line stage name (no trailing newline) so hooks that have not
-migrated still work. Ensure the `production/` directory exists first:
+produced, and the gate re-run. That holds inside a CONCERNS verdict too: CONCERNS
+outranks NOT ASSESSED in the verdict, but while any required check is NOT ASSESSED
+the override is not offered. Name each such check and what would let it run.
+
+### 6.1 Write the stage
+
+After the yes, write both stage files with one command (quote a two-word stage):
+
```bash
-mkdir -p production && printf '%s' "Production" > production/stage.txt
+bash .claude/scripts/set-stage.sh "<new-stage>"
```
-### 6.3 Verify both writes
+It sets `project.stage` in `project.yaml`: it edits the `stage:` line, adds a
+`project:` block after `framework:` when there is none, or creates the file from
+the minimal template when there is no `project.yaml`. It keeps comments, other
+keys and line endings. It also writes the legacy `production/stage.txt`, so hooks
+that have not migrated still work, then reads both files back. It never seeds
+`modes.review_mode`: `modes.rigor` supplies that, and an explicit value would pin
+the review mode whatever the project's rigor.
+
+### 6.2 Verify both writes
-After both writes, Read `project.yaml` and `production/stage.txt` and confirm both
-show the new stage. If they diverge, report the discrepancy to the user and stop —
-a split stage indicator corrupts future auto-detection.
+Show its `stage_yaml` and `stage_txt` rows. Exit 0 means both files hold the new
+stage. Exit 4 means they disagree after writing: report the discrepancy to the
+user and stop, because a split stage indicator corrupts future auto-detection.
+Exit 5 means `project.yaml` has a layout the script will not edit (`project:` as
+a one-line value): nothing was written, so say so and edit `project.yaml` with
+the user's yes. Any other non-zero exit: report the message and stop.
**Always ask before writing**: "Gate passed. May I update `project.stage` in `project.yaml` to 'Production' (and the legacy `production/stage.txt`)?" — on an accepted CONCERNS override, the explicit yes above is that ask.
-### 6.4 Rigor-fit check (advisory — never affects the verdict)
+### 6.3 Rigor-fit check (advisory — never affects the verdict)
After the stage advance is confirmed, apply the raise trigger in
`.claude/docs/settings-guidance.md § 4`: if the new stage is **Production** (or
diff --git a/.claude/skills/gate-check/references/7-next-steps.md b/.claude/skills/gate-check/references/7-next-steps.md
index fa939b0a..1f989973 100644
--- a/.claude/skills/gate-check/references/7-next-steps.md
+++ b/.claude/skills/gate-check/references/7-next-steps.md
@@ -18,8 +18,10 @@ being entered, so `/gate-check systems-design` is the Concept → Systems Design
**At `workflow: minimal`, skip the menus below.** They walk the phase ladder, and
the minimal route is not the ladder: offer the first incomplete step of
`paths.minimal` instead (the `--path minimal` rows from Section 3):
-`/setup-engine`, then `/brainstorm`, then `/create-stories`, then `/dev-story`
-on the next story — the route `/help` gives.
+`/setup-engine`, then `/brainstorm` (or `/reverse-document design [code root]`
+when the code root already holds the game: it writes the brief from what is
+built), then `/create-stories`, then `/dev-story` on the next story — the route
+`/help` gives.
For **Concept → Systems Design** (`/gate-check systems-design`) PASS — option [A] is
`/map-systems` when `design/gdd/systems-index.md` does not exist yet (many
@@ -83,7 +85,7 @@ Based on the verdict, suggest specific next steps:
- **Small design change needed?** → `/quick-design` for changes under about one week of implementation (bypasses full GDD pipeline)
- **No UX specs?** → `/ux-design [screen name]` to author specs, or `/team-ui [feature]` for full pipeline
- **UX specs not reviewed?** → `/ux-review [file]` or `/ux-review all` to validate
-- **No accessibility requirements doc?** → run `/ux-design` which creates both `design/accessibility-requirements.md` and `design/ux/interaction-patterns.md` in one step
+- **No accessibility requirements doc?** → `/ux-design accessibility` to write `design/accessibility-requirements.md`
- **No interaction pattern library?** → `/ux-design patterns` to initialize it
- **Concept or a GDD not reviewed?** → `/design-review [doc]`
- **GDDs not cross-reviewed?** → `/review-all-gdds` (run after all MVP GDDs are individually approved)
@@ -104,13 +106,11 @@ Based on the verdict, suggest specific next steps:
- **No Difficulty Curve doc?** → Author `design/difficulty-curve.md` by hand from the template at `.claude/docs/templates/difficulty-curve.md`. (`/quick-design` is a related session but writes to `design/quick-specs/`, not to this path — use it to think the curve through, then copy the outcome here.)
- **No player journey map?** → Author `design/player-journey.md` by hand from the template at `.claude/docs/templates/player-journey.md`.
-> **Neither of these has a skill that writes it — the remediations must not imply
-> otherwise.** Naming "`/ux-design` Phase 2b" would point at the step that *reads*
-> `design/player-journey.md`, landing the user back at the check that just
-> failed. Naming `/quick-design` would point at a skill that writes
-> `design/quick-specs/[name]-[date].md` and would leave this gate still failing.
-> Both docs are hand-authored from their templates; say so plainly rather than
-> naming a skill that cannot produce them.
+> **Neither of these has a skill that writes it — do not name one.**
+> "`/ux-design` Phase 2b" is the step that *reads* `design/player-journey.md`,
+> so it lands the user back at the check that just failed. `/quick-design`
+> writes `design/quick-specs/[name]-[date].md` and leaves this gate still
+> failing. Say plainly that both docs are hand-authored from their templates.
- **Need a quick sprint check?** → `/sprint-status` for current sprint progress snapshot
- **Performance unknown?** → `/perf-profile`
- **Not localized?** → `/localize`
diff --git a/.claude/skills/gate-check/references/gate-polish.md b/.claude/skills/gate-check/references/gate-polish.md
index aae3cc08..d61efcfe 100644
--- a/.claude/skills/gate-check/references/gate-polish.md
+++ b/.claude/skills/gate-check/references/gate-polish.md
@@ -11,7 +11,7 @@
- [ ] Main gameplay path is playable end-to-end
- [ ] Test files exist under the engine's test root — `tests/unit/` and `tests/integration/` (Godot), `Assets/Tests/EditMode/` and `Assets/Tests/PlayMode/` (Unity), `Source/<Module>/Private/Tests/` (Unreal) — covering Logic and Integration stories
- [ ] All Logic stories from this sprint have corresponding unit test files in the engine's unit-test location (`tests/unit/`, `Assets/Tests/EditMode/` or `Source/<Module>/Private/Tests/`)
-- [ ] Smoke check has been run with a PASS or PASS WITH WARNINGS verdict — report exists in `production/qa/`
+- [ ] Smoke check has been run with a PASS or PASS WITH WARNINGS verdict — report exists in `production/qa/` (a `quick` run, labelled `(quick — …)`, does not count: it skipped the coverage scan)
- [ ] At least one QA plan exists in `production/qa/` (generated by `/qa-plan`) covering this sprint, the final production sprint, or this production phase — run `/qa-plan` if missing (CONCERNS — advisory, not blocking)
- [ ] QA sign-off report exists in `production/qa/` (generated by `/team-qa`) with verdict APPROVED or APPROVED WITH CONDITIONS
- [ ] At least 3 distinct playtest sessions documented in `production/qa/playtests/`
diff --git a/.claude/skills/gate-check/references/gate-pre-production.md b/.claude/skills/gate-check/references/gate-pre-production.md
index 74704544..7531d723 100644
--- a/.claude/skills/gate-check/references/gate-pre-production.md
+++ b/.claude/skills/gate-check/references/gate-pre-production.md
@@ -21,6 +21,24 @@
- [ ] `design/accessibility-requirements.md` exists with accessibility tier committed
- [ ] `design/ux/interaction-patterns.md` exists (pattern library initialized, even if minimal)
+**Which `/architecture-review` report counts.** Read the `Mode:` line of each
+`docs/architecture/architecture-review-*.md`, and for each item below use the
+newest report whose mode checked it:
+
+| Item | Modes that check it |
+|---|---|
+| `/architecture-review` has been run | `full` |
+| Traceability matrix has zero Foundation layer gaps | `full`, `coverage`, `rtm` |
+| Engine audit shows no deprecated API usage | `full`, `engine` |
+
+A `single-gdd` report saw one system and a `consistency` report only compared
+ADRs, so neither counts here. When no report's mode checked an item,
+that item is NOT ASSESSED, never passed on a narrower report: name the newest report's
+mode and the run that closes it (run `/architecture-review full`, or the mode
+the table names). A report with no `Mode:` line was written before 1.2.0 and
+does not say what it checked, so it counts for none of the three, as
+`/architecture-review` itself rules.
+
**Quality Checks:**
- [ ] Architecture decisions cover core systems (rendering, input, state management)
- [ ] Technical preferences have naming conventions and performance budgets set
@@ -41,14 +59,20 @@ eventually misses an edge; the script cannot:
Bash: bash .claude/scripts/adr-dep-graph.sh
```
It prints `ADRS`, `EDGES` (one `adr-A -> adr-B` per Depends-On reference),
-`NO_DEPS_SECTION` (ADRs with no Depends On), and a `CYCLE:` line per node in any
-dependency cycle.
+`NO_DEPS_SECTION` (ADRs with no Depends On), `UNFILLED_DEPS` (a Depends On row
+still the template's placeholder), a `CYCLE:` line per ADR on a dependency cycle
+with its edges into that cycle, `BLOCKED_BY_CYCLE` (ADRs on no cycle that depend
+on one) and `ORDER` (the rest, dependencies first).
- **Any `CYCLE:` lines → FAIL**: "Circular ADR dependency: [the nodes on the
`CYCLE:` lines]. Neither can reach Accepted while the cycle exists. Remove one
- 'Depends On' edge to break the cycle."
+ 'Depends On' edge shown on a `CYCLE:` line to break the cycle." Name the
+ `BLOCKED_BY_CYCLE` ADRs as waiting on the cycle, not as part of it: none of
+ their own edges is the one to remove.
- No `CYCLE:` lines → this check passes. But the acyclic result is only as
- trustworthy as the dependency sections are complete: if `NO_DEPS_SECTION` lists
- many ADRs, surface that as a CONCERNS note rather than a clean pass.
+ trustworthy as the dependency sections are complete: if `NO_DEPS_SECTION` or
+ `UNFILLED_DEPS` lists many ADRs, surface that as a CONCERNS note rather than a
+ clean pass, naming each `UNFILLED_DEPS` ADR as unfilled (what it depends on is
+ unknown, not none).
**Engine Validation** (read `docs/engine-reference/[engine]/VERSION.md` first):
- [ ] ADRs that touch post-cutoff engine APIs are flagged with Knowledge Risk: HIGH/MEDIUM
diff --git a/.claude/skills/gate-check/references/gate-release.md b/.claude/skills/gate-check/references/gate-release.md
index 0ee05fea..3d99960c 100644
--- a/.claude/skills/gate-check/references/gate-release.md
+++ b/.claude/skills/gate-check/references/gate-release.md
@@ -12,7 +12,7 @@
- [ ] QA test plan exists (`/qa-plan` output in `production/qa/`)
- [ ] QA sign-off report exists (`/team-qa` output — APPROVED or APPROVED WITH CONDITIONS)
- [ ] All Must Have story test evidence is present (Logic/Integration: test files pass; UI: retained screenshots of each screen touched; Visual/Feel: retained screenshots plus lead sign-off — both in `production/qa/evidence/`, and no `qa.level` waives either)
-- [ ] Smoke check passes cleanly (PASS verdict) on the release candidate build
+- [ ] Smoke check passes cleanly (PASS verdict) on the release candidate build — a full run, not a `quick` one labelled `(quick — …)`
- [ ] No test regressions from previous sprint (test suite passes fully)
- [ ] Balance data has been reviewed (`/balance-check` run)
- [ ] Release checklist completed (`/release-checklist` run)
diff --git a/.claude/skills/gate-check/references/gate-technical-setup.md b/.claude/skills/gate-check/references/gate-technical-setup.md
index 57b4eda1..0f6a1a79 100644
--- a/.claude/skills/gate-check/references/gate-technical-setup.md
+++ b/.claude/skills/gate-check/references/gate-technical-setup.md
@@ -12,7 +12,7 @@
**Quality Checks:**
- [ ] All MVP GDDs pass individual design review (8 required sections, no MAJOR REVISION NEEDED verdict)
-- [ ] `/review-all-gdds` verdict is not FAIL (cross-GDD consistency and design theory checks pass). A NOT ASSESSED verdict does not satisfy this: that review could not compare the GDDs, so this item is NOT ASSESSED for the gate
+- [ ] `/review-all-gdds` verdict is not FAIL (cross-GDD consistency and design theory checks pass). A NOT ASSESSED verdict does not satisfy this: that review could not compare the GDDs, so this item is NOT ASSESSED for the gate. Nor does a focus-run report (its `Focus:` line names one pass only): the other pass never ran, so the item stays open until a review runs both
- [ ] All cross-GDD consistency issues flagged by `/review-all-gdds` are resolved or explicitly accepted
- [ ] System dependencies are mapped in the systems index and are bidirectionally consistent
- [ ] MVP priority tier is defined
diff --git a/.claude/skills/help/SKILL.md b/.claude/skills/help/SKILL.md
index ef1f080a..01f5396d 100644
--- a/.claude/skills/help/SKILL.md
+++ b/.claude/skills/help/SKILL.md
@@ -143,8 +143,8 @@ against the working tree and reports one line per step. Map its statuses:
| `NO_CHECK` | **MANUAL** if the step carries a `note=`, else **UNKNOWN** — completion is not trackable (e.g. repeatable implementation work) |
Do not re-derive any of this with Glob/Grep. `any_of` in particular is a list of
-**alternatives** — one match is enough — and hand-evaluating it has already
-produced a false "incomplete" once: `engine-setup` is satisfied by `engine.name`
+**alternatives** — one match is enough — and hand-evaluating it risks a false
+"incomplete": `engine-setup` is satisfied by `engine.name`
in `project.yaml` **or** by the legacy `Engine:` line in
`.claude/docs/technical-preferences.md`, and the script reports which alternative
matched (`alt=`/`match=`).
@@ -189,7 +189,11 @@ Map the statuses exactly as in Step 4. `implement` and `story-done` are
step is the first of these that applies:
1. `engine-setup` not PRESENT → `/setup-engine`
-2. `game-brief` not PRESENT → `/brainstorm` (at `minimal` it writes the one-page brief)
+2. `game-brief` not PRESENT → `/reverse-document design [code root]` when the
+ code root already holds the game (10 or more source files, the test Step 2
+ uses for `production`): at `minimal` it writes `design/game-brief.md` from
+ what is built. Otherwise `/brainstorm` (at `minimal` it writes the one-page
+ brief), which on a built game would start a new idea.
3. `create-stories` not PRESENT → `/create-stories` with no argument (at
`minimal` it builds the stories straight from the brief's MVP list)
4. Stories exist → the list below was printed by `.claude/scripts/story-status.sh`
diff --git a/.claude/skills/hotfix/SKILL.md b/.claude/skills/hotfix/SKILL.md
index 00272624..9b593944 100644
--- a/.claude/skills/hotfix/SKILL.md
+++ b/.claude/skills/hotfix/SKILL.md
@@ -4,7 +4,7 @@ description: "Emergency fix bypassing normal sprint process — hotfix branch, a
argument-hint: "[bug-id or description]"
user-invocable: true
disable-model-invocation: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(git rev-parse *), Bash(git tag --list*), Bash(git branch --list *)
model: sonnet
---
diff --git a/.claude/skills/launch-checklist/SKILL.md b/.claude/skills/launch-checklist/SKILL.md
index 6eb71c91..cf329189 100644
--- a/.claude/skills/launch-checklist/SKILL.md
+++ b/.claude/skills/launch-checklist/SKILL.md
@@ -3,6 +3,7 @@ name: launch-checklist
description: "Launch readiness across every department: code, content, store, marketing, community, infrastructure, legal, go/no-go sign-offs."
argument-hint: "[launch-date or 'dry-run']"
user-invocable: true
+disable-model-invocation: true
allowed-tools: Read, Glob, Grep, Write, AskUserQuestion, Bash(bash "*/.claude/skills/launch-checklist/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
@@ -45,11 +46,10 @@ trains the reader to skip the list, which defeats the gate:
- `console` — full platform certification (TRC / XR / Lotcheck), save-data
rules, controller-mapping rules, age-rating boards. The heaviest tier.
- > **Branch on the `cert_tier` values above, not on platform names.** "Emit
- > console/mobile certification items only for the platforms the project targets"
- > is the wrong test: it treats an `itch` project and a `steam` project
- > identically, conflates `none` with unset, and keys on `mobile`, which is not a
- > `cert_tier` value at all. Use the vocabulary the config defines.
+ > **Branch on the `cert_tier` values above, not on platform names.** A test on
+ > target platforms treats an `itch` project and a `steam` project identically,
+ > conflates `none` with unset, and keys on `mobile`, which is not a `cert_tier`
+ > value at all. Use the vocabulary the config defines.
If an item cannot be scoped because the config is absent, mark it
**`NOT ASSESSED — platform/stage unknown`**. Do not silently include it: a
@@ -60,8 +60,6 @@ ratings, of which ~140 are unassessable.
---
-> **Explicit invocation only**: This skill should only run when the user explicitly requests it with `/launch-checklist`. Do not auto-invoke based on context matching.
-
## Phase 1: Parse Arguments
Read the argument for the launch date or `dry-run` mode. Dry-run mode generates the checklist without creating sign-off entries or writing files. With no argument the run is a normal one with the target date unset (`Target Launch: not set`) — dry-run only when the argument says `dry-run`.
@@ -91,13 +89,11 @@ Read the argument for the launch date or `dry-run` mode. Dry-run mode generates
> (resolve per `.claude/docs/code-root-resolution.md`); assets live in
> `assets/`, `Assets/` or `Content/`.
>
-> This is written once, over the whole phase, rather than under **one** of the
-> four bullets. All four search the code root the same way — for placeholder assets,
-> TODOs, debug output and hardcoded test values — so if only one carries the
-> warning, an empty or absent code root returns zero
-> hits three times and read as three clean results. With no `assets/` directory,
-> for example, the placeholder scan returns zero hits, and "All placeholder art
-> replaced" would be ticked green.
+> This applies to all four bullets below: each searches the same way, for
+> placeholder assets, TODOs, debug output and hardcoded test values, and each
+> returns zero hits on an empty or absent root. With no `assets/` directory, for
+> example, the placeholder scan returns zero hits, and a bare tick would mark
+> "All placeholder art replaced" green.
- Count `TODO`, `FIXME`, `HACK` comments and their locations
- Check for any `console.log`, `print()`, or debug output left in production code
@@ -224,14 +220,10 @@ do not fall back to emitting all of them.
**Every tier**, because these are not certification-gated:
- [ ] Accessibility: minimum standards met (remapping, text scaling, colorblind)
-> **Keep this template gated by tier.** An ungated list — PC *and* Console *and*
-> Mobile rows emitted at every tier — contradicts the `cert_tier` rule at the top
-> of this skill, which says an `itch` project gets no console and no Steamworks
-> items. When a rule and a template disagree, the template wins in practice,
-> because a template is what gets copied.
->
-> Changing the branching vocabulary is only half the job: the rows that branching
-> governs have to move with it, or the rule describes behaviour nothing reaches.
+> **Emit this section gated by tier, never as one ungated list.** PC *and*
+> Console *and* Mobile rows emitted at every tier contradict the `cert_tier` rule
+> at the top of this skill, which says an `itch` project gets no console and no
+> Steamworks items.
### Performance
- [ ] Target FPS met on minimum spec hardware
diff --git a/.claude/skills/localize/SKILL.md b/.claude/skills/localize/SKILL.md
index 9370f766..5eccbecd 100644
--- a/.claude/skills/localize/SKILL.md
+++ b/.claude/skills/localize/SKILL.md
@@ -3,7 +3,7 @@ name: localize
description: "Localization pipeline — find hardcoded strings, extract string tables, cultural review, VO, RTL, enforce string freeze."
argument-hint: "[scan|extract|validate|status|brief|cultural-review|vo-pipeline|rtl-check|freeze|qa]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Bash, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/localize/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/localize/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
@@ -140,7 +140,9 @@ Generate a translator context briefing document. This document is sent to the
external translation team or localisation vendor alongside the string table export.
Read:
-- `design/gdd/` — extract game genre, tone, setting, character names
+- `design/gdd/` — extract game genre, tone, setting, character names. Read the
+ GDDs by section: find the headings you need with the Grep tool (pattern `^#`,
+ content mode) and Read those ranges with offset and limit.
- `assets/data/strings/strings-en.json` — the source string table
- Any existing lore or narrative documents in `design/narrative/`
diff --git a/.claude/skills/map-systems/SKILL.md b/.claude/skills/map-systems/SKILL.md
index 78b1a566..4dd6b792 100644
--- a/.claude/skills/map-systems/SKILL.md
+++ b/.claude/skills/map-systems/SKILL.md
@@ -74,7 +74,9 @@ every section you author.
## Phase 1: Read Concept (Required Context)
Read the game concept and any existing design work. This provides the raw material
-for systems decomposition.
+for systems decomposition. Read each doc by section: find the headings you need with
+the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and
+limit.
**Required:**
- Read `design/gdd/game-concept.md` (at `minimal`, read `design/game-brief.md`
@@ -152,12 +154,6 @@ Then use `AskUserQuestion` to capture feedback:
**At `autonomous`** — do not ask. Record the enumeration and its inferred systems
via `log_decision` and proceed.
-> **The loop needed an exit that does not depend on being asked.**
-> `automation-modes.md:56` defines `autonomous` as *"No `AskUserQuestion`"*, so a
-> loop terminating on "the user approves" has no termination path there at all.
-> Same class as Step 5b, one level up: that was an unconditional *write* gate,
-> this is an unconditional *control-flow loop* around the question.
-
---
## Phase 3: Dependency Mapping (Collaborative)
@@ -256,10 +252,8 @@ both, and cites the pillar it serves:
costs before any of the choices built on top of it mean anything"
> **Fill the brackets from *this* project.** The bracketed slots are not
-> decoration. Worked examples from another genre (a tower-defense "Ballista's
-> punch-through identity… what makes it feel different from Archer", "Pillar 2:
-> Placement is the Puzzle") get reproduced verbatim by a run against a different
-> game, which then carries that game's vocabulary instead of its own.
+> decoration. Reasoning copied from another game's worked example carries that
+> game's vocabulary instead of this one's.
**Review mode check** — apply before spawning PR-SCOPE:
- `solo` → skip. Note: "PR-SCOPE skipped — Solo mode." Proceed to Step 4c.
@@ -321,12 +315,6 @@ write?" for new files. When the index already exists, present the summary above,
name the destination (`design/gdd/systems-index.md`), and write the update without
waiting for an explicit "yes". Say what you wrote afterwards.
-> **Keep this line scoped to its mode.** `automation-modes.md` says `guided`
-> *"proceeds after a short summary, does not wait for explicit yes"* and asks
-> "May I write?" *"for new files only"*, and this skill's own Collaborative
-> Protocol section is scoped to `collaborative`. An unconditional "wait for
-> approval" here collides with both.
-
**Review mode check** — apply before spawning CD-SYSTEMS:
- `solo` → skip. Note: "CD-SYSTEMS skipped — Solo mode." Proceed to Step 5c.
- `lean` → skip (not a PHASE-GATE). Note: "CD-SYSTEMS skipped — Lean mode." Proceed to Step 5c.
diff --git a/.claude/skills/milestone-review/SKILL.md b/.claude/skills/milestone-review/SKILL.md
index 5d071d5d..7490deb0 100644
--- a/.claude/skills/milestone-review/SKILL.md
+++ b/.claude/skills/milestone-review/SKILL.md
@@ -80,14 +80,11 @@ report whole:
Grep pattern="^## (Sprint Goal|Capacity|Tasks|Carryover|Risks|Progress|Burndown Assessment|Emerging Risks|Definition of Done)" glob="production/sprints/sprint-*.md" output_mode="content" -A 12
```
-> **These alternates are copied from `/sprint-plan`'s emitted headings — keep
-> them in sync with it, not with what a milestone review wishes existed.** The
-> previous pattern asked for `Summary|Goal|Velocity|Completed|Blockers|
-> Retrospective`, none of which `/sprint-plan` writes (it emits `## Sprint
-> Goal`, not `## Goal`). Only `Carryover` matched — and that was the trap: a
-> non-zero match count meant the zero-match escape hatch below could never
-> fire, so every milestone review silently aggregated carryover tables and
-> nothing else while reporting full coverage.
+> **These alternates are the headings `/sprint-plan` emits** (`## Sprint Goal`,
+> not `## Goal`) — not what a milestone review might expect. A pattern that
+> matches only one real heading still returns a non-zero count, so the
+> zero-match escape hatch below never fires and the review aggregates a fraction
+> of each report while reporting full coverage.
Full-read a single sprint report when its scanned sections point outside
themselves, or when it matched nothing — a zero-match report predates the
diff --git a/.claude/skills/patch-notes/SKILL.md b/.claude/skills/patch-notes/SKILL.md
index bd6a16b1..4bf6cb6f 100644
--- a/.claude/skills/patch-notes/SKILL.md
+++ b/.claude/skills/patch-notes/SKILL.md
@@ -3,7 +3,7 @@ name: patch-notes
description: "Player-facing patch notes from git history and changelogs. Translates developer language into player communication."
argument-hint: "[version] [--style brief|detailed|full]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Bash, Bash(bash "*/.claude/skills/patch-notes/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/patch-notes/../../hooks/yaml-helper.sh" resolve_config *), Bash(git log *)
model: sonnet
---
@@ -40,13 +40,10 @@ before Phase 2 and stop if it fails.
> **Filter per commit; do not stop on a repo that merely contains maintenance
> work.** Every project built on this framework accumulates commits touching
-> hooks, CI and skills — the game repo *is* the framework repo. An earlier
-> version of this check listed "subjects naming the framework, its skills, hooks,
-> agents or test plan" as a hard STOP, which fires on virtually every real
-> project and contradicted its own step 2 whenever a history was mostly the
-> game's. The danger was never that such commits *exist*; it is that they get
-> **rendered as player-facing copy**. Excluding them addresses that exactly, and
-> a repo-level stop does not.
+> hooks, CI and skills — the game repo *is* the framework repo, so a repo-level
+> stop fires on virtually every real project. The danger is not that such
+> commits *exist*; it is that they get **rendered as player-facing copy**.
+> Excluding them addresses that exactly, and a repo-level stop does not.
Corroborate before you proceed, cheaply: the Game commits should name systems
that appear in `design/` and the code root (`src/`, `Assets/` or `Source/`). If
@@ -62,12 +59,11 @@ If **no** commit in the range is this game's, say so and stop:
Verdict: **BLOCKED** — stop here without generating notes.
-**Why this is a hard stop, not a warning.** This exact failure is real, not
-hypothetical: a batch of framework-internal commits produced player-facing copy
-reading *"Fixed an issue where progress from your last session could be lost on launch"*
-— a session-hook timeout rendered as a gameplay fix for a game with **no save
-system**. It was fluent, plausible, and entirely false. A reader cannot tell the
-difference; only this check can.
+**Why this is a hard stop, not a warning.** Framework-internal commits rendered
+as player copy read as real changes: a session-hook timeout becomes *"Fixed an
+issue where progress from your last session could be lost on launch"* in a game
+with **no save system**. That copy is fluent, plausible, and entirely false. A
+reader cannot tell the difference; only this check can.
---
diff --git a/.claude/skills/perf-profile/SKILL.md b/.claude/skills/perf-profile/SKILL.md
index 554caf1e..f7a95b9f 100644
--- a/.claude/skills/perf-profile/SKILL.md
+++ b/.claude/skills/perf-profile/SKILL.md
@@ -3,7 +3,7 @@ name: perf-profile
description: "Performance profiling — find bottlenecks, measure against budgets, produce ranked optimization recommendations."
argument-hint: "[system-name or 'full']"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Bash, Bash(bash "*/.claude/skills/perf-profile/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/perf-profile/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash "*/.claude/skills/perf-profile/../../hooks/yaml-helper.sh" get_effective_yaml_key *)
model: sonnet
---
@@ -82,28 +82,21 @@ Read the argument:
record of what it agreed to, and design docs are the fallback, not the source:
```bash
-(cd "${CLAUDE_SKILL_DIR}/../../.." && source .claude/hooks/yaml-helper.sh 2>/dev/null &&
- echo "performance.target_framerate: $(get_effective_yaml_key performance.target_framerate)" &&
- echo "performance.frame_budget_ms: $(get_effective_yaml_key performance.frame_budget_ms)" &&
- echo "performance.draw_call_limit: $(get_effective_yaml_key performance.draw_call_limit)" &&
- echo "performance.memory_ceiling_mb: $(get_effective_yaml_key performance.memory_ceiling_mb)")
+bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.target_framerate
+bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.frame_budget_ms
+bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.draw_call_limit
+bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.memory_ceiling_mb
```
-Run it as one command: it loads the helper from the project root, so it works
-when the session was started in a subfolder. An empty value after a key means
-that budget is not set.
-
-> Written as four literal keys rather than a loop over leaf names, deliberately.
-> The dead-settings audit matches the **full dotted key**, so a loop building
-> `performance.$k` leaves three of the four spelled nowhere and the audit
-> reports them DEAD while this skill reads them. Spell each key out in full.
+Run each line as its own plain command, one key per call: the helper moves to
+the project root itself, so it works when the session was started in a
+subfolder, and this skill pre-approves that form only (a `source` or `cd ... &&`
+wrapper asks the user every time). Empty output means that budget is not set.
> **Resolve these budgets from `project.yaml`, not from prose.** Phase 0 above
-> states these four budgets "are profiled the same way at every level". Sending
-> the reader to *"design docs or CLAUDE.md"* instead means a user who set
-> `performance.target_framerate: 60` in `project.yaml` has it ignored by the one
-> skill that profiles against budgets. The keys resolve correctly — this phase
-> has to actually ask for them.
+> states these four budgets "are profiled the same way at every level". A user
+> who set `performance.target_framerate: 60` in `project.yaml` has it ignored if
+> the budget is read from design docs or CLAUDE.md instead.
Then fall back to design docs or CLAUDE.md for anything config does not carry:
diff --git a/.claude/skills/playtest-report/SKILL.md b/.claude/skills/playtest-report/SKILL.md
index aa418a24..9df02469 100644
--- a/.claude/skills/playtest-report/SKILL.md
+++ b/.claude/skills/playtest-report/SKILL.md
@@ -108,7 +108,7 @@ In `new` mode, stop here with: Verdict: **COMPLETE** — blank template output;
## Phase 2B: Analyze Mode
-Read the raw notes at the provided path. Cross-reference with existing design documents. Fill in the template above with structured findings. Flag any playtest observations that conflict with design intent.
+Read the raw notes at the provided path. Cross-reference with existing design documents, reading each by section: find the headings you need with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit. Fill in the template above with structured findings. Flag any playtest observations that conflict with design intent.
An observation that describes a defect — a crash, a framerate drop, a softlock,
something that plainly breaks rather than plays badly — goes in the **Bugs
diff --git a/.claude/skills/project-stage-detect/SKILL.md b/.claude/skills/project-stage-detect/SKILL.md
index e7c48c01..ac6e3e82 100644
--- a/.claude/skills/project-stage-detect/SKILL.md
+++ b/.claude/skills/project-stage-detect/SKILL.md
@@ -32,15 +32,12 @@ every file write follows `.claude/docs/automation-modes.md`
Resolved above — use as-is. No block → defaults in
`.claude/docs/config-resolution.md`.
-> **Resolve the tier — do not assume it.** Saying "surface gaps per the **resolved** workflow
-> tier" without resolving it — no bootstrap, no helper call — leaves
-> the tier as whatever the model assumed. The tier decides what counts as a gap
+> **Resolve the tier — do not assume it.** The tier decides what counts as a gap
> at all: at `full` every missing doc is one; at `minimal` none of them are,
> because a brief plus an engine is the normal state and code is the expected
> next step. Guessing high tells a jam project it is missing GDDs, an art bible
> and ADRs — the exact "process feels mismatched to my project" experience
-> `modes.rigor` exists to prevent. A missing bootstrap is invisible to a static
-> read — the config block simply does not render — so verify it by running.
+> `modes.rigor` exists to prevent.
**`workflow`** (per `.claude/docs/workflow-modes.md`). The tier governs
which absent documents count as gaps (step 3) — below `full`, optional docs are
@@ -76,7 +73,9 @@ track, and the judgement calls.
- Count GDD files in `design/gdd/*.md`
- Check for game-concept.md (or `design/game-brief.md` at `minimal`), game-pillars.md, systems-index.md
- If systems-index.md exists, count total systems vs. designed systems
-- Analyze completeness (Overview, Detailed Design, Edge Cases, etc.)
+- Analyze completeness (Overview, Detailed Design, Edge Cases, etc.). Read GDDs
+ by section: find the headings you need with the Grep tool (pattern `^#`, content
+ mode) and Read those ranges with offset and limit.
- Count narrative docs in `design/narrative/`
- Count level designs in `design/levels/`
@@ -270,6 +269,9 @@ resolved workflow tier surfaces** (step 3). At `standard`/`minimal`, do not
suggest authoring optional docs (e.g. don't suggest `/reverse-document` for an
absent GDD at `minimal`, where code is the expected next step):
+- **No `design/game-brief.md` at `minimal`?** → `/reverse-document design <code root>`
+ when the code root already holds the game (10 or more source files): it writes
+ the brief from what is built. With little or no code, `/brainstorm`.
- **Concept exists but no systems index?** → `/map-systems` to decompose into systems
- **Missing design docs?** → `/reverse-document design <code root>/[system]`
- **Missing architecture docs?** → `/architecture-decision` or `/reverse-document architecture`
diff --git a/.claude/skills/propagate-design-change/SKILL.md b/.claude/skills/propagate-design-change/SKILL.md
index ac753154..576f628d 100644
--- a/.claude/skills/propagate-design-change/SKILL.md
+++ b/.claude/skills/propagate-design-change/SKILL.md
@@ -1,225 +1,166 @@
---
name: propagate-design-change
-description: "A GDD changed — scan ADRs and the traceability index for now-stale architectural decisions. Impact report, guides resolution."
+description: "Finds architecture decisions (ADRs) made stale by a changed GDD and walks through resolving each. Use when the user changed a number or rule in a GDD and asks which ADRs or architecture decisions are now out of date."
argument-hint: "[path/to/changed-gdd.md] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Bash, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/propagate-design-change/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/propagate-design-change/../../hooks/yaml-helper.sh" resolve_config *), Bash(git diff *), Bash(git log *), Bash(bash .claude/scripts/adr-status.sh*), Bash(bash .claude/scripts/md-section.sh *)
model: sonnet
---
-!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,system_overrides`
+!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,automation_always_ask,workflow,system_overrides`
Resolved above — use as-is; `--review` overrides `review_mode` for this run. No
block → defaults in `.claude/docs/config-resolution.md`.
-# Propagate Design Change
-
-When a GDD changes, architectural decisions written against it may no longer be
-valid. This skill finds every affected ADR, compares what the ADR assumed against
-what the GDD now says, and guides the user through resolution.
+Ask with the question tool. Without one, list the options numbered and end your turn
+to wait. A skipped or dismissed question is not an answer: ask again in plain text.
-**Usage:** `/propagate-design-change design/gdd/combat-system.md`
-
----
+# Propagate Design Change
-Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
-(collaborative asks always · guided major-only · autonomous logs and proceeds;
-`automation_always_ask` categories always prompt — ADR/schema impacts here fall
-under `schema_changes` and `architecture_decisions`).
+When a GDD changes, the architecture decisions written against it may no longer
+hold. This skill finds every ADR the change touches, compares what the ADR assumed
+with what the GDD says now, and walks the user through each one.
-**Workflow tier**: resolve for the **changed GDD's system** (per
-`.claude/docs/workflow-modes.md`): use the
-`system_overrides` row for that system if the block lists one, else the
-project value. (A system pinned `minimal` has no ADRs even on a `standard`
-project — so its change is N/A.) It scopes the cascade: `full` cascades across all
-ADRs; `standard` checks only critical (Foundation-layer) ADRs plus any ADR
-referencing the changed GDD; `minimal` is **not applicable** — no ADRs to cascade.
-See Step 4.
+**Example:** `/propagate-design-change design/gdd/combat-system.md`
-## 1. Validate Argument
+Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided
+asks on major choices, autonomous logs and goes on; `automation_always_ask`
+categories always ask: an ADR impact here is `schema_changes` and
+`architecture_decisions`).
-A GDD path argument is **required**. If missing, fail with:
-> "Usage: `/propagate-design-change design/gdd/[system].md`
-> Provide the path to the GDD that was changed."
+**Tier.** `workflow` for the changed GDD's system: its `system_overrides` row if
+there is one, else the project value. A system pinned `minimal` has no ADRs even on
+a `standard` project. `full` checks every ADR; `standard` checks the critical
+(Foundation-layer) ADRs and any ADR that names the changed GDD; `minimal` has
+nothing to check (Phase 4).
-Verify the file exists. If not, fail with:
-> "[path] not found. Check the path and try again."
+## Phase 1: The GDD path
----
+The text typed after the skill name, with any `--review <mode>` pair removed, is the
+changed GDD. It is required. Missing: "Usage: `/propagate-design-change
+design/gdd/[system].md` — give the path to the GDD that changed." Not a file:
+"[path] not found. Check the path and try again."
-## 2. Diff the GDD Against Its Previous Version
+## Phase 2: What changed
-**Ask git what changed — do not read two whole documents and compare them by
-eye.** The previous form of this step read the current GDD in full *and*
-`git show`-ed the full committed version, then diffed them mentally: two entire
-documents in context to find what is usually a handful of lines, and a model
-comparing 400-line documents will eventually miss an edit. Git cannot.
+Ask git, never compare two whole documents by eye:
```bash
git diff HEAD -- design/gdd/[filename].md
```
-If that is empty, the change may already be committed — widen to the commit that
-last touched it:
+Empty: the change may be committed already, so widen to the last commit that
+touched it: `git diff HEAD~1 HEAD -- design/gdd/[filename].md`.
-```bash
-git diff HEAD~1 HEAD -- design/gdd/[filename].md
-```
-
-If the file has no git history (new file), report:
-> "No previous version in git — this appears to be a new GDD, not a revision.
-> Nothing to propagate."
-
-If the diff is empty **and** the file has history, report that plainly — "no
-uncommitted or last-commit changes to `[file]`" — and ask which revision to
-propagate. An empty diff is not "no impact"; it means nothing changed *here*.
-
-From the diff hunks:
-- Identify sections that changed (new rules, removed rules, modified formulas,
- changed acceptance criteria, changed tuning knobs). The `@@` hunk headers name
- the enclosing section, so the changed-section list falls out of the diff itself.
-- Read the surrounding section from the current GDD **only** where a hunk is too
- small to interpret on its own (a changed number whose meaning depends on the
- rule above it). That is a targeted read of one section, not the document.
-- Sections with no hunk are unchanged — by construction, not by inspection.
----
+- No history at all (`git log --oneline -1 -- design/gdd/[filename].md` prints
+ nothing): "No previous version in git — this is a new GDD, not a revision.
+ Nothing to propagate." Stop.
+- History, but both diffs empty: report "no uncommitted or last-commit changes to
+ `[file]`" and ask which revision to propagate. An empty diff means nothing changed
+ *here*, not that nothing is affected.
-## 3. Produce the Change Summary
+From the hunks: the `@@` headers name the section each change sits in, so the
+changed-section list comes from the diff itself. A section with no hunk is unchanged
+by construction. Read the surrounding section only when a hunk cannot be understood
+alone (a changed number whose meaning depends on the rule above it), and then only
+that section: `bash .claude/scripts/md-section.sh extract design/gdd/[file].md "[Section]"`.
-From the hunks resolved in step 2:
+## Phase 3: The change summary
```
## Change Summary: [GDD filename]
Date of revision: [today]
Changed sections:
-- [Section name]: [what changed — new rule, removed rule, formula modified, etc.]
+- [Section]: [what changed — new rule, removed rule, formula modified, …]
Unchanged sections:
-- [Section name]
+- [Section]
Key changes affecting architecture:
-- [Change 1 — likely to affect ADRs]
-- [Change 2]
+- [change likely to affect ADRs]
```
-**Downstream GDD impact via the registry.** If `design/registry/entities.yaml`
-exists, it already records which other GDDs depend on this system's facts —
-compute the affected set from it rather than re-reading every GDD:
-```
-Grep pattern="source: design/gdd/[filename]" path="design/registry/entities.yaml" output_mode="content" -A 6
-```
-For each entity/constant/formula this GDD **owns** whose value the diff changed,
-its `referenced_by:` list is the set of downstream GDDs that may now be
-inconsistent — report them under "Downstream GDDs to re-check". **If
-`design/registry/entities.yaml` does not exist or has no entries** (it ships as
-an empty stub until `/design-system` populates it), skip this — the ADR cascade
-below still runs.
+**Other GDDs that use these facts.** When `design/registry/entities.yaml` does not
+exist or has no entries (it ships as an empty stub until `/design-system` fills it),
+skip this; the ADR check below still runs. Otherwise it records which GDDs depend on
+this system's facts: search it for `source: design/gdd/[filename]`. For each entity, constant or formula this GDD owns
+whose value the diff changed, its `referenced_by:` list names the GDDs that may now
+disagree. List them under "Downstream GDDs to re-check".
----
+## Phase 4: The ADRs in scope
-## 4. Load Architecture Inputs
-
-Read ADRs in `docs/architecture/` **per the resolved tier**:
-- **`full`** — read **all** ADRs.
-- **`standard`** — read only **critical (Foundation-layer) ADRs** plus any ADR
- that references the changed GDD. An ADR is critical when the `**Layer**` row of
- its `## Engine Compatibility` table says `Foundation`, or when it has no
- `**Layer**` row — when in doubt, treat it as critical
- (`.claude/docs/workflow-modes.md`). Read every row in one call:
- `Grep pattern="\*\*Layer\*\*" glob="docs/architecture/adr-*.md" output_mode="content"`,
- and count an ADR that Grep does not list as critical.
-- **`minimal`** — **not applicable**: there are no ADRs to cascade. Report "No ADR
- cascade at minimal workflow — design change recorded; no architecture impact
- analysis." and stop here.
-
-**Establish the denominator first.** Glob the in-scope ADRs (per the tier above).
-Call the count **N**. If N is 0: "No ADRs found in `docs/architecture/` — nothing
-to cascade." Stop.
-
-**Scan the requirement tables — do not full-read the ADRs at this step:**
-```
-Grep pattern="## GDD Requirements Addressed" glob="docs/architecture/adr-*.md" output_mode="content" -A 15
-```
-**Recall net — an ADR may cite the changed GDD in prose without tabling it:**
-```
-Grep pattern="[changed-gdd-basename]" glob="docs/architecture/adr-*.md" output_mode="files_with_matches"
-```
-Take the **union** of the two results as the affected set **M**. This turns
-N × ~200 lines into N × ~15 lines; §5 full-reads only the M.
+`bash .claude/scripts/adr-status.sh` lists every ADR with its status, layer and
+missing sections.
-Interpret the result — a zero-match scan is **never** "no impact" by default:
+- **`full`:** every ADR.
+- **`standard`:** the critical ones (the `layer` column reads Foundation, or holds
+ no layer: when in doubt, critical) and any ADR that names the changed GDD.
+- **`minimal`:** report "No ADR check at minimal workflow — design change recorded;
+ no architecture impact analysis." Stop.
-| Result | Meaning | Action |
-|---|---|---|
-| **M ≥ 1** | Normal. | Proceed. The N − M non-matching ADRs are *out of scope for this cascade* — do not describe them as verified unaffected. |
-| **Both scans 0, N > 0** | Ambiguous — either no ADR references this GDD, or the ADRs lack requirement tables. | Run `Grep pattern="## GDD Requirements Addressed" glob="docs/architecture/adr-*.md" output_mode="files_with_matches"`. If that is **also** empty: "[N] ADRs found, none contains a 'GDD Requirements Addressed' section — traceability cannot be computed (a `gate-pre-production` blocker). Run `/architecture-decision retrofit [adr]`." If it is **non-empty**: the tables exist and genuinely none reference this GDD — "No ADR references [gdd] — no architecture impact." |
+Establish the denominator first: their count is **N**. N is 0: "No ADRs found in `docs/architecture/` — nothing to
+check." Stop.
-Read `docs/architecture/requirements-traceability.md` if it exists.
+**Which ones reference this GDD.** Without reading whole ADRs:
-Report: "Loaded [N] ADRs by scan. [M] reference [gdd filename] ([X] via
-requirements table, [Y] via prose reference only)."
+1. each ADR's GDD Requirements Addressed section
+ (`bash .claude/scripts/md-section.sh extract <adr> "GDD Requirements Addressed"`),
+ for rows naming the changed GDD;
+2. a search of the ADRs for the changed GDD's file name, which catches an ADR that
+ cites it in prose without a table row.
----
+The union of the two is the affected set **M**.
-## 5. Impact Analysis
+| Result | Meaning | Action |
+|---|---|---|
+| **M ≥ 1** | Normal. | Go on. The N − M others are out of scope for this check: never describe them as verified unaffected. |
+| **M = 0**, and every in-scope ADR lacks GDD Requirements Addressed (`missing` column) | Traceability cannot be computed. | "[N] ADRs found, none has a 'GDD Requirements Addressed' section — traceability cannot be computed (a pre-production gate blocker). Run `/architecture-decision retrofit [adr]`." Stop. |
+| **M = 0**, the sections exist | No ADR references this GDD. | "No ADR references [gdd] — no architecture impact." Stop. |
-Now read each ADR in the affected set **M** for its reasoning, not just its
-table — judging whether a decision is still valid needs the ADR's `## Context`
-and `## Decision` (and `## Consequences` where present), not scan output. **Do
-not attempt the judgement below from scan output.**
+Read `docs/architecture/requirements-traceability.md` when it exists.
-This read is unbounded only up to a point — check size first
-(`Bash: wc -c "docs/architecture/[adr-file].md"`):
-- **Under ~50KB** — one full `Read` is fine and cheapest at this size.
-- **~50KB or larger** — map headings first
- (`Grep pattern="^## " path="docs/architecture/[adr-file].md" output_mode="content" -n`),
- then bounded-`Read` only `## Context`, `## Decision`, and `## Consequences`.
- An unbounded `Read` on a large ADR hits the 25k-token cap and, unrecovered,
- the only path forward is paging through the entire remainder — most of it
- content this analysis never uses.
+Report: "Checked [N] ADRs. [M] reference [gdd filename] ([X] in a requirements
+table, [Y] in prose only)."
-For each ADR that references the changed GDD:
+## Phase 5: Impact analysis
-Compare the ADR's "GDD Requirements Addressed" entries against the changed sections
-of the GDD. For each referenced requirement:
+For each ADR in **M**, read its Context, Decision and Consequences sections with
+`md-section.sh extract`: whether a decision still holds needs its reasoning, never
+only its table row. Then, for each requirement it lists from the changed GDD:
-1. **Locate the requirement** in the current GDD — does it still exist?
-2. **Compare**: What did the GDD say when the ADR was written vs. what it says now?
-3. **Assess the ADR decision**: Is the architectural decision still valid?
+1. Does the requirement still exist in the current GDD?
+2. What did the GDD say when the ADR was written, and what does it say now?
+3. Does the decision still hold?
-Classify each affected ADR as one of:
+Classify each ADR:
| Status | Meaning |
|--------|---------|
-| ✅ **Still Valid** | The GDD change doesn't affect what this ADR decided |
-| ⚠️ **Needs Review** | The GDD change may affect this ADR — human judgment needed |
-| 🔴 **Likely Superseded** | The GDD change directly contradicts what this ADR assumed |
-
-For each affected ADR, produce an impact entry:
+| ✅ **Still Valid** | The change does not touch what this ADR decided |
+| ⚠️ **Needs Review** | The change may affect it; human judgement needed |
+| 🔴 **Likely Superseded** | The change contradicts what this ADR assumed |
```
### ADR-NNNN: [title]
-Status: [Still Valid / Needs Review / Likely Superseded]
+Status: [Still Valid | Needs Review | Likely Superseded]
What the ADR assumed about this GDD:
- "[relevant quote from the ADR's GDD Requirements Addressed section]"
+ "[quote from its GDD Requirements Addressed or Context]"
What the GDD now says:
- "[relevant quote from the current GDD]"
+ "[quote from the current GDD]"
Assessment:
- [Explanation of whether the ADR decision is still valid, and why]
+ [whether the decision still holds, and why]
Recommended action:
- [Keep as-is | Review and update | Mark Superseded and write new ADR]
+ [Keep as-is | Review and update | Mark Superseded and write a new ADR]
```
----
-
-## 6. Present Impact Report
+## Phase 6: The impact report, then the review
-Present the full impact report to the user before asking for any action. Format:
+Show the whole report before asking for any action:
```
## Design Change Impact Report
@@ -229,63 +170,70 @@ Changes detected: [N sections changed]
ADRs referencing this GDD: [M]
### Not Affected
-[ADRs referencing this GDD whose decisions remain valid]
+[ADRs whose decisions still hold]
### Needs Review ([count])
[ADRs that may need updating]
### Likely Superseded ([count])
-[ADRs whose assumptions are now contradicted]
+[ADRs whose assumptions the change contradicts]
```
----
+**The technical review.** Read the `review_gate` line above. `skill-gates=skip`
+(solo or lean): no agent; note `TD-CHANGE-IMPACT skipped — [Solo | Lean] mode`.
+`skill-gates=run`: hand the review to the `technical-director` agent with gate
+**TD-CHANGE-IMPACT** (`.claude/docs/director-gates/td-change-impact.md`; the agent
+reads it itself). Brief:
+
+- **Objective:** check the impact report before the user acts on it.
+- **Give it:** the whole report above: the change summary, every affected ADR with
+ its classification and recommended action.
+- **Check:** no ADR is under-classified; the recommended actions are sound; no
+ knock-on effect on other ADRs or systems was missed.
+- **Return:** APPROVE, CONCERNS, REJECT, or NOT ASSESSED naming a missing input.
+- **Boundaries:** it edits no file.
+
+Act on the verdict:
+
+- **APPROVE:** go to Phase 7.
+- **CONCERNS:** show the flagged ADRs or actions, and ask: "How do you want to go
+ on?" Options: Revise the impact assessment / Accept with the noted concerns /
+ Discuss further.
+- **REJECT:** do not go to Phase 7; analyse the impact again first.
+- **NOT ASSESSED:** it is not an approval (`.claude/docs/director-gates.md`). Name
+ what was missing, then supply it and run the review again; or, when the user
+ chooses to go on without it, go to Phase 7 and state `TD-CHANGE-IMPACT: NOT
+ ASSESSED — [input]` in the report and the final verdict line.
+
+## Phase 7: Resolve each ADR
+
+For each ADR marked Needs Review or Likely Superseded, one at a time, ask: "ADR-NNNN
+([title]) — [status]. What would you like to do?" Options:
+
+- Mark it Superseded (I'll write the new ADR)
+- Update it in place (a small revision): note what to revise; the user edits it
+- Keep it as it is (the change does not affect this decision)
+- Skip it for now (revisit later)
+
+**Mark Superseded.** Ask "May I set the Status of [ADR file] to Superseded?" On yes,
+replace only the body of its `## Status` section:
-## 6b. Director Gate — Technical Impact Review
-
-**Review mode check** — apply before spawning TD-CHANGE-IMPACT:
-- `solo` → skip. Note: "TD-CHANGE-IMPACT skipped — Solo mode." Proceed to Phase 7.
-- `lean` → skip. Note: "TD-CHANGE-IMPACT skipped — Lean mode." Proceed to Phase 7.
-- `full` → spawn as normal.
-
-Spawn `technical-director` via `Agent` using gate **TD-CHANGE-IMPACT** (`.claude/docs/director-gates/td-change-impact.md`).
-
-Pass: the full Design Change Impact Report from Phase 6 (change summary, all affected ADRs with their Still Valid / Needs Review / Likely Superseded classifications, and recommended actions).
-
-The technical-director reviews whether:
-- The impact classifications are correct (no ADRs under-classified)
-- The recommended actions are architecturally sound
-- Any cascading effects on other ADRs or systems were missed
-
-Apply the verdict:
-- **APPROVE** → proceed to Phase 7 resolution workflow
-- **CONCERNS** → surface the specific ADRs or recommendations flagged; use `AskUserQuestion` with options: `Revise the impact assessment` / `Accept with noted concerns` / `Discuss further`
-- **REJECT** → do not proceed to resolution; re-analyze the impact before continuing
-- **NOT ASSESSED** [missing input] → not an approval (`.claude/docs/director-gates.md`): name what was missing, then supply it and re-run the gate — or, if the user chooses to go on without it, proceed to Phase 7 and state `TD-CHANGE-IMPACT: NOT ASSESSED — [input]` in the change impact report and the final Verdict line
-
----
-
-## 7. Resolution Workflow
-
-For each ADR marked "Needs Review" or "Likely Superseded", ask the user what to do:
-
-Ask for each ADR in turn:
-> "ADR-NNNN ([title]) — [status]. What would you like to do?"
-> Options:
-> - "Mark Superseded (I'll write a new ADR)" — updates ADR status line to `Superseded by: [pending]`
-> - "Update in place (minor revision)" — opens the ADR for editing; note what to revise
-> - "Keep as-is (the change doesn't actually affect this decision)"
-> - "Skip for now (revisit later)"
+```
+bash .claude/scripts/md-section.sh replace docs/architecture/[adr-file].md "Status" <<'EOF'
+Superseded — replacement pending (see docs/architecture/change-impact-[date]-[system-slug].md)
+EOF
+```
-For ADRs marked **Superseded**:
-- Update the ADR's Status field: `Superseded by ADR-[next number] (pending — see change-impact-[date]-[system].md)`
-- Ask: "May I update the status in [ADR filename]?"
+This is the one form this skill writes. `adr-status.sh` reads it as Superseded, so
+`/dev-story` and `/create-stories` block the stories that still point at it. The
+new ADR, once written, records which one it replaces. Change nothing else in the
+ADR: its content stays.
----
+## Phase 8: The traceability index
-## 8. Update Traceability Index
-
-If `docs/architecture/requirements-traceability.md` exists:
-- Add the changed GDD requirements to the "Superseded Requirements" table:
+When `docs/architecture/requirements-traceability.md` exists, ask "May I add the
+changed requirements to the traceability index?" On yes, add a row per changed
+requirement:
```markdown
## Superseded Requirements
@@ -294,45 +242,22 @@ If `docs/architecture/requirements-traceability.md` exists:
| [date] | [gdd] | [old requirement text] | [new requirement text] | ADR-NNNN | [Superseded/Updated/Valid] |
```
-Ask: "May I update the traceability index?"
-
----
-
-## 9. Output Change Impact Document
-
-Ask: "May I write the change impact report to `docs/architecture/change-impact-[date]-[system-slug].md`?"
-
-The document contains:
-- The change summary from step 3
-- The full impact analysis from step 5
-- Resolution decisions made in step 7
-- List of ADRs that need to be written or updated
+## Phase 9: The change impact document
-If user approved: Verdict: **COMPLETE** — change impact report saved.
-If user declined: Verdict: **BLOCKED** — user declined write.
+Ask "May I write the change impact report to
+`docs/architecture/change-impact-[date]-[system-slug].md`?" It holds the change
+summary, the impact analysis, the resolution chosen for each ADR, and the ADRs that
+need writing or updating.
----
-
-## 10. Follow-Up Actions
-
-Based on the resolution decisions, suggest:
-
-- **ADRs marked Superseded**: "Run `/architecture-decision [title]` to write the
- replacement ADR. Then re-run `/propagate-design-change` to verify coverage."
-- **ADRs to update in place**: List the specific fields to update in each ADR
-- **If many ADRs affected**: "Run `/architecture-review` after all ADRs are updated
- to verify the full traceability matrix is still coherent."
-
----
+## Phase 10: Follow-up
-## Collaborative Protocol
+From the resolutions:
-**Applies in `collaborative` mode (the default).** For `guided` and
-`autonomous` modes, see `.claude/docs/automation-modes.md` — the rules below
-describe what collaborative mode requires, not universal behavior.
+- ADRs marked Superseded: "Run `/architecture-decision [title]` to write the
+ replacement, then `/propagate-design-change` again to check coverage."
+- ADRs to update in place: the fields to change in each.
+- Many ADRs affected: "Run `/architecture-review` once they are updated, to check
+ the traceability matrix still holds together."
-1. **Read silently** — compute the full impact before presenting anything
-2. **Show the full report first** — let the user see the scope before asking for action
-3. **Ask per-ADR** — don't batch decisions; each affected ADR may need different treatment
-4. **Ask before writing** — always confirm before modifying any file
-5. **Non-destructive** — never delete ADR content; only add "Superseded by" notes
+End with `Verdict: COMPLETE — change impact report saved` after the Phase 9 write,
+or `Verdict: BLOCKED — user declined the write` when declined.
diff --git a/.claude/skills/prototype/SKILL.md b/.claude/skills/prototype/SKILL.md
index 056d63e4..526f19b6 100644
--- a/.claude/skills/prototype/SKILL.md
+++ b/.claude/skills/prototype/SKILL.md
@@ -3,7 +3,7 @@ name: prototype
description: "Concept prototype before GDDs — throwaway HTML, Engine or Paper build, PROCEED/PIVOT/KILL/NOT ASSESSED. After /brainstorm and /setup-engine."
argument-hint: "[concept-description] [--path html|engine|paper] [--review full|lean|solo] [--spike]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/prototype/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/prototype/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
diff --git a/.claude/skills/prototype/references/1-question.md b/.claude/skills/prototype/references/1-question.md
index 3fb2e521..42f6f162 100644
--- a/.claude/skills/prototype/references/1-question.md
+++ b/.claude/skills/prototype/references/1-question.md
@@ -21,7 +21,7 @@ intent before proceeding — with or without a carry-forward note:
- **Prompt**: "How would you like to use this prototype session?"
- **Options**:
- - `Prototype this concept` — build a throwaway build to validate the core idea is fun before writing GDDs (1–3 days)
+ - `Prototype this concept` — build a throwaway build to validate the core idea is fun before writing GDDs (1 day at most)
- `Skip — concept already proven` — I have enough evidence this works; log it and proceed directly to design
- `Mid-production spike` — I'm already in Production and want to test a specific mechanic or technical question quickly (~4 hours, no phase gate implications)
diff --git a/.claude/skills/prototype/references/2-load-context.md b/.claude/skills/prototype/references/2-load-context.md
index 23c9de60..ad6b6fb2 100644
--- a/.claude/skills/prototype/references/2-load-context.md
+++ b/.claude/skills/prototype/references/2-load-context.md
@@ -6,7 +6,9 @@
## Phase 2: Load Concept Context
Read `design/gdd/game-concept.md` — or `design/game-brief.md`, the one-page brief
-that replaces it at `rigor: minimal` — if either exists. Extract:
+that replaces it at `rigor: minimal` — if either exists. Read it by section: find the
+headings you need with the Grep tool (pattern `^#`, content mode) and Read those
+ranges with offset and limit. Extract:
- Core fantasy (what the player is supposed to feel)
- Core loop (the moment-to-moment action being tested)
diff --git a/.claude/skills/prototype/references/8-cd-review.md b/.claude/skills/prototype/references/8-cd-review.md
index acc9500f..c0e9c0a4 100644
--- a/.claude/skills/prototype/references/8-cd-review.md
+++ b/.claude/skills/prototype/references/8-cd-review.md
@@ -16,7 +16,9 @@
Pass: the full REPORT.md content, the original hypothesis, and game pillars /
core fantasy from `design/gdd/game-concept.md` (or the brief's pitch and "what
-they feel" line from `design/game-brief.md`).
+they feel" line from `design/game-brief.md`). Read the concept by section: find the
+headings you need with the Grep tool (pattern `^#`, content mode) and Read those
+ranges with offset and limit.
The creative director evaluates the result against the game's creative vision and
returns one of the gate's verdicts — APPROVE, CONCERNS or REJECT — or NOT
diff --git a/.claude/skills/qa-plan/SKILL.md b/.claude/skills/qa-plan/SKILL.md
index d91dace1..a32307db 100644
--- a/.claude/skills/qa-plan/SKILL.md
+++ b/.claude/skills/qa-plan/SKILL.md
@@ -86,12 +86,6 @@ for one missing file.
> QA plan.** This skill gates the hand-off to manual QA, so a false-clean here
> sends a build to QA on the strength of a plan that tested nothing.
>
-> Note the shape, because this skill already had the harder half of the rule.
-> Phase 2 states **"Never treat an absent section as an absent story"** — the
-> sophisticated inner case, correctly handled. The outer boundary, no stories at
-> all, had nothing. The same shape appears in `/story-readiness`, where `NOT ASSESSED`
-> existed for per-story failures and the empty scope could not reach it.
->
> The rule at the top of this block still stands: one missing file among several
> is MISSING-and-continue. This is the different case where there is no *several*.
@@ -135,8 +129,9 @@ After reading stories, load supporting context once (not per story):
(**Acceptance Criteria** and **Edge Cases** always, plus **Formulas** for any
system that defines numeric rules); at `minimal`, **Acceptance
Criteria only**. Do not load the full GDD
- text. These sections contain the testable requirements, the math to verify, and
- the boundary conditions tests must cover. If an Edge Cases section is absent (or
+ text. Find the section headings with the Grep tool (pattern `^#`, content mode) and Read
+ those ranges with offset and limit. These sections contain the testable requirements, the math
+ to verify, and the boundary conditions tests must cover. If an Edge Cases section is absent (or
not expected at minimal), note per GDD: "No Edge Cases section found — edge case
coverage will be inferred from acceptance criteria only."
- `docs/architecture/control-manifest.md` — scan for forbidden patterns that
@@ -267,8 +262,8 @@ list when running that skill.*
|-------|--------------|--------------|-------------------|
| [story] | [What question must the session answer?] | [N] | [new player / experienced] |
-**Sign-off requirement**: Playtest notes must be written to
-`production/session-logs/playtest-[sprint]-[story-slug].md` and reviewed by
+**Sign-off requirement**: Playtest notes must be written with `/playtest-report` to
+`production/qa/playtests/` (naming the story) and reviewed by
the [designer / qa-lead] before the story can be marked COMPLETE.
If no stories require playtest validation: *No playtest sessions required for
diff --git a/.claude/skills/quick-design/SKILL.md b/.claude/skills/quick-design/SKILL.md
index 6f29afeb..a7f7f3df 100644
--- a/.claude/skills/quick-design/SKILL.md
+++ b/.claude/skills/quick-design/SKILL.md
@@ -73,7 +73,9 @@ Otherwise: proceed with the selected type.
## 2. Context Scan
-Before drafting anything, read the relevant context:
+Before drafting anything, read the relevant context. Read the GDD and the systems
+index by section: find the headings you need with the Grep tool (pattern `^#`,
+content mode) and Read those ranges with offset and limit.
- Search `design/gdd/` for the GDD most relevant to this change. Read the
sections that this change would affect. If no GDD covers this system — usually
diff --git a/.claude/skills/regression-suite/SKILL.md b/.claude/skills/regression-suite/SKILL.md
index 63ed888d..00a73c4d 100644
--- a/.claude/skills/regression-suite/SKILL.md
+++ b/.claude/skills/regression-suite/SKILL.md
@@ -115,6 +115,10 @@ scope the scan by each system's workflow tier (resolved above):
(Tier affects `audit` mode only; `update` and `report` modes are tier-independent.)
+Read each GDD by section: find the headings you need with the Grep tool (pattern
+`^#`, content mode) and Read those ranges with offset and limit. At `full` that
+is every section, read in ranges, since a whole-file Read over 40 KB is refused.
+
For each in-scope MVP-tier system's GDD, extract:
- Acceptance Criteria (these define the critical paths)
- Formulas section (formulas must have regression tests)
@@ -238,10 +242,6 @@ Check for drift indicators:
> same defect `/scope-check` carries a Phase 4 guard against, in the same words:
> *"a percentage computed from no baseline items is not a small number; it is not
> a number."*
->
-> **A hand-written list of skills required to carry `NOT ASSESSED` pins what was
-> known when it was written**, so a skill added later inherits no obligation and
-> nothing notices. Derive that set rather than enumerating it.
The manifest is a curated index — not the tests themselves, but a registry
of which tests should always pass before a release:
diff --git a/.claude/skills/release-checklist/SKILL.md b/.claude/skills/release-checklist/SKILL.md
index 8fa713a0..b0cee9d1 100644
--- a/.claude/skills/release-checklist/SKILL.md
+++ b/.claude/skills/release-checklist/SKILL.md
@@ -44,11 +44,10 @@ trains the reader to skip the list, which defeats the gate:
- `console` — full platform certification (TRC / XR / Lotcheck), save-data
rules, controller-mapping rules, age-rating boards. The heaviest tier.
- > **Branch on the `cert_tier` values above, not on platform names.** "Emit
- > console/mobile certification items only for the platforms the project targets"
- > is the wrong test: it treats an `itch` project and a `steam` project
- > identically, conflates `none` with unset, and keys on `mobile`, which is not a
- > `cert_tier` value at all. Use the vocabulary the config defines.
+ > **Branch on the `cert_tier` values above, not on platform names.** A test on
+ > target platforms treats an `itch` project and a `steam` project identically,
+ > conflates `none` with unset, and keys on `mobile`, which is not a `cert_tier`
+ > value at all. Use the vocabulary the config defines.
If an item cannot be scoped because the config is absent, mark it
**`NOT ASSESSED — platform/stage unknown`**. Do not silently include it: a
@@ -59,8 +58,6 @@ ratings, of which ~140 are unassessable.
---
-> **Explicit invocation only**: This skill should only run when the user explicitly requests it with `/release-checklist`. Do not auto-invoke based on context matching.
-
## Phase 1: Parse Arguments
Read the argument for the target platform (`pc`, `console`, `mobile`, or `all`). If no platform is specified, default to `all`.
@@ -96,10 +93,6 @@ certification track.
> **`NOT ASSESSED — code root unresolved`**, and when it is absent or holds no
> source files, **`NOT ASSESSED — no source files found to scan`**. A bare `0` is
> not a result.
->
-> `/launch-checklist` scans the same way and is most often run beside this one.
-> Keep the two consistent: changing the rule in one and not the other leaves a
-> route to the same misleading `0`.
Scan for outstanding issues:
@@ -159,8 +152,7 @@ Generated: [Date]
Add **device** sections based on the argument. These carry no certification or
storefront-SDK items — those are gated on `platform.cert_tier` in the next
-subsection, and duplicating them here is what let an `itch` project receive
-Steamworks rows.
+subsection, and repeating them here would hand an `itch` project Steamworks rows.
**For `pc`:**
```markdown
@@ -252,11 +244,11 @@ emitting every track; if it cannot be determined, emit
`none`** — `none` is a decision and unset is a missing one.
> **Certification rows belong here, in one `cert_tier`-gated subsection.** Do not
-> spread them back through the PC, Console and Mobile device blocks: those are
-> selected by the command argument and default to `all`, so an `itch` project
-> running `/release-checklist` with no argument would be handed the Steamworks SDK
-> rows *and* the Lotcheck rows — exactly what the `cert_tier` rule at the top of
-> this skill forbids.
+> put them in the PC, Console and Mobile device blocks: those are selected by the
+> command argument and default to `all`, so an `itch` project running
+> `/release-checklist` with no argument would be handed the Steamworks SDK rows
+> *and* the Lotcheck rows, which the `cert_tier` rule at the top of this skill
+> forbids.
>
> **`console` means two different things in this file.** It is a device-block
> argument value *and* a `cert_tier` value, colliding on one word out of four. A
diff --git a/.claude/skills/retrospective/SKILL.md b/.claude/skills/retrospective/SKILL.md
index 213445c1..f1852f7b 100644
--- a/.claude/skills/retrospective/SKILL.md
+++ b/.claude/skills/retrospective/SKILL.md
@@ -3,7 +3,7 @@ name: retrospective
description: "Sprint or milestone retrospective from completed work, velocity, blockers. Actionable insights for the next iteration."
argument-hint: "[sprint-N|milestone-name]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Bash, AskUserQuestion, Bash(bash "*/.claude/skills/retrospective/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, AskUserQuestion, Bash(bash "*/.claude/skills/retrospective/../../hooks/yaml-helper.sh" resolve_config *), Bash(git log *)
model: sonnet
---
diff --git a/.claude/skills/reverse-document/SKILL.md b/.claude/skills/reverse-document/SKILL.md
index c6c358e0..de268c5a 100644
--- a/.claude/skills/reverse-document/SKILL.md
+++ b/.claude/skills/reverse-document/SKILL.md
@@ -54,10 +54,9 @@ lists one, else the project `workflow` value. It sets how much document is
generated — see Phase 5. Semantics of each tier are in
`.claude/docs/workflow-modes.md`.
-> **Resolve the tier — do not assume it.** "Resolve the tier per
-> `workflow-modes.md`" with no bootstrap names a resolution it gives no way to
-> perform: that document defines what each tier *means*, but it cannot say what
-> *this project* is set to. The consequence is large here — at `full` this skill
+> **Resolve the tier — do not assume it.** `workflow-modes.md` defines what each
+> tier *means*, but it cannot say what *this project* is set to; take that from
+> the block above. The consequence is large here — at `full` this skill
> writes an 8-section GDD and at `minimal` a one-page brief, so a wrong tier
> produces the wrong artifact entirely.
@@ -208,8 +207,9 @@ Based on type, use appropriate template:
Dependencies, Acceptance Criteria; + Formulas when the recovered system defines
numeric rules). Skip Player Fantasy and Tuning Knobs.
- **`minimal`** — generate a **game brief** in the one-page format
- (`.claude/docs/templates/game-brief.md`), not a GDD. For the whole game write
- `design/game-brief.md`; for a single reverse-engineered system write
+ (`.claude/docs/templates/game-brief.md`), not a GDD. For the whole game
+ (the path is the code root itself) write `design/game-brief.md`; for a single
+ reverse-engineered system write
`design/[system-name]-brief.md`.
(`architecture` and `concept` outputs are tier-independent.)
@@ -276,11 +276,6 @@ still has it asked ("May I write?" is asked for new files only); if the target
already exists, present the diff and proceed without waiting for an explicit
"yes". **At `autonomous`** — write and log the decision.
-> **Keep this line scoped to its mode.** The skill header defers every file
-> write to `automation-modes.md`, so an unconditional "wait for approval" here
-> collides with it at both `guided` and `autonomous`. Same class as
-> `/map-systems` Step 5b.
-
## Phase 7: Write Document with Metadata
When approved, write the file with special markers:
diff --git a/.claude/skills/review-all-gdds/SKILL.md b/.claude/skills/review-all-gdds/SKILL.md
index 4769a5f6..6e18feab 100644
--- a/.claude/skills/review-all-gdds/SKILL.md
+++ b/.claude/skills/review-all-gdds/SKILL.md
@@ -3,7 +3,7 @@ name: review-all-gdds
description: "Holistic cross-GDD review — contradictions between systems, dominant strategies, economic imbalance, cognitive overload, pillar drift."
argument-hint: "[focus: full | consistency | design-theory | since-last-review]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Bash, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/review-all-gdds/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/review-all-gdds/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/review-scope.sh*)
model: opus
---
diff --git a/.claude/skills/review-all-gdds/references/1-load.md b/.claude/skills/review-all-gdds/references/1-load.md
index 963b6760..c40d24fb 100644
--- a/.claude/skills/review-all-gdds/references/1-load.md
+++ b/.claude/skills/review-all-gdds/references/1-load.md
@@ -81,6 +81,10 @@ Read whole (small, and every part is used):
2. `design/gdd/game-pillars.md` if it exists — design pillars and anti-pillars
3. `design/gdd/systems-index.md` — authoritative system list, layers, dependencies, status
+Read each document by section: find the headings with the Grep tool (pattern `^#`,
+content mode) and Read those ranges with offset and limit. A document read whole
+is read in ranges the same way, since a whole-file Read over 40 KB is refused.
+
Then, for **every in-scope system GDD**, load the sections this review actually
consumes — **not the whole file**:
diff --git a/.claude/skills/review-all-gdds/references/2-consistency.md b/.claude/skills/review-all-gdds/references/2-consistency.md
index 630e1390..a170f61c 100644
--- a/.claude/skills/review-all-gdds/references/2-consistency.md
+++ b/.claude/skills/review-all-gdds/references/2-consistency.md
@@ -56,7 +56,7 @@ Categories to scan:
### 2c: Stale References
**Start from the `## Cross-References` table where a GDD has one.** That table is
-the document's own declaration of what it depends on — `templates/game-design-document.md`
+the document's own declaration of what it depends on — `templates/guidance/game-design-document-guide.md`
tells authors it is machine-checked here, and `/design-system` requires it
whenever Dependencies names another GDD. For each row, confirm the `Target GDD`
exists and the `Specific Element Referenced` is still present in it under that
diff --git a/.claude/skills/review-all-gdds/references/5-report.md b/.claude/skills/review-all-gdds/references/5-report.md
index 83c6a0af..0e0c9c4b 100644
--- a/.claude/skills/review-all-gdds/references/5-report.md
+++ b/.claude/skills/review-all-gdds/references/5-report.md
@@ -15,6 +15,7 @@
Date: [date]
GDDs Reviewed: [N] of [M] present
Not read: [each GDD that could not be read or is present but empty, by file name — or "none"]
+Focus: [full / consistency only — design theory not run / design theory only — consistency not run]
Systems Covered: [list]
---
@@ -96,7 +97,10 @@ thorough while covering a fraction of the surface. Emit it when any of:
is not a cross-review; a clean result there means only that nothing was
compared. This is the single most important trigger in this skill.
- **A whole review phase did not run** — consistency, design theory, economy,
- pillar drift. A parallel phase that returned nothing has to be distinguished
+ pillar drift — when it should have. A pass the focus argument left out is not
+ this trigger: the user asked for it. Give the verdict for the pass that ran,
+ labelled — `PASS (consistency only — design theory not run)` — and fill the
+ `Focus:` line. A parallel phase that returned nothing has to be distinguished
from one that returned no findings; if a spawned agent produced no report, that
phase is NOT ASSESSED, not clean — an agent can return a fluent sentence,
write nothing, and consume a phase.
diff --git a/.claude/skills/review-all-gdds/references/7-handoff.md b/.claude/skills/review-all-gdds/references/7-handoff.md
index faaf6d49..6220d353 100644
--- a/.claude/skills/review-all-gdds/references/7-handoff.md
+++ b/.claude/skills/review-all-gdds/references/7-handoff.md
@@ -11,7 +11,7 @@ Before building options, check project state:
- Are there any Warning-level items that are simple edits (flagged with "30-second edit", "brief addition", or similar)? → offer inline quick-fix option
- Are any GDDs in the "Flagged for Revision" table? → offer /design-review option for each
- Read systems-index.md for the next system with Status: Not Started → offer /design-system option
-- Is the verdict PASS or CONCERNS? → offer /gate-check or /create-architecture
+- Is the verdict PASS or CONCERNS on a review that ran both passes? → offer /gate-check or /create-architecture. A focus run (`consistency` or `design-theory`) checked one pass, so it never offers either
Build the option list dynamically — only include options that apply:
@@ -19,8 +19,8 @@ Build the option list dynamically — only include options that apply:
- `[_] Apply quick fix: [W-XX description] in [gdd-name].md — [effort estimate]` (one option per simple-edit warning; only for Warning-level, not Blocking)
- `[_] Run /design-review [flagged-gdd-path] — address flagged warnings` (one per flagged GDD, if any)
- `[_] Run /design-system [next-system] — next in design order` (always include, name the actual system)
-- `[_] Run /create-architecture — begin architecture (verdict is PASS/CONCERNS)` (include only if the verdict is PASS or CONCERNS — never on FAIL or NOT ASSESSED)
-- `[_] Run /gate-check — validate Systems Design phase gate` (include if verdict is PASS)
+- `[_] Run /create-architecture — begin architecture (verdict is PASS/CONCERNS)` (include only if the verdict is PASS or CONCERNS on a review that ran both passes — never on FAIL, NOT ASSESSED or a focus run)
+- `[_] Run /gate-check — validate Systems Design phase gate` (include if verdict is PASS on a review that ran both passes)
- `[_] Stop here`
Assign letters A, B, C… only to included options. Mark the most pipeline-advancing option as `(recommended)`.
diff --git a/.claude/skills/scope-check/SKILL.md b/.claude/skills/scope-check/SKILL.md
index 8f7b6174..daf45ef2 100644
--- a/.claude/skills/scope-check/SKILL.md
+++ b/.claude/skills/scope-check/SKILL.md
@@ -27,7 +27,9 @@ Locate the baseline scope document for the given argument:
- **Milestone** → read `production/milestones/[name].md`
If the document is not found, report the missing file and stop. Do not proceed without
-a baseline to compare against.
+a baseline to compare against. Read a GDD by section: find the headings you need with
+the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and
+limit.
---
diff --git a/.claude/skills/security-audit/SKILL.md b/.claude/skills/security-audit/SKILL.md
index 2db5ce4a..83ede5eb 100644
--- a/.claude/skills/security-audit/SKILL.md
+++ b/.claude/skills/security-audit/SKILL.md
@@ -3,7 +3,7 @@ name: security-audit
description: "Security audit — save tampering, cheat vectors, network exploits, data exposure, input validation. Before public or multiplayer release."
argument-hint: "[full | network | save | input | quick]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash, Write, Agent, Bash(bash "*/.claude/skills/security-audit/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Agent, Bash(bash "*/.claude/skills/security-audit/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
@@ -144,12 +144,10 @@ platform.online are false`).
### Engine pattern sets — read this before any Category below
-**Every pattern list in Categories 1–3 was written for Godot.** On a Unity or
-Unreal project they match nothing, and this skill already states what a zero-hit
-scan means: it renders the report clean, "the most dangerous possible failure for
-a security audit". That warning was earned along the **version** axis
-(`File.open` vs `FileAccess`) and the identical hole along the **engine** axis
-shipped anyway. Use the table for `engine.name` resolved in Phase 1.
+**Every pattern list in Categories 1–3 is written for Godot.** On a Unity or
+Unreal project they match nothing, and a zero-hit scan renders the report clean,
+"the most dangerous possible failure for a security audit". Use the table for
+`engine.name` resolved in Phase 1.
| Category | Godot | Unity | Unreal |
|---|---|---|---|
diff --git a/.claude/skills/settings/SKILL.md b/.claude/skills/settings/SKILL.md
index 1ab52c0f..215fde1f 100644
--- a/.claude/skills/settings/SKILL.md
+++ b/.claude/skills/settings/SKILL.md
@@ -3,7 +3,7 @@ name: settings
description: "View or change project config — effective merged values, or set locally in project.local.yaml."
argument-hint: "[key | key=value | --local key=value]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
+allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Bash(bash "*/.claude/skills/settings/../../hooks/yaml-helper.sh" resolve_setting *), Bash(bash "*/.claude/skills/settings/../../hooks/yaml-helper.sh" get_yaml_key *), Bash(bash "*/.claude/skills/settings/../../hooks/yaml-helper.sh" validate_yaml_enum *), Bash(bash "*/.claude/skills/settings/../../hooks/yaml-helper.sh" validate_enum_value *), Bash(bash "*/.claude/skills/settings/../../hooks/yaml-helper.sh" is_locally_overridable *), Bash(bash .claude/scripts/config-set.sh *), Bash(grep -B14 '^> ### RESERVED' .claude/docs/effects-map.md), Bash(grep -E '^## ')
model: sonnet
---
@@ -46,19 +46,21 @@ Anything else that doesn't match the four forms above → Phase 6 (usage).
## Phase 1: Load Helper
-All four subcommands need `yaml-helper.sh`. Each Bash call starts a fresh
-shell, so load it **in the same command as every helper call**, from the project
-root, in parentheses so the session's working directory does not change:
+All four subcommands need `yaml-helper.sh`. Run each helper call as its own
+plain command:
```bash
-(cd "${CLAUDE_SKILL_DIR}/../../.." && source .claude/hooks/yaml-helper.sh && <helper call>)
+bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" <helper call>
```
`<helper call>` is the function each phase below names, for example
-`resolve_setting modes.review_mode` or `validate_yaml_enum project.yaml`.
-Running from the root is what makes those `project.yaml` and
+`resolve_setting modes.review_mode` or `validate_yaml_enum project.yaml`. The
+helper moves to the project root itself, so those `project.yaml` and
`project.local.yaml` arguments resolve when the session was started in a
-subfolder.
+subfolder, and it keeps the function's exit status. `is_locally_overridable`
+also prints its `0` or `1`. Run the call exactly as shown: do not `source` the
+file, wrap it in `cd ... &&` or append `; echo $?`. This skill pre-approves the
+plain form only, and a compound command asks the user every time.
If `.claude/hooks/yaml-helper.sh` is missing, this is not a CCGS project.
Report the error and exit.
@@ -193,7 +195,7 @@ Schema validation: ok
Effective config:
framework:
- version: 1.1.3 (project.yaml, locked)
+ version: 1.2.0 (project.yaml, locked)
modes:
review_mode: lean (project.yaml)
@@ -210,7 +212,7 @@ qa:
engine:
name: Godot (project.yaml, locked)
- version: 4.6 (project.yaml, locked)
+ version: 4.7 (project.yaml, locked)
testing:
strict:
@@ -310,6 +312,16 @@ When the effective value is empty (key not set anywhere), print just:
exits without writing. If it returns 0, the value is either valid
or the key has no enum constraint — proceed.
+1b. **Known-key check**: run, from the project root as in Phase 1,
+ `bash .claude/scripts/config-set.sh <key> <value> --dry-run` and read its
+ `known` row. If it says `yes`, proceed. If it says `no`, nothing in CCGS reads
+ that key, so writing it changes nothing; it is most often a typo. Do not
+ write yet: say so, and ask via `AskUserQuestion` with the options
+ `Use <nearest> instead` (only when the row ends `nearest: <key>`),
+ `Write <key> anyway`, `Cancel`. Continue only on an explicit choice; with
+ `Use <nearest> instead`, start this phase again with that key. A skipped or
+ empty answer cancels.
+
2. **Reserved warning**: if `<key>` is in `RESERVED_SET` (Phase 1b), print
BEFORE the approval prompt:
> "Note: `<key>` is RESERVED — no skill or hook reads it, so setting it will
@@ -391,6 +403,10 @@ When the effective value is empty (key not set anywhere), print just:
it returns 1, show the stderr message verbatim and exit without
writing.
+2a. **Known-key check**: as in Phase 4 step 1b, with `--local` before
+ `<key>`: if the `known` row says `no`, ask before writing, offering the `nearest:` key
+ when the row names one.
+
2b. **Reserved warning**: if `<key>` is in `RESERVED_SET` (Phase 1b), print
BEFORE the approval prompt:
> "Note: `<key>` is RESERVED — no skill or hook reads it, so setting it will
diff --git a/.claude/skills/setup-engine/SKILL.md b/.claude/skills/setup-engine/SKILL.md
index 83326c7f..b2db9186 100644
--- a/.claude/skills/setup-engine/SKILL.md
+++ b/.claude/skills/setup-engine/SKILL.md
@@ -3,7 +3,7 @@ name: setup-engine
description: "Configure engine and version. Pins it in CLAUDE.md; WebSearch fills reference docs when the version is beyond LLM training data."
argument-hint: "[engine] | [engine version] | refresh | upgrade [old-version] [new-version] | no args for guided selection"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, WebSearch, WebFetch, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/setup-engine/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, WebSearch, WebFetch, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/setup-engine/../../hooks/yaml-helper.sh" resolve_config *), Bash(godot --version), Bash(godot --headless --path . --import), Bash(command -v godot), Bash(uname -s), Bash(bash .claude/scripts/project-coherence.sh*)
model: sonnet
---
@@ -28,7 +28,7 @@ If the block did not render (shell preprocessing disabled), assume `minimal` (th
Four modes:
-- **Full spec**: `/setup-engine godot 4.6` — engine and version provided
+- **Full spec**: `/setup-engine godot 4.7` — engine and version provided
- **Engine only**: `/setup-engine unity` — engine provided, version will be looked up
- **No args**: `/setup-engine` — fully guided mode (engine recommendation + version)
- **Refresh**: `/setup-engine refresh` — update reference docs (see Section 10)
diff --git a/.claude/skills/setup-engine/references/2-guided-mode.md b/.claude/skills/setup-engine/references/2-guided-mode.md
index e5e0ef9f..573e796a 100644
--- a/.claude/skills/setup-engine/references/2-guided-mode.md
+++ b/.claude/skills/setup-engine/references/2-guided-mode.md
@@ -14,18 +14,21 @@
If no engine is specified, run an interactive engine selection process:
### Check for existing game concept
-Read the design artifact for the resolved tier (see **Tier awareness** above):
+Read the design artifact for the resolved tier (see **Tier awareness** above), by
+section: find the headings you need with the Grep tool (pattern `^#`, content
+mode) and Read those ranges with offset and limit:
- **`standard` / `full`**: read `design/gdd/game-concept.md` if it exists —
- extract genre, scope, platform targets, art style, team size, and any engine
- recommendation from `/brainstorm`.
+ extract genre, scope, platform targets, art style, team size, and the engine
+ preference `/brainstorm` recorded (an engine the user named, or "undecided":
+ `/brainstorm` never recommends one, so the recommendation is made here).
- **`minimal`**: read `design/game-brief.md` if it exists — extract genre,
scope, platform, and art direction from its fields. Its absence is **expected**
at `minimal` (the brief is authored *after* engine setup in the minimal path), so
do not treat a missing brief as a gap — proceed straight to guided selection.
- If no concept **or** brief exists, inform the user:
> "No game concept found. Consider running `/brainstorm` first to discover what
- > you want to build — it will also recommend an engine. Or tell me about your
- > game and I can help you pick."
+ > you want to build — it records your engine preference if you have one. Or
+ > tell me about your game and I can help you pick."
(At `minimal` this is optional, not a prerequisite — you can pick an engine now
and write the brief next.)
diff --git a/.claude/skills/setup-engine/references/4-claude-md-stack.md b/.claude/skills/setup-engine/references/4-claude-md-stack.md
index ae791656..583b826d 100644
--- a/.claude/skills/setup-engine/references/4-claude-md-stack.md
+++ b/.claude/skills/setup-engine/references/4-claude-md-stack.md
@@ -65,9 +65,9 @@ to point at the configured engine:
- Unity → `@docs/engine-reference/unity/VERSION.md`
- Unreal → `@docs/engine-reference/unreal/VERSION.md`
-This is why a fresh Unity or Unreal project no longer loads the Godot reference in
-every session. It is idempotent — re-running `/setup-engine` for a different
+This keeps a Unity or Unreal project from loading the Godot reference in every
+session. It is idempotent — re-running `/setup-engine` for a different
engine rewrites the same line. (The target `docs/engine-reference/<engine>/`
-directory is created in Section 8 below if it does not yet exist.)
+directory is created in Section 7, Populate Engine Reference Docs, if it does not yet exist.)
---
diff --git a/.claude/skills/setup-engine/references/5.5-project-yaml.md b/.claude/skills/setup-engine/references/5.5-project-yaml.md
index 4b152400..c07d1790 100644
--- a/.claude/skills/setup-engine/references/5.5-project-yaml.md
+++ b/.claude/skills/setup-engine/references/5.5-project-yaml.md
@@ -56,9 +56,8 @@ alone.** On Unity and Unreal the table has a single `any` row and the engine nam
| Unity | any | URP | PhysX |
| Unreal | any | Lumen + Nanite (deferred) | Chaos |
-> **Why this table has a shape column and the others do not.** Both Godot
-> defaults were wrong for a 2D browser game, and both were wrong from data this
-> skill had already collected and then discarded.
+> **Why the Godot rows depend on project shape.** Picked from the engine name
+> alone, both Godot defaults are wrong for a 2D browser game.
> - **Jolt is Godot's default *3D* engine.** `docs/engine-reference/godot/modules/physics.md`:
> "Jolt Physics is the DEFAULT 3D engine" and "2D physics UNCHANGED (still
> Godot Physics 2D)". Writing `Jolt` on a 2D project sends the implementer to
@@ -199,8 +198,8 @@ the language:
> an agent following one produces config the other rejects. The row is **left
> unchanged pending sourcing** rather than picked by preference — neither
> `docs/engine-reference/unity/` nor `unreal/` contains a SCREAMING_SNAKE constant
-> to confirm or refute it, and the Unreal run flagged the same row as wrong for
-> Unreal on the same grounds. Resolve by adding a naming section to the engine
+> to confirm or refute it, so the Unreal column's `SCREAMING_SNAKE` is unsourced on
+> the same grounds. Resolve by adding a naming section to the engine
> references, then correct table and prose together. Until then, treat
> `naming.constants` as unverified for Unity and Unreal.
>
@@ -318,10 +317,10 @@ too, so no value holds both quote types. Godot not on PATH, installed under
```yaml
commands:
- build: '"C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe" --headless --export-debug "Windows Desktop"'
- test: '"C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe" --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode'
- run: '"C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe" --path . --windowed --resolution 1280x720'
- smoke: '"C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe" --headless --quit-after 5'
+ build: '"C:/Program Files/Godot/Godot_v4.7.2-stable_win64.exe" --headless --export-debug "Windows Desktop"'
+ test: '"C:/Program Files/Godot/Godot_v4.7.2-stable_win64.exe" --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode'
+ run: '"C:/Program Files/Godot/Godot_v4.7.2-stable_win64.exe" --path . --windowed --resolution 1280x720'
+ smoke: '"C:/Program Files/Godot/Godot_v4.7.2-stable_win64.exe" --headless --quit-after 5'
```
If the probe found no executable and the user does not know where it is, keep
@@ -339,8 +338,8 @@ single-quoted scalar:
```yaml
commands:
- test: '"C:/Program Files/Unity/Hub/Editor/6000.3.23f1/Editor/Unity.exe" -batchmode -runTests -projectPath . -testPlatform EditMode -testResults test-results/editmode.xml'
- smoke: '"C:/Program Files/Unity/Hub/Editor/6000.3.23f1/Editor/Unity.exe" -batchmode -quit -projectPath . -logFile -'
+ test: '"C:/Program Files/Unity/Hub/Editor/6000.3.26f1/Editor/Unity.exe" -batchmode -runTests -projectPath . -testPlatform EditMode -testResults test-results/editmode.xml'
+ smoke: '"C:/Program Files/Unity/Hub/Editor/6000.3.26f1/Editor/Unity.exe" -batchmode -quit -projectPath . -logFile -'
```
> **Also write `engine.path` if the editor is not on `PATH`.** Agents and
@@ -354,7 +353,7 @@ commands:
>
> ```yaml
> engine:
-> path: "C:/Program Files/Epic Games/UE_5.7" # omit if the editor is on PATH
+> path: "C:/Program Files/Epic Games/UE_5.8" # omit if the editor is on PATH
> ```
>
> **This is not cosmetic.** Without it, an agent reports *"no editor on this
@@ -458,7 +457,7 @@ Wait for confirmation, then apply based on the file's current state:
schema_version: 1
framework:
- version: 1.1.3
+ version: 1.2.0
last_upgraded: <today's date>
engine:
diff --git a/.claude/skills/setup-engine/references/7.5-scaffold.md b/.claude/skills/setup-engine/references/7.5-scaffold.md
index 6af1a194..84609b3b 100644
--- a/.claude/skills/setup-engine/references/7.5-scaffold.md
+++ b/.claude/skills/setup-engine/references/7.5-scaffold.md
@@ -7,10 +7,8 @@
**Without this step the framework produces source files no engine can open.**
`/dev-story` writes `.gd`/`.cs`/`.cpp` under the resolved code root, and the `minimal` path
-advertises "four steps to running code" — but nothing anywhere created a project
-for the engine to load. Verified by grep across every skill: no `project.godot`,
-no Unity project, no `.uproject` was ever written. The files were real and
-orphaned.
+advertises "four steps to running code" — but no other skill writes a
+`project.godot`, a Unity project or a `.uproject` for the engine to load.
### Godot — write `project.godot` if one is absent
@@ -50,7 +48,9 @@ an empty project with no main scene opens fine in the editor.
binary was found in Section 3, run its headless import
(`godot --headless --path . --import`) and report the result — read the output
for `ERROR`, because the import exits 0 even when something in the project
-fails to load. If the binary was
+fails to load. On Godot 4.7, this first import of a new project sometimes exits
+139 (a crash on exit) after it has finished; run it once more and report the
+second result. If the binary was
not found, or its version differs from the pinned one, write
**`project.godot NOT VERIFIED — <reason>`**. The `config_version` and feature
strings are stable across Godot 4.x, but "stable in the versions I know" is not
diff --git a/.claude/skills/setup-engine/references/8-verify.md b/.claude/skills/setup-engine/references/8-verify.md
index 8a90c4f3..209365c5 100644
--- a/.claude/skills/setup-engine/references/8-verify.md
+++ b/.claude/skills/setup-engine/references/8-verify.md
@@ -29,15 +29,11 @@ the line here.
## 8.5 Read Back What You Just Wrote
-This section exists because prose did not hold. Section 5.5.1's rendering/physics
-table already carries an emphatic, source-cited warning naming the two mistakes
-most often made here -- and it is still entirely possible to make **both** of
-them anyway, writing `Forward+` and `Jolt` for a 2D browser game. Section 3's
-`Installed at pin time` row is just as easy to drop silently, because a missing
-row leaves no trace.
-
-Neither is fixed by adding more instructions. They are fixed by verifying the
-files after writing them:
+Section 5.5.1's rendering/physics table warns against the two mistakes most
+often made here, and it is still easy to make **both** of them, writing
+`Forward+` and `Jolt` for a 2D browser game. Section 3's `Installed at pin time`
+row is just as easy to drop silently, because a missing row leaves no trace.
+Catch both by verifying the files after writing them:
```bash
bash .claude/scripts/project-coherence.sh
@@ -51,6 +47,11 @@ checks that the files `commands.build` and `commands.test` name exist.
Each one means two files this skill just wrote disagree, or describe something
that is not there.
+One is expected on a new Godot project: `commands.test` names the gdUnit4
+runner under `addons/gdUnit4/`, which `/test-setup` installs later. Report that
+line as expected, name `/test-setup` as the step that clears it, and never edit
+`commands.test` to make it go away. Every other `[DIFFERS]` line is resolved here.
+
**`[NOT CHECKED]` is not a pass.** Each such line names why a comparison could
not be made -- an absent binary, a missing `project.godot`. Say which ones
applied. A comparison that could not run has not established agreement.
diff --git a/.claude/skills/setup-engine/references/godot-language-config.md b/.claude/skills/setup-engine/references/godot-language-config.md
index ea7aa845..504378bc 100644
--- a/.claude/skills/setup-engine/references/godot-language-config.md
+++ b/.claude/skills/setup-engine/references/godot-language-config.md
@@ -58,11 +58,7 @@ and A3.
> **This list and the `naming` enum table in Section 5.5.1 of the skill must
> agree, value for value.** They are written into two different files —
> `technical-preferences.md` from here, `project.yaml` from there — and Section
-> 5.5.3 compares them and **stops the skill** on any mismatch. They disagreed on
-> `scenes` (this list said PascalCase, the enum table said snake_case) for the
-> GDScript column only, which halted `/setup-engine` on the most common Godot
-> configuration there is. Changing a value in one place without the other
-> reintroduces that halt.
+> 5.5.3 compares them and **stops the skill** on any mismatch.
**C#:**
- Classes: PascalCase (`PlayerController`) — must also be `partial`
diff --git a/.claude/skills/skill-improve/SKILL.md b/.claude/skills/skill-improve/SKILL.md
index de3cd8a0..ee145533 100644
--- a/.claude/skills/skill-improve/SKILL.md
+++ b/.claude/skills/skill-improve/SKILL.md
@@ -3,7 +3,7 @@ name: skill-improve
description: "Improve a skill via a test-fix-retest loop — static checks, targeted fixes, keep or revert on score change."
argument-hint: "[skill-name]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Bash, Bash(bash "*/.claude/skills/skill-improve/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/skill-improve/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
@@ -20,6 +20,11 @@ every file write follows `.claude/docs/automation-modes.md`
Runs an improvement loop on a single skill:
test → fix → retest → keep or revert.
+Its score comes from `/skill-test` static and category checks, which read the
+skill rather than run it: a better score means a better-written skill, not proof
+that it behaves better. To check behaviour, run the skill on a real request
+before and after the change.
+
---
## Phase 1: Parse Argument
@@ -34,6 +39,11 @@ Example: /skill-improve tech-debt
Verify `.claude/skills/[name]/SKILL.md` exists. If not, stop with:
"Skill '[name]' not found."
+Glob `CCGS Skill Testing Framework/catalog.yaml`. When it exists, say so first:
+"`CCGS Skill Testing Framework/` was renamed `studio-tests/` in 1.2.0, and this
+skill reads only `studio-tests/`. Move any specs you wrote there; UPGRADING.md
+(v1.1.3 → v1.2.0, `studio-tests/`) says how." Then go on.
+
---
## Phase 2: Baseline Test
@@ -57,7 +67,7 @@ If baseline is 0 FAILs and 0 WARNs, note it and proceed to Phase 2b.
### Phase 2b: Category Baseline
-Look up the skill's `category:` field in `CCGS Skill Testing Framework/catalog.yaml`.
+Look up the skill's `category:` field in `studio-tests/catalog.yaml`.
If no `category:` field is found, display:
"Category: not yet assigned — skipping category checks."
diff --git a/.claude/skills/skill-test/SKILL.md b/.claude/skills/skill-test/SKILL.md
index 6583d98b..5c0be43c 100644
--- a/.claude/skills/skill-test/SKILL.md
+++ b/.claude/skills/skill-test/SKILL.md
@@ -3,7 +3,7 @@ name: skill-test
description: "Validate skill files for structural compliance and behavioral correctness. Four modes: static linter, spec, category rubric, audit."
argument-hint: "static [skill-name | all] | spec [skill-or-agent-name] | category [skill-or-agent-name | all] | audit"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/skill-test/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/skill-test/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/agent-check.sh*), Bash(bash .claude/scripts/compat-inventory.sh*)
model: sonnet
---
@@ -25,28 +25,43 @@ runs entirely within the existing skill/hook/template architecture.
| Mode | Command | Purpose | Token Cost |
|------|---------|---------|------------|
-| `static` | `/skill-test static [name\|all]` | Structural linter — 7 compliance checks per skill (skills only) | Low (~1k/skill) |
+| `static` | `/skill-test static [name\|all]` | Structural linter — 7 compliance checks per skill, plus agent, delegation and compatibility observations | Low (~1k/skill) |
| `spec` | `/skill-test spec [name]` | Behavioral verifier — evaluates assertions in a skill's or agent's test spec | Medium (~5k each) |
| `category` | `/skill-test category [name\|all]` | Category rubric — checks a skill or agent against its category-specific metrics | Low (~2k each) |
| `audit` | `/skill-test audit` | Coverage report — skills, agent specs, last test dates | Low (~3k total) |
+**What a pass proves.** Every mode reads files; none runs the skill. `static`:
+the file has the structure a skill needs, not that it behaves. `spec`: read
+closely, the instructions cover each case, not that Claude follows them when it
+runs. `category`: the skill meets its category's rubric as written. `audit`:
+which skills and agents have specs, and when each was last checked. What a skill
+does shows only when it runs: a real request in a throwaway copy of the project,
+on each model you use, with and without the skill (Anthropic's Agent Skills best
+practices, "Build evaluations first").
+
---
## Phase 1: Parse Arguments
Determine mode from the first argument:
-- `static [name]` → run 7 structural checks on one skill
-- `static all` → run 7 structural checks on all skills (Glob `.claude/skills/*/SKILL.md`)
+- `static [name]` → run 7 structural checks on one skill, or the agent observations on one agent
+- `static all` → run 7 structural checks on all skills (Glob `.claude/skills/*/SKILL.md`), plus the observations for every agent
- `spec [name]` → read the skill or agent + its test spec, evaluate assertions
-- `category [name]` → run category-specific rubric from `CCGS Skill Testing Framework/quality-rubric.md`
+- `category [name]` → run category-specific rubric from `studio-tests/quality-rubric.md`
- `category all` → run category rubric for every skill and every agent that has a `category:` in catalog
- `audit` (or no argument) → read catalog, list all skills and agents, show coverage
If the argument is unrecognized, output usage and stop.
+**The old spec folder.** Glob `CCGS Skill Testing Framework/catalog.yaml`. When
+it exists, say so first: "`CCGS Skill Testing Framework/` was renamed
+`studio-tests/` in 1.2.0, and this skill reads only `studio-tests/`. Move any
+specs you wrote there; UPGRADING.md (v1.1.3 → v1.2.0, `studio-tests/`) says how."
+Then go on with `studio-tests/`.
+
**Resolve the name before `spec` or `category`.** Look it up in
-`CCGS Skill Testing Framework/catalog.yaml`: an entry under `skills:` is a skill
+`studio-tests/catalog.yaml`: an entry under `skills:` is a skill
(`.claude/skills/[name]/SKILL.md`); an entry under `agents:` is an agent
(`.claude/agents/[name].md`). With no catalog entry, use whichever of those two
files exists. Only when neither exists, report "'[name]' is neither a skill in
@@ -54,9 +69,9 @@ files exists. Only when neither exists, report "'[name]' is neither a skill in
also an ordinary word is still a name: `/skill-test spec help` tests the `/help`
skill, never a request for this skill's usage.
-`static` checks SKILL.md structure, so it is skills-only. Given an agent name,
-say so and point to `/skill-test spec [name]` — do not report the agent as
-missing.
+The 7 checks lint SKILL.md structure, so they are skills-only. Given an agent
+name, `static` runs only the observations below: an agent file has no
+phases or verdict keywords to lint. Never report the agent as missing.
---
@@ -143,6 +158,45 @@ hint against the first phase's "Parse Arguments" section.
**WARN** if hint is `""` or if documented modes don't match hint.
+### Agent and Delegation Observations (not scored)
+
+Run `bash .claude/scripts/agent-check.sh --skill [name]` for a skill,
+`bash .claude/scripts/agent-check.sh --agent [name]` for an agent, or
+`bash .claude/scripts/agent-check.sh` once for `static all`. It prints
+observations, never a verdict, and nothing here changes a skill's verdict. Report
+them under `Observations:`, judging each:
+
+- **`DELEGATION:`** a part of the skill that hands work to an agent. Read it and
+ say whether the brief gives an objective, an output format, the tools and
+ sources, and boundaries, and whether it hands the agent a job of only a few
+ tool calls or a re-check of the skill's own work. Its `markers:` are word
+ counts that show where to look, not a grade.
+- **`AGENT:`** the model, effort and turn limit as set, and the tools beside the
+ description: name any tool the job in the description does not need.
+- **`NOTE:`** frontmatter that does not parse; `asks-user` (an agent has no
+ question tool, so its questions belong at the end of its report); a setting
+ that is ignored or does more than it says (`agent-type-list`, `preload-off`,
+ `disallowed-specifier`, `memory-grants`).
+- **`OVERLAP:`** two descriptions that share distinctive words: say whether each
+ still singles out its agent, or which request would reach the wrong one.
+
+If the script cannot run, write `Observations: not run (<reason>)`. Never leave
+the section out: a missing section reads the same as a clean one.
+
+### Compatibility Observations (not scored)
+
+Run `bash .claude/scripts/compat-inventory.sh --skill [name]` for a skill,
+`bash .claude/scripts/compat-inventory.sh --agent [name]` for an agent, or
+`bash .claude/scripts/compat-inventory.sh` once for `static all`. Each `FOUND:`
+line is a place the file depends on something only Claude Code provides, with
+its feature: questions, subagents, skill-loading, shell-lines, arguments,
+frontmatter, instructions, hooks, settings or tools. Claude Code runs all of
+them, so none is a defect and none changes a verdict. Report them under
+`Compatibility:`, one line per feature with its constructs and line numbers;
+for `static all`, give the `COUNT:` totals by feature instead. A `NOT FOUND:`
+line means the name matched no file: say so. If the script cannot run, write
+`Compatibility: not run (<reason>)`.
+
---
### Static Mode Output Format
@@ -159,10 +213,31 @@ Check 5 — Next-Step Handoff: WARN (no follow-up section found)
Check 6 — Fork Context Complexity: PASS (8 phases, context: fork set)
Check 7 — Argument Hint: PASS
+Observations (not scored):
+ Delegation, "Phase 3: Implementation" (line 202): ux-designer, ui-programmer.
+ The brief names the output file and limits but no sources to read.
+
+Compatibility (not scored):
+ questions: AskUserQuestion (lines 13, 88) · shell-lines: shell-line (line 10)
+ frontmatter: allowed-tools, argument-hint, model, user-invocable (lines 4-7)
+
Verdict: WARNINGS (1 warning, 0 failures)
Recommended: Add a "Follow-Up Actions" section at the end of the skill.
```
+For a single agent there is no verdict, only observations:
+```
+=== Agent Static Check: qa-lead ===
+
+Model: inherit · Effort: unset · Turn limit: 20
+Tools: Read, Glob, Grep, Write, Edit, Bash. Fits the job (it writes test plans).
+Observations (not scored):
+ asks-user (lines 31, 52): tells the agent to get approval before writing.
+ overlap with qa-tester (creation, regression, test): each still singled out.
+Compatibility (not scored):
+ frontmatter: tools, tools-string, model, maxTurns (lines 4-6)
+```
+
A WARN or FAIL line names its cause in parentheses, and any verdict other than
COMPLIANT ends with a `Recommended:` line naming the fix.
@@ -184,6 +259,14 @@ story-readiness | WARNINGS | Check 5: no handoff
Summary: 48 COMPLIANT, 3 WARNINGS, 1 NON-COMPLIANT, 1 NOT ASSESSED
Aggregate Verdict: N WARNINGS / N FAILURES / N NOT ASSESSED
+
+Agents (observations, not scored): 49 read
+ asks-user: N agents · agent-type-list: N · preload-off: N · frontmatter: N
+ Overlap pairs: [each pair, with whether both are still singled out]
+ Delegation blocks: N in N skills; [the ones whose brief lacks a part]
+
+Compatibility (not scored): N FOUND lines in N of N files read
+ [feature]: [construct] N files, N hits; ... (one line per feature)
```
**`NOT ASSESSED` is a per-skill result here, not only an aggregate line.** A skill
@@ -209,7 +292,7 @@ No file writes in static mode.
### Step 1 — Locate Files
Use the skill or agent file resolved in Phase 1.
-Look up the spec path from `CCGS Skill Testing Framework/catalog.yaml` — use the
+Look up the spec path from `studio-tests/catalog.yaml` — use the
`spec:` field on the matching `skills:` or `agents:` entry.
If either is missing:
@@ -313,7 +396,7 @@ the floor, added when the list does not already cover them:
```
=== Skill Spec Test: /[name] ===
Date: [date]
-Spec: CCGS Skill Testing Framework/skills/[category]/[name].md
+Spec: studio-tests/skills/[category]/[name].md
Static Assertions:
[PASS] [assertion text]
@@ -347,17 +430,17 @@ FAIL, PARTIAL, NOT ASSESSED, PASS. An assertion nobody could evaluate keeps the
overall result from reading PASS.
For an agent, the header is `=== Agent Spec Test: [name] ===`, `Spec:` is its
-path under `CCGS Skill Testing Framework/agents/`, and a `Static Assertions:`
+path under `studio-tests/agents/`, and a `Static Assertions:`
block comes before Case 1.
### Step 5 — Offer to Write Results
-"May I write these results to `CCGS Skill Testing Framework/results/skill-test-spec-[name]-[date].md`
-and update `CCGS Skill Testing Framework/catalog.yaml`?"
+"May I write these results to `studio-tests/results/skill-test-spec-[name]-[date].md`
+and update `studio-tests/catalog.yaml`?"
If yes:
-- Write results file to `CCGS Skill Testing Framework/results/`
-- Update the skill's or agent's entry in `CCGS Skill Testing Framework/catalog.yaml`:
+- Write results file to `studio-tests/results/`
+- Update the skill's or agent's entry in `studio-tests/catalog.yaml`:
- `last_spec: [date]`
- `last_spec_result: PASS|PARTIAL|FAIL|NOT ASSESSED` — the Overall Verdict
@@ -369,7 +452,7 @@ If yes:
Use the skill or agent file resolved in Phase 1.
Look up the `category:` field on its `skills:` or `agents:` entry in
-`CCGS Skill Testing Framework/catalog.yaml`.
+`studio-tests/catalog.yaml`.
If neither file exists: the Phase 1 message.
If no `category:` field: "No category assigned for '[name]' in catalog.yaml.
@@ -386,7 +469,7 @@ excluded from the run.
### Step 2 — Read Rubric Section
-Read `CCGS Skill Testing Framework/quality-rubric.md`.
+Read `studio-tests/quality-rubric.md`.
Extract the section matching the category (e.g., `### gate`, `### team`; an
agent's category is under `## Agent Categories`, e.g. `### director`).
If the rubric has no section for the category, the result is **NOT ASSESSED**:
@@ -436,7 +519,7 @@ when every metric passes — the same ranking as static and spec mode. It is
### Step 6 — Offer to Update Catalog
-"May I update `CCGS Skill Testing Framework/catalog.yaml` to record this category check
+"May I update `studio-tests/catalog.yaml` to record this category check
(`last_category`, `last_category_result`) for [name]?"
---
@@ -445,7 +528,7 @@ when every metric passes — the same ranking as static and spec mode. It is
### Step 1 — Read Catalog
-Read `CCGS Skill Testing Framework/catalog.yaml`. If missing, note that catalog doesn't exist
+Read `studio-tests/catalog.yaml`. If missing, note that catalog doesn't exist
yet (first-run state).
### Step 2 — Enumerate All Skills and Agents
@@ -462,7 +545,7 @@ missing from the catalog by name, so an uncatalogued one cannot drop out silentl
### Step 3 — Build Skill Coverage Table
For each skill:
-- Check if a spec file exists (use the `spec:` path from catalog, or glob `CCGS Skill Testing Framework/skills/*/[name].md`)
+- Check if a spec file exists (use the `spec:` path from catalog, or glob `studio-tests/skills/*/[name].md`)
- Look up `last_static`, `last_static_result`, `last_spec`, `last_spec_result`,
`last_category`, `last_category_result`, `category` from catalog (or mark as
"never" / "—" if not in catalog)
@@ -471,7 +554,7 @@ For each skill:
### Step 3b — Build Agent Coverage Table
For each agent in catalog's `agents:` section:
-- Check if a spec file exists (use the `spec:` path from catalog, or glob `CCGS Skill Testing Framework/agents/*/[name].md`)
+- Check if a spec file exists (use the `spec:` path from catalog, or glob `studio-tests/agents/*/[name].md`)
- Look up `last_spec`, `last_spec_result`, `last_category`,
`last_category_result`, `category` from catalog
@@ -522,10 +605,10 @@ After any mode completes, offer contextual follow-up:
correctness if a test spec exists."
- After `static all` with failures: "Address NON-COMPLIANT skills first. Run
`/skill-test static [name]` individually for detailed remediation guidance."
-- After `spec [name]` PASS: "Update `CCGS Skill Testing Framework/catalog.yaml` to record this
+- After `spec [name]` PASS: "Update `studio-tests/catalog.yaml` to record this
pass date. Consider running `/skill-test audit` to find the next spec gap."
- After `spec [name]` FAIL: "Review the failing assertions and update the skill
or agent, or the test spec, to resolve the mismatch."
- After `audit`: "Start with the critical-priority gaps. Use the spec template
- at `CCGS Skill Testing Framework/templates/skill-test-spec.md` (agents:
+ at `studio-tests/templates/skill-test-spec.md` (agents:
`agent-test-spec.md`) to create new specs."
diff --git a/.claude/skills/smoke-check/SKILL.md b/.claude/skills/smoke-check/SKILL.md
index 74d515a7..297bb44a 100644
--- a/.claude/skills/smoke-check/SKILL.md
+++ b/.claude/skills/smoke-check/SKILL.md
@@ -3,7 +3,7 @@ name: smoke-check
description: "Critical-path smoke gate before QA hand-off — runs the automated suite. A failed check means the build is not QA-ready."
argument-hint: "[sprint | quick | --platform pc|console|mobile|all]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash, Write, AskUserQuestion, Bash(bash "*/.claude/skills/smoke-check/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, AskUserQuestion, Bash(bash "*/.claude/skills/smoke-check/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/project-coherence.sh*), Bash(command -v *), Bash(uname -s), Bash(godot --headless --path . --import), Bash(timeout 900 godot --headless *), Bash(timeout 1800 godot --headless *), Bash(grep -q 'com.unity.test-framework' Packages/manifest.json), Bash(echo present), Bash(echo ABSENT)
model: sonnet
---
@@ -87,8 +87,7 @@ describe what collaborative mode requires, not universal behavior.
- **Never treat NOT RUN as automatic FAIL** — record it as NOT RUN and let
the developer confirm status manually. Unconfirmed NOT RUN yields **NOT
- ASSESSED**, not FAIL — and not a pass verdict either, which is what it used to
- yield.
+ ASSESSED**, not FAIL — and not a pass verdict either.
- **Never auto-fix failures** — report them and state what must be resolved.
Do not attempt to edit source code or test files.
- **PASS WITH WARNINGS does not block QA hand-off** — it records advisory
diff --git a/.claude/skills/smoke-check/references/1-detect-setup.md b/.claude/skills/smoke-check/references/1-detect-setup.md
index a4c72ea6..f69bd6e5 100644
--- a/.claude/skills/smoke-check/references/1-detect-setup.md
+++ b/.claude/skills/smoke-check/references/1-detect-setup.md
@@ -69,7 +69,9 @@ Before running anything, understand the environment:
onto `PATH` by default on Windows or macOS, so a bare `godot` that does not
resolve says nothing about whether the engine is installed. Take the first
that resolves (the file exists, or `command -v` finds it): the executable
- `commands.test` names (its quoted path or first word), else the editor
+ `commands.test` names (its quoted path or first word; on Godot, only when its
+ file name says godot, since a wrapper such as `bash run-tests.sh` is not the
+ editor), else the editor
`engine.path` records, else the engine's name on `PATH` (`godot`). Use it
wherever Phase 2 writes `godot` or `"<Unity editor>"`, quoting a path with a
space; on Unreal, `<UE root>` is `engine.path`. If none resolves, the test
diff --git a/.claude/skills/smoke-check/references/2-run-tests.md b/.claude/skills/smoke-check/references/2-run-tests.md
index 36948ce4..26b7a0f0 100644
--- a/.claude/skills/smoke-check/references/2-run-tests.md
+++ b/.claude/skills/smoke-check/references/2-run-tests.md
@@ -38,7 +38,7 @@ the executable Phase 1 step 3 resolved):
godot --headless --path . --import
godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode 2>&1
```
-gdUnit4's exit code gives the verdict (6.1.3):
+gdUnit4's exit code gives the verdict (run on 6.1.3 and 6.2.2):
- **0** — every test passed: PASS. **But exit 0 over zero tests is not a pass:**
gdUnit4 aborts and still exits 0, so if the output says `No test cases found`,
the verdict is `NOT ASSESSED — no tests found`.
@@ -60,8 +60,7 @@ debugger and the run hangs at a `debug>` prompt until the timeout.
Unity **can** run tests headlessly via shell. Do not skip to reading artifacts.
First confirm the Unity Test Framework is installed. A project without it does
-not fail cleanly — it **hangs** until something kills it, which is the
-observation the old "Unity cannot test headlessly" advice was generalised from:
+not fail cleanly — it **hangs** until something kills it:
```bash
grep -q 'com.unity.test-framework' Packages/manifest.json && echo present || echo ABSENT
```
diff --git a/.claude/skills/smoke-check/references/4-manual-checks.md b/.claude/skills/smoke-check/references/4-manual-checks.md
index ee5e74e7..41927ea7 100644
--- a/.claude/skills/smoke-check/references/4-manual-checks.md
+++ b/.claude/skills/smoke-check/references/4-manual-checks.md
@@ -22,11 +22,11 @@ Draw the smoke test checklist from, in priority order (and name the one you used
**Name the source you used in the report**, on its own line — *"Checklist source:
`production/qa/smoke-tests.md`"*, or *"Checklist source: standard fallback list —
no QA plan scope, no `production/qa/smoke-tests.md`, no `tests/smoke/`."* The
-fallback is a real fallback, so nothing is silently skipped here; what was
-missing is that a report drawn from the generic list and one drawn from this
-project's own smoke definitions were indistinguishable. `/gate-check` now
-validates a smoke report's claims against the repo, and it cannot weigh them
-without knowing what the checklist was drawn from.
+fallback is a real fallback, so nothing is silently skipped here, but without
+that line a report drawn from the generic list reads the same as one drawn from
+this project's own smoke definitions. `/gate-check` validates a smoke report's
+claims against the repo, and it cannot weigh them without knowing what the
+checklist was drawn from.
Tailor batches 2 and 3 to the actual systems identified from the sprint or QA
plan. Replace bracketed placeholders with real mechanic names from the current
diff --git a/.claude/skills/smoke-check/references/5-report.md b/.claude/skills/smoke-check/references/5-report.md
index d3e4d6e6..60e698f0 100644
--- a/.claude/skills/smoke-check/references/5-report.md
+++ b/.claude/skills/smoke-check/references/5-report.md
@@ -55,6 +55,9 @@ will determine whether the automated test row contributes to a FAIL verdict."
**Summary**: [N] covered, [N] manual, [N] missing, [N] expected.
+[If `quick`:] "Coverage: not checked (quick run) — run `/smoke-check sprint`
+before hand-off." in place of the table and summary.
+
---
### Manual Smoke Checks
@@ -78,6 +81,8 @@ Stories that must have test evidence before they can be marked COMPLETE via
Expected location: `tests/unit/[system]/[story-slug]_test.[ext]`
[If none:] "All Logic and Integration stories have test coverage."
+[If `quick`:] "Not checked (quick run)." — never the line above, which a quick
+run has not shown.
---
@@ -140,6 +145,9 @@ Any platform with one or more FAIL checks contributes to the overall FAIL verdic
launch and critical-path batches below then carry the verdict)
- All smoke checks in all batches PASS or N/A
- No MISSING test evidence entries
+
+[On a `quick` run, any verdict carries the label: `PASS (quick — coverage and
+Batch 3 not checked)`. A quick run can pass; it never reads as a full one.]
````
**`NOT ASSESSED` — the build nobody could check.** Rank: it **outranks PASS and
@@ -147,11 +155,10 @@ PASS WITH WARNINGS** and **ranks below FAIL**. A suite that never ran has not
shown the build is healthy; a suite that ran and failed is the more actionable
finding and must not be demoted behind one that did not run.
-This is a change in where unconfirmed `NOT RUN` lands, and it is deliberate. The
-rule below — **never treat NOT RUN as an automatic FAIL** — is unchanged and
-still correct: NOT ASSESSED is not a FAIL, and it ranks below one. What changes
-is that an unrun suite no longer resolves to a *pass* verdict while waiting for a
-confirmation that may never come. Confirmed NOT RUN (the developer reports the
+The rule below — **never treat NOT RUN as an automatic FAIL** — still holds:
+NOT ASSESSED is not a FAIL, and it ranks below one. But an unrun suite never
+resolves to a *pass* verdict while waiting for a confirmation that may never
+come. Confirmed NOT RUN (the developer reports the
result from their own IDE or CI) still lands at PASS WITH WARNINGS, because
somebody did look.
diff --git a/.claude/skills/smoke-check/references/6-write-gate.md b/.claude/skills/smoke-check/references/6-write-gate.md
index 1fde829d..2b2d32da 100644
--- a/.claude/skills/smoke-check/references/6-write-gate.md
+++ b/.claude/skills/smoke-check/references/6-write-gate.md
@@ -33,8 +33,8 @@ developer's local override is silently ignored):
2. Else read `testing.strict` as a plain boolean (legacy single-value form) — if
its value is `true` or `false`, it applies.
3. Else default to **blocking** — an unset `testing.strict.config` keeps
- smoke-check's FAIL gate blocking (behavior unchanged from before this setting
- existed). Smoke check is a build-health gate, so its unset default is strict
+ smoke-check's FAIL gate blocking. Smoke check is a build-health gate, so its
+ unset default is strict
even though the `config` test type defaults to advisory elsewhere. The
reciprocal carve-out is recorded in `.claude/skills/story-done/SKILL.md` and
`.claude/docs/coding-standards.md`, which own the per-story evidence table.
diff --git a/.claude/skills/soak-test/SKILL.md b/.claude/skills/soak-test/SKILL.md
index 0b443ae2..4de42ab9 100644
--- a/.claude/skills/soak-test/SKILL.md
+++ b/.claude/skills/soak-test/SKILL.md
@@ -68,7 +68,9 @@ Read:
- `design/gdd/game-concept.md` — intended session length (for comparison against
soak duration), core loop description (or `design/game-brief.md`, the one-page
brief that replaces it at `rigor: minimal` — core loop, and session length only
- if its "Who it's for" line states one)
+ if its "Who it's for" line states one). Read it by section: find the headings you
+ need with the Grep tool (pattern `^#`, content mode) and Read those ranges
+ with offset and limit.
- Most recent file in `production/qa/playtests/` — prior playtest findings
(to avoid re-documenting known issues)
- Most recent file in `production/qa/qa-plan-*.md` — current sprint test coverage
@@ -106,14 +108,6 @@ Engine-specific monitoring guidance.
> delta against this session's own T+0 baseline* — which is unit-agnostic and
> stays correct however the editor reports the number. Write the unit down at
> T+0 exactly as displayed and use it consistently for the rest of the run.
->
-> This replaces a note asserting the return units of
-> `Performance.get_monitor` — **NOT SOURCEABLE from `docs/engine-reference/`**,
-> the identifier appears nowhere in it — a claim that sat one line under a row asking
-> the tester to record "Static Memory (**KB**)". A wrong units claim in a leak
-> detector is off by 1024× in the one measurement the protocol exists to take,
-> and it would read as a plausible instruction throughout. Deltas need no such
-> claim, so the safest fix was to stop needing it.
> **NOT SOURCEABLE — the tool, panel and counter names below are not covered by
> `docs/engine-reference/`**: Godot's Debugger → Monitors and its memory
@@ -143,9 +137,9 @@ Engine-specific monitoring guidance.
- Use `stat memory` console command at each checkpoint
- Record: Physical Memory Used, Physical Memory Available (**units as displayed**)
- Alert threshold: Physical Memory Used growth **> 20% over the full soak**,
- measured against this run's T+0. The previous threshold was an absolute
- "> 50MB", which silently assumes both the unit *and* a project scale — 50MB is
- a rounding error for one game and a catastrophe for another
+ measured against this run's T+0. An absolute threshold such as "> 50MB"
+ silently assumes both the unit *and* a project scale — 50MB is a rounding
+ error for one game and a catastrophe for another
### Stability observation items (if focus = stability or all)
diff --git a/.claude/skills/sprint-plan/SKILL.md b/.claude/skills/sprint-plan/SKILL.md
index fe79e48c..25d1b336 100644
--- a/.claude/skills/sprint-plan/SKILL.md
+++ b/.claude/skills/sprint-plan/SKILL.md
@@ -3,7 +3,7 @@ name: sprint-plan
description: "New or updated sprint plan from the current milestone, completed work, and available capacity."
argument-hint: "[new|update|status] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/sprint-plan/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/sprint-plan/../../hooks/yaml-helper.sh" resolve_config *), Bash(ls production/sprints/*)
model: sonnet
---
@@ -92,7 +92,9 @@ smaller than the range is planned whole — never padded with invented stories.
which do not exist cannot be implemented. Verdict: **BLOCKED** — no stories to plan.
4. **Scan design documents** in `design/gdd/` for additional context on the
- features those stories implement. At `workflow: minimal` there are no
+ features those stories implement. Read each by section: find the headings you
+ need with the Grep tool (pattern `^#`, content mode) and Read those ranges
+ with offset and limit. At `workflow: minimal` there are no
per-system GDDs — use `design/game-brief.md` instead, and do not treat the
absent GDDs as missing work. (Note: `/sprint-plan` is **optional** at
`minimal` — the brief's Build order already is the plan.)
@@ -117,6 +119,10 @@ For `new`:
## Sprint Goal
[One sentence describing what this sprint achieves toward the milestone]
+## Goal Prerequisites
+| Needed to show the goal | Status |
+|-------------------------|--------|
+
## Capacity
- Total days: [X]
- Buffer (20%): [Y days reserved for unplanned work]
@@ -159,6 +165,45 @@ For `new`:
- [ ] Code reviewed and merged
```
+### Check the goal's prerequisites
+
+Before you present a `new` plan, check that its goal can be shown working by the
+sprint's end. A goal can need something no story builds: a playtest needs a
+scene to run in. This check reports and never blocks. It adds no question and no
+story of its own.
+
+1. **Settle the goal.** Quote the milestone's goal when there is one; otherwise
+ write one sentence from the stories picked.
+2. **List what showing it needs.** A goal the player can see or play (a playable
+ loop, a feature working end to end, a playtest) needs the scene or level it
+ runs in and the setting that starts it: `run/main_scene` in `project.godot`,
+ the scene list in Unity's `ProjectSettings/EditorBuildSettings.asset`, or
+ `GameDefaultMap` in Unreal's `Config/DefaultEngine.ini`. Add any file, scene
+ or system that a picked story's acceptance criteria, notes or dependencies
+ name and no picked story creates. A goal with nothing to run or show (logic
+ and tests only) needs none.
+3. **Check each one.** It is covered when it exists in the project or a picked
+ story builds it. Find scenes by the engine's scene files (`engine.name` in
+ `project.yaml`): `*.tscn` for Godot, `Assets/**/*.unity` for Unity,
+ `Content/**/*.umap` for Unreal. Find anything else by the path or name the
+ stories use. With no engine set, check by name only and say the scene search
+ did not run.
+4. **Fill in the Goal Prerequisites section**: each need with `exists`,
+ `built by [story ID]` or **missing**, or the single row "None: the goal has
+ nothing to run or show". Copy each missing one into Risks. When you present
+ the plan, name each missing one and the three fixes open to the user: pull in
+ the Ready story that builds it (name it, and say if that takes the sprint past
+ its `story_granularity` range or needs stories it depends on), write a story
+ for it first with `/create-stories`, or reword the goal to promise only what
+ the sprint can show. Give them as part of the plan,
+ not as a question: the write ask stays the only question, and a user who
+ wants a fix says so in reply to it. **Report the gap; do not solve it.** A
+ missing prerequisite stays missing in this plan, however small it looks (a
+ flat test level, an input map): plan no task for it and put none of its work
+ into a picked story, not even as setup. Its work needs a story first, which
+ is `/create-stories`' job. Never add a story the backlog does not
+ hold, and never widen a picked story or edit a story file to cover the gap.
+
For `update`:
**Update an existing sprint plan**:
@@ -166,7 +211,8 @@ For `update`:
1. Read the most recent sprint plan from `production/sprints/`.
2. Present the current story list with their current statuses from `production/sprint-status.yaml`.
3. Ask the user what to change: stories to add, remove, reprioritize, or re-estimate. Use `AskUserQuestion` to gather changes.
-4. Apply the changes and re-present the full revised plan for review.
+4. Apply the changes and re-present the full revised plan for review. If the
+ goal or the Must Have stories changed, check the goal's prerequisites again first.
5. Re-run the producer feasibility gate (Phase 4) on the revised plan.
6. Write the updated markdown plan and yaml together (same approval as `new` mode).
@@ -268,7 +314,7 @@ stories that haven't changed, add new stories, remove dropped ones.
Before finalising the sprint plan, spawn `producer` via `Agent` using gate **PR-SPRINT** (`.claude/docs/director-gates/pr-sprint.md`).
-Pass: proposed story list (titles, estimates, dependencies), total team capacity in hours/days, any carryover from the previous sprint, milestone constraints and deadline.
+Pass: proposed story list (titles, estimates, dependencies), total team capacity in hours/days, any carryover from the previous sprint, milestone constraints and deadline, and any missing goal prerequisite.
Present the producer's assessment.
@@ -313,6 +359,8 @@ Use `AskUserQuestion`:
- `[B] Skip for now — I understand QA sign-off will be blocked at the Production → Polish gate`
Wait for this answer before the write ask below — the two are separate questions.
+An answer here is never approval to write, even "yes, go ahead" or "once the plan is written":
+ask the write question next and write only after a yes to it.
If [A]: note in the plan "QA plan: run `/qa-plan sprint` before implementation begins."
If [B]: add a warning block to the sprint plan document:
@@ -326,7 +374,7 @@ If [B]: add a warning block to the sprint plan document:
### Write the plan
Ask: "May I write the sprint plan to `production/sprints/sprint-NNN.md` (`[N]` zero-padded to three digits) and
-`production/sprint-status.yaml`?" If yes, write both files (creating directories as
+`production/sprint-status.yaml`?" Ask it even when an earlier answer sounded like a yes. If yes, write both files (creating directories as
needed). Verdict: **COMPLETE** — sprint plan and status file created. If no:
Verdict: **BLOCKED** — user declined write.
diff --git a/.claude/skills/sprint-status/SKILL.md b/.claude/skills/sprint-status/SKILL.md
index c4c4d7a1..4ac8ff6e 100644
--- a/.claude/skills/sprint-status/SKILL.md
+++ b/.claude/skills/sprint-status/SKILL.md
@@ -138,10 +138,10 @@ After collecting status for all stories, check each IN PROGRESS story for stalen
> **The `\*{0,2}` wrappers are why this works at all.** `/create-stories` emits
> `> **Last Updated**: …`, so a pattern requiring `:` immediately after the word
-> matched no story ever written. Combined with the "no match = never stamped"
-> rule directly above — which is correct in itself — the failure was completely
-> silent: every in-progress story reported as never stamped, and stale-story
-> detection never once fired. A bare `Updated:` anchor will regress it.
+> matches no story. Combined with the "no match = never stamped" rule directly
+> above, that failure is silent: every in-progress story reports as never
+> stamped and stale-story detection never fires. Do not use a bare `Updated:`
+> anchor.
- Calculate days since that date using today's date.
- If the date is more than 4 days ago, flag the story as **STALE**. (4-day threshold accounts for weekends — a story last touched on Friday won't appear stale until Wednesday.)
- If no date field is found in the story file, note "no timestamp — cannot check staleness."
diff --git a/.claude/skills/start/SKILL.md b/.claude/skills/start/SKILL.md
index d1d76638..eee07d46 100644
--- a/.claude/skills/start/SKILL.md
+++ b/.claude/skills/start/SKILL.md
@@ -1,417 +1,219 @@
---
name: start
-description: "First-time onboarding — asks where you are, then guides you to the right workflow."
+description: "Guides a first-time user through onboarding and picks the right workflow. Use when the user is new, just cloned or installed the studio, has no idea or engine yet, asks where to begin, or wants to bring in an existing game."
argument-hint: "[no arguments]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion
+allowed-tools: Read, Glob, Grep, AskUserQuestion, Bash(bash .claude/scripts/project-state.sh*), Bash(bash .claude/scripts/set-stage.sh *), Bash(bash .claude/scripts/config-set.sh *)
model: sonnet
---
# Guided Onboarding
-This skill writes `project.yaml` — the `project.stage`, `modes.rigor` and
-`modes.automation` settings — plus one legacy mirror, `production/stage.txt`,
-for backward compatibility with hooks that have not migrated. `modes.rigor` and
-`modes.automation` have no legacy mirror; they are written to `project.yaml`
-only.
-
-> **`/start` never writes `modes.review_mode`, in either location.** It is a
-> rigor-fronted knob: writing it explicitly pins it and shadows the `modes.rigor`
-> expansion, so the Phase 3d question would stop changing director-review depth
-> (see Phase 3d, and the same rule in `project.yaml`'s header comment). It must
-> **not** write `production/review-mode.txt` either — the legacy step sits
-> **above** the rigor expansion in the resolution chain, deliberately, so a genuine
-> v1.0 project's explicit choice survives migration. On a new project that
-> ordering works against you: a mirror file written here would outrank the
-> expansion permanently. Verified: `rigor: minimal` plus a `review-mode.txt`
-> containing `lean` resolves to `lean`, not the expected `solo`.
-
-This skill is the entry point for new users. It does NOT assume you have a game idea, an engine preference, or any prior experience. It asks first, then routes you to the right workflow.
-
----
-
-**Automation mode**: Resolve `modes.automation` (`project.local.yaml` →
-`project.yaml` → default `collaborative`). **Note**: on a fresh project no
-`modes.automation` is set yet, so `/start` runs collaboratively — it is
-creating the config. Its core onboarding questions (starting point, rigor,
-automation) are project-shaping and always prompt regardless
-of mode. Engine choice is **not** among them — it is deferred to
-`/setup-engine`, which Phase 4 hands off to.
-If `/start` is re-run on an already-configured project, the resolved mode
-applies per `.claude/docs/automation-modes.md`.
-
-## Phase 1: Detect Project State
-
-Before asking anything, silently gather context so you can tailor your guidance. Do NOT show these results unprompted — they inform your recommendations, not the conversation opener.
-
-Check:
-- **Engine configured?** Read `engine.name` from `project.yaml`; if that key is absent or empty (including when `project.yaml` has no `engine:` block), fall back to `.claude/docs/technical-preferences.md` (an Engine field of `[TO BE CONFIGURED]`, or no file, means not set). The engine is configured if either source yields a real engine name.
-- **Game concept exists?** Check for `design/gdd/game-concept.md` (or `design/game-brief.md` at the `minimal` tier).
-- **Source code exists?** Resolve the code root from the `engine.name` read above (`src/` Godot, `Assets/` Unity, `Source/` Unreal; full order in `.claude/docs/code-root-resolution.md`), then Glob it for source files (`*.gd`, `*.cs`, `*.cpp`, `*.h`, `*.rs`, `*.py`, `*.js`, `*.ts`). **If the code root is unresolved, say so rather than concluding there is no code** — a Unity or Unreal project scanned as `src/` returns zero files and reads as greenfield.
-- **Prototypes exist?** Check for subdirectories in `prototypes/`.
-- **Design docs exist?** Count markdown files in `design/gdd/`.
-- **Production artifacts?** Check for files in `production/sprints/` or `production/milestones/`.
-- **Still wired to the template repo?** Read `.git/config` if it is a file. If its
- `[remote "origin"]` url contains `donchitos/claude-code-game-studios`, compared
- case-insensitively, the user cloned the template and `origin` still points at
- it — so `git push` and `gh pr create` target the CCGS repo, not their game. A
- fork (the same repo name under another owner) is the user's own and does not
- count. Note it: it is reported on every path, the returning user's included.
- Read only; never run git.
-
-Store these findings internally to validate the user's self-assessment and tailor recommendations.
-
----
-
-## Phase 2: Ask Where the User Is
-
-This is the first thing the user sees — unless Phase 1 found a returning user (engine configured, and a concept or brief present): then ask nothing here and answer as the **User is returning** edge case below. Otherwise, use `AskUserQuestion` with these exact options so the user can click rather than type:
-
-- **Prompt**: "Welcome to Claude Code Game Studios! Before I suggest anything, I'd like to understand where you're starting from. Where are you at with your game idea right now?"
-- **Options**:
- - `A) No idea yet` — I don't have a game concept at all. I want to explore and figure out what to make.
- - `B) Vague idea` — I have a rough theme, feeling, or genre in mind (e.g., "something with space" or "a cozy farming game") but nothing concrete.
- - `C) Clear concept` — I know the core idea — genre, basic mechanics, maybe a pitch sentence — but haven't formalized it into documents yet.
- - `D) Existing work` — I already have design docs, prototypes, code, or significant planning done. I want to organize or continue the work.
-
-Wait for the user's selection. Do not proceed until they respond.
-
----
-
-## Phase 3: Route Based on Answer
-
-#### If A: No idea yet
-
-The user needs creative exploration before anything else.
-
-1. Acknowledge that starting from zero is completely fine
-2. Briefly explain what `/brainstorm` does: it turns "no idea" into a written design your next step can build from. Mention that it has two modes: `/brainstorm open` for fully open exploration, or `/brainstorm [hint]` if they have even a vague theme (e.g., "space", "cozy", "horror").
-
- > **Describe it tier-neutrally here.** Phase 3d has not run, so you do not yet
- > know how much process this project wants — and `/brainstorm` changes shape
- > completely on that answer. At `minimal` it runs a short Lean Brief flow and
- > stops, producing a one-page `design/game-brief.md`; at `standard`/`full` it
- > runs the full ideation walk (MDA, player psychology, verb-first design) and
- > produces the concept document. Naming the full walk here, then having Phase 4
- > describe the same skill as "produce the one-page brief", gives the user two
- > contradicting accounts of one skill inside a single `/start` run. Phase 4 is
- > where the tier-specific description belongs.
-3. Recommend running `/brainstorm open` as the next step, but invite them to use a hint if something comes to mind
-4. Name the **immediate next step only** — `/brainstorm open`. Do not list the
- full pipeline here. Phase 3d has not yet asked how much process the user
- wants, and that answer changes the path substantially. Say: "I'll lay out the
- full path once I know how much process you want — two quick questions away."
-
-#### If B: Vague idea
-
-1. Ask them to share their vague idea — even a few words is enough
-2. Validate the idea as a starting point (don't judge or redirect)
-3. Recommend running `/brainstorm [their hint]` to develop it
-4. Name the **immediate next step only** — `/brainstorm [their hint]`. Do not
- list the full pipeline here; Phase 3d has not yet asked how much process the
- user wants, and that answer changes the path. Say: "I'll lay out the full
- path once I know how much process you want — two quick questions away."
-
-#### If C: Clear concept
-
-1. Ask them to describe their concept in one sentence — genre and core mechanic. Use plain text, not AskUserQuestion (it's an open response).
-2. Acknowledge the concept, then use `AskUserQuestion` to offer two paths:
- - **Prompt**: "How would you like to proceed?"
- - **Options**:
- - `Formalize it first` — Run `/brainstorm [concept]` to write it down: a one-page brief at `rigor: minimal` (the default), a full concept document above it
- - `Jump straight in` — Go to `/setup-engine` now and write the design down afterward
-3. Name the **immediate next step only** — their pick from step 2. Do not list
- the full pipeline here; Phase 3d has not yet asked how much process the user
- wants, and that answer changes the path. Say: "I'll lay out the full path
- once I know how much process you want — two quick questions away."
-
-#### If D: Existing work
-
-1. Share what you found in Phase 1:
- - "I can see you have [X source files / Y design docs / Z prototypes]..."
- - "Your engine is [configured as X / not yet configured]..."
-
-2. **Sub-case D1 — Early stage** (engine not configured or only a game concept exists):
- - Recommend `/setup-engine` first if engine not configured
- - Then `/project-stage-detect` for a gap inventory
-
- **Sub-case D2 — GDDs, ADRs, or stories already exist:**
- - Explain: "Having files isn't the same as the template's skills being able to use them. GDDs might be missing required sections. `/adopt` checks this specifically."
- - Recommend:
- 1. `/project-stage-detect` — understand what phase and what's missing entirely
- 2. `/adopt` — audit whether existing artifacts are in the right internal format
-
-3. For D2, name the **immediate next step only** — `/project-stage-detect`.
- The rest of the D2 path depends on rigor, which Phase 3d has not asked yet,
- so Phase 4 prints it. Say: "I'll lay out the full path once I know how much
- process you want — two quick questions away."
-
----
-
-## Phase 3c: Write Initial Stage
-
-**Ask before the `project.yaml` write:** "May I write `project.stage: [stage]`
-to `project.yaml` (and the legacy mirror `production/stage.txt`)?" Take `[stage]` from the Stage mapping below; say the file
-will be created when there is none, and that the Phase 3d and 3e answers will go
-there too when those questions are still to be asked. That one approval covers
-this write and the Phase 3d and 3e writes. If the user declines, write neither
-file, keep the stage and those answers for this run only, and say they were not
-saved.
-
-After confirming the starting path, write the initial stage to BOTH `project.yaml` (primary) AND `production/stage.txt` (legacy fallback for hooks that haven't migrated yet). Create the `production/` directory if it does not exist.
-
-In `project.yaml`, ensure a `project:` block exists with `stage: [value]`.
-- **If `project.yaml` already exists**: Read it first (the Edit tool requires the
- file to have been read in this session), then use the Edit tool to add/update
- the `project:` block, placing it immediately after the `framework:` block.
-- **If `project.yaml` does not exist** at the repo root: create it with the Write
- tool using this v1.1 minimal template (replace `[value]` and the date):
- ```yaml
- # CCGS project configuration — single source of truth for project settings.
- # Schema: grep the `## <key>` section of .claude/docs/effects-map.md —
- # it is ~31k tokens whole, ~900 per section. Do not open it entire.
-
- schema_version: 1
-
- framework:
- version: 1.1.3
- last_upgraded: <YYYY-MM-DD>
-
- project:
- stage: [value]
- ```
- **Do not seed `modes.review_mode` here.** It is a rigor-fronted knob —
- `modes.rigor` supplies its value, so an explicit value here would shadow the
- rigor expansion and pin the review mode regardless of the rigor the user picks
- in Phase 3d. `modes.rigor` itself is omitted for a related reason: Phase 3d skips
- its question when the key is already set, so seeding it would suppress that
- question. The other knobs `modes.rigor`
- fronts — `modes.workflow`, `docs.density`, `qa.level`,
- `modes.story_granularity`, `team.size` — are never written by `/start`
- either, here or in Phase 3d: each would pin its value over the rigor expansion.
-
-Then also write the same single-line stage name to `production/stage.txt` (no trailing newline) so legacy tooling still works.
-
-Stage mapping:
-- **Path A, B, or C (starting from scratch)**: write `Concept`
-- **Path D, existing project, engine not configured or only a game concept exists**: write `Concept`
-- **Path D, existing project with GDDs but no architecture documents**: write `Systems Design`
-- **Path D, existing project with full architecture (ADRs, architecture doc)**: write `Technical Setup`
-
-`production/stage.txt` is covered by the same ask: it is a one-line legacy mirror
-of the stage approved for `project.yaml`, kept for hooks that have not migrated.
-
-Say: "I've set `project.stage` to `[stage]` (and updated `production/stage.txt`) — this anchors your status line and stage detection."
-
----
-
-## Phase 3d: Set Rigor
-
-Check whether `modes.rigor` is already set in `project.yaml`. **If it is**, show
-it — "Rigor is set to `[current]`." — and proceed to **Phase 3e**. Do not ask
-again. Either way, **carry the resolved value forward** — Phase 4 branches its
-recommended path on it.
-
-**If it is not set**: first pick a recommendation, then ask.
-
-**Seed the recommendation** from what the user described in Phase 2, using the
-archetype presets in `.claude/docs/settings-guidance.md § 2–3`:
-- Map their concept to an archetype (e.g. "open-world RPG with crafting and
- factions" → systems-heavy → `full`; "a small weekend puzzler" → `minimal`).
-- If the user has **no concept at all** (Path A, or a Path B hint with nothing in
- §3's signal table), recommend the jam/prototype option (`minimal`) and add:
- "You can raise this after `/brainstorm` once the concept is clearer —
- `/settings` changes it anytime."
-- **A Path B hint still counts as a description.** "Still exploring" is about
- having no signal, not about which path the user picked. If the vague idea trips
- §3's signals — "some kind of open-world survival sim" hits open-world, sim and
- survival — seed from the signal, not from the path, and say why in the user's
- own terms. Recommending `minimal` for a described systems-heavy game is the
- mismatch Phase 4 would then have to flag, caused here.
-- If nothing in the description points either way, recommend `minimal`, the
- documented default, and add: "`/settings` raises it once the game shows it
- needs more."
-
-Then use `AskUserQuestion`. Order the options so the **recommended** archetype is
-first and append ` (Recommended)` to its label (per the AskUserQuestion
-convention); the other two follow in any order.
-
-- **Prompt**: "What best describes what you're building? This sets how much process
- the project carries — you can change it anytime with `/settings`."
-- **Options** (base labels — the recommended one also gets ` (Recommended)`):
- - `Jam / prototype / first game` — Short docs, coarse stories, tests optional — the screenshot of what you built is not. **~4 steps to your first line of code instead of ~18.** Shipping beats recording; design lives in your head. The trade: no GDDs, so design problems surface in code rather than before it.
- - `Several systems that affect each other` — Balanced docs, normal story size, standard QA evidence. **Expect ~8 design documents and roughly an hour of design work before your first line of code.** Worth paying when systems interact and a design mistake is expensive to unpick once it is in code. **Intending to finish is not the test** — most small games ship faster on the jam path and can move up later with `/settings`.
- - `Big systems-heavy or team project` — Thorough docs, fine-grained stories, evidence required everywhere. Many interacting systems (open-world, sim, RPG), a firm release date, or shared ownership.
-
-Value mapping (ignore any ` (Recommended)` suffix on the first option):
-`Jam / prototype / first game` → `minimal`, `Several systems that affect each other` → `standard`,
-`Big systems-heavy or team project` → `full`.
-
-Write `modes.rigor` to `project.yaml` immediately after the user selects — no
-separate "May I write?" needed, as the write is a direct consequence of the
-selection. Use the Edit tool. The Phase 3c template has no `modes:` block: if
-`project.yaml` has none, add one with `rigor:` under it; if it has one, add
-`rigor:` under it. Never add a second `modes:` line — YAML allows one block per
-key. There is **no legacy mirror file** for this setting, so this is a single
-write, not a dual-write.
-If the Phase 3c `project.yaml` write was declined, do not write this one either —
-carry the answer forward and say it was not saved.
-
-Then say: "Set `modes.rigor` to `[choice]`. That drives six settings —
-`modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`,
-`modes.review_mode` (director-review depth), and `team.size` (how many agents are
-active on team tasks) — a lighter rigor means fewer reviews, a smaller active
-team, and fewer tokens. Run `/settings` to see the exact value each one takes, or
-set any of them explicitly to override just that one."
-
-**Why this is asked here.** These six knobs each change what skills produce, and
-before `rigor` existed `/start` never asked about any of them — so every project
-silently ran at defaults the user had never seen. Asking once, at onboarding, is
-the only point where the answer is cheap; skipping this question puts the project
-back where it was.
-
----
-
-## Phase 3e: Set Automation Mode
-
-Check whether `modes.automation` is already set in `project.yaml`. **If it is**,
-show it — "Automation is set to `[current]`." — and proceed to Phase 4. Do not
-ask again.
-
-**If it is not set**: Use `AskUserQuestion`:
-
-- **Prompt**: "Last one: how much should I confirm with you as we work?"
-- **Options**:
- - `Collaborative` — I ask before each significant step and show drafts before writing. Most control; best while you are learning the workflow and want to see everything.
- - `Guided (recommended)` — I decide the small stuff and proceed, but still stop for the big calls (scope changes, file deletions, schema changes). Far fewer interruptions than collaborative, without giving up control of the decisions that matter.
- - `Autonomous` — I proceed and log decisions rather than asking, except for the always-ask categories. Fastest to run, but it makes every call itself and costs more tokens; best for trusted, well-scoped runs.
-
-Value mapping: `Collaborative` → `collaborative`, `Guided (recommended)` →
-`guided`, `Autonomous` → `autonomous`.
-
-Write `modes.automation` to `project.yaml` immediately after the user selects —
-no separate "May I write?" needed, as the write is a direct consequence of the
-selection. Use the Edit tool to add `automation:` under the `modes:` block
-(Phase 3d creates it); if `project.yaml` has none, add one.
-Never add a second `modes:` line — YAML allows one block per key. There is **no
-legacy mirror file** for this setting. If the Phase 3c `project.yaml` write was
-declined, do not write this one either — say it was not saved.
-
-Then say: "Set `modes.automation` to `[choice]`. See
-`.claude/docs/automation-modes.md` for exactly what each mode asks vs. proceeds
-on. `guided` and `autonomous` still always stop for the `automation_always_ask`
-categories (scope changes, file deletions, schema changes)."
-
-**Why this is asked here.** `modes.automation` controls how often every skill
-stops to confirm. A project that wants to move fast should not have to discover
-the knob after fifty approval prompts — that is the frustration this setting
-answers. Asked once, at onboarding, like the others. Do **not** seed
-`modes.automation` into the Phase 3c template: Phase 3e skips when the key is
-already set, so seeding it would suppress its own question (the same collision
-Phase 3c's rigor note describes for the other knobs).
-
----
-
-## Phase 4: Show the Path, Then Confirm
-
-**Now** present the recommended path — after Phase 3d, so it can match the rigor
-the user actually chose. Print **one** of the three below, using the `modes.rigor`
-value resolved or written in Phase 3d; if it is somehow still unset, use
-`minimal` (its documented default) rather than skipping the path. (Paths A/B/C;
-a D2 user gets the retrofit path below instead, and a D1 user was given their
-steps in Phase 3.)
-
-Say first: "Here's your path at `rigor: [chosen]`. Every skill still runs at any
-level — rigor changes what's *required*, not what's allowed. So at `minimal` you can
-still call `/art-bible`, `/ux-design`, `/qa-plan` or anything else the moment you want
-it — nothing is locked, it simply is not demanded up front. And if one system alone
-deserves more care, raise just that one with
-`workflow_overrides.system_overrides.<system>` rather than the whole project."
-
-**If `minimal` (default) — 4 steps to running code:**
-- `/setup-engine` — configure the engine
-- `/brainstorm` — produce the one-page `design/game-brief.md` (the lean-tier design artifact; it replaces the full concept doc, systems decomposition, and per-system GDDs)
-- `/create-stories` — turn the brief's MVP list into implementable stories (the epic is implicit — no separate `/create-epics` or `/sprint-plan`; the brief's build order is the plan)
-- `/dev-story` — **first line of game code**
-
-**If `standard` — the full pipeline:**
-- **Concept:** `/setup-engine` → `/brainstorm` → `/prototype` → `/art-bible` → `/map-systems` → `/design-system` (×N systems) → `/review-all-gdds` → `/gate-check`
-- **Architecture:** `/create-architecture` → `/architecture-decision` (×N) → `/create-control-manifest` → `/architecture-review`
-- **Pre-Production:** `/ux-design` → `/create-epics` → `/create-stories` → `/sprint-plan`
-- **Production:** `/dev-story`
-
-**If `full` — the full pipeline plus validation builds:**
-- Everything in `standard`, plus `/vertical-slice` and `/playtest-report` (×1+)
- in Pre-Production, and `/design-review` after each GDD.
-
-**For a Path D2 user, print this retrofit path in place of the three above.**
-At `minimal` it stops after `/adopt` and `/setup-engine`: the minimal path needs
-only `design/game-brief.md` (`/brainstorm`) and stories (`/create-stories`), so
-do not send the user through the GDD, ADR and registry retrofit below. At
-`standard` and `full`:
-- `/project-stage-detect` — phase detection + existence gaps
-- `/adopt` — format compliance audit + migration plan
-- `/setup-engine` — if engine not configured
-- `/design-system retrofit [path]` — fill missing GDD sections
-- `/architecture-decision retrofit [path]` — add missing ADR sections
-- `/architecture-review` — bootstrap the TR requirement registry
-- `/gate-check` — validate readiness for next phase
-
-> **Do not present the minimal path as lesser.** It is the tier's documented
-> floor (`.claude/docs/workflow-modes.md` — "engine choice and a filled
-> `design/game-brief.md` are required before code starts … everything else can
-> be skipped"), not a degraded mode. Equally, do not oversell it: at `minimal`
-> there are no GDDs to catch design problems before they reach code, which is
-> the trade being made.
-
-If the user picked a rigor that contradicts what they described in Phase 2 —
-overriding the seeded recommendation, e.g. choosing `minimal` after describing a
-multi-year commercial project, or `full` for a weekend jam — apply the "mismatch"
-trigger in `.claude/docs/settings-guidance.md § 4`: say so once, in one sentence,
-and offer `/settings` to change it. Do not re-ask.
-
-If Phase 1 found `origin` pointing at the template repo, add once, after the path:
-"Your clone's `origin` still points at the Claude Code Game Studios repo, so a push
-or pull request would go there, not to your game. When you're ready:
-`git remote rename origin template` (the name `UPGRADING.md` uses to pull updates),
-then `git remote add origin <your repo URL>`. After the rename, `template` already
-exists, so skip `UPGRADING.md`'s own one-time `git remote add template` step —
-it would fail with `remote template already exists`." Suggest it; do not run it.
-
-Then use `AskUserQuestion` to ask which step they'd like to take first. Never auto-run the next skill.
-
-- **Prompt**: "Would you like to start with [recommended first step]?"
-- **Options**:
- - `Yes, let's start with [recommended first step]`
- - `I'd like to do something else first`
-
----
-
-## Phase 5: Hand Off
-
-When the user confirms their next step, respond with a single short line: "Type `[skill command]` to begin." Nothing else. Do not re-explain the skill or add encouragement. The `/start` skill's job is done.
-
-Verdict: **COMPLETE** — user oriented and handed off to next step.
-
----
-
-## Edge Cases
-
-- **User picks D but project is empty**: Gently redirect — "It looks like the project is a fresh template with no artifacts yet. Would Path A or B be a better fit?"
-- **User picks A but project has code**: Mention what you found — "I noticed there's already code in `[code root]`. Did you mean to pick D (existing work)?"
-- **User is returning (engine configured, concept exists)**: Skip onboarding entirely — "It looks like you're already set up! Your engine is [X] and you have a game concept at `design/gdd/game-concept.md` (or a game brief at `design/game-brief.md`). Review mode: `[resolve modes.review_mode — an explicit value if set, otherwise it follows modes.rigor: minimal→solo, standard→lean, full→full]`. Want to pick up where you left off? Try `/help` — it reads your tier and progress and names the next step — or just tell me what you'd like to work on." If Phase 1 found `origin` pointing at the template repo, add the Phase 4 note about renaming `origin` here too.
-- **User doesn't fit any option**: Let them describe their situation in their own words and adapt.
-
----
-
-## Collaborative Protocol
-
-**Applies in `collaborative` mode (the default).** For `guided` and
-`autonomous` modes, see `.claude/docs/automation-modes.md` — the rules below
-describe what collaborative mode requires, not universal behavior.
-
-1. **Ask first** — never assume the user's state or intent
-2. **Present options** — give clear paths, not mandates
-3. **User decides** — they pick the direction
-4. **No auto-execution** — recommend the next skill, don't run it without asking
-5. **Adapt** — if the user's situation doesn't fit a template, listen and adjust
+The entry point for a new user. It assumes no game idea, no engine and no experience: it reads
+the project, asks where the user is starting from, shows what it assumes about the project, and
+names the one next step. It never runs that step itself.
+
+It writes these settings to `project.yaml`, all through helpers, and only after an explicit yes:
+`project.stage` (with its legacy mirror `production/stage.txt`), `modes.rigor` and
+`modes.automation`. It never writes `modes.review_mode` or `production/review-mode.txt`, and none
+of the other knobs rigor fronts (`modes.workflow`, `docs.density`, `qa.level`,
+`modes.story_granularity`, `team.size`): a written value pins that knob over the rigor expansion,
+and a mirror file outranks it.
+
+Ask with the question tool. Without one, list the options numbered and end your turn to wait. The
+question is the last thing in the reply: no path, note or advice after it. A skipped or dismissed
+question is not an answer: ask again in plain text.
+
+The questions in Phases 2, 4 and 5 shape the project, so they are asked in every automation mode.
+The engine is not one of them: `/setup-engine` chooses it. Phase 6's last question follows a
+`modes.automation` already in `project.yaml`, per `.claude/docs/automation-modes.md`; with none
+set, ask it.
+
+## Phase 1: Read the project
+
+Run `bash .claude/scripts/project-state.sh` and keep its rows. Do not show them yet; they check
+the user's answer in Phase 2.
+
+| Row | Use |
+|---|---|
+| `engine`, `code_root`, `source_files` | Is an engine set, and how much code is there. `source_files` of `unknown` means the code root could not be found: say that, never "no code" |
+| `concept` | `design/gdd/game-concept.md` or `design/game-brief.md` exists |
+| `gdd_files`, `adr` | Design documents and architecture decisions on disk (they set the stage in Phase 4) |
+| `prototype`, `sprint`, `milestone`, `story` | Other existing work |
+| `origin_url` | Contains `donchitos/claude-code-game-studios`, matched case-insensitively: the clone still points at the template repo, so a push or pull request would go there. A fork under another owner is the user's own |
+| `stage` | The stage already recorded, if any |
+
+Ignore `phase_inferred`: it guesses from file counts, and a project with code but no design
+documents is not in Production. If the helper fails, say so and read the same facts by hand
+(engine in `project.yaml`, the two concept files, the code root's files, `design/gdd/`).
+
+The helper does not report rigor or automation. Read `project.yaml`, if it exists, and note
+whether `modes.rigor` and `modes.automation` are set: a set value is kept, and its question is
+not asked (Phases 4 and 5).
+
+**Returning user** (an engine is set and `concept` is present): ask nothing. Say the engine, the
+concept or brief found, and the review mode: `modes.review_mode` if set, otherwise the one
+`modes.rigor` implies (`minimal` → `solo`, `standard` → `lean`, `full` → `full`). Suggest `/help` for the next step, add the
+template-remote note if it applies, and stop.
+
+## Phase 2: Ask where the user is
+
+Ask with the question tool: "Welcome! Where are you starting from with your game?" Options:
+- `A) No idea yet`: no game concept; explore and find what to make.
+- `B) Vague idea`: a theme, feeling or genre ("something with space", "a cozy farming game").
+- `C) Clear concept`: the core idea and genre are known, nothing is written down yet.
+- `D) Existing work`: design documents, prototypes, code or plans already exist.
+
+Wait for the answer. If it contradicts Phase 1, say what you found once and ask again: D on an
+empty project ("this looks like a fresh template; would A or B fit better?"), or A with code on
+disk ("I found code in `[code_root]`; did you mean D?"). If no option fits, let the user describe
+their situation and route from that.
+
+## Phase 3: Route
+
+Name the immediate next step only. The full path waits for Phase 6, after the rigor is known.
+
+- **A, no idea:** starting from zero is fine. `/brainstorm open` explores freely; `/brainstorm
+ [hint]` starts from a word or theme. Next step: `/brainstorm open`, or a hint if one comes to
+ mind. Describe it as "turns no idea into a written design the next step builds from"; how long
+ that design is depends on the rigor, so leave that for Phase 6.
+- **B, vague idea:** ask for the idea in a few words, take it as it is, and name
+ `/brainstorm [their words]`.
+- **C, clear concept:** ask for the concept in one sentence (genre and core mechanic), as plain
+ text. Then ask: "How would you like to proceed?" Options: `Formalize it first` (`/brainstorm
+ [concept]` writes it down) / `Jump straight in` (`/setup-engine` now, write the design after).
+ The next step is their pick.
+- **D, existing work:** say what Phase 1 found ("N source files under `[code_root]`, N design
+ documents, engine [X / not set]"). Next step: `/setup-engine` when no engine is set and there is
+ no more than a concept; otherwise `/project-stage-detect`.
+
+Then say: "I'll lay out the full path in a moment."
+
+## Phase 4: Show what you assume, then save it
+
+Work out two values.
+
+**Stage.** Paths A, B and C: `Concept`. Path D, from the Phase 1 rows:
+
+| On disk | Stage |
+|---|---|
+| no engine, or nothing beyond a concept (`gdd_files` 0) | `Concept` |
+| `gdd_files` 1 or more, `adr` 0 | `Systems Design` |
+| `adr` 1 or more | `Technical Setup` |
+
+**Rigor.** If `modes.rigor` is already set in `project.yaml`, keep it and say so. Otherwise infer
+it from what the user said in Phases 2 and 3, using the signals in
+`.claude/docs/settings-guidance.md` §3:
+
+| The user's words mention | Rigor |
+|---|---|
+| open world, RPG, sim, sandbox, factions, crafting, economy, MMO, multiplayer, many systems | `full` |
+| release, commercial, Steam, one clear core loop | `standard` |
+| jam, weekend, prototype, first game, small, just trying | `minimal` |
+| nothing above, or no idea yet | `minimal` (the default) |
+
+A path B hint is still a description: "some kind of open-world survival sim" is `full`.
+
+Show the card:
+
+```
+What I'll set up
+ Stage: [stage] ([why, from what was found or picked])
+ Rigor: [value] ([why, in the user's words] | already set)
+ minimal: short brief, coarse stories, tests optional; about 4 steps to code
+ standard: about 8 design documents before code; standard QA evidence
+ full: everything in standard plus validation builds; evidence everywhere
+ /settings changes either of these any time.
+```
+
+Then ask with the question tool: "Save these to `project.yaml` (and the stage to
+`production/stage.txt`)?" Options: `Save them` / `Don't save`. Ask no question about the rigor
+itself: the card shows it, and `/settings` changes it.
+
+- **Save them:** run `bash .claude/scripts/set-stage.sh "[stage]"`, then, only when rigor was not
+ already set, `bash .claude/scripts/config-set.sh modes.rigor [value]`. Check the read-back rows
+ match. Say: "Saved. Rigor `[value]` sets six other settings; `/settings` shows them and changes
+ any of them."
+- **Don't save**, or anything other than an explicit yes: write nothing, keep the values for this
+ run, and say they were not saved.
+
+If a helper exits non-zero, show its output, say which setting was not written, and go on with the
+value for this run.
+
+## Phase 5: Ask how much to confirm
+
+If `modes.automation` is already set, say "Automation is `[value]`" and go on. Otherwise ask:
+"Last one: how much should I confirm with you as we work?" Options:
+- `Guided (Recommended)`: I decide small things and still stop for big ones (scope changes,
+ deletions, schema changes).
+- `Collaborative`: I ask before each significant step and show drafts before writing.
+- `Autonomous`: I proceed and log decisions, stopping only for the always-ask categories. Fastest,
+ most tokens.
+
+Mapping: `Guided` → `guided`, `Collaborative` → `collaborative`, `Autonomous` → `autonomous`. The
+pick is the consent to write it: run `bash .claude/scripts/config-set.sh modes.automation [value]`,
+unless the Phase 4 save was declined (then say it was not saved).
+
+## Phase 6: Show the path
+
+Say: "Here's your path at rigor `[value]`. Every skill still runs at any rigor; rigor changes
+what's required, not what's allowed."
+
+The path starts with the step Phase 3 named. When that was `/brainstorm` (paths A and B, and C's
+`Formalize it first`), list `/brainstorm` first and `/setup-engine` second: each runs without the
+other.
+
+**`minimal`: 4 steps to running code**
+1. `/setup-engine`: choose and configure the engine
+2. `/brainstorm`: write the one-page `design/game-brief.md`
+3. `/create-stories`: turn the brief's MVP list into stories (no epics or sprint plan needed)
+4. `/dev-story`: the first line of game code
+
+**`standard`**
+- Concept: `/setup-engine` → `/brainstorm` → `/prototype` → `/art-bible` → `/gate-check`
+- Systems Design: `/map-systems` → `/design-system` (once per system) → `/review-all-gdds` →
+ `/gate-check`
+- Architecture: `/create-architecture` → `/architecture-decision` (once per decision) →
+ `/create-control-manifest` → `/architecture-review` → `/test-setup` → `/ux-design`
+ (accessibility and interaction patterns) → `/gate-check`
+- Pre-Production: `/ux-design` (HUD and key screens) → `/create-epics` → `/create-stories` →
+ `/sprint-plan` → `/gate-check`
+- Production: `/dev-story`
+
+Each `/gate-check` moves the project one stage, and only when it passes.
+
+**`full`:** everything in `standard`, plus `/vertical-slice` and `/playtest-report` in
+Pre-Production and `/design-review` after each GDD.
+
+**Path D with existing work** (stage `Systems Design` or later, or code on disk) gets this instead.
+Print only the steps that apply, and for the brief only the one source that applies. At `minimal`:
+1. `/project-stage-detect`: what stage the project is at and what is missing
+2. `/adopt`: whether the existing files are in the format the skills read
+3. `/setup-engine`: only when no engine is set; leave it out when `engine` names one
+4. The brief, only if `concept` is absent: `/reverse-document design [code_root]` when the code
+ root holds 10 or more source files (it writes the brief from the game), and then do not mention
+ `/brainstorm` at all; `/brainstorm` only when it holds fewer
+
+At `standard` and `full`, steps 1 to 3, then `/design-system retrofit [path]`,
+`/architecture-decision retrofit [path]`, `/architecture-review` and `/gate-check`.
+
+Present `minimal` as the documented floor, not a lesser mode, and name its trade once: no GDDs, so
+design problems show up in code.
+
+If `origin_url` pointed at the template repo, add: "Your clone's `origin` still points at the
+CCGS template repo, so a push or pull request would go there. When you're ready, run
+`git remote rename origin template`, then `git remote add origin <your repo URL>`. `UPGRADING.md`
+pulls updates from `template`; skip its own `git remote add template` step, since that remote now
+exists." Suggest it; do not run it.
+
+Ask: "Would you like to start with [first step]?" Options: `Yes, start with [first step]` /
+`Something else first`. Either answer leads to Phase 7, never to running the step.
+
+## Phase 7: Hand off
+
+Respond with exactly one line: "Type `[skill]` to begin." Do not start that skill or call the
+skill tool for it, even after a yes: the user types it. If they picked something else, name the skill for that instead, the same
+way.
+
+Verdict: **COMPLETE**, the user is oriented and handed off. If the user stopped before Phase 7,
+say which settings were saved and which were not.
diff --git a/.claude/skills/story-done/CONTRACT.md b/.claude/skills/story-done/CONTRACT.md
index 6748402e..fd7b6cfe 100644
--- a/.claude/skills/story-done/CONTRACT.md
+++ b/.claude/skills/story-done/CONTRACT.md
@@ -16,27 +16,27 @@ Closes the implementation loop for a single story by verifying every acceptance
| `production/session-state/active.md` | Active story path (used when no argument given) | No — `<!-- CHECKPOINT -->` block overwritten |
> **Tier.** The TR registry, GDD-section and ADR rows are `standard`/`full` inputs.
-> At `workflow: minimal` the story traces to the brief, and Phase 4 runs the
-> acceptance-criteria check only (no GDD/ADR traceability); the manifest,
-> hardcoded-value and scope checks still run. At `qa.level: minimal` no test
-> evidence is required (SKILL.md Phase 3) — but the Visual/UI run-and-observe
-> screenshot is not waived.
+> At `workflow: minimal` the story traces to the brief, and Phase 5 runs no GDD
+> or ADR check; the manifest, hardcoded-value and scope checks still run. At
+> `qa.level: minimal` no test evidence is required (SKILL.md Phase 4) — but the
+> Visual/UI run-and-observe screenshot is not waived.
### Test Evidence Files (presence checked, not pre-required to exist — absence triggers gate)
| Story Type | Expected Location |
|------------|------------------|
| Logic | `tests/unit/[system]/[story-slug]_test.[ext]` |
-| Integration | `tests/integration/[system]/[story-slug]_test.[ext]` OR `production/session-logs/` playtest record |
+| Integration | `tests/integration/[system]/[story-slug]_test.[ext]` OR `production/qa/playtests/` playtest record |
| Visual/Feel | `production/qa/evidence/[story-slug]-evidence.md` + a retained screenshot |
| UI | A retained screenshot of each screen touched, under `production/qa/evidence/` — no evidence doc or sign-off required |
| Config/Data | `production/qa/smoke-*.md` |
### Preconditions
- The story file must be findable either by argument path, in `production/session-state/active.md`, or in the current sprint file as `IN PROGRESS`
-- Implementation must have been attempted (source files listed in the story's "files to create/modify" should exist) — this skill does not implement; it verifies
+- Implementation must have been attempted (the files the story's `## Files` section lists should exist) — this skill does not implement; it verifies
+- At `qa.level: full`, a Config/Data story's smoke report is BLOCKING by default (an explicit `testing.strict.config: false` keeps it advisory), and any UNTESTED acceptance criterion blocks; at `standard` only more than half untested blocks
- For Logic and Integration stories, the test file at the `## Test Evidence` path must **exist** before a COMPLETE verdict is possible — unless `testing.strict` in `project.yaml` sets that type to advisory (`testing.strict.logic`/`.integration: false`), in which case a missing test is recorded as a warning but does not block
- For Visual/Feel and UI stories, a retained screenshot must exist under `production/qa/evidence/` before a COMPLETE verdict is possible, and for Visual/Feel an evidence doc with every sign-off `[x] Approved` too (UI needs the screenshot only, as `coding-standards.md` says) — unless `testing.strict.visual`/`.ui` is set to `false`, in which case the gap is recorded as a warning but does not block
-- **This skill does not execute the test.** Phase 3 checks existence with `Glob`; nothing runs. A test that exists and FAILS satisfies the gate, so a failing test cannot block a COMPLETE verdict here — this gate is existence, not "exist and pass". Pass/fail is established by `/gate-check` and `/smoke-check`, both of which run a suite and both of which come after story closure. See the note under Phase 3 of `SKILL.md`.
+- **This skill does not execute the test.** Phase 4 checks that the file exists; nothing runs. A test that exists and FAILS satisfies the gate, so a failing test cannot block a COMPLETE verdict here — this gate is existence, not "exist and pass". Pass/fail is established by `/gate-check` and `/smoke-check`, both of which run a suite and both of which come after story closure. See Phase 3 of `SKILL.md`.
## Verdicts Emitted
`COMPLETE` / `COMPLETE WITH NOTES` / `NOT ASSESSED` / `BLOCKED`.
@@ -44,26 +44,25 @@ Closes the implementation loop for a single story by verifying every acceptance
`NOT ASSESSED` outranks `COMPLETE` — one or more acceptance criteria could not
be evaluated at all, which is not the same as evaluating them and finding them
met. Precedence is `BLOCKED`, then `NOT ASSESSED`, then `COMPLETE WITH NOTES`,
-then `COMPLETE`; see the verdict section of `SKILL.md`. This contract listed no
-verdict set at all, so a reader had nothing to branch on.
+then `COMPLETE`; see the verdict section of `SKILL.md`.
## Outputs Produced
### Files Written
| File | Guaranteed Fields / Sections | Notes |
|------|------------------------------|-------|
-| `production/epics/**/*.md` (the story file) | `Status: Complete`, `## Completion Notes` block (date, criteria count, deviations, test evidence path, code review status) | updated after explicit user approval |
+| `production/epics/**/*.md` (the story file) | `Status: Complete`, `## Completion Notes` block (date, criteria count, deviations, test evidence path, code review status, Reviewed by) | updated after explicit user approval |
| `production/sprint-status.yaml` | `status: done`, `completed: [date]`, top-level `updated` field | updated silently alongside story file if file exists |
| `docs/tech-debt-register.md` | Advisory deviation entries (if user confirms) | appended if advisory deviations exist and user agrees |
-| `production/session-state/active.md` | `<!-- CHECKPOINT -->` block: current task (story path and verdict), next step (the next story), blocker, tech debt count | block overwritten, never appended (file created from `.claude/docs/templates/session-state.md` if absent) |
+| `production/session-state/active.md` | `<!-- CHECKPOINT -->` block: current task (story path, verdict, closed or left open), next step (the next story, or the fix the verdict named), blocker, tech debt count | written on every verdict, closed or not, by `session-state.sh checkpoint`: the block is replaced, never appended (the file is created from `.claude/docs/templates/session-state.md` if absent) |
### Output Guarantees
- `Status: Complete` is written only after the user explicitly approves: on a COMPLETE or COMPLETE WITH NOTES verdict, or — on a BLOCKED or NOT ASSESSED verdict — only when the user explicitly asks to close anyway (the Phase 7 override, which always prompts as a `scope_changes` decision), with the override risk recorded in `## Completion Notes`
-- `## Completion Notes` always contains: completion date, criteria pass count, deviation summary, test evidence path (or "None required"), code review status
+- `## Completion Notes` always contains: completion date, criteria pass count, deviation summary, test evidence path (or "None required"), code review status, and a Reviewed by line: `lead-programmer`, `/code-review (you said you ran it; not verified here)`, or `self, no independent review` when nobody else reviewed the work
- Session state always records the final verdict and the next recommended story path
## Immutability Rules
-- READS but does NOT modify: `docs/architecture/tr-registry.yaml`, `docs/architecture/adr-NNNN-[slug].md` (Decision + Consequences only), GDD sections, `docs/architecture/control-manifest.md`, source files under the code root — `src/`, `Assets/` or `Source/` by engine (Grep only) — and test files under the engine's test root (existence checked with Glob; never run or edited)
+- READS but does NOT modify: `docs/architecture/tr-registry.yaml`, `docs/architecture/adr-NNNN-[slug].md` (Decision + Consequences only), GDD sections, `docs/architecture/control-manifest.md`, source files under the code root — `src/`, `Assets/` or `Source/` by engine (searched only) — and test files under the engine's test root (existence checked; never run or edited)
- MODIFIES: the story `.md` file (status + completion notes), `production/sprint-status.yaml` (if exists), `production/session-state/active.md` (the `<!-- CHECKPOINT -->` block, overwritten), `docs/tech-debt-register.md` (append a row, and update its `Last updated:` and `Total items:` lines, only with user approval)
- Does NOT write to the code root or the test root under any circumstances
@@ -81,13 +80,14 @@ verdict set at all, so a reader had nothing to branch on.
- It will read: story files in `production/epics/` checking `Status: Complete` and presence of `## Completion Notes`
- It will read: `tests/unit/` and `tests/integration/` for test file presence and will run the test suite via Bash
- It assumes: every Complete Logic story whose `testing.strict.logic` gate resolved to BLOCKING (the default) has a corresponding test file that **exists**; under an explicit `testing.strict.logic: false` a Logic story may be Complete with the test gap documented in `## Completion Notes`
- > **Existence, not passing.** `/story-done` checks that the test file exists with `Glob` and runs nothing, so a Complete Logic story may carry a test that fails. `/gate-check` running the suite is the FIRST point at which pass/fail is established, so it must never treat a Complete status as evidence the tests passed — it has to run them. That is also why an unconfigured test runner is `NOT ASSESSED` there rather than a silent skip: with no run, nothing upstream has verified the story either.
+ > **Existence, not passing.** `/story-done` checks that the test file exists and runs nothing, so a Complete Logic story may carry a test that fails. `/gate-check` running the suite is the FIRST point at which pass/fail is established, so it must never treat a Complete status as evidence the tests passed — it has to run them. That is also why an unconfigured test runner is `NOT ASSESSED` there rather than a silent skip: with no run, nothing upstream has verified the story either.
- It assumes: Visual/Feel and UI stories that are Complete have a retained screenshot in `production/qa/evidence/`, and Visual/Feel ones a signed-off evidence doc as well — that gate is BLOCKING by default; only under an explicit `testing.strict.visual`/`.ui: false` may such a story be Complete with the deviation documented in `## Completion Notes`
- It will read: `production/sprint-status.yaml` for `status: done` entries if that file exists
## Known Fragile Points
-- The story's `## Test Evidence` section must contain the exact file path written by `/dev-story`; a path mismatch causes a false BLOCKING result even if the test file exists under a slightly different name
+- The story's `## Test Evidence` path is checked first; when it does not match, Phase 4 searches `tests/unit/[system]/` (or `tests/integration/[system]/`) before flagging the test missing, so a file under a slightly different name is still found — one outside that folder is not
+- The scope check reads the story's `## Files` list (filled by `/create-stories`, replaced by `/dev-story`). A story written before the section existed falls back to the checkpoint's **Files in progress** when it names this story, else reports scope NOT ASSESSED; changes already committed are not seen, since it compares uncommitted files only
- If `Type:` is absent from the story header, test evidence gate enforcement is ADVISORY only — stories can slip through without tests
- Manifest version staleness check is skipped if `docs/architecture/control-manifest.md` does not exist; the check being skipped is noted in the report but is non-blocking
- `production/sprint-status.yaml` update is silent (no separate approval); if that file uses a different key structure than expected, the update silently fails and sprint tracking becomes stale
-- The traceability table escalation rule (>50% UNTESTED = BLOCKING) can be triggered by deferred Visual/Feel criteria that are legitimately not automatable — ensure deferred criteria are explicitly marked `DEFERRED` (not left as unchecked) to avoid false escalation
+- The traceability table escalation rule (>50% UNTESTED = BLOCKING at `qa.level: standard`, any UNTESTED at `full`) can be triggered by deferred Visual/Feel criteria that are legitimately not automatable — ensure deferred criteria are explicitly marked `DEFERRED` (not left as unchecked) to avoid false escalation
diff --git a/.claude/skills/story-done/SKILL.md b/.claude/skills/story-done/SKILL.md
index e03cdb05..91c6f7c3 100644
--- a/.claude/skills/story-done/SKILL.md
+++ b/.claude/skills/story-done/SKILL.md
@@ -1,87 +1,351 @@
---
name: story-done
-description: "End-of-story completion review — verifies each acceptance criterion, checks GDD/ADR deviations, prompts code review, updates status."
+description: "Closes a finished story: verifies each acceptance criterion, checks for design or ADR deviations and updates its status. Use when the user says a story is done, finished or ready to close."
argument-hint: "[story-file-path] [--review full|lean|solo]"
user-invocable: true
disable-model-invocation: true
-allowed-tools: Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/story-done/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/story-done/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/story-facts.sh *), Bash(bash .claude/scripts/story-status.sh*), Bash(bash .claude/scripts/adr-status.sh *), Bash(bash .claude/scripts/md-section.sh *), Bash(bash .claude/scripts/review-receipts.sh check *), Bash(bash .claude/scripts/session-state.sh *), Bash(git status --porcelain*)
model: sonnet
---
-!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,story_granularity,qa.level,testing.strict,system_overrides`
+!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,automation_always_ask,workflow,qa.level,gate_level,system_overrides`
Resolved above — use as-is; `--review` overrides `review_mode`. No block →
defaults in `.claude/docs/config-resolution.md`.
+Ask with the question tool. Without one, list the options numbered and end your turn
+to wait. A skipped or dismissed question is not an answer: ask again in plain text.
+
# Story Done
-This skill closes the loop between design and implementation. Run it at the end
-of implementing any story. It ensures every acceptance criterion is verified
-before the story is marked done, GDD and ADR deviations are explicitly
-documented rather than silently introduced, code review is prompted rather than
-forgotten, and the story file reflects actual completion status.
+Closes a finished story. Every acceptance criterion is checked against evidence,
+deviations from the GDD, the ADRs and the story's own scope are reported as facts,
+and the story is marked Complete only on the user's yes.
-**Output:** Updated story file (Status: Complete) + surfaced next story.
+**Writes, after the user's yes:** the story file (`Status`, `Last Updated`, a
+`## Completion Notes` section) and its `production/sprint-status.yaml` entry;
+`docs/tech-debt-register.md` only when the user picks that option. The session
+checkpoint is written at the end of every run, whatever the verdict.
+**Next:** the next story (Phase 8).
----
+Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided
+asks on major choices, autonomous logs and goes on; `automation_always_ask`
+categories always ask).
-## Phase 1: Find the Story
+Checklist (copy it and tick as you go):
-**Read `references/1-find-story.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
+```
+- [ ] Phase 1: story found, facts and settings read
+- [ ] Phase 2: what the story is checked against, loaded for its tier
+- [ ] Phase 3: each criterion verified, traceability table built
+- [ ] Phase 4: test evidence and run result checked
+- [ ] Phase 5: deviations and scope checked
+- [ ] Phase 6: review gates run, or their skip noted
+- [ ] Phase 7: report and verdict shown; close asked
+- [ ] Phase 8: next story named, checkpoint written, closing block printed
+```
-## Phase 2: Read the Story
+## Phase 1: The story and its settings
-**Read `references/2-read-story.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
+**Which story.** The text typed after the skill name, with any `--review <mode>`
+pair removed, is the story path. With nothing typed:
-## Phase 3: Verify Acceptance Criteria
+1. The checkpoint in `production/session-state/active.md`: its **Current task**
+ line, when it names a story.
+2. Else the stories in progress: `bash .claude/scripts/story-facts.sh --all`, rows
+ whose state is `IN_REVIEW` or `IN_PROGRESS`. Several: ask "Which story are we
+ closing?" with one option per story.
+3. None: ask for the path. When `production/epics/` holds no story file at all,
+ stop:
+ "No stories found in `production/epics/` — run `/create-stories [epic-slug]` to make them (at `standard` and `full`, run `/create-epics` first if there is no epic yet)."
-**Read `references/3-verify-criteria.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
+**Its facts.** `bash .claude/scripts/story-facts.sh <story-path>` gives the status,
+type, layer, TR-IDs, ADRs, criteria count, test-evidence status and dependencies.
+Then read the story in full: the criteria text, the Test Evidence path, `## Files`,
+Out of Scope.
-## Phase 4: Check for Deviations
+**Tier.** `workflow` for the story's system, keyed on the GDD filename stem of its
+`GDD:` path (`design/gdd/<stem>.md` → `<stem>`; the `[system]` of its TR-ID only
+when there is no GDD path): that system's `system_overrides` row if there is one,
+else the project value.
-**Read `references/4-deviations.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
+**What `qa.level` requires** (the evidence rows of `.claude/docs/coding-standards.md`).
+Take the value from the `qa.level` line above, never from `workflow` or `rigor`: the
+two are set apart, so `workflow: minimal` with `qa.level: standard` still requires a
+Logic story's unit test.
-## Phase 5: Lead Programmer Code Review Gate
+| Check | `qa.level: minimal` | `qa.level: standard` | `qa.level: full` |
+|---|---|---|---|
+| Logic, Integration test | waived | required | required |
+| Config/Data smoke report | waived | required, advisory by default | required, **blocking** by default |
+| Visual/Feel, UI retained screenshot | required | required | required |
+| Untested criteria (Phase 3) | never escalate | more than half block | **any** blocks |
-**Read `references/5-code-review-gate.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
+The look is never waived: a Visual/Feel or UI story needs its screenshot at every
+level. **Gate level** per type is the `gate_level` line above. At `full`, a
+Config/Data default (`config=advisory(default…)`) becomes blocking; an explicit
+`testing.strict.config: false` still makes it advisory.
-## Phase 6: Present the Completion Report
+## Phase 2: What the story is checked against
-**Read `references/6-completion-report.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
+By the tier. Read every document by section, never whole.
-## Phase 7: Update Story Status
+- **`full`:** the current requirement text of each TR-ID: in
+ `docs/architecture/tr-registry.yaml`, the lines matching `id: <TR-ID>\s*$` and the
+ entry's text below (the anchor keeps `TR-combat-001` from matching
+ `TR-combat-0010`; `\s*` takes a Windows line ending). Never use text quoted in the
+ story; the GDD's Acceptance Criteria and Detailed Design
+ (`bash .claude/scripts/md-section.sh extract design/gdd/<file>.md "Acceptance Criteria"`,
+ then the same for `"Detailed Design"`; exit 3: try `"Detailed Rules"`, the design
+ standard's name for the same section);
+ each ADR's status with `bash .claude/scripts/adr-status.sh <ADR ids>`, then its
+ Decision and Consequences sections.
+- **`standard`:** the same GDD sections; the ADR sections only for a critical ADR
+ (`adr-status.sh`'s layer column reads Foundation, or has no layer).
+- **`minimal`:** none. The story's criteria are the spec.
-**Read `references/7-update-status.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
+At every tier, when `docs/architecture/control-manifest.md` exists, note its
+`Manifest Version` line.
-## Phase 8: Surface the Next Story
+## Phase 3: Verify each criterion
-**Read `references/8-next-story.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
+Take each acceptance criterion in turn:
-## Collaborative Protocol
+- **Checked by looking:** a file the criterion names exists; a test file it names
+ exists (report "test file present", never "test passes": nothing here runs it);
+ numeric literals in gameplay code that belong in data files; player-facing
+ strings in the code root that belong in localization files (resolve the root
+ per `.claude/docs/code-root-resolution.md`; unresolved, report `NOT ASSESSED —
+ code root unresolved`, never zero hits).
+- **Asked:** behaviour ("the player takes damage when…"), feel, and performance
+ criteria. Never mark one passed from reading the code: the code says what should
+ happen, not what the build does. Up to four per ask: "Does [criterion]?" Options:
+ Yes — passes / No — fails / Not tested yet. `Not tested yet` is UNTESTED, and
+ keeps the verdict at best NOT ASSESSED until someone checks it.
+- **Seen on screen:** a criterion about something visible is covered by a retained
+ image under `production/qa/evidence/[story-slug]/` (`[story-slug]`: the story
+ file's name without `.md`) that you opened and saw it in.
+ Never describe an image you have not opened; a checkpoint's `Run result:
+ OBSERVED — <text>` is `/dev-story`'s description, to quote as such.
+- **Needs a full playtest:** `DEFERRED — requires playtest session`. It does not
+ block.
-**In `collaborative` mode (the default).** For `guided` and `autonomous` modes,
-see `.claude/docs/automation-modes.md` — the rules below describe collaborative
-behavior. The BLOCKED-override close (Phase 7) always prompts regardless of mode
-(it's a `scope_changes` always-ask decision).
+Then map each criterion to what covers it: a test under the test root, a
+"Yes — passes", or a retained image.
-- **Never mark a story complete without user approval** — Phase 7 requires an
- explicit "yes" before any file is edited.
-- **Never auto-fix failing criteria** — report them and ask what to do.
-- **Deviations are facts, not judgments** — present them neutrally; the user
- decides if they are acceptable.
-- **BLOCKED and NOT ASSESSED verdicts are advisory** — the user can override and
- mark complete anyway; document the risk explicitly if they do. For NOT
- ASSESSED, the documented risk is that the criterion was never evaluated, not
- that it failed — record which criteria those were, so the gap is recoverable
- later rather than closed over.
-- Use `AskUserQuestion` for the code review prompt and for batching manual
- criteria confirmations.
+```
+| Criterion | Covered by | Status |
+|-----------|------------|--------|
+| AC-1: [text] | tests/unit/[system]/[file]::[test] | COVERED |
+| AC-2: [text] | production/qa/evidence/[slug]/01-[what].png | COVERED |
+| AC-3: [text] | — | UNTESTED |
+```
----
+Untested criteria escalate by the Phase 1 table: blocking above the line; below it,
+advisory, listed in the Completion Notes as "Untested criteria: [AC-N list]".
+
+## Phase 4: Test evidence and the run result
+
+By the story's type, at the Phase 1 gate level. Skip a check `qa.level` waives, and
+say so: `Test evidence: waived at qa.level minimal`.
+
+- **Logic:** the exact path in the story's Test Evidence section, else anywhere
+ under `tests/unit/[system]/`.
+- **Integration:** the same under `tests/integration/[system]/`, else a playtest
+ record naming this story in `production/qa/playtests/` (`/playtest-report`
+ writes them there).
+- **UI:** a UI story is satisfied by the retained screenshot of each screen touched,
+ under `production/qa/evidence/`. No evidence doc or sign-off needed.
+- **Visual/Feel:** the screenshot, and a Visual/Feel story also needs the sign-off:
+ `production/qa/evidence/[story-slug]-evidence.md` with every sign-off row
+ `[x] Approved` (one person may sign every role).
+- **Config/Data:** a `production/qa/smoke-*.md` report; none: "No smoke check
+ report found. Run `/smoke-check`."
+- **No Type:** advisory: "Story Type not declared. Add `Type:` to the story header."
+
+A missing item is a gap at the gate level: BLOCKING stops COMPLETE, ADVISORY goes
+in the notes. Name what is missing and where it goes. An evidence doc with no image
+beside it is not evidence: a described check is an assertion.
+
+**Is the evidence older than its code?** For a retained image, run
+`bash .claude/scripts/review-receipts.sh check production/qa/evidence/[story-slug]/stamp.txt`.
+Each `CHANGED:` or `GONE:` file: "[file] changed after the evidence was captured —
+re-capture it." `RECEIPT: NONE`: "no stamp — whether the evidence is older than the
+code cannot be told". Report these lines; they never change the verdict.
+
+**Run result, every other type.** Take the `Run result:` line from the `/dev-story`
+checkpoint (only when its **Current task** names this story) or the story's Completion Notes.
+`OBSERVED` with a path: note it. `N/A — <reason>`: accept only a reason that says
+why nothing is observable ("it's a Logic story" is not one). `NOT VERIFIED` on a
+story whose criteria name something on screen: a gap at the gate level. No line:
+advisory, "confirm the build was launched and looked at". A user's "Yes — passes"
+to an on-screen criterion with no retained image is an assertion, not an
+observation: a gap at the gate level.
+
+## Phase 5: Deviations and scope
+
+Run, by tier (`minimal` skips 1 and 3):
+
+1. **GDD rules** (`full`; `standard` on its required sections): search the changed
+ files for the names the current GDD text and TR requirement use.
+2. **Manifest:** the story's `Manifest Version` older than the manifest's: ADVISORY,
+ "written against manifest v[story]; current is v[current] — run
+ `/story-readiness` to check". No manifest: skip. A `Manifest-Note:` line in the
+ story is carried into the deviations as written.
+3. **ADR constraints** (`full`; `standard` for a critical ADR): search for the
+ patterns the ADR's Decision or the manifest forbids.
+4. **Hardcoded values** in the changed files.
+5. **Scope:** the files the story lists under `## Files` against the code and test
+ files changed (`git status --porcelain`). A changed file the list does not name
+ is OUT OF SCOPE. A story with no `## Files` section: use the checkpoint's
+ **Files in progress** when its Current task names this story; else report
+ `Scope: NOT ASSESSED — the story lists no files`. A clean working tree: report
+ `Scope: not checked — no uncommitted changes to compare`.
+
+Each deviation is **BLOCKING** (contradicts the GDD or ADR), **ADVISORY** (drifts
+but works the same; the user decides) or **OUT OF SCOPE** (for awareness). State
+them as facts; the user judges them.
+
+## Phase 6: Review gates
+
+Read the `review_gate` line above.
+
+- **`skill-gates=skip`:** no agent. Note `QL-TEST-COVERAGE skipped — [Solo | Lean]
+ mode` and `LP-CODE-REVIEW skipped — [Solo | Lean] mode`. In `lean` mode, ask: "Did
+ you run `/code-review` on the implemented files?" Options: Yes — it passed or was
+ approved with suggestions / No — skipping review for this story / No — I'll run
+ it before the sprint close-out. The answer sets Reviewed by.
+- **`skill-gates=run`:** read `references/review-gates.md` and
+ `.claude/docs/director-gates.md`, and run both gates now. On a skip, do not load
+ it.
+
+**Reviewed by** is never blank: `lead-programmer` when LP-CODE-REVIEW ran;
+`/code-review (you said you ran it; not verified here)` for the lean Yes; `self, no
+independent review` in solo mode, for either No, and when no implementation file
+exists yet.
+
+## Phase 7: Report, verdict, and the close
+
+```markdown
+## Story Done: [title]
+**Story**: [path] · **Type**: [type] · **Date**: [today]
+
+### Acceptance Criteria: [X/Y passing]
+- [x] [criterion] — [how verified]
+- [ ] [criterion] — FAILS: [reason]
+- [?] [criterion] — DEFERRED: requires playtest
+
+### Traceability
+[the Phase 3 table]
+
+### Test Evidence
+**Required**: [what the type needs at this qa.level, or "waived at qa.level minimal"]
+**Found**: [YES — path | NO — BLOCKING | NO — ADVISORY]
+
+### Deviations
+[NONE, or each: BLOCKING / ADVISORY / OUT OF SCOPE — description — reference]
+
+### Review
+**Reviewed by**: [value]
+
+### Verdict: [COMPLETE | COMPLETE WITH NOTES | NOT ASSESSED | BLOCKED]
+```
+
+**Verdicts, the first that matches wins:**
+
+1. **BLOCKED:** a criterion fails, or a BLOCKING gap or deviation stands.
+2. **NOT ASSESSED:** a criterion could not be evaluated: it names no observable
+ outcome, the user answered "Not tested yet", a review gate returned NOT ASSESSED
+ and its input was not supplied, evidence exists but cannot be read, or the GDD
+ or ADR a deviation would be judged against is missing. Name each one and what
+ would settle it. It outranks the two passes and never hides a failure.
+3. **COMPLETE WITH NOTES:** every criterion passes or is DEFERRED, with advisory
+ items listed. Information lines are not advisory items: the evidence-stamp
+ lines, an absent sprint file and the run result never turn COMPLETE into COMPLETE
+ WITH NOTES.
+4. **COMPLETE:** every criterion passes, nothing advisory.
+
+**Then ask, before writing anything:** "How do you want to proceed?" Options:
+Close the story — mark it Complete and log notes (Recommended) / Close and log the
+advisory deviations as tech debt / Don't close yet — I'll fix things first / Close
+anyway, accepting the deviations. On BLOCKED or NOT ASSESSED, recommend "Don't close
+yet" and list what must change. Closing such a story is a `scope_changes` decision:
+when the `automation_always_ask` line lists it, ask in every automation mode, even
+when the user's own request is what got here. Write only on an explicit choice to
+close.
+
+**On close:**
+
+1. `bash .claude/scripts/md-section.sh set-field <story> Status Complete`, then
+ `set-field <story> "Last Updated" <YYYY-MM-DD> --after Status`.
+2. Add at the end of the story, with a file edit, never a shell command (a shell
+ write skips the project's write checks):
+ ```markdown
+ ## Completion Notes
+ **Completed**: [date]
+ **Criteria**: [X/Y passing] ([deferred items])
+ **Deviations**: [None, or the advisory ones]
+ **Test Evidence**: [path, or "waived at qa.level minimal", or "none required"]
+ **Reviewed by**: [value]
+ ```
+3. "Close and log as tech debt": read `references/tech-debt-row.md` and add one
+ row per advisory deviation.
+4. `production/sprint-status.yaml`, when it exists: this story's entry gets
+ `status: done` and `completed: [date]`, and the top-level `updated` gets today.
+ The close answer covers it.
+5. Print a suggested commit: `git add [the changed code and test files] [story path]`
+ and `git commit -m "feat: [story title] ([TR-ID])"`.
+
+**On "Don't close yet":** change no story file. List what the user flagged. Never
+fix a failing criterion yourself: report it and ask what to do.
+
+## Phase 8: Next story, checkpoint, close
+
+**The next story.** With no sprint plan in `production/sprints/` (always at
+`workflow: minimal`): Run `bash .claude/scripts/story-status.sh` after the close, so
+this story's new status is in it. It prints the unfinished stories in route order;
+do not re-rank them. The first `In Review` story is next (the first `IN_REVIEW`
+line), else the first `In Progress` one, else the first `Ready` or `Not Started`
+one (`TODO`):
+
+```
+### Next Up
+**[Story NNN: title]** — [one line]
+Run `/story-done [path]` to close it (In Review) — else `/dev-story [path]` to implement it.
+```
+
+When the `workflow` line above reads `minimal`, print no `/story-readiness` line at
+all, not even as an option: it is not on that path. With no sprint plan at
+`workflow: standard` or `full`, add "Run `/story-readiness [path]` first."
+
+- Only `COMPLETE N of N`: every story is built. Offer: play the build and note what
+ feels wrong; add stories from the brief with `/create-stories`; or `/settings` to
+ raise `modes.rigor` if the game has outgrown its brief.
+- Only `BLOCKED`, `OTHER` or `NO_STATUS` lines left: there is no Next Up, and the
+ build order is **not** done. Name each story with its blocker, `Draft` or `no
+ status`.
+- Never print the Sprint Close-Out Sequence on this branch: there is no sprint.
+
+With a sprint plan: read `references/sprint-next.md`.
+
+**The checkpoint**, on every verdict, closed or not. Pipe the block to
+`bash .claude/scripts/session-state.sh checkpoint`, which replaces the old block:
+
+```
+**Updated:** [date]
+**Branch:** `[current git branch]`
+**Current task:** /story-done — [story path]: [verdict], [closed | left open]
+**Next step:** [the Next Up command, or the fix the verdict named]
+**Blocked on:** [nothing, or what blocked the verdict]
+**Files in progress:** none
+**Open questions:** [tech debt logged: N items, or none]
+```
-## Recommended Next Steps
+**The run's last reply ends with this block** (repeat it if you showed it earlier):
-- At `minimal`: run `/dev-story [next-story-path]` (`/story-done` for an In Review one); when every story is Complete, play the build, then `/create-stories` for more or `/settings` to raise `modes.rigor`
-- With a sprint plan: run `/story-readiness [next-story-path]` to validate the next story before starting implementation
-- If a sprint plan exists and all its Must Have stories are complete: run `/smoke-check sprint` → `/team-qa sprint` → `/gate-check`
-- If tech debt was logged: track it via `/tech-debt` to keep the register current
+```
+Verdict: [COMPLETE | COMPLETE WITH NOTES | NOT ASSESSED | BLOCKED] — [story path]
+Story: [closed — Status: Complete | left open — Status: [status]]
+Review: [Reviewed by value; the gates' skip notes]
+Next step: [/dev-story [path] | /story-done [path] | the fix | play the build]
+```
diff --git a/.claude/skills/story-done/references/1-find-story.md b/.claude/skills/story-done/references/1-find-story.md
deleted file mode 100644
index 4bbb1b59..00000000
--- a/.claude/skills/story-done/references/1-find-story.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# /story-done — Phase 1: Find the Story
-
-> Part of `/story-done`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 1: Find the Story
-
-See `.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.
-
-
-Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
-(collaborative asks always · guided major-only · autonomous logs and proceeds;
-`automation_always_ask` categories always prompt).
-
-**Workflow tier**: resolved per the story's system (per
-`.claude/docs/workflow-modes.md`) — **the GDD filename stem** of the story's
-`GDD:` path (`design/gdd/<stem>.md` → `<stem>`), with the `[system]` segment of
-its `TR-[system]-NNN` ID accepted only as a fallback alias: use the
-`system_overrides` row for that system if the block lists one, else the
-project value. It governs which Phase 4 deviation checks run — see Phase 4.
-
-**Workflow companion — `modes.story_granularity`** (resolved above — supplied by
-`modes.rigor` unless set explicitly): cadence expectation only — story-done fires **every 3–5 days** at
-`coarse`, **every 1–2 days** at `balanced`, **multiple times/day** at `fine`. It
-does not change any completion check.
-
-**`qa.level`**: controls whether test *evidence is required*, where
-`testing.strict` controls whether a failure blocks and `workflow` controls which
-docs exist. `modes.rigor` sets `qa.level` and `workflow` together; set either
-explicitly to vary it alone. `testing.strict` is not fronted by `rigor` at all.
-At `minimal`, no *test* evidence is required → skip the Logic, Integration and
-Config/Data evidence checks (Phase 3), the >50%-untested traceability escalation,
-and the Phase 4b QA gate; the acceptance-criteria verification still runs, and so
-do the Visual/Feel and UI screenshot gate and the `Run result:` check for other
-story types — the look is never waived. At
-`standard`, the story's own type requires evidence; at `full`, every type does.
-`testing.strict` then decides whether present-but-failing evidence blocks.
-(`rigor: minimal` sets both; `qa.level: minimal` on its own leaves the workflow
-tier where it was.)
-
-**If a file path is provided** (e.g., `/story-done production/epics/core/story-damage-calculator.md`):
-read that file directly.
-
-**If no argument is provided:**
-
-1. Check `production/session-state/active.md` for the currently active story.
-2. If not found there, read the most recent file in `production/sprints/` and
- look for stories marked IN PROGRESS.
-3. If multiple in-progress stories are found, use `AskUserQuestion`:
- - "Which story are we completing?"
- - Options: list the in-progress story file names.
-4. If no story can be found, ask the user to provide the path.
-
----
diff --git a/.claude/skills/story-done/references/2-read-story.md b/.claude/skills/story-done/references/2-read-story.md
deleted file mode 100644
index e1f3e742..00000000
--- a/.claude/skills/story-done/references/2-read-story.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# /story-done — Phase 2: Read the Story
-
-> Part of `/story-done`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 2: Read the Story
-
-Read the full story file. Extract and hold in context:
-
-- **Story name and ID**
-- **GDD Requirement TR-ID(s)** referenced (e.g., `TR-combat-001`)
-- **Manifest Version** embedded in the story header (e.g., `2026-03-10`)
-- **ADR reference(s)** referenced
-- **Acceptance Criteria** — the complete list (every checkbox item)
-- **Implementation files** — files listed under "files to create/modify"
-- **Story Type** — the `Type:` field from the story header (Logic / Integration / Visual/Feel / UI / Config/Data)
-- **Engine notes** — any engine-specific constraints noted
-- **Definition of Done** — if present, the story-level DoD
-- **Estimated vs actual scope** — if an estimate was noted
-
-Also read:
-- `docs/architecture/tr-registry.yaml` — grep the story's TR-IDs
- (`Grep pattern="id: <each TR-ID>\s*$" path="docs/architecture/tr-registry.yaml" output_mode="content" -A 6`),
- not a full read of the registry. Read the *current* `requirement` text from each
- matched entry. This is the source of truth for what the GDD required — do not use any
- requirement text that may be quoted inline in the story (it may be stale).
-- The referenced GDD section — just the acceptance criteria and key rules, not
- the full document. Use this to cross-check the registry text is still accurate.
-- The referenced ADR(s) — **just the `## Decision` and `## Consequences`
- sections, never an unbounded full read.** Map headings first
- (`Grep pattern="^## " path="docs/architecture/[adr-file].md" output_mode="content" -n`),
- then bounded-`Read` only those two spans. This is the exact same content
- Phase 4 item 3's ADR constraints check needs — hold it here, do not
- re-read it there.
-- `docs/architecture/control-manifest.md` header — extract the current
- `Manifest Version:` date (used in Phase 4 staleness check)
-
----
diff --git a/.claude/skills/story-done/references/3-verify-criteria.md b/.claude/skills/story-done/references/3-verify-criteria.md
deleted file mode 100644
index f2400a1e..00000000
--- a/.claude/skills/story-done/references/3-verify-criteria.md
+++ /dev/null
@@ -1,246 +0,0 @@
-# /story-done — Phase 3: Verify Acceptance Criteria
-
-> Part of `/story-done`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 3: Verify Acceptance Criteria
-
-**In this file:**
-
-- Automatic verification (run without asking)
-- Manual verification with confirmation (use `AskUserQuestion`)
-- Unverifiable (flag without blocking)
-- Test-Criterion Traceability
-- Test Evidence Requirement
-
-For each acceptance criterion in the story, attempt verification using one of
-three methods:
-
-### Automatic verification (run without asking)
-
-- **File existence check**: `Glob` for files the story said would be created.
-- **Test file check**: if a test file path is mentioned, confirm the file exists
- with `Glob`. Do not run it — this skill establishes existence only (see the
- note under Test Evidence Requirement), so report "test file present", never
- "test passes".
-- **No hardcoded values check**: `Grep` for numeric literals in gameplay code
- paths that should be in config files.
-- **No hardcoded strings check**: `Grep` for player-facing strings in the **code root** (resolve per `.claude/docs/code-root-resolution.md`). **If the code root is unresolved, report `NOT ASSESSED — code root unresolved` rather than zero hits.**
- that should be in localization files.
-- **Dependency check**: if a criterion says "depends on X", check that X exists.
-
-### Manual verification with confirmation (use `AskUserQuestion`)
-
-- Criteria about subjective qualities ("feels responsive", "animations play correctly")
-- Criteria about gameplay behaviour ("player takes damage when...", "enemy responds to...")
- — these are asked, never marked verified from reading the code: the code says
- what should happen, not what the build does
-- Performance criteria ("completes within Xms") — ask if profiled or accept as assumed
-
-Batch up to 4 manual verification questions into a single `AskUserQuestion` call:
-
-```
-question: "Does [criterion]?"
-options: "Yes — passes", "No — fails", "Not tested yet"
-```
-
-Map each answer: `Yes — passes` → confirmed; `No — fails` → FAILS;
-`Not tested yet` → not evaluated — UNTESTED in the traceability table below, and
-the verdict is NOT ASSESSED (Phase 6) until someone checks it. If the criterion
-genuinely needs a full-build playtest, mark it `DEFERRED — requires playtest
-session` instead.
-
-### Unverifiable (flag without blocking)
-
-- Criteria that require a full game build to test (end-to-end gameplay scenarios)
-- Mark as: `DEFERRED — requires playtest session`
-
-### Test-Criterion Traceability
-
-After completing the pass/fail/deferred check above, map each acceptance
-criterion to the test that covers it:
-
-For each acceptance criterion in the story:
-
-1. Ask: is there a test — unit, integration, or confirmed manual playtest — that
- directly verifies this criterion?
- - **Unit test**: check `tests/unit/` for a test file or function name that
- matches the criterion's subject (use `Glob` and `Grep`)
- - **Integration test**: check `tests/integration/` similarly
- - **Manual confirmation**: if the criterion was verified via `AskUserQuestion`
- above with a "Yes — passes" answer, count that as a manual test
- - **Retained screenshot**: if the criterion names something on screen and a
- retained image under `production/qa/evidence/[story-slug]/` shows it (the
- `Run result: OBSERVED` from `/dev-story` Phase 6 step 4), count that as
- covered — put the image path in the Test column. A visual criterion
- verified by looking is not UNTESTED; without this row every UI story
- reads as >50% untested and false-escalates. "Shows it" means you opened
- the image with `Read` and saw it; a checkpoint's `Run result: OBSERVED —
- <text>` is `/dev-story`'s description, to quote as such, not yours.
- **Never describe an image you have not opened.**
-
-2. Produce a traceability table:
-
-```
-| Criterion | Test | Status |
-|-----------|------|--------|
-| AC-1: [criterion text] | tests/unit/test_foo.gd::test_bar | COVERED |
-| AC-2: [criterion text] | Manual playtest confirmation | COVERED |
-| AC-3: [criterion text] | production/qa/evidence/[slug]/01-shop-open.png | COVERED |
-| AC-4: [criterion text] | — | UNTESTED |
-```
-
-3. Apply these escalation rules (skip entirely at `qa.level: minimal` — no
- evidence is required, so untested criteria never escalate):
-
- - If **>50% of criteria are UNTESTED**: escalate to **BLOCKING** — test
- coverage is insufficient to confirm the story is actually done. The verdict
- in Phase 6 cannot be COMPLETE until coverage improves.
- - If **some (≤50%) criteria are UNTESTED**: remain ADVISORY — does not block
- completion, but must appear in Completion Notes.
- - If **all criteria are COVERED**: no action needed beyond including the
- table in the report.
-
-4. For any ADVISORY untested criteria, add to the Completion Notes in Phase 7:
- `"Untested criteria: [AC-N list]. Recommend adding tests in a follow-up story."`
-
-### Test Evidence Requirement
-
-**First apply `qa.level` (resolved in Phase 1).** At `minimal`, no *test*
-evidence is required — skip the Logic, Integration and Config/Data checks below.
-But still run the Visual/Feel and UI check and the `Run result:` check: the look
-is not waived at minimal, only the tests are. At `standard`, require evidence
-for the story's own type. At `full`, require evidence for every story type. The
-`testing.strict` resolution below applies to every check that runs.
-
-Based on the Story Type extracted in Phase 2, check for required evidence.
-
-**Resolve the gate level for this story's type.** A gate level is either
-BLOCKING (a gap prevents the COMPLETE verdict in Phase 6) or ADVISORY (a gap is
-noted in the Completion Notes but does not block). Resolve it from the
-`testing.strict` block **already resolved in the resolved-config block at the top of this skill** — not by reading
-`project.yaml` yourself:
-
-1. Map the Story Type to a `testing.strict` key — Logic→`logic`,
- Integration→`integration`, Visual/Feel→`visual`, UI→`ui`, Config/Data→`config`.
- Take `testing.strict.<key>` from that resolved block. If its value is `true`
- (case-insensitive) → BLOCKING; if `false` → ADVISORY; `unset` → fall through.
-2. Else read `testing.strict` as a plain boolean (legacy single-value form). If
- its value is `true` → BLOCKING or `false` → ADVISORY, it applies to every type.
-3. Else use the default in the table below.
-
-> **Use that resolved block, never `project.yaml` directly.** `testing.strict.*` is
-> on the `/settings --local` whitelist, so a developer can set
-> `testing.strict.logic=false` in `project.local.yaml` for fast WIP commits —
-> `effects-map.md` specifies exactly this ("stricter dev's local `/story-done`
-> blocks earlier"). Reading `project.yaml` alone silently ignores that file: the
-> setting is accepted, displayed by `/settings`, and has no effect. The
-> `resolve_config` block at the top of this skill already merges local over base.
-
-Only `true` and `false` (case-insensitive) are recognized at steps 1–2. A key
-that is present but holds any other value — `maybe`, `1`, `yes`, etc. — is
-treated as unset: continue to the next step, and surface the unrecognized value
-to the user.
-
-| Story Type | Required Evidence | Default Gate Level |
-|---|---|---|
-| **Logic** | Automated unit test in `tests/unit/[system]/` — must exist and pass (this skill verifies **existence**; see the note below Phase 3) | BLOCKING |
-| **Integration** | Integration test in `tests/integration/[system]/` OR playtest doc | BLOCKING |
-| **Visual/Feel** | Retained screenshot + sign-off in `production/qa/evidence/` | BLOCKING |
-| **UI** | Retained screenshot of each screen touched, in `production/qa/evidence/` | BLOCKING |
-| **Config/Data** | Smoke check pass report in `production/qa/smoke-*.md` | ADVISORY |
-
-The **Default Gate Level** column applies when `testing.strict` is unset (the
-common case). When `testing.strict` is configured, the resolved value from
-steps 1–2 overrides it. Visual/Feel and UI default to BLOCKING because for a
-game the rendered result is the product; set `testing.strict.visual` or
-`testing.strict.ui` to `false` for an advisory gate.
-
-> **Exception — `/smoke-check`.** The ADVISORY default for **Config/Data** above
-> governs *per-story evidence* gates, which is what this skill checks.
-> `/smoke-check` is a build-health gate, not a per-story evidence gate, so its own
-> unset default for `testing.strict.config` is **BLOCKING** — see
-> `.claude/skills/smoke-check/SKILL.md` § "Resolve the gate enforcement level".
-> The divergence is intentional; do not "fix" either side to match the other.
-
-> **This phase checks that evidence EXISTS. It does not run anything.** The
-> `Default Gate Level` table above, and `.claude/docs/coding-standards.md`, both
-> say a Logic story's test "must exist **and pass**". The checks below establish
-> only the first half — every one of them is a `Glob` or a `Grep`. A unit test
-> that exists and fails, or that contains no assertions, satisfies them.
->
-> Say which half you verified when you report. "Test file present at `<path>`"
-> is the honest claim; "tests pass" is not one this phase can make. Pass/fail is
-> established by `/gate-check` (runs the suite at a phase gate) and
-> `/smoke-check` (runs it before QA hand-off), both of which do execute.
->
-> Unlike `/regression-suite` and `/launch-checklist`, which stop at existence
-> and carry no general `Bash` pre-approval, this skill has `Bash` pre-approved —
-> the limit here is the instruction, not the grant (a pre-approval never
-> restricts). Running the story's own test before closing it is a live option;
-> it is not enabled because it needs a configured runner and a decision about
-> what a missing runner should mean.
-
-**For Logic stories**: first read the story's **Test Evidence** section to extract the
-exact required file path. Use `Glob` to check that exact path. If the exact path is not
-found, also search `tests/unit/[system]/` broadly (the file may have been placed at a
-slightly different location). If no test file is found at either location:
-- Flag at the resolved gate level: "Logic story has no unit test file. Story
- requires it at `[exact-path-from-Test-Evidence-section]`. Create and run the
- test before marking this story Complete."
-
-**For Integration stories**: read the story's **Test Evidence** section for the exact
-required path. Use `Glob` to check that exact path first, then search
-`tests/integration/[system]/` broadly, then check `production/session-logs/` for a
-playtest record referencing this story.
-If none found: flag at the resolved gate level (same rule as Logic).
-
-**For Visual/Feel and UI stories**: glob `production/qa/evidence/` for a
-retained screenshot for this story (`*.png`, `*.jpg`, `*.gif`) and for an
-evidence doc referencing it. What closes the story follows the evidence table
-in `.claude/docs/coding-standards.md`, the same at every `qa.level`:
-- A **UI** story is satisfied by the retained screenshot of each screen it
- touched. No evidence doc or sign-off is required; note one if it exists.
-- A **Visual/Feel** story also needs the sign-off: the evidence doc
- (`production/qa/evidence/[story-slug]-evidence.md`, from the test-evidence
- template) with every sign-off row `[x] Approved`.
-
-Flag at the resolved gate level:
-- No screenshot: "No visual evidence found. Capture a screenshot of each screen or effect this story touched and save it under `production/qa/evidence/` before final closure." For Visual/Feel add: "then record sign-off in `production/qa/evidence/[story-slug]-evidence.md` using the test-evidence template."
-- An evidence doc but no screenshot retained beside it: "Evidence doc found at `[path]` but no screenshot is retained. A described check is an assertion, not evidence — capture the screen and save the image under `production/qa/evidence/` before final closure."
-- Visual/Feel with a screenshot but no evidence doc: "Screenshot found but no sign-off is recorded. Create `production/qa/evidence/[story-slug]-evidence.md` using the test-evidence template and obtain sign-off before final closure."
-- Visual/Feel sign-off rows still unchecked — grep the doc for `| .* | .* | .* | \[ \] Approved`: "Evidence file found at `[path]` but [N] sign-off(s) are still pending (shown as `[ ] Approved` in the sign-off table). Obtain required sign-offs before final closure. Note: for solo developers, all roles may be signed off by the same person."
-
-Otherwise note "Retained screenshot found[, sign-offs complete] — gate satisfied."
-
-The retained image **is** the `Run result: OBSERVED` from `/dev-story` Phase 6
-step 4 (`.claude/docs/run-and-observe.md`); its absence means the run was
-`NOT VERIFIED` or never happened, and the flag above is the consequence. The
-run is not waived at `qa.level: minimal`.
-
-**For every other story type**, read the `Run result:` line from the
-`/dev-story` checkpoint in `production/session-state/active.md` — only when its
-**Current task** names this story; a later `/dev-story` overwrites it — or from
-the story's `## Completion Notes`. `OBSERVED` with a retained path: note
-it. `N/A — <reason>`: accept only if the reason names why nothing is
-observable — "it's a Logic story" is not a reason. `NOT VERIFIED — <reason>`
-on a story whose acceptance criteria name anything on screen: flag at the
-resolved gate level for the story's type. No `Run result:` line at all: flag
-as ADVISORY — "the implementation summary carries no run result; confirm the
-build was launched and looked at before closure." The exception: when the
-acceptance criteria name something on screen and no retained image for this
-story is under `production/qa/evidence/`, nothing observed the story — a user's
-`Yes — passes` to such a criterion is an assertion, not the retained observation
-`.claude/docs/run-and-observe.md` requires — so flag it at the resolved gate
-level for the story's type, as for `NOT VERIFIED`.
-
-**For Config/Data stories**: check for any `production/qa/smoke-*.md` file.
-If none: flag at the resolved gate level — "No smoke check report found. Run `/smoke-check`."
-
-**If no Story Type is set**: flag as **ADVISORY** —
-"Story Type not declared. Add `Type: [Logic|Integration|Visual/Feel|UI|Config/Data]`
-to the story header to enable test evidence gate enforcement in future stories."
-
-Any BLOCKING test evidence gap prevents the COMPLETE verdict in Phase 6.
-
----
diff --git a/.claude/skills/story-done/references/4-deviations.md b/.claude/skills/story-done/references/4-deviations.md
deleted file mode 100644
index 1149d6b8..00000000
--- a/.claude/skills/story-done/references/4-deviations.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# /story-done — Phases 4 and 4b: Deviations and QA Coverage Gate
-
-> Part of `/story-done`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 4: Check for Deviations
-
-Compare the implementation against the design documents.
-
-> **Workflow tier adjustment** (resolved in Phase 1, per the story's system).
-> Checks 1 (GDD rules) and 3 (ADR constraints) below are the `full` baseline:
-> - **`full`** — run both: full GDD traceability against the current TR text +
-> the ADR constraints check.
-> - **`standard`** — run the GDD rules check against the **5 required sections**;
-> run the ADR constraints check only where a **critical ADR** governs the story.
-> - **`minimal`** — **acceptance-criteria check only**: skip checks 1 and 3 (no
-> GDD/ADR traceability expected). Checks 2 (manifest), 4 (hardcoded values), and
-> 5 (scope) still run as written.
->
-> This adjustment governs only the Phase 4 *deviation* checks. The test-evidence
-> gates (Phase 3 traceability, Phase 4b QA coverage) are governed by `qa.level`
-> and `testing.strict`, not `workflow` — they run independently of the tier here.
-
-Run these checks automatically:
-
-1. **GDD rules check**: Using the current requirement text from `tr-registry.yaml`
- (looked up by the story's TR-ID), check that the implementation reflects what
- the GDD actually requires now — not what it required when the story was written.
- `Grep` the implemented files for key function names, data structures, or class
- names mentioned in the current GDD section.
-
-2. **Manifest version staleness check**: Compare the `Manifest Version:` date
- embedded in the story header against the `Manifest Version:` date in the
- current `docs/architecture/control-manifest.md` header.
- - If they match → pass silently.
- - If the story's version is older → flag as ADVISORY:
- `ADVISORY: Story was written against manifest v[story-date]; current manifest
- is v[current-date]. New rules may apply. Run /story-readiness to check.`
- - If control-manifest.md does not exist → skip this check.
-
-3. **ADR constraints check**: Use the ADR's `## Decision` section already
- loaded in Phase 2 — do not read the ADR file again. Check for forbidden
- patterns from `docs/architecture/control-manifest.md` (if it exists).
- `Grep` for patterns explicitly forbidden in the ADR.
-
-4. **Hardcoded values check**: `Grep` the implemented files for numeric literals
- in gameplay logic that should be in data files.
-
-5. **Scope check**: Did the implementation touch files outside the story's stated
- scope? (files not listed in "files to create/modify")
-
-For each deviation found, categorize:
-
-- **BLOCKING** — implementation contradicts the GDD or ADR (must fix before
- marking complete)
-- **ADVISORY** — implementation drifts slightly from spec but is functionally
- equivalent (document, user decides)
-- **OUT OF SCOPE** — additional files were touched beyond the story's stated
- boundary (flag for awareness — may be valid or scope creep)
-
----
-
-## Phase 4b: QA Coverage Gate
-
-**Skip this phase entirely at `qa.level: minimal`** (resolved in Phase 1) — no
-test evidence is required, so there is no coverage to review. Note: "QL-TEST-COVERAGE
-skipped — qa.level minimal." Proceed to Phase 5.
-
-**Review mode check** — apply before spawning QL-TEST-COVERAGE:
-- `solo` → skip. Note: "QL-TEST-COVERAGE skipped — Solo mode." Proceed to Phase 5.
-- `lean` → skip (not a PHASE-GATE). Note: "QL-TEST-COVERAGE skipped — Lean mode." Proceed to Phase 5.
-- `full` → spawn as normal.
-
-After completing the deviation checks in Phase 4, spawn `qa-lead` via `Agent` using gate **QL-TEST-COVERAGE** (`.claude/docs/director-gates/ql-test-coverage.md`).
-
-Pass:
-- The story file path and story type
-- Test file paths found during Phase 3 (exact paths, or "none found")
-- The story's `## QA Test Cases` section (the pre-written test specs from story creation)
-- The story's `## Acceptance Criteria` list
-- The GDD acceptance criteria and Edge Cases for the story's system, from the GDD
- section read in Phase 2 — or "no GDD for this system" when there is none (at
- `workflow: minimal` the story's own criteria are the spec); an absent GDD is
- information for the gate, not a missing input
-
-The qa-lead reviews whether the tests actually cover what was specified — not just whether files exist.
-
-Apply the verdict:
-- **ADEQUATE** → proceed to Phase 5
-- **GAPS** → flag as **ADVISORY**: "QA lead identified coverage gaps: [list]. Story can complete but gaps should be addressed in a follow-up story."
-- **INADEQUATE** → flag as **BLOCKING**: "QA lead: critical logic is untested. Verdict cannot be COMPLETE until coverage improves. Specific gaps: [list]."
-- **NOT ASSESSED [missing input]** → no judgement was made; never read it as ADEQUATE. Name the missing input — supply it and re-run the gate, or carry it to Phase 6, where it keeps the verdict at best NOT ASSESSED.
-
-Skip this phase for Config/Data stories (no code tests required).
-
----
diff --git a/.claude/skills/story-done/references/5-code-review-gate.md b/.claude/skills/story-done/references/5-code-review-gate.md
deleted file mode 100644
index f0565c55..00000000
--- a/.claude/skills/story-done/references/5-code-review-gate.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# /story-done — Phase 5: Lead Programmer Code Review Gate
-
-> Part of `/story-done`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 5: Lead Programmer Code Review Gate
-
-**Review mode check** — apply before spawning LP-CODE-REVIEW:
-- `solo` → skip. Note: "LP-CODE-REVIEW skipped — Solo mode." Proceed to Phase 6 (completion report).
-- `lean` → use `AskUserQuestion` before proceeding:
- - Prompt: "Code review is skipped in lean mode. Did you run `/code-review` on the implemented files?"
- - Options:
- - `Yes — /code-review passed or was approved with suggestions`
- - `No — skipping code review for this story`
- - `No — I'll run /code-review before the sprint close-out`
- - Record the answer in the completion notes (Phase 7). All three options proceed to Phase 6.
-- `full` → spawn as normal.
-
-Spawn `lead-programmer` via `Agent` using gate **LP-CODE-REVIEW** (`.claude/docs/director-gates/lp-code-review.md`).
-
-Pass: implementation file paths, story file path, relevant GDD section, governing ADR.
-
-Present the verdict to the user. If CONCERNS, surface them via `AskUserQuestion`:
-- Options: `Revise flagged issues` / `Accept and proceed` / `Discuss further`
-If REJECT, do not proceed to Phase 6 verdict until the issues are resolved.
-If NOT ASSESSED, name the input the gate said was missing and never treat it as APPROVE: supply it and re-run the gate, or carry it to Phase 6, where it keeps the verdict at best NOT ASSESSED.
-
-If the story has no implementation files yet (verdict is being run before coding is done), skip this phase and note: "LP-CODE-REVIEW skipped — no implementation files found. Run after implementation is complete."
-
----
diff --git a/.claude/skills/story-done/references/6-completion-report.md b/.claude/skills/story-done/references/6-completion-report.md
deleted file mode 100644
index d06f5011..00000000
--- a/.claude/skills/story-done/references/6-completion-report.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# /story-done — Phase 6: Present the Completion Report
-
-> Part of `/story-done`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 6: Present the Completion Report
-
-**In this file:**
-
-- The completion report template
-- Verdict definitions
-- `NOT ASSESSED` and verdict precedence
-
-Before updating any files, present the full report:
-
-```markdown
-## Story Done: [Story Name]
-**Story**: [file path]
-**Date**: [today]
-
-### Acceptance Criteria: [X/Y passing]
-- [x] [Criterion 1] — auto-verified (test file present)
-- [x] [Criterion 2] — confirmed
-- [ ] [Criterion 3] — FAILS: [reason]
-- [?] [Criterion 4] — DEFERRED: requires playtest
-
-### Test-Criterion Traceability
-| Criterion | Test | Status |
-|-----------|------|--------|
-| AC-1: [text] | [test file::test name] | COVERED |
-| AC-2: [text] | Manual confirmation | COVERED |
-| AC-3: [text] | — | UNTESTED |
-
-### Test Evidence
-**Story Type**: [Logic | Integration | Visual/Feel | UI | Config/Data | Not declared]
-**Required evidence**: [unit test file | integration test or playtest | screenshot + sign-off | screenshot of each screen touched | smoke check pass]
-**Evidence found**: [YES — `[path]` | NO — BLOCKING | NO — ADVISORY]
-
-### Deviations
-[NONE] OR:
-- BLOCKING: [description] — [GDD/ADR reference]
-- ADVISORY: [description] — user accepted / flagged for tech debt
-
-### Scope
-[All changes within stated scope] OR:
-- Extra files touched: [list] — [note whether valid or scope creep]
-
-### Verdict: COMPLETE / COMPLETE WITH NOTES / NOT ASSESSED / BLOCKED
-```
-
-**Verdict definitions:**
-- **COMPLETE**: all criteria pass, no blocking deviations
-- **COMPLETE WITH NOTES**: every criterion passes or is `DEFERRED` (Phase 3 —
- evaluable, awaiting a playtest), with advisory deviations or deferred criteria
- documented — list each DEFERRED criterion so it is not lost
-- **NOT ASSESSED**: one or more acceptance criteria could not be evaluated at
- all — name which, and why
-- **BLOCKED**: failing criteria or blocking deviations must be resolved first
-
-**`NOT ASSESSED` — the story nobody could verify.** Rank: it **outranks COMPLETE
-and COMPLETE WITH NOTES** (a review that could not evaluate a criterion has not
-shown the criterion is met) and **ranks below BLOCKED** (a criterion known to
-fail is more actionable than one nobody could check, and demoting it would bury
-it). It is not a gentler BLOCKED: "this acceptance criterion fails" and "I could
-not tell whether it passes" send the reader to different fixes.
-
-**Verdict precedence — first matching rule wins**, evaluated in this order:
-**BLOCKED**, then **NOT ASSESSED**, then **COMPLETE WITH NOTES**, then
-**COMPLETE**. A run with both a failing criterion and an unassessable one is
-BLOCKED. Stating the order mechanically, rather than leaving it to be inferred
-from the rank sentence, is what keeps two reviewers from grading the same story
-differently.
-
-Emit it when any of:
-
-- An acceptance criterion **cannot be evaluated at all** — it names no observable
- outcome, so no evidence could settle it either way.
- > **Not the same as Phase 3's `DEFERRED`.** A criterion that is evaluable but
- > needs a playtest is `DEFERRED — requires playtest session`, it does **not**
- > block, and Phase 3 keeps ownership of it. This trigger is for a criterion no
- > session could ever settle as written. If Phase 3 already marked it DEFERRED,
- > that classification stands and this trigger does not fire.
-- A criterion the user answered **`Not tested yet`** (Phase 3) — it could be
- checked, but nobody has. Name it and what would settle it: launch the build,
- check it, then re-run `/story-done`.
-- QL-TEST-COVERAGE or LP-CODE-REVIEW returned **NOT ASSESSED** and the input it
- named was not supplied.
-- The **test evidence is present but unreadable or unclassifiable** — corrupt,
- empty, or of a type that cannot be determined.
- > **Absent evidence is Phase 3's, not this trigger's.** Phase 3 resolves a
- > missing file through `testing.strict`: BLOCKING types produce **BLOCKED**,
- > ADVISORY types produce **COMPLETE WITH NOTES**. Both outrank or are already
- > decided, so re-routing "absent" here would silently override an explicit
- > advisory ruling. *Unreadable* is the genuinely unassessable case, and it is
- > the only one this trigger claims.
-- **`/test-evidence-review` returned `NOT ASSESSED`** for this story — applicable
- only when that skill was actually run against it, which this skill does not do
- itself. It
- propagates: that skill's whole point is that "could not check" is not
- "checked and fine", and collapsing its unknown into a COMPLETE here would undo
- the distinction one skill downstream. `coding-standards.md` marks Logic and
- Integration evidence BLOCKING, so this is the path where an unverifiable story
- would otherwise acquire a verdict saying somebody verified it.
-- A **deviation's severity cannot be determined** because the GDD or ADR it
- would be judged against is missing.
-
-A `NOT ASSESSED` verdict takes the same Phase 7 path as BLOCKED: do not
-automatically proceed, list what could not be checked and what would make it
-checkable. Closing anyway remains the user's explicit call, and stays gated by
-Phase 7's `scope_changes` always-ask rule.
-
-If the verdict is **BLOCKED**: do not *automatically* proceed to Phase 7. List
-what must be fixed and offer to help fix the blocking items. This is the
-default path, not an absolute stop — the user may still explicitly ask to
-close the story anyway despite the blockers. That request is what routes to
-Phase 7's menu below, and Phase 7's own `scope_changes` always-ask rule is
-exactly what stands between that request and a silent close in autonomous
-mode. Do not treat "do not automatically proceed" as "Phase 7 is now
-unreachable" — it is reachable, on request, and gated when reached.
-
----
diff --git a/.claude/skills/story-done/references/7-update-status.md b/.claude/skills/story-done/references/7-update-status.md
deleted file mode 100644
index c0f059ec..00000000
--- a/.claude/skills/story-done/references/7-update-status.md
+++ /dev/null
@@ -1,95 +0,0 @@
-# /story-done — Phase 7: Update Story Status
-
-> Part of `/story-done`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 7: Update Story Status
-
-**Reached one of two ways**: normally, immediately after a COMPLETE or
-COMPLETE-WITH-NOTES verdict in Phase 6; or, after a BLOCKED **or NOT ASSESSED**
-verdict, only if the user explicitly asks to close the story despite the
-blockers (Phase 6 does not advance here on its own in either case).
-
-**Automation note**: This is the story-completion gate. Closing a story whose
-verdict is BLOCKED (failing acceptance criteria) **or NOT ASSESSED** (criteria
-nobody could evaluate) — the "Accept deviations as-is and close anyway" option —
-is a `scope_changes` decision. Call
-`is_always_ask_category scope_changes`; when it returns 0 (the default), this
-gate prompts via `AskUserQuestion` **regardless of `modes.automation`** —
-autonomous mode must NOT silently close a BLOCKED story, even when the user's
-own request is what got you here. For a COMPLETE or COMPLETE-WITH-NOTES
-verdict, autonomous mode may pick "Close the story (Recommended)" and record
-it via `log_decision`.
-
-Use `AskUserQuestion` before writing anything:
-- Prompt: "Verification complete. How do you want to proceed?"
-- Options:
- - `Close the story — update file, mark Complete, log notes (Recommended)`
- - `Close and log advisory deviations as tech debt in docs/tech-debt-register.md`
- - `There are issues I want to fix first — don't close yet`
- - `Accept deviations as-is and close anyway`
-
-If "Close", "Close and log tech debt", or "Accept deviations": edit the story file.
-If "Close and log tech debt": after updating the story file, also append the advisory deviations to `docs/tech-debt-register.md` (create the file if it does not exist).
-If "Fix first": stop here and list what the user flagged. Do not write any files.
-
-1. Update the status field: `Status: Complete`
-2. Update the `Last Updated:` field in the story header to today's date (format: `YYYY-MM-DD`). If the field does not exist, add it after the `Status:` line.
-3. Add a `## Completion Notes` section at the bottom:
-
-```markdown
-## Completion Notes
-**Completed**: [date]
-**Criteria**: [X/Y passing] ([any deferred items listed])
-**Deviations**: [None] or [list of advisory deviations]
-**Test Evidence**: [Logic: test file at path | Visual/Feel: evidence doc at path | None required (Config/Data)]
-**Code Review**: [Pending / Complete / Skipped]
-```
-
-4. If the user chose "Close and log tech debt": append each advisory deviation to `docs/tech-debt-register.md` as one row of `/tech-debt`'s register table — the format under "Debt Register Format" in `.claude/skills/tech-debt/SKILL.md` — so `/tech-debt report` can date it from its `Added` column:
- ```
- | TD-[next free NNN] | [category] | [deviation description] — from [story file path] | [files] | [S/M/L/XL] | [Low/Med/High/Critical] | — | Open | [YYYY-MM-DD] | Backlog |
- ```
- Category is one of `/tech-debt`'s six (Architecture, Code Quality, Test, Documentation, Dependency, Performance); Effort and Impact are your estimate from the deviation; Priority stays `—` until `/tech-debt prioritize` scores it; `Added` is today. If the file does not exist, create it with that format's heading, `Last updated:` and `Total items:` lines and table header; if it exists, update those two lines (and add the table header first if the file has none yet).
-
-5. **Update `production/sprint-status.yaml`** (if it exists):
- - Find the entry matching this story's file path or ID
- - Set `status: done` and `completed: [today's date]`
- - Update the top-level `updated` field
- - This is a silent update — no extra approval needed (already approved in step above)
-
-6. **Suggest a git commit**: Output a ready-to-use commit command covering the implementation files from the dev-story summary and the updated story file:
-
-```
-Suggested commit:
-git add [code-root and test-root files changed during implementation] [story-file-path]
-git commit -m "feat: [story title] ([TR-ID])"
-```
-
-The `validate-commit.sh` hook blocks invalid data JSON and warns on hardcoded gameplay values and TODOs without an owner. It does not read the commit message: the story and design references go there from you.
-
-### Session State Update
-
-After updating the story file, silently update the checkpoint in
-`production/session-state/active.md` — **overwrite the `<!-- CHECKPOINT -->` …
-`<!-- /CHECKPOINT -->` block, never append** (schema:
-`.claude/docs/templates/session-state.md`). `session-start.sh` shows exactly
-that block when the next session opens. Fill **Next step** from Phase 8, so it
-names the same next story the user is shown:
-
- <!-- CHECKPOINT -->
- **Updated:** [date]
- **Branch:** `[current git branch]`
- **Current task:** /story-done — [story file path] closed: [COMPLETE / COMPLETE WITH NOTES / NOT ASSESSED / BLOCKED]
- **Next step:** [/story-done [next story path] for an In Review story, else /dev-story [next story path] — or "build order done: play the build" — or the blocker to clear when every unfinished story is blocked — or the sprint's next step]
- **Blocked on:** [nothing, or what blocked this verdict]
- **Files in progress:** none
- **Open questions:** [tech debt logged: N items, or none]
- <!-- /CHECKPOINT -->
-
-If `active.md` does not exist, create it from the template. If it exists with no
-markers (a file from before the schema), insert the template's STATUS and
-CHECKPOINT blocks at the top and leave the rest untouched.
-Confirm in conversation: "Session state updated."
-
----
diff --git a/.claude/skills/story-done/references/8-next-story.md b/.claude/skills/story-done/references/8-next-story.md
deleted file mode 100644
index f624fe68..00000000
--- a/.claude/skills/story-done/references/8-next-story.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# /story-done — Phase 8: Surface the Next Story
-
-> Part of `/story-done`. `SKILL.md` names when to read this file; the settings it
-> resolved and the rules under its later headings still apply here.
-
-## Phase 8: Surface the Next Story
-
-**In this file:**
-
-- No sprint plan — the minimal path
-- With a sprint plan
-
-After completion, help the developer keep momentum. Which branch applies depends
-on whether there is a sprint at all.
-
-### No sprint plan — the minimal path
-
-**At `workflow: minimal`, or whenever `production/sprints/` holds no sprint
-plan, there is no sprint to close out.** The brief's build order is the plan and
-the story files carry it:
-
-1. Run `bash .claude/scripts/story-status.sh`, from the project root — after
- Phase 7's story-file write, so this story's new status is in it. It prints
- every unfinished story under `production/epics/`, whatever Status form its
- file uses, **already in the route's order** — `IN_REVIEW`, then `IN_PROGRESS`, then `TODO` (a `Ready` or
- `Not Started` story) in build (file-name) order — then `BLOCKED`, `OTHER`,
- `NO_STATUS` and the `COMPLETE` count. It is the list `/help` and
- `/sprint-status` read, so the three name the same next story; do not re-read
- or re-rank the story files.
-2. The first `In Review` story is next (recommend `/story-done [path]` for it —
- its work is written, and closing it first keeps finished work from piling
- up); else the first `In Progress` one; else the first `Ready` or
- `Not Started` one — the story on the script's first `IN_REVIEW`,
- `IN_PROGRESS` or `TODO` line. Name any `Blocked` story with its blocker and pass
- over it.
-
- ```
- ### Next Up
- **[Story NNN: title]** — [1-line description]
- Run `/story-done [path]` to close it (In Review) — else `/dev-story [path]` to implement it.
- ```
-
- At `minimal` recommend `/dev-story` directly (or `/story-done` for an In Review
- story) — `/story-readiness` is not on
- the minimal path (engine → brief → stories → code), and it checks fields the
- minimal story template does not carry. With no sprint plan at a higher tier,
- add the `/story-readiness [path]` line from the sprint branch below.
-3. **No unfinished story — only `COMPLETE N of N`** → every story is built —
- at `minimal`, the brief's build order is done. Say so, and offer three ways on:
- - play the build and note what feels wrong
- - add the next stories from the brief with `/create-stories`
- - if the game has outgrown a one-page brief, `/settings` to raise `modes.rigor`
-4. **No `IN_REVIEW`, `IN_PROGRESS` or `TODO` line, but `BLOCKED`, `OTHER` or
- `NO_STATUS` lines remain** — every unfinished story is `Blocked`, `Draft`, or
- has no status line. There is no Next Up, and the
- build order is **not** done — never say it is. Name each such story with its
- blocker (or `Draft` / `no status`), and suggest clearing the blocker first. For
- a Draft or unstatused story: at `minimal`, finish it and set its Status to
- `Ready`; at a higher tier, `/story-readiness [path]` shows what it still needs.
-
-**Never print the Sprint Close-Out Sequence on this branch** (`/smoke-check
-sprint`, `/team-qa sprint`, `/retrospective`, `/gate-check`, `/sprint-plan new`)
-— it closes a sprint, and there is none. Each of those still runs if the user
-asks for it; do not present them as required.
-
-### With a sprint plan
-
-1. Read the current sprint plan from `production/sprints/`.
-2. Find stories that are:
- - Status: READY or NOT STARTED
- - Not blocked by other incomplete stories
- - In the Must Have or Should Have tier
-
-Present:
-
-```
-### Next Up
-The following stories are ready to pick up:
-1. [Story name] — [1-line description] — Est: [X hrs]
-2. [Story name] — [1-line description] — Est: [X hrs]
-
-Run `/story-readiness [path]` to confirm a story is implementation-ready
-before starting.
-```
-
-If no more Must Have stories remain in this sprint (all are Complete or Blocked):
-
-```
-### Sprint Close-Out Sequence
-
-All Must Have stories are complete. QA sign-off is required before advancing.
-Run these in order:
-
-1. `/smoke-check sprint` — verify the critical path still works end-to-end
-2. `/team-qa sprint` — full QA cycle: test case execution, bug triage, sign-off report
-3. `/retrospective` — capture what went well, what didn't, and action items for the next sprint
-4. `/gate-check` — advance to the next phase once QA approves (only if advancing a phase)
-5. `/sprint-plan new` — plan the next sprint, incorporating velocity data and retrospective action items
-
-Do not run `/gate-check` until `/team-qa` returns APPROVED or APPROVED WITH CONDITIONS.
-```
-
-If there are Should Have stories still unstarted, surface them alongside the close-out sequence so the user can choose: close the sprint now, or pull in more work first.
-
-If no more stories are ready but Must Have stories are still In Progress (not Complete):
-"No more stories ready to start — [N] Must Have stories still in progress. Continue implementing those before sprint close-out."
-
----
diff --git a/.claude/skills/story-done/references/review-gates.md b/.claude/skills/story-done/references/review-gates.md
new file mode 100644
index 00000000..371e6e39
--- /dev/null
+++ b/.claude/skills/story-done/references/review-gates.md
@@ -0,0 +1,53 @@
+# Phase 6: Review gates at review mode full
+
+Read only when the `review_gate` line says `skill-gates=run`. Run both gates before
+the Phase 7 report. Each agent reads its own gate file; do not read it here.
+
+## QL-TEST-COVERAGE
+
+Skip it at `qa.level: minimal` (note `QL-TEST-COVERAGE skipped — qa.level minimal`)
+and for a Config/Data story (no code tests).
+
+Hand the review to the `qa-lead` agent with gate **QL-TEST-COVERAGE**. Brief:
+
+- **Objective:** judge whether the story's tests cover what was specified, not
+ only whether the files exist.
+- **Give it:** the story path and type; the test files Phase 4 found (exact paths,
+ or "none found"); the story's `## QA Test Cases` and `## Acceptance Criteria`;
+ the GDD's acceptance criteria and edge cases for the system, or "no GDD for this
+ system" (at `workflow: minimal` the story's own criteria are the spec).
+- **Return:** ADEQUATE, GAPS, INADEQUATE, or NOT ASSESSED naming a missing input,
+ with the gaps listed.
+- **Boundaries:** it writes no file.
+
+Act on the verdict:
+
+- **ADEQUATE:** go on.
+- **GAPS:** ADVISORY — "QA lead found coverage gaps: [list]. The story can close;
+ address them in a follow-up story."
+- **INADEQUATE:** BLOCKING — "critical logic is untested: [list]."
+- **NOT ASSESSED:** never ADEQUATE. Supply the input and run it again, or carry it
+ to the verdict, where it keeps the story at best NOT ASSESSED.
+
+## LP-CODE-REVIEW
+
+No implementation file yet: skip it, note `LP-CODE-REVIEW skipped — no
+implementation files found`, and Reviewed by is `self, no independent review`.
+
+Hand the review to the `lead-programmer` agent with gate **LP-CODE-REVIEW**. Brief:
+
+- **Objective:** review the story's implementation against its GDD section and
+ governing ADR.
+- **Give it:** the implementation file paths, the story path, the GDD path and
+ section, the ADR path. It reads the GDD and ADR by section, never whole.
+- **Return:** APPROVE, CONCERNS, REJECT, or NOT ASSESSED naming a missing input.
+- **Boundaries:** it edits no file.
+
+Act on the verdict:
+
+- **APPROVE:** Reviewed by is `lead-programmer`.
+- **CONCERNS:** ask: "The lead programmer raised concerns. How do you want to go
+ on?" Options: Revise the flagged issues / Accept and go on / Discuss further.
+- **REJECT:** no COMPLETE verdict until the issues are fixed.
+- **NOT ASSESSED:** never APPROVE. Supply the input and run it again, or carry it
+ to the verdict, where it keeps the story at best NOT ASSESSED.
diff --git a/.claude/skills/story-done/references/sprint-next.md b/.claude/skills/story-done/references/sprint-next.md
new file mode 100644
index 00000000..3d061300
--- /dev/null
+++ b/.claude/skills/story-done/references/sprint-next.md
@@ -0,0 +1,38 @@
+# Phase 8: The next story when a sprint plan exists
+
+Read only when `production/sprints/` holds a sprint plan.
+
+1. Read the newest sprint plan in `production/sprints/`.
+2. Find the stories that are Ready or Not Started, not waiting on an unfinished
+ story, and in the Must Have or Should Have tier.
+
+```
+### Next Up
+The following stories are ready to pick up:
+1. [Story name] — [one line] — Est: [estimate]
+2. [Story name] — [one line] — Est: [estimate]
+
+Run `/story-readiness [path]` to confirm a story is ready before starting.
+```
+
+**Every Must Have story Complete or Blocked:** print the close-out sequence.
+
+```
+### Sprint Close-Out Sequence
+All Must Have stories are complete. QA sign-off is required before advancing.
+1. `/smoke-check sprint` — the critical path still works end to end
+2. `/team-qa sprint` — test case execution, bug triage, sign-off report
+3. `/retrospective` — what went well, what didn't, action items
+4. `/gate-check` — only when advancing a stage, after `/team-qa` returns
+ APPROVED or APPROVED WITH CONDITIONS
+5. `/sprint-plan new` — the next sprint
+```
+
+Should Have stories still unstarted: list them beside the sequence, so the user can
+close the sprint now or pull in more work.
+
+**No story ready, Must Have stories still In Progress:** "No more stories ready to
+start — [N] Must Have stories still in progress. Finish those before the sprint
+close-out."
+
+The checkpoint's **Next step** names the same story or step the user is shown.
diff --git a/.claude/skills/story-done/references/tech-debt-row.md b/.claude/skills/story-done/references/tech-debt-row.md
new file mode 100644
index 00000000..2f3975ce
--- /dev/null
+++ b/.claude/skills/story-done/references/tech-debt-row.md
@@ -0,0 +1,30 @@
+# Phase 7: Logging advisory deviations as tech debt
+
+Read only when the user picks "Close and log the advisory deviations as tech debt".
+
+Add one row per advisory deviation to `docs/tech-debt-register.md`, in the table
+`/tech-debt` keeps, so `/tech-debt report` can date it from its `Added` column:
+
+```
+| TD-[next free NNN] | [category] | [deviation] — from [story path] | [files] | [S/M/L/XL] | [Low/Med/High/Critical] | — | Open | [YYYY-MM-DD] | Backlog |
+```
+
+- **ID:** one above the highest TD number already in the file, three digits;
+ `TD-001` in a new file.
+- **Category:** one of Architecture, Code Quality, Test, Documentation, Dependency,
+ Performance.
+- **Effort and Impact:** your estimate from the deviation.
+- **Priority:** `—` until `/tech-debt prioritize` scores it.
+- **Added:** today.
+
+The file starts with a `## Technical Debt Register` heading, a `Last updated:
+[date]` line, a `Total items: [N] | Estimated total effort: [sizes summed]` line and
+the table header:
+
+```
+| ID | Category | Description | Files | Effort | Impact | Priority | Status | Added | Sprint |
+|----|----------|-------------|-------|--------|--------|----------|--------|-------|--------|
+```
+
+When the file does not exist, create it that way. When it does, update those two
+lines, and add the table header first if it has none.
diff --git a/.claude/skills/story-readiness/CONTRACT.md b/.claude/skills/story-readiness/CONTRACT.md
index ecd1bbbe..f64da98f 100644
--- a/.claude/skills/story-readiness/CONTRACT.md
+++ b/.claude/skills/story-readiness/CONTRACT.md
@@ -13,10 +13,10 @@ implementation and produces a READY / NEEDS WORK / BLOCKED / NOT ASSESSED verdic
| `production/epics/[epic-slug]/story-NNN-[slug].md` | All header fields (`Status:`, `Layer:`, `Type:`, `Manifest Version:`), `## Context` (GDD path, TR-ID, ADR reference, Engine Notes, Control Manifest Rules), `## Acceptance Criteria`, `## Test Evidence`, `## Dependencies`, `## Out of Scope` | Yes |
| `docs/architecture/control-manifest.md` | `Manifest Version:` date in header, layer rules | Yes (if exists) |
| `docs/architecture/tr-registry.yaml` | `id`, `status` fields per TR entry | Yes (if exists) |
-| `docs/architecture/adr-NNNN-[slug].md` (all ADRs referenced in stories) | `Status:` field | Yes |
-| `design/gdd/systems-index.md` | Which systems have approved GDDs | Yes |
+| `docs/architecture/adr-NNNN-[slug].md` (all ADRs referenced in stories) | `## Status`, the `**Layer**` row (read through `adr-status.sh`) | Yes |
+| `production/sprint-status.yaml` | `file:` entries (for `sprint` scope, read through `story-facts.sh --sprint`) | Yes (if exists) |
-> **Tier.** The manifest, TR registry, ADR and systems-index rows are
+> **Tier.** The manifest, TR registry and ADR rows are
> `standard`/`full` inputs. At `workflow: minimal` the skill is not on the path
> (`/dev-story` follows `/create-stories` directly); run anyway, it checks
> acceptance criteria and scope only and treats Architecture Completeness as N/A
@@ -26,7 +26,7 @@ implementation and produces a READY / NEEDS WORK / BLOCKED / NOT ASSESSED verdic
### Preconditions
- The story file being validated was produced by `/create-stories` (or follows the same format)
-- For `sprint` scope: a sprint file exists in `production/sprints/` with story path references
+- For `sprint` scope: `production/sprint-status.yaml` exists and lists story paths in its `file:` entries
- For `all` scope: `production/epics/` directory exists and contains story files
## Outputs Produced
@@ -39,18 +39,18 @@ None. This skill is strictly read-only and produces no file modifications under
- Every non-READY verdict includes a specific gap list with fix instructions for each failing checklist item
- Every BLOCKED verdict names the specific blocker (missing dependency story path, Proposed ADR ID, or unresolved design question marker)
- For `sprint` scope: a sprint-level escalation warning is prepended if any Must Have story is not READY (NEEDS WORK, BLOCKED or NOT ASSESSED)
-- The skill offers to draft missing sections in conversation but never uses Write or Edit tools
+- The skill offers to draft missing sections in conversation but never writes or edits a file
## Immutability Rules
-- READS but does NOT modify: story files, `docs/architecture/control-manifest.md`, `docs/architecture/tr-registry.yaml`, all ADR files, `design/gdd/systems-index.md`, sprint files, any referenced asset files (existence-only Glob checks)
+- READS but does NOT modify: story files, `docs/architecture/control-manifest.md`, `docs/architecture/tr-registry.yaml`, all ADR files, sprint files, any referenced asset files (existence only)
- MODIFIES: nothing
## Hard Constraints (Never Violate)
-- Never use Write or Edit tools under any circumstances
+- Never write or edit a file under any circumstances
- Never draft corrections directly into files — offer drafts in conversation only
- Never mark a story READY if its governing ADR has `Status: Proposed`, `Deprecated` or `Superseded`, at any tier
- Never mark a story READY if a dependency story file is missing or has `Status: Draft`
-- Never re-read the same ADR file multiple times in one run — cache ADR statuses after the first read
+- Never re-read ADR statuses per story — one `adr-status.sh` call serves the run
- Never penalize a story for missing `Manifest Version:` if `control-manifest.md` does not exist
- Never penalize a story for missing TR-ID if `tr-registry.yaml` does not exist
@@ -62,7 +62,7 @@ It will rely on this skill's verdict as follows:
- If verdict is NEEDS WORK, BLOCKED or NOT ASSESSED: `/dev-story` must not be run until the story is corrected (or, for NOT ASSESSED, made readable) and re-validated — a story nobody could evaluate has not been shown ready
- `/dev-story` reads the same story fields this skill validates — a READY verdict is an implicit guarantee that those fields are present, parseable, and internally consistent:
- `Type:` field is set to a valid story type
- - `## Acceptance Criteria` contains specific, testable checkbox items
+ - `## Acceptance Criteria` contains specific, testable checkbox items, at least the minimum for the story's type at the project's `story_granularity` (coarse 3/2/1, balanced 2/2/1, fine 1)
- `## Test Evidence` specifies a concrete evidence path
- The governing ADR exists and has `Status: Accepted`
- `Manifest Version:` matches the current control manifest
@@ -74,6 +74,6 @@ It will rely on this skill's verdict as follows:
- If `control-manifest.md` is regenerated with a new `Manifest Version:` date, every story that embeds the old date will fail the manifest version check — a bulk update of all story `Manifest Version:` fields is required before stories can pass readiness again
- If an ADR is silently renamed or moved after stories reference it by ID, the ADR file-existence check will BLOCK those stories even though the decision content is unchanged
- The manifest version comparison is a string date match, not a semantic version comparison — if the date format changes (e.g., from `2026-01-15` to `Jan 15 2026`), all stories will fail the check regardless of actual currency
-- Asset existence checks use Glob — on Windows, path separator mismatches (`\` vs `/`) may cause a Glob miss that incorrectly flags an asset as missing
+- Asset existence checks match paths — on Windows, path separator mismatches (`\` vs `/`) may cause a miss that incorrectly flags an asset as missing
- The TR-ID status check auto-passes if the registry does not exist, which means stories written before TR tracking was introduced will always pass this check even if they contain invalid or placeholder IDs like `TR-[system]-???`
-- For `sprint` scope, the skill depends on sprint file formatting to extract story paths — if the sprint file format changes, story paths may not be parsed and the scope silently reduces to zero stories validated
+- For `sprint` scope, the skill depends on sprint file formatting to extract story paths; if the sprint file format changes, story paths may not be parsed; the run then reports `NOT ASSESSED — no stories in scope` rather than a clean summary
diff --git a/.claude/skills/story-readiness/SKILL.md b/.claude/skills/story-readiness/SKILL.md
index f2f15da8..56935cf9 100644
--- a/.claude/skills/story-readiness/SKILL.md
+++ b/.claude/skills/story-readiness/SKILL.md
@@ -1,375 +1,235 @@
---
name: story-readiness
-description: "Is a story implementation-ready? Checks clear acceptance criteria, open questions, ADR refs. READY/NEEDS WORK/BLOCKED/NOT ASSESSED."
+description: "Checks whether a story is ready to implement: clear acceptance criteria, no open questions, valid ADR and dependencies. Use when the user asks if a story, or the sprint's stories, are ready to start or build."
argument-hint: "[story-file-path or 'all' or 'sprint'] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/story-readiness/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/story-readiness/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/story-facts.sh *), Bash(bash .claude/scripts/adr-status.sh *)
model: sonnet
---
-!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,qa.level,testing.strict,system_overrides`
+!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,workflow,qa.level,gate_level,story_granularity,system_overrides`
Resolved above — use as-is; `--review` overrides `review_mode`. No block →
defaults in `.claude/docs/config-resolution.md`.
+Ask with the question tool. Without one, list the options numbered and end your turn
+to wait. A skipped or dismissed question is not an answer: ask again in plain text.
# Story Readiness
-This skill validates that a story file contains everything a developer needs
-to begin implementation — no mid-sprint design interruptions, no guessing,
-no ambiguous acceptance criteria. Run it before assigning a story.
-
-**This skill is read-only.** It never edits story files. It reports findings
-and asks whether the user wants help filling gaps.
-
-**Output:** Verdict per story (READY / NEEDS WORK / BLOCKED / NOT ASSESSED) with a specific
-
-> **`NOT ASSESSED` is not a synonym for `BLOCKED`.** `BLOCKED` is a
-> finding about the story — a Proposed ADR, an ADR file it names that does not
-> exist, an unresolved dependency — and it tells the reader exactly what to clear.
-> Use `NOT ASSESSED` when the story could not be evaluated at all: the file is
-> unreadable or unparseable, a referenced ADR exists but has no readable
-> `## Status` (malformed), or a referenced design document cannot be located, so
-> the checks below cannot run. Collapsing that into `BLOCKED` reports a blocker
-> that does not exist and hides the one that does — the reader chases a phantom
-> blocker instead of the unreadable file.
-> `READY` must never be reachable for a story that was not actually evaluated.
->
-> **Precedence — first matching rule wins**, in this order: **BLOCKED**, then
-> **NEEDS WORK**, then **NOT ASSESSED**, then **READY**. `NOT ASSESSED` outranks
-> `READY` (a story that could not be evaluated has not been shown ready) and
-> ranks **below** both failure verdicts (a known blocker is more actionable than
-> an unknown, and demoting it behind an access problem buries it). A story with
-> both a real blocker and an unevaluable check is `BLOCKED` — the blocker is the
-> actionable finding. This half of the rank has to be stated: the rule above
-> establishes only that `READY` is unreachable, which would leave the ordering
-> against `BLOCKED` to inference.
-gap list for each non-ready story.
-
----
-
-## Phase 0: Resolve Review Mode
-
-
-See `.claude/docs/director-gates.md` for the full check pattern and mode definitions. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.
-
-
-Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
-(collaborative asks always · guided major-only · autonomous logs and proceeds;
-`automation_always_ask` categories always prompt).
-
-**Resolve the workflow tier per story** (per `.claude/docs/workflow-modes.md`):
-for the system a story belongs to (**the GDD filename stem** of its `GDD:` path;
-the `[system]` segment of a `TR-[system]-NNN` ID is a fallback alias only), use the
-`system_overrides` row for that system if the block lists one, else the
-project value. When validating multiple stories (`all` / `sprint` scope),
-resolve **per story** — different systems may sit at different tiers. The tier
-sets which checklist sections block — see the note in Section 3.
-
-**`qa.level`**: controls whether a test requirement is
-validated. At `minimal`, the "Test evidence requirement is clear" item
-auto-passes (no requirement validated); at `standard`, validate the per-type test
-requirement (strictness from `testing.strict`); at `full`, also validate a
-coverage target. Distinct axis from `workflow`. **UI and Visual/Feel stories are
-the exception at `minimal`:** their retained screenshot is required at every
-`qa.level`, so for them the item is still validated — the tests are waived, the
-look is not.
-
----
-
-## 1. Parse Arguments
-
-**Scope:** `$ARGUMENTS` with any `--review <mode>` pair removed (blank = ask user via AskUserQuestion). What remains is one value — a path may contain spaces.
-
-- **Specific path** (e.g., `/story-readiness production/epics/combat/story-001-basic-attack.md`):
- validate that single story file.
-- **`sprint`**: read the current sprint plan from `production/sprints/` (most
- recent file), extract every story path it references, validate each one.
-- **`all`**: glob `production/epics/**/*.md`, exclude `EPIC.md` index files,
- validate every story file found.
-- **No argument**: ask the user which scope to validate.
-
-If no argument is given, use `AskUserQuestion`:
-- "What would you like to validate?"
- - Options: "A specific story file", "All stories in the current sprint",
- "All stories in production/epics/", "Stories for a specific epic"
-
-Report the scope before proceeding: "Validating [N] story files."
-
-> **If the scope resolves to ZERO story files, stop and report
-> `NOT ASSESSED — no stories in scope`.** Name which scope was searched and
-> which path was empty (`production/epics/**/*.md`, the sprint file's story
-> list, or the specific path given), and route: `/create-epics [layer]` then
-> `/create-stories [epic-slug]`.
->
-> **The zero-scope path is mandatory.** Without it an empty glob falls through
-> to the Section 5 aggregate template and renders `Ready: 0 /
-> Needs Work: 0 / Blocked: 0` above an empty list — **indistinguishable from
-> "I checked every story and none needed work"**. It is the core failure of this
-> framework exactly: a scan that finds nothing because there was nothing to
-> scan, reported the same way as a clean result. Three zeros read as a healthy
-> sprint.
->
-> Note what made this survive: `NOT ASSESSED` was already in this skill's
-> vocabulary, but the body scoped it to **per-story** evaluation failures (an
-> unreadable or unparseable file, an ADR with no readable Status). The verdict existed;
-> the case that most needs it had no route to it. It is a recurring shape — a
-> correct fix that did not reach one surface.
->
-> **A zero-story sprint scope is not the same as an absent sprint file.** If
-> `production/sprints/` has no file at all, say that instead — "no sprint plan
-> found" and "the sprint plan lists no stories" send the reader to different
-> fixes, and Section 7 already draws that distinction for the handoff block.
-
----
-
-## 2. Load Supporting Context
-
-Before checking any stories, load reference documents once (not per-story):
-
-- `design/gdd/systems-index.md` — to know which systems have approved GDDs
-- `docs/architecture/control-manifest.md` — story-readiness needs only the header
- `Manifest Version:` date (its manifest check is existence + version, not the rule
- bodies), so grep it (`Grep pattern="Manifest Version" path="docs/architecture/control-manifest.md"`)
- rather than a full read. If the file does not exist, note it as missing once; do not
- re-flag per story.
-- `docs/architecture/tr-registry.yaml` — index all entries by `id`. Used to
- validate TR-IDs in stories. If the file does not exist, note it once; TR-ID
- checks will auto-pass for all stories (registry predates stories, so missing
- registry means stories are from before TR tracking was introduced).
-- All ADR status fields — resolve these with **one scan, not one read per ADR**.
- A `Status:` value is a single line; reading whole ADR files to find it costs the
- entire architecture corpus, and in `all` scope that multiplies across every
- story in the repo:
- ```
- Grep pattern="^## Status" glob="docs/architecture/adr-*.md" output_mode="content" -A 3
- ```
- Establish the denominator first (glob `docs/architecture/adr-*.md`, count **N**)
- and interpret against it: **0 matches with N > 0 means malformed ADRs, not
- "no Accepted ADRs"** — report "run `/architecture-decision retrofit [file]`"
- rather than failing every story's ADR check. Never treat an unreadable status as
- a failed one. Cache the resulting map; do not re-scan per story.
-- The current sprint file (if scope is `sprint`) — to identify Must Have /
- Should Have priority for escalation decisions
-
----
-
-## 3. Story Readiness Checklist
-
-For each story file, evaluate every item below. A story is READY only if all
-items pass or are explicitly marked N/A with a stated reason.
-
-> **Workflow tier adjustment** (resolved in Phase 0, per the story's system). The
-> full checklist below is the `full` baseline:
-> - **`full`** — every item is blocking (TR registry + ADR + control manifest
-> fully validated).
-> - **`standard`** — **Design Completeness** and **Scope Clarity** stay blocking.
-> In **Architecture Completeness**, an ADR the story references that is missing,
-> `Proposed`, `Deprecated` or `Superseded` BLOCKS at every tier (see that section's note). Beyond that, only
-> a **critical (Foundation-layer) ADR** that is missing or `Proposed` BLOCKS; an
-> absent "ADR referenced" note is **advisory** (NEEDS WORK note, not BLOCKED).
-> The TR-ID and manifest items are advisory.
-> - **`minimal`** — **acceptance-criteria check only**: evaluate Design
-> Completeness and Scope Clarity. Treat the rest of **Architecture
-> Completeness** as N/A — except that a referenced ADR that is missing,
-> `Proposed`, `Deprecated` or `Superseded` still BLOCKS. Do not flag a missing ADR, TR-ID or manifest reference.
+Checks that a story file holds everything a developer needs before writing code:
+no design questions mid-build, no guessing, no vague acceptance criteria.
+
+**Read-only.** It never writes or edits a file. It reports, and offers to draft
+fixes in the conversation.
+
+**Verdicts**, one per story. The first that matches wins, in this order:
+
+1. **BLOCKED**: a finding the reader can clear. A referenced ADR is missing,
+ `Proposed`, `Deprecated` or `Superseded`; a dependency story is missing or
+ `Draft`; or a criterion holds an UNRESOLVED design question with no owner.
+2. **NEEDS WORK**: a blocking checklist item fails. The story can be fixed now.
+3. **NOT ASSESSED**: the story could not be evaluated. The file is unreadable,
+ a referenced ADR has no readable `## Status`, or the design document it names
+ cannot be found. Name what could not be read. It is never READY: a story
+ nobody could check has not been shown ready. It ranks below the two failures,
+ because a known blocker is more useful than an unknown.
+4. **READY**: every item passes, is N/A with a reason, or is advisory. Advisory
+ gaps are still listed.
+
+Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided
+asks on major choices, autonomous logs and goes on; `automation_always_ask`
+categories always ask).
+
+## Phase 1: Scope
+
+The scope is the text typed after the skill name, with any `--review <mode>` pair
+removed. What remains is one value; a path may contain spaces. With nothing typed,
+the story, epic or sprint the user's request names is the scope.
+
+- **A story path**: that story.
+- **`sprint`**: the stories the current sprint lists (Phase 2 reads them).
+- **`all`**: every `story-*.md` under `production/epics/`.
+- **An epic** (a slug or its folder): the `story-*.md` files in that folder.
+- **Blank**: Ask: "What would you like to check?" Options: A specific story file /
+ All stories in the current sprint / All stories in production/epics/ / The
+ stories of one epic.
+
+**Zero stories in scope: stop with `NOT ASSESSED — no stories in scope`.** Name the
+scope and the path that was empty, and route to `/create-stories` (at `standard`
+and `full`, `/create-epics` first). Never print a `Ready: 0 / Needs Work: 0` summary
+over an empty list: it reads as a clean result. For `sprint`, "no sprint plan
+found" and "the sprint plan lists no stories" are different reports; say which.
+
+Say "Checking [N] story files." before going on.
+
+## Phase 2: Facts, read once for the run
+
+1. **Stories.** Run the story helper over the scope, with the `story_granularity`
+ resolved above:
+ ```
+ bash .claude/scripts/story-facts.sh --lint --granularity <story_granularity> [--sprint | --all | <path> ...]
+ ```
+ Each `STORY` row gives a story's status, type, layer, estimate, TR-IDs, ADRs,
+ acceptance-criteria count, test-evidence line and dependencies. Each `LINT` row
+ is a rule the story trips. Rows are observations; the verdict is yours. Exit 3
+ means a file was not found. With `NOT_FOUND` rows, each names a sprint `file:`
+ entry or a path that is not a file: report each as a missing story and check
+ the rest. With no `NOT_FOUND` row and `--sprint`, there is no
+ `production/sprint-status.yaml`: report "no sprint plan found". Read each story file too: the testability, scope and
+ asset items below need its words.
+2. **ADRs.** One call gives every ADR's status and layer:
+ `bash .claude/scripts/adr-status.sh`. A `no_status` or `UNFILLED` status is a
+ malformed ADR: never treat an absent status as a failed one (route:
+ `/architecture-decision retrofit [file]`). An ADR a story cites with no row is missing.
+3. **Control manifest.** Only its `Manifest Version` line in
+ `docs/architecture/control-manifest.md`. Missing file: note it once.
+4. **TR registry.** Look up each story's TR-IDs, with their `status`, in
+ `docs/architecture/tr-registry.yaml`. Missing file: note it once; the TR-ID
+ item passes for every story.
+5. **Sprint priority** (`sprint` scope): which stories are Must Have and Should
+ Have, from the newest plan in `production/sprints/`.
+
+**Tier per story.** `workflow` is resolved per story: use the `system_overrides`
+row for the story's system (the GDD filename stem of its `GDD:` path; the `[system]`
+of a `TR-[system]-NNN` ID only when there is no GDD path), else the project value.
+Stories in one run can sit at different tiers.
+
+## Phase 3: The checklist
+
+Check every item for every story. The tier decides which groups block:
+
+| Group | `full` | `standard` | `minimal` |
+|---|---|---|---|
+| Design Completeness | blocks | blocks | blocks; `design/game-brief.md` stands in for the GDD |
+| Architecture Completeness | blocks | the ADR status item blocks; the rest advisory unless it concerns a critical ADR | N/A, except the ADR status item |
+| Scope Clarity | blocks | blocks | blocks, except Estimate: advisory (no sprint plan to size for) |
+| Open Questions | blocks | blocks | blocks |
+| Asset References | blocks | blocks | blocks |
+| Definition of Done | blocks | blocks | blocks; the test evidence item follows `qa.level` |
+
+An **advisory** item that fails is listed under Gaps with its Fix, and never
+lowers READY by itself.
### Design Completeness
-- [ ] **GDD requirement referenced**: The story includes a `design/gdd/` path
- and quotes or links a specific requirement, acceptance criterion, or rule from
- that GDD — not just the GDD filename. A link to the document without tracing
- to a specific requirement does not pass. At `minimal`,
- `design/game-brief.md` — the MVP feature and the Player goal & fail state the
- story traces to — stands in for the GDD.
-- [ ] **Requirement is self-contained**: The acceptance criteria in the story
- are understandable without opening the GDD. A developer should not need to
- read a separate document to understand what DONE means.
-- [ ] **Acceptance criteria are testable**: Each criterion is a specific,
- observable condition — not "implement X" or "the system works correctly".
- Bad example: "Implement the jump mechanic." Good example: "Jump reaches
- max height of 5 units within 0.3 seconds when jump is held."
-- [ ] **No acceptance criteria require judgment calls** *(auto-pass for `Type: Visual/Feel`)*: Criteria like
- "feels responsive" or "looks good" are not testable without a defined
- benchmark. For Logic, Integration, UI, and Config/Data stories, these must be
- replaced with specific observable conditions. For Visual/Feel stories, subjective
- criteria are expected and this check auto-passes — instead verify that each
- subjective criterion has a paired playtest protocol or evidence requirement
- (e.g., "evidence doc required at `production/qa/evidence/[slug]-evidence.md`").
- PASS if the acceptance criterion ends with or is accompanied by an explicit reference to a file path such as `production/qa/evidence/[slug]-evidence.md`. NEEDS WORK if the criterion is purely subjective with no evidence file path specified.
+- [ ] **Requirement traced**: the story names its `design/gdd/` file and quotes or
+ links a specific rule or criterion from it, not just the file name. At
+ `minimal`: `design/game-brief.md` and the MVP feature the story implements.
+ A named design document that does not exist: NOT ASSESSED.
+- [ ] **Self-contained**: the acceptance criteria say what done means without
+ opening the GDD.
+- [ ] **Testable**: each criterion is a specific, observable condition. Not:
+ "Implement the jump mechanic." Yes: "Jump reaches 5 units within 0.3 seconds
+ when held." A criterion a unit test can set up (any input values) is testable,
+ even when the shipped data never reaches that case.
+- [ ] **No judgement calls**: "feels responsive" or "looks good" fails for Logic,
+ Integration, UI and Config/Data. For Visual/Feel such criteria are expected:
+ pass when the criterion names an evidence file such as
+ `production/qa/evidence/[slug]-evidence.md`, NEEDS WORK when it names none.
### Architecture Completeness
-> The `BLOCKED` / fail outcomes in this section are the `full` baseline, with one
-> rule that holds at every tier: **an ADR the story references that is missing,
-> `Proposed`, `Deprecated` or `Superseded` BLOCKS**. `/dev-story` stops on it at `full`, `standard` and
-> `minimal` alike, so a READY here would send the story straight into a stop.
-> Beyond that, apply the tier note above: at `standard` the other items are
-> advisory unless they concern a **critical** ADR; at `minimal` the rest of this
-> section is N/A.
->
-> At `standard`, an advisory item — a stale manifest version, missing engine notes
-> or manifest rules for a non-critical ADR — is written up like a NEEDS WORK item,
-> under Gaps with its `Fix:` line, but it never BLOCKS and does not by itself
-> downgrade READY. An ADR is critical
-> when the `**Layer**` row of its `## Engine Compatibility` table says
-> Foundation, or when that row is missing — when in doubt, treat it as critical
-> (`.claude/docs/workflow-modes.md`). Read the rows once, alongside the Section 2
-> status scan: `Grep pattern="\*\*Layer\*\*" glob="docs/architecture/adr-*.md" output_mode="content"`.
-
-- [ ] **ADR referenced or N/A stated**: The story references at least one ADR,
- OR explicitly states "No ADR applies" with a brief reason.
- A story with no ADR reference and no explicit N/A note fails this check.
-- [ ] **ADR is Accepted (not Proposed)**: For each referenced ADR, check its
- `Status:` field using the cached ADR statuses loaded in Section 2.
- - If `Status: Accepted` → pass.
- - If `Status: Proposed` → **BLOCKED**: the ADR may change before it is accepted,
- and the story's implementation guidance could be wrong.
- Fix: `BLOCKED: ADR-NNNN is Proposed — wait for acceptance before implementing.`
- - If the ADR file does not exist → **BLOCKED**: referenced ADR is missing.
- - If `Status:` is `Deprecated` or `Superseded by ADR-XXXX` → **BLOCKED**: the
- decision no longer stands.
- Fix: `BLOCKED: ADR-NNNN is [status] — point the story at [successor] (edit its ADR field — /create-stories never rewrites an existing story).`
- - If the ADR file exists but has no readable `## Status` (the Section 2 scan
- found none in it) → **NOT ASSESSED** for this check: its status is unknown,
- not failed. Name the file and route to `/architecture-decision retrofit [file]`.
- - Auto-pass if story has an explicit "No ADR applies" N/A note.
-- [ ] **TR-ID is valid and active**: If the story contains a `TR-[system]-NNN`
- reference, look it up in the TR registry loaded in Section 2.
- - If the ID exists and `status: active` → pass.
- - If the ID exists and `status: deprecated` or `status: "superseded-by: ..."`
- (quoted or not) →
- NEEDS WORK: the requirement was removed or replaced.
- Fix: update the story to reference the current requirement ID or remove if no longer applicable.
- - If the ID does not exist in the registry → NEEDS WORK: ID was not registered
- (story may predate registry, or registry needs an `/architecture-review` run).
- - Auto-pass if the story has no TR-ID reference OR if the registry does not exist.
-- [ ] **Manifest version is current**: If the story has a `Manifest Version:` date
- in its header AND `docs/architecture/control-manifest.md` exists:
- - If story version matches current manifest `Manifest Version:` → pass.
- - If story version is older than current manifest → NEEDS WORK: new rules may
- apply. Fix: review changed manifest rules, update story if any forbidden/required
- entries changed, then update the story's `Manifest Version:` to current.
- - Auto-pass if either the story has no `Manifest Version:` field OR the manifest
- does not exist.
-- [ ] **Engine notes present**: For any post-cutoff engine API this story
- is likely to touch, implementation notes or a verification requirement are
- included. If the story clearly does not touch engine APIs (e.g., it is a
- pure data/config change), "N/A — no engine API involved" is acceptable.
-- [ ] **Control manifest rules noted**: Relevant layer rules from the control
- manifest are referenced, OR "N/A — manifest not yet created" is stated.
- This item auto-passes if `docs/architecture/control-manifest.md` does not
- exist yet (do not penalize stories written before the manifest was created).
+- [ ] **ADR status**, at every tier: each ADR the story cites, by the Phase 2
+ table.
+ - `Accepted`: pass.
+ - `Proposed`: BLOCKED. Fix: `BLOCKED: ADR-NNNN is Proposed — accept it with
+ /architecture-decision accept ADR-NNNN once decided`.
+ - `Deprecated` or `Superseded`: BLOCKED. Fix: `BLOCKED: ADR-NNNN is [status] —
+ point the story at [successor] (edit its ADR field;
+ /create-stories never rewrites an existing story)`.
+ - No such ADR file: BLOCKED.
+ - No readable status: NOT ASSESSED for this item; name the file.
+ At `standard`, a **critical** ADR (its `layer` is Foundation, or missing) that
+ is missing or Proposed blocks; for other ADRs the items below are advisory.
+- [ ] **ADR cited or N/A stated**: an ADR, or an explicit N/A with a reason
+ (`ADR: N/A — [reason]`, or `N/A (minimal — no ADRs)`). Blank fails.
+- [ ] **TR-ID valid**: each `TR-[system]-NNN` is in the registry with `status:
+ active`. `deprecated` or `superseded-by` (quoted or not): NEEDS WORK, Fix: point
+ the story at the current requirement. Not in the registry: NEEDS WORK (the story
+ may predate it, or the registry needs `/architecture-review`). Passes with no
+ TR-ID, or no registry.
+- [ ] **Manifest Version current**: the story's `Manifest Version` against the
+ manifest's. Older: a gap, because rules added since may apply. It stays a gap
+ even when the new rules look unrelated: say what changed, and leave the call to
+ the user. At `full` it is NEEDS WORK whatever the new rules cover; at
+ `standard` it is advisory. Fix, all three steps: "Review the manifest rules added since
+ [story's date]; update the story's rules if any apply; then set its Manifest
+ Version to [current date]." Passes with no `Manifest Version` field, or no
+ manifest.
+- [ ] **Engine notes**: post-cutoff engine APIs the story touches have notes or a
+ verification step, or the story states "N/A — no engine API involved".
+- [ ] **Manifest rules noted**: the layer's rules are listed, or "N/A — manifest
+ not yet created". Passes when there is no manifest.
### Scope Clarity
-- [ ] **Estimate present**: The story includes a size estimate (hours,
- points, or a t-shirt size). A story with no estimate cannot be planned.
-- [ ] **In-scope / Out-of-scope boundary stated**: The story states what
- it does NOT include, either in an explicit Out of Scope section or in
- language that makes the boundary unambiguous. Without this, scope creep
- during implementation is likely.
-- [ ] **Story dependencies listed**: If this story depends on other stories
- being DONE first, those story IDs are listed. If there are no dependencies,
- "None" is explicitly stated (not just omitted).
+- [ ] **Estimate**: hours, points or a t-shirt size. `unfilled Estimate` (still the
+ template's bracket) fails. Advisory at `minimal`.
+- [ ] **Out of scope stated**: an Out of Scope section, or wording that leaves the
+ boundary unambiguous.
+- [ ] **Dependencies listed**: each story this one needs, or "None" stated.
### Open Questions
-- [ ] **No unresolved design questions**: The story does not contain text
- flagged as "UNRESOLVED", "TBD", "TODO", "?", or equivalent markers in
- any acceptance criterion, implementation note, or rule statement.
-- [ ] **Dependency stories are not in DRAFT**: For each story listed as a
- dependency, check if the file exists and does not have a DRAFT status. A
- story that depends on a DRAFT or missing story is BLOCKED, not just
- NEEDS WORK.
-
-### Asset References Check
-
-- [ ] **Referenced assets exist**: Scan the story text for asset path patterns
- (paths containing `assets/`, or file extensions `.png`, `.jpg`, `.svg`,
- `.wav`, `.ogg`, `.mp3`, `.glb`, `.gltf`, `.tres`, `.tscn`, `.res`).
- - For each asset path found: use Glob to check whether the file exists.
- - If any referenced asset does not exist: **NEEDS WORK** — note the missing
- path(s). (The story references assets that have not been created yet.
- Either remove the reference, create a placeholder, or mark it as an
- explicit dependency on an asset creation story.)
- - If all referenced assets exist: note "Referenced assets verified:
- [count] found."
- - If no asset paths are referenced in the story: note "No asset references
- found in story — skipping asset check." This item auto-passes.
- - This is an existence-only check. Do not validate file format or content.
+- [ ] **No open markers**: no `marker` rows (TBD, TODO or UNRESOLVED as whole
+ words in capitals). A `?` is not a marker: a formula like `crit ? 2 : 1` passes.
+ A criterion written as an open question still fails Testable.
+- [ ] **Dependencies exist and are not Draft**: a dependency story that is missing
+ or `Draft` makes the story BLOCKED. `Story NNN` means that number in the same
+ epic folder; a path names one exactly.
-### Definition of Done
+### Asset References
-- [ ] **Minimum testable acceptance criteria by story type**:
- - Logic / Integration stories: at least 3
- - Visual/Feel and UI stories: at least 2
- - Config/Data stories: at least 1
- Apply the threshold matching the story's `Type:` field. If the story has fewer than the minimum, mark as NEEDS WORK.
-- [ ] **Performance budget noted if applicable**: If this story touches any
- part of the gameplay loop, rendering, or physics, a performance budget or
- a "no performance impact expected — [reason]" note is present.
-- [ ] **Story Type declared**: The story includes a `Type:` field in its header
- identifying the test category (Logic / Integration / Visual/Feel / UI / Config/Data).
- Without this, test evidence requirements cannot be enforced at story close.
- Fix: Add `Type: [Logic|Integration|Visual/Feel|UI|Config/Data]` to the story header.
-- [ ] **Test evidence requirement is clear** *(auto-pass at `qa.level: minimal` for
- Logic, Integration and Config/Data stories — no test evidence is required for
- them; never for UI or Visual/Feel, whose retained screenshot is required at every
- `qa.level`)*: If the Story Type is set, the story includes a `## Test Evidence`
- section stating where evidence will be stored (test file path for
- Logic/Integration; for UI, where the retained screenshot of each screen touched
- goes under `production/qa/evidence/`; for Visual/Feel, that plus the sign-off doc
- `production/qa/evidence/[story-slug]-evidence.md`).
- Resolve this item's gate level from the `testing.strict` block **resolved in
- Phase 0** — not by reading `project.yaml`, which would ignore a developer's
- locally-overridden value. Map the Story Type to a key (Logic→`logic`,
- Integration→`integration`, Visual/Feel→`visual`, UI→`ui`,
- Config/Data→`config`) and take
- `testing.strict.<key>`; use it only if its value is `true` or `false`
- (case-insensitive). If the key is absent, empty, or holds any other value, read
- `testing.strict` as a plain boolean (legacy single-value form); if that too is
- absent or invalid, default to strict for Logic, Integration, Visual/Feel and UI,
- and advisory for Config/Data. Surface any unrecognized value to the user.
- - At a **strict** gate level, a missing `## Test Evidence` section marks the
- story **NEEDS WORK**.
- - At an **advisory** gate level, a missing section is listed as a gap but does
- not by itself downgrade the verdict from READY.
- Fix: Add `## Test Evidence` with the expected evidence location for the story's type.
+- [ ] **Assets the story uses exist**: paths under `assets/`, or with `.png`,
+ `.jpg`, `.svg`, `.wav`, `.ogg`, `.mp3`, `.glb`, `.gltf`, `.tres`, `.tscn` or
+ `.res`, that the story reads or builds on. A file the story says it will create
+ (a new scene, a new data file) is not checked. Missing: NEEDS WORK; name the
+ path. Report "Referenced assets verified: [N] found", or "No asset references".
+ Existence only.
----
+### Definition of Done
-## 4. Verdict Assignment
+- [ ] **Enough acceptance criteria**: no `ac_below_min` row. The minimums follow
+ `story_granularity`, because `/create-stories` writes to it:
-Assign one of four verdicts per story, first match wins in the order BLOCKED,
-NEEDS WORK, NOT ASSESSED, READY (the precedence stated at the top):
+ | `story_granularity` | Logic, Integration | Visual/Feel, UI | Config/Data |
+ |---|---|---|---|
+ | `coarse` | 3 | 2 | 1 |
+ | `balanced` | 2 | 2 | 1 |
+ | `fine` | 1 | 1 | 1 |
-**READY** — All checklist items pass, have explicit N/A justifications, or are
-advisory-level gaps (a checklist item whose gate level resolved to advisory via
-`testing.strict`, or one the Section 3 workflow tier note makes advisory).
-Advisory gaps are still listed under Gaps in the output.
-The story can be assigned immediately.
+- [ ] **Performance noted**: a story touching the gameplay loop, rendering or
+ physics states a budget, or "no performance impact expected — [reason]".
+- [ ] **Type declared**: no `type_missing` or `type_unknown` row. Fix: add
+ `Type: [Logic|Integration|Visual/Feel|UI|Config/Data]` to the header.
+- [ ] **Test evidence clear**: a `## Test Evidence` section saying where evidence
+ goes: the test file for Logic and Integration; the retained screenshot of each
+ screen under `production/qa/evidence/` for UI; that plus
+ `production/qa/evidence/[story-slug]-evidence.md` for Visual/Feel.
+ - At `qa.level: minimal`, Logic, Integration and Config/Data pass: tests are
+ waived. List no gap, and add no note, about a missing test file, `tests/`
+ folder or test runner. UI and
+ Visual/Feel are still checked: their screenshot is required at every level.
+ - Otherwise the `gate_level` line above sets the level for the story's type.
+ `blocking`: a missing section is NEEDS WORK. `advisory`: a listed gap only.
+ Fix: add `## Test Evidence` with the evidence location for the story's type.
-**NEEDS WORK** — One or more checklist items fail, but all dependency stories
-exist and are not DRAFT. The story can be fixed before assignment.
+## Phase 4: Verdict
-**BLOCKED** — One or more dependency stories are missing or in DRAFT state,
-OR a governing ADR is `Proposed`, `Deprecated` or `Superseded`, or its file is missing (Section 3's ADR check),
-OR a critical design question (flagged UNRESOLVED in a criterion or rule) has
-no owner. The story cannot be assigned until the blocker is resolved. Note:
-a story that is BLOCKED may also have NEEDS WORK items — list both.
+Apply the order at the top to each story. A BLOCKED story may also have NEEDS WORK
+items: list both.
-**NOT ASSESSED** — the story could not be evaluated at all (unreadable or
-unparseable file, a referenced ADR with no readable `## Status`, or a referenced
-design document that cannot be located, so the checks cannot run — a referenced
-ADR file that does not exist is BLOCKED instead). Name what could not be read.
-Never READY.
+## Phase 5: QA lead review
----
+Read the `review_gate` line above. `skill-gates=skip` (solo or lean): skip it, and
+the reply says "QL-STORY-READY skipped — [Solo | Lean] mode". `skill-gates=run`:
+read `references/qa-lead-gate.md` and `.claude/docs/director-gates.md`, and run it
+before reporting. On a skip, do not load it.
-## 5. Output Format
+## Phase 6: Report and close
-### Single story output
+One story:
```
## Story Readiness: [story title]
@@ -377,143 +237,67 @@ File: [path]
Verdict: [READY / NEEDS WORK / BLOCKED / NOT ASSESSED]
### Passing Checks (N/[total])
-Design Completeness: [passing items, briefly]
-Architecture Completeness: [passing items — or "N/A — [reason]", e.g. "N/A at `minimal` (referenced-ADR check applied)"]
+Design Completeness: [passing items]
+Architecture Completeness: [passing items, or "N/A at minimal (ADR status checked)"]
Scope Clarity: [passing items]
Open Questions: [passing items]
-Asset References: [passing items — or "no asset references"]
+Asset References: [passing items, or "no asset references"]
Definition of Done: [passing items]
### Gaps
-- [Checklist item]: [exact description of what is missing or wrong]
- Fix: [specific text needed to resolve this gap]
+- [Checklist item]: [what is missing or wrong]
+ Fix: [the text that resolves it]
### Blockers (if BLOCKED)
-- [What is blocking]: [story ID or design question that must resolve first]
+- [What blocks]: [the story, ADR or question that must clear first]
```
-Name all six check groups under Passing Checks every time. A group with nothing
-passing says so ("none — see Gaps"), so a reader can see that each group was
-evaluated rather than skipped.
+Name all six groups every time, by these exact names. A group with nothing
+passing says "none — see Gaps", so the reader sees it was checked.
-### Multiple story aggregate output
+Gaps lists failed checklist items only: never a passing or N/A item, and never an
+observation from outside the checklist (a sprint status, another document).
-```
-## Story Readiness Summary — [scope] — [date]
-
-Ready: [N] stories
-Needs Work: [N] stories
-Blocked: [N] stories
-Not Assessed: [N] stories
-
-### Ready Stories
-- [story title] ([path])
+Several stories: a summary first, then the one-story block for each story that is
+not READY.
-### Needs Work
-- [story title]: [primary gap — one line]
-- [story title]: [primary gap — one line]
-
-### Blocked Stories
-- [story title]: Blocked by [story ID / design question]
-
----
-[Full detail for each non-ready story follows, using the single-story format]
```
+## Story Readiness Summary — [scope] — [date]
+Ready: [N] · Needs Work: [N] · Blocked: [N] · Not Assessed: [N]
-### Sprint escalation
-
-If the scope is `sprint` and any Must Have stories are NEEDS WORK, BLOCKED or
-NOT ASSESSED, add a prominent warning at the top of the output:
-
-```
-WARNING: [N] Must Have stories are not implementation-ready.
-[List them with their primary gap or blocker.]
-Resolve these before the sprint begins or replan with `/sprint-plan update`.
+Ready: [title] ([path]), ...
+Needs Work: [title]: [main gap]
+Blocked: [title]: blocked by [story, ADR or question]
+Not Assessed: [title]: [what could not be read]
```
----
-
-## 6. Collaborative Protocol
-
-This skill is read-only. It never proposes edits or asks to write files.
+`sprint` scope: when a Must Have story is not READY, put this first:
+`WARNING: [N] Must Have stories are not ready to implement: [each with its main
+gap]. Fix them before the sprint starts, or replan with /sprint-plan update.`
-After reporting findings, offer:
+**Then, for one story:** look for other stories to start. In the newest plan in
+`production/sprints/`, find up to 3 that are Ready or Not Started, not this one,
+not waiting on unfinished dependencies, and Must Have or Should Have. List each
+with a one-line description and its estimate. When there are none, say which:
+`Next ready stories: no sprint file found` or `Next ready stories: none ready in
+[sprint]`.
-"Would you like help filling in the gaps for any of these stories? I can
-draft the missing sections for your approval."
+**Offer help.** Ask: "Would you like me to draft the missing parts for any of
+these stories?" Options: Yes, draft them / No, that's all. On yes, draft only the
+missing parts, in the conversation. The user, or `/create-stories`, writes them.
-If the user says yes for a specific story, draft only the missing sections
-in conversation. Do not use Write or Edit tools — the user (or
-`/create-stories`) handles writing.
+Redirects:
+- Story file missing: run `/create-stories [epic-slug]` (at `standard` and
+ `full`, `/create-epics` first).
+- No design reference and the change is small (under about a week): run
+ `/quick-design [description]` and cite that spec in the story.
+- Scope grew past its sizing: split the story, or raise it with the producer.
-**Redirect rules:**
-- If a story file does not exist at all: "This story file is missing entirely.
- Run `/create-epics [layer]` then `/create-stories [epic-slug]` to generate stories from the GDD and ADR."
-- If a story has no GDD reference and the work appears small: "This story has
- no GDD reference. If the change is small (under about one week of implementation), run
- `/quick-design [description]` to create a Quick Design Spec, then reference
- that spec in the story."
-- If a story's scope has grown beyond its original sizing: "This story appears
- to have expanded in scope. Consider splitting it or escalating to the producer
- before implementation begins."
-
----
-
-## 7. Next-Story Handoff
-
-After completing a single-story readiness check (not `all` or `sprint` scope):
-
-1. Read the current sprint file from `production/sprints/` (most recent).
-2. Find stories that are:
- - Status: READY or NOT STARTED
- - Not the story just checked
- - Not blocked by incomplete dependencies
- - In the Must Have or Should Have tier
-
-If any are found, surface up to 3:
+**End the reply with:**
```
-### Other Ready Stories in This Sprint
-
-1. [Story name] — [1-line description] — Est: [X hrs]
-2. [Story name] — [1-line description] — Est: [X hrs]
-
-Run `/story-readiness [path]` to validate before starting.
+Review: [QL-STORY-READY skipped — Solo mode | skipped — Lean mode | its verdict]
+Next ready stories: [up to 3 | no sprint file found | none ready in [sprint]] (one-story scope)
+Next step: [/dev-story [path] when READY | fix the gaps above, then /story-readiness [path]]
+Files changed: none
```
-
-If no sprint file exists, or no other ready stories are found, say which — `Next ready stories: no sprint file found` or `Next ready stories: none ready in [sprint]` — rather than omitting the section. The two mean different things (nothing to read versus nothing ready) and an omitted section reads as neither.
-
----
-
-## Phase 8: Director Gate — Story Readiness Review
-
-Apply the review mode resolved in Phase 0 before spawning QL-STORY-READY:
-
-- `solo` → skip. Note: "QL-STORY-READY skipped — Solo mode." Proceed to close.
-- `lean` → skip. Note: "QL-STORY-READY skipped — Lean mode." Proceed to close.
-- `full` → spawn as normal.
-
-Spawn `qa-lead` via `Agent` using gate **QL-STORY-READY** (`.claude/docs/director-gates/ql-story-ready.md`).
-
-Pass the context that gate lists, plus this skill's findings:
-- Story file path
-- Story type (Logic / Integration / Visual/Feel / UI / Config/Data) — the gate's prompt branches on it
-- Acceptance criteria list (verbatim, all items)
-- The GDD requirement the story covers (TR-ID and text)
-- Dependency status (all dependencies listed and their current state: exist / DRAFT / missing)
-- Overall verdict (READY / NEEDS WORK / BLOCKED / NOT ASSESSED) from Phase 4
-
-Handle the verdict per standard rules in `director-gates.md`:
-- **ADEQUATE** → story is cleared. Proceed to close.
-- **GAPS [list]** → surface the specific gaps to the user via `AskUserQuestion`:
- options: `Update story with suggested gaps` / `Accept and proceed anyway` / `Discuss further`.
-- **INADEQUATE** → the gate says the story must be revised before sprint inclusion, so it is not READY: the verdict becomes at least NEEDS WORK (a BLOCKED one stays BLOCKED). List the gaps and restate the final verdict line, then ask whether to update the story or proceed anyway. If the user proceeds anyway, the verdict stays NEEDS WORK (BLOCKED if it was BLOCKED) and the output states the override — "proceeding despite QL-STORY-READY: INADEQUATE (user override)" — never a silent READY.
-- **NOT ASSESSED [missing input]** → the gate made no judgement; never read it as ADEQUATE. Name the missing input and offer to supply it and re-run the gate; otherwise a READY verdict becomes NOT ASSESSED (BLOCKED and NEEDS WORK stand).
-
----
-
-## Recommended Next Steps
-
-- Run `/dev-story [story-path]` to begin implementation once the story is READY
-- Run `/story-readiness sprint` to check all stories in the current sprint at once
-- Run `/create-stories [epic-slug]` if a story file is missing entirely
diff --git a/.claude/skills/story-readiness/references/qa-lead-gate.md b/.claude/skills/story-readiness/references/qa-lead-gate.md
new file mode 100644
index 00000000..d52404f1
--- /dev/null
+++ b/.claude/skills/story-readiness/references/qa-lead-gate.md
@@ -0,0 +1,32 @@
+# Phase 5: QA lead review (QL-STORY-READY)
+
+Read only when the `review_gate` line says `skill-gates=run` (`review_mode: full`).
+
+Hand the review to the `qa-lead` agent, once per story, with gate
+**QL-STORY-READY**. The agent reads its own gate file; do not read it here.
+
+Brief:
+- **Objective:** judge whether this story's acceptance criteria are testable enough
+ to implement against.
+- **Give it:** the story path; its type (Logic / Integration / Visual/Feel / UI /
+ Config/Data), which the gate branches on; every acceptance criterion, verbatim;
+ the requirement it covers (TR-ID and text); each dependency and its state
+ (exists, Draft, missing); this run's verdict.
+- **Return:** ADEQUATE, GAPS with the list, INADEQUATE with the list, or NOT
+ ASSESSED naming the missing input.
+- **Boundaries:** it reads the story and the files the brief names; it edits
+ nothing.
+
+Act on its report:
+
+- **ADEQUATE**: the story is cleared.
+- **GAPS**: show the gaps, then ask: "How do you want to handle these?" Options:
+ Draft the fixes / Accept and go on / Discuss further.
+- **INADEQUATE**: the story is not READY. The verdict becomes at least NEEDS WORK
+ (BLOCKED stays BLOCKED). List the gaps, restate the verdict, then ask whether to
+ draft fixes or go on anyway. If the user goes on, the verdict stays and the
+ report says "proceeding despite QL-STORY-READY: INADEQUATE (user override)".
+ Never a silent READY.
+- **NOT ASSESSED**: the gate judged nothing; never read it as ADEQUATE. Name the
+ missing input and offer to supply it and run the gate again. Otherwise a READY
+ verdict becomes NOT ASSESSED; NEEDS WORK and BLOCKED stand.
diff --git a/.claude/skills/team-audio/SKILL.md b/.claude/skills/team-audio/SKILL.md
index dc3410e5..a912b774 100644
--- a/.claude/skills/team-audio/SKILL.md
+++ b/.claude/skills/team-audio/SKILL.md
@@ -3,7 +3,7 @@ name: team-audio
description: "Orchestrate the audio team — audio-director, sound-designer, technical-artist, gameplay-programmer — direction through implementation."
argument-hint: "[feature or area to design audio for] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-audio/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-audio/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
@@ -74,7 +74,9 @@ enforced.**
`main menu`, `forest biome`, `boss encounter`).
2. **Gather context**:
- - Read relevant design docs in `design/gdd/` for the feature
+ - Read relevant design docs in `design/gdd/` for the feature, by section: find the
+ headings you need with the Grep tool (pattern `^#`, content mode) and Read
+ those ranges with offset and limit
- Read the sound bible at `design/audio/sound-bible.md` if it exists. If only
`design/gdd/sound-bible.md` exists (where earlier versions put it), read that
and recommend moving it to `design/audio/` — in `design/gdd/` the GDD checks
@@ -179,7 +181,7 @@ Spawn the `gameplay-programmer` agent to:
5. **Save to** `design/audio/audio-[feature].md` — **but ask first.** `design/` is
NOT one of the three directories the bounded write exception covers
(`production/`, `docs/`, `tests/`), so a sub-agent handed this path must
- prompt, and one has done exactly that. Do not
+ prompt. Do not
resolve that by widening the exception. Instead, follow the same pattern
`team-level` uses: **you** already hold every sub-agent's output, so compile
the document yourself and ask directly via `AskUserQuestion` — "May I write the
diff --git a/.claude/skills/team-combat/SKILL.md b/.claude/skills/team-combat/SKILL.md
index c2d7df5a..afa01e72 100644
--- a/.claude/skills/team-combat/SKILL.md
+++ b/.claude/skills/team-combat/SKILL.md
@@ -3,7 +3,7 @@ name: team-combat
description: "Orchestrate the combat team — game-designer, gameplay-programmer, ai-programmer, technical-artist, sound-designer, qa-tester — design through implement and validate."
argument-hint: "[combat feature description] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-combat/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-combat/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
# Team Combat
@@ -146,7 +146,7 @@ via `AskUserQuestion`: "May I write the design document to
### Phase 2: Architecture
Delegate to **gameplay-programmer** (with **ai-programmer** if AI is involved):
-- Review the design document
+- Review the design document, reading it by section: find the headings you need with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit
- Design the code architecture: class structure, interfaces, data flow
- Identify integration points with existing systems
- Output: architecture sketch with file list and interface definitions
diff --git a/.claude/skills/team-level/SKILL.md b/.claude/skills/team-level/SKILL.md
index a71bd02d..9fa9dd8c 100644
--- a/.claude/skills/team-level/SKILL.md
+++ b/.claude/skills/team-level/SKILL.md
@@ -3,7 +3,7 @@ name: team-level
description: "Orchestrate the level team — level-designer, narrative-director, world-builder, art-director, systems-designer, qa-tester — for complete area creation."
argument-hint: "[level name or area to design] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-level/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-level/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
@@ -73,7 +73,9 @@ enforced.**
1. **Read the argument** for the target level or area (e.g., `tutorial`,
`forest dungeon`, `hub town`, `final boss arena`).
-2. **Gather context**:
+2. **Gather context** (read each design doc by section: find the headings you need
+ with the Grep tool with pattern `^#` in content mode, and Read those ranges
+ with offset and limit):
- Read the game concept at `design/gdd/game-concept.md` — or `design/game-brief.md`,
the one-page brief that replaces it at `rigor: minimal` — if either exists
- Read game pillars at `design/gdd/game-pillars.md`
@@ -137,7 +139,7 @@ Spawn the `art-director` agent to:
- Define the color temperature and lighting mood for this area (how does it differ from adjacent areas?)
- Specify shape language direction (angular fortress? organic cave? decayed grandeur?)
- Name the primary visual landmarks that will orient the player
-- Read `design/art/art-bible.md` if it exists — anchor all direction in the established art bible
+- Read `design/art/art-bible.md` if it exists — anchor all direction in the established art bible. Read it by section: find the headings you need with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit.
**The art-director's visual targets from Step 1 must be passed to the level-designer in Step 2** as explicit constraints. Layout decisions happen within the visual direction, not before it.
diff --git a/.claude/skills/team-live-ops/SKILL.md b/.claude/skills/team-live-ops/SKILL.md
index e9b14596..ce653d99 100644
--- a/.claude/skills/team-live-ops/SKILL.md
+++ b/.claude/skills/team-live-ops/SKILL.md
@@ -3,7 +3,7 @@ name: team-live-ops
description: "Orchestrate the live-ops team — live-ops-designer, economy-designer, analytics-engineer, community-manager, writer — for a season or live event."
argument-hint: "[season name or event description] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-live-ops/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-live-ops/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
# Team Live Ops
diff --git a/.claude/skills/team-polish/SKILL.md b/.claude/skills/team-polish/SKILL.md
index b4bf0855..4758f080 100644
--- a/.claude/skills/team-polish/SKILL.md
+++ b/.claude/skills/team-polish/SKILL.md
@@ -3,7 +3,7 @@ name: team-polish
description: "Orchestrate the polish team — performance-analyst, technical-artist, sound-designer, qa-tester — to optimize and harden a feature or area."
argument-hint: "[feature or area to polish] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-polish/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-polish/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
# Team Polish
diff --git a/.claude/skills/team-release/SKILL.md b/.claude/skills/team-release/SKILL.md
index d46a984c..e1772511 100644
--- a/.claude/skills/team-release/SKILL.md
+++ b/.claude/skills/team-release/SKILL.md
@@ -3,7 +3,7 @@ name: team-release
description: "Orchestrate the release team — release-manager, qa-lead, devops-engineer, producer — to execute a release from candidate to deployment."
argument-hint: "[version number or 'next'] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-release/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-release/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
# Team Release
diff --git a/.claude/skills/team-ui/SKILL.md b/.claude/skills/team-ui/SKILL.md
index 824d50f2..af4bff32 100644
--- a/.claude/skills/team-ui/SKILL.md
+++ b/.claude/skills/team-ui/SKILL.md
@@ -3,7 +3,7 @@ name: team-ui
description: "Orchestrate the UI team through the UX pipeline — authoring, visual design, implementation, review, polish. Uses /ux-design, /ux-review, studio templates."
argument-hint: "[UI feature description] [--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-ui/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-ui/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
# Team UI
@@ -122,7 +122,9 @@ Launch independent agents in parallel where the pipeline allows it (e.g., Phase
### Phase 1a: Context Gathering
-Before designing anything, read and synthesize:
+Before designing anything, read and synthesize. Read each GDD by section: find the
+headings you need with the Grep tool (pattern `^#`, content mode) and Read those
+ranges with offset and limit.
- `design/gdd/game-concept.md` — platform targets and intended audience (or
`design/game-brief.md`, the one-page brief that replaces it at `rigor: minimal` —
its "Who it's for" line gives the audience; it names no platform)
@@ -132,8 +134,7 @@ Before designing anything, read and synthesize:
- `design/accessibility-requirements.md` — committed accessibility tier (Basic, Standard, Comprehensive or Exemplary)
**Report the status of every document above before designing anything.** Phase 1a
-reads five inputs; for a long time only the pattern library was guarded, and the
-other four could be absent without anything noticing. List each as
+reads five inputs, and any of them can be absent. List each as
present or ABSENT.
**`design/accessibility-requirements.md` is the one that must not pass silently.**
diff --git a/.claude/skills/tech-debt/SKILL.md b/.claude/skills/tech-debt/SKILL.md
index 2b45d159..b9436978 100644
--- a/.claude/skills/tech-debt/SKILL.md
+++ b/.claude/skills/tech-debt/SKILL.md
@@ -87,6 +87,12 @@ If no, stop here. Verdict: **BLOCKED** — user declined write.
Ask the user for the description and affected files (plain text prompts).
+**Run as a subagent?** `lead-programmer` preloads this skill, and a subagent has
+no `AskUserQuestion`. Return the three questions below (category, effort,
+impact) in one reply, each as a short list of its options, and stop: whoever
+called you asks the user. Nothing goes into the register until the answers
+come back.
+
Then use `AskUserQuestion` to collect the **category**:
- Prompt: "What category does this tech debt belong to?"
- Options:
diff --git a/.claude/skills/test-evidence-review/SKILL.md b/.claude/skills/test-evidence-review/SKILL.md
index 1042fd66..6845a48b 100644
--- a/.claude/skills/test-evidence-review/SKILL.md
+++ b/.claude/skills/test-evidence-review/SKILL.md
@@ -3,7 +3,7 @@ name: test-evidence-review
description: "Quality review of test files and evidence — goes beyond existence, evaluates assertion coverage. ADEQUATE/INCOMPLETE/MISSING/NOT ASSESSED per story."
argument-hint: "[story-path | sprint | system-name]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/test-evidence-review/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/test-evidence-review/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/review-receipts.sh check *)
model: sonnet
---
@@ -86,10 +86,6 @@ the list of story file paths from the sprint plan.
> all fine*. This skill gates story closure, and `coding-standards.md` marks Logic,
> Integration, Visual/Feel and UI evidence BLOCKING, so a false-clean closes stories nobody
> reviewed.
->
-> This is a recurring shape: the sophisticated inner rule present, the outer
-> boundary unguarded. Ask it of any skill that aggregates —
-> **what does this emit when the set is empty?**
For the resulting story set, collect the fields below with **targeted section
greps, not a full read of each story**:
@@ -121,7 +117,7 @@ contains the story slug or its system. Test files are named per
**Integration stories**: the same, under the integration root (`tests/integration/[system]/`,
`Assets/Tests/PlayMode/`, or Unreal's test root)
- - Also check `production/session-logs/` for playtest records mentioning the story
+ - Also check `production/qa/playtests/` for playtest records mentioning the story
**Visual/Feel and UI stories**: Glob `production/qa/evidence/` for a retained image
(`*.png`, `*.jpg`, `*.gif`) belonging to this story, and for
@@ -219,6 +215,14 @@ default, and a description is an assertion rather than evidence.
For UI stories: require the same retained screenshot of each screen touched.
A walkthrough log is welcome but not required.
+### Evidence older than its code
+
+For each story with a retained image, run
+`bash .claude/scripts/review-receipts.sh check production/qa/evidence/[story-slug]/stamp.txt`.
+List each `CHANGED:` or `GONE:` file as POTENTIALLY STALE — it changed after the
+evidence was captured. `RECEIPT: NONE`: say "no stamp" and use the date check
+below. A report line only: it never changes the story's verdict.
+
### Date coverage
Evidence doc should have a date. If the date is earlier than the story's
@@ -265,7 +269,7 @@ and demoting a real failure behind an access problem would bury it. `WAIVED`
ranks below `ADEQUATE`: the overall verdict reads WAIVED only when every story
in scope was waived, and the report names each waived story either way.
-> Why this needed saying: evidence review **gates story completion**, and
+> Why this matters: evidence review **gates story completion**, and
> `coding-standards.md` makes Logic, Integration, Visual/Feel and UI evidence BLOCKING. A verdict
> vocabulary with no way to express "I could not check" forces every unknown
> into one of three claims about the story — which is how a story nobody
diff --git a/.claude/skills/test-flakiness/SKILL.md b/.claude/skills/test-flakiness/SKILL.md
index 924a7d20..38deb96b 100644
--- a/.claude/skills/test-flakiness/SKILL.md
+++ b/.claude/skills/test-flakiness/SKILL.md
@@ -3,7 +3,7 @@ name: test-flakiness
description: "Find flaky tests from CI logs — aggregates pass rates, spots intermittent failures, recommends quarantine. After multiple runs."
argument-hint: "[ci-log-path | scan | registry]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Bash(bash "*/.claude/skills/test-flakiness/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash(ls -t *), Bash(bash "*/.claude/skills/test-flakiness/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
@@ -159,7 +159,7 @@ Skip mechanisms, by engine — name only the one for the project's engine:
- **Godot (gdUnit4), GDScript**: a skip parameter on the test function —
`func test_x(_do_skip := true, _skip_reason := "flaky: [cause]")`. gdUnit4 reads
the argument names `do_skip` and `skip_reason` (a leading `_` is allowed) in
- `addons/gdUnit4/src/core/GdUnitTestSuiteScanner.gd`, as of gdUnit4 6.1.3;
+ `addons/gdUnit4/src/core/GdUnitTestSuiteScanner.gd`, as of gdUnit4 6.2.2;
confirm them there for the installed version.
- **Godot (gdUnit4), C#**: **NOT SOURCEABLE** — gdUnit4's C# test attributes are
not in the `addons/gdUnit4/` source, and `docs/engine-reference/godot/` does not
diff --git a/.claude/skills/test-helpers/SKILL.md b/.claude/skills/test-helpers/SKILL.md
index dc5b43da..c9e3f65a 100644
--- a/.claude/skills/test-helpers/SKILL.md
+++ b/.claude/skills/test-helpers/SKILL.md
@@ -115,7 +115,9 @@ generic template.
Also read:
- `design/gdd/systems-index.md` — to know which systems exist
-- In-scope GDD(s) — to understand what data types and values need testing
+- In-scope GDD(s) — to understand what data types and values need testing. Read
+ them by section: find the headings you need with the Grep tool (pattern `^#`,
+ content mode) and Read those ranges with offset and limit.
- `docs/architecture/tr-registry.yaml` — to map requirements to tested systems
---
diff --git a/.claude/skills/test-setup/SKILL.md b/.claude/skills/test-setup/SKILL.md
index 8f51e334..468c6264 100644
--- a/.claude/skills/test-setup/SKILL.md
+++ b/.claude/skills/test-setup/SKILL.md
@@ -3,7 +3,7 @@ name: test-setup
description: "Scaffold the test framework and CI — tests/ directory, engine test runner, GitHub Actions workflow. Once, before the first sprint."
argument-hint: "[force]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash, Write, Bash(bash "*/.claude/skills/test-setup/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Bash(grep -q 'com.unity.test-framework' Packages/manifest.json), Bash(bash "*/.claude/skills/test-setup/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
diff --git a/.claude/skills/test-setup/references/2-plan.md b/.claude/skills/test-setup/references/2-plan.md
index 98c5f167..5331f9ba 100644
--- a/.claude/skills/test-setup/references/2-plan.md
+++ b/.claude/skills/test-setup/references/2-plan.md
@@ -38,7 +38,6 @@ already exist at these paths."
**At `collaborative` and `guided`** — do not proceed without approval. These are
**new** files, and `automation-modes.md:81` gates new-file writes in `guided` too,
so the answer is the same in both modes. **At `autonomous`** — create them and log
-the decision; do not block. An unconditional gate here would read as "block even
-in autonomous" and contradict this skill's own header.
+the decision; do not block.
---
diff --git a/.claude/skills/test-setup/references/3-directories.md b/.claude/skills/test-setup/references/3-directories.md
index 20441758..85bc52f7 100644
--- a/.claude/skills/test-setup/references/3-directories.md
+++ b/.claude/skills/test-setup/references/3-directories.md
@@ -107,7 +107,8 @@ script`), so no test ran. A cache older than a new `class_name` fails valid
code with 105. The CI action imports on its own.
Exit code **0** when every test passes and **100** when any fails — verified
-on Godot 4.6.1 with gdUnit4 6.1.3. **101** means every test passed but a test
+on Godot 4.6.1 with gdUnit4 6.1.3 and on Godot 4.7.2 with gdUnit4 6.2.2.
+**101** means every test passed but a test
leaked nodes: a warning, not a failure. 103 and 104 mean gdUnit4 could not run
(headless refused, Godot older than 4.3); 105 means a test script does not parse. `-a res://tests` runs every suite
under `tests/`; `--ignoreHeadlessMode` is required because gdUnit4 otherwise
@@ -127,7 +128,7 @@ Create `tests/integration/.gdignore_placeholder` with content:
Note in the README: **Installing GdUnit4**
```
-1. Open Godot → AssetLib → search "GdUnit4" → Download & Install
+1. Open Godot → Asset Store (AssetLib before Godot 4.7) → search "GdUnit4" → install it
2. Enable the plugin: Project → Project Settings → Plugins → GdUnit4 ✓
3. Restart the editor
4. Verify: res://addons/gdUnit4/bin/GdUnitCmdTool.gd exists (capital U)
diff --git a/.claude/skills/test-setup/references/4-ci.md b/.claude/skills/test-setup/references/4-ci.md
index 1ae1ac74..859e42cd 100644
--- a/.claude/skills/test-setup/references/4-ci.md
+++ b/.claude/skills/test-setup/references/4-ci.md
@@ -39,18 +39,18 @@ jobs:
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@v7
with:
lfs: true
- # godot-version must be a full release such as 4.6.1 (`godot --version`
- # shows it); VERSION.md's "4.6" is not one. version: installed runs the
+ # godot-version must be a full release such as 4.7.2 (`godot --version`
+ # shows it); VERSION.md's "4.7" is not one. version: installed runs the
# gdUnit4 committed in addons/ -- without it the action deletes that
# copy and installs the latest release, which may not match your tests.
- name: Run GdUnit4 Tests
uses: godot-gdunit-labs/gdUnit4-action@v1
with:
- godot-version: '[FULL GODOT VERSION, e.g. 4.6.1]'
+ godot-version: '[FULL GODOT VERSION, e.g. 4.7.2]'
version: 'installed'
paths: |
tests/unit
@@ -59,7 +59,7 @@ jobs:
- name: Upload Test Results
if: always()
- uses: actions/upload-artifact@v4
+ uses: actions/upload-artifact@v7
with:
name: test-results
path: reports/
@@ -85,7 +85,7 @@ jobs:
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@v7
with:
lfs: true
@@ -107,7 +107,7 @@ jobs:
- name: Upload Test Results
if: always()
- uses: actions/upload-artifact@v4
+ uses: actions/upload-artifact@v7
with:
name: test-results
path: test-results/
@@ -139,7 +139,7 @@ jobs:
# ("No such file or directory") when the runner's folder has a space.
steps:
- name: Checkout
- uses: actions/checkout@v4
+ uses: actions/checkout@v7
with:
lfs: true
@@ -165,7 +165,7 @@ jobs:
- name: Upload Logs
if: always()
- uses: actions/upload-artifact@v4
+ uses: actions/upload-artifact@v7
with:
name: test-logs
path: Saved/Logs/
@@ -174,7 +174,10 @@ jobs:
Note: UE CI requires a self-hosted Windows runner with Unreal Editor installed.
The `windows` label keeps the job off any Linux self-hosted runner the
repository also has. Set the `UE_ROOT` environment variable on the runner to the engine folder
-(e.g. `C:/Program Files/Epic Games/UE_5.7`). `[ProjectName]Editor` is the
-editor target in `Source/[ProjectName]Editor.Target.cs`.
+(e.g. `C:/Program Files/Epic Games/UE_5.8`). `[ProjectName]Editor` is the
+editor target in `Source/[ProjectName]Editor.Target.cs`. `actions/checkout@v7`
+and `actions/upload-artifact@v7` run on Node.js 24, which needs Actions Runner
+2.327.1 or newer: update the self-hosted runner before the first run
+(https://github.com/actions/checkout/blob/v7.0.1/README.md).
---
diff --git a/.claude/skills/test-setup/references/6-summary.md b/.claude/skills/test-setup/references/6-summary.md
index 485f8f2e..82691187 100644
--- a/.claude/skills/test-setup/references/6-summary.md
+++ b/.claude/skills/test-setup/references/6-summary.md
@@ -20,7 +20,7 @@ Files created:
- .github/workflows/tests.yml
Next steps:
-1. [Engine-specific install step, e.g., "Install GdUnit4 via AssetLib"]
+1. [Engine-specific install step, e.g., "Install GdUnit4 via the Asset Store (AssetLib before Godot 4.7)"]
2. Write your first test in the engine's test root:
tests/unit/[system]/[system]_[feature]_test.gd (Godot),
Assets/Tests/EditMode/[System]Tests.cs (Unity), or
diff --git a/.claude/skills/ux-design/SKILL.md b/.claude/skills/ux-design/SKILL.md
index 45b48c54..0647dc43 100644
--- a/.claude/skills/ux-design/SKILL.md
+++ b/.claude/skills/ux-design/SKILL.md
@@ -64,7 +64,7 @@ Four authoring modes exist based on the argument:
> Polish gates, and `/architecture-review` all check
> `design/accessibility-requirements.md` at that exact path. Do not "tidy" it
> under `design/ux/`: every one of those checks would stop matching, and the
-> Technical Setup → Pre-Production gate would become unpassable again.
+> Technical Setup → Pre-Production gate would become unpassable.
**If no argument is provided**, do not fail — ask instead. Use `AskUserQuestion`:
- "What are we designing today?"
diff --git a/.claude/skills/ux-design/references/2-gather-context.md b/.claude/skills/ux-design/references/2-gather-context.md
index 82eb59e2..2eea3167 100644
--- a/.claude/skills/ux-design/references/2-gather-context.md
+++ b/.claude/skills/ux-design/references/2-gather-context.md
@@ -18,7 +18,9 @@
- 2i: Present Context Summary
Read all relevant context **before** asking the user anything. The skill's value
-comes from arriving informed.
+comes from arriving informed. Read each GDD and the art bible by section: find the
+headings you need with the Grep tool (pattern `^#`, content mode) and Read those
+ranges with offset and limit.
### 2a: Required Reads
diff --git a/.claude/skills/ux-review/SKILL.md b/.claude/skills/ux-review/SKILL.md
index 9a37fb93..4891f47f 100644
--- a/.claude/skills/ux-review/SKILL.md
+++ b/.claude/skills/ux-review/SKILL.md
@@ -84,7 +84,9 @@ Before validating any spec, load:
(if it exists)
3. The interaction pattern library at `design/ux/interaction-patterns.md` (if
it exists)
-4. The GDDs referenced in the spec's header (read their UI Requirements sections)
+4. The GDDs referenced in the spec's header (read their UI Requirements sections:
+ find the headings with the Grep tool (pattern `^#`, content mode) and Read
+ those ranges with offset and limit)
5. The player journey map at `design/player-journey.md` (if it exists) for
context-arrival validation
diff --git a/.claude/skills/vertical-slice/SKILL.md b/.claude/skills/vertical-slice/SKILL.md
index 79892517..786172a6 100644
--- a/.claude/skills/vertical-slice/SKILL.md
+++ b/.claude/skills/vertical-slice/SKILL.md
@@ -3,7 +3,7 @@ name: vertical-slice
description: "Pre-production validation — end-to-end build to confirm the full loop is achievable before committing to Production. After GDDs, architecture, UX specs."
argument-hint: "[--review full|lean|solo]"
user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/vertical-slice/../../hooks/yaml-helper.sh" resolve_config *)
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/vertical-slice/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
@@ -51,7 +51,10 @@ Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
(collaborative asks always · guided major-only · autonomous logs and proceeds;
`automation_always_ask` categories always prompt).
-Read the following files to understand the full design intent:
+Read the following files to understand the full design intent. Read each GDD, ADR
+and the control manifest by section: find the headings you need with
+the Grep tool (pattern `^#`, content mode) and Read those ranges with offset
+and limit.
- `CLAUDE.md` — tech stack and engine
- `design/gdd/game-concept.md` — core fantasy and game pillars (or
`design/game-brief.md`, the one-page brief that replaces it at `rigor: minimal` —
diff --git a/.claude/statusline.sh b/.claude/statusline.sh
index 99759754..9ec8f948 100644
--- a/.claude/statusline.sh
+++ b/.claude/statusline.sh
@@ -11,16 +11,19 @@
# project, not this one. Resolving to the script's own location first would
# override them. So, in order:
# 1. cwd holds project.yaml -> cwd (a project root)
-# 2. cwd holds .claude/ -> cwd (a project root not yet configured)
-# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment)
+# 2. cwd holds .claude/ -> cwd (a project root not yet configured),
+# unless cwd is itself named .claude: a stray .claude/.claude/ would
+# make .claude/ a root, and the hooks would write .claude/production/
+# 3. CLAUDE_PROJECT_DIR -> that (populated in the hook environment),
+# unless it names a .claude folder, for the same reason as rule 2
# 4. this script's location -> <root>/.claude/hooks/../.. by construction
# Rule 4 always works and needs no environment at all; rules 1-2 stop it from
# overriding a caller that legitimately means somewhere else.
#
# NOT an upward search: that resolves a nested project to its parent's config.
-if [ -f "project.yaml" ] || [ -d ".claude" ]; then
+if [ -f "project.yaml" ] || { [ -d ".claude" ] && [ "${PWD##*/}" != ".claude" ]; }; then
CCGS_ROOT="$PWD"
-elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ] && case "${CLAUDE_PROJECT_DIR%/}" in */.claude|*\\.claude) false ;; *) true ;; esac; then
CCGS_ROOT="$CLAUDE_PROJECT_DIR"
else
CCGS_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)"
diff --git a/.gitattributes b/.gitattributes
index 54899c5e..c6583662 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -4,16 +4,24 @@
# .claude/hooks/*.sh hooks and .claude/scripts/*.sh.
*.sh text eol=lf
+# awk programs the helpers read with `awk -f` (yaml-get.awk). Git Bash gawk
+# tolerates CRLF; mawk and BWK awk may not, so they are checked out LF too.
+*.awk text eol=lf
+
+# .worktreeinclude is a pattern list Claude Code reads when it creates a
+# worktree. A CRLF checkout would end every pattern in \r, and a parser that
+# does not strip it matches nothing, so the local config is silently not copied.
+.worktreeinclude text eol=lf
+
# Tabular data is compared byte-for-byte by tooling that diffs it against
# freshly-generated output (which is always LF). A CRLF checkout would make
# every line differ, silently breaking any such comparison.
*.tsv text eol=lf
-# Markdown under .claude/ is authored LF. Two concrete reasons, both hit during
-# v1.1 development:
+# Markdown under .claude/ is authored LF. Two concrete reasons:
# - tooling that flattens SKILL.md files and substring-matches sentences
-# breaks on a stray \r mid-sentence: every multi-line match fails.
-# Before this was found it produced 262 false "lost rule" reports.
+# breaks on a stray \r mid-sentence: every multi-line match fails, and
+# the tooling then reports rules as lost that are present.
# - a CRLF file produces a whole-file diff the first time anyone edits it,
# which buries real changes.
# .gitattributes governs the INDEX. It does not retro-fix a working tree that
diff --git a/.gitignore b/.gitignore
index aa65a769..f5202eda 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,6 +20,10 @@ production/session-state/
.scratch/
# Per-agent working memory written at runtime — not release material
.claude/agent-memory/
+# Worktrees from the prototyper, isolated subagents and `claude --worktree`.
+# Each is a separate checkout; staging everything would add it as an embedded
+# repository.
+.claude/worktrees/
# === Local sandboxes and scratch work ===
diff --git a/.worktreeinclude b/.worktreeinclude
new file mode 100644
index 00000000..65968cdf
--- /dev/null
+++ b/.worktreeinclude
@@ -0,0 +1,8 @@
+# Gitignored files Claude Code copies into every worktree it creates: the
+# prototyper's, other isolated subagents' and `claude --worktree`. Only files
+# that match a line here AND are gitignored are copied (.gitignore syntax).
+# Local config only. Never list secrets (.env, keys, credentials): a worktree
+# copy is one more place for them to leak from.
+project.local.yaml
+CLAUDE.local.md
+.claude/settings.local.json
diff --git a/CCGS Skill Testing Framework/skills/utility/start.md b/CCGS Skill Testing Framework/skills/utility/start.md
deleted file mode 100644
index 219c3263..00000000
--- a/CCGS Skill Testing Framework/skills/utility/start.md
+++ /dev/null
@@ -1,249 +0,0 @@
-# Skill Test Spec: /start
-
-## Skill Summary
-
-`/start` is the first-time onboarding skill. Phase 1 silently detects project
-state (engine from `project.yaml` or `technical-preferences.md`, concept or
-brief, source code under the engine's code root, prototypes, GDDs, production
-artifacts, and whether `.git/config`'s `origin` still points at the template
-repo). Phase 2 asks where the user is with four `AskUserQuestion` options
-(A No idea yet, B Vague idea, C Clear concept, D Existing work); engine choice
-is not asked here — it is deferred to `/setup-engine`.
-
-Phase 3 routes by answer and names only the immediate next step. Phase 3c asks
-"May I write `project.stage: [stage]` to `project.yaml` (and the legacy mirror
-`production/stage.txt`)?" — one approval that also covers the Phase 3d and 3e
-answers — then writes both and announces them. Phase 3d asks the rigor question and Phase
-3e the automation question, each skipped when the key is already set; each
-answer is written to `project.yaml` straight from the selection. `/start` never
-writes any of the six knobs `modes.rigor` fronts (`modes.review_mode`,
-`modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`,
-`team.size`) or `production/review-mode.txt`. Phase 4 prints the path for the
-chosen rigor — Path D2's retrofit path included — and asks which step to take
-first; Phase 5 prints a single "Type `[skill command]` to begin." line. A
-returning user (engine configured and a concept or brief present) skips
-onboarding. No director gates apply. Verdict: COMPLETE.
-
----
-
-## Static Assertions (Structural)
-
-Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
-
-- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
-- [ ] Has ≥2 phase headings
-- [ ] Contains verdict keyword: COMPLETE
-- [ ] States the write rule for every write it makes: "May I write" before the `project.yaml` write, the same ask naming the `production/stage.txt` legacy mirror; `modes.rigor` and `modes.automation` written as a direct consequence of the user's selection, under that approval
-- [ ] Has a next-step handoff at the end (Phase 5: "Type `[skill command]` to begin.")
-
----
-
-## Director Gate Checks
-
-None. `/start` is a utility setup skill. No director agents exist yet at the
-point this skill runs.
-
----
-
-## Test Cases
-
-### Case 1: Happy Path — Fresh repo, Path A, minimal rigor
-
-**Fixture:**
-- No `project.yaml`, no `production/stage.txt`; `technical-preferences.md`
- holds only placeholders
-- No design docs, prototypes or source code; `origin` is the user's own repo
-- The user picks `A) No idea yet`, approves the `project.yaml` write, then picks
- `Jam / prototype / first game`, then `Guided`
-
-**Input:** `/start`
-
-**Expected behavior:**
-1. Phase 1 detection runs without printing its findings
-2. Phase 2 `AskUserQuestion` offers exactly A–D; no engine question is asked
-3. Path A: explains `/brainstorm` tier-neutrally and names only `/brainstorm open`
- as the next step ("I'll lay out the full path once I know how much process you want")
-4. Phase 3c asks "May I write `project.stage: Concept` to `project.yaml` (and the
- legacy mirror `production/stage.txt`)?",
- saying the file will be created; on approval it creates `project.yaml` from
- the v1.1 minimal template with `project: stage: Concept` (no `modes.rigor`,
- no `modes.review_mode`), writes `Concept` to `production/stage.txt` under
- the same approval, and announces both
-5. Phase 3d offers `Jam / prototype / first game (Recommended)` first (no
- concept → minimal); `modes.rigor: minimal` is written on selection
-6. Phase 3e writes `modes.automation: guided` on selection
-7. Phase 4 prints the minimal 4-step path (`/setup-engine`, `/brainstorm`,
- `/create-stories`, `/dev-story`) and asks which step to take first
-8. Phase 5 prints only "Type `[skill command]` to begin."; verdict COMPLETE
-
-**Assertions:**
-- [ ] Phase 2 offers exactly the four A–D options and no engine choice
-- [ ] `project.yaml` and `production/stage.txt` are written only after the one "May I write" ask that names both
-- [ ] `project.stage` and `production/stage.txt` are both `Concept`
-- [ ] `project.yaml` ends up holding only `project.stage`, `modes.rigor` and `modes.automation` from `/start` — none of the six rigor-fronted knobs — and `production/review-mode.txt` is not written
-- [ ] The recommended rigor option is listed first with ` (Recommended)`
-- [ ] Phase 4 prints the minimal 4-step path
-- [ ] The next skill is not auto-run; Verdict is COMPLETE
-
----
-
-### Case 2: Returning User — Onboarding skipped
-
-**Fixture:**
-- `project.yaml` has `engine.name: Godot` and `modes.rigor: minimal`; no explicit `modes.review_mode`
-- `design/game-brief.md` exists
-
-**Input:** `/start`
-
-**Expected behavior:**
-1. Phase 1 finds the engine configured and the brief present
-2. Skill skips onboarding: "It looks like you're already set up! Your engine is
- Godot and you have … a game brief at `design/game-brief.md`."
-3. Review mode is reported as `solo` (resolved from `modes.rigor: minimal`)
-4. Skill points to `/help` or asks what the user would like to work on
-
-**Assertions:**
-- [ ] The A–D starting-point question is not asked
-- [ ] The message names the configured engine (Godot) and the brief path
-- [ ] Review mode is reported as `solo`, resolved from rigor
-- [ ] No write is made to `project.yaml` or `production/stage.txt`
-
----
-
-### Case 3: Existing Work on Unity — Path D2, stage and rigor already set
-
-**Fixture:**
-- `project.yaml` has `engine.name: Unity`, `modes.rigor: standard` and
- `modes.automation: collaborative`
-- C# scripts exist under `Assets/Scripts/`; `design/gdd/` holds 3 system GDDs;
- no `design/gdd/game-concept.md`, no `docs/architecture/`
-- The user picks `D) Existing work` and approves the `project.yaml` write
-
-**Input:** `/start`
-
-**Expected behavior:**
-1. Phase 1 resolves the code root as `Assets/` for Unity and finds source files
- there (it does not scan `src/` and conclude there is no code)
-2. Phase 3 D shares what it found (source files, 3 design docs, engine Unity)
-3. Sub-case D2: recommends `/project-stage-detect` then `/adopt`, naming
- `/project-stage-detect` as the immediate step; the tiered path waits for
- Phase 4
-4. Phase 3c asks "May I write `project.stage: Systems Design` to
- `project.yaml` (and the legacy mirror `production/stage.txt`)?", then writes `Systems Design` (GDDs, no architecture) to the
- existing `project.yaml` (read first, then edited) and to `production/stage.txt`
-5. Phase 3d prints "Rigor is set to `standard`." and Phase 3e "Automation is set
- to `collaborative`." — neither question is asked
-6. Phase 4 prints the D2 retrofit path at `standard`: `/project-stage-detect`,
- `/adopt`, `/design-system retrofit`, `/architecture-decision retrofit`,
- `/architecture-review`, `/gate-check`
-
-**Assertions:**
-- [ ] Source files are found under `Assets/`, not reported as absent
-- [ ] `/project-stage-detect` and `/adopt` are recommended for D2
-- [ ] Stage `Systems Design` is written to both `project.yaml` and `production/stage.txt`, after the "May I write" ask
-- [ ] The rigor and automation questions are skipped because both keys are set
-- [ ] The D2 retrofit path is printed in Phase 4, including the GDD, ADR and registry retrofit steps
-- [ ] Verdict is COMPLETE
-
----
-
-### Case 4: Clone Still Wired to the Template Repo — remote note, never run
-
-**Fixture:**
-- Fresh project as in Case 1
-- `.git/config` has `[remote "origin"]` with url
- `https://github.com/Donchitos/Claude-Code-Game-Studios.git`
-- The user picks `B) Vague idea` with the hint "a small weekend puzzler"
-
-**Input:** `/start`
-
-**Expected behavior:**
-1. Phase 1 reads `.git/config` as a file and matches the template URL case-insensitively
-2. Path B recommends `/brainstorm a small weekend puzzler` as the immediate step
-3. Phase 3d recommends `Jam / prototype / first game` for the described scope
-4. After the Phase 4 path, the skill adds once: the clone's `origin` still points
- at the Claude Code Game Studios repo, and suggests
- `git remote rename origin template` then `git remote add origin <your repo URL>`
-5. The commands are suggested only — no git command is run
-
-**Assertions:**
-- [ ] The template-origin note appears exactly once, after the path
-- [ ] Both suggested commands are given as written above
-- [ ] No git command is executed (read of `.git/config` only)
-- [ ] The minimal rigor option is the recommended one for the described scope
-
----
-
-### Case 5: Director Gate Check — No gate; start is a utility setup skill
-
-**Fixture:**
-- Fresh project and answers as in Case 1 (`A) No idea yet`, the write approved,
- `Jam / prototype / first game`, `Guided`)
-
-**Input:** `/start`
-
-**Expected behavior:**
-1. Skill completes the onboarding flow through Phase 5
-2. No director agents are spawned at any point
-3. No gate IDs (CD-*, TD-*, AD-*, PR-*) appear in the output
-
-**Assertions:**
-- [ ] No director gate is invoked during the skill execution
-- [ ] No gate skip messages appear (gates are absent, not suppressed)
-- [ ] Skill reaches COMPLETE without any gate verdict
-
----
-
-### Case 6: Path D2 With Rigor Unset — the retrofit path waits for the answer
-
-**Fixture:**
-- `project.yaml` has `engine.name: Godot` and no `modes` block
-- `src/` holds GDScript files; `design/gdd/` holds 4 system GDDs; no
- `docs/architecture/`
-- The user picks `D) Existing work`, approves the `project.yaml` write, then
- picks `Several systems that affect each other` and `Collaborative`
-
-**Input:** `/start`
-
-**Expected behavior:**
-1. Phase 3 D2 names `/project-stage-detect` as the immediate step and prints no
- tiered path yet
-2. Phase 3c asks, then writes `Systems Design`
-3. Phase 3d asks the rigor question, since `modes.rigor` is unset;
- `modes.rigor: standard` is written on selection
-4. Phase 4 prints the D2 retrofit path at `standard`, including
- `/design-system retrofit`, `/architecture-decision retrofit` and
- `/architecture-review` — not the minimal stop after `/adopt` and
- `/setup-engine`
-
-**Assertions:**
-- [ ] No tiered D2 path is printed before Phase 3d has the rigor
-- [ ] The rigor question is asked because the key is unset
-- [ ] Phase 4's D2 path matches the chosen `standard`, with the GDD, ADR and registry retrofit steps
-- [ ] None of the six rigor-fronted knobs is written — only `modes.rigor` and `modes.automation` are added
-
----
-
-## Protocol Compliance
-
-- [ ] Detects project state silently before the first question
-- [ ] Asks the starting-point question via `AskUserQuestion` with options A–D; defers engine choice to `/setup-engine`
-- [ ] Never writes any of the six rigor-fronted knobs (`modes.review_mode`, `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`, `team.size`) or `production/review-mode.txt`
-- [ ] Skips the rigor and automation questions when those keys are already set
-- [ ] Asks "May I write" before the `project.yaml` write, naming `production/stage.txt` in the same ask; announces the stage it wrote; writes rigor/automation only from the user's selection
-- [ ] Prints the Path D2 retrofit path only in Phase 4, after the rigor is known
-- [ ] Never auto-runs the next skill; a completed onboarding run (not the returning-user skip, which ends at its `/help` pointer) ends with "Type `[skill command]` to begin." and Verdict COMPLETE
-
----
-
-## Coverage Notes
-
-- Path C (clear concept, `Formalize it first` vs `Jump straight in`) is not
- separately tested.
-- The `standard` and `full` Phase 4 paths follow Case 1 with the longer
- pipeline; not separately tested.
-- The mismatch note (a rigor that contradicts the described project) and the
- edge cases "picks D but project is empty" / "picks A but code exists" are not
- separately tested.
-- A declined Phase 3c write (neither file written, the stage and the two
- answers kept for the run and reported as not saved) is not separately tested.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a3e23e4b..376b41f5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,284 @@ existing project on the older config files.
---
+## [1.2.0] — 2026-10-19
+
+**The story skills are rebuilt around shared helper scripts, a read guard stops
+whole-file reads of large design docs, the engine references move to Godot 4.7
+and Unreal Engine 5.8, and no skill pre-approves every shell command any more.**
+A minor release. [UPGRADING.md](UPGRADING.md#v113--v120) lists the
+`settings.json` merges, the new files and the renamed `studio-tests/` folder.
+
+### Added
+
+- **Session start says when a newer release is out**, in one line with the
+ release page and how to stop the notice; nothing is downloaded or changed.
+ The hook only reads a per-user cache outside your project. A background job
+ refreshes it by asking GitHub for the latest release at most once a day, so
+ session start never waits and nothing about your project is sent. Turn it off
+ with `/settings --local updates.check=false`, or for the team with
+ `updates.check: false` in `project.yaml`; it is always off when `CI` is set.
+- **A read guard for large design docs.** The new `validate-read.sh` hook
+ refuses a whole-file read of a doc over 40 KB under `design/`,
+ `docs/architecture/` or `production/session-state/` and answers with its
+ headings by line, so the retry reads one section; a ranged read always
+ passes. Coordination rule 6 and most skills that read a GDD, ADR or the art
+ bible now read by section. `features.read_guard: off` (or `false`) turns it off and
+ `features.read_guard_kb` sets the size (#136, #140, suggested by @mamonbleau).
+- **Evidence knows when its code changed.** `/dev-story` writes `stamp.txt`
+ beside a story's retained screenshots, recording the files they prove.
+ `/story-done` and `/test-evidence-review` name each of those files changed
+ since ("re-capture it"), or say "no stamp" for older evidence. They report it
+ and never block on it (#135, proposed by @jiangshoujie).
+- **Stories list their files.** The new story template,
+ `.claude/docs/templates/story.md`, has a `## Files` section: `/create-stories`
+ lists the planned files, `/dev-story` replaces them with the files it changed,
+ and `/story-done` checks scope against the list. Its scope check used to look
+ for a list no story had, so it could not run.
+- **Helper scripts answer what skills worked out by hand.** New scripts in
+ `.claude/scripts/` read story facts, ADR status, a Markdown section to its next
+ heading, the project's stage, the session checkpoint and config writes. The
+ rebuilt skills and `/settings` use them, so the same question gets the same
+ answer each time and a long section is never cut off by a fixed-size grep.
+ More ship alongside them for you to run: bug counts, code markers,
+ sprint arithmetic, tech-debt scores, flaky-test rates, asset checks, content
+ counts, test runs and test scaffolding. Each prints observations, not
+ verdicts, and has `--help`. All but `agent-check.sh` and
+ `compat-inventory.sh`, which need Python 3, need only bash and awk. `resolve_config` also
+ answers six more questions for skill authors (`gate_level`, `engine_values`,
+ `specialists`, `review_gate`, `input_methods`, `perf_budgets`).
+- **Registry checks.** `registry.sh` lists, looks up and validates the three
+ registries and hands out the next ID as the highest ever used plus one, so a
+ retired ID is never reused. It reads the unquoted `status: superseded_by:`
+ lines 1.1.3's `/architecture-decision` wrote, and names each one to quote. The new `validate-registry.sh` hook warns when a
+ write to the entity or TR-ID registry would delete or renumber an entry or set
+ a status the header does not list, and the skills that write a registry
+ validate it afterwards.
+- **Write rules that warn, never block.** `validate-write.sh` flags a write
+ that would replace a file skills never overwrite (an existing `EPIC.md`,
+ `project.godot`, an engine reference doc), set a config value outside its
+ list, cross the prototype boundary or break a localization freeze.
+ `validate-agent-artifact.sh` tells you when a subagent stops without writing
+ the file its brief named.
+- **`/sprint-plan` checks the sprint goal can be shown.** It lists what showing
+ the goal needs (the scene it runs in, the setting that starts it, anything a
+ picked story names but none builds) and reports any gap in a new Goal
+ Prerequisites section and in Risks, without blocking (based on an idea in #76
+ by @FreedomPortal).
+- **Rules for engine scene and asset files**, which a bad hand edit can corrupt.
+ The new path-scoped `.claude/rules/scene-files.md` covers `.tscn`, `.tres`,
+ `.unity`, `.prefab` and `Assets/**/*.asset`: use the editor where you can,
+ never invent a Godot `uid://`, never hand-edit Unity YAML while an Editor is
+ reachable. `settings.json` denies `Edit(**/*.uasset)` and `Edit(**/*.umap)`,
+ which covers writes too.
+- **Agents never file upstream.** Coordination rule 7: no agent files, opens or
+ comments on an issue or pull request in an engine, plugin or vendor
+ repository, even when asked. It writes a draft for you to submit, and
+ `/bug-report` says it drafts only.
+- **`/skill-test static` checks agents and Claude Code-only features**:
+ descriptions close enough to pick the wrong agent, an agent told to ask the
+ user, settings Claude Code ignores, and each place a skill, agent, hook or
+ setting depends on something only Claude Code provides. These never change a
+ verdict. `/skill-test` and `/skill-improve` now say what a pass proves: they
+ read files and never run the skill.
+- **New templates** in `.claude/docs/templates/` for layouts the skills write,
+ from bug reports and certification checklists to `/help` output and
+ `sprint-status.yaml`. `/create-stories` writes from `story.md`; the other
+ skills do not use the new layouts yet. The GDD template is now exactly the
+ skeleton `/design-system` writes, its guidance moved to
+ `guidance/game-design-document-guide.md`.
+
+### Changed
+
+- **Six skills rebuilt to Anthropic's skill-authoring guidance.**
+ `/create-stories`, `/story-readiness`, `/create-epics`, `/dev-story`,
+ `/story-done` and `/start` are shorter: the main path in `SKILL.md`, rare
+ branches in `references/` (`/start` is a single `SKILL.md`), fixed steps in
+ the helper scripts. `/dev-story` and
+ `/story-done` replace 1.1.3's numbered phase files with fewer, named ones, and
+ `/brainstorm` loads its full concept flow only at `standard` and `full`.
+ - `/start` works out the rigor from what you describe and shows it with the
+ stage on one card with a single Save them / Don't save question.
+ - `/create-stories` reports each governing ADR's status before drafting and
+ blocks a story whose ADR depends on one not yet Accepted; `/create-epics`
+ marks a requirement whose only ADR is Proposed, so that block still holds.
+ - `/dev-story` hands every code story's changed files to the engine
+ specialist, and its brief rules out one-off helpers, handling for errors
+ that cannot happen, and values special-cased so a test passes.
+ - `/story-done`'s report carries a **Reviewed by** line that is never blank:
+ `lead-programmer`, `/code-review (you said you ran it; not verified here)`
+ or `self, no independent review` (#135).
+- **Engine references move to Godot 4.7 and Unreal Engine 5.8.** The Godot
+ docs cover 4.7 (latest patch 4.7.2): AreaLight3D, HDR output, the Asset
+ Store, VirtualJoystick, Jolt changes and typed-return overrides. Unreal 5.8
+ (latest hotfix 5.8.3) is recorded across the breaking changes, deprecated
+ APIs, modules and plugins. Unity stays on 6.3 LTS, the newest LTS, and lists 6.4 to
+ 6.6 and the 6.7 beta as newer releases with unconfirmed APIs. Timelines carry
+ vendor-sourced dates; Unreal's pooling sample and GAS tag calls are corrected.
+ Where the 5.8 editor disagrees with Epic's release notes, the Unreal reference
+ says so: MegaLights' tooltip still calls it Experimental and says it needs
+ hardware ray tracing and skips directional lights, and the Iris plugin still
+ carries a Beta flag.
+ Staying on Godot 4.6 or Unreal 5.7? Keep your current engine folder.
+- **CI templates.** `/test-setup` writes `actions/checkout@v7` and
+ `actions/upload-artifact@v7` (a self-hosted runner needs 2.327.1 or newer)
+ and names Godot 4.7.2 and gdUnit4 6.2. On Godot 4.7, `/setup-engine` runs a
+ new project's first import again when it exits 139, a crash on exit after
+ the import has finished.
+- **Worktrees start from your current commit and get your local config.**
+ `settings.json` sets `worktree.baseRef: "head"`, so a worktree (the
+ prototyper's, an isolated subagent's, `claude --worktree`) starts from your
+ commit, not the remote's default branch. The new `.worktreeinclude` copies
+ `project.local.yaml`, `CLAUDE.local.md` and `.claude/settings.local.json` into
+ it, and `.gitignore` ignores `.claude/worktrees/`. The prototyper names its
+ worktree and branch, lists uncommitted files it cannot see and asks you to
+ commit the ones it needs, pulls Git LFS files when the project uses LFS, and
+ says which checks it could not run.
+- **Hooks that did nothing stop running.** `post-compact.sh` is removed: Claude
+ Code discards its output, and `session-start.sh` already restores context.
+ The Stop hook runs in the background, so it no longer holds up a turn, and
+ `notify.sh` fires for permission and idle prompts only.
+- **Agents end their turn with the question.** The 49 agents were told to "wait
+ for yes", which an agent started by a skill cannot do; they now end the turn
+ with the draft and the question for the caller to put to you. `/balance-check`,
+ `/tech-debt` and `/bug-report` do the same when run as a subagent.
+- **`/settings` refuses a bare `testing.strict` other than `true` or `false`**
+ instead of writing it, and suggests the nearest known key and asks before
+ writing an unknown one (#135).
+- **`/prototype` is capped at one day everywhere**; `/team-release` may start
+ `/release-checklist`; `/launch-checklist` runs only when you type it.
+- **The skill and agent spec folder is now `studio-tests/`**, renamed from
+ `CCGS Skill Testing Framework/`. Every skill spec pins the settings its cases
+ assume, and `/settings` has a spec. UPGRADING says how to move your own specs;
+ `/skill-test` and `/skill-improve` say so while the old folder is still there.
+- **`/create-stories` proposes an estimate.** Each story gets a size (`S`, `M`
+ or `L`) that you can change before the stories are written. `/story-readiness`
+ still fails a story with no estimate at `standard` and `full`, and a new story
+ now has one.
+- **`yaml-helper.sh` answers six read-only lookups directly**, run from the
+ project root (`bash .claude/hooks/yaml-helper.sh resolve_setting <key>` and
+ five more); `/settings` and `/perf-profile` use them.
+- **`.gitattributes` keeps awk programs and `.worktreeinclude` LF** on every
+ checkout, `core.autocrlf=true` on Windows included.
+
+### Fixed
+
+- **A repeated key in `project.yaml` is merged and named.** A second `modes:`
+ block wiped the first while the schema check passed. Blocks are now merged,
+ and session start, `/settings` and `resolve_config` name the repeated keys.
+- **A saved review is reused only when nothing it read has changed.**
+ `/architecture-review` reused its last report after an engine upgrade or a
+ TR registry, `architecture.md` or budget change. It now checks every file it
+ read, names a deleted GDD or ADR, and never stands on a narrower report.
+ `/design-review` logs its mode and tier.
+- **`/design-review` checks every place a registry value appears**, so a value
+ restated in a long GDD's tables (an enemy's health, a drop rate) that
+ contradicts the registry is a blocking item with its line number.
+- **`/story-readiness` asks for as many acceptance criteria as
+ `story_granularity` wrote** (coarse 3/2/1, balanced 2/2/1, fine 1), instead of
+ demanding three of a Logic story written at `fine` or `balanced`.
+- **Requirement IDs and ADRs.** `/create-architecture` keeps registered TR-IDs
+ and marks new ones provisional, so a re-run no longer renumbers what stories
+ cite. `/architecture-review` may now Edit, so its appends to
+ `tr-registry.yaml` stop rewriting the whole file. `/architecture-decision`
+ writes the ADR Layer row; without it every ADR counted as critical, turning
+ advisory items into blockers at `standard`. A superseded status is written
+ quoted, as YAML requires.
+- **The commit check** skips GDD copies in `design/gdd/` subfolders such as
+ `archive/` (#133), checks the copy the commit takes, and reads a PowerShell
+ `git add` path with backslashes. `gdd-structure-check.sh` names sections
+ holding only `[To be designed]` as placeholders.
+- **Session start.** A stray `.claude/.claude/` no longer makes hooks write
+ `.claude/production/`, and neither does a `CLAUDE_PROJECT_DIR` that points at
+ `.claude/` itself. The checkpoint preview says when it was written on
+ another branch. "Open bugs" counts only bugs that are not Closed or Verified
+ Fixed. The sparse-design-docs notice counts only the GDDs at the top of
+ `design/gdd/`, as the commit check does, and names the copies in subfolders
+ such as `archive/` that it skipped.
+- **Rotating `active.md` keeps the live checkpoint**; it used to move it into
+ the session log when the file came from the template.
+- **Missing prerequisites name the skill that makes them**: `/dev-story` and
+ `/story-done` with no story point to `/create-stories`, and `/create-epics`
+ stops without `architecture.md` at `standard` and `full`.
+- **`/adopt`'s "help me find them" option works**: it searches by heading,
+ shows where each doc belongs and asks before moving it with `git mv`. At
+ `workflow: minimal`, a project whose code already holds the game is sent to
+ `/reverse-document design [code root]`, not `/brainstorm`.
+- **`/estimate` measures the size and branching it asks for**, from Grep counts
+ reported as an approximation.
+- **A partial check says what it skipped.** A focused `/review-all-gdds` labels
+ its verdict ("consistency only") and does not count as a full review at the
+ Technical Setup gate; `/smoke-check quick` says coverage was not checked, and
+ the Polish and Release gates do not count it. The Pre-Production gate counts
+ an `/architecture-review` report only for what its mode checked: a
+ `single-gdd` or `consistency` report no longer passes the Foundation-gap and
+ engine-audit items, and a report from before 1.2.0, which has no `Mode:`
+ line, counts for none of them.
+- **A stage never advances past a check that could not run.** A gate with a
+ concern and an unrun required check returned CONCERNS, and accepting the
+ concerns moved the stage. `/gate-check` now offers no override until that
+ check runs, and its report names it.
+- **`/sprint-plan` asks before it writes the plan**, even after a "yes, go
+ ahead" to its QA-plan question, which it used to take as approval to write.
+- **Godot no longer imports `production/`.** In a Godot project the evidence
+ screenshots in `production/qa/evidence/`, and the `.wav` Movie Maker writes
+ beside them, were imported as game resources with `.import` files, and a
+ default export packed them into the game. The new `production/.gdignore`
+ makes Godot skip the folder.
+- **Playtest records count as test evidence.** `/story-done`,
+ `/test-evidence-review` and `/qa-plan` looked for them in
+ `production/session-logs/`, which is gitignored. They now read
+ `production/qa/playtests/`, where `/playtest-report` writes them.
+- **`/help` and `/gate-check` see when stories are missing.** Two `EPIC.md`
+ files counted as the two story files the Create Stories step needed, so the
+ step read as done before any story existed.
+- **ADR cycles name only the ADRs on the cycle.** `adr-dep-graph.sh` also
+ listed every ADR that depends on a cycle, so the advice was to cut a
+ legitimate dependency. It now also prints a build order and names a Depends On
+ row still holding the template text, instead of reading it as no dependency.
+- **`/architecture-review single-gdd` writes only that system.** Its "write all
+ three files" replaced the project-wide traceability index with one system's
+ rows and could propose retiring other systems' requirements. A review with no
+ ADRs now reports NOT ASSESSED instead of stopping without a report, and the
+ argument hint lists `rtm`.
+- **The architecture skills.** `/architecture-decision` reads the ADRs still to
+ write from `architecture.md`'s Required ADRs, and writes the first entry of an
+ empty registry section as valid YAML. `/create-architecture` says no system
+ goes in the Platform layer, which has no manifest rules.
+- **`/setup-engine` on a new Godot project** reports the gdUnit4 runner it names
+ in `commands.test` as expected until `/test-setup` installs it, instead of
+ asking you to resolve it. It no longer expects `/brainstorm` to recommend an
+ engine: `/brainstorm` records your preference and never recommends one.
+- **Review receipts written on Windows read correctly on Linux and macOS.** A
+ receipt with Windows line endings read every file as CHANGED there.
+- **Pointers to sections that no longer exist** in `/gate-check`,
+ `/setup-engine`, `/create-architecture` and `/create-stories` name the right
+ ones.
+- **A multi-line value in `project.yaml` is read as text.** The lines under a
+ `|` or `>` value were read as settings: a note holding `review_mode: full`
+ could change the review mode, and a `stage:` line in one was reported as an
+ invalid stage. Every reader, the stage writer and `/settings` now skip that
+ text; `/settings` will not overwrite a multi-line value.
+
+### Security
+
+- **Skills pre-approve only the commands they run.** A bare `Bash` entry in
+ `allowed-tools` let 34 skills run any shell command without asking in the
+ default permission mode. Each now names the framework scripts and read-only
+ commands its text runs. Anything else, including your `commands.test`, asks
+ first: approve it once, or add `Bash(<your command> *)` to
+ `.claude/settings.local.json`. A skill you keep your own copy of needs the
+ shipped `allowed-tools:` line.
+- **Tagging, merging and deploying are flagged before they run.** The push check
+ also warns on `git tag`, `git merge`, `gh release`, `butler push` and
+ `steamcmd +run_app_build`, which `/hotfix` and `/team-release` ask about first.
+- **The same `.env` protection with fewer rules.** The three Bash `.env` deny
+ rules are gone: `Read(**/.env*)` and `Edit(**/.env*)` already cover Bash file
+ commands and redirects. `settings-local-template.md` no longer suggests
+ `Bash(git *)`, which approves `git push` too.
+
+---
+
## [1.1.3] — 2026-10-08
**Long skills keep their later steps through a long session, a question nobody
diff --git a/CLAUDE.md b/CLAUDE.md
index 60359288..d9292fbd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,7 +36,7 @@ naming, platform, performance, modes. Skills resolve it via `resolve_config`
(see `.claude/docs/config-resolution.md`).
`.claude/docs/technical-preferences.md` is the **legacy fallback**, read on demand
-when a key is absent from `project.yaml`. It is no longer imported here: before
+when a key is absent from `project.yaml`. It is not imported here: before
`/setup-engine` runs it is almost entirely `[TO BE CONFIGURED]` placeholders, and
after it runs `project.yaml` holds the real values.
diff --git a/README.md b/README.md
index fe1b1228..d73112ea 100644
--- a/README.md
+++ b/README.md
@@ -11,8 +11,8 @@
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
<a href=".claude/agents"><img src="https://img.shields.io/badge/agents-49-blueviolet" alt="49 Agents"></a>
<a href=".claude/skills"><img src="https://img.shields.io/badge/skills-74-green" alt="74 Skills"></a>
- <a href=".claude/hooks"><img src="https://img.shields.io/badge/hooks-12-orange" alt="12 Hooks"></a>
- <a href=".claude/rules"><img src="https://img.shields.io/badge/rules-13-red" alt="13 Rules"></a>
+ <a href=".claude/hooks"><img src="https://img.shields.io/badge/hooks-15-orange" alt="15 Hooks"></a>
+ <a href=".claude/rules"><img src="https://img.shields.io/badge/rules-14-red" alt="14 Rules"></a>
<a href="https://code.claude.com/docs"><img src="https://img.shields.io/badge/built%20for-Claude%20Code-f5f5f5?logo=anthropic" alt="Built for Claude Code"></a>
<a href="https://www.buymeacoffee.com/donchitos3"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support%20this%20project-FFDD00?logo=buymeacoffee&logoColor=black" alt="Buy Me a Coffee"></a>
<a href="https://github.com/sponsors/Donchitos"><img src="https://img.shields.io/badge/GitHub%20Sponsors-Support%20this%20project-ea4aaa?logo=githubsponsors&logoColor=white" alt="GitHub Sponsors"></a>
@@ -56,9 +56,9 @@ The result: you still make every decision, but now you have a team that asks the
|----------|-------|-------------|
| **Agents** | 49 | Specialized subagents across design, programming, art, audio, narrative, QA, and production |
| **Skills** | 74 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics`, `/create-stories`, `/dev-story`, `/story-done`, etc.) |
-| **Hooks** | 12 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit trail, and gap detection |
-| **Rules** | 13 | Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, and more |
-| **Templates** | 39 | Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more |
+| **Hooks** | 15 | Automated validation on commits, pushes, asset changes, design-doc reads, writes and registries, session lifecycle, agent audit trail, and gap detection |
+| **Rules** | 14 | Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, scene and asset files, and more |
+| **Templates** | 62 | Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more |
## Studio Hierarchy
@@ -201,7 +201,7 @@ Hooks fail gracefully if optional tools are missing — you just lose validation
Or jump directly to a specific skill if you already know what you need:
- `/brainstorm` — explore game ideas from scratch
- - `/setup-engine godot 4.6` — configure your engine if you already know
+ - `/setup-engine godot 4.7` — configure your engine if you already know
- `/project-stage-detect` — analyze an existing project
## Configuration
@@ -265,13 +265,14 @@ CLAUDE.md # Master configuration
settings.json # Hooks, permissions, safety rules
agents/ # 49 agent definitions (markdown + YAML frontmatter)
skills/ # 74 slash commands (subdirectory per skill)
- hooks/ # 14 scripts (bash) — 12 event hooks, yaml-helper.sh,
- # and one opt-in diagnostic you wire yourself
- rules/ # 13 path-scoped coding standards
+ hooks/ # 18 scripts (bash) — 15 event hooks, two helpers they
+ # source (yaml-helper.sh, update-check.sh), and one
+ # opt-in diagnostic you wire yourself
+ rules/ # 14 path-scoped coding standards
statusline.sh # Status line script (context%, model, stage, epic breadcrumb)
docs/
workflow-catalog.yaml # 7-phase pipeline definition (read by /help)
- templates/ # 39 document templates (+ per-section guidance)
+ templates/ # 62 document templates (+ per-section guidance)
src/ # Game source code (Godot). The code root is
# ENGINE-SPECIFIC: Unity compiles only
# Assets/, Unreal builds from Source/<Module>/
@@ -282,12 +283,12 @@ tests/ # Test suites (unit, integration, performanc
tools/ # Build and pipeline tools
prototypes/ # Throwaway prototypes (isolated from src/)
production/ # Sprint plans, milestones, release tracking
-CCGS Skill Testing Framework/ # QA for the skills and agents themselves — see below
+studio-tests/ # QA for the skills and agents themselves — see below
```
### Testing your customizations
-CCGS is a template you are meant to edit. `CCGS Skill Testing Framework/` is how
+CCGS is a template you are meant to edit. `studio-tests/` is how
you check that an edited or newly written skill still holds up — a catalog of all
74 skills and 49 agents, per-category quality rubrics, behavioral specs, and
templates for writing specs of your own.
@@ -339,19 +340,22 @@ auto mode.
| Hook | Trigger | What It Does |
|------|---------|--------------|
| `validate-commit.sh` | PreToolUse (Bash, PowerShell) | Checks for hardcoded values, TODO format, JSON validity, design doc sections — exits early if the command is not `git commit` |
-| `validate-push.sh` | PreToolUse (Bash, PowerShell) | Warns on pushes to protected branches — exits early if the command is not `git push` |
+| `validate-push.sh` | PreToolUse (Bash, PowerShell) | Warns on pushes to protected branches, and on `git tag`, `git merge`, `gh release`, `butler push` and `steamcmd +run_app_build` — exits early for any other command |
+| `validate-read.sh` | PreToolUse (Read) | Refuses a whole-file read of a design doc over 40 KB and answers with its headings, so the retry reads one section (`features.read_guard`) |
+| `validate-write.sh` | PreToolUse (Write/Edit) | Warns, never blocks, when a write would break a rule the skills state: a file they never overwrite, the config guard, the prototype boundary, a localization freeze |
+| `validate-registry.sh` | PreToolUse (Write/Edit) | Warns when a write to the entity or TR-ID registry would delete or renumber an entry, or set a status its header does not list |
| `validate-assets.sh` | PostToolUse (Write/Edit) | Checks data-file JSON under `assets/`, `Assets/` or `Content/`, and asset naming in Godot's `assets/` only — exits early if the file is under none of them |
| `session-start.sh` | Session open | Shows current branch and recent commits for orientation |
| `detect-gaps.sh` | Session open | Detects fresh projects (suggests `/start`) and missing design docs when code or prototypes exist |
| `pre-compact.sh` | Before compaction | Logs the compaction (its output does not reach Claude — `session-start.sh` restores context afterwards) |
-| `post-compact.sh` | After compaction | Debug-log reminder only (its output does not reach Claude) |
-| `notify.sh` | Notification event | Shows Windows toast notification via PowerShell |
-| `session-stop.sh` | Every response end | Archives `active.md` to session log and records git activity |
+| `notify.sh` | Permission prompt, or idle about a minute | Shows Windows toast notification via PowerShell |
+| `session-stop.sh` | Every response end, in the background | Archives `active.md` to session log and records git activity |
| `log-agent.sh` | Agent spawned | Audit trail start — logs subagent invocation |
| `log-agent-stop.sh` | Agent stops | Audit trail stop — completes subagent record |
+| `validate-agent-artifact.sh` | Agent stops | Warns when a subagent stops without writing the file its brief named |
| `validate-skill-change.sh` | PostToolUse (Write/Edit) | Advises running `/skill-test` after any `.claude/skills/` change |
-> **Note**: `validate-commit.sh`, `validate-assets.sh`, and `validate-skill-change.sh` fire on every Bash, PowerShell or Write tool call and exit immediately (exit 0) when the command or file path is not relevant. This is normal hook behavior — not a performance concern.
+> **Note**: `validate-commit.sh`, `validate-push.sh`, `validate-read.sh`, `validate-write.sh`, `validate-registry.sh`, `validate-assets.sh` and `validate-skill-change.sh` fire on every Bash, PowerShell, Read, Write or Edit tool call and exit immediately (exit 0) when the command or file path is not relevant. This is normal hook behavior — not a performance concern.
**Permission rules** in `settings.json` auto-allow test runs and block dangerous operations (force push, `rm -rf`, reading `.env` files) in both the Bash and PowerShell tools. Read-only commands such as `git status`, `git log` and `ls` need no rule: Claude Code runs them without asking. The `git` rules match anywhere after `git`, so a git command whose text only mentions `push` followed later by ` +` or ` -f`, `clean` followed by ` -f`, or `reset` followed by `--hard` — a commit message such as `git commit -m "push + pull"` included — is denied too: reword the message.
@@ -375,6 +379,7 @@ C# under `Assets/Tests/` and C++ under `Source/**/Tests/`.
| `design/narrative/**` | Lore consistency, character voice, canon levels |
| `assets/data/**/*.json` | JSON validity, naming conventions, schema rules |
| `assets/shaders/**` | Naming conventions, performance targets, cross-platform rules |
+| `**/*.tscn`, `**/*.tres` | Scene and resource files changed in the editor where possible; safe hand-edit rules |
| `tests/**` | Test naming, coverage requirements, fixture patterns |
| `prototypes/**` | Relaxed standards, README required, hypothesis documented |
diff --git a/UPGRADING.md b/UPGRADING.md
index 57669b19..c083ad75 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -18,6 +18,7 @@ of the template to the next.
## Table of Contents
- [Upgrade Strategies](#upgrade-strategies)
+- [v1.1.3 → v1.2.0](#v113--v120)
- [v1.1.2 → v1.1.3](#v112--v113)
- [v1.1.1 → v1.1.2](#v111--v112)
- [v1.1.0 → v1.1.1](#v110--v111)
@@ -45,8 +46,8 @@ your repo shares history with the template.
# Add the template as a remote (one-time setup; skip this if `git remote -v` already lists template)
git remote add template https://github.com/Donchitos/Claude-Code-Game-Studios.git
-# Fetch the new version
-git fetch template main
+# Fetch the new version and its release tag
+git fetch --tags template main
# Merge into your branch
git merge template/main
@@ -172,6 +173,222 @@ Best when: you didn't use git to set up the template (just downloaded a zip).
---
+## v1.1.3 → v1.2.0
+
+**Released:** 2026-10-19
+**Commit range:** `v1.1.3..v1.2.0`
+**Key themes:** The story skills rebuilt around shared helper scripts; a read
+guard for large design docs; Godot 4.7 and Unreal Engine 5.8 references; skills
+pre-approve only the commands they run
+
+### What Changed
+
+| Category | Changes |
+|----------|---------|
+| **Config helper** | `yaml-helper.sh` runs six read-only lookups directly (`bash .claude/hooks/yaml-helper.sh resolve_setting <key>` and five more), from the project root; `/settings` and `/perf-profile` call it that way |
+| **Hooks** | `post-compact.sh` removed: its output never reached Claude. `pre-compact.sh` only logs the compaction. `session-stop.sh` runs in the background and prints nothing. `notify.sh` fires for permission and idle prompts only |
+| **New hooks** | `validate-read.sh` refuses a whole-file read of a design doc over 40 KB and answers with its headings, so the retry reads one section (`features.read_guard: off` turns it off, `features.read_guard_kb` sets the size). `validate-write.sh` and `validate-registry.sh` warn, never block, when a write would break a rule the skills state (a file they never overwrite, the prototype boundary, an append-only registry). `validate-agent-artifact.sh` warns when a subagent stops without writing the file its brief named |
+| **Update alert** | Session start prints one line when a newer release is out. It asks GitHub at most once a day, in the background, and never waits; `updates.check: false` in `project.yaml` or `project.local.yaml` turns it off, and CI runs never ask |
+| **Worktrees** | `settings.json` sets `worktree.baseRef` to `"head"`, so a worktree (the prototyper's, an isolated subagent's, `claude --worktree`) starts from your current commit, not the remote's default branch. The new `.worktreeinclude` copies `project.local.yaml`, `CLAUDE.local.md` and `.claude/settings.local.json` into each one. The prototyper names uncommitted files its worktree can't see, and says which of its checks it could not run |
+| **Rules** | New `.claude/rules/scene-files.md`: engine scene and asset files (`.tscn`, `.tres`, `.unity`, `.prefab`, `Assets/**/*.asset`) are changed in the editor where possible |
+| **Templates** | New layouts in `.claude/docs/templates/`: bug reports, launch and certification checklists, patch notes, start paths and more. `/create-stories` writes stories from `story.md`; the other skills do not use the new layouts yet |
+| **Permissions** | `settings.json`: the three Bash `.env` deny rules removed; `Read(**/.env*)` and `Edit(**/.env*)` already cover them. No skill pre-approves bare `Bash` any more: 34 skills now pre-approve only the commands their text runs (framework scripts, `git log` and the like). A command a skill does not name, such as your `commands.test`, asks first; approve it once, or add `Bash(<your command> *)` to `.claude/settings.local.json` |
+| **Git** | `.gitignore` ignores `.claude/worktrees/` |
+| **Docs** | `settings-local-template.md` uses the current permission mode names and narrower example rules |
+| **Skill testing** | `CCGS Skill Testing Framework/` is renamed `studio-tests/`. `/skill-test`, `/skill-improve` and the `spec:` paths in its `catalog.yaml` use the new name; the two skills say so while the old folder is still there |
+| **Skills** | `/create-stories`, `/story-readiness`, `/create-epics`, `/dev-story`, `/story-done` and `/start` are rebuilt: shorter, with rarely used branches moved to each skill's `references/` folder (`/start` stays one `SKILL.md`) and fixed steps handed to scripts in `.claude/scripts/`. `/dev-story` and `/story-done` replace 1.1.3's numbered phase files with fewer, named ones. `/start` works out the rigor from what you describe and shows it on one card with a single save question, instead of asking for it. `/brainstorm`'s full concept path moved to `references/full-concept.md` |
+| **Stories** | New story template `.claude/docs/templates/story.md` with a `## Files` section: `/create-stories` lists the planned files, `/dev-story` replaces the list with the files it changed, and `/story-done` checks scope against it. `/create-stories` proposes an estimate (`S`, `M` or `L`) for each story, which you can change before it writes them |
+| **Evidence** | `/dev-story` writes `stamp.txt` beside a story's screenshots. `/story-done` names any of the story's files that changed after the evidence was captured; it reports this and never blocks on it |
+| **Gates** | The Technical Setup → Pre-Production gate reads each `/architecture-review` report's `Mode:` line and counts the report only for what that mode checked. Reports written by 1.1.3 have no `Mode:` line and count for nothing, so run `/architecture-review` once after upgrading, before that gate |
+| **Engine references** | `docs/engine-reference/` now covers Godot 4.7 (was 4.6) and Unreal Engine 5.8 (was 5.7). Unity stays on 6.3 LTS, the newest LTS, and records 6.4 to 6.6 and the 6.7 beta. Release timelines carry vendor-sourced dates |
+| **CI templates** | `/test-setup` writes `actions/checkout@v7` and `actions/upload-artifact@v7` (was `@v4`), names Godot 4.7.2 and gdUnit4 6.2, and `game-ci/unity-test-runner@v4` now resolves to v4.4.0 |
+
+---
+
+### Files: Safe to Overwrite
+
+**Existing files to overwrite (no user content), and new files to add:**
+```
+.claude/hooks/*.sh ← take the whole folder: 13 hooks
+ changed, yaml-helper.sh among
+ them, and 5 are new. Take
+ .claude/scripts/ in the same
+ step: the hooks call its helpers
+.claude/scripts/** ← 25 new helper scripts, 7 changed
+.claude/statusline.sh
+.claude/skills/** ← if you edited a skill, see
+ Merge Carefully
+.claude/agents/*.md ← all 49 changed; if you edited
+ one, see Merge Carefully
+.claude/docs/** ← EXCEPT technical-preferences.md,
+ which is yours and unchanged in
+ 1.2.0
+.claude/rules/scene-files.md ← new
+docs/WORKFLOW-GUIDE.md
+docs/engine-reference/<engine>/ ← unless your project stays on
+ Godot 4.6 or Unreal 5.7; see
+ Merge Carefully
+README.md, CHANGELOG.md, UPGRADING.md ← keep your README if it is your
+ game's
+studio-tests/ ← renamed from CCGS Skill Testing
+ Framework/; if you wrote specs
+ there, see Merge Carefully
+production/.gdignore ← new: Godot skips production/
+```
+
+In a Godot project, after adding `production/.gdignore`, delete the .import files Godot made under `production/`
+(`find production -name '*.import' -delete`): Godot imported the evidence screenshots there as game resources,
+and a default export packed them into the game.
+
+With Strategy A2, also check out what this release changes outside `.claude`
+(your README aside): `git checkout template/main -- studio-tests production/.gdignore .worktreeinclude docs/WORKFLOW-GUIDE.md`.
+
+Take `.claude/hooks/` whole, not only its new files: a 1.1.3 `yaml-helper.sh`
+answers the new lookups (`resolve_setting modes.rigor` and the rest) with its
+usage line, so `/settings`, `/perf-profile` and the command the update notice
+prints stop working, and the rebuilt skills lose their review and gate lines.
+
+---
+
+### Files: Merge Carefully
+
+**Strategy A:** the merge has already made these changes wherever git could,
+which is every file you never edited. Check each item instead of making it
+again (a hook entry added twice runs twice). The steps are for files that
+conflicted, and for Strategies A2 and C.
+
+**`.claude/settings.json`** — if you have not edited it, overwrite it with the
+shipped file. If you have:
+
+- Delete the `"PostCompact"` entry under `hooks`, and delete
+ `.claude/hooks/post-compact.sh`. Do both: an entry left pointing at the
+ deleted script fails on every compaction.
+- Under `"Stop"`, add `"async": true` to the `session-stop.sh` hook.
+- Under `"Notification"`, change `"matcher": ""` to
+ `"matcher": "permission_prompt|idle_prompt"`.
+- Remove `Bash(*>.env*)`, `Bash(cat *.env*)` and `Bash(type *.env*)` from
+ `deny`. Keep `Read(**/.env*)` and `Edit(**/.env*)`, which cover Bash file
+ commands and redirects to `.env` files, and keep the two PowerShell `.env`
+ rules.
+- Add `Edit(**/*.uasset)` and `Edit(**/*.umap)` to `deny`. They stop Unreal's
+ binary assets being edited or overwritten as text, which corrupts them; an
+ `Edit(...)` rule covers writes too.
+- Add the four new hooks, copying each entry from the shipped file: under
+ `"PreToolUse"`, a `"Write|Edit"` entry running `validate-registry.sh` and
+ `validate-write.sh`, and a `"Read"` entry running `validate-read.sh`; under
+ `"SubagentStop"`, `validate-agent-artifact.sh` after `log-agent-stop.sh`.
+ Take `.claude/hooks/` and `.claude/scripts/` (Safe to Overwrite) first: an
+ entry pointing at a missing script fails every time it fires, and the four
+ hooks call helpers in `.claude/scripts/`, so without them every Read and
+ Write prints "guard skipped".
+- Add `"worktree": { "baseRef": "head" }` at the top level. Without it, Claude
+ Code makes each worktree from the remote's default branch, so a prototype or
+ isolated subagent works on code without your local commits.
+
+**`.gitignore`** — add `.claude/worktrees/`. Without it, a worktree made by the
+prototyper, an isolated subagent or `claude --worktree` shows up as untracked
+files, and `git add -A` stages it as an embedded repository.
+
+**`.worktreeinclude`** (new, at the root) — take it. It lists the gitignored
+local config Claude Code copies into each new worktree. If you add lines, add
+only local config, never secrets such as `.env` or keys.
+
+**`.gitattributes`** — add `*.awk text eol=lf` and `.worktreeinclude text eol=lf`.
+They keep both LF on every checkout, including `core.autocrlf=true` on Windows:
+mawk and BWK awk may misread an awk program with carriage returns, and a CRLF
+`.worktreeinclude` leaves every pattern ending in one, so nothing is copied.
+
+**`project.yaml`** — optionally set `framework.version: 1.2.0`. Nothing reads it
+for this release: the update alert compares against the version stamp in
+`.claude/hooks/update-check.sh`, which arrives with the hooks folder. Leave
+`updates.check` and `features.read_guard` unset to keep their defaults (on).
+
+**`CLAUDE.md`** — one wording change in the Technical Preferences paragraph;
+nothing to do if you edited the file.
+
+**`.claude/settings.local.json`** — if you copied `Bash(git *)` from the old
+`settings-local-template.md`, it approves every git command, `git push`
+included. Narrow it to the commands you mean, such as `Bash(git add *)` and
+`Bash(git commit *)`.
+
+**`studio-tests/`** — the renamed `CCGS Skill Testing Framework/`, same layout.
+If you never changed anything in the old folder, take the new one and delete
+the old one. If you wrote or edited specs there, move them to the same path
+under `studio-tests/`, and in `studio-tests/catalog.yaml` change their `spec:`
+paths from `CCGS Skill Testing Framework/` to `studio-tests/`. Then delete the
+old folder: `/skill-test` and `/skill-improve` only read the new one.
+
+**`.claude/skills/` and `.claude/scripts/`** — take the rebuilt skill folders
+whole (`create-stories`, `story-readiness`, `create-epics`, `dev-story`,
+`story-done`, `start`, `brainstorm`), and take `.claude/scripts/` with them: they
+call scripts 1.1.3 did not have (`adr-status.sh`, `story-facts.sh`,
+`md-section.sh`, `session-state.sh`, `write-guard.sh`, `project-state.sh`,
+`set-stage.sh`, `config-set.sh`). If you edited one of these skills, make your
+edit again on the new text; the step it changed may now be in the skill's
+`references/` folder.
+
+If you keep your own copy of any other skill, take the shipped `allowed-tools:`
+line into it: 34 skills replaced a bare `Bash` grant there, and a kept copy
+still pre-approves every shell command while it runs.
+
+**`docs/engine-reference/<engine>/`** — take the folder if your project uses
+the newer engine (Godot 4.7, Unreal 5.8) or has not pinned one yet. If your
+project stays on Godot 4.6 or Unreal 5.7, keep your current folder for that
+engine: the new one describes APIs your editor does not have. With Strategy A
+the merge takes the new folder without asking; only a file you edited (usually
+`VERSION.md`) conflicts. To keep yours, run `git checkout HEAD -- docs/engine-reference/<engine>/` before you commit the merge. Either way, run
+`/setup-engine` again afterwards so `Installed at pin time` records your editor.
+
+**`.github/workflows/`** — a workflow `/test-setup` already wrote is not changed.
+To move it to the current actions, change `actions/checkout@v4` and
+`actions/upload-artifact@v4` to `@v7`. On a self-hosted runner (the Unreal
+template), update the runner to 2.327.1 or newer first: v7 runs on Node.js 24.
+
+**`.claude/agents/`** — all 49 agent files changed: an agent ends its turn with
+its question instead of waiting for a yes it cannot receive, the GDScript, Unity,
+Unreal and Blueprint specialists leave scene and asset files to the editor, the engine agents follow the
+new engine versions, and the prototyper checks what its worktree cannot see. Take
+the folder; if you edited an agent, make your edit again on the new text.
+
+**Your registries** (`design/registry/entities.yaml`,
+`docs/architecture/tr-registry.yaml`, `docs/registry/architecture.yaml`) — keep
+yours: they hold your project's entries. The shipped files gained `# LAYOUT:`
+comment lines in their headers describing the shape `.claude/scripts/registry.sh`
+reads; copy them into your header if you like. Nothing reads the comment.
+1.1.3's `/architecture-decision` wrote a replaced entry in
+`docs/registry/architecture.yaml` as `status: superseded_by: ADR-NNNN`, without
+quotes. Quote each one: `status: "superseded_by: ADR-NNNN"`. Unquoted, the second
+colon makes the file invalid YAML. `registry.sh` still reads the old form and
+prints an `UNQUOTED` row naming each line to change.
+
+**`.claude/docs/templates/sprint-plan.md`** — take it. It gains a
+`## Goal Prerequisites` section that `/sprint-plan` fills; sprint plans you
+already wrote need no change.
+
+**Your existing stories and evidence** need no change. A story written before
+1.2.0 has no `## Files` section, so `/story-done` checks its scope against the
+session checkpoint's files in progress, or reports scope as NOT ASSESSED. Add
+the section by hand (one changed file per line) to get the check. Evidence
+captured before 1.2.0 has no `stamp.txt`, and `/story-done` says "no stamp"
+instead of whether the code changed after it.
+
+---
+
+### Files: Delete
+
+```
+.claude/hooks/post-compact.sh → removed; delete its PostCompact entry in settings.json too
+CCGS Skill Testing Framework/ → renamed studio-tests/; move any specs you wrote first (above)
+.claude/skills/dev-story/references/2-load-context.md, 3-route.md, 4-implement.md,
+ 5-test-evidence.md, 6-collect.md, 7-session-state.md
+ → replaced by engine-checks.md and version-mismatch.md
+.claude/skills/story-done/references/1-find-story.md, 2-read-story.md, 3-verify-criteria.md,
+ 4-deviations.md, 5-code-review-gate.md, 6-completion-report.md, 7-update-status.md,
+ 8-next-story.md → replaced by review-gates.md, sprint-next.md and tech-debt-row.md
+```
+
+---
+
## v1.1.2 → v1.1.3
**Released:** 2026-10-08
diff --git a/design/registry/entities.yaml b/design/registry/entities.yaml
index 216ffa67..dfeacb02 100644
--- a/design/registry/entities.yaml
+++ b/design/registry/entities.yaml
@@ -45,6 +45,13 @@
# FORMAT: YAML. Consistent indentation is critical for grep reliability.
# Sections: entities | items | formulas | constants
# Each entry: name, status, source, referenced_by[], attributes{}, added, revised
+#
+# LAYOUT: the one shape .claude/scripts/registry.sh reads. Each section is a
+# key at column 0 holding a block list, or [] while it is empty. Each entry
+# starts "- name: <name>" with the dash at column 2 (or 0, the same for every
+# entry of a section); its fields sit two columns past the dash, and a deeper
+# line belongs to the field above it. Quote a value that holds ": ". A line
+# in any other shape is reported as unsupported layout, with its number.
version: 1
last_updated: ""
diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md
index 1de66133..8bab85ce 100644
--- a/docs/WORKFLOW-GUIDE.md
+++ b/docs/WORKFLOW-GUIDE.md
@@ -3,7 +3,7 @@
> **How to go from zero to a shipped game using the Agent Architecture.**
>
> This guide walks you through every phase of game development using the
-> 49-agent system, 74 slash commands, and 12 automated hooks. It assumes you
+> 49-agent system, 74 slash commands, and 15 automated hooks. It assumes you
> have Claude Code installed and are working from the project root.
>
> The pipeline has 7 phases. At `rigor: standard` and `full`, each phase has
@@ -65,8 +65,8 @@ This guided onboarding asks where you are and routes you to the right phase:
- **Path B** -- Vague idea: routes to `/brainstorm` with seed
- **Path C** -- Clear concept: routes to `/brainstorm` to write it down, or
straight to `/setup-engine`
-- **Path D1** -- Existing project, few artifacts: normal flow
-- **Path D2** -- Existing project, GDDs/ADRs exist: runs `/project-stage-detect`
+- **Path D** -- Existing work: routes to `/setup-engine` when no engine is set
+ and there is no more than a concept; otherwise to `/project-stage-detect`,
then `/adopt` for brownfield migration
### Step 3: Verify Hooks Are Working
@@ -150,8 +150,8 @@ production/ # Sprint plans, milestones, releases
## The Default Path: Rigor Minimal
-`modes.rigor` defaults to `minimal` (`/start` asks which tier fits; `/settings`
-changes it any time). At `minimal` the path to code is four steps:
+`modes.rigor` defaults to `minimal` (`/start` infers the tier from your description and shows it
+before saving; `/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`, which replaces
@@ -196,7 +196,7 @@ with defined pillars and a player journey. This is where you figure out
|
v
/prototype
- (concept prototype — 1-3 days)
+ (concept prototype — 1 day max)
PROCEED ↓ PIVOT → /brainstorm
|
v (PROCEED)
@@ -261,7 +261,7 @@ Validates structure and completeness before you proceed.
Or with a specific engine:
```
-/setup-engine godot 4.6
+/setup-engine godot 4.7
```
**What /setup-engine does:**
@@ -1399,22 +1399,25 @@ Tier 3 (Specialists): gameplay-programmer, engine-programmer,
### Automated Hooks (Safety Net)
-The system has 12 hooks that run automatically:
+The system has 15 hooks that run automatically:
| Hook | Trigger | What It Does |
|------|---------|-------------|
| `session-start.sh` | Session start | Shows branch, recent commits, detects active.md for recovery |
| `detect-gaps.sh` | Session start | Detects fresh projects (no engine, no concept) and suggests `/start` |
| `pre-compact.sh` | Before compaction | Logs the compaction (its output does not reach Claude) |
-| `post-compact.sh` | After compaction | Debug-log reminder only (its output does not reach Claude) |
-| `notify.sh` | Notification event | Shows Windows toast notification via PowerShell |
+| `notify.sh` | Permission prompt, or idle about a minute | Shows Windows toast notification via PowerShell |
| `validate-commit.sh` | Before commit | Checks design doc sections, valid JSON, hardcoded values, TODO format |
-| `validate-push.sh` | Before push | Warns on pushes to main, master or release/* |
+| `validate-push.sh` | Before push, tag, merge or deploy | Warns on pushes to main, master or release/*, and on `git tag`, `git merge`, `gh release`, `butler push` and `steamcmd +run_app_build` |
+| `validate-read.sh` | Before a file read | Refuses a whole-file read of a design doc over 40 KB and answers with its headings |
+| `validate-write.sh` | Before a file write | Warns when a write would break a rule the skills state (never blocks) |
+| `validate-registry.sh` | Before an entity or TR-ID registry write | Warns when an entry would be deleted or renumbered, or a status is not in the header's list |
| `validate-assets.sh` | After a file write | Checks data-file JSON, and asset naming in Godot's `assets/` |
| `validate-skill-change.sh` | Skill file written | Advises running `/skill-test` after `.claude/skills/` changes |
| `log-agent.sh` | Agent start | Logs agent invocations for audit trail |
| `log-agent-stop.sh` | Agent stop | Completes agent audit trail (start + stop) |
-| `session-stop.sh` | **Every response ends** | Session logging and the subagent spawn tally. Despite the name it fires once per response, not once per session. |
+| `validate-agent-artifact.sh` | Agent stop | Warns when a subagent stops without writing the file its brief named |
+| `session-stop.sh` | **Every response ends** | Session logging and the subagent spawn tally, in the background. Despite the name it fires once per response, not once per session. |
### Context Resilience
diff --git a/docs/architecture/tr-registry.yaml b/docs/architecture/tr-registry.yaml
index a9224f6f..0e63d229 100644
--- a/docs/architecture/tr-registry.yaml
+++ b/docs/architecture/tr-registry.yaml
@@ -22,6 +22,7 @@
# /create-epics (trace requirements to ADR coverage)
# /test-helpers (map requirements to tested systems)
# /adopt (brownfield audit: is the registry there)
+# /create-architecture (reuses registered IDs in its baseline)
#
# ID FORMAT: TR-[system]-[NNN]
# [system] = a short lowercase slug for the system. It is an alias: the
@@ -29,6 +30,12 @@
# NNN = three-digit zero-padded sequence per system, starting at 001
#
# STATUS VALUES: active | deprecated | "superseded-by: TR-[system]-NNN"
+#
+# LAYOUT: the one shape .claude/scripts/registry.sh reads. requirements: holds
+# a block list, or [] while it is empty. Each entry starts "- id: TR-..." with
+# the dash at column 0, as in the examples (or 2, the same for every entry);
+# its fields sit two columns past the dash. Quote a value that holds ": ". A
+# line in any other shape is reported as unsupported layout, with its number.
version: 1
last_updated: ""
diff --git a/docs/engine-reference/godot/VERSION.md b/docs/engine-reference/godot/VERSION.md
index 95eef504..d3c411aa 100644
--- a/docs/engine-reference/godot/VERSION.md
+++ b/docs/engine-reference/godot/VERSION.md
@@ -2,18 +2,19 @@
| Field | Value |
|-------|-------|
-| **Engine Version** | Godot 4.6 |
+| **Engine Version** | Godot 4.7 |
| **Installed at pin time** | NOT DETERMINED — `/setup-engine` §3 probes the installed editor and records the result here. |
-| **Release Date** | January 2026 |
-| **Project Pinned** | 2026-02-12 |
-| **Last Docs Verified** | 2026-02-12 |
+| **Release Date** | June 2026 (latest patch: 4.7.2, August 2026) |
+| **Project Pinned** | 2026-10-17 |
+| **Last Docs Verified** | 2026-10-17 (release timeline and 4.7 changes); 2026-02-12 (4.4-4.6 content) |
| **LLM Knowledge Cutoff** | May 2025 |
## Knowledge Gap Warning
-The LLM's training data likely covers Godot up to ~4.3. Versions 4.4, 4.5,
-and 4.6 introduced significant changes that the model does NOT know about.
-Always cross-reference this directory before suggesting Godot API calls.
+The LLM's training data likely covers Godot up to ~4.3. Versions 4.5, 4.6
+and 4.7 were released after the cutoff and introduced significant changes that
+the model does NOT know about; 4.4 came out shortly before it and may be thinly
+covered. Always cross-reference this directory before suggesting Godot API calls.
## Installed-Version Gap Warning
@@ -28,14 +29,15 @@ version-qualified claim** — `NOT DETERMINED` means the gap is unknown, not abs
| Version | Release | Risk Level | Key Theme |
|---------|---------|------------|-----------|
-| 4.4 | ~Mid 2025 | MEDIUM | Jolt physics option, FileAccess return types, shader texture type changes |
-| 4.5 | ~Late 2025 | HIGH | Accessibility (AccessKit), variadic args, @abstract, shader baker, SMAA |
+| 4.5 | Sep 2025 | HIGH | Accessibility (AccessKit), variadic args, @abstract, shader baker, SMAA |
| 4.6 | Jan 2026 | HIGH | Jolt default, glow rework, D3D12 default on Windows, IK restored |
+| 4.7 | Jun 2026 | HIGH | AreaLight3D, HDR output, Asset Store replaces the Asset Library, VirtualJoystick, Jolt soft-body and world-boundary changes, typed-return overrides |
-## Verified Sources
+## Before the Cutoff
-- Official docs: https://docs.godotengine.org/en/stable/
-- 4.5→4.6 migration: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.6.html
-- 4.4→4.5 migration: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.5.html
-- Changelog: https://github.com/godotengine/godot/blob/master/CHANGELOG.md
-- Release notes: https://godotengine.org/releases/4.6/
+4.4 (Mar 2025, Jolt option, FileAccess return types) predates the May 2025
+cutoff; the Knowledge Gap Warning still applies to it.
+
+Dates from https://github.com/godotengine/godot/releases, checked 2026-10-17:
+4.4 Mar 3 2025, 4.5 Sep 15 2025, 4.6 Jan 26 2026, 4.7 Jun 18 2026, 4.7.2 Aug 18
+2026. Migration guides and release notes: `breaking-changes.md` § Sources.
diff --git a/docs/engine-reference/godot/breaking-changes.md b/docs/engine-reference/godot/breaking-changes.md
index e536fbf8..4bc55e16 100644
--- a/docs/engine-reference/godot/breaking-changes.md
+++ b/docs/engine-reference/godot/breaking-changes.md
@@ -1,9 +1,48 @@
# Godot — Breaking Changes
-Last verified: 2026-02-12
+Last verified: 2026-10-17 (4.6 → 4.7 and the section dates); 2026-02-12 (older sections)
Changes between Godot versions, focused on post-LLM-cutoff changes (4.4+).
+## 4.6 → 4.7 (Jun 2026 — POST-CUTOFF, HIGH RISK)
+
+From the official migration guide
+(https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html,
+checked 2026-10-17). Rows marked **GDScript breaks** stop existing GDScript from
+working; the rest add optional parameters, change C# compatibility only, or
+change behaviour or defaults. The guide lists no deprecations.
+
+| Subsystem | Change | Details |
+|-----------|--------|---------|
+| GDScript | Overrides inherit a typed return | An override of a method with a typed return now inherits that type, so it needs an explicit `return` (add `return null` to fix the error). **GDScript breaks** |
+| GDScript | Packed array element writes | Setting one element of a packed array no longer calls the setter of the whole packed-array property |
+| GUI | `RichTextLabel.ImageUpdateMask.UPDATE_WIDTH_IN_PERCENT` renamed | Now `UPDATE_WIDTH_UNIT`. **GDScript breaks** |
+| GUI | `RichTextLabel.add_image()` / `update_image()` | `width` / `height` are `float` (were `int`); `width_in_percent` / `height_in_percent` renamed `width_unit` / `height_unit`, typed `RichTextLabel.ImageUnit` (were `bool`, default `false` → `0`). C# source breaks |
+| GUI | `Control.accessibility_live` type | `AccessibilityServer.AccessibilityLiveMode` (was `DisplayServer.AccessibilityLiveMode`). C# breaks |
+| Core | `Object.is_class()` | Parameter is `StringName` (was `String`) |
+| Core | `OptimizedTranslation.generate()` | Returns `bool` (was `void`). C# binary breaks |
+| Input | Mouse and keyboard device IDs | Were `0`; now `InputEvent.DEVICE_ID_MOUSE` and `InputEvent.DEVICE_ID_KEYBOARD`, because some joypads use `0`. Identify events by type or compare `InputEvent.device` to those constants |
+| Physics | Jolt: `WorldBoundaryShape3D` plane sign | The sign of `plane.d` is read the way Godot Physics reads it, so it is flipped compared to 4.6: negate it to keep 4.6 behaviour |
+| Physics | Jolt: `SoftBody3D` mass and stiffness | Mass defaults to 1 kg for the whole body (was 1 kg per point); `linear_stiffness` is applied differently. Re-tune `linear_stiffness` and `damping_coefficient` on every `SoftBody3D` |
+| Physics | Jolt: `Area3D` and `SoftBody3D` | `Area3D` now reports overlaps with `SoftBody3D`; use collision layers and masks to ignore them |
+| Physics | `PhysicsServer2D.body_set_shape_as_one_way_collision()` | Optional `direction` added; `PhysicsServer2DExtension._body_set_shape_as_one_way_collision()` requires it (extensions break) |
+| Audio | `AudioStreamPlayer2D` / `AudioStreamPlayer3D` `area_mask` default | Changed from layer `1` to `0` (disabled). An `Area2D`/`Area3D` `audio_bus_override` that relied on the default mask stops working until the mask is set back to layer `1` |
+| Audio | `AudioEffectSpectrumAnalyzer.tap_back_pos` | Removed. **GDScript breaks** where it is used |
+| Rendering | `CanvasItem` line drawing | No antialiasing feather is added, so lines look thinner; widen lines that relied on the old thickness |
+| Rendering | `LinearToSRGB` visual shader node | No longer clamps to `[0.0, 1.0]` under Forward+ and Mobile |
+| Rendering | `get_format()` moved | From `ImageTexture` / `PortableCompressedTexture2D` to base class `Texture2D` |
+| Rendering | `RenderingServer.particles_request_process_time()` | `time` renamed `process_time`; optional `process_time_residual` added (also on `request_particles_process()` of the four particle nodes) |
+| Rendering | Sky reflection roughness layers | `rendering/reflections/sky_reflections/roughness_layers` default `7` → `8` |
+| Animation | `Animation.length` | Type metadata `double` (was `float`). C# breaks |
+| Animation | `LookAtModifier3D.relative` | Default `false` (was `true`) |
+| Animation | `AnimationNodeBlendSpace1D/2D.add_blend_point()` | Optional `name` added |
+| Project | Stretch defaults for NEW projects | `display/window/stretch/mode` `canvas_items` (was `disabled`), `display/window/stretch/aspect` `expand` (was `keep`). Existing projects keep their settings |
+| Text | `ResourceImporterDynamicFont.hinting` | Default `3` (was `1`) |
+| Editor | `EditorSceneFormatImporter` import constants | Moved into the `ImportFlags` enum (`IMPORT_SCENE`, `IMPORT_ANIMATION`, …). C# source breaks |
+| Editor | `EditorVCSInterface._commit()` | New `amend` parameter; VCS plugins break |
+| Editor | Asset Library replaced by the Asset Store | The editor workspace is now "Asset Store" (release notes: https://godotengine.org/releases/4.7/) |
+| XR | `OpenXRExtensionWrapper._on_register_metadata()` | New `interaction_profile_metadata` parameter; extensions break |
+
## 4.5 → 4.6 (Jan 2026 — POST-CUTOFF, HIGH RISK)
| Subsystem | Change | Details |
@@ -22,7 +61,7 @@ Changes between Godot versions, focused on post-LLM-cutoff changes (4.4+).
| C# | Automatic string extraction | Translation strings auto-extracted from C# code. |
| Plugins | New EditorDock class | Specialized container for plugin docks with layout control. |
-## 4.4 → 4.5 (Late 2025 — POST-CUTOFF, HIGH RISK)
+## 4.4 → 4.5 (Sep 2025 — POST-CUTOFF, HIGH RISK)
| Subsystem | Change | Details |
|-----------|--------|---------|
@@ -45,7 +84,7 @@ Changes between Godot versions, focused on post-LLM-cutoff changes (4.4+).
| Platform | SDL3 gamepad driver | Delegated gamepad handling to SDL library |
| Platform | Android 16KB page support | Required for Google Play targeting Android 15+ |
-## 4.3 → 4.4 (Mid 2025 — NEAR CUTOFF, VERIFY)
+## 4.3 → 4.4 (Mar 2025 — BEFORE CUTOFF, VERIFY)
| Subsystem | Change | Details |
|-----------|--------|---------|
@@ -68,3 +107,13 @@ Changes between Godot versions, focused on post-LLM-cutoff changes (4.4+).
| Navigation | `NavigationRegion2D` | Removed `avoidance_layers`, `constrain_avoidance` properties |
| Editor | `EditorSceneFormatImporterFBX` | Renamed to `EditorSceneFormatImporterFBX2GLTF` |
| Animation | AnimationMixer base class | AnimationPlayer and AnimationTree now extend AnimationMixer |
+
+## Sources
+
+- Official docs: https://docs.godotengine.org/en/stable/
+- 4.6→4.7 migration: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html
+- 4.5→4.6 migration: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.6.html
+- 4.4→4.5 migration: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.5.html
+- Changelog: https://github.com/godotengine/godot/blob/master/CHANGELOG.md
+- Release notes: https://godotengine.org/releases/4.7/ (4.6: https://godotengine.org/releases/4.6/)
+- Releases and dates: https://github.com/godotengine/godot/releases
diff --git a/docs/engine-reference/godot/current-best-practices.md b/docs/engine-reference/godot/current-best-practices.md
index 251c7d0f..a45cd2c3 100644
--- a/docs/engine-reference/godot/current-best-practices.md
+++ b/docs/engine-reference/godot/current-best-practices.md
@@ -1,6 +1,6 @@
# Godot — Current Best Practices
-Last verified: 2026-02-12 | Engine: Godot 4.6
+Last verified: 2026-10-17 (4.7 sections); 2026-02-12 (rest) | Engine: Godot 4.7
Practices that are **new or changed** since the model's training data (~4.3).
This supplements (not replaces) the agent's built-in knowledge.
@@ -41,6 +41,24 @@ This supplements (not replaces) the agent's built-in knowledge.
- **Script backtracing**: Detailed call stacks available even in Release builds
+## GDScript (4.7)
+
+- **An override of a typed method inherits its return type**, so it needs an
+ explicit `return` statement; the migration guide's fix is `return null`
+- **Writing one element of a packed array no longer calls the property's
+ setter.** A setter on a `PackedInt32Array` (etc.) property no longer runs on
+ `arr[i] = v`; assign the whole array where the setter has to run
+
+## Physics (4.7)
+
+- **Jolt `WorldBoundaryShape3D`**: the sign of `plane.d` now matches Godot
+ Physics, flipped from 4.6. Negate it in scenes authored on 4.6
+- **Jolt `SoftBody3D`**: mass is 1 kg for the whole body (was 1 kg per point)
+ and `linear_stiffness` is applied differently; re-tune `linear_stiffness`
+ and `damping_coefficient`. `Area3D` now reports `SoftBody3D` overlaps
+- **Audio areas**: `area_mask` on `AudioStreamPlayer2D`/`3D` defaults to `0`
+ (was layer `1`); set it to layer `1` where `audio_bus_override` areas are used
+
## Physics (4.6)
- **Jolt Physics is the default 3D engine** for new projects
@@ -49,6 +67,17 @@ This supplements (not replaces) the agent's built-in knowledge.
- Switch: Project Settings → Physics → 3D → Physics Engine
- 2D physics unchanged (still Godot Physics 2D)
+## Rendering (4.7)
+
+- **`AreaLight3D`**: real-time rectangular area lights, instead of an emissive
+ material plus global illumination
+- **HDR output** on Windows, macOS, iOS, visionOS and Linux (Wayland)
+- **`DrawableTexture2D`**: a simpler API for drawing onto textures
+- **`CanvasItem` lines are drawn without an antialiasing feather**, so they look
+ thinner than in 4.6; widen lines that relied on the old look
+- The `LinearToSRGB` visual shader node no longer clamps to `[0.0, 1.0]` under
+ Forward+ and Mobile
+
## Rendering (4.6)
- **D3D12 is the default backend on Windows** (was Vulkan) — for better driver compatibility
@@ -76,6 +105,11 @@ This supplements (not replaces) the agent's built-in knowledge.
- **BoneConstraint3D**: Bind bones to other bones with modifiers
- AimModifier3D, CopyTransformModifier3D, ConvertTransformModifier3D
+## Animation (4.7)
+
+- **`Tween.tween_await()`** pauses a tween until a signal is emitted
+- **`LookAtModifier3D.relative`** defaults to `false` (was `true`)
+
## Animation (4.6)
- **IK system fully restored**: Complete inverse kinematics reintroduced for 3D
@@ -99,6 +133,33 @@ This supplements (not replaces) the agent's built-in knowledge.
- Visual feedback differs depending on input method
- Consider this when designing custom focus behavior
+## UI and Input (4.7)
+
+- **`Control.offset_transform_*`** (`offset_transform_enabled`,
+ `offset_transform_position`, `offset_transform_rotation`,
+ `offset_transform_scale`, …): a visual transform that containers do not
+ reset, for hover and press animations inside containers
+- **`RichTextLabel` images can size relative to the font**
+ (`[img height=1em]…[/img]`); `add_image()` / `update_image()` take
+ `width_unit` / `height_unit` (`RichTextLabel.ImageUnit`) in place of the
+ `*_in_percent` booleans
+- **`VirtualJoystick` node** for touch controls, with Fixed, Dynamic and
+ Following modes
+- **Mouse and keyboard events report `InputEvent.DEVICE_ID_MOUSE` /
+ `DEVICE_ID_KEYBOARD`**, not device `0`; check the event type rather than
+ `device == 0`
+- **New projects stretch by default**: `display/window/stretch/mode` is
+ `canvas_items` and `aspect` is `expand`. Projects created before 4.7 keep
+ their settings
+
+## Editor Workflow (4.7)
+
+- **The Asset Store replaces the Asset Library**: the editor workspace is
+ "Asset Store" (it was "AssetLib"), and addons such as gdUnit4 are installed
+ from there
+- Method, signal and property names show in a monospace font by default
+ ("Use Monospace Font for Editor Symbols" turns it off)
+
## Editor Workflow (4.6)
- Flexible dock drag-and-drop with blue outline preview (including bottom panel)
@@ -132,7 +193,15 @@ the documented exit codes are 0 (all passed), 100 (failures) and 101 (warnings).
The command the framework uses:
`godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode`.
-Observed on Godot 4.6.1 with gdUnit4 6.1.3 — not in the docs:
+gdUnit4 6.2.x lists Godot 4.5 to 4.7.1 as compatible in its README
+(https://github.com/godot-gdunit-labs/gdUnit4#compatibility-overview, checked
+2026-10-17); 4.7.2 is not listed there yet, but gdUnit4 6.2.2 runs on it. On
+Windows, 2026-10-17, Godot 4.7.2 and 4.7.1 gave the same exits on the command
+above: 0 pass, 100 fail, 101 orphans, 105 parse error, 0 with `No test cases
+found` over none, and 1 before the first import.
+
+Observed on Godot 4.6.1 with gdUnit4 6.1.3, and the exits again on 4.7.2 with
+6.2.2 — not in the docs:
- 101 is also the exit when every test passed but a test leaked orphan nodes;
105 means a test script does not parse; 103 means gdUnit4 refused to run
headless (`--ignoreHeadlessMode` missing). 104 is gdUnit4 refusing a Godot
@@ -144,6 +213,10 @@ Observed on Godot 4.6.1 with gdUnit4 6.1.3 — not in the docs:
- A fresh clone has no `.godot/` class cache: run
`godot --headless --path . --import` first, or `GdUnitCmdTool.gd` does not
load and the run exits 1 having run nothing.
+- On 4.7.1 and 4.7.2 (Windows, 2026-10-17), that first `--import` of a fresh
+ project crashed on exit (139, segmentation fault) in 3 of 17 runs, after
+ writing the same `.godot/` files as a clean run; running it again exited 0.
+ 4.6.1 did not crash in 4 runs.
- `--check-only` with `-s <file>` exits 1 on valid code that names an autoload
(`Identifier not found`), and `--import` / `--quit-after` exit 0 on a parse
error — neither is a parse check. The framework's parse check is
@@ -155,6 +228,9 @@ Observed on Godot 4.6.1 with gdUnit4 6.1.3 — not in the docs:
Sources:
- Command line tutorial: https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html
- gdUnit4 command line tool: https://godot-gdunit-labs.github.io/gdUnit4/latest/advanced_testing/cmd/
+- gdUnit4 releases: https://github.com/godot-gdunit-labs/gdUnit4/releases
+- Godot 4.7 migration guide: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html
+- Godot 4.7 release notes: https://godotengine.org/releases/4.7/
- GDScript reference, lambda functions and rest parameters: https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html
## Platform (4.5+)
diff --git a/docs/engine-reference/godot/deprecated-apis.md b/docs/engine-reference/godot/deprecated-apis.md
index 9b8c511a..6a135398 100644
--- a/docs/engine-reference/godot/deprecated-apis.md
+++ b/docs/engine-reference/godot/deprecated-apis.md
@@ -1,6 +1,10 @@
# Godot — Deprecated APIs
-Last verified: 2026-02-12
+Last verified: 2026-10-17 (4.7 rows); 2026-02-12 (rest)
+
+The 4.7 migration guide lists no formal deprecations; the 4.7 rows below are
+renames and removals from it
+(https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html).
If an agent suggests any API in the "Deprecated" column, it MUST be replaced
with the "Use Instead" column.
@@ -30,6 +34,11 @@ with the "Use Instead" column.
| `Skeleton3D` signal `bone_pose_updated` | `skeleton_updated` | 4.3 | Renamed |
| `AnimationPlayer.method_call_mode` | `AnimationMixer.callback_mode_method` | 4.3 | Moved to base class |
| `AnimationPlayer.playback_active` | `AnimationMixer.active` | 4.3 | Moved to base class |
+| `RichTextLabel.ImageUpdateMask.UPDATE_WIDTH_IN_PERCENT` | `ImageUpdateMask.UPDATE_WIDTH_UNIT` | 4.7 | Renamed; GDScript using the old name breaks |
+| `add_image()` / `update_image()` `width_in_percent`, `height_in_percent` (`bool`) | `width_unit`, `height_unit` (`RichTextLabel.ImageUnit`) | 4.7 | Renamed and retyped |
+| `DisplayServer.AccessibilityLiveMode` for `Control.accessibility_live` | `AccessibilityServer.AccessibilityLiveMode` | 4.7 | Enum moved to `AccessibilityServer` |
+| `AudioEffectSpectrumAnalyzer.tap_back_pos` | — | 4.7 | Removed |
+| `EditorSceneFormatImporter.IMPORT_*` constants | `EditorSceneFormatImporter.ImportFlags` enum | 4.7 | Same names, now in an enum |
## Patterns (Not Just APIs)
@@ -41,3 +50,5 @@ with the "Use Instead" column.
| `Texture2D` in `Shader.set_default_texture_parameter()` / `get_default_texture_parameter()` | `Texture` base type | Changed in 4.4; the shading language's `sampler2D` / `texture()` did not change |
| Manual post-process viewport chains | `Compositor` + `CompositorEffect` | Structured post-processing (4.3+) |
| GodotPhysics3D for new projects | Jolt Physics 3D | Default since 4.6; better stability |
+| `event.device == 0` to detect mouse or keyboard | `event is InputEventMouse` / `InputEventKey`, or `InputEvent.DEVICE_ID_MOUSE` / `DEVICE_ID_KEYBOARD` | Since 4.7 mouse and keyboard no longer report device `0`, which some joypads use |
+| Installing addons from the editor's AssetLib tab | The editor's Asset Store workspace (4.7+) | 4.7 replaced the Asset Library with the Asset Store |
diff --git a/docs/engine-reference/godot/modules/animation.md b/docs/engine-reference/godot/modules/animation.md
index 25a4cbb0..ee51f50a 100644
--- a/docs/engine-reference/godot/modules/animation.md
+++ b/docs/engine-reference/godot/modules/animation.md
@@ -1,9 +1,15 @@
# Godot Animation — Quick Reference
-Last verified: 2026-02-12 | Engine: Godot 4.6
+Last verified: 2026-10-17 (4.7 changes); 2026-02-12 (rest) | Engine: Godot 4.7
## What Changed Since ~4.3 (LLM Cutoff)
+### 4.7 Changes
+- **`Tween.tween_await()`**: pauses a tween until a signal is emitted (4.7 release notes: https://godotengine.org/releases/4.7/)
+- **`LookAtModifier3D.relative`** defaults to `false` (was `true`)
+- **`AnimationNodeBlendSpace1D/2D.add_blend_point()`**: optional `name` parameter
+- **`Animation.length`** is `double` in C# (was `float`); GDScript unaffected (4.7 migration guide: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html)
+
### 4.6 Changes
- **IK system fully restored**: Complete inverse kinematics for 3D skeletons
- CCDIK, FABRIK, Jacobian IK, Spline IK, TwoBoneIK
diff --git a/docs/engine-reference/godot/modules/audio.md b/docs/engine-reference/godot/modules/audio.md
index 2924588b..c72af247 100644
--- a/docs/engine-reference/godot/modules/audio.md
+++ b/docs/engine-reference/godot/modules/audio.md
@@ -1,11 +1,17 @@
# Godot Audio — Quick Reference
-Last verified: 2026-02-12 | Engine: Godot 4.6
+Last verified: 2026-10-17 (4.7 changes); 2026-02-12 (rest) | Engine: Godot 4.7
## What Changed Since ~4.3 (LLM Cutoff)
-No major breaking changes to the audio API in 4.4–4.6. The core audio system
-remains stable. Key updates are workflow improvements:
+No major breaking changes to the audio API in 4.4–4.6; 4.7 removes one
+property and changes one default:
+
+### 4.7 Changes
+- **`AudioEffectSpectrumAnalyzer.tap_back_pos` removed**
+- **`area_mask` on `AudioStreamPlayer2D`/`3D` defaults to `0`** (was layer `1`):
+ `audio_bus_override` on an `Area2D`/`Area3D` stops working with the default
+ mask until it is set back to layer `1` (4.7 migration guide: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html)
### 4.6 Changes
- **No audio-specific breaking changes** in this release
diff --git a/docs/engine-reference/godot/modules/input.md b/docs/engine-reference/godot/modules/input.md
index 9b03a100..3406b1b8 100644
--- a/docs/engine-reference/godot/modules/input.md
+++ b/docs/engine-reference/godot/modules/input.md
@@ -1,9 +1,17 @@
# Godot Input — Quick Reference
-Last verified: 2026-02-12 | Engine: Godot 4.6
+Last verified: 2026-10-17 (4.7 changes); 2026-02-12 (rest) | Engine: Godot 4.7
## What Changed Since ~4.3 (LLM Cutoff)
+### 4.7 Changes
+- **Mouse and keyboard device IDs**: `InputEvent.device` is
+ `InputEvent.DEVICE_ID_MOUSE` / `DEVICE_ID_KEYBOARD` (was `0`, which some
+ joypads also use). Identify events by type, not `device == 0` (4.7 migration guide: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html)
+- **`VirtualJoystick` node**: on-screen joystick with Fixed, Dynamic and
+ Following modes
+- **Gamepad gyro and accelerometer** readings are available (4.7 release notes: https://godotengine.org/releases/4.7/)
+
### 4.6 Changes
- **Dual-focus system**: Mouse/touch focus is now separate from keyboard/gamepad focus
- Visual feedback differs by input method
diff --git a/docs/engine-reference/godot/modules/navigation.md b/docs/engine-reference/godot/modules/navigation.md
index 4dd35d5a..7ae18ffb 100644
--- a/docs/engine-reference/godot/modules/navigation.md
+++ b/docs/engine-reference/godot/modules/navigation.md
@@ -1,9 +1,12 @@
# Godot Navigation — Quick Reference
-Last verified: 2026-02-12 | Engine: Godot 4.6
+Last verified: 2026-10-17 (4.7 changes); 2026-02-12 (rest) | Engine: Godot 4.7
## What Changed Since ~4.3 (LLM Cutoff)
+### 4.7 Changes
+- **No navigation-specific changes** are listed in the 4.7 migration guide (4.7 migration guide: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html)
+
### 4.5 Changes
- **Dedicated 2D navigation server**: No longer a proxy to 3D NavigationServer
- Reduces export binary size for 2D-only games
diff --git a/docs/engine-reference/godot/modules/networking.md b/docs/engine-reference/godot/modules/networking.md
index 287a5479..66068804 100644
--- a/docs/engine-reference/godot/modules/networking.md
+++ b/docs/engine-reference/godot/modules/networking.md
@@ -1,9 +1,12 @@
# Godot Networking — Quick Reference
-Last verified: 2026-02-12 | Engine: Godot 4.6
+Last verified: 2026-10-17 (4.7 changes); 2026-02-12 (rest) | Engine: Godot 4.7
## What Changed Since ~4.3 (LLM Cutoff)
+### 4.7 Changes
+- **No networking-specific changes** are listed in the 4.7 migration guide (4.7 migration guide: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html)
+
### 4.6 Changes
- **Networking section in breaking changes**: See the official migration guide for
specifics at the 4.5→4.6 level
diff --git a/docs/engine-reference/godot/modules/physics.md b/docs/engine-reference/godot/modules/physics.md
index e790a473..3b6ac894 100644
--- a/docs/engine-reference/godot/modules/physics.md
+++ b/docs/engine-reference/godot/modules/physics.md
@@ -1,9 +1,19 @@
# Godot Physics — Quick Reference
-Last verified: 2026-02-12 | Engine: Godot 4.6
+Last verified: 2026-10-17 (4.7 changes); 2026-02-12 (rest) | Engine: Godot 4.7
## What Changed Since ~4.3 (LLM Cutoff)
+### 4.7 Changes
+- **Jolt `WorldBoundaryShape3D`**: `plane.d` sign now matches Godot Physics,
+ flipped from 4.6; negate it to keep 4.6 behavior
+- **Jolt `SoftBody3D`**: mass defaults to 1 kg for the whole body (was 1 kg per
+ point) and `linear_stiffness` is applied differently; re-tune
+ `linear_stiffness` and `damping_coefficient`
+- **Jolt `Area3D`** reports overlaps with `SoftBody3D`; filter with layers/masks
+- **`PhysicsServer2D.body_set_shape_as_one_way_collision()`**: optional
+ `direction` parameter (required in `PhysicsServer2DExtension`) (4.7 migration guide: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html)
+
### 4.6 Changes
- **Jolt Physics is the DEFAULT 3D engine** for new projects
- Existing projects keep their current physics engine setting
diff --git a/docs/engine-reference/godot/modules/rendering.md b/docs/engine-reference/godot/modules/rendering.md
index e257823f..2a303185 100644
--- a/docs/engine-reference/godot/modules/rendering.md
+++ b/docs/engine-reference/godot/modules/rendering.md
@@ -1,9 +1,18 @@
# Godot Rendering — Quick Reference
-Last verified: 2026-02-12 | Engine: Godot 4.6
+Last verified: 2026-10-17 (4.7 changes); 2026-02-12 (rest) | Engine: Godot 4.7
## What Changed Since ~4.3 (LLM Cutoff)
+### 4.7 Changes
+- **`AreaLight3D`**: real-time rectangular area lights
+- **HDR output** on Windows, macOS, iOS, visionOS and Linux (Wayland)
+- **`DrawableTexture2D`**: simple API for drawing on textures (4.7 release notes: https://godotengine.org/releases/4.7/)
+- **`CanvasItem` lines**: no antialiasing feather, so lines look thinner
+- **`LinearToSRGB` visual shader** no longer clamps to `[0.0, 1.0]` (Forward+, Mobile)
+- **`get_format()`** moved from `ImageTexture` / `PortableCompressedTexture2D` to `Texture2D`
+- **`rendering/reflections/sky_reflections/roughness_layers`** default `7` → `8` (4.7 migration guide: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html)
+
### 4.6 Changes
- **D3D12 is the default rendering backend on Windows** (was Vulkan)
- **Glow processes before tonemapping** (was after) — uses screen blending mode
diff --git a/docs/engine-reference/godot/modules/ui.md b/docs/engine-reference/godot/modules/ui.md
index 2c237817..30ad166a 100644
--- a/docs/engine-reference/godot/modules/ui.md
+++ b/docs/engine-reference/godot/modules/ui.md
@@ -1,9 +1,20 @@
# Godot UI — Quick Reference
-Last verified: 2026-02-12 | Engine: Godot 4.6
+Last verified: 2026-10-17 (4.7 changes); 2026-02-12 (rest) | Engine: Godot 4.7
## What Changed Since ~4.3 (LLM Cutoff)
+### 4.7 Changes
+- **`RichTextLabel` images**: `ImageUpdateMask.UPDATE_WIDTH_IN_PERCENT` renamed
+ `UPDATE_WIDTH_UNIT`; `add_image()` / `update_image()` take `width_unit` /
+ `height_unit` (`RichTextLabel.ImageUnit`) instead of `*_in_percent` booleans,
+ and `width` / `height` are `float`
+- **`Control.accessibility_live`** is typed `AccessibilityServer.AccessibilityLiveMode`
+- **Stretch defaults for new projects**: `display/window/stretch/mode`
+ `canvas_items`, `aspect` `expand` (existing projects keep theirs) (4.7 migration guide: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html)
+- **`Control.offset_transform_*`**: visual offset transforms that containers
+ do not reset; **`PopupMenu`** can show a search bar (4.7 release notes: https://godotengine.org/releases/4.7/)
+
### 4.6 Changes
- **Dual-focus system**: Mouse/touch focus is now SEPARATE from keyboard/gamepad focus
- Visual feedback differs by input method
diff --git a/docs/engine-reference/unity/VERSION.md b/docs/engine-reference/unity/VERSION.md
index 6f80f32d..2c3a9665 100644
--- a/docs/engine-reference/unity/VERSION.md
+++ b/docs/engine-reference/unity/VERSION.md
@@ -5,8 +5,9 @@
| **Engine Version** | Unity 6.3 LTS |
| **Installed at pin time** | NOT DETERMINED — `/setup-engine` §3 probes the installed editor and records the result here. |
| **Release Date** | December 2025 |
+| **Latest editor on the pinned line** | 6000.3.26f1 (Oct 8, 2026) |
| **Project Pinned** | 2026-02-13 |
-| **Last Docs Verified** | 2026-02-13 |
+| **Last Docs Verified** | 2026-10-17 (release timeline, newer releases, latest 6.3 LTS editor); 2026-02-13 (rest of directory) |
| **LLM Knowledge Cutoff** | May 2025 |
## Knowledge Gap Warning
@@ -27,39 +28,60 @@ version-qualified claim** — `NOT DETERMINED` means the gap is unknown, not abs
## Post-Cutoff Version Timeline
-<!-- timeline-unverified -->
-
-> **⚠ THIS TABLE IS INTERNALLY INCONSISTENT AND MUST NOT BE TRUSTED FOR RISK
-> JUDGEMENTS UNTIL RE-VERIFIED (flagged 2026-08-10).** It is titled
-> *Post-Cutoff* and the stated cutoff above is **May 2025**, yet three of its four
-> rows are dated **Oct, Nov and Dec 2024** — before that cutoff — followed by a
-> twelve-month gap to 6.3 in Dec 2025. Both cannot be right. The sibling files
-> `godot/VERSION.md` and `unreal/VERSION.md` list only genuinely post-cutoff
-> versions, so this is a defect in this file, not in the format.
->
-> **Why it matters more than a wrong date.** This table's entire job is to tell an
-> agent what it does *not* already know. Rows that predate the cutoff invert that
-> signal: take an installed `6000.1.0f1` (**Unity 6.1**) — this
-> table dates it to Nov 2024 and labels it post-cutoff MEDIUM risk, while by its own
-> cutoff a Nov 2024 release would be *inside* training data. An agent reading this
-> either over-trusts the reference or mis-scopes what is new, and the `6.2+`
-> boundaries cited elsewhere in this directory are anchored to these rows.
->
-> **The dates are NOT corrected here, deliberately.** Real Unity release dates
-> cannot be sourced from this repo — this directory *is* the source — and writing
-> them from training data is the failure this whole directory exists to prevent
-> (`/security-audit` makes the same call). Re-verify against Unity's
-> published release notes and update the row dates, the `Release Date` field, and
-> `Last Docs Verified` together. Until then, treat every version-qualified claim in
-> `docs/engine-reference/unity/` as **unconfirmed**, and prefer APIs that are not
-> version-boundary-dependent.
+| Version | Release | Risk Level | Key Theme |
+|---------|---------|------------|-----------|
+| 6.2 | Aug 2025 | MEDIUM | Supported Update release: Unity AI (beta) in the Editor, Mesh LOD, World Space UI for UI Toolkit, Graph Toolkit, Android XR hand mesh |
+| 6.3 LTS | Dec 2025 | HIGH | First LTS since 6.0 (two years of support): Platform Toolkit, Nintendo Switch 2 support, Android XR, desktop screen reader support, Shader Build Settings |
+
+## Newer Releases After the Pin (6.4 to 6.7)
+
+**The pin does not change: it stays Unity 6.3 LTS, the newest LTS.** These are
+Supported Update releases that shipped after it. Nothing else in this directory
+covers their APIs, so treat any 6.4+ API as unconfirmed until checked against
+Unity's docs for that release. 6.0 LTS support ends in October 2026.
+
+| Version | Release | Status (2026-10-17) | Key Theme |
+|---------|---------|---------------------|-----------|
+| 6.4 | Mar 2026 | Reached end of life | ECS (Entities, Collections, Mathematics, Entities Graphics) ships as Core packages, Project Auditor built into the Editor, DirectStorage on Windows, `EntityId` replaces `InstanceID`, URP Compatibility Mode removed in favor of Render Graph |
+| 6.5 | Jun 2026 | Reached end of life | Entity unification (`InstanceID` to `EntityId`), Editor Lifecycle API toward a CoreCLR Editor, 2D (custom lights and shadows, `RenderSprite` API, Physics Core 2D), on-tile post-processing for mobile, Built-In Render Pipeline deprecated |
+| 6.6 | Sep 2026 | Supported until 6.7 ships | Final supported release of the Unity 6 family: Play Mode skips domain reloads by default for new projects, Content Directories, Build Analysis window, WebGPU as a production Web option |
+| 6.7 | Beta | Not released | 6000.7.0b1 on Sep 17, 2026, latest 6000.7.0b5 on Oct 15, 2026; Unity's 6.6 post calls it the 6.7 LTS |
+
+Dates and status, verified 2026-10-17: 6.4 (announced Mar 17, 2026; editor
+6000.4.0f1 Mar 18) https://discussions.unity.com/t/unity-6-4-is-now-available/1713245
+and https://docs.unity.com/en-us/engine/6000.6/manual/whats-new/unity64; 6.5
+(Jun 15, 2026) https://discussions.unity.com/t/unity-6-5-is-now-available/1723176
+and https://docs.unity.com/en-us/engine/6000.5/manual/whats-new/unity65; 6.6
+(editor 6000.6.0f1 Aug 31, announced Sep 1, 2026, latest 6000.6.6f1 Oct 15)
+https://discussions.unity.com/t/unity-6-6-is-now-available/1735357. The 6.4 and
+6.5 threads carry the banner "This supported release has reached end of life"
+(6.4 points to 6.5 or above, 6.5 to 6.6 or above); the 6.6 post says it is
+supported "until the next release - in this case 6.7 - arrives" and that it
+"brings you one step closer to the 6.7 LTS". Editor versions and release dates
+come from Unity's release API
+https://services.api.unity.com/unity/editor/release/v1/releases (6.3 LTS first
+editor 6000.3.0f1 on Dec 3, 2025; latest 6000.3.26f1 on Oct 8, 2026). Upgrading
+the pin is a decision for when 6.7 LTS ships and `/setup-engine` re-pins; until
+then new projects stay on 6.3 LTS.
+
+## Unity 6 Releases Before the Cutoff
+
+These two predate the May 2025 cutoff, so they are not post-cutoff. The Knowledge
+Gap Warning above still applies to them: treat their APIs as unconfirmed until
+checked against this directory.
| Version | Release | Risk Level | Key Theme |
|---------|---------|------------|-----------|
-| 6.0 | Oct 2024 | HIGH | Unity 6 rebrand, new rendering features, Entities 1.3, DOTS improvements |
-| 6.1 | Nov 2024 | MEDIUM | Bug fixes, stability improvements |
-| 6.2 | Dec 2024 | MEDIUM | Performance optimizations, new input system improvements |
-| 6.3 LTS | Dec 2025 | HIGH | First LTS since 6.0, production-ready DOTS, enhanced graphics features |
+| 6.0 LTS | Oct 2024 | HIGH | Unity 6 launch: GPU Resident Drawer, Render Graph for URP, multiplayer workflows, mobile web, new Update release type |
+| 6.1 | Apr 2025 | MEDIUM | First Supported Update release: URP Deferred+ path, Variable Rate Shading, Project Auditor, WebGPU for Unity Web, foldable/large-screen Android |
+
+Release dates verified 2026-10-17 against Unity's announcements: 6.0
+(Oct 17, 2024) https://unity.com/blog/introducing-unity-6-launch, 6.1
+(Apr 24, 2025) https://unity.com/blog/unity-6-1-is-now-available, 6.2
+(Aug 12, 2025) https://discussions.unity.com/t/6-2-is-now-available/1677060,
+6.3 LTS (Dec 4, 2025) https://unity.com/blog/unity-6-3-lts-is-now-available.
+Support windows: https://unity.com/releases/unity-6/support (6.0 LTS through
+October 2026, 6.3 LTS until December 2027).
## Major Changes from 2022 LTS to Unity 6.3 LTS
@@ -88,7 +110,14 @@ version-qualified claim** — `NOT DETERMINED` means the gap is unknown, not abs
- Official docs: https://docs.unity3d.com/6000.0/Documentation/Manual/index.html
- Unity 6 release: https://unity.com/releases/unity-6
+- Unity 6.0 launch: https://unity.com/blog/introducing-unity-6-launch
+- Unity 6.1 announcement: https://unity.com/blog/unity-6-1-is-now-available
+- Unity 6.2 announcement: https://discussions.unity.com/t/6-2-is-now-available/1677060
- Unity 6.3 LTS announcement: https://unity.com/blog/unity-6-3-lts-is-now-available
- Migration guide: https://docs.unity3d.com/6000.0/Documentation/Manual/upgrade-guides.html
- Unity 6 support: https://unity.com/releases/unity-6/support
+- Unity 6.4 announcement: https://discussions.unity.com/t/unity-6-4-is-now-available/1713245
+- Unity 6.5 announcement: https://discussions.unity.com/t/unity-6-5-is-now-available/1723176
+- Unity 6.6 announcement: https://discussions.unity.com/t/unity-6-6-is-now-available/1735357
+- Editor release API: https://services.api.unity.com/unity/editor/release/v1/releases
- C# API reference: https://docs.unity3d.com/6000.0/Documentation/ScriptReference/index.html
diff --git a/docs/engine-reference/unity/current-best-practices.md b/docs/engine-reference/unity/current-best-practices.md
index 38bef9da..764d12ee 100644
--- a/docs/engine-reference/unity/current-best-practices.md
+++ b/docs/engine-reference/unity/current-best-practices.md
@@ -10,7 +10,7 @@ These are production-ready recommendations as of Unity 6.3 LTS.
## Project Setup
### Use Unity 6.3 LTS for Production
-- **Tech Stream** (6.4+): Latest features, less stable
+- **Supported Update releases** (6.4+): Latest features, supported only until the next one ships
- **LTS** (6.3): Production-ready, 2-year support (until Dec 2027)
### Choose the Right Render Pipeline
diff --git a/docs/engine-reference/unreal/PLUGINS.md b/docs/engine-reference/unreal/PLUGINS.md
index f97a9f49..4a776525 100644
--- a/docs/engine-reference/unreal/PLUGINS.md
+++ b/docs/engine-reference/unreal/PLUGINS.md
@@ -1,8 +1,8 @@
-# Unreal Engine 5.7 — Optional Plugins & Systems
+# Unreal Engine 5.8 — Optional Plugins & Systems
-**Last verified:** 2026-02-13
+**Last verified:** 2026-10-17 (5.8 status flags, Mover, Iris, AI Assistant, MCP Server, Raw Input); 2026-02-13 (rest of file, written against 5.7)
-This document indexes **optional plugins and systems** available in Unreal Engine 5.7.
+This document indexes **optional plugins and systems** available in Unreal Engine 5.8.
These are NOT part of the core engine but are commonly used for specific game types.
---
@@ -14,6 +14,35 @@ These are NOT part of the core engine but are commonly used for specific game ty
**⚠️ Experimental** - May have breaking changes in future versions
**📦 Plugin Required** - Must be enabled in `Edit > Plugins`
+### Status flags in the UE 5.8 install
+
+Epic's own `.uplugin` flags decide whether the Plugins window shows a plugin as
+Beta or Experimental. Read from a UE 5.8.1 install (`Engine/Plugins/...`) on
+2026-10-17; where a status line below and this table disagree, the table is the
+engine's word.
+
+| Plugin | `.uplugin` | 5.8 flag |
+|--------|-----------|----------|
+| Gameplay Abilities | `Runtime/GameplayAbilities/GameplayAbilities.uplugin` | none (not Beta/Experimental) |
+| CommonUI | `Runtime/CommonUI/CommonUI.uplugin` | none |
+| PCG | `PCG/PCG.uplugin` | none; enabled by default |
+| Gameplay Cameras | `Cameras/GameplayCameras/GameplayCameras.uplugin` | Experimental; enabled by default |
+| Mass Gameplay / Mass Crowd | `Runtime/MassGameplay/MassGameplay.uplugin`, `AI/MassCrowd/MassCrowd.uplugin` | Experimental (MassEntity itself is engine code, `Engine/Source/Runtime/MassEntity`) |
+| Niagara Fluids | `FX/NiagaraFluids/NiagaraFluids.uplugin` | Beta |
+| Water | `Experimental/Water/Water.uplugin` | Experimental |
+| Landmass | `Experimental/Landmass/Landmass.uplugin` | Beta |
+| Chaos Destruction (Geometry Collection) | `Experimental/GeometryCollectionPlugin/GeometryCollectionPlugin.uplugin` | Beta |
+| Chaos Vehicles | `Experimental/ChaosVehiclesPlugin/ChaosVehiclesPlugin.uplugin` | Experimental |
+| Geometry Scripting | `Runtime/GeometryScripting/GeometryScripting.uplugin` | none |
+| Mover / ChaosMover | `Experimental/Mover/Mover.uplugin`, `Experimental/ChaosMover/ChaosMover.uplugin` | Experimental |
+| Iris | `Experimental/Iris/Iris.uplugin` | Beta (the 5.8 release notes call Iris "production-ready for licensees") |
+| Replication Graph | `Runtime/ReplicationGraph/ReplicationGraph.uplugin` | Beta (no deprecation flag) |
+| AI Assistant | `Experimental/AIAssistant/AIAssistant.uplugin` | Experimental |
+| Raw Input | `Experimental/RawInput/RawInput.uplugin` | `"DeprecatedEngineVersion": "5.8"` |
+| Game Input (Windows) | `GameInputWindows/GameInputWindows.uplugin` | Beta |
+| OpenXR | `Runtime/OpenXR/OpenXR.uplugin` | none |
+| Enhanced Input, MetaSound | `EnhancedInput/EnhancedInput.uplugin`, `Runtime/Metasound/Metasound.uplugin` | none; enabled by default |
+
---
## Production-Ready Systems (Detailed Docs Available)
@@ -44,7 +73,7 @@ These are NOT part of the core engine but are commonly used for specific game ty
- **Purpose:** Modular camera management (camera modes, blending, context-aware cameras)
- **When to use:** Games needing dynamic camera behavior (3rd person, aiming, vehicles)
- **Knowledge Gap:** NEW in UE 5.5, completely post-cutoff
-- **Status:** ⚠️ Experimental (UE 5.5-5.7)
+- **Status:** ⚠️ Experimental (UE 5.5-5.8; still flagged Experimental in 5.8)
- **Plugin:** `GameplayCameras` (built-in, enable in Plugins)
- **Detailed Docs:** [plugins/gameplay-camera-system.md](plugins/gameplay-camera-system.md)
- **Official:** https://docs.unrealengine.com/5.7/en-US/gameplay-cameras-in-unreal-engine/
@@ -54,7 +83,7 @@ These are NOT part of the core engine but are commonly used for specific game ty
### ✅ PCG (Procedural Content Generation)
- **Purpose:** Node-based procedural world generation (foliage, props, terrain details)
- **When to use:** Open worlds, procedural levels, large-scale environment population
-- **Knowledge Gap:** Experimental in UE 5.0-5.6, production-ready in 5.7
+- **Knowledge Gap:** Experimental in UE 5.0-5.6, production-ready in 5.7; 5.8 adds manual editing, complex attributes and embedded subgraphs
- **Status:** Production-Ready (as of UE 5.7)
- **Plugin:** `PCG` (built-in, enable in Plugins)
- **Detailed Docs:** [plugins/pcg.md](plugins/pcg.md)
@@ -62,13 +91,13 @@ These are NOT part of the core engine but are commonly used for specific game ty
---
-## Other Production-Ready Plugins (Brief Overview)
+## Other Plugins (Brief Overview)
### 🟡 Mass Entity
- **Purpose:** High-performance ECS for large-scale AI/crowds (10,000+ entities)
- **When to use:** RTS, city simulators, massive crowds, large-scale AI
-- **Status:** Production-Ready (UE 5.1+)
-- **Plugin:** `MassEntity`, `MassGameplay`, `MassCrowd`
+- **Status:** `MassGameplay` and `MassCrowd` are flagged Experimental in 5.8. 5.8 overhauled Mass: Mass Signals moved into the core engine, entities can be created off the game thread, and a new MassCore module separates the core entity system from MassGameplay
+- **Plugin:** `MassGameplay`, `MassCrowd` (MassEntity is engine code in 5.8, not a plugin)
- **Official:** https://docs.unrealengine.com/5.7/en-US/mass-entity-in-unreal-engine/
---
@@ -76,7 +105,7 @@ These are NOT part of the core engine but are commonly used for specific game ty
### 🟡 Niagara Fluids
- **Purpose:** GPU fluid simulation (smoke, fire, liquids)
- **When to use:** Realistic fire/smoke effects, water simulation
-- **Status:** Experimental → Production-Ready (UE 5.4+)
+- **Status:** Beta (5.8 flag)
- **Plugin:** `NiagaraFluids` (built-in)
- **Official:** https://docs.unrealengine.com/5.7/en-US/niagara-fluids-in-unreal-engine/
@@ -85,7 +114,7 @@ These are NOT part of the core engine but are commonly used for specific game ty
### 🟡 Water Plugin
- **Purpose:** Ocean, river, lake rendering with buoyancy
- **When to use:** Games with water bodies, boats, swimming
-- **Status:** Production-Ready (UE 5.0+)
+- **Status:** Experimental (5.8 flag)
- **Plugin:** `Water` (built-in)
- **Official:** https://docs.unrealengine.com/5.7/en-US/water-system-in-unreal-engine/
@@ -94,7 +123,7 @@ These are NOT part of the core engine but are commonly used for specific game ty
### 🟡 Landmass Plugin
- **Purpose:** Terrain sculpting and landscape editing
- **When to use:** Large-scale terrain modification, procedural landscapes
-- **Status:** Production-Ready
+- **Status:** Beta (5.8 flag)
- **Plugin:** `Landmass` (built-in)
- **Official:** https://docs.unrealengine.com/5.7/en-US/landmass-plugin-in-unreal-engine/
@@ -103,8 +132,8 @@ These are NOT part of the core engine but are commonly used for specific game ty
### 🟡 Chaos Destruction
- **Purpose:** Real-time fracture and destruction
- **When to use:** Destructible environments (walls, buildings, objects)
-- **Status:** Production-Ready (UE 5.0+)
-- **Plugin:** `ChaosDestruction` (built-in)
+- **Status:** Beta (5.8 flag on `GeometryCollectionPlugin`)
+- **Plugin:** `GeometryCollectionPlugin` (built-in)
- **Official:** https://docs.unrealengine.com/5.7/en-US/destruction-in-unreal-engine/
---
@@ -112,8 +141,8 @@ These are NOT part of the core engine but are commonly used for specific game ty
### 🟡 Chaos Vehicle
- **Purpose:** Advanced vehicle physics (wheeled vehicles, suspension)
- **When to use:** Racing games, vehicle-heavy gameplay
-- **Status:** Production-Ready (replaces PhysX Vehicles)
-- **Plugin:** `ChaosVehicles` (built-in)
+- **Status:** Experimental (5.8 flag; replaces PhysX Vehicles)
+- **Plugin:** `ChaosVehiclesPlugin` (built-in)
- **Official:** https://docs.unrealengine.com/5.7/en-US/chaos-vehicles-overview-in-unreal-engine/
---
@@ -141,11 +170,25 @@ These are NOT part of the core engine but are commonly used for specific game ty
### ⚠️ AI Assistant (UE 5.7+)
- **Purpose:** In-editor AI guidance and help
- **Status:** Experimental
-- **Plugin:** Enable in UE 5.7 settings
+- **Plugin:** `AIAssistant` (Experimental, off by default in 5.8)
- **Official:** Announced in UE 5.7 release
---
+### ⚠️ MCP Server (UE 5.8+)
+- **Purpose:** Lets agentic AI systems connect to the Unreal Editor to understand the engine and project and help build assets or systems
+- **Status:** Experimental
+- **Official:** UE 5.8 release notes, *MCP Server (Experimental)*
+
+---
+
+### ⚠️ Mover / ChaosMover
+- **Purpose:** Character and object movement framework with rollback and prediction
+- **Status:** Experimental (5.8 flag). 5.8 continues "the architectural work toward moving Mover out of Experimental status"
+- **5.8 change:** PhysicsMover / NetworkPhysicsLiaison code was removed from the Mover plugin; use `ChaosMover`
+
+---
+
### ⚠️ OpenXR (VR/AR)
- **Purpose:** Cross-platform VR/AR support
- **When to use:** VR/AR games
@@ -174,7 +217,13 @@ These are NOT part of the core engine but are commonly used for specific game ty
### ❌ Old Replication Graph
- **Deprecated:** Replaced by Iris (UE 5.1+)
-- **Status:** Use Iris for modern networking
+- **Status:** Use Iris for modern networking. Note: in 5.8 the `ReplicationGraph` plugin carries a Beta flag and no deprecation flag, so this is guidance, not an engine deprecation
+
+---
+
+### ❌ Raw Input
+- **Deprecated:** In UE 5.8 (`"DeprecatedEngineVersion": "5.8"`)
+- **Status:** Use the Game Input for Windows plugin (`GameInputWindows`, Beta)
---
@@ -182,11 +231,11 @@ These are NOT part of the core engine but are commonly used for specific game ty
For plugins NOT listed above, use the following approach when users ask:
-1. **WebSearch** for latest documentation: `"Unreal Engine 5.7 [plugin name]"`
+1. **WebSearch** for latest documentation: `"Unreal Engine 5.8 [plugin name]"`
2. Verify if plugin is:
- Post-cutoff (beyond May 2025 training data)
- Experimental vs Production-Ready
- - Still supported in UE 5.7
+ - Still supported in UE 5.8
3. Optionally cache findings in `plugins/[plugin-name].md` for future reference
---
@@ -205,6 +254,7 @@ For plugins NOT listed above, use the following approach when users ask:
---
-**Last Updated:** 2026-02-13
-**Engine Version:** Unreal Engine 5.7
+**Last Updated:** 2026-10-17
+**Engine Version:** Unreal Engine 5.8
+**Sources (5.8):** UE 5.8 release notes https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8 (Mass, Iris, Mover, MCP Server, Raw Input upgrade note); `.uplugin` files in a UE 5.8.1 install, paths in the status table above
**LLM Knowledge Cutoff:** May 2025
diff --git a/docs/engine-reference/unreal/VERSION.md b/docs/engine-reference/unreal/VERSION.md
index 91c5a8e3..cd058dce 100644
--- a/docs/engine-reference/unreal/VERSION.md
+++ b/docs/engine-reference/unreal/VERSION.md
@@ -2,18 +2,19 @@
| Field | Value |
|-------|-------|
-| **Engine Version** | Unreal Engine 5.7 |
+| **Engine Version** | Unreal Engine 5.8 |
| **Installed at pin time** | NOT DETERMINED — `/setup-engine` §3 probes the installed editor and records the result here. |
-| **Release Date** | November 2025 |
-| **Project Pinned** | 2026-02-13 |
-| **Last Docs Verified** | 2026-02-13 |
+| **Release Date** | June 2026 (5.8.0); latest hotfix 5.8.3, September 2026 |
+| **Project Pinned** | 2026-10-17 |
+| **Last Docs Verified** | 2026-10-17 (release timeline, 5.8 release notes, and the 5.8 changes recorded in this directory); 2026-02-13 (rest of directory, written against 5.7) |
| **LLM Knowledge Cutoff** | May 2025 |
## Knowledge Gap Warning
-The LLM's training data likely covers Unreal Engine up to ~5.3. Versions 5.4, 5.5,
-5.6, and 5.7 introduced significant changes that the model does NOT know about.
-Always cross-reference this directory before suggesting Unreal API calls.
+The LLM's training data likely covers Unreal Engine up to ~5.3. Versions 5.4
+through 5.8 introduced significant changes that the model does NOT know about
+(5.4 and 5.5 predate the cutoff but are not reliably covered). Always
+cross-reference this directory before suggesting Unreal API calls.
## Installed-Version Gap Warning
@@ -28,37 +29,68 @@ version-qualified claim** — `NOT DETERMINED` means the gap is unknown, not abs
| Version | Release | Risk Level | Key Theme |
|---------|---------|------------|-----------|
-| 5.4 | ~Mid 2025 | HIGH | Motion Design tools, animation improvements, PCG enhancements |
-| 5.5 | ~Sep 2025 | HIGH | Megalights (millions of lights), animation authoring, MegaCity demo |
-| 5.6 | ~Oct 2025 | MEDIUM | Performance optimizations, bug fixes |
-| 5.7 | Nov 2025 | HIGH | PCG production-ready, Substrate production-ready, AI assistant |
+| 5.6 | Jun 2025 | MEDIUM | Large open worlds at 60 Hz (Hardware Ray Tracing Lumen performance, Fast Geometry Streaming plugin, Experimental), MetaHuman Creator in the engine, in-editor animation and rigging tools |
+| 5.7 | Nov 2025 | HIGH | PCG production-ready, Substrate production-ready (on by default for new projects), MegaLights Beta, in-editor AI Assistant (Experimental) |
+| 5.8 | Jun 2026 | HIGH | MegaLights production-ready, Iris replication production-ready, Mesh Terrain (Experimental), Lumen Lite (Beta), Enhanced Input and Common UI unified, MCP Server plugin (Experimental), C++20 minimum, WASAPI default audio backend on Windows, multi-pass deferred default on mobile |
-## Major Changes from UE 5.3 to UE 5.7
+## Unreal Engine 5 Releases Before the Cutoff
+
+These two predate the May 2025 cutoff, so they are not post-cutoff. The Knowledge
+Gap Warning above still applies to them: treat their APIs as unconfirmed until
+checked against this directory.
+
+| Version | Release | Risk Level | Key Theme |
+|---------|---------|------------|-----------|
+| 5.4 | Apr 2024 | HIGH | Motion Matching production-ready, Choosers, animation authoring (Modular Control Rig, Sequencer rework), Nanite Tessellation (Experimental), Motion Design mode |
+| 5.5 | Nov 2024 | HIGH | MegaLights introduced, Substrate moves to Beta, Sequencer animation authoring, mobile game development, many features reach production-ready |
+
+Release dates verified 2026-10-17 against Epic's release announcement threads:
+5.4 (Apr 23, 2024) https://forums.unrealengine.com/t/unreal-engine-5-4-released/1817064,
+5.5 (Nov 12, 2024) https://forums.unrealengine.com/t/unreal-engine-5-5-released/2117936,
+5.6 (Jun 3, 2025) https://forums.unrealengine.com/t/unreal-engine-5-6-released/2538952,
+5.7 (Nov 12, 2025) https://forums.unrealengine.com/t/unreal-engine-5-7-released/2673913,
+5.8 (Jun 17, 2026) https://forums.unrealengine.com/t/unreal-engine-5-8-released/2729274.
+Hotfixes 5.8.1 (Jul 28, 2026), 5.8.2 (Aug 25, 2026) and 5.8.3 (Sep 22, 2026):
+https://forums.unrealengine.com/t/5-8-3-hotfix-released/2833315. Key themes come
+from the same threads and from the 5.7 and 5.8 release notes (Verified Sources below).
+
+## Major Changes from UE 5.3 to UE 5.8
### Breaking Changes
-- **Substrate Material System**: New material framework (replaces legacy materials)
+- **Substrate Material System**: New material framework (replaces legacy materials); new projects created in 5.7+ have it enabled automatically
- **PCG (Procedural Content Generation)**: Production-ready, major API changes
-- **Megalights**: New lighting system (millions of dynamic lights)
+- **MegaLights**: New lighting system for many shadow-casting dynamic lights; production-ready in 5.8
- **Animation Authoring**: New rigging and animation tools
-- **AI Assistant**: In-editor AI guidance (experimental)
+- **C++20 minimum (5.8)**: `CppStandardVersion.Cpp14` and `Cpp17` are obsolete and no longer compile
+- **5.8 API removals**: deprecated animation, Control Rig and Live Link symbols from 5.0-5.6 removed; PhysicsMover removed from Mover in favour of ChaosMover — see `breaking-changes.md`
### New Features (Post-Cutoff)
-- **Megalights**: Dynamic lighting at massive scale (millions of lights)
-- **Substrate Materials**: Production-ready modular material system
+- **MegaLights**: Dynamic lighting at massive scale (production-ready in 5.8)
+- **Substrate Materials**: Production-ready modular material system (5.7)
- **PCG Framework**: Procedural world generation (production-ready in 5.7)
+- **Iris**: Replication system, production-ready in 5.8
+- **Lumen Lite (5.8, Beta)**: Medium-quality GI setting, the default on current-generation handheld consoles
+- **Mesh Terrain (5.8, Experimental)**: Mesh-based terrain beyond heightfield landscapes
- **Enhanced Virtual Production**: MetaHuman integration, deeper VP workflows
- **Animation Improvements**: Better rigging, blending, procedural animation
-- **AI Assistant**: In-editor AI help (experimental)
+- **AI Assistant (5.7)**: In-editor AI help (Experimental)
+- **MCP Server (5.8)**: Editor plugin that lets agentic AI systems connect to the Unreal Editor (Experimental)
### Deprecated Systems
- **Legacy Material System**: Migrate to Substrate for new projects
- **Old PCG API**: Use new production-ready PCG API (5.7+)
+- **Raw Input plugin (5.8)**: Deprecated in favour of the Game Input for Windows plugin
+- **`UE_LOG` (5.8)**: Still supported; Epic says it "will eventually be deprecated" and asks for `UE_LOGF`
## Verified Sources
-- Official docs: https://docs.unrealengine.com/5.7/
+- Official docs: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-documentation?application_version=5.8
+- UE 5.8 release notes: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
+- UE 5.8 release thread: https://forums.unrealengine.com/t/unreal-engine-5-8-released/2729274
+- UE 5.8.3 hotfix: https://forums.unrealengine.com/t/5-8-3-hotfix-released/2833315
- UE 5.7 release notes: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-7-release-notes
- What's new in 5.7: https://dev.epicgames.com/documentation/en-us/unreal-engine/whats-new
- UE 5.7 announcement: https://www.unrealengine.com/en-US/news/unreal-engine-5-7-is-now-available
- UE 5.5 blog: https://www.unrealengine.com/en-US/blog/unreal-engine-5-5-is-now-available
-- Migration guides: https://docs.unrealengine.com/5.7/en-US/upgrading-projects/
+- Migration guides: https://dev.epicgames.com/documentation/en-us/unreal-engine/upgrading-projects-to-newer-versions-of-unreal-engine
+- Engine source, read from a UE 5.8.1 install on 2026-10-17: `Engine/Source/Programs/UnrealBuildTool/System/CppCompileEnvironment.cs` (C++ standard), `Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp` (Substrate defaults)
diff --git a/docs/engine-reference/unreal/breaking-changes.md b/docs/engine-reference/unreal/breaking-changes.md
index d3081c2d..7aad70a8 100644
--- a/docs/engine-reference/unreal/breaking-changes.md
+++ b/docs/engine-reference/unreal/breaking-changes.md
@@ -1,14 +1,44 @@
-# Unreal Engine 5.7 — Breaking Changes
+# Unreal Engine 5.8 — Breaking Changes
-**Last verified:** 2026-02-13
+**Last verified:** 2026-10-17 (UE 5.8 Changes, Substrate/MegaLights versions, Platform-Specific, Migration Checklist); 2026-02-13 (rest of file, written against 5.7)
This document tracks breaking API changes and behavioral differences between Unreal Engine 5.3
-(likely in model training) and Unreal Engine 5.7 (current version). Organized by risk level.
+(likely in model training) and Unreal Engine 5.8 (current version). Organized by risk level.
+Changes new in 5.8 come first, under **UE 5.8 Changes**.
+
+## UE 5.8 Changes
+
+Sourced from the UE 5.8 release notes (Upgrade Notes and API Change entries) and
+the 5.8 engine source; the sources are listed at the end of this file.
+
+### HIGH RISK — Will Break Existing Code
+
+| Change | What breaks | Do this |
+|--------|-------------|---------|
+| **C++20 is the minimum** | A target that sets `CppStandard = CppStandardVersion.Cpp17` (or `Cpp14`): both are now obsolete, "no longer allowed, code will not compile with this version" | Remove the override, or set `CppStandardVersion.Default` (= `Cpp20`) |
+| **PhysicsMover removed from Mover** | Code using the unsupported PhysicsMover / NetworkPhysicsLiaison code in the Mover plugin | Use the ChaosMover plugin ("Equivalent functionality is there for every PhysicsMover feature") |
+| **Deprecated animation symbols removed** | Non-reflected `UE_DEPRECATED` items from 5.0-5.6 in Animation, Control Rig, Persona and Live Link (e.g. FSmartName-taking constructors, `UMotionWarpingComponent::GetCharacterOwner`) | Use the replacements their deprecation messages named; `GetCharacterOwner` → `GetOwnerAdapter()->GetActor()` / `GetActorOwner()` |
+| **`LexToString(bool)` no longer catches other types** | A type that only converted implicitly to `bool` now fails to compile in `LexToString` | Add an explicit cast, or a real `LexToString` overload for the type |
+| **MetaSound node metadata** | `FNodeClassMetadata::DefaultInterface` now takes `FClassInterface`, not `FVertexInterface`; deprecated input/output node helpers removed from `IDataTypeRegistry` | Update custom MetaSound node classes |
+| **Slate window type** | `EWindowType::GameWindow` | Use `EWindowType::Normal`; a module depending on `SlateRHIRender` may also need `SlateBaseRenderer` |
+| **`FSharedEventRef` reset mode** | It used `EEventMode::AutoReset` whatever the constructor argument; `ManualReset` is now honoured | Check call sites that pass `ManualReset` |
+
+### MEDIUM RISK — Behavioral Changes
+
+- **Windows audio backend**: default switched from XAudio2 to WASAPI (also used on Xbox); XAudio2 stays available as an opt-in fallback. Epic: "No changes are required on the developers end."
+- **Mobile renderer**: multi-pass deferred rendering is the default path across mobile platforms; forward rendering is opt-in. Materials with the 'Use Half Precision' override revert to Default (listed in the message log).
+- **Zen cooked output**: Zenserver as Cooked Output Store is on by default; an existing project with the Zen store disabled stays off until it is enabled in project settings. `AllowRemoteNetworkService` became `RemoteNetworkService` (`None` / `Unsecured` / `GeneratedStaticKey`, not true/false).
+- **Lumen**: height fog is now applied to reflection ray hits by default (`r.Lumen.HeightFog 1`).
+- **Audio voice limit**: `au.EnableRelativeRenderCostVoiceLimit` is on by default, so fewer sounds may play under the same voice count; revisit voice-count tuning.
+- **Enhanced Input fixes behind CVars**: held keys are ignored on flush (`EnhancedInput.IgnoreHeldKeysOnFlush`, default true) and touch bool action keys are corrected (`EnhancedInput.CorrectTouchBoolActionKeys`, default on). Both CVars "will be removed in a future release".
+- **Blueprint local variables**: a function local variable with the same name as a member variable can inherit the wrong default; rename such locals.
+
+---
## HIGH RISK — Will Break Existing Code
### Substrate Material System (Production-Ready in 5.7)
-**Versions:** UE 5.5+ (experimental), 5.7 (production-ready)
+**Versions:** UE 5.5 (Beta), 5.7 (production-ready; enabled automatically for new projects)
Substrate replaces the legacy material system with a modular, physically accurate framework.
@@ -21,7 +51,7 @@ Substrate replaces the legacy material system with a modular, physically accurat
// Modular material authoring with true physical accuracy
```
-**Migration:** Enable Substrate in `Project Settings > Engine > Substrate` and rebuild materials using Substrate nodes.
+**Migration:** New projects created in 5.7+ start with Substrate on. An existing project keeps its setting: enable it in `Project Settings > Engine > Rendering > Substrate > Substrate materials` (`r.Substrate`, editor restart required) and rebuild materials using Substrate nodes.
---
@@ -43,18 +73,19 @@ PCG framework reached production-ready status with major API changes.
---
-### Megalights Rendering System
-**Versions:** UE 5.5+
+### MegaLights Rendering System
+**Versions:** UE 5.5 (introduced), 5.7 (Beta), 5.8 (production-ready)
-New lighting system supports millions of dynamic lights.
+New lighting system for many shadow-casting dynamic lights.
```cpp
// ❌ OLD: Limited dynamic lights (clustered forward shading)
// Max ~100-200 dynamic lights before performance degrades
-// ✅ NEW: Megalights (5.5+)
-// Millions of dynamic lights with minimal performance cost
-// Enable: Project Settings > Engine > Rendering > Megalights
+// ✅ NEW: MegaLights (5.5+, production-ready in 5.8)
+// Many shadow-casting lights at a consistent, low GPU cost
+// Enable: Project Settings > Engine > Rendering > Direct Lighting > MegaLights
+// (r.MegaLights.EnableForProject, default 0)
```
**Migration:** No code changes needed, but lighting behavior may differ. Test scenes after enabling.
@@ -117,34 +148,51 @@ Use UE5's World Partition system for large worlds.
## Platform-Specific Breaking Changes
+UE 5.8 toolchain and SDK requirements come from the 5.8 release notes'
+*Platform SDK Upgrades* table.
+
### Windows
+- **UE 5.8**: Visual Studio 2022 v17.14 or newer is the minimum; Visual Studio 2026 is recommended (MSVC 14.38 minimum, 14.50 recommended)
+- **UE 5.8**: Windows SDK 10.0.22621.0 minimum, 10.0.26100.0 default; LLVM Clang 18.1.8 minimum
- **UE 5.7**: DirectX 12 is now default (was DX11 in older versions)
- Update shaders for DX12 compatibility
### macOS
- **UE 5.5+**: Metal 3 required (minimum macOS 13)
+- **UE 5.8**: Minimum OS macOS Sonoma 14.0; Xcode 15.2 minimum, 15.4 or newer recommended (macOS target)
+
+### Linux
+- **UE 5.8**: Ubuntu 22.04, Rocky Linux 8 or Red Hat Linux 8 or newer recommended; compiler clang 20.1.8
### Mobile
-- **UE 5.7**: Minimum Android API level raised to 26 (Android 8.0)
-- Minimum iOS deployment target raised to iOS 14
+- **UE 5.8**: Android minimum install SDK level 26 (Android 8.0+); NDK r27c; minimum SDK for compiling UE 34, recommended 35; Gradle 8.7, AGP 8.5.2
+- **UE 5.8**: iOS / iPadOS / tvOS SDK 17 or later; Xcode 26.0 minimum, 26.1.1 recommended (iOS targets)
+- **UE 5.8**: iOS Shader Model 6 is Experimental
---
## Migration Checklist
-When upgrading from UE 5.3 to UE 5.7:
+When upgrading from UE 5.3 to UE 5.8:
+- [ ] Remove any `CppStandardVersion.Cpp17` / `Cpp14` override (5.8 requires C++20)
+- [ ] Install a 5.8 toolchain (Visual Studio 2022 17.14+ or 2026 on Windows; Xcode 26 for iOS)
+- [ ] Move PhysicsMover usage to ChaosMover
+- [ ] Rebuild and fix calls to deprecated APIs removed in 5.8 (see **UE 5.8 Changes**)
- [ ] Review Substrate materials (convert if ready for new system)
- [ ] Audit PCG usage (update to production API if using experimental)
-- [ ] Test Megalights performance (enable and benchmark)
+- [ ] Test MegaLights performance (enable and benchmark)
- [ ] Migrate legacy input to Enhanced Input
- [ ] Convert high-poly meshes to Nanite
- [ ] Update shaders for DX12 (Windows) or Metal 3 (macOS)
-- [ ] Verify minimum platform versions (Android 8.0, iOS 14)
+- [ ] Verify minimum platform versions (5.8: Android install SDK 26 / Android 8.0, iOS SDK 17, macOS Sonoma 14)
- [ ] Test Lumen and Nanite performance on target hardware
---
**Sources:**
+- UE 5.8 release notes (Upgrade Notes, API Change entries, Platform SDK Upgrades, WASAPI, Mobile Renderer, Zenserver as Cooked Output Store): https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
+- 5.8 engine source, read from a UE 5.8.1 install on 2026-10-17: `Engine/Source/Programs/UnrealBuildTool/System/CppCompileEnvironment.cs` (`Cpp14`/`Cpp17` marked `[Obsolete("Deprecated in UE5.8 ...")]`, `Minimum = Cpp20`); `Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp` (Substrate defaults for new and existing projects); `Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h` and `Engine/Source/Runtime/Renderer/Private/MegaLights/MegaLights.cpp` (MegaLights setting and default)
+- Substrate Beta in 5.5, MegaLights Beta in 5.7: https://forums.unrealengine.com/t/unreal-engine-5-5-released/2117936 , https://forums.unrealengine.com/t/unreal-engine-5-7-released/2673913
- https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-7-release-notes
- https://dev.epicgames.com/documentation/en-us/unreal-engine/upgrading-projects-to-newer-versions-of-unreal-engine
diff --git a/docs/engine-reference/unreal/current-best-practices.md b/docs/engine-reference/unreal/current-best-practices.md
index bc9f4b20..84434704 100644
--- a/docs/engine-reference/unreal/current-best-practices.md
+++ b/docs/engine-reference/unreal/current-best-practices.md
@@ -1,23 +1,24 @@
-# Unreal Engine 5.7 — Current Best Practices
+# Unreal Engine 5.8 — Current Best Practices
-**Last verified:** 2026-02-13
+**Last verified:** 2026-10-17 (5.8 pin: project setup, C++ standard, Blueprint Nativization, MegaLights, Substrate, Object Pooling sample, logging); 2026-02-13 (rest of file, written against 5.7)
Modern UE5 patterns that may not be in the LLM's training data.
-These are production-ready recommendations as of UE 5.7.
+These are production-ready recommendations as of UE 5.8.
---
## Project Setup
-### Use UE 5.7 for New Projects
-- Latest features: Megalights, production-ready Substrate and PCG
-- Better performance and stability
+### Use UE 5.8 for New Projects
+- Latest release: 5.8 (latest hotfix 5.8.3, September 2026)
+- MegaLights and Iris are production-ready in 5.8 (per the release notes; the Iris plugin still carries a Beta flag); Substrate and PCG have been since 5.7
+- Needs a C++20 toolchain: Visual Studio 2022 17.14 or newer on Windows (2026 recommended), see `breaking-changes.md` → Platform-Specific
### Choose the Right Rendering Features
- **Lumen**: Real-time global illumination (RECOMMENDED for most projects)
- **Nanite**: Virtualized geometry for high-poly meshes (RECOMMENDED for detailed environments)
-- **Megalights**: Millions of dynamic lights (RECOMMENDED for complex lighting)
-- **Substrate**: Modular material system (RECOMMENDED for new projects)
+- **MegaLights**: Many shadow-casting dynamic lights at a consistent GPU cost (production-ready in 5.8; RECOMMENDED for complex lighting)
+- **Substrate**: Modular material system (RECOMMENDED; enabled automatically for new projects since 5.7)
---
@@ -59,7 +60,11 @@ Sources:
## C++ Coding
-### Use Modern C++ Features (C++20 in UE5.7)
+### Use Modern C++ Features (C++20, the minimum in UE 5.8)
+
+UE 5.8 makes C++20 the floor: `CppStandardVersion.Cpp14` and `Cpp17` are marked
+obsolete ("no longer allowed, code will not compile with this version") and
+`Minimum = Cpp20`. C++23 is selectable but marked experimental.
```cpp
// ✅ Use TObjectPtr<T> (UE5 type-safe pointers)
@@ -116,8 +121,9 @@ void OnDeath();
// ✅ Use Event Tick sparingly (expensive)
// Prefer timers or events
-// ✅ Use Blueprint Nativization (Blueprints → C++)
-// Project Settings > Packaging > Blueprint Nativization
+// ✅ Move hot Blueprint logic to C++ by hand
+// (Blueprint Nativization is gone: UE 5.8's packaging settings keep only an
+// unused EProjectPackagingBlueprintNativizationMethod enum, no setting)
// ✅ Cache frequently accessed components
// Don't call GetComponent every tick
@@ -125,7 +131,7 @@ void OnDeath();
---
-## Rendering (UE 5.7)
+## Rendering (UE 5.8)
### Use Lumen for Global Illumination
@@ -141,17 +147,22 @@ void OnDeath();
// Automatically LODs millions of triangles (RECOMMENDED for detailed meshes)
```
-### Use Megalights for Complex Lighting (UE 5.5+)
+### Use MegaLights for Complex Lighting (UE 5.5+, production-ready in 5.8)
```cpp
-// Enable: Project Settings > Engine > Rendering > Megalights = Enabled
-// Supports millions of dynamic lights with minimal cost
+// Enable: Project Settings > Engine > Rendering > Direct Lighting > MegaLights
+// (r.MegaLights.EnableForProject, default 0; a Post Process Volume can
+// override it, and it can be disabled per light)
+// Many shadow-casting lights at a consistent, low GPU cost
```
### Use Substrate Materials (Production-Ready in 5.7)
```cpp
-// Enable: Project Settings > Engine > Substrate > Enable Substrate
+// New projects created in 5.7+ have Substrate enabled automatically.
+// Existing projects keep their setting; to enable it:
+// Project Settings > Engine > Rendering > Substrate > Substrate materials
+// (r.Substrate, read-only at runtime, editor restart required)
// Modular, physically accurate materials (RECOMMENDED for new projects)
```
@@ -303,30 +314,33 @@ void AMyCharacter::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLife
```cpp
// ✅ Reuse objects instead of Spawn/Destroy
-//
-// ⚠ INCONSISTENT WITH THIS FILE'S OWN RULE (flagged 2026-08-10).
-// The GC section above states that an unmarked raw UObject pointer is
-// "Dangerous! May be garbage collected" and requires UPROPERTY() +
-// TObjectPtr<T>. This pooling example then holds raw AActor* in a bare TArray,
-// which is exactly the shape that section forbids. FOLLOW THE RULE, NOT THIS
-// SNIPPET: declare the pool UPROPERTY() TArray<TObjectPtr<AActor>>.
-//
-// Left visible rather than silently rewritten: the corrected form has not been
-// verified against Epic's docs for 5.7, and this directory is the offline
-// substitute for them -- editing a code sample here from memory is the failure
-// mode the whole reference exists to prevent. Re-verify, then fix both together.
-TArray<AActor*> ProjectilePool;
+// The pool is a member of a UCLASS. UPROPERTY() makes the container a GC
+// reference, so inactive pooled actors are not collected (same rule as the
+// GC section above).
+UPROPERTY()
+TArray<TObjectPtr<AActor>> ProjectilePool;
+//
+// AActor has no IsActive()/SetActive() -- those are UActorComponent members.
+// A parked actor is hidden, has no collision and does not tick.
AActor* GetPooledProjectile() {
for (AActor* Proj : ProjectilePool) {
- if (!Proj->IsActive()) {
- Proj->SetActive(true);
+ if (Proj && Proj->IsHidden()) {
+ Proj->SetActorHiddenInGame(false);
+ Proj->SetActorEnableCollision(true);
+ Proj->SetActorTickEnabled(true);
return Proj;
}
}
// Pool exhausted, spawn new
return SpawnNewProjectile();
}
+
+void ReturnToPool(AActor* Proj) {
+ Proj->SetActorHiddenInGame(true);
+ Proj->SetActorEnableCollision(false);
+ Proj->SetActorTickEnabled(false);
+}
```
### Use Instanced Static Meshes
@@ -354,6 +368,11 @@ UE_LOG(LogTemp, Warning, TEXT("Player health: %d"), Health);
DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, All);
DEFINE_LOG_CATEGORY(LogMyGame);
UE_LOG(LogMyGame, Error, TEXT("Critical error!"));
+
+// UE 5.8: UE_LOGF takes a printf-style format literal given as "..." or
+// UTF8TEXT("...") (LogMacros.h). Epic asks new code to use it: UE_LOG "will
+// eventually be deprecated", and 5.8 ships ConvertUELog.py to convert most uses.
+UE_LOGF(LogMyGame, Warning, "Player health: %d", Health);
```
### Use Visual Logger
@@ -368,11 +387,11 @@ UE_VLOG_LOCATION(this, LogTemp, Log, TargetLocation, 50.f, FColor::Green, TEXT("
---
-## Summary: UE 5.7 Recommended Stack
+## Summary: UE 5.8 Recommended Stack
| Feature | Use This (2026) | Notes |
|---------|------------------|-------|
-| **Lighting** | Lumen + Megalights | Real-time GI, millions of lights |
+| **Lighting** | Lumen + MegaLights | Real-time GI, many shadow-casting lights |
| **Geometry** | Nanite | High-poly meshes, automatic LOD |
| **Materials** | Substrate | Modular, physically accurate |
| **Input** | Enhanced Input | Rebindable, modular |
@@ -384,5 +403,9 @@ UE_VLOG_LOCATION(this, LogTemp, Log, TargetLocation, 50.f, FColor::Green, TEXT("
---
**Sources:**
-- https://docs.unrealengine.com/5.7/en-US/
+- https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-documentation?application_version=5.8
+- UE 5.8 release notes (MegaLights production-ready, Iris production-ready, Platform SDK Upgrades, `UE_LOGF` upgrade note): https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
+- 5.8 engine source, read from a UE 5.8.1 install on 2026-10-17: C++ standard — `Engine/Source/Programs/UnrealBuildTool/System/CppCompileEnvironment.cs` (`enum CppStandardVersion`); Blueprint Nativization — `Engine/Source/Developer/DeveloperToolSettings/Classes/Settings/ProjectPackagingSettings.h` (the enum is the only reference left in engine source); MegaLights setting — `Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h` (`bEnableMegaLights`, category DirectLighting) and `Engine/Source/Runtime/Renderer/Private/MegaLights/MegaLights.cpp` (default 0); Substrate — `RendererSettings.h` (`bEnableSubstrate`, category Substrate) and `Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp` ("New projects created with 5.7, will have Substrate enabled automatically"); `UE_LOGF` — `Engine/Source/Runtime/Core/Public/Logging/LogMacros.h`
+- Object pooling calls — `Engine/Source/Runtime/Engine/Classes/GameFramework/Actor.h` (UE 5.8.1: `SetActorHiddenInGame`, `SetActorEnableCollision`, `SetActorTickEnabled`, `IsHidden`; no `IsActive`/`SetActive`) and `Engine/Source/Runtime/Engine/Classes/Components/ActorComponent.h` (`UActorComponent::SetActive`/`IsActive`); `AActor` API, UE 5.8: https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/AActor?application_version=5.8
- https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-7-release-notes
+- Object pooling container (`UPROPERTY() TArray<TObjectPtr<AActor>>`) — *Unreal Object Handling* (a UPROPERTY reference keeps an object alive "whether it's a simple Object pointer or an Unreal Engine container class"; a raw pointer "will not be automatically nulled, nor will it prevent garbage collection"): https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-object-handling-in-unreal-engine?application_version=5.7 ; *Object Pointers* ("TObjectPtr is only garbage collection safe if it is marked as a UPROPERTY"; use it in place of raw pointers): https://dev.epicgames.com/documentation/en-us/unreal-engine/object-pointers-in-unreal-engine?application_version=5.7
diff --git a/docs/engine-reference/unreal/deprecated-apis.md b/docs/engine-reference/unreal/deprecated-apis.md
index f88d9549..9369070e 100644
--- a/docs/engine-reference/unreal/deprecated-apis.md
+++ b/docs/engine-reference/unreal/deprecated-apis.md
@@ -1,12 +1,35 @@
-# Unreal Engine 5.7 — Deprecated APIs
+# Unreal Engine 5.8 — Deprecated APIs
-**Last verified:** 2026-02-13
+**Last verified:** 2026-10-17 (Deprecated in UE 5.8, Gameplay Ability System row, summary); 2026-02-13 (rest of file, written against 5.7)
Quick lookup table for deprecated APIs and their replacements.
Format: **Don't use X** → **Use Y instead**
---
+## Deprecated in UE 5.8
+
+From the 5.8 release notes' Upgrade Notes and the 5.8 engine headers (sources at
+the end of this file). Deprecated items still compile with a warning unless the
+Notes column says otherwise.
+
+| Deprecated | Replacement | Notes |
+|------------|-------------|-------|
+| `UE_LOG(...)` | `UE_LOGF(Category, Verbosity, "fmt", ...)` | Not deprecated yet: Epic says UE_LOG "will eventually be deprecated" and asks for `UE_LOGF`. The header documents the format as a printf-style literal given as `"..."` or `UTF8TEXT("...")`. 5.8 ships `ConvertUELog.py` for most uses |
+| `#if PLATFORM_IOS` (and other `PLATFORM_*`) | `#if UE_PLATFORM_IOS` (`UE_PLATFORM_*`) | Optional migration; `PLATFORM_IOS` can be stomped by Apple framework headers |
+| `CppStandardVersion.Cpp17` / `Cpp14` | `CppStandardVersion.Default` (C++20) | Obsolete in 5.8: code no longer compiles with them |
+| Raw Input plugin (`RawInput`) | Game Input for Windows plugin (`GameInputWindows`, Beta) | `"DeprecatedEngineVersion": "5.8"` in `RawInput.uplugin` |
+| PhysicsMover (Mover plugin) | ChaosMover plugin | Removed in 5.8, not just deprecated |
+| `FActiveGameplayEffectHandle(int32)` | `FActiveGameplayEffectHandle::GenerateNewHandle` or `GetInstantExecutedHandle()` | `UE_DEPRECATED(5.8, ...)` |
+| `FSmartName`, `FSmartNameMapping`, `FSmartNameContainer` | None: remove the use | `UE_DEPRECATED(5.8, "Smart names and their mappings are no longer used")` |
+| `UFadeFunction`, `FFadeFunctionData`, `EWaveEditorFadeMode` | `UTransformationFadeFunction`, `UWaveformTransformationFade` | Waveform Editor |
+| `URigHierarchy::FindBone` / `FindControl` / `FindNull` in Blueprint | `Contains(Key)`, `GetBoneType(Key)`, `GetControlSettings(Key)`, `IsSelected(Key)`, `GetIndex(Key)` | Control Rig; existing graphs keep working with warnings |
+| `PluginName.ini` / `BasePluginName.ini` in a plugin | `DefaultPluginName.ini` | Plugin config files |
+| `r.Water.SingleLayer.ForceVelocity` | `r.Water.SingleLayer.VelocityOutputPass` (or the project setting) | Rendering CVar |
+| `EWindowType::GameWindow` | `EWindowType::Normal` | Slate |
+
+---
+
## Input
| Deprecated | Replacement | Notes |
@@ -23,7 +46,7 @@ Format: **Don't use X** → **Use Y instead**
| Deprecated | Replacement | Notes |
|------------|-------------|-------|
-| Legacy material nodes | Substrate material nodes | Substrate is production-ready in 5.7 |
+| Legacy material nodes | Substrate material nodes | Substrate is production-ready in 5.7 and on by default for new projects |
| Forward shading (default) | Deferred + Lumen | Lumen is default in UE5 |
| Old lighting workflow | Lumen Global Illumination | Real-time GI |
@@ -56,6 +79,15 @@ Format: **Don't use X** → **Use Y instead**
---
+## Gameplay Ability System
+
+| Deprecated | Replacement | Notes |
+|------------|-------------|-------|
+| `UGameplayAbility::AbilityTags` (direct access) | `GetAssetTags()` to read; `SetAssetTags()` in the constructor to set | `UE_DEPRECATED_FORGAME(5.5, ...)` in the 5.8 header: "This is being made non-mutable, private and renamed to AssetTags in the future" |
+| `FActiveGameplayEffectHandle(int32)` | `GenerateNewHandle` / `GetInstantExecutedHandle()` | Deprecated in 5.8 |
+
+---
+
## Niagara (VFX)
| Deprecated | Replacement | Notes |
@@ -150,21 +182,25 @@ UNiagaraComponent* NiagaraComp = CreateDefaultSubobject<UNiagaraComponent>(TEXT(
---
-## Summary: UE 5.7 Tech Stack
+## Summary: UE 5.8 Tech Stack
| Feature | Use This (2026) | Avoid This (Legacy) |
|---------|------------------|----------------------|
| **Input** | Enhanced Input | Legacy Input Bindings |
| **Materials** | Substrate | Legacy Material System |
-| **Lighting** | Lumen + Megalights | Lightmaps + Limited Lights |
+| **Lighting** | Lumen + MegaLights | Lightmaps + Limited Lights |
| **Particles** | Niagara | Cascade |
| **Audio** | MetaSounds | Sound Cue (for logic) |
| **World Streaming** | World Partition | World Composition |
| **Animation Retarget** | IK Rig + Retargeter | Old Retargeting |
| **Geometry** | Nanite (high-poly) | Standard Static Mesh LODs |
+| **Logging** | `UE_LOGF` (5.8) | `UE_LOG` (still supported) |
+| **Windows device input** | Game Input for Windows | Raw Input plugin (deprecated 5.8) |
---
**Sources:**
+- UE 5.8 release notes, Upgrade Notes and API Change entries: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
+- 5.8 engine headers, read from a UE 5.8.1 install on 2026-10-17: `Engine/Source/Runtime/Core/Public/Logging/LogMacros.h` (`UE_LOGF`); `Engine/Source/Runtime/Core/Public/HAL/Platform.h` (`UE_PLATFORM_*`); `Engine/Source/Programs/UnrealBuildTool/System/CppCompileEnvironment.cs`; `Engine/Plugins/Experimental/RawInput/RawInput.uplugin` and `Engine/Plugins/GameInputWindows/GameInputWindows.uplugin`; `Engine/Plugins/Runtime/GameplayAbilities/Source/GameplayAbilities/Public/ActiveGameplayEffectHandle.h` and `.../Public/Abilities/GameplayAbility.h`; `Engine/Source/Runtime/Engine/Classes/Animation/SmartName.h`
- https://docs.unrealengine.com/5.7/en-US/deprecated-and-removed-features/
- https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-7-release-notes
diff --git a/docs/engine-reference/unreal/modules/animation.md b/docs/engine-reference/unreal/modules/animation.md
index 49887030..22b215d2 100644
--- a/docs/engine-reference/unreal/modules/animation.md
+++ b/docs/engine-reference/unreal/modules/animation.md
@@ -1,13 +1,22 @@
-# Unreal Engine 5.7 — Animation Module Reference
+# Unreal Engine 5.8 — Animation Module Reference
-**Last verified:** 2026-02-13
-**Knowledge Gap:** UE 5.7 animation authoring improvements, Control Rig 2.0
+**Last verified:** 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
+**Knowledge Gap:** UE 5.4-5.8 animation authoring improvements, Control Rig 2.0
+
+> **UE 5.8 changes:** Smart names are deprecated — `FSmartName`,
+> `FSmartNameMapping` and `FSmartNameContainer` carry `UE_DEPRECATED(5.8, "Smart
+> names and their mappings are no longer used")` (`Engine/Source/Runtime/Engine/Classes/Animation/SmartName.h`).
+> Non-reflected deprecated Animation, Control Rig, Persona and Live Link APIs
+> from 5.0-5.6 were removed (e.g. `UMotionWarpingComponent::GetCharacterOwner`
+> → `GetOwnerAdapter()->GetActor()`). Control Rig Physics and the RigMapper
+> retargeting tool are Beta; Animation Mixing in Sequencer and Direct Mesh
+> Controls are Experimental. Source: UE 5.8 release notes, https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
---
## Overview
-UE 5.7 animation systems:
+UE 5.8 animation systems:
- **Animation Blueprint**: State machine-based animation logic
- **Control Rig**: Runtime procedural animation (production-ready in UE5)
- **IK Rig + Retargeter**: Modern retargeting system
diff --git a/docs/engine-reference/unreal/modules/audio.md b/docs/engine-reference/unreal/modules/audio.md
index 9495e49b..26d7beb4 100644
--- a/docs/engine-reference/unreal/modules/audio.md
+++ b/docs/engine-reference/unreal/modules/audio.md
@@ -1,13 +1,23 @@
-# Unreal Engine 5.7 — Audio Module Reference
+# Unreal Engine 5.8 — Audio Module Reference
-**Last verified:** 2026-02-13
-**Knowledge Gap:** UE 5.7 MetaSounds production-ready
+**Last verified:** 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
+**Knowledge Gap:** UE 5.7 MetaSounds production-ready; UE 5.8 WASAPI default on Windows
+
+> **UE 5.8 changes:** The default Windows audio backend is now WASAPI
+> (XAudio2 is an opt-in fallback; Epic: "No changes are required on the
+> developers end"). `au.EnableRelativeRenderCostVoiceLimit` is on by default,
+> so fewer sounds may play under the same voice count — revisit voice-count
+> tuning. Attenuation submix sends that were implicitly disabled by
+> `bEnableSubmixSends` may now be audible. Audio Insights is production-ready;
+> Audio Subtitles is Beta; MetaSound Node Configuration and Templates are
+> Experimental. Custom MetaSound nodes: `FNodeClassMetadata::DefaultInterface`
+> now takes `FClassInterface`. Source: UE 5.8 release notes, https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
---
## Overview
-UE 5.7 audio systems:
+UE 5.8 audio systems:
- **MetaSounds**: Node-based procedural audio (RECOMMENDED, production-ready)
- **Sound Cues**: Legacy node-based audio (use for simple cases)
- **Audio Component**: Play sounds on actors
diff --git a/docs/engine-reference/unreal/modules/input.md b/docs/engine-reference/unreal/modules/input.md
index d956782d..5771e819 100644
--- a/docs/engine-reference/unreal/modules/input.md
+++ b/docs/engine-reference/unreal/modules/input.md
@@ -1,13 +1,23 @@
-# Unreal Engine 5.7 — Input Module Reference
+# Unreal Engine 5.8 — Input Module Reference
-**Last verified:** 2026-02-13
-**Knowledge Gap:** UE 5.7 uses Enhanced Input as default (legacy input deprecated)
+**Last verified:** 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
+**Knowledge Gap:** UE 5.7+ uses Enhanced Input as default (legacy input deprecated); UE 5.8 unifies it with Common UI input
+
+> **UE 5.8 changes:** Enhanced Input and Common Input/UI are unified,
+> which "removes the need for duplicate data assets"; there is a new Input
+> Debugger for Enhanced Input UI. Fixes ship behind CVars that "will be removed
+> in a future release": `EnhancedInput.IgnoreHeldKeysOnFlush` (default true) and
+> `EnhancedInput.CorrectTouchBoolActionKeys` (default on). The Raw Input plugin
+> is deprecated (`"DeprecatedEngineVersion": "5.8"`) in favour of the Game Input
+> for Windows plugin (`GameInputWindows`, Beta); the release notes say to set
+> `IncludeRedistFiles=True` in the Game Input section of `DefaultEngine.ini` so
+> packaging includes `GameInputRedist.msi`. Source: UE 5.8 release notes, https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
---
## Overview
-UE 5.7 input systems:
+UE 5.8 input systems:
- **Enhanced Input** (RECOMMENDED, default in UE5): Modular, rebindable, context-based
- **Legacy Input**: Deprecated, avoid for new projects
diff --git a/docs/engine-reference/unreal/modules/navigation.md b/docs/engine-reference/unreal/modules/navigation.md
index 4ba3ebdd..82fdfed5 100644
--- a/docs/engine-reference/unreal/modules/navigation.md
+++ b/docs/engine-reference/unreal/modules/navigation.md
@@ -1,13 +1,19 @@
-# Unreal Engine 5.7 — Navigation Module Reference
+# Unreal Engine 5.8 — Navigation Module Reference
-**Last verified:** 2026-02-13
-**Knowledge Gap:** UE 5.7 navigation improvements
+**Last verified:** 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
+**Knowledge Gap:** UE 5.7-5.8 navigation improvements
+
+> **UE 5.8 changes:** Static meshes can define their own walkable areas
+> during navmesh generation (per-mesh area costs, e.g. so AI walks around a
+> couch rather than over it), enabled per mesh through a flag and an area class
+> setting on NavCollision. Mover gained NavWalking support for Detour Crowd.
+> Source: UE 5.8 release notes, https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
---
## Overview
-UE 5.7 navigation systems:
+UE 5.8 navigation systems:
- **Nav Mesh**: Automatic pathfinding mesh for AI
- **AI Controller**: Controls AI movement and behavior
- **Behavior Trees**: AI decision-making (covered in AI module)
diff --git a/docs/engine-reference/unreal/modules/networking.md b/docs/engine-reference/unreal/modules/networking.md
index d6ce54a7..05e96461 100644
--- a/docs/engine-reference/unreal/modules/networking.md
+++ b/docs/engine-reference/unreal/modules/networking.md
@@ -1,13 +1,28 @@
-# Unreal Engine 5.7 — Networking Module Reference
-
-**Last verified:** 2026-02-13
-**Knowledge Gap:** UE 5.7 networking improvements
+# Unreal Engine 5.8 — Networking Module Reference
+
+**Last verified:** 2026-10-18 (Iris status: release notes and plugin flag); 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
+**Knowledge Gap:** UE 5.7-5.8 networking improvements (Iris production-ready in 5.8)
+
+> **UE 5.8 changes:** Iris "is now production-ready for licensees in UE
+> 5.8" (the `Iris.uplugin` in a 5.8.1 install still carries a Beta flag), with
+> clearer protocol-mismatch errors and RPC DoS detection re-enabled. Thread-safety
+> primitives were added for parallel `NetConnection::Tick`; a target that does
+> not need them can drop them with `ExcludeParallelIrisSupport` in
+> `TargetRules.cs`. Network Prediction gained optional Iris support. Source: UE
+> 5.8 release notes, https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
+>
+> **The notes and the plugin flag disagree.** Treat Iris as production-ready,
+> as the release notes say ("Iris is now production-ready for licensees in UE
+> 5.8", Framework > "Iris: Production-Ready Replication System"), and expect
+> the editor's plugin list to show it as Beta: `Engine/Plugins/Experimental/Iris/Iris.uplugin`
+> in a 5.8.1 install (CL 56057345) has `"IsBetaVersion": true`. Both read
+> 2026-10-18.
---
## Overview
-UE 5.7 networking:
+UE 5.8 networking:
- **Client-Server Architecture**: Server-authoritative (RECOMMENDED)
- **Replication**: Automatic state synchronization
- **RPCs (Remote Procedure Calls)**: Call functions across network
diff --git a/docs/engine-reference/unreal/modules/physics.md b/docs/engine-reference/unreal/modules/physics.md
index 70025475..0c80abde 100644
--- a/docs/engine-reference/unreal/modules/physics.md
+++ b/docs/engine-reference/unreal/modules/physics.md
@@ -1,7 +1,13 @@
-# Unreal Engine 5.7 — Physics Module Reference
+# Unreal Engine 5.8 — Physics Module Reference
-**Last verified:** 2026-02-13
-**Knowledge Gap:** UE 5.7 Chaos Physics improvements
+**Last verified:** 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
+**Knowledge Gap:** UE 5.7-5.8 Chaos Physics improvements
+
+> **UE 5.8 changes:** PhysicsMover / NetworkPhysicsLiaison code was removed
+> from the Mover plugin; use the ChaosMover plugin ("Equivalent functionality
+> is there for every PhysicsMover feature"). Mover and ChaosMover are still
+> flagged Experimental. Floor queries: move `FloorQueryUtil` calls to the new
+> `FFloorCheckSettings` variants. Source: UE 5.8 release notes, https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
---
diff --git a/docs/engine-reference/unreal/modules/rendering.md b/docs/engine-reference/unreal/modules/rendering.md
index 329430ab..f4c0a9bf 100644
--- a/docs/engine-reference/unreal/modules/rendering.md
+++ b/docs/engine-reference/unreal/modules/rendering.md
@@ -1,16 +1,29 @@
-# Unreal Engine 5.7 — Rendering Module Reference
-
-**Last verified:** 2026-02-13
-**Knowledge Gap:** UE 5.7 has Megalights, production-ready Substrate, and Lumen improvements
+# Unreal Engine 5.8 — Rendering Module Reference
+
+**Last verified:** 2026-10-18 (MegaLights tooltip against the 5.8 notes and source); 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
+**Knowledge Gap:** UE 5.8 has production-ready MegaLights, production-ready Substrate (5.7), Lumen Lite, and Lumen improvements
+
+> **UE 5.8 changes:** MegaLights is production-ready (enable it in Project
+> Settings > Engine > Rendering > Direct Lighting > MegaLights,
+> `r.MegaLights.EnableForProject`, default 0). Lumen Lite (Beta) is a
+> medium-quality GI setting, about twice as fast as Lumen high quality and the
+> default for current-generation handheld consoles. Mobile: multi-pass deferred
+> is the default path (forward is opt-in), with SSAO, SSR, deferred decals and
+> contact shadows. Lumen applies height fog to reflection ray hits by default
+> (`r.Lumen.HeightFog 1`). Substrate has been on for new projects since 5.7
+> (`r.Substrate`); Substrate NPR (toon) shading and Fog Screen Space Scattering
+> are Experimental. Sources: UE 5.8 release notes, https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8 ;
+> `Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h` and
+> `Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp` (5.8.1 install).
---
## Overview
-UE 5.7 rendering stack:
+UE 5.8 rendering stack:
- **Lumen**: Real-time global illumination (default)
- **Nanite**: Virtualized geometry for millions of triangles
-- **Megalights**: Support for millions of dynamic lights (NEW in 5.5+)
+- **MegaLights**: Many shadow-casting dynamic lights (NEW in 5.5+, production-ready in 5.8)
- **Substrate**: Production-ready modular material system (NEW in 5.7)
---
@@ -65,16 +78,41 @@ MeshComp->SetStaticMesh(NaniteMesh); // Automatically uses Nanite if enabled
---
-## Megalights (UE 5.5+)
+## MegaLights (UE 5.5+, production-ready in 5.8)
-### Enable Megalights
+### Enable MegaLights
```cpp
-// Project Settings > Engine > Rendering > Megalights = Enabled
-// Supports millions of dynamic lights with minimal performance cost
+// Project Settings > Engine > Rendering > Direct Lighting > MegaLights
+// (r.MegaLights.EnableForProject, default 0; a Post Process Volume can
+// override it, and it can be disabled per light)
+// Many shadow-casting lights at a consistent, low GPU cost
```
-### Megalights Usage
+### The editor tooltip is older than the 5.8 release notes
+
+In a 5.8.1 install, this setting's tooltip (`RendererSettings.h`) and the
+`r.MegaLights.EnableForProject` help text (`MegaLights.cpp`) still end
+"Experimental feature." and say MegaLights "requires Hardware Ray Tracing, and
+does not support Directional Lights". Follow the release notes and the engine
+code instead:
+
+- **Status:** "Megalights is now entering Production Ready status with Unreal
+ Engine 5.8" (5.8 release notes, Rendering > Megalights).
+- **Ray tracing:** the renderer accepts hardware or software ray tracing support
+ (`HasRequiredTracingData` in `MegaLights.cpp`). Shadow rays use hardware ray
+ tracing while `r.MegaLights.HardwareRayTracing` is 1, the default. Shadows
+ come from ray tracing (the default) or Virtual Shadow Maps:
+ `r.MegaLights.DefaultShadowMethod` 0 or 1.
+- **Directional lights:** supported behind `r.MegaLights.DirectionalLights`,
+ default 0 (off). The 5.7 release notes list Directional Light support.
+
+Sources, read 2026-10-18: the 5.8 and 5.7 release notes (§ Sources); in a UE
+5.8.1 install (CL 56057345), `Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h`,
+`Engine/Source/Runtime/Renderer/Private/MegaLights/MegaLights.cpp` and
+`MegaLightsRayTracing.cpp`.
+
+### MegaLights Usage
```cpp
// Add point lights as usual
@@ -82,7 +120,7 @@ UPointLightComponent* Light = CreateDefaultSubobject<UPointLightComponent>(TEXT(
Light->SetIntensity(5000.0f);
Light->SetAttenuationRadius(500.0f);
-// Megalights automatically handles thousands/millions of these
+// MegaLights handles many of these at a consistent GPU cost
```
---
@@ -92,8 +130,9 @@ Light->SetAttenuationRadius(500.0f);
### Enable Substrate
```cpp
-// Project Settings > Engine > Substrate > Enable Substrate
-// Restart editor
+// On by default for new projects created in 5.7+.
+// Existing project: Project Settings > Engine > Rendering > Substrate >
+// Substrate materials (r.Substrate), then restart the editor
```
### Substrate Material Nodes
@@ -292,6 +331,8 @@ Console commands:
---
## Sources
+- UE 5.8 release notes: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
+- UE 5.7 release notes: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-7-release-notes?application_version=5.7
- https://docs.unrealengine.com/5.7/en-US/lumen-global-illumination-and-reflections-in-unreal-engine/
- https://docs.unrealengine.com/5.7/en-US/nanite-virtualized-geometry-in-unreal-engine/
- https://docs.unrealengine.com/5.7/en-US/substrate-materials-in-unreal-engine/
diff --git a/docs/engine-reference/unreal/modules/ui.md b/docs/engine-reference/unreal/modules/ui.md
index bfd9cf53..5dc9788a 100644
--- a/docs/engine-reference/unreal/modules/ui.md
+++ b/docs/engine-reference/unreal/modules/ui.md
@@ -1,13 +1,20 @@
-# Unreal Engine 5.7 — UI Module Reference
+# Unreal Engine 5.8 — UI Module Reference
-**Last verified:** 2026-02-13
-**Knowledge Gap:** UE 5.7 UMG and CommonUI improvements
+**Last verified:** 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
+**Knowledge Gap:** UE 5.7-5.8 UMG and CommonUI improvements (Enhanced Input unified with Common UI in 5.8)
+
+> **UE 5.8 changes:** Enhanced Input and Common Input/UI are unified (no
+> duplicate data assets; Input Debugger for Enhanced Input UI). Slate:
+> `EWindowType::GameWindow` → `EWindowType::Normal`; the "OnlyGameWindow" CVars
+> are renamed "OnlyProjectContent" and `bDebugGameWindowOnly` is now
+> `bDebugProjectContentOnly`; a module depending on `SlateRHIRender` may also
+> need `SlateBaseRenderer`. Source: UE 5.8 release notes, https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
---
## Overview
-UE 5.7 UI systems:
+UE 5.8 UI systems:
- **UMG (Unreal Motion Graphics)**: Visual widget-based UI (RECOMMENDED)
- **CommonUI**: Cross-platform input-aware UI framework (console/PC)
- **Slate**: Low-level C++ UI (engine/editor UI)
diff --git a/docs/engine-reference/unreal/plugins/common-ui.md b/docs/engine-reference/unreal/plugins/common-ui.md
index 99efb1ee..b2b5c004 100644
--- a/docs/engine-reference/unreal/plugins/common-ui.md
+++ b/docs/engine-reference/unreal/plugins/common-ui.md
@@ -1,9 +1,16 @@
-# Unreal Engine 5.7 — CommonUI Plugin
+# Unreal Engine 5.8 — CommonUI Plugin
-**Last verified:** 2026-02-13
+**Last verified:** 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
**Status:** Production-Ready
**Plugin:** `CommonUI` (built-in, enable in Plugins)
+> **UE 5.8 changes:** Common Input/UI and Enhanced Input are unified, which
+> "removes the need for duplicate data assets", with more reliable event
+> processing, better widget binding and an Input Debugger for Enhanced Input
+> UI. CommonUI tags are now comparable in Blueprint. The `CommonUI.uplugin` in a
+> 5.8.1 install carries no Beta/Experimental flag. Source: UE 5.8 release
+> notes, https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
+
---
## Overview
diff --git a/docs/engine-reference/unreal/plugins/gameplay-ability-system.md b/docs/engine-reference/unreal/plugins/gameplay-ability-system.md
index 2da059cc..4ce689a9 100644
--- a/docs/engine-reference/unreal/plugins/gameplay-ability-system.md
+++ b/docs/engine-reference/unreal/plugins/gameplay-ability-system.md
@@ -1,6 +1,6 @@
-# Unreal Engine 5.7 — Gameplay Ability System (GAS)
+# Unreal Engine 5.8 — Gameplay Ability System (GAS)
-**Last verified:** 2026-02-13
+**Last verified:** 2026-10-17 (ability asset tags, re-confirmed against the 5.8 header); 2026-02-13 (rest of file, written against 5.7)
**Status:** Production-Ready
**Plugin:** `GameplayAbilities` (built-in, enable in Plugins)
@@ -210,15 +210,11 @@ public:
InstancingPolicy = EGameplayAbilityInstancingPolicy::InstancedPerActor;
NetExecutionPolicy = EGameplayAbilityNetExecutionPolicy::ServerInitiated;
- // Tags
- // ⚠️ UNVERIFIED FOR 5.7 — `AbilityTags` may be deprecated in favour of
- // SetAssetTags()/GetAssetTags(); the change is believed to have landed
- // around 5.5.
- // NOT SOURCEABLE — the 5.7 tag API for abilities is not covered by
- // docs/engine-reference/unreal/ (no 5.7 API dump). Verify against the UE
- // 5.7 docs before using this snippet, and correct both occurrences (here
- // and in "Use Tags in Abilities") together.
- AbilityTags.AddTag(FGameplayTag::RequestGameplayTag(FName("Ability.Attack.Fireball")));
+ // Tags: the ability's own tags (asset tags, formerly AbilityTags).
+ // Set them with SetAssetTags(), constructor only; read with GetAssetTags().
+ FGameplayTagContainer Tags;
+ Tags.AddTag(FGameplayTag::RequestGameplayTag(FName("Ability.Attack.Fireball")));
+ SetAssetTags(Tags);
}
virtual void ActivateAbility(const FGameplayAbilitySpecHandle Handle, const FGameplayAbilityActorInfo* ActorInfo,
@@ -346,8 +342,10 @@ class UGA_MeleeAttack : public UGameplayAbility {
public:
UGA_MeleeAttack() {
- // This ability has these tags
- AbilityTags.AddTag(FGameplayTag::RequestGameplayTag(FName("Ability.Attack.Melee")));
+ // This ability has these tags (asset tags; SetAssetTags() is constructor-only)
+ FGameplayTagContainer Tags;
+ Tags.AddTag(FGameplayTag::RequestGameplayTag(FName("Ability.Attack.Melee")));
+ SetAssetTags(Tags);
// Block these tags while active
BlockAbilitiesWithTag.AddTag(FGameplayTag::RequestGameplayTag(FName("Ability.Attack")));
@@ -406,4 +404,5 @@ void AMyCharacter::OnHealthChanged(const FOnAttributeChangeData& Data) {
## Sources
- https://docs.unrealengine.com/5.7/en-US/gameplay-ability-system-for-unreal-engine/
- Clamping: *Gameplay Attributes and Attribute Sets* https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-attributes-and-attribute-sets-for-the-gameplay-ability-system-in-unreal-engine ; `UAttributeSet` API https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UAttributeSet ; `PreAttributeChange` https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UAttributeSet/PreAttributeChange
+- Ability asset tags (`SetAssetTags()` / `GetAssetTags()`) — `UGameplayAbility` API, UE 5.7: https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UGameplayAbility?application_version=5.7 ; `SetAssetTags`: https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UGameplayAbility/SetAssetTags?application_version=5.7 . The 5.7 reference lists `SetAssetTags(const FGameplayTagContainer&)` as protected, "formerly AbilityTags", callable "only ... during construction"; `GetAssetTags()` as the public read; and `AbilityTags` as a public variable "exposed for backwards compatibility" (no deprecation note on the page). Re-confirmed for UE 5.8 on 2026-10-17 against `Engine/Plugins/Runtime/GameplayAbilities/Source/GameplayAbilities/Public/Abilities/GameplayAbility.h` (5.8.1 install): `GetAssetTags()` public, `SetAssetTags(const FGameplayTagContainer&)` protected ("This can only be called during construction"), and `AbilityTags` still a public `UPROPERTY`, marked `UE_DEPRECATED_FORGAME(5.5, "Use GetAssetTags(). This is being made non-mutable, private and renamed to AssetTags in the future. Use SetAssetTags to set defaults (in constructor only).")` — so game code that touches `AbilityTags` directly gets a deprecation warning. 5.8 API page: https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UGameplayAbility/SetAssetTags?application_version=5.8 . Also deprecated in 5.8: the `FActiveGameplayEffectHandle(int32)` constructor (use `GenerateNewHandle` or `GetInstantExecutedHandle()`; `.../Public/ActiveGameplayEffectHandle.h`).
- https://github.com/tranek/GASDocumentation (community guide)
diff --git a/docs/engine-reference/unreal/plugins/gameplay-camera-system.md b/docs/engine-reference/unreal/plugins/gameplay-camera-system.md
index 0dc2e4c8..79c351d8 100644
--- a/docs/engine-reference/unreal/plugins/gameplay-camera-system.md
+++ b/docs/engine-reference/unreal/plugins/gameplay-camera-system.md
@@ -1,9 +1,19 @@
-# Unreal Engine 5.7 — Gameplay Camera System
+# Unreal Engine 5.8 — Gameplay Camera System
-**Last verified:** 2026-02-13
-**Status:** ⚠️ Experimental (introduced in UE 5.5)
+**Last verified:** 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
+**Status:** ⚠️ Experimental (introduced in UE 5.5; still flagged Experimental in 5.8)
**Plugin:** `GameplayCameras` (built-in, enable in Plugins)
+> **UE 5.8 changes:** The camera component can run its own camera system
+> ("standalone" mode, the default) or only a camera evaluation context. The
+> player camera manager now runs whatever is the view target as a "blackbox";
+> for blending or child directors a procedural camera must be activated with
+> dedicated new methods such as "Activate Gameplay Camera". Rig/modifier
+> activation and shake start/stop methods were moved; there is a new "aim-at"
+> camera action and a camera action service. `GameplayCameras.uplugin` (5.8.1)
+> is flagged Experimental and enabled by default. Source: UE 5.8 release notes,
+> https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
+
---
## Overview
@@ -18,7 +28,7 @@ camera modes, blending, and context-aware camera behavior.
- Smooth camera blending between modes
- Procedural camera motion (camera shake, lag, offset)
-**⚠️ Warning:** This plugin is experimental in UE 5.5-5.7. Expect API changes in future versions.
+**⚠️ Warning:** This plugin is experimental in UE 5.5-5.8. Expect API changes in future versions.
---
@@ -308,7 +318,7 @@ UGameplayCameraComponent* CameraComponent;
## Limitations (Experimental Status)
-- **API Instability**: Expect breaking changes in UE 5.8+
+- **API Instability**: Expect breaking changes in later releases (5.8 already reworked component and activation APIs)
- **Limited Documentation**: Official docs still evolving
- **Blueprint Support**: Primarily C++ focused (Blueprint support improving)
- **Production Risk**: Test thoroughly before shipping
diff --git a/docs/engine-reference/unreal/plugins/pcg.md b/docs/engine-reference/unreal/plugins/pcg.md
index 3d11ab6f..268407d7 100644
--- a/docs/engine-reference/unreal/plugins/pcg.md
+++ b/docs/engine-reference/unreal/plugins/pcg.md
@@ -1,9 +1,19 @@
-# Unreal Engine 5.7 — PCG (Procedural Content Generation)
+# Unreal Engine 5.8 — PCG (Procedural Content Generation)
-**Last verified:** 2026-02-13
+**Last verified:** 2026-10-17 (UE 5.8 changes block); 2026-02-13 (rest of file, written against 5.7)
**Status:** Production-Ready (as of UE 5.7)
**Plugin:** `PCG` (built-in, enable in Plugins)
+> **UE 5.8 changes:** Non-destructive manual editing of PCG data (selection,
+> exclusion, modification, restore; a Data Overrides window), complex metadata
+> attributes (arrays, structs, sets, maps), embedded subgraphs stored inside a
+> graph, a graph parameters hierarchy editor, and GPU runtime scatter "within
+> the same performance range as the landscape GPU grass system". New nodes
+> include metadata array operations, Align Points, Apply Spline to Component
+> and Teleport Actors and Components. `UPCGComponent` exposes a
+> `SourceDataContainer` through the execution source interface. Source: UE 5.8
+> release notes, https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes?application_version=5.8
+
---
## Overview
diff --git a/docs/registry/architecture.yaml b/docs/registry/architecture.yaml
index edfb05c7..1c8288cf 100644
--- a/docs/registry/architecture.yaml
+++ b/docs/registry/architecture.yaml
@@ -8,7 +8,8 @@
# - Register a stance when it constrains how OTHER systems must be built.
# An internal implementation detail that affects only one ADR does not need
# to be registered.
-# - Never delete entries — set status: superseded_by: ADR-NNNN instead.
+# - Never delete entries — set status: "superseded_by: ADR-NNNN" instead,
+# quoted: unquoted, the second colon makes the file invalid YAML.
# - When a stance changes: update the entry, set revised: to today's date,
# add a comment with the old value, and run /architecture-review to check
# what ADRs are now invalidated.
@@ -27,7 +28,16 @@
# All signal contracts: Grep pattern="pattern: signal"
# Budget for combat: Grep pattern="system: combat"
# All forbidden patterns: Grep pattern="^ - pattern:" (forbidden_patterns section)
-# Superseded entries: Grep pattern="status: superseded"
+# Superseded entries: Grep pattern="superseded_by: ADR-"
+#
+# LAYOUT: the one shape .claude/scripts/registry.sh reads. Each section is a
+# key at column 0 holding a block list, or [] while it is empty. Each entry
+# starts with its section's name key ("- state:", "- contract:", "- system:"
+# or "- target_fps:" for the frame budget, "- purpose:", "- pattern:"), the
+# dash at column 2 (or 0, the same for every entry of a section); its fields
+# sit two columns past the dash. Quote a value that holds ": ", such as
+# "superseded_by: ADR-NNNN". A line in any other shape is reported as
+# unsupported layout, with its number.
version: 1
last_updated: ""
@@ -49,7 +59,7 @@ state_ownership: []
#
# state_ownership:
# - state: player_health
-# status: active # active | superseded_by: ADR-NNNN
+# status: active # active | "superseded_by: ADR-NNNN"
# owner_system: health-system
# adr: docs/architecture/adr-0001-health-system.md
# interface: "HealthComponent.current_health (read-only float, range 0–max_health)"
diff --git a/production/.gdignore b/production/.gdignore
new file mode 100644
index 00000000..8be05c17
--- /dev/null
+++ b/production/.gdignore
@@ -0,0 +1,2 @@
+# Godot skips this folder. Project records and evidence screenshots are not game
+# resources: without this file a Godot project imports them and exports them.
diff --git a/project.yaml b/project.yaml
index 6755ad65..c309382c 100644
--- a/project.yaml
+++ b/project.yaml
@@ -4,8 +4,8 @@
schema_version: 1
framework:
- version: 1.1.3
- last_upgraded: 2026-09-25
+ version: 1.2.0
+ last_upgraded: 2026-10-19
# NOTE: this template ships with no `modes:` block, and the six knobs below must
# never be added to one.
@@ -17,9 +17,9 @@ framework:
# What must stay absent is the six knobs `modes.rigor` FRONTS:
# `modes.review_mode`, `modes.workflow`, `docs.density`, `qa.level`,
# `modes.story_granularity` and `team.size`. Seeding any of them in this file
-# pins that value and shadows the rigor expansion, so `/start` asking "what are
-# you building?" would stop changing anything. `/start` Phase 3c documents the
-# same rule for the file it writes.
+# pins that value and shadows the rigor expansion, so the rigor `/start` infers
+# and saves would stop changing anything. `/start` states the same rule for the
+# settings it writes.
#
# Per-developer preferences belong in `project.local.yaml` (gitignored), not
# here. `/settings --local <key>=<value>` writes there; `/settings <key>=<value>`
diff --git a/CCGS Skill Testing Framework/CLAUDE.md b/studio-tests/CLAUDE.md
similarity index 78%
rename from CCGS Skill Testing Framework/CLAUDE.md
rename to studio-tests/CLAUDE.md
index d302563d..e769923a 100644
--- a/CCGS Skill Testing Framework/CLAUDE.md
+++ b/studio-tests/CLAUDE.md
@@ -1,4 +1,4 @@
-# CCGS Skill Testing Framework — Claude Instructions
+# Studio Tests — Claude Instructions
This folder is the quality assurance layer for the Claude Code Game Studios skill/agent
framework. It is self-contained and separate from any game project.
@@ -17,10 +17,10 @@ framework. It is self-contained and separate from any game project.
## Path conventions
-- Skill specs: `CCGS Skill Testing Framework/skills/[category]/[name].md`
-- Agent specs: `CCGS Skill Testing Framework/agents/[tier]/[name].md`
-- Catalog: `CCGS Skill Testing Framework/catalog.yaml`
-- Rubric: `CCGS Skill Testing Framework/quality-rubric.md`
+- Skill specs: `studio-tests/skills/[category]/[name].md`
+- Agent specs: `studio-tests/agents/[tier]/[name].md`
+- Catalog: `studio-tests/catalog.yaml`
+- Rubric: `studio-tests/quality-rubric.md`
The `spec:` field in `catalog.yaml` is the authoritative path for each skill/agent spec.
Always read it rather than guessing the path.
@@ -85,6 +85,33 @@ A tier is the directory a spec lives in. The rubric category is the agent's
Protocol Compliance list
6. Offer to write results to `results/` and update `catalog.yaml`
+## Fixture defaults
+
+Every skill spec has a `## Fixture Defaults` section above its cases. A case's
+sandbox project starts from this `project.yaml` block:
+
+```yaml
+modes:
+ rigor: minimal # → workflow minimal, docs.density terse, qa.level minimal,
+ # story_granularity coarse, review_mode solo, team.size individual
+ automation: collaborative
+```
+
+- A setting the case's Fixture names wins over the block, and an explicit
+ sub-knob (`modes.workflow`, `modes.review_mode`, `qa.level`, …) wins over the
+ `rigor` preset (`.claude/docs/config-resolution.md` § Defaults).
+- A case that says `project.yaml` sets no `modes` keys, or that there is no
+ `project.yaml`, runs without the block: it tests the unset defaults.
+- There is no `project.local.yaml` unless the case names one.
+- A case whose expected behaviour changes with a setting pins that setting in
+ its own Fixture, with the reason — e.g. `modes.workflow: standard` (pinned:
+ unset resolves to minimal, which recommends the next build instead of a
+ sprint).
+
+The block is pinned so that a change to the framework's defaults cannot
+silently change what a case tests. A spec may set a different default in its
+own section when most of its cases need one.
+
## Workflow for improving a skill
Use `/skill-improve [name]`. It handles the full loop:
diff --git a/CCGS Skill Testing Framework/README.md b/studio-tests/README.md
similarity index 97%
rename from CCGS Skill Testing Framework/README.md
rename to studio-tests/README.md
index bd1efada..ae94d6ae 100644
--- a/CCGS Skill Testing Framework/README.md
+++ b/studio-tests/README.md
@@ -1,4 +1,4 @@
-# CCGS Skill Testing Framework
+# Studio Tests
Quality assurance infrastructure for the **Claude Code Game Studios** framework.
Tests the skills and agents themselves — not any game built with them.
@@ -28,13 +28,13 @@ you write. Driven by `/skill-test` and `/skill-improve`.
## What's in here
```
-CCGS Skill Testing Framework/
+studio-tests/
├── README.md ← you are here
├── CLAUDE.md ← tells Claude how to use this framework
├── catalog.yaml ← master registry: all 74 skills + 49 agents, coverage tracking
├── quality-rubric.md ← category-specific pass/fail metrics for /skill-test category
│
-├── skills/ ← behavioral spec files for skills (73 of 74 — settings has none yet)
+├── skills/ ← behavioral spec files for all 74 skills
│ ├── gate/ ← gate category specs
│ ├── review/ ← review category specs
│ ├── authoring/ ← authoring category specs
@@ -166,7 +166,7 @@ No hook or import in the main project depends on this folder, but `/skill-test`
and `/skill-improve` read it by path. To remove:
```bash
-rm -rf "CCGS Skill Testing Framework"
+rm -rf studio-tests
```
Afterwards `/skill-test static` works as before, `spec` and `category` stop
diff --git a/CCGS Skill Testing Framework/agents/directors/art-director.md b/studio-tests/agents/directors/art-director.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/directors/art-director.md
rename to studio-tests/agents/directors/art-director.md
diff --git a/CCGS Skill Testing Framework/agents/directors/creative-director.md b/studio-tests/agents/directors/creative-director.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/directors/creative-director.md
rename to studio-tests/agents/directors/creative-director.md
diff --git a/CCGS Skill Testing Framework/agents/directors/producer.md b/studio-tests/agents/directors/producer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/directors/producer.md
rename to studio-tests/agents/directors/producer.md
diff --git a/CCGS Skill Testing Framework/agents/directors/technical-director.md b/studio-tests/agents/directors/technical-director.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/directors/technical-director.md
rename to studio-tests/agents/directors/technical-director.md
diff --git a/CCGS Skill Testing Framework/agents/engine/godot/godot-csharp-specialist.md b/studio-tests/agents/engine/godot/godot-csharp-specialist.md
similarity index 94%
rename from CCGS Skill Testing Framework/agents/engine/godot/godot-csharp-specialist.md
rename to studio-tests/agents/engine/godot/godot-csharp-specialist.md
index 4ca4e175..34731b29 100644
--- a/CCGS Skill Testing Framework/agents/engine/godot/godot-csharp-specialist.md
+++ b/studio-tests/agents/engine/godot/godot-csharp-specialist.md
@@ -53,13 +53,13 @@ No gate IDs assigned.
- Provides the correct pattern: use `CallDeferred()`, `Callable.From().CallDeferred()`, or marshal back to the main thread via a thread-safe queue
- Explains why the code compiles yet is unsafe: the `Task` body runs on a .NET thread-pool thread and nothing in C# stops it touching a Node — the main-thread rule belongs to Godot's scene tree
-### Case 5: Context pass — Godot 4.6 API correctness
-**Input:** Engine version context: Godot 4.6. Request: "Connect a signal using the new typed signal delegate pattern."
+### Case 5: Context pass — Godot 4.7 API correctness
+**Input:** Engine version context: Godot 4.7. Request: "Connect a signal using the new typed signal delegate pattern."
**Expected behavior:**
- Produces C# signal connection using the typed delegate pattern introduced in Godot 4 C# (`+=` operator on typed signal)
-- Checks the 4.6 context to confirm no breaking changes to the signal delegate API in 4.4, 4.5, or 4.6
+- Checks the 4.7 context to confirm no breaking changes to the signal delegate API in 4.4, 4.5, 4.6 or 4.7
- Does NOT use the old string-based `Connect("signal_name", callable)` pattern (deprecated in Godot 4 C#)
-- Produces code compatible with the project's pinned 4.6 version as documented in VERSION.md
+- Produces code compatible with the project's pinned 4.7 version as documented in VERSION.md
---
diff --git a/CCGS Skill Testing Framework/agents/engine/godot/godot-gdextension-specialist.md b/studio-tests/agents/engine/godot/godot-gdextension-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/engine/godot/godot-gdextension-specialist.md
rename to studio-tests/agents/engine/godot/godot-gdextension-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/engine/godot/godot-gdscript-specialist.md b/studio-tests/agents/engine/godot/godot-gdscript-specialist.md
similarity index 97%
rename from CCGS Skill Testing Framework/agents/engine/godot/godot-gdscript-specialist.md
rename to studio-tests/agents/engine/godot/godot-gdscript-specialist.md
index c55e476a..86831365 100644
--- a/CCGS Skill Testing Framework/agents/engine/godot/godot-gdscript-specialist.md
+++ b/studio-tests/agents/engine/godot/godot-gdscript-specialist.md
@@ -72,7 +72,7 @@ No gate IDs assigned.
- [ ] Redirects GDExtension requests to godot-gdextension-specialist
- [ ] Returns structured GDScript output with full static typing
- [ ] Uses Godot 4 API only — no deprecated Godot 3 patterns (yield, connect with strings, etc.)
-- [ ] Flags post-cutoff features (4.4, 4.5, 4.6) and marks them as requiring doc verification
+- [ ] Flags features from 4.4 onward (4.4 just before the cutoff; 4.5, 4.6, 4.7 after it) and marks them as requiring doc verification
- [ ] Asks "May I write this to [filepath]?" naming the file before writing
---
diff --git a/CCGS Skill Testing Framework/agents/engine/godot/godot-shader-specialist.md b/studio-tests/agents/engine/godot/godot-shader-specialist.md
similarity index 99%
rename from CCGS Skill Testing Framework/agents/engine/godot/godot-shader-specialist.md
rename to studio-tests/agents/engine/godot/godot-shader-specialist.md
index 4d466b99..7a8072e5 100644
--- a/CCGS Skill Testing Framework/agents/engine/godot/godot-shader-specialist.md
+++ b/studio-tests/agents/engine/godot/godot-shader-specialist.md
@@ -83,4 +83,4 @@ No gate IDs assigned.
## Coverage Notes
- Dissolve shader (Case 1) should be paired with a visual test screenshot in `production/qa/evidence/`
- Texture-type case (Case 3) confirms the agent reads what a post-cutoff change actually covers before applying it, instead of rewriting syntax the change does not touch
-- Glow rework (Case 5) is a Godot 4.6-specific test — verifies the agent applies the most recent migration notes
+- Glow rework (Case 5) is a Godot 4.6-specific test — verifies the agent applies a post-cutoff migration note
diff --git a/CCGS Skill Testing Framework/agents/engine/godot/godot-specialist.md b/studio-tests/agents/engine/godot/godot-specialist.md
similarity index 96%
rename from CCGS Skill Testing Framework/agents/engine/godot/godot-specialist.md
rename to studio-tests/agents/engine/godot/godot-specialist.md
index 7d91a73b..02fd17e2 100644
--- a/CCGS Skill Testing Framework/agents/engine/godot/godot-specialist.md
+++ b/studio-tests/agents/engine/godot/godot-specialist.md
@@ -34,7 +34,7 @@ No gate IDs assigned.
- Does NOT produce Unity MonoBehaviour code
- Clearly identifies that this is a Unity pattern, not a Godot pattern
- Maps the concepts to Godot: `_ready()` instead of `Start()`, and a typed Godot `signal` connected in `_ready()` instead of a UnityEvent
-- Grounds the answer in the project's engine pin (`docs/engine-reference/godot/VERSION.md`, Godot 4.6) rather than asking which engine the project uses
+- Grounds the answer in the project's engine pin (`docs/engine-reference/godot/VERSION.md`, Godot 4.7) rather than asking which engine the project uses
- Routes the actual node script to godot-gdscript-specialist or godot-csharp-specialist rather than writing it itself
- Variant: with `engine.name: Unity` in `project.yaml`, it says it is the wrong specialist for this project instead of mapping the concepts
@@ -73,7 +73,7 @@ No gate IDs assigned.
- [ ] Redirects language-specific implementation to godot-gdscript-specialist or godot-csharp-specialist
- [ ] Returns structured findings (decision trees, pattern recommendations with rationale)
- [ ] Treats `docs/engine-reference/godot/VERSION.md` as authoritative over LLM training data
-- [ ] Flags post-cutoff API usage (4.4, 4.5, 4.6) with verification requirements
+- [ ] Flags API usage from 4.4 onward (4.4 just before the cutoff; 4.5, 4.6, 4.7 after it) with verification requirements
- [ ] Leaves language-selection decisions to the user and routes adoption of a new language or runtime to technical-director
- [ ] Asks "May I write this to [filepath]?" naming the file before writing
diff --git a/CCGS Skill Testing Framework/agents/engine/unity/unity-addressables-specialist.md b/studio-tests/agents/engine/unity/unity-addressables-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/engine/unity/unity-addressables-specialist.md
rename to studio-tests/agents/engine/unity/unity-addressables-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/engine/unity/unity-dots-specialist.md b/studio-tests/agents/engine/unity/unity-dots-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/engine/unity/unity-dots-specialist.md
rename to studio-tests/agents/engine/unity/unity-dots-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/engine/unity/unity-shader-specialist.md b/studio-tests/agents/engine/unity/unity-shader-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/engine/unity/unity-shader-specialist.md
rename to studio-tests/agents/engine/unity/unity-shader-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/engine/unity/unity-specialist.md b/studio-tests/agents/engine/unity/unity-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/engine/unity/unity-specialist.md
rename to studio-tests/agents/engine/unity/unity-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/engine/unity/unity-ui-specialist.md b/studio-tests/agents/engine/unity/unity-ui-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/engine/unity/unity-ui-specialist.md
rename to studio-tests/agents/engine/unity/unity-ui-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/engine/unreal/ue-blueprint-specialist.md b/studio-tests/agents/engine/unreal/ue-blueprint-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/engine/unreal/ue-blueprint-specialist.md
rename to studio-tests/agents/engine/unreal/ue-blueprint-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/engine/unreal/ue-gas-specialist.md b/studio-tests/agents/engine/unreal/ue-gas-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/engine/unreal/ue-gas-specialist.md
rename to studio-tests/agents/engine/unreal/ue-gas-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/engine/unreal/ue-replication-specialist.md b/studio-tests/agents/engine/unreal/ue-replication-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/engine/unreal/ue-replication-specialist.md
rename to studio-tests/agents/engine/unreal/ue-replication-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/engine/unreal/ue-umg-specialist.md b/studio-tests/agents/engine/unreal/ue-umg-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/engine/unreal/ue-umg-specialist.md
rename to studio-tests/agents/engine/unreal/ue-umg-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/engine/unreal/unreal-specialist.md b/studio-tests/agents/engine/unreal/unreal-specialist.md
similarity index 95%
rename from CCGS Skill Testing Framework/agents/engine/unreal/unreal-specialist.md
rename to studio-tests/agents/engine/unreal/unreal-specialist.md
index 8a62b7df..e72dcc62 100644
--- a/CCGS Skill Testing Framework/agents/engine/unreal/unreal-specialist.md
+++ b/studio-tests/agents/engine/unreal/unreal-specialist.md
@@ -10,7 +10,7 @@
## Static Assertions (Structural)
- [ ] `description:` field is present and domain-specific (references Unreal Engine)
-- [ ] `tools:` reads Read, Glob, Grep, Write, Edit, Bash and `Agent(ue-gas-specialist, ue-blueprint-specialist, ue-replication-specialist, ue-umg-specialist)` — it may spawn only its four sub-specialists
+- [ ] `tools:` reads Read, Glob, Grep, Write, Edit, Bash and `Agent`, and its body tells it to start only its four sub-specialists (ue-gas, ue-blueprint, ue-replication, ue-umg), since a type list in a subagent's `tools` is ignored
- [ ] Model tier is `inherit` — frontmatter `model:` reads exactly `inherit` (tiers: `.claude/docs/model-tiers.md`)
- [ ] Agent definition does not claim authority outside its declared domain (no art, no server infra)
@@ -39,7 +39,7 @@
### Case 3: Domain boundary — UE5.4 API requirement
**Input**: "I need to use the new Motion Matching API introduced in UE5.4."
**Expected behavior**:
-- Flags that UE5.4 is past the model's training coverage (`docs/engine-reference/unreal/VERSION.md` lists 5.4 as a post-cutoff, HIGH-risk version)
+- Flags that UE5.4 is past the model's training coverage (`docs/engine-reference/unreal/VERSION.md`'s Knowledge Gap Warning puts coverage at ~5.3 and lists 5.4 as a HIGH-risk version)
- Checks `docs/engine-reference/unreal/` before trusting any API suggestion
- States that no file under `docs/engine-reference/unreal/` documents Motion Matching, and labels any class or node names it offers as unverified against the pinned version
- Does NOT silently produce stale or incorrect API signatures without a caveat
diff --git a/CCGS Skill Testing Framework/agents/leads/audio-director.md b/studio-tests/agents/leads/audio-director.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/leads/audio-director.md
rename to studio-tests/agents/leads/audio-director.md
diff --git a/CCGS Skill Testing Framework/agents/leads/game-designer.md b/studio-tests/agents/leads/game-designer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/leads/game-designer.md
rename to studio-tests/agents/leads/game-designer.md
diff --git a/CCGS Skill Testing Framework/agents/leads/lead-programmer.md b/studio-tests/agents/leads/lead-programmer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/leads/lead-programmer.md
rename to studio-tests/agents/leads/lead-programmer.md
diff --git a/CCGS Skill Testing Framework/agents/leads/level-designer.md b/studio-tests/agents/leads/level-designer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/leads/level-designer.md
rename to studio-tests/agents/leads/level-designer.md
diff --git a/CCGS Skill Testing Framework/agents/leads/narrative-director.md b/studio-tests/agents/leads/narrative-director.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/leads/narrative-director.md
rename to studio-tests/agents/leads/narrative-director.md
diff --git a/CCGS Skill Testing Framework/agents/leads/qa-lead.md b/studio-tests/agents/leads/qa-lead.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/leads/qa-lead.md
rename to studio-tests/agents/leads/qa-lead.md
diff --git a/CCGS Skill Testing Framework/agents/leads/systems-designer.md b/studio-tests/agents/leads/systems-designer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/leads/systems-designer.md
rename to studio-tests/agents/leads/systems-designer.md
diff --git a/CCGS Skill Testing Framework/agents/operations/analytics-engineer.md b/studio-tests/agents/operations/analytics-engineer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/operations/analytics-engineer.md
rename to studio-tests/agents/operations/analytics-engineer.md
diff --git a/CCGS Skill Testing Framework/agents/operations/community-manager.md b/studio-tests/agents/operations/community-manager.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/operations/community-manager.md
rename to studio-tests/agents/operations/community-manager.md
diff --git a/CCGS Skill Testing Framework/agents/operations/devops-engineer.md b/studio-tests/agents/operations/devops-engineer.md
similarity index 98%
rename from CCGS Skill Testing Framework/agents/operations/devops-engineer.md
rename to studio-tests/agents/operations/devops-engineer.md
index 7f6ad294..777f19d9 100644
--- a/CCGS Skill Testing Framework/agents/operations/devops-engineer.md
+++ b/studio-tests/agents/operations/devops-engineer.md
@@ -40,7 +40,7 @@
**Input**: "Our CI pipeline is failing on the merge step. The error is: 'Asset import failed: texture compression format unsupported in headless mode.'"
**Expected behavior**:
- Diagnoses the failure as an environment problem in the headless CI runner (the import step needs a capability the headless runner lacks), not a flaky step to retry
-- Before stating how Godot 4.6 imports or compresses textures headlessly, cross-references `docs/engine-reference/godot/` — `VERSION.md` pins 4.6, past the model's training data — and says so when the reference does not cover it, rather than asserting version-specific behavior from memory
+- Before stating how Godot 4.7 imports or compresses textures headlessly, cross-references `docs/engine-reference/godot/` — `VERSION.md` pins 4.7, past the model's training data — and says so when the reference does not cover it, rather than asserting version-specific behavior from memory
- Proposes at least one actionable fix that keeps the import and test steps in the pipeline, and names its tradeoff
- Does NOT remove the import step, skip the tests, or mark the job `continue-on-error` to get a green build — "Skip CI steps for speed" is forbidden, and `coding-standards.md` says "Never disable or skip failing tests to make CI pass — fix the underlying issue"
- Does NOT declare the pipeline unfixable
diff --git a/CCGS Skill Testing Framework/agents/operations/economy-designer.md b/studio-tests/agents/operations/economy-designer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/operations/economy-designer.md
rename to studio-tests/agents/operations/economy-designer.md
diff --git a/CCGS Skill Testing Framework/agents/operations/live-ops-designer.md b/studio-tests/agents/operations/live-ops-designer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/operations/live-ops-designer.md
rename to studio-tests/agents/operations/live-ops-designer.md
diff --git a/CCGS Skill Testing Framework/agents/operations/localization-lead.md b/studio-tests/agents/operations/localization-lead.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/operations/localization-lead.md
rename to studio-tests/agents/operations/localization-lead.md
diff --git a/CCGS Skill Testing Framework/agents/operations/release-manager.md b/studio-tests/agents/operations/release-manager.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/operations/release-manager.md
rename to studio-tests/agents/operations/release-manager.md
diff --git a/CCGS Skill Testing Framework/agents/qa/accessibility-specialist.md b/studio-tests/agents/qa/accessibility-specialist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/qa/accessibility-specialist.md
rename to studio-tests/agents/qa/accessibility-specialist.md
diff --git a/CCGS Skill Testing Framework/agents/qa/qa-tester.md b/studio-tests/agents/qa/qa-tester.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/qa/qa-tester.md
rename to studio-tests/agents/qa/qa-tester.md
diff --git a/CCGS Skill Testing Framework/agents/qa/security-engineer.md b/studio-tests/agents/qa/security-engineer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/qa/security-engineer.md
rename to studio-tests/agents/qa/security-engineer.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/ai-programmer.md b/studio-tests/agents/specialists/ai-programmer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/ai-programmer.md
rename to studio-tests/agents/specialists/ai-programmer.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/engine-programmer.md b/studio-tests/agents/specialists/engine-programmer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/engine-programmer.md
rename to studio-tests/agents/specialists/engine-programmer.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/gameplay-programmer.md b/studio-tests/agents/specialists/gameplay-programmer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/gameplay-programmer.md
rename to studio-tests/agents/specialists/gameplay-programmer.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/network-programmer.md b/studio-tests/agents/specialists/network-programmer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/network-programmer.md
rename to studio-tests/agents/specialists/network-programmer.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/performance-analyst.md b/studio-tests/agents/specialists/performance-analyst.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/performance-analyst.md
rename to studio-tests/agents/specialists/performance-analyst.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/prototyper.md b/studio-tests/agents/specialists/prototyper.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/prototyper.md
rename to studio-tests/agents/specialists/prototyper.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/sound-designer.md b/studio-tests/agents/specialists/sound-designer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/sound-designer.md
rename to studio-tests/agents/specialists/sound-designer.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/technical-artist.md b/studio-tests/agents/specialists/technical-artist.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/technical-artist.md
rename to studio-tests/agents/specialists/technical-artist.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/tools-programmer.md b/studio-tests/agents/specialists/tools-programmer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/tools-programmer.md
rename to studio-tests/agents/specialists/tools-programmer.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/ui-programmer.md b/studio-tests/agents/specialists/ui-programmer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/ui-programmer.md
rename to studio-tests/agents/specialists/ui-programmer.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/ux-designer.md b/studio-tests/agents/specialists/ux-designer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/ux-designer.md
rename to studio-tests/agents/specialists/ux-designer.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/world-builder.md b/studio-tests/agents/specialists/world-builder.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/world-builder.md
rename to studio-tests/agents/specialists/world-builder.md
diff --git a/CCGS Skill Testing Framework/agents/specialists/writer.md b/studio-tests/agents/specialists/writer.md
similarity index 100%
rename from CCGS Skill Testing Framework/agents/specialists/writer.md
rename to studio-tests/agents/specialists/writer.md
diff --git a/CCGS Skill Testing Framework/catalog.yaml b/studio-tests/catalog.yaml
similarity index 71%
rename from CCGS Skill Testing Framework/catalog.yaml
rename to studio-tests/catalog.yaml
index ae51c2e9..6151c77a 100644
--- a/CCGS Skill Testing Framework/catalog.yaml
+++ b/studio-tests/catalog.yaml
@@ -3,7 +3,7 @@ last_updated: ""
skills:
# Critical — gate skills that control phase transitions
- name: gate-check
- spec: CCGS Skill Testing Framework/skills/gate/gate-check.md
+ spec: studio-tests/skills/gate/gate-check.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -14,7 +14,7 @@ skills:
category: gate
- name: design-review
- spec: CCGS Skill Testing Framework/skills/review/design-review.md
+ spec: studio-tests/skills/review/design-review.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -25,7 +25,7 @@ skills:
category: review
- name: story-readiness
- spec: CCGS Skill Testing Framework/skills/readiness/story-readiness.md
+ spec: studio-tests/skills/readiness/story-readiness.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -36,7 +36,7 @@ skills:
category: readiness
- name: story-done
- spec: CCGS Skill Testing Framework/skills/readiness/story-done.md
+ spec: studio-tests/skills/readiness/story-done.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -47,7 +47,7 @@ skills:
category: readiness
- name: review-all-gdds
- spec: CCGS Skill Testing Framework/skills/review/review-all-gdds.md
+ spec: studio-tests/skills/review/review-all-gdds.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -58,7 +58,7 @@ skills:
category: review
- name: architecture-review
- spec: CCGS Skill Testing Framework/skills/review/architecture-review.md
+ spec: studio-tests/skills/review/architecture-review.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -70,7 +70,7 @@ skills:
# High — pipeline-critical skills
- name: create-epics
- spec: CCGS Skill Testing Framework/skills/pipeline/create-epics.md
+ spec: studio-tests/skills/pipeline/create-epics.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -81,7 +81,7 @@ skills:
category: pipeline
- name: create-stories
- spec: CCGS Skill Testing Framework/skills/pipeline/create-stories.md
+ spec: studio-tests/skills/pipeline/create-stories.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -92,7 +92,7 @@ skills:
category: pipeline
- name: dev-story
- spec: CCGS Skill Testing Framework/skills/pipeline/dev-story.md
+ spec: studio-tests/skills/pipeline/dev-story.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -103,7 +103,7 @@ skills:
category: pipeline
- name: create-control-manifest
- spec: CCGS Skill Testing Framework/skills/pipeline/create-control-manifest.md
+ spec: studio-tests/skills/pipeline/create-control-manifest.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -114,7 +114,7 @@ skills:
category: pipeline
- name: propagate-design-change
- spec: CCGS Skill Testing Framework/skills/pipeline/propagate-design-change.md
+ spec: studio-tests/skills/pipeline/propagate-design-change.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -125,7 +125,7 @@ skills:
category: pipeline
- name: architecture-decision
- spec: CCGS Skill Testing Framework/skills/authoring/architecture-decision.md
+ spec: studio-tests/skills/authoring/architecture-decision.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -136,7 +136,7 @@ skills:
category: authoring
- name: map-systems
- spec: CCGS Skill Testing Framework/skills/pipeline/map-systems.md
+ spec: studio-tests/skills/pipeline/map-systems.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -147,7 +147,7 @@ skills:
category: pipeline
- name: vertical-slice
- spec: CCGS Skill Testing Framework/skills/pipeline/vertical-slice.md
+ spec: studio-tests/skills/pipeline/vertical-slice.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -158,7 +158,7 @@ skills:
category: pipeline
- name: design-system
- spec: CCGS Skill Testing Framework/skills/authoring/design-system.md
+ spec: studio-tests/skills/authoring/design-system.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -169,7 +169,7 @@ skills:
category: authoring
- name: consistency-check
- spec: CCGS Skill Testing Framework/skills/analysis/consistency-check.md
+ spec: studio-tests/skills/analysis/consistency-check.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -181,7 +181,7 @@ skills:
# Medium — team and sprint management skills
- name: sprint-plan
- spec: CCGS Skill Testing Framework/skills/sprint/sprint-plan.md
+ spec: studio-tests/skills/sprint/sprint-plan.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -192,7 +192,7 @@ skills:
category: sprint
- name: sprint-status
- spec: CCGS Skill Testing Framework/skills/sprint/sprint-status.md
+ spec: studio-tests/skills/sprint/sprint-status.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -203,7 +203,7 @@ skills:
category: sprint
- name: team-ui
- spec: CCGS Skill Testing Framework/skills/team/team-ui.md
+ spec: studio-tests/skills/team/team-ui.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -214,7 +214,7 @@ skills:
category: team
- name: team-combat
- spec: CCGS Skill Testing Framework/skills/team/team-combat.md
+ spec: studio-tests/skills/team/team-combat.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -225,7 +225,7 @@ skills:
category: team
- name: team-narrative
- spec: CCGS Skill Testing Framework/skills/team/team-narrative.md
+ spec: studio-tests/skills/team/team-narrative.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -236,7 +236,7 @@ skills:
category: team
- name: team-audio
- spec: CCGS Skill Testing Framework/skills/team/team-audio.md
+ spec: studio-tests/skills/team/team-audio.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -247,7 +247,7 @@ skills:
category: team
- name: team-level
- spec: CCGS Skill Testing Framework/skills/team/team-level.md
+ spec: studio-tests/skills/team/team-level.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -258,7 +258,7 @@ skills:
category: team
- name: team-polish
- spec: CCGS Skill Testing Framework/skills/team/team-polish.md
+ spec: studio-tests/skills/team/team-polish.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -269,7 +269,7 @@ skills:
category: team
- name: team-release
- spec: CCGS Skill Testing Framework/skills/team/team-release.md
+ spec: studio-tests/skills/team/team-release.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -280,7 +280,7 @@ skills:
category: team
- name: team-live-ops
- spec: CCGS Skill Testing Framework/skills/team/team-live-ops.md
+ spec: studio-tests/skills/team/team-live-ops.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -291,7 +291,7 @@ skills:
category: team
- name: team-qa
- spec: CCGS Skill Testing Framework/skills/team/team-qa.md
+ spec: studio-tests/skills/team/team-qa.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -303,7 +303,7 @@ skills:
# Low — analysis, reporting, utility skills
- name: skill-test
- spec: CCGS Skill Testing Framework/skills/utility/skill-test.md
+ spec: studio-tests/skills/utility/skill-test.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -314,7 +314,7 @@ skills:
category: utility
- name: skill-improve
- spec: CCGS Skill Testing Framework/skills/utility/skill-improve.md
+ spec: studio-tests/skills/utility/skill-improve.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -325,7 +325,7 @@ skills:
category: utility
- name: start
- spec: CCGS Skill Testing Framework/skills/utility/start.md
+ spec: studio-tests/skills/utility/start.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -336,7 +336,7 @@ skills:
category: utility
- name: help
- spec: CCGS Skill Testing Framework/skills/utility/help.md
+ spec: studio-tests/skills/utility/help.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -347,7 +347,7 @@ skills:
category: utility
- name: brainstorm
- spec: CCGS Skill Testing Framework/skills/utility/brainstorm.md
+ spec: studio-tests/skills/utility/brainstorm.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -358,7 +358,7 @@ skills:
category: utility
- name: project-stage-detect
- spec: CCGS Skill Testing Framework/skills/utility/project-stage-detect.md
+ spec: studio-tests/skills/utility/project-stage-detect.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -369,7 +369,7 @@ skills:
category: utility
- name: setup-engine
- spec: CCGS Skill Testing Framework/skills/utility/setup-engine.md
+ spec: studio-tests/skills/utility/setup-engine.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -380,7 +380,7 @@ skills:
category: utility
- name: quick-design
- spec: CCGS Skill Testing Framework/skills/authoring/quick-design.md
+ spec: studio-tests/skills/authoring/quick-design.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -391,7 +391,7 @@ skills:
category: authoring
- name: ux-design
- spec: CCGS Skill Testing Framework/skills/authoring/ux-design.md
+ spec: studio-tests/skills/authoring/ux-design.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -402,7 +402,7 @@ skills:
category: authoring
- name: ux-review
- spec: CCGS Skill Testing Framework/skills/authoring/ux-review.md
+ spec: studio-tests/skills/authoring/ux-review.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -413,7 +413,7 @@ skills:
category: authoring
- name: art-bible
- spec: CCGS Skill Testing Framework/skills/authoring/art-bible.md
+ spec: studio-tests/skills/authoring/art-bible.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -424,7 +424,7 @@ skills:
category: authoring
- name: create-architecture
- spec: CCGS Skill Testing Framework/skills/authoring/create-architecture.md
+ spec: studio-tests/skills/authoring/create-architecture.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -435,7 +435,7 @@ skills:
category: authoring
- name: code-review
- spec: CCGS Skill Testing Framework/skills/analysis/code-review.md
+ spec: studio-tests/skills/analysis/code-review.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -446,7 +446,7 @@ skills:
category: analysis
- name: balance-check
- spec: CCGS Skill Testing Framework/skills/analysis/balance-check.md
+ spec: studio-tests/skills/analysis/balance-check.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -457,7 +457,7 @@ skills:
category: analysis
- name: asset-audit
- spec: CCGS Skill Testing Framework/skills/analysis/asset-audit.md
+ spec: studio-tests/skills/analysis/asset-audit.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -468,7 +468,7 @@ skills:
category: analysis
- name: content-audit
- spec: CCGS Skill Testing Framework/skills/analysis/content-audit.md
+ spec: studio-tests/skills/analysis/content-audit.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -479,7 +479,7 @@ skills:
category: analysis
- name: tech-debt
- spec: CCGS Skill Testing Framework/skills/analysis/tech-debt.md
+ spec: studio-tests/skills/analysis/tech-debt.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -490,7 +490,7 @@ skills:
category: analysis
- name: scope-check
- spec: CCGS Skill Testing Framework/skills/analysis/scope-check.md
+ spec: studio-tests/skills/analysis/scope-check.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -501,7 +501,7 @@ skills:
category: analysis
- name: estimate
- spec: CCGS Skill Testing Framework/skills/analysis/estimate.md
+ spec: studio-tests/skills/analysis/estimate.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -512,7 +512,7 @@ skills:
category: analysis
- name: perf-profile
- spec: CCGS Skill Testing Framework/skills/analysis/perf-profile.md
+ spec: studio-tests/skills/analysis/perf-profile.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -523,7 +523,7 @@ skills:
category: analysis
- name: security-audit
- spec: CCGS Skill Testing Framework/skills/analysis/security-audit.md
+ spec: studio-tests/skills/analysis/security-audit.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -534,7 +534,7 @@ skills:
category: analysis
- name: test-evidence-review
- spec: CCGS Skill Testing Framework/skills/analysis/test-evidence-review.md
+ spec: studio-tests/skills/analysis/test-evidence-review.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -545,7 +545,7 @@ skills:
category: analysis
- name: test-flakiness
- spec: CCGS Skill Testing Framework/skills/analysis/test-flakiness.md
+ spec: studio-tests/skills/analysis/test-flakiness.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -556,7 +556,7 @@ skills:
category: analysis
- name: reverse-document
- spec: CCGS Skill Testing Framework/skills/utility/reverse-document.md
+ spec: studio-tests/skills/utility/reverse-document.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -567,7 +567,7 @@ skills:
category: utility
- name: bug-report
- spec: CCGS Skill Testing Framework/skills/utility/bug-report.md
+ spec: studio-tests/skills/utility/bug-report.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -578,7 +578,7 @@ skills:
category: utility
- name: hotfix
- spec: CCGS Skill Testing Framework/skills/utility/hotfix.md
+ spec: studio-tests/skills/utility/hotfix.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -589,7 +589,7 @@ skills:
category: utility
- name: prototype
- spec: CCGS Skill Testing Framework/skills/utility/prototype.md
+ spec: studio-tests/skills/utility/prototype.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -600,7 +600,7 @@ skills:
category: utility
- name: playtest-report
- spec: CCGS Skill Testing Framework/skills/utility/playtest-report.md
+ spec: studio-tests/skills/utility/playtest-report.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -611,7 +611,7 @@ skills:
category: utility
- name: milestone-review
- spec: CCGS Skill Testing Framework/skills/sprint/milestone-review.md
+ spec: studio-tests/skills/sprint/milestone-review.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -622,7 +622,7 @@ skills:
category: sprint
- name: retrospective
- spec: CCGS Skill Testing Framework/skills/sprint/retrospective.md
+ spec: studio-tests/skills/sprint/retrospective.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -633,7 +633,7 @@ skills:
category: sprint
- name: changelog
- spec: CCGS Skill Testing Framework/skills/sprint/changelog.md
+ spec: studio-tests/skills/sprint/changelog.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -644,7 +644,7 @@ skills:
category: sprint
- name: patch-notes
- spec: CCGS Skill Testing Framework/skills/sprint/patch-notes.md
+ spec: studio-tests/skills/sprint/patch-notes.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -655,7 +655,7 @@ skills:
category: sprint
- name: onboard
- spec: CCGS Skill Testing Framework/skills/utility/onboard.md
+ spec: studio-tests/skills/utility/onboard.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -666,7 +666,7 @@ skills:
category: utility
- name: localize
- spec: CCGS Skill Testing Framework/skills/utility/localize.md
+ spec: studio-tests/skills/utility/localize.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -677,7 +677,7 @@ skills:
category: utility
- name: launch-checklist
- spec: CCGS Skill Testing Framework/skills/utility/launch-checklist.md
+ spec: studio-tests/skills/utility/launch-checklist.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -688,7 +688,7 @@ skills:
category: utility
- name: release-checklist
- spec: CCGS Skill Testing Framework/skills/utility/release-checklist.md
+ spec: studio-tests/skills/utility/release-checklist.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -699,7 +699,7 @@ skills:
category: utility
- name: adopt
- spec: CCGS Skill Testing Framework/skills/utility/adopt.md
+ spec: studio-tests/skills/utility/adopt.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -710,7 +710,7 @@ skills:
category: utility
- name: smoke-check
- spec: CCGS Skill Testing Framework/skills/utility/smoke-check.md
+ spec: studio-tests/skills/utility/smoke-check.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -721,7 +721,7 @@ skills:
category: utility
- name: soak-test
- spec: CCGS Skill Testing Framework/skills/utility/soak-test.md
+ spec: studio-tests/skills/utility/soak-test.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -732,7 +732,7 @@ skills:
category: utility
- name: test-setup
- spec: CCGS Skill Testing Framework/skills/utility/test-setup.md
+ spec: studio-tests/skills/utility/test-setup.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -743,7 +743,7 @@ skills:
category: utility
- name: test-helpers
- spec: CCGS Skill Testing Framework/skills/utility/test-helpers.md
+ spec: studio-tests/skills/utility/test-helpers.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -754,7 +754,7 @@ skills:
category: utility
- name: regression-suite
- spec: CCGS Skill Testing Framework/skills/utility/regression-suite.md
+ spec: studio-tests/skills/utility/regression-suite.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -765,7 +765,7 @@ skills:
category: utility
- name: qa-plan
- spec: CCGS Skill Testing Framework/skills/utility/qa-plan.md
+ spec: studio-tests/skills/utility/qa-plan.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -776,7 +776,7 @@ skills:
category: utility
- name: bug-triage
- spec: CCGS Skill Testing Framework/skills/utility/bug-triage.md
+ spec: studio-tests/skills/utility/bug-triage.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -787,7 +787,7 @@ skills:
category: utility
- name: asset-spec
- spec: CCGS Skill Testing Framework/skills/utility/asset-spec.md
+ spec: studio-tests/skills/utility/asset-spec.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -798,7 +798,7 @@ skills:
category: utility
- name: day-one-patch
- spec: CCGS Skill Testing Framework/skills/utility/day-one-patch.md
+ spec: studio-tests/skills/utility/day-one-patch.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -809,7 +809,7 @@ skills:
category: utility
- name: settings
- spec: ""
+ spec: studio-tests/skills/utility/settings.md
last_static: ""
last_static_result: ""
last_spec: ""
@@ -822,7 +822,7 @@ skills:
agents:
# Tier 1 Directors
- name: creative-director
- spec: CCGS Skill Testing Framework/agents/directors/creative-director.md
+ spec: studio-tests/agents/directors/creative-director.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -830,7 +830,7 @@ agents:
category: director
- name: technical-director
- spec: CCGS Skill Testing Framework/agents/directors/technical-director.md
+ spec: studio-tests/agents/directors/technical-director.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -838,7 +838,7 @@ agents:
category: director
- name: producer
- spec: CCGS Skill Testing Framework/agents/directors/producer.md
+ spec: studio-tests/agents/directors/producer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -846,7 +846,7 @@ agents:
category: director
- name: art-director
- spec: CCGS Skill Testing Framework/agents/directors/art-director.md
+ spec: studio-tests/agents/directors/art-director.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -855,7 +855,7 @@ agents:
# Tier 2 Leads
- name: lead-programmer
- spec: CCGS Skill Testing Framework/agents/leads/lead-programmer.md
+ spec: studio-tests/agents/leads/lead-programmer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -863,7 +863,7 @@ agents:
category: lead
- name: qa-lead
- spec: CCGS Skill Testing Framework/agents/leads/qa-lead.md
+ spec: studio-tests/agents/leads/qa-lead.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -871,7 +871,7 @@ agents:
category: lead
- name: narrative-director
- spec: CCGS Skill Testing Framework/agents/leads/narrative-director.md
+ spec: studio-tests/agents/leads/narrative-director.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -879,7 +879,7 @@ agents:
category: lead
- name: audio-director
- spec: CCGS Skill Testing Framework/agents/leads/audio-director.md
+ spec: studio-tests/agents/leads/audio-director.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -887,7 +887,7 @@ agents:
category: lead
- name: game-designer
- spec: CCGS Skill Testing Framework/agents/leads/game-designer.md
+ spec: studio-tests/agents/leads/game-designer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -895,7 +895,7 @@ agents:
category: lead
- name: systems-designer
- spec: CCGS Skill Testing Framework/agents/leads/systems-designer.md
+ spec: studio-tests/agents/leads/systems-designer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -903,7 +903,7 @@ agents:
category: lead
- name: level-designer
- spec: CCGS Skill Testing Framework/agents/leads/level-designer.md
+ spec: studio-tests/agents/leads/level-designer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -912,7 +912,7 @@ agents:
# Core Specialists
- name: gameplay-programmer
- spec: CCGS Skill Testing Framework/agents/specialists/gameplay-programmer.md
+ spec: studio-tests/agents/specialists/gameplay-programmer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -920,7 +920,7 @@ agents:
category: specialist
- name: ai-programmer
- spec: CCGS Skill Testing Framework/agents/specialists/ai-programmer.md
+ spec: studio-tests/agents/specialists/ai-programmer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -928,7 +928,7 @@ agents:
category: specialist
- name: technical-artist
- spec: CCGS Skill Testing Framework/agents/specialists/technical-artist.md
+ spec: studio-tests/agents/specialists/technical-artist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -936,7 +936,7 @@ agents:
category: specialist
- name: sound-designer
- spec: CCGS Skill Testing Framework/agents/specialists/sound-designer.md
+ spec: studio-tests/agents/specialists/sound-designer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -944,7 +944,7 @@ agents:
category: specialist
- name: engine-programmer
- spec: CCGS Skill Testing Framework/agents/specialists/engine-programmer.md
+ spec: studio-tests/agents/specialists/engine-programmer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -952,7 +952,7 @@ agents:
category: specialist
- name: tools-programmer
- spec: CCGS Skill Testing Framework/agents/specialists/tools-programmer.md
+ spec: studio-tests/agents/specialists/tools-programmer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -960,7 +960,7 @@ agents:
category: specialist
- name: network-programmer
- spec: CCGS Skill Testing Framework/agents/specialists/network-programmer.md
+ spec: studio-tests/agents/specialists/network-programmer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -968,7 +968,7 @@ agents:
category: specialist
- name: security-engineer
- spec: CCGS Skill Testing Framework/agents/qa/security-engineer.md
+ spec: studio-tests/agents/qa/security-engineer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -976,7 +976,7 @@ agents:
category: specialist
- name: accessibility-specialist
- spec: CCGS Skill Testing Framework/agents/qa/accessibility-specialist.md
+ spec: studio-tests/agents/qa/accessibility-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -984,7 +984,7 @@ agents:
category: specialist
- name: ux-designer
- spec: CCGS Skill Testing Framework/agents/specialists/ux-designer.md
+ spec: studio-tests/agents/specialists/ux-designer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -992,7 +992,7 @@ agents:
category: specialist
- name: ui-programmer
- spec: CCGS Skill Testing Framework/agents/specialists/ui-programmer.md
+ spec: studio-tests/agents/specialists/ui-programmer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1000,7 +1000,7 @@ agents:
category: specialist
- name: performance-analyst
- spec: CCGS Skill Testing Framework/agents/specialists/performance-analyst.md
+ spec: studio-tests/agents/specialists/performance-analyst.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1009,7 +1009,7 @@ agents:
# Engine Specialists — Godot
- name: godot-specialist
- spec: CCGS Skill Testing Framework/agents/engine/godot/godot-specialist.md
+ spec: studio-tests/agents/engine/godot/godot-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1017,7 +1017,7 @@ agents:
category: engine
- name: godot-gdscript-specialist
- spec: CCGS Skill Testing Framework/agents/engine/godot/godot-gdscript-specialist.md
+ spec: studio-tests/agents/engine/godot/godot-gdscript-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1025,7 +1025,7 @@ agents:
category: engine
- name: godot-csharp-specialist
- spec: CCGS Skill Testing Framework/agents/engine/godot/godot-csharp-specialist.md
+ spec: studio-tests/agents/engine/godot/godot-csharp-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1033,7 +1033,7 @@ agents:
category: engine
- name: godot-shader-specialist
- spec: CCGS Skill Testing Framework/agents/engine/godot/godot-shader-specialist.md
+ spec: studio-tests/agents/engine/godot/godot-shader-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1041,7 +1041,7 @@ agents:
category: engine
- name: godot-gdextension-specialist
- spec: CCGS Skill Testing Framework/agents/engine/godot/godot-gdextension-specialist.md
+ spec: studio-tests/agents/engine/godot/godot-gdextension-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1050,7 +1050,7 @@ agents:
# Engine Specialists — Unity
- name: unity-specialist
- spec: CCGS Skill Testing Framework/agents/engine/unity/unity-specialist.md
+ spec: studio-tests/agents/engine/unity/unity-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1058,7 +1058,7 @@ agents:
category: engine
- name: unity-ui-specialist
- spec: CCGS Skill Testing Framework/agents/engine/unity/unity-ui-specialist.md
+ spec: studio-tests/agents/engine/unity/unity-ui-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1066,7 +1066,7 @@ agents:
category: engine
- name: unity-shader-specialist
- spec: CCGS Skill Testing Framework/agents/engine/unity/unity-shader-specialist.md
+ spec: studio-tests/agents/engine/unity/unity-shader-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1074,7 +1074,7 @@ agents:
category: engine
- name: unity-dots-specialist
- spec: CCGS Skill Testing Framework/agents/engine/unity/unity-dots-specialist.md
+ spec: studio-tests/agents/engine/unity/unity-dots-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1082,7 +1082,7 @@ agents:
category: engine
- name: unity-addressables-specialist
- spec: CCGS Skill Testing Framework/agents/engine/unity/unity-addressables-specialist.md
+ spec: studio-tests/agents/engine/unity/unity-addressables-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1091,7 +1091,7 @@ agents:
# Engine Specialists — Unreal
- name: unreal-specialist
- spec: CCGS Skill Testing Framework/agents/engine/unreal/unreal-specialist.md
+ spec: studio-tests/agents/engine/unreal/unreal-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1099,7 +1099,7 @@ agents:
category: engine
- name: ue-blueprint-specialist
- spec: CCGS Skill Testing Framework/agents/engine/unreal/ue-blueprint-specialist.md
+ spec: studio-tests/agents/engine/unreal/ue-blueprint-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1107,7 +1107,7 @@ agents:
category: engine
- name: ue-gas-specialist
- spec: CCGS Skill Testing Framework/agents/engine/unreal/ue-gas-specialist.md
+ spec: studio-tests/agents/engine/unreal/ue-gas-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1115,7 +1115,7 @@ agents:
category: engine
- name: ue-umg-specialist
- spec: CCGS Skill Testing Framework/agents/engine/unreal/ue-umg-specialist.md
+ spec: studio-tests/agents/engine/unreal/ue-umg-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1123,7 +1123,7 @@ agents:
category: engine
- name: ue-replication-specialist
- spec: CCGS Skill Testing Framework/agents/engine/unreal/ue-replication-specialist.md
+ spec: studio-tests/agents/engine/unreal/ue-replication-specialist.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1132,7 +1132,7 @@ agents:
# Operations
- name: devops-engineer
- spec: CCGS Skill Testing Framework/agents/operations/devops-engineer.md
+ spec: studio-tests/agents/operations/devops-engineer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1140,7 +1140,7 @@ agents:
category: operations
- name: release-manager
- spec: CCGS Skill Testing Framework/agents/operations/release-manager.md
+ spec: studio-tests/agents/operations/release-manager.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1148,7 +1148,7 @@ agents:
category: operations
- name: live-ops-designer
- spec: CCGS Skill Testing Framework/agents/operations/live-ops-designer.md
+ spec: studio-tests/agents/operations/live-ops-designer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1156,7 +1156,7 @@ agents:
category: operations
- name: community-manager
- spec: CCGS Skill Testing Framework/agents/operations/community-manager.md
+ spec: studio-tests/agents/operations/community-manager.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1164,7 +1164,7 @@ agents:
category: operations
- name: analytics-engineer
- spec: CCGS Skill Testing Framework/agents/operations/analytics-engineer.md
+ spec: studio-tests/agents/operations/analytics-engineer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1172,7 +1172,7 @@ agents:
category: operations
- name: economy-designer
- spec: CCGS Skill Testing Framework/agents/operations/economy-designer.md
+ spec: studio-tests/agents/operations/economy-designer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1180,7 +1180,7 @@ agents:
category: operations
- name: localization-lead
- spec: CCGS Skill Testing Framework/agents/operations/localization-lead.md
+ spec: studio-tests/agents/operations/localization-lead.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1189,7 +1189,7 @@ agents:
# QA & Creative
- name: qa-tester
- spec: CCGS Skill Testing Framework/agents/qa/qa-tester.md
+ spec: studio-tests/agents/qa/qa-tester.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1197,7 +1197,7 @@ agents:
category: qa
- name: prototyper
- spec: CCGS Skill Testing Framework/agents/specialists/prototyper.md
+ spec: studio-tests/agents/specialists/prototyper.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1205,7 +1205,7 @@ agents:
category: specialist
- name: writer
- spec: CCGS Skill Testing Framework/agents/specialists/writer.md
+ spec: studio-tests/agents/specialists/writer.md
last_spec: ""
last_spec_result: ""
last_category: ""
@@ -1213,7 +1213,7 @@ agents:
category: specialist
- name: world-builder
- spec: CCGS Skill Testing Framework/agents/specialists/world-builder.md
+ spec: studio-tests/agents/specialists/world-builder.md
last_spec: ""
last_spec_result: ""
last_category: ""
diff --git a/CCGS Skill Testing Framework/quality-rubric.md b/studio-tests/quality-rubric.md
similarity index 100%
rename from CCGS Skill Testing Framework/quality-rubric.md
rename to studio-tests/quality-rubric.md
diff --git a/CCGS Skill Testing Framework/skills/analysis/asset-audit.md b/studio-tests/skills/analysis/asset-audit.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/analysis/asset-audit.md
rename to studio-tests/skills/analysis/asset-audit.md
index 98d1886d..230f7171 100644
--- a/CCGS Skill Testing Framework/skills/analysis/asset-audit.md
+++ b/studio-tests/skills/analysis/asset-audit.md
@@ -40,6 +40,15 @@ None. Asset auditing is a read-only analysis skill; no gates are invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All assets follow naming conventions
diff --git a/CCGS Skill Testing Framework/skills/analysis/balance-check.md b/studio-tests/skills/analysis/balance-check.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/analysis/balance-check.md
rename to studio-tests/skills/analysis/balance-check.md
index 5b9a64ae..526f46bb 100644
--- a/CCGS Skill Testing Framework/skills/analysis/balance-check.md
+++ b/studio-tests/skills/analysis/balance-check.md
@@ -41,6 +41,15 @@ None. Balance check is an analysis skill; no gates are invoked in any review mod
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All balance values within their intended ranges
diff --git a/CCGS Skill Testing Framework/skills/analysis/code-review.md b/studio-tests/skills/analysis/code-review.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/analysis/code-review.md
rename to studio-tests/skills/analysis/code-review.md
index 783bedc0..244e4523 100644
--- a/CCGS Skill Testing Framework/skills/analysis/code-review.md
+++ b/studio-tests/skills/analysis/code-review.md
@@ -39,6 +39,15 @@ engine specialists and `qa-tester` as reviewers (Phase 7); those are not gates.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Standards-compliant file that follows its ADR
diff --git a/CCGS Skill Testing Framework/skills/analysis/consistency-check.md b/studio-tests/skills/analysis/consistency-check.md
similarity index 85%
rename from CCGS Skill Testing Framework/skills/analysis/consistency-check.md
rename to studio-tests/skills/analysis/consistency-check.md
index b69949e6..47fae3ae 100644
--- a/CCGS Skill Testing Framework/skills/analysis/consistency-check.md
+++ b/studio-tests/skills/analysis/consistency-check.md
@@ -45,6 +45,15 @@ required as part of the scan itself.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Registry and 4 GDDs agree
@@ -270,9 +279,47 @@ required as part of the scan itself.
---
+### Case 7: Registry Changed Since Phase 1 — re-read, then anchor each Edit on the current text
+
+**Fixture:**
+- `modes.workflow` resolves to `full`
+- Registry at the start of the run: `entities:` has `goblin` (`health: 40`,
+ `source: design/gdd/combat.md`) and `orc`; `items:` has `health_potion`
+- `design/gdd/combat.md` says goblin health is 50 (changed after the registry
+ entry was written: stale); `iron_sword` appears with a stated damage in both
+ `combat.md` and `loot.md` and is not in the registry
+- Between the Phase 1 read and the writes, another session edits
+ `design/registry/entities.yaml`: it adds a `troll` entity after `orc`, adds
+ an `iron_axe` item after `health_potion`, and changes the `referenced_by`
+ list on `goblin`
+- The user approves both asks: the stale-entry update and the new-entry add
+
+**Input:** `/consistency-check`
+
+**Expected behavior:**
+1. The scan reports one ⚠️ STALE REGISTRY entry (`goblin`) and one unregistered
+ cross-GDD item (`iron_sword`)
+2. Before the update Edit, the skill reads the current
+ `design/registry/entities.yaml`, finds the `goblin` entry in it, and anchors
+ the Edit on the entry's current text (the changed `referenced_by` included),
+ not on what Phase 1 saw
+3. Before the add Edit, it reads the file again and appends `iron_sword` after
+ the last existing entry of the `items:` section, which is now `iron_axe`
+4. The other session's changes survive: `troll`, `iron_axe` and the new
+ `referenced_by` are all still in the file
+
+**Assertions:**
+- [ ] A Read of `design/registry/entities.yaml` happens before each registry Edit, not only in Phase 1
+- [ ] The Edit that updates `goblin` is anchored on the entry as it reads at that moment, and it succeeds without overwriting the other session's `referenced_by` change
+- [ ] `iron_sword` is appended after `iron_axe`, the last existing `items:` entry, not after `health_potion`
+- [ ] `troll`, `iron_axe` and the changed `referenced_by` are present after the run: the registry is never rewritten whole from the Phase 1 copy
+- [ ] Each registry write still waits for its own "May I update" / "May I add" approval
+
+---
+
## Protocol Compliance
-- [ ] Reads the registry once, then greps GDDs; full-section reads happen only for conflicts
+- [ ] Reads the registry before each registry edit (it re-reads it per edit, so Case 3 reads it twice, and Case 7 shows a concurrent change surviving), then greps GDDs; full-section reads happen only for conflicts
- [ ] The report is shown in full before any registry write ask
- [ ] Report verdict is PASS, CONFLICTS FOUND or NOT ASSESSED (empty registry, unregistered name, or no GDD in scope — never PASS over nothing compared); post-correction verdict is COMPLETE or BLOCKED
- [ ] Applies each GDD's effective tier (the resolved `modes.workflow`, or that system's `system_overrides` row): at `standard`, compares the required GDD sections only (plus Tuning Knobs when `workflow_overrides.tuning_knobs` is true) and says so in the report
diff --git a/CCGS Skill Testing Framework/skills/analysis/content-audit.md b/studio-tests/skills/analysis/content-audit.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/analysis/content-audit.md
rename to studio-tests/skills/analysis/content-audit.md
index 2388c492..d13667d4 100644
--- a/CCGS Skill Testing Framework/skills/analysis/content-audit.md
+++ b/studio-tests/skills/analysis/content-audit.md
@@ -42,6 +42,15 @@ None. Content audit is an analysis skill; no gates are invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All specified content present
diff --git a/CCGS Skill Testing Framework/skills/analysis/estimate.md b/studio-tests/skills/analysis/estimate.md
similarity index 95%
rename from CCGS Skill Testing Framework/skills/analysis/estimate.md
rename to studio-tests/skills/analysis/estimate.md
index b66a0e9c..02ce48c9 100644
--- a/CCGS Skill Testing Framework/skills/analysis/estimate.md
+++ b/studio-tests/skills/analysis/estimate.md
@@ -36,6 +36,15 @@ None. Estimation is an advisory informational skill; no gates are invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Clear task in a documented system with existing patterns
@@ -60,6 +69,7 @@ None. Estimation is an advisory informational skill; no gates are invoked.
**Assertions:**
- [ ] The combat GDD and the sprint history are read before the estimate is produced
+- [ ] The Complexity Assessment's size row gives Grep counts for the affected files (non-blank lines, branch lines) and calls branching an approximation, not a measured complexity
- [ ] Effort is given as three day figures (Optimistic, Expected, Pessimistic), not a single number
- [ ] Recommended budget equals the Expected figure, not the Optimistic one
- [ ] Figures are rounded to half days, not hours
diff --git a/CCGS Skill Testing Framework/skills/analysis/perf-profile.md b/studio-tests/skills/analysis/perf-profile.md
similarity index 73%
rename from CCGS Skill Testing Framework/skills/analysis/perf-profile.md
rename to studio-tests/skills/analysis/perf-profile.md
index 81b7466f..f8047b88 100644
--- a/CCGS Skill Testing Framework/skills/analysis/perf-profile.md
+++ b/studio-tests/skills/analysis/perf-profile.md
@@ -5,7 +5,8 @@
`/perf-profile` is a static-analysis performance profiler. It takes a system
name or `full` as its scope, records every input it needs as `FOUND` or
`ABSENT` before producing anything, resolves `performance.enforce` from the
-config block injected at its top (Phase 0), and reads the committed budgets
+config block injected at its top (Phase 0; the block also carries
+`automation` and `workflow`), and reads the committed budgets
with `get_effective_yaml_key` for `performance.target_framerate`,
`performance.frame_budget_ms`, `performance.draw_call_limit` and
`performance.memory_ceiling_mb` before falling back to design docs or
@@ -18,7 +19,9 @@ report to `production/polish/[scope]-report-[date].md`?" before writing (Phase
4), offers implement / cut scope / defer / escalate choices for M- or L-effort
hotspots (Phase 5), and hands off to `/architecture-decision`, `/scope-check`
or `/sprint-plan update` (Phase 6). No director gates are invoked. Verdicts:
-COMPLETE, or NOT ASSESSED — NO DATA when every required input is absent.
+COMPLETE, or NOT ASSESSED — NO DATA when every required input is absent. At
+`workflow: minimal`, which has no sprints, an accepted optimization goes to the
+brief's build order and Phase 6 does not point to `/sprint-plan update`.
---
@@ -41,6 +44,15 @@ in any review mode.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Budgets committed, combat hotspots found
@@ -156,7 +168,7 @@ in any review mode.
### Case 5: Enforcement Level `off` in Full Review Mode — Informational only, no gates
**Fixture:**
-- `project.yaml`: `engine.name: godot`, `modes.review_mode: full`, `performance.enforce: off`, all four budgets set
+- `project.yaml`: `engine.name: godot`, `modes.review_mode: full`, `modes.workflow: standard` (pinned: unset resolves to `minimal`, which has no sprints, so Phase 6 would name the brief's build order instead of `/sprint-plan update`), `performance.enforce: off`, all four budgets set
- `src/` contains a `_process()` whose estimated frame cost exceeds `performance.frame_budget_ms`
**Input:** `/perf-profile full`
@@ -177,6 +189,67 @@ in any review mode.
---
+### Case 6: `workflow` — where an accepted optimization goes
+
+**Fixture:**
+- As Case 1: budgets committed, `enemy_manager.gd` has the nested loop and
+ per-frame raycast, and the nested-loop hotspot is rated Fix Effort M or L
+- `modes.rigor: minimal`, so `modes.workflow` resolves to `minimal` (no sprints)
+- The user picks A for the nested-loop hotspot
+- Variant: `modes.workflow: standard` (pinned: it is the tier that has sprints)
+
+**Input:** `/perf-profile combat`
+
+**Expected behavior:**
+1. Phase 5 runs because a hotspot is M or L, and option A reads "Implement the
+ optimization" with, at `minimal`, the note that there are no sprints and the
+ work is added to the brief's build order
+2. After the user picks A at `minimal`, the optimization is directed to the
+ brief's build order, not to a sprint
+3. Phase 6's scheduling line says to add the optimizations to the brief's build
+ order instead of running `/sprint-plan update`; `/sprint-plan` is not named
+ as the way to schedule
+4. Variant at `standard`: option A offers to proceed with the fix now or
+ schedule it, and Phase 6 names `/sprint-plan update`
+5. Verdict: COMPLETE in both runs
+
+**Assertions:**
+- [ ] At `minimal`, option A and Phase 6 both point to the brief's build order
+- [ ] At `minimal`, `/sprint-plan update` is not recommended
+- [ ] Variant at `standard`: Phase 6 names `/sprint-plan update` and option A does not mention the build order
+- [ ] The other Phase 5 options (`/scope-check`, defer to Polish, `/architecture-decision`) and the Phase 6 lines for `/architecture-decision` and `/scope-check [feature]` are the same in both runs
+- [ ] Verdict is COMPLETE
+
+---
+
+### Case 7: Session Started in a Subfolder — budgets are still read from the project root
+
+**Fixture:**
+- `project.yaml` at the project root: `engine.name: godot`,
+ `performance.target_framerate: 60`, `performance.frame_budget_ms: 16.6`,
+ `performance.draw_call_limit: 200`, `performance.memory_ceiling_mb: 2048`
+- The session's working directory is `src/gameplay/` (a subfolder), not the root
+- `src/gameplay/combat/enemy_manager.gd` has a `_process()` with a nested loop
+
+**Input:** `/perf-profile combat`
+
+**Expected behavior:**
+1. Phase 2 runs the four `get_effective_yaml_key` reads as one command that
+ first changes to the project root and loads `.claude/hooks/yaml-helper.sh`
+ from there
+2. All four keys return their committed values; none comes back empty because
+ the helper or `project.yaml` was not found from the subfolder
+3. The Performance Budgets table uses 16.6 ms, 2048 MB and 200 draw calls; those
+ rows are not `NOT ASSESSED`
+
+**Assertions:**
+- [ ] The budget read is a single command that changes to the project root before sourcing the helper, not four reads run from the current folder
+- [ ] The four values are the committed ones, not empty
+- [ ] No budget row is `NOT ASSESSED` because of the working directory: a budget set in `project.yaml` is never reported as unset
+- [ ] The nested loop is still found and reported with a `file:line` location
+
+---
+
## Protocol Compliance
- [ ] Records each input as FOUND or ABSENT before producing any report
@@ -185,7 +258,7 @@ in any review mode.
- [ ] Applies `performance.enforce` from the resolved block: `warn` → findings, `block` → blockers, `off` → informational
- [ ] Asks "May I write" naming `production/polish/[scope]-report-[date].md` before writing, and keeps `NOT ASSESSED` sections in the written file
- [ ] No director gates are invoked
-- [ ] Ends with the Phase 6 next-step handoff
+- [ ] Ends with the Phase 6 next-step handoff; the scheduling line depends on `workflow` (`/sprint-plan update` at `standard`/`full`, the brief's build order at `minimal`)
---
diff --git a/CCGS Skill Testing Framework/skills/analysis/scope-check.md b/studio-tests/skills/analysis/scope-check.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/analysis/scope-check.md
rename to studio-tests/skills/analysis/scope-check.md
index ff5ce0b8..99f1fe77 100644
--- a/CCGS Skill Testing Framework/skills/analysis/scope-check.md
+++ b/studio-tests/skills/analysis/scope-check.md
@@ -38,6 +38,15 @@ None. Scope check is a read-only advisory skill; no gates are invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Multi-word feature on track
diff --git a/CCGS Skill Testing Framework/skills/analysis/security-audit.md b/studio-tests/skills/analysis/security-audit.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/analysis/security-audit.md
rename to studio-tests/skills/analysis/security-audit.md
index 32206de0..de67c469 100644
--- a/CCGS Skill Testing Framework/skills/analysis/security-audit.md
+++ b/studio-tests/skills/analysis/security-audit.md
@@ -48,6 +48,15 @@ any review mode.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Single-player Godot project, no findings
diff --git a/CCGS Skill Testing Framework/skills/analysis/tech-debt.md b/studio-tests/skills/analysis/tech-debt.md
similarity index 81%
rename from CCGS Skill Testing Framework/skills/analysis/tech-debt.md
rename to studio-tests/skills/analysis/tech-debt.md
index ebc32185..8c27c36f 100644
--- a/CCGS Skill Testing Framework/skills/analysis/tech-debt.md
+++ b/studio-tests/skills/analysis/tech-debt.md
@@ -18,7 +18,10 @@ nothing. `add` collects an
entry through prompts and three `AskUserQuestion` choices, then asks "May I append
this entry to `docs/tech-debt-register.md`?". `prioritize` scores each register
item as `impact ÷ effort` from its Impact and Effort columns, re-sorts
-and asks before writing it back. `report` is read-only. No director gates are
+and asks before writing it back; it recommends what goes in the next sprint, or at
+`workflow: minimal` (no sprints) what to build next, and the closing next steps
+send high-priority items to `/sprint-plan` or the brief's build order. The skill
+resolves `automation` and `workflow`. `report` is read-only. No director gates are
invoked. Verdicts: COMPLETE, BLOCKED (user declined a write), FAIL (missing
subcommand), NOT ASSESSED.
@@ -43,6 +46,15 @@ invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Scan appends new findings to an existing register
@@ -184,11 +196,14 @@ invoked.
existing `Open` entry (same file and category) and asks whether to update
it instead of adding a duplicate
3. On "update", the matched entry is updated in place — no duplicate row is added
-4. On "add anyway", a new entry is appended alongside the match
+4. On "add anyway" (the user declines the update), the skill still asks
+ "May I append this entry to `docs/tech-debt-register.md`?" and, on yes,
+ appends a new entry alongside the match
**Assertions:**
- [ ] A new entry with the same file and category as an existing `Open` entry is never appended without first showing the match and asking
- [ ] "Update" edits the matched row rather than adding a new one
+- [ ] Declining the update does not end the run: the append is still offered, and asked for before it is written
---
@@ -214,7 +229,7 @@ invoked.
### Case 5: Prioritize in Full Review Mode — Scored, re-sorted, approved
**Fixture:**
-- `project.yaml`: `modes.review_mode: full`
+- `project.yaml`: `modes.review_mode: full`; `modes.workflow: standard` (pinned: unset resolves to minimal, which recommends the next build instead of a sprint)
- `docs/tech-debt-register.md` has 4 entries: TD-001 High/S, TD-002 Low/L, TD-003
Critical/M, TD-004 Med/— (Effort not yet estimated)
@@ -236,6 +251,33 @@ invoked.
- [ ] No director gate is invoked in any review mode
- [ ] The write happens only after the "May I write" prompt is approved
- [ ] Verdict is COMPLETE
+- [ ] The next steps send high-priority items to `/sprint-plan`
+
+---
+
+### Case 5b: Prioritize at Workflow Minimal — Build next, not a sprint
+
+**Fixture:**
+- `project.yaml`: `modes.rigor: minimal` (workflow resolves to `minimal`, which has no sprints); `modes.automation` unset (collaborative)
+- `docs/tech-debt-register.md` has 3 `Open` entries: TD-001 High/S, TD-002 Low/L, TD-003 Critical/M
+- `design/game-brief.md` exists with a build order of three numbered items; no `production/sprints/` folder
+
+**Input:** `/tech-debt prioritize`
+
+**Expected behavior:**
+1. Skill resolves `workflow: minimal` and reads the register
+2. Items are scored and re-sorted as in Case 5: TD-001 3.0, TD-003 2.0, TD-002 0.3
+3. The recommendation says which items to build next, not which belong in the next sprint
+4. Skill asks "May I write the re-prioritized register back to `docs/tech-debt-register.md`?" and writes on approval
+5. Next steps tell the user to add the high-priority items to the brief's build order instead of running `/sprint-plan`; they still include `/tech-debt report`
+6. Verdict: **COMPLETE** — register re-prioritized and saved
+
+**Assertions:**
+- [ ] The recommendation is "which to build next"; the word "sprint" is not used as the place to put the items
+- [ ] The next steps name the brief's build order (`design/game-brief.md`) as where the high-priority items go
+- [ ] `/sprint-plan` is not recommended
+- [ ] Scoring, re-sort and the write-after-approval rule are the same as in Case 5
+- [ ] Verdict is COMPLETE
---
@@ -249,7 +291,8 @@ invoked.
- [ ] New rows follow the Debt Register Format: the next `TD-NNN` ID, all ten columns, an `Added` date in `YYYY-MM-DD`
- [ ] A declined write ends with BLOCKED
- [ ] No director gates are invoked
-- [ ] Ends with the Phase 3 next steps (`/sprint-plan`, `/tech-debt report`)
+- [ ] Ends with the Phase 3 next steps (`/sprint-plan`, `/tech-debt report`); at workflow `minimal` the sprint step becomes "add them to the brief's build order"
+- [ ] Resolves `automation` and `workflow` through `resolve_config`
---
diff --git a/CCGS Skill Testing Framework/skills/analysis/test-evidence-review.md b/studio-tests/skills/analysis/test-evidence-review.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/analysis/test-evidence-review.md
rename to studio-tests/skills/analysis/test-evidence-review.md
index f116d31c..bb9ae135 100644
--- a/CCGS Skill Testing Framework/skills/analysis/test-evidence-review.md
+++ b/studio-tests/skills/analysis/test-evidence-review.md
@@ -49,6 +49,15 @@ None. Test evidence review is an advisory quality skill; no gates are invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Single Logic story with a strong test
@@ -288,7 +297,7 @@ None. Test evidence review is an advisory quality skill; no gates are invoked.
## Coverage Notes
-- Integration stories (playtest records in `production/session-logs/`) and
+- Integration stories (playtest records in `production/qa/playtests/`) and
Config/Data stories (`production/qa/smoke-*.md`) are not tested here.
- The no-argument path (the skill asks which scope to review) is not tested.
- The POTENTIALLY STALE freshness flag is not tested separately.
diff --git a/CCGS Skill Testing Framework/skills/analysis/test-flakiness.md b/studio-tests/skills/analysis/test-flakiness.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/analysis/test-flakiness.md
rename to studio-tests/skills/analysis/test-flakiness.md
index 3379f141..4d9f7915 100644
--- a/CCGS Skill Testing Framework/skills/analysis/test-flakiness.md
+++ b/studio-tests/skills/analysis/test-flakiness.md
@@ -40,6 +40,15 @@ None. Flakiness detection is an advisory quality skill; no gates are invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — High flakiness from JUnit history, quarantined on approval
diff --git a/CCGS Skill Testing Framework/skills/authoring/architecture-decision.md b/studio-tests/skills/authoring/architecture-decision.md
similarity index 89%
rename from CCGS Skill Testing Framework/skills/authoring/architecture-decision.md
rename to studio-tests/skills/authoring/architecture-decision.md
index 660d56cf..355ec841 100644
--- a/CCGS Skill Testing Framework/skills/authoring/architecture-decision.md
+++ b/studio-tests/skills/authoring/architecture-decision.md
@@ -61,6 +61,15 @@ In every mode the written ADR has `Status: Proposed`.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — New rendering ADR, full mode, TD-ADR approves
@@ -168,7 +177,7 @@ In every mode the written ADR has `Status: Proposed`.
2. Still in Step 3a — right after the stances, before Step 4's assumptions prompt — the skill surfaces the conflict: "⚠️ Conflict: This ADR proposes [X], but ADR-0003 established that [Y]…"
3. It offers three options: (1) align with the existing stance, (2) supersede ADR-0003 with an explicit replacement, (3) explain why this case is an exception
4. It does not proceed to Step 4 until the conflict is resolved or accepted as an intentional exception
-5. If the user chooses to supersede: at the registry step the old entry is set to `status: superseded_by: ADR-[NNNN]` and the new entry is added — the existing entry is not otherwise modified
+5. If the user chooses to supersede: at the registry step the old entry is set to `status: "superseded_by: ADR-[NNNN]"` (quoted) and the new entry is added — the existing entry is not otherwise modified
**Assertions:**
- [ ] The registry is read before any existing ADR file
@@ -205,6 +214,39 @@ In every mode the written ADR has `Status: Proposed`.
---
+### Case 5b: Acceptance Mode — a story that names the ADR only as a successor is left out
+
+**Fixture:**
+- `docs/architecture/adr-0005-physics-layers.md` exists with `Status: Proposed`
+ and a `## ADR Dependencies` section whose only dependency, ADR-0001, is `Accepted`
+- Three stories under `production/epics/` are `> **Status**: Blocked`:
+ - `story-001.md`: blocked because ADR-0005 is Proposed
+ - `story-002.md`: blocked with "BLOCKED: ADR-0003 is Superseded — point the
+ story at ADR-0005 (edit its ADR field …) before implementing"; ADR-0005 is
+ named only as the successor of ADR-0003
+ - `story-003.md`: blocked for an unrelated reason that names no ADR-0005
+- The user answers `[A] Yes — accept it`
+
+**Input:** `/architecture-decision accept ADR-0005`
+
+**Expected behavior:**
+1. The dependency check passes
+2. The Blocked-story grep returns all three files; only `story-001.md` names
+ ADR-0005 as the reason it is blocked. `story-002.md` is left out because it
+ names ADR-0005 only as the successor to point at: it is still governed by
+ ADR-0003, and accepting ADR-0005 does not re-point it
+3. The confirmation prompt says "1 story becomes Ready", not 2 or 3
+4. On yes: `## Status` becomes `Accepted`; only `story-001.md` moves from
+ `Blocked` to `Ready`; the report lists the ADR and that one story
+
+**Assertions:**
+- [ ] The stories-to-unblock count in the prompt is 1
+- [ ] `story-002.md` stays `Blocked`, unedited, and is not in the report of what moved
+- [ ] `story-003.md` stays `Blocked`, unedited
+- [ ] `story-001.md` becomes `Ready` only after the user confirms
+
+---
+
### Case 6: Retrofit — Missing Status answered `Accepted`
**Fixture:**
diff --git a/CCGS Skill Testing Framework/skills/authoring/art-bible.md b/studio-tests/skills/authoring/art-bible.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/authoring/art-bible.md
rename to studio-tests/skills/authoring/art-bible.md
index 1e773efd..5a8a0f0a 100644
--- a/CCGS Skill Testing Framework/skills/authoring/art-bible.md
+++ b/studio-tests/skills/authoring/art-bible.md
@@ -65,6 +65,15 @@ The section-drafting delegation to `art-director` (and to `ux-designer` /
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Full mode, full workflow, all nine sections, AD-ART-BIBLE approves
diff --git a/CCGS Skill Testing Framework/skills/authoring/create-architecture.md b/studio-tests/skills/authoring/create-architecture.md
similarity index 91%
rename from CCGS Skill Testing Framework/skills/authoring/create-architecture.md
rename to studio-tests/skills/authoring/create-architecture.md
index c6db86f1..5aa7e88b 100644
--- a/CCGS Skill Testing Framework/skills/authoring/create-architecture.md
+++ b/studio-tests/skills/authoring/create-architecture.md
@@ -67,6 +67,15 @@ skipped — Solo mode."
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — New architecture document, full mode, reviews approve
@@ -84,7 +93,7 @@ skipped — Solo mode."
**Expected behavior:**
1. Phase 0a reads the four engine docs and only the `modules/` docs matching domains in the systems index
-2. Phase 0b Greps the requirement-bearing sections of each GDD (Detailed Rules/Design, Formulas, Dependencies, Tuning Knobs, Acceptance Criteria) and presents the Technical Requirements Baseline with IDs such as `TR-combat-001`
+2. Phase 0b Greps the requirement-bearing sections of each GDD (Detailed Rules/Design, Formulas, Dependencies, Tuning Knobs, Acceptance Criteria) and presents the Technical Requirements Baseline with IDs such as `TR-combat-001 (provisional)` (no TR registry yet)
3. Phase 0c builds the ADR inventory from `## Status`/`## Summary` and `**Domain**` Greps, not full reads
4. Phase 0d shows the Engine Knowledge Gap Inventory and asks `[A] Proceed — flag HIGH RISK domains…` / `[B] Let me check the engine reference first…` / `[C] Show me which domains are HIGH RISK and why`
5. Phases 1–4: each proposal (layer map, ownership map, each data-flow scenario, API boundaries) is shown and approved before the next, and each approval is recorded in `production/session-state/active.md` — nothing is written to the architecture document before Phase 7
@@ -259,6 +268,28 @@ skipped — Solo mode."
---
+### Case 7: Re-run with a TR registry — registered IDs are reused, new ones are provisional
+
+**Fixture:**
+- Same project as Case 1, but `/architecture-review` has run: `docs/architecture/tr-registry.yaml` holds `TR-combat-001` (`requirement: "Hitbox detection per-frame"`, `status: active`) and `TR-combat-002` (`requirement: "Old combo timing"`, `status: deprecated`)
+- `design/gdd/combat.md` still describes per-frame hitbox detection and adds a combo state machine; `design/gdd/inventory.md` has no registry entries
+
+**Input:** `/create-architecture`
+
+**Expected behavior:**
+1. Phase 0b reads `docs/architecture/tr-registry.yaml` before numbering the baseline
+2. Hitbox detection keeps `TR-combat-001`
+3. The combo state machine is numbered from `registry.sh next-id tr combat` (`TR-combat-003`), not `TR-combat-002`, and is marked `(provisional)`
+4. The inventory requirements are `TR-inventory-001 (provisional)` onwards
+5. The baseline's header line gives the registered and provisional counts and says the registry was read
+
+**Assertions:**
+- [ ] No registered ID is given to a different requirement, and the deprecated `TR-combat-002` is not reused
+- [ ] Every ID not in the registry is marked `(provisional)`
+- [ ] With no registry (Case 1), the header says the registry is absent and every ID is provisional
+
+---
+
## Protocol Compliance
- [ ] Stops before authoring when the engine is missing, or on a `standard`/`full` project when the systems index or game concept is missing; at `minimal` it proceeds from `design/game-brief.md` and stops only when that is absent too
diff --git a/CCGS Skill Testing Framework/skills/authoring/design-system.md b/studio-tests/skills/authoring/design-system.md
similarity index 77%
rename from CCGS Skill Testing Framework/skills/authoring/design-system.md
rename to studio-tests/skills/authoring/design-system.md
index 0d0cfeb0..7a07e360 100644
--- a/CCGS Skill Testing Framework/skills/authoring/design-system.md
+++ b/studio-tests/skills/authoring/design-system.md
@@ -10,6 +10,9 @@ Dependencies, Tuning Knobs, Acceptance Criteria); 5 plus conditional Formulas at
`standard`; 5 at a voluntary `minimal`. `## Summary` is authored at every tier,
after the other sections.
+Each of the five phases is a `references/N-*.md` file the skill reads before doing
+that phase and reads again if the conversation is compacted during it.
+
The skill reads context first (game concept, systems index, entity registry,
dependency GDD sections, engine reference), presents a context summary and a
Technical Feasibility Brief, then asks "May I create the skeleton file at
@@ -69,6 +72,15 @@ Review manually before production."
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — New combat GDD, full mode, full workflow
@@ -244,6 +256,61 @@ Review manually before production."
---
+### Case 7: Phase Files Are Read Before Each Phase, and Again After a Compaction
+
+**Fixture:**
+- `project.yaml` has `engine.name: Godot`, `modes.workflow: standard`, `modes.review_mode: solo`
+- `design/gdd/game-concept.md` and `design/gdd/systems-index.md` exist; `stamina` is listed with `Category: Gameplay`; no `design/gdd/stamina.md`
+- The skill folder holds `references/1-parse-arguments.md` through `references/5-post-design.md`
+- Mid-run, while Section D (Formulas) is being drafted, the conversation is compacted; the user then replies to the open question and the run continues
+
+**Input:** `/design-system stamina`
+
+**Expected behavior:**
+1. SKILL.md carries no phase steps itself; before starting each phase the run reads that phase's file: `references/1-parse-arguments.md`, then `2-gather-context.md`, then `3-file-skeleton.md`, then `4-section-design.md`, then `5-post-design.md`
+2. No phase's steps are carried out before its file has been read — e.g. no context read or question before `1-parse-arguments.md`, no skeleton ask before `3-file-skeleton.md`, no section cycle before `4-section-design.md`
+3. After the compaction the run reads `references/4-section-design.md` again before resuming Section D, as the skill says: "Read it again if the conversation was compacted or resumed during this phase."
+4. The run does not re-read the phase files of other phases because of the compaction, and it does not continue Section D from memory of the earlier read
+5. The run then reads `references/5-post-design.md` before the Summary and self-check
+
+**Assertions:**
+- [ ] The transcript shows a file read of each of the five `references/N-*.md` files, in order, each before that phase's work begins
+- [ ] No phase work (context reads, skeleton ask, section drafts, Summary) happens before its phase file is read
+- [ ] After the compaction, `references/4-section-design.md` is read again before Section D resumes
+- [ ] Settings resolved in SKILL.md (`workflow`, `review_mode`, `automation`, `docs.density`) still apply in the phase files; the run does not ask for them again
+
+---
+
+### Case 8: Populated Registry and Numbered-Heading Dependency GDDs — Block-form greps find the facts
+
+**Fixture:**
+- `project.yaml` has `engine.name: Godot`, `modes.workflow: standard`, `modes.review_mode: solo`
+- `design/gdd/game-concept.md` and `design/gdd/systems-index.md` exist; `stamina` is listed with `Category: Gameplay` and `Depends on: combat`
+- `design/registry/entities.yaml` has a live `constants:` list with two entries:
+ - `- name: stagger_threshold` with `value: 40` and `source: design/gdd/combat.md` (owned by combat)
+ - `- name: stamina_cost_dodge` with `value: 25`, `source: design/gdd/stamina.md`, and a block-form `referenced_by:` list (the key on one line, `- design/gdd/combat.md` on the next)
+- The same file's header comments hold an example entry for `gold_carry_limit: 9999` referencing `design/gdd/inventory.md`
+- `design/gdd/combat.md` exists with numbered headings: `## 1. Overview`, `## 3. Detailed Design`, `## 4. Formulas`, `## 5. Edge Cases`, `## 6. Dependencies`, `## 7. Tuning Knobs`; its Formulas section uses `stagger_threshold` and its Tuning Knobs section lists it
+- No `design/gdd/stamina.md`
+
+**Input:** `/design-system stamina`
+
+**Expected behavior:**
+1. Registry lookups use two greps: one for `source: design/gdd/stamina.md` with trailing context (`-A 6`) and one for `design/gdd/stamina.md` with leading context (`-B 8`); the `-B 8` match reaches the owning entry above the `referenced_by` path, so `stamina_cost_dodge` is found as owned by stamina and `stagger_threshold` as a fact stamina must respect
+2. A single-line `referenced_by.*stamina` pattern is not relied on, because the list is block-form
+3. For the dependency GDD `combat.md`, the run greps `^## ([0-9]+\. )?(Dependencies|Formulas|Edge Cases|Tuning Knobs)` so the numbered headings `## 4. Formulas`, `## 5. Edge Cases`, `## 6. Dependencies` and `## 7. Tuning Knobs` all match; the whole GDD is not read
+4. The context summary's "Known cross-system facts (from registry)" lists `stamina_cost_dodge=25` and `stagger_threshold=40` with their owning GDDs, marked locked
+5. The commented `gold_carry_limit: 9999` example is not listed as a known fact
+
+**Assertions:**
+- [ ] The registry is searched for `source: design/gdd/stamina.md` and for the path with `-B 8` context, not only with a one-line `referenced_by` pattern
+- [ ] `stamina_cost_dodge` (found through its `source:` and its block-form `referenced_by:`) and `stagger_threshold` appear under Known cross-system facts with their values and owners
+- [ ] The dependency GDD's sections are found despite their `N.` heading numbers — all four of Dependencies, Formulas, Edge Cases and Tuning Knobs are read
+- [ ] `combat.md` is read by section, not whole
+- [ ] The commented `gold_carry_limit` example is not presented as a locked value
+
+---
+
## Protocol Compliance
- [ ] Reads context before asking anything; stops with the `/brainstorm` or `/map-systems` message when the game concept or systems index is missing on a `standard`/`full` project (a `minimal` project reads the brief instead, even for a system `system_overrides` raises)
@@ -253,6 +320,7 @@ Review manually before production."
- [ ] Specialist spawns follow the per-section review-mode checks; every skipped spawn leaves a "not consulted" note naming the agent and the mode, in lean as in solo
- [ ] CD-GDD-ALIGN runs once in full mode after all sections; lean and solo print a skip note naming the gate and mode
- [ ] `/design-review` is directed to a fresh session and never run or offered inline
+- [ ] Reads each phase's `references/N-*.md` file before doing that phase, and again after a compaction or resume during it
- [ ] Ends with a next-step `AskUserQuestion` and Recommended Next Steps (`/consistency-check`, `/map-systems next`, `/design-review` in a fresh session)
---
diff --git a/CCGS Skill Testing Framework/skills/authoring/quick-design.md b/studio-tests/skills/authoring/quick-design.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/authoring/quick-design.md
rename to studio-tests/skills/authoring/quick-design.md
index 683860ea..c19c42d5 100644
--- a/CCGS Skill Testing Framework/skills/authoring/quick-design.md
+++ b/studio-tests/skills/authoring/quick-design.md
@@ -47,6 +47,15 @@ agent. The review mode setting has no effect on it.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Tweak to an existing system
diff --git a/CCGS Skill Testing Framework/skills/authoring/ux-design.md b/studio-tests/skills/authoring/ux-design.md
similarity index 85%
rename from CCGS Skill Testing Framework/skills/authoring/ux-design.md
rename to studio-tests/skills/authoring/ux-design.md
index 7a64d5d8..a559cf3f 100644
--- a/CCGS Skill Testing Framework/skills/authoring/ux-design.md
+++ b/studio-tests/skills/authoring/ux-design.md
@@ -50,6 +50,15 @@ to the user, and this session owns every file write.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — New HUD design
@@ -184,6 +193,41 @@ to the user, and this session owns every file write.
---
+### Case 6: Handoff — names the Production gate and what the review requirement depends on
+
+**Fixture:**
+- `modes.rigor: standard` (pinned: the handoff states how the Production gate treats
+ `/ux-review` per workflow tier, and `standard` is the tier where it is recommended)
+- A screen spec `design/ux/settings-menu.md` whose sections are all approved and
+ written; the Cross-Reference Check has run
+- Variant: the user picks "Design another screen first, then review all specs together"
+
+**Input:** `/ux-design settings-menu` (continuing to the handoff)
+
+**Expected behavior:**
+1. Phase 6 updates `production/session-state/active.md`
+2. Before offering options, it states: "This spec should be validated with
+ `/ux-review` before it enters the implementation pipeline. The Production gate
+ (`/gate-check production`) requires all key screen specs to have passed
+ `/ux-review` at `workflow: full` (recommended at `standard`)."
+3. It then asks "Run `/ux-review [filename]` now, or do something else first?" with
+ four options (run now / design another screen / update the pattern library / stop)
+4. Variant: it adds "Reminder: run `/ux-review` on all completed specs before
+ running `/gate-check production`."
+5. The closing next steps include running `/gate-check production` once all key
+ screens have approved UX specs
+6. Verdict: `COMPLETE`
+
+**Assertions:**
+- [ ] The handoff names `/gate-check production` as the gate that depends on `/ux-review`, not only `/ux-review` itself
+- [ ] It says the requirement is `workflow: full` and only recommended at `standard`, so a `standard` project is not told the review is mandatory
+- [ ] The statement comes before the options question
+- [ ] Variant — the "Design another screen first" pick adds the reminder naming `/gate-check production`
+- [ ] The next steps list `/gate-check production` after the screens' specs are approved
+- [ ] The verdict is `COMPLETE`
+
+---
+
## Protocol Compliance
- [ ] Once the mode is known — with no argument, the mode question comes first (Case 4) — reads context before asking the user anything else
diff --git a/CCGS Skill Testing Framework/skills/authoring/ux-review.md b/studio-tests/skills/authoring/ux-review.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/authoring/ux-review.md
rename to studio-tests/skills/authoring/ux-review.md
index 0196ecf7..d9b4665b 100644
--- a/CCGS Skill Testing Framework/skills/authoring/ux-review.md
+++ b/studio-tests/skills/authoring/ux-review.md
@@ -47,6 +47,15 @@ tool and invokes no director gate.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Complete UX spec, APPROVED
diff --git a/CCGS Skill Testing Framework/skills/gate/gate-check.md b/studio-tests/skills/gate/gate-check.md
similarity index 91%
rename from CCGS Skill Testing Framework/skills/gate/gate-check.md
rename to studio-tests/skills/gate/gate-check.md
index 959adf10..d7c3d908 100644
--- a/CCGS Skill Testing Framework/skills/gate/gate-check.md
+++ b/studio-tests/skills/gate/gate-check.md
@@ -32,6 +32,15 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All Concept artifacts present, advancing to Systems Design
@@ -378,6 +387,37 @@ before it is made.
---
+### Case 10: Minimal-tier closing route — a built game with no brief is sent to `/reverse-document`
+
+**Fixture:**
+- `project.yaml` sets `modes.rigor: minimal` (so `workflow: minimal`) and
+ `engine.name: Godot`
+- `src/` holds 15 GDScript files (the code root already holds the game)
+- No `design/game-brief.md`, no `design/gdd/game-concept.md`, no GDDs
+- Variant: `src/` is empty (a new project)
+
+**Input:** `/gate-check systems-design`
+
+**Expected behavior:**
+1. The target artifact at `minimal` is `design/game-brief.md`; it is missing, so
+ the verdict is FAIL, naming the brief as the blocker
+2. The stage is not written
+3. The closing next-step widget skips the phase-ladder menus (`/map-systems`,
+ `/design-system`) because the minimal route is not the ladder, and offers the
+ first incomplete step of `paths.minimal`: the brief
+4. Because the code root already holds the game, that step is
+ `/reverse-document design src/` (it writes the brief from what is built), not
+ `/brainstorm`
+5. Variant (empty `src/`): the step is `/brainstorm`
+
+**Assertions:**
+- [ ] The closing widget is built from the minimal route, with no `/map-systems` or `/design-system` option
+- [ ] With a built game and no brief, the first option is `/reverse-document design src/`, with the code root filled in, and `/brainstorm` is not offered as the way to get the brief
+- [ ] Variant — with an empty code root the first option is `/brainstorm`, not `/reverse-document`
+- [ ] The verdict is FAIL and the stage is not written, whatever the route offered
+
+---
+
## Protocol Compliance
- [ ] Asks before updating the stage ("May I update `project.stage` in `project.yaml` … (and the legacy `production/stage.txt`)?")
@@ -399,3 +439,5 @@ before it is made.
- The Vertical Slice validation block (Pre-Production → Production gate at
`standard`/`full`) is not covered because it requires a playable build context
that cannot be expressed as a document fixture; at `minimal` it drops (Case 8).
+- The `minimal` closing route is tested for the missing-brief step only (Case 10);
+ the later steps (`/create-stories`, `/dev-story`) are not separately tested.
diff --git a/CCGS Skill Testing Framework/skills/pipeline/create-control-manifest.md b/studio-tests/skills/pipeline/create-control-manifest.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/pipeline/create-control-manifest.md
rename to studio-tests/skills/pipeline/create-control-manifest.md
index 377e98ed..b017ba0e 100644
--- a/CCGS Skill Testing Framework/skills/pipeline/create-control-manifest.md
+++ b/studio-tests/skills/pipeline/create-control-manifest.md
@@ -54,6 +54,15 @@ then supplied and the gate re-run, or the run goes on with
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — 4 Accepted ADRs create a correct manifest
diff --git a/CCGS Skill Testing Framework/skills/pipeline/create-epics.md b/studio-tests/skills/pipeline/create-epics.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/pipeline/create-epics.md
rename to studio-tests/skills/pipeline/create-epics.md
index 4bbf53bd..a40700b5 100644
--- a/CCGS Skill Testing Framework/skills/pipeline/create-epics.md
+++ b/studio-tests/skills/pipeline/create-epics.md
@@ -56,6 +56,15 @@ In `solo` mode: PR-EPIC is skipped. Output notes: "PR-EPIC skipped — Solo mode
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Two approved GDDs create two epics
diff --git a/CCGS Skill Testing Framework/skills/pipeline/create-stories.md b/studio-tests/skills/pipeline/create-stories.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/pipeline/create-stories.md
rename to studio-tests/skills/pipeline/create-stories.md
index 6a8ec50d..3d321d00 100644
--- a/CCGS Skill Testing Framework/skills/pipeline/create-stories.md
+++ b/studio-tests/skills/pipeline/create-stories.md
@@ -60,6 +60,15 @@ In `solo` mode: QL-STORY-READY is skipped. Output notes:
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Epic with 3 stories, all ADRs Accepted
@@ -308,7 +317,8 @@ In `solo` mode: QL-STORY-READY is skipped. Output notes:
## Coverage Notes
-- At `minimal`, the "run `/brainstorm` first" stop when no brief exists and a named
+- At `minimal`, the "run `/brainstorm` first" stop when no brief exists (or
+ `/reverse-document design [code root]` when the game is already built) and a named
epic slug that does not exist (the `minimal` branch is taken instead of
`/create-epics`) are not given fixtures.
- The `full` missing-ADR-file stop and the `standard` critical/non-critical ADR
diff --git a/CCGS Skill Testing Framework/skills/pipeline/dev-story.md b/studio-tests/skills/pipeline/dev-story.md
similarity index 92%
rename from CCGS Skill Testing Framework/skills/pipeline/dev-story.md
rename to studio-tests/skills/pipeline/dev-story.md
index 5485f224..d5cdf0f6 100644
--- a/CCGS Skill Testing Framework/skills/pipeline/dev-story.md
+++ b/studio-tests/skills/pipeline/dev-story.md
@@ -53,6 +53,15 @@ step at `standard`/`full`.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Logic story implemented at full workflow
@@ -426,6 +435,37 @@ The `full` column of the file-check table has its own STOP rule, so the
---
+### Case 11: Two TR-IDs share a prefix — the registry lookup matches the exact id
+
+**Fixture:**
+- `project.yaml`: `engine.name: Godot`, `modes.workflow: full` (pinned: the TR registry
+ is required at `full`, so the lookup always runs)
+- `docs/architecture/tr-registry.yaml` lists `TR-combat-0010` first, then
+ `TR-combat-001`, each as `- id: TR-combat-NNN` followed by its own `requirement:`
+ line. `TR-combat-0010` reads "Enemies drop loot on death"; `TR-combat-001` reads
+ "Damage is clamped to the target's remaining health"
+- Story A: `Requirement: TR-combat-001`. Story B: `Requirement: TR-combat-0010`.
+ Both `Status: Ready`, Type Logic, ADR governing field `N/A`, Dependencies None
+
+**Input:** `/dev-story production/epics/combat/story-A-[slug].md`, then the same for story B
+
+**Expected behavior:**
+1. For story A the registry grep is anchored at the end of the line
+ (`id: TR-combat-001\s*$`), so `id: TR-combat-0010` does not match
+2. The matched entry is `TR-combat-001`; its `requirement` text ("Damage is clamped…")
+ is the one held and briefed to the agent
+3. For story B the grep returns only the `TR-combat-0010` entry and its
+ "Enemies drop loot on death" requirement
+4. Neither run reads the whole registry
+
+**Assertions:**
+- [ ] Story A's brief carries the `TR-combat-001` requirement text, never the `TR-combat-0010` text, although `TR-combat-0010` appears first in the file
+- [ ] Story B's brief carries the `TR-combat-0010` requirement text
+- [ ] The grep pattern ends with `\s*$` (or is otherwise an exact match), so neither lookup returns the other id's entry
+- [ ] The whole registry is not read for either story
+
+---
+
## Protocol Compliance
- [ ] Does NOT write source code directly — delegates to specialist agents
diff --git a/CCGS Skill Testing Framework/skills/pipeline/map-systems.md b/studio-tests/skills/pipeline/map-systems.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/pipeline/map-systems.md
rename to studio-tests/skills/pipeline/map-systems.md
index ab072455..96cf9660 100644
--- a/CCGS Skill Testing Framework/skills/pipeline/map-systems.md
+++ b/studio-tests/skills/pipeline/map-systems.md
@@ -62,6 +62,15 @@ In `solo` mode the same three notes appear with "Solo mode."
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Concept decomposed and index written in full review mode
diff --git a/CCGS Skill Testing Framework/skills/pipeline/propagate-design-change.md b/studio-tests/skills/pipeline/propagate-design-change.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/pipeline/propagate-design-change.md
rename to studio-tests/skills/pipeline/propagate-design-change.md
index 043e14f8..d9960b32 100644
--- a/CCGS Skill Testing Framework/skills/pipeline/propagate-design-change.md
+++ b/studio-tests/skills/pipeline/propagate-design-change.md
@@ -56,6 +56,15 @@ and the Verdict line.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — GDD formula change affects one of two referencing ADRs
diff --git a/CCGS Skill Testing Framework/skills/pipeline/vertical-slice.md b/studio-tests/skills/pipeline/vertical-slice.md
similarity index 82%
rename from CCGS Skill Testing Framework/skills/pipeline/vertical-slice.md
rename to studio-tests/skills/pipeline/vertical-slice.md
index 31547055..66244ddc 100644
--- a/CCGS Skill Testing Framework/skills/pipeline/vertical-slice.md
+++ b/studio-tests/skills/pipeline/vertical-slice.md
@@ -20,8 +20,11 @@ row, one ask naming both. Verdicts are **PROCEED / PIVOT / KILL**, plus
**NOT ASSESSED** when nobody has played the loop through from scratch — ranked
above PROCEED and below PIVOT and KILL, and never recorded as PROCEED. The verdict
feeds `/gate-check production`, which FAILs a built slice with any NO among its
-Vertical Slice Validation items, so PROCEED is not available after such a NO. In
-`full` review mode `creative-director` reviews the result via **CD-PLAYTEST**
+Vertical Slice Validation items, so PROCEED is not available after such a NO. The
+resolved `modes.workflow` shapes the PROCEED route: at `minimal` there are no
+sprints, so the velocity log feeds the brief's build order and the next steps are
+`/create-stories` then `/dev-story`; at `standard` and `full` they are the epics,
+stories, sprint and gate list. In `full` review mode `creative-director` reviews the result via **CD-PLAYTEST**
(APPROVE / CONCERNS / REJECT, or NOT ASSESSED): APPROVE keeps the recommendation;
CONCERNS go to the user (Revise / Accept / Discuss); REJECT means PROCEED cannot
stand — the user chooses PIVOT or KILL and the report records the director's
@@ -62,13 +65,24 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — slice built, played unaided, PROCEED
**Fixture:**
- `project.yaml`: `engine.name: Godot`, `engine.language: GDScript`,
- `modes.review_mode: solo`
+ `modes.review_mode: solo`, `modes.workflow: standard` (pinned: unset resolves
+ to minimal, which routes PROCEED to `/create-stories` and `/dev-story` instead
+ of the step 7 list)
- `design/gdd/game-concept.md` (core fantasy, pillars), `design/gdd/systems-index.md`,
`docs/architecture/architecture.md` and `docs/architecture/control-manifest.md`
exist; `prototypes/` has no `ember-trail-vertical-slice/`
@@ -224,6 +238,41 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+### Case 6: Minimal workflow — PROCEED routes to stories and the velocity feeds the brief
+
+**Fixture:**
+- `project.yaml`: `engine.name: Godot`, `engine.language: GDScript`,
+ `modes.workflow: minimal`, `modes.review_mode: solo` (pinned: this case tests the
+ `minimal` PROCEED route, the opposite of Case 1)
+- `design/game-brief.md` holds the pitch, a "what they feel" line and a build order
+ of three features; there is no `design/gdd/game-concept.md`, no sprint plan and no
+ `production/sprints/`
+- In the debrief the player finished the loop unaided, reached the first meaningful
+ action in 40 seconds, felt the core fantasy and hit no fun blocker; the user
+ answers PROCEED
+
+**Input:** `/vertical-slice`
+
+**Expected behavior:**
+1. Reads the brief in place of the concept and builds as in Case 1
+2. The report's day-by-day velocity log is described as feeding the brief's build
+ order, not sprint planning ("at `workflow: minimal`, which has no sprints, into
+ the brief's build order")
+3. PROCEED prints the minimal route: `/create-stories` (from the brief), then
+ `/dev-story` on the first story. The skill states "the rest of this list is the
+ `standard`/`full` path"
+4. The `/create-epics layer:foundation`, `/create-epics layer:core` and `/sprint-plan`
+ steps are not offered as the next steps
+
+**Assertions:**
+- [ ] The workflow is resolved from `project.yaml` (`modes.workflow: minimal`), not assumed from the rigor preset alone
+- [ ] PROCEED's next steps are `/create-stories` then `/dev-story`
+- [ ] `/create-epics` and `/sprint-plan` are not recommended as next steps at `minimal`
+- [ ] The velocity log is tied to the brief's build order, and no sprint plan is referenced or created
+- [ ] REPORT.md and the `prototypes/index.md` row still record PROCEED after one ask naming both
+
+---
+
## Protocol Compliance
- [ ] Reads the concept (or the brief at `minimal`) before defining the validation question
@@ -242,8 +291,9 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
log need a live run to verify.
- Reading a prior `PIVOT-NOTE.md` on a re-run to frame the new validation question
is not tested.
-- The `rigor: minimal` path (the brief's pitch and "what they feel" line in place
- of pillars) is not given its own fixture.
+- The `rigor: minimal` PROCEED route is Case 6. The brief's pitch and "what they
+ feel" line standing in for pillars in the CD-PLAYTEST input is not tested, since
+ the gate is skipped outside `full`.
- A KILL whose soundness checklist gives 0–1 items (one targeted PIVOT suggested
instead) is not tested.
- The networked-game limit (a local slice cannot validate network feel) is
diff --git a/CCGS Skill Testing Framework/skills/readiness/story-done.md b/studio-tests/skills/readiness/story-done.md
similarity index 90%
rename from CCGS Skill Testing Framework/skills/readiness/story-done.md
rename to studio-tests/skills/readiness/story-done.md
index 5989759e..de63e3e8 100644
--- a/CCGS Skill Testing Framework/skills/readiness/story-done.md
+++ b/studio-tests/skills/readiness/story-done.md
@@ -34,6 +34,15 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All acceptance criteria met, no deviations
@@ -285,8 +294,30 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+### Case 8: Reference files are read only on the branch that needs them
+
+**Fixture:**
+- As Case 1 (`modes.rigor: standard`, so `review_mode: lean`; `engine.name: Godot`; the Logic story with three covered criteria and its retained run evidence), with no sprint plan and no `production/sprint-status.yaml`
+- The skill folder holds `references/review-gates.md`, `references/sprint-next.md` and `references/tech-debt-row.md`
+- Variant: `modes.review_mode: full`, a sprint plan listing one more story after this one, and one advisory deviation (Case 3's fixture, downgraded to advisory)
+
+**Input:** `/story-done production/epics/core/story-light-pickup.md`
+
+**Expected behavior:**
+1. The main path is in `SKILL.md`. At `lean` with no sprint plan and no advisory deviation, none of the three reference files applies, and the run reads none of them
+2. Phase 6 asks the lean `/code-review` question without loading `references/review-gates.md`
+3. Variant: at `full`, the run reads `references/review-gates.md` at Phase 6, before either gate agent starts; on "Close and log as tech debt" it reads `references/tech-debt-row.md` before writing the row; with the sprint plan, it reads `references/sprint-next.md` at Phase 8, before naming Next Up
+
+**Assertions:**
+- [ ] Lean, no sprint plan: the transcript shows no read of any `references/*.md` file
+- [ ] Variant: each reference file is read before the step it holds begins, never at the start of the run
+- [ ] The resolved settings (`review_mode`, `workflow`, `qa.level`, `automation`) still govern every step: lean still asks the `/code-review` question, and Phase 7 still asks before editing the story file
+
+---
+
## Protocol Compliance
+- [ ] Reads a `references/*.md` file only on the branch that needs it, before that branch's step begins
- [ ] Asks via `AskUserQuestion` before updating the story file
- [ ] Appends to `docs/tech-debt-register.md` only when the user picks "Close and log advisory deviations as tech debt", as rows of `/tech-debt`'s register table with an `Added` date — never as free bullets
- [ ] Presents the complete report (criteria, traceability, test evidence, deviations, scope) before asking
diff --git a/CCGS Skill Testing Framework/skills/readiness/story-readiness.md b/studio-tests/skills/readiness/story-readiness.md
similarity index 81%
rename from CCGS Skill Testing Framework/skills/readiness/story-readiness.md
rename to studio-tests/skills/readiness/story-readiness.md
index 3fc10d01..6fbc2858 100644
--- a/CCGS Skill Testing Framework/skills/readiness/story-readiness.md
+++ b/studio-tests/skills/readiness/story-readiness.md
@@ -35,6 +35,15 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Fully ready story
@@ -253,6 +262,69 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+### Case 8: A Deprecated or Superseded ADR blocks, and the fix points at the story's ADR field
+
+**Fixture:**
+- `project.yaml` sets `modes.workflow: standard` (a referenced dead ADR blocks at
+ every tier; `standard` shows it is not left to the advisory rule)
+- Story A `production/epics/core/story-save-format.md` references `ADR-0006`;
+ `docs/architecture/adr-0006-save-format.md` has `## Status` Superseded by ADR-0009
+- Story B `production/epics/core/story-input-map.md` references `ADR-0008`;
+ `docs/architecture/adr-0008-input-map.md` has `## Status` Deprecated
+- Both stories are otherwise complete
+
+**Input:** `/story-readiness production/epics/core/story-save-format.md`, then
+`/story-readiness production/epics/core/story-input-map.md`
+
+**Expected behavior:**
+1. The status scan reads `Superseded by ADR-0009` for A and `Deprecated` for B
+2. Both verdicts are BLOCKED, listing the ADR under Blockers: the decision no longer
+ stands
+3. A's `Fix:` reads `BLOCKED: ADR-0006 is Superseded by ADR-0009 — point the story
+ at ADR-0009 (edit its ADR field — /create-stories never rewrites an existing
+ story).` B's names `ADR-0008` with the status `Deprecated`
+4. Nothing is written: the skill only tells the user to edit the story's ADR field
+
+**Assertions:**
+- [ ] Both verdicts are BLOCKED, not NEEDS WORK or READY, at `standard`
+- [ ] A's `Fix:` names the successor ADR-0009 and says to edit the story's ADR field
+- [ ] The `Fix:` states that `/create-stories` never rewrites an existing story, and does not suggest re-running it to refresh this story
+- [ ] B's blocker names ADR-0008 and its `Deprecated` status
+- [ ] No file is written or edited
+
+---
+
+### Case 9: A deprecated or superseded TR-ID needs work, quoted or not
+
+**Fixture:**
+- `project.yaml` sets `modes.workflow: full`
+- `docs/architecture/tr-registry.yaml` has `TR-light-001` with `status: active`,
+ `TR-light-004` with `status: deprecated`, `TR-light-005` with
+ `status: "superseded-by: TR-light-009"` (quoted) and `TR-light-006` with
+ `status: superseded-by: TR-light-010` (unquoted)
+- Stories S1, S4, S5 and S6 each reference one of `TR-light-001`, `TR-light-004`,
+ `TR-light-005` and `TR-light-006`; every other checklist item passes (ADR
+ Accepted, current manifest version, criteria, estimate)
+
+**Input:** `/story-readiness production/epics/core/story-S4.md`, then S5, then S6, then S1
+
+**Expected behavior:**
+1. The registry lookup finds each id and reads its status
+2. S4, S5 and S6 are NEEDS WORK, not BLOCKED and not READY: "the requirement was
+ removed or replaced"
+3. Each `Fix:` says to update the story to reference the current requirement ID, or
+ remove the reference if it no longer applies
+4. S1 passes the TR-ID item and is READY
+
+**Assertions:**
+- [ ] `deprecated` yields NEEDS WORK with the update-or-remove `Fix:`
+- [ ] The quoted `"superseded-by: TR-light-009"` and the unquoted `superseded-by: TR-light-010` are treated the same way: both NEEDS WORK
+- [ ] Neither a deprecated nor a superseded TR-ID passes as "valid and active"
+- [ ] The verdict is NEEDS WORK, never BLOCKED — nothing outside the story is required
+- [ ] S1 (`status: active`) passes the item, so the deprecated and superseded results come from the registry status and not from the lookup itself
+
+---
+
## Protocol Compliance
- [ ] Does NOT use Write or Edit tools; any help filling gaps is drafted in conversation only
@@ -265,7 +337,8 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
## Coverage Notes
-- A TR-ID missing from the registry follows the same NEEDS WORK pattern as Case 4.
+- A TR-ID missing from the registry follows the same NEEDS WORK pattern as Case 4;
+ a deprecated or superseded TR-ID is Case 9.
- The zero-story scope is Case 7a; the `sprint` / `all` aggregate output over real
stories and the Must Have sprint escalation warning are not tested here.
- The no-argument path (scope chosen via `AskUserQuestion`) is not tested.
diff --git a/CCGS Skill Testing Framework/skills/review/architecture-review.md b/studio-tests/skills/review/architecture-review.md
similarity index 92%
rename from CCGS Skill Testing Framework/skills/review/architecture-review.md
rename to studio-tests/skills/review/architecture-review.md
index 023aec4c..b78b663d 100644
--- a/CCGS Skill Testing Framework/skills/review/architecture-review.md
+++ b/studio-tests/skills/review/architecture-review.md
@@ -43,6 +43,15 @@ this skill.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — every requirement covered by an Accepted ADR
@@ -70,7 +79,7 @@ this skill.
targeted Greps rather than whole files, and reports
"Loaded [N] GDDs, [M] ADRs, engine: Godot 4.6"
3. Skill extracts TR-IDs (reusing any existing `tr-registry.yaml` IDs) and builds the matrix
-4. Skill runs `bash .claude/scripts/adr-dep-graph.sh` and prints the recommended implementation order
+4. Skill runs `bash .claude/scripts/adr-dep-graph.sh` and prints the recommended implementation order from its `ORDER:` row
5. Skill runs the engine audit and consults `godot-specialist`
6. Report ends with `### Verdict: PASS`
7. Phase 8 asks what to write; Phase 9 offers `/gate-check pre-production`
@@ -78,9 +87,10 @@ this skill.
**Assertions:**
- [ ] Output reports "Loaded [N] GDDs, [M] ADRs, engine: [name + version]"
- [ ] A Traceability Matrix lists each TR-ID with its GDD, system, requirement, ADR coverage and status; every row is ✅
-- [ ] The ADR dependency order comes from `adr-dep-graph.sh`, not hand-tracing, and puts `adr-0001` first; `NO_DEPS_SECTION` is empty, so the acyclic result is a clean graph rather than a structural gap
+- [ ] The ADR dependency order is `adr-dep-graph.sh`'s `ORDER:` row, not hand-tracing, and puts `adr-0001` first; `NO_DEPS_SECTION` and `UNFILLED_DEPS` are empty, so the acyclic result is a clean graph rather than a structural gap
- [ ] Verdict is PASS only because all requirements are covered by **Accepted** ADRs, no conflicts exist, and engine references agree
-- [ ] The report includes the `review-receipts.sh hash` lines for the ADRs and GDDs reviewed
+- [ ] The report header has `Mode: full` and `Workflow: full` lines
+- [ ] The report includes the `review-receipts.sh hash` lines for every review input (ADRs, GDDs, TR registry, engine reference, `project.yaml`, the skill's own files), taken after the TR registry is written
- [ ] No file is written before the Phase 8 `AskUserQuestion` (`[A]` all three files / `[B]` report only at `docs/architecture/architecture-review-[date].md` / `[C]` nothing yet)
- [ ] The closing widget offers `/gate-check pre-production`, because every pre-gate checklist item is ✅
@@ -199,8 +209,9 @@ this skill.
individually fixture-tested; Cases 1–5 exercise the default `full` mode.
- Phase 5b (GDD revision flags written to `systems-index.md` as `Needs Revision`)
is not tested; it needs a HIGH RISK engine finding that contradicts a GDD.
-- The freshness receipt paths (everything `UNCHANGED`, some `CHANGED`/`NEW`,
- `UNRESOLVED`) are not fixture-tested.
+- The freshness receipt paths (everything `UNCHANGED` with a report that does
+ or does not cover the run, some `CHANGED`/`NEW`, `GONE`, `UNRESOLVED`) are not
+ fixture-tested.
- The `standard` tier's reduced scope (architecture doc + critical ADRs only) is
not tested.
- The default `minimal` tier (a `project.yaml` with no `modes` block), where the skill's scope table
diff --git a/CCGS Skill Testing Framework/skills/review/design-review.md b/studio-tests/skills/review/design-review.md
similarity index 95%
rename from CCGS Skill Testing Framework/skills/review/design-review.md
rename to studio-tests/skills/review/design-review.md
index 55878025..c11be69b 100644
--- a/CCGS Skill Testing Framework/skills/review/design-review.md
+++ b/studio-tests/skills/review/design-review.md
@@ -33,6 +33,15 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Complete GDD, all 8 sections present
@@ -67,7 +76,7 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
- [ ] Output includes "Required Before Implementation", "Recommended Revisions" and "Scope Signal" sections, and "Re-review: No — first review"
- [ ] Output ends with `### Verdict:` APPROVED when all REQUIRED sections are present and no blocking issue is found
- [ ] No file is written before the tracking-records widget, and only the options the user selects are written
-- [ ] If the review-log option is selected, the appended entry includes the `review-receipts.sh hash` output for the document
+- [ ] If the review-log option is selected, the appended entry has a `Review mode:` line and the `review-receipts.sh hash` output for the document, the skill file and the related GDDs it read
---
@@ -230,7 +239,8 @@ runs and the last assertion below would test nothing.)
- Cross-system consistency across many GDDs is covered by the `/review-all-gdds`
spec; this spec checks only one document's dependency references.
- The freshness receipt paths (byte-identical re-review offering the prior
- verdict; registry-only change) are not fixture-tested here.
+ verdict; a shallower logged review when a deeper one is asked for;
+ cross-document change only) are not fixture-tested here.
- The entity-registry grep path (registry lists this system) is not tested; the
fixtures above use the fallback of reading the GDDs named in Dependencies.
- The `minimal` tier (no GDD expected; standard sections checked advisorily) is
diff --git a/CCGS Skill Testing Framework/skills/review/review-all-gdds.md b/studio-tests/skills/review/review-all-gdds.md
similarity index 62%
rename from CCGS Skill Testing Framework/skills/review/review-all-gdds.md
rename to studio-tests/skills/review/review-all-gdds.md
index c38dfd63..b3b76e28 100644
--- a/CCGS Skill Testing Framework/skills/review/review-all-gdds.md
+++ b/studio-tests/skills/review/review-all-gdds.md
@@ -14,6 +14,11 @@ multi-system scenarios. It produces a PASS / NOT ASSESSED / CONCERNS / FAIL
verdict, and writes `design/gdd/gdd-cross-review-[YYYY-MM-DD].md` and
systems-index "Needs Revision" statuses only after the user approves.
+Each phase is a `references/N-*.md` file the skill reads before doing that phase and
+again if the conversation is compacted during it. The argument picks the focus:
+`full` (default), `consistency`, `design-theory`, or `since-last-review`, which
+takes its scope from `.claude/scripts/review-scope.sh`.
+
It is invoked after individual GDDs are approved and before architecture work.
It spawns no director gate agents. At `workflow: minimal` it does not apply (no
GDDs), so every fixture below sets `modes.workflow: full`.
@@ -41,6 +46,15 @@ review mode. It IS the holistic review; its only agents are the two
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Clean GDD set with no conflicts
@@ -222,8 +236,99 @@ review mode. It IS the holistic review; its only agents are the two
---
+### Case 7: Phase files are read on demand, and again after a compaction
+
+**Fixture:**
+- `project.yaml` sets `modes.workflow: full`
+- `design/gdd/` holds the Case 1 set: concept, pillars, systems index and three consistent system GDDs
+- The skill folder holds `references/1-load.md` through `references/7-handoff.md`
+- The conversation is compacted while Phase 4 (scenario walkthrough) is under way, then the run continues
+
+**Input:** `/review-all-gdds`
+
+**Expected behavior:**
+1. SKILL.md holds no phase steps; before Phase 1 the run reads `references/1-load.md`, and it does not scan `## Summary` lines or load GDD sections before that read
+2. Phases 2 and 3 are spawned in parallel as `game-designer` sub-agents, and the main run reads `references/2-consistency.md` and `references/3-design-holism.md` before it passes each sub-agent its checklist (2a–2f, 3a–3g)
+3. `references/4-scenarios.md`, `5-report.md`, `6-write.md` and `7-handoff.md` are each read before that phase's work: no scenario before the first, no verdict or report before `5-report.md`, no write question before `6-write.md`, no closing widget before `7-handoff.md`
+4. After the compaction the run reads `references/4-scenarios.md` again before it continues the walkthrough, as the skill says: "Read it again if the conversation was compacted or resumed during this phase."
+
+**Assertions:**
+- [ ] The transcript shows a read of each of the seven `references/N-*.md` files, each before that phase's work begins
+- [ ] No phase work (summary scan, checklist hand-off, scenarios, verdict, write question, closing widget) happens before its phase file is read
+- [ ] After the compaction, `references/4-scenarios.md` is read again before the walkthrough resumes
+- [ ] The Phase 2 and Phase 3 sub-agents are still spawned in parallel with the checklist items from the phase files
+
+---
+
+### Case 8: `since-last-review` — scope comes from the script, not from reasoning over git
+
+**Fixture:**
+- `project.yaml` sets `modes.workflow: full`
+- `design/gdd/` holds `game-pillars.md`, `systems-index.md`, a committed `gdd-cross-review-2025-01-15.md`, and four system GDDs: `combat.md`, `inventory.md`, `crafting.md`, `status-effects.md`
+- Only `combat.md` has been modified since that report was committed; its `## Dependencies` section names `inventory.md`
+- `crafting.md` and `status-effects.md` are unchanged and no changed GDD names them
+- `.claude/scripts/review-scope.sh` prints `PRIOR_REVIEW: design/gdd/gdd-cross-review-2025-01-15.md`, `CHANGED:` with `design/gdd/combat.md`, and a `DEPS` line `combat.md -> inventory.md`
+
+**Input:** `/review-all-gdds since-last-review`
+
+**Expected behavior:**
+1. After the manifest, the run executes `bash .claude/scripts/review-scope.sh` rather than working out the changed set from `git log` or `git diff` itself
+2. Scope is the `CHANGED` set plus the GDDs named on the `DEPS` lines: `combat.md` and `inventory.md`; the run shows the user which GDDs are in scope before any full read
+3. Only those two GDDs get the Phase 1c section load; `crafting.md` and `status-effects.md` are not loaded, and no second dependency-expansion pass is made
+4. The report states `GDDs reviewed: 2 of 4 present`
+5. Phases 2 and 3 run over the two in-scope GDDs as usual
+
+**Assertions:**
+- [ ] `bash .claude/scripts/review-scope.sh` is run, and its `CHANGED` and `DEPS` lists are used as the scope as printed
+- [ ] The run does not derive the changed set with its own git history search
+- [ ] `inventory.md` is in scope although it did not change, because `combat.md` declares it as a dependency
+- [ ] The unchanged, undeclared GDDs are not loaded and are not counted as reviewed: the report says `GDDs reviewed: 2 of 4 present`
+- [ ] The scope is shown to the user before the full section reads
+
+**Case 8b — no prior review:** the same fixture with no `gdd-cross-review-*.md` file. The script prints `PRIOR_REVIEW: NONE (full review required)`.
+
+**Assertions (8b):**
+- [ ] The run falls back to `full` mode and says a full review is required because no prior review exists
+- [ ] All four system GDDs are loaded and reviewed (`GDDs reviewed: 4 of 4 present`)
+
+---
+
+### Case 9: Focus modes — one pass runs, and the report says which did not
+
+**Fixture:**
+- `project.yaml` sets `modes.workflow: full`
+- `design/gdd/` holds the Case 1 set: concept, pillars, systems index and three consistent system GDDs, with no conflicts and nothing a design-theory check would warn on
+
+**Case 9a — `/review-all-gdds consistency`**
+
+**Expected behavior:**
+1. Phase 1 loads everything as usual; only the Phase 2 (Cross-GDD Consistency) `game-designer` sub-agent is spawned, with checklist 2a–2f
+2. No Phase 3 (Game Design Holism) sub-agent is spawned
+3. The report's `Focus:` line reads "consistency only — design theory not run", and the session extract's `Phases not run:` line names design theory, rather than reporting it as clean
+4. The verdict is for the pass that ran, labelled: `PASS (consistency only — design theory not run)` — not NOT ASSESSED, since the user asked for one pass
+5. The closing widget offers neither `/gate-check` nor `/create-architecture`: a one-pass review is not the full review either needs
+
+**Assertions (9a):**
+- [ ] Exactly one `Agent` spawn: the Phase 2 consistency sub-agent
+- [ ] The design-theory phase is named as not run — never omitted silently, never reported as having found nothing
+- [ ] The verdict is `PASS (consistency only — design theory not run)`: labelled, never an unqualified PASS, and not NOT ASSESSED
+- [ ] Neither `/gate-check` nor `/create-architecture` is offered
+- [ ] The session extract's `Phases not run:` line names design theory
+
+**Case 9b — `/review-all-gdds design-theory`**
+
+**Expected behavior:** the mirror of 9a. Only the Phase 3 sub-agent is spawned (checklist 3a–3g), Phase 4 and the report still follow, and the consistency pass is named as not run.
+
+**Assertions (9b):**
+- [ ] Exactly one `Agent` spawn: the Phase 3 design-theory sub-agent
+- [ ] The `Focus:` line names consistency as not run, the verdict is `PASS (design theory only — consistency not run)`, and the session extract's `Phases not run:` line names consistency
+- [ ] Neither `/gate-check` nor `/create-architecture` is offered
+
+---
+
## Protocol Compliance
+- [ ] Reads each phase's `references/N-*.md` file before doing that phase, and again after a compaction or resume during it
- [ ] Phase 2 (Consistency) and Phase 3 (Design Theory) spawned in parallel — not sequentially
- [ ] The full analysis is shown before any write is requested
- [ ] Does NOT write the report or update `systems-index.md` without `AskUserQuestion` approval
@@ -243,5 +348,6 @@ review mode. It IS the holistic review; its only agents are the two
- Case 6 covers the fewer-than-two-readable-GDDs trigger, through a
present-but-empty GDD. The NOT ASSESSED triggers for undefined pillars and for
a sub-agent that returns no report are not fixture-tested.
-- The `since-last-review` mode (`.claude/scripts/review-scope.sh`) and the
- `consistency` / `design-theory` focus modes are not tested here.
+- Case 8 covers `since-last-review` with and without a prior review; a prior
+ review whose changed GDDs name no dependencies is not tested separately.
+ Case 9 covers the `consistency` and `design-theory` focus modes.
diff --git a/CCGS Skill Testing Framework/skills/sprint/changelog.md b/studio-tests/skills/sprint/changelog.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/sprint/changelog.md
rename to studio-tests/skills/sprint/changelog.md
index c39b57bd..1fa5b7b1 100644
--- a/CCGS Skill Testing Framework/skills/sprint/changelog.md
+++ b/studio-tests/skills/sprint/changelog.md
@@ -39,6 +39,15 @@ None. Changelog generation is a fast compilation task; no gates are invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Multiple sprints since last release tag
diff --git a/CCGS Skill Testing Framework/skills/sprint/milestone-review.md b/studio-tests/skills/sprint/milestone-review.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/sprint/milestone-review.md
rename to studio-tests/skills/sprint/milestone-review.md
index 41f76dfd..b507400e 100644
--- a/CCGS Skill Testing Framework/skills/sprint/milestone-review.md
+++ b/studio-tests/skills/sprint/milestone-review.md
@@ -47,6 +47,15 @@ recommends GO.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Nearly complete milestone with one deferred feature
diff --git a/CCGS Skill Testing Framework/skills/sprint/patch-notes.md b/studio-tests/skills/sprint/patch-notes.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/sprint/patch-notes.md
rename to studio-tests/skills/sprint/patch-notes.md
index 7a4e8182..9ce3afc5 100644
--- a/CCGS Skill Testing Framework/skills/sprint/patch-notes.md
+++ b/studio-tests/skills/sprint/patch-notes.md
@@ -41,6 +41,15 @@ None. Patch notes generation is a fast compilation task; no gates are invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Changelog filtered to player-facing entries
diff --git a/CCGS Skill Testing Framework/skills/sprint/retrospective.md b/studio-tests/skills/sprint/retrospective.md
similarity index 94%
rename from CCGS Skill Testing Framework/skills/sprint/retrospective.md
rename to studio-tests/skills/sprint/retrospective.md
index 83dbcfb5..57d6d15f 100644
--- a/CCGS Skill Testing Framework/skills/sprint/retrospective.md
+++ b/studio-tests/skills/sprint/retrospective.md
@@ -43,6 +43,15 @@ None. Retrospectives are team self-reflection documents; no gates are invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Sprint with mixed outcomes
@@ -215,6 +224,8 @@ None. Retrospectives are team self-reflection documents; no gates are invoked.
5. Skill asks "May I write this to
`production/retrospectives/retro-sprint-001-[today's date].md`?"; user
approves; verdict COMPLETE
+6. Phase 6 skips the start-sprint-planning question: the skill points to the
+ retrospective file and says its action items go into the brief's build order
**Assertions:**
- [ ] The no-data prompt offers [C] Look back over the closed stories alongside [A] and [B]
@@ -222,6 +233,7 @@ None. Retrospectives are team self-reflection documents; no gates are invoked.
- [ ] The `In Progress` story is not reported as completed work
- [ ] The sections that need sprint data read `NOT ASSESSED — NO DATA` rather than invented figures
- [ ] "May I write" appears before the write, and the verdict is COMPLETE after it
+- [ ] After the write there is no offer to start `/sprint-plan new` — the skill names the retrospective file and says the action items go into the brief's build order
---
@@ -234,6 +246,7 @@ None. Retrospectives are team self-reflection documents; no gates are invoked.
- [ ] No director gates are invoked
- [ ] Verdict is COMPLETE after a write, BLOCKED when the user stops at the no-data prompt or declines the write
- [ ] Checks prior retrospectives for unresolved action items
+- [ ] Offers `/sprint-plan new` at the end only when the workflow has sprints; at `minimal` it points the action items at the brief's build order instead
---
diff --git a/CCGS Skill Testing Framework/skills/sprint/sprint-plan.md b/studio-tests/skills/sprint/sprint-plan.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/sprint/sprint-plan.md
rename to studio-tests/skills/sprint/sprint-plan.md
index aa5c0f16..976d51f3 100644
--- a/CCGS Skill Testing Framework/skills/sprint/sprint-plan.md
+++ b/studio-tests/skills/sprint/sprint-plan.md
@@ -47,6 +47,15 @@ REALISTIC.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Ready backlog generates sprint
diff --git a/CCGS Skill Testing Framework/skills/sprint/sprint-status.md b/studio-tests/skills/sprint/sprint-status.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/sprint/sprint-status.md
rename to studio-tests/skills/sprint/sprint-status.md
index 2de321fd..d27efb95 100644
--- a/CCGS Skill Testing Framework/skills/sprint/sprint-status.md
+++ b/studio-tests/skills/sprint/sprint-status.md
@@ -39,6 +39,15 @@ None. `/sprint-status` is a read-only reporting skill; no gates are invoked.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Mixed sprint, At Risk with a blocked Must Have
diff --git a/CCGS Skill Testing Framework/skills/team/team-audio.md b/studio-tests/skills/team/team-audio.md
similarity index 90%
rename from CCGS Skill Testing Framework/skills/team/team-audio.md
rename to studio-tests/skills/team/team-audio.md
index d8b55493..6a64efe5 100644
--- a/CCGS Skill Testing Framework/skills/team/team-audio.md
+++ b/studio-tests/skills/team/team-audio.md
@@ -44,6 +44,15 @@ Skips the engine specialist when no engine is configured and records
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All steps complete, audio design document saved
@@ -198,6 +207,34 @@ Skips the engine specialist when no engine is configured and records
---
+### Case 6: `review_mode` gates nothing — the same request at full, lean and solo
+
+**Fixture:**
+- `project.yaml`: `modes.review_mode: lean` (pinned: the runs below override or keep
+ it), `team.size: studio` (pinned: so every step and agent in the pipeline is active)
+- `engine.name` is Godot; `design/gdd/combat.md` and `design/audio/sound-bible.md`
+ exist; no accessibility gaps in the event list
+- Run A: `/team-audio combat --review full`. Run B: `/team-audio combat` (resolves
+ `lean`). Run C: `/team-audio combat --review solo`
+
+**Expected behavior:**
+1. All three runs open with the same active-set line for `team.size: studio`
+2. All three run the same four steps with the same agents: audio-director, then
+ sound-designer + accessibility-specialist, then technical-artist + `godot-specialist`,
+ then gameplay-programmer. These are team members working the steps, not director gates
+3. No run spawns a CD-, TD-, PR- or AD-PHASE-GATE at any step: "no phase below spawns
+ CD-, TD-, PR- or AD-PHASE-GATE, at any `review_mode`"
+4. The `AskUserQuestion` at each step transition, the single ask for the audio design
+ document and the verdict are the same in all three
+
+**Assertions:**
+- [ ] No director gate (CD-, TD-, PR- or AD-PHASE-GATE) is spawned in Run A (`full`), Run B (`lean`) or Run C (`solo`)
+- [ ] The active set, the agents spawned per step and the number of step-transition asks are identical across the three runs
+- [ ] `--review full` does not add a review step and `--review solo` does not remove one: only `team.size` changes who is spawned
+- [ ] Each run writes `design/audio/audio-combat.md` only after its own ask and ends COMPLETE
+
+---
+
## Protocol Compliance
- [ ] At the default `team.size: individual`, the run opens with `Active set (team.size: individual): sound-designer.` and a `Not spawned this run:` line naming audio-director, accessibility-specialist, technical-artist, the engine specialist and gameplay-programmer, consulted through sound-designer — before any agent is spawned
diff --git a/CCGS Skill Testing Framework/skills/team/team-combat.md b/studio-tests/skills/team/team-combat.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/team/team-combat.md
rename to studio-tests/skills/team/team-combat.md
index 8599e109..887b63d9 100644
--- a/CCGS Skill Testing Framework/skills/team/team-combat.md
+++ b/studio-tests/skills/team/team-combat.md
@@ -38,6 +38,15 @@ verdict COMPLETE / NEEDS WORK / BLOCKED and handoffs to `/code-review`,
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All agents succeed, full pipeline runs to completion
diff --git a/CCGS Skill Testing Framework/skills/team/team-level.md b/studio-tests/skills/team/team-level.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/team/team-level.md
rename to studio-tests/skills/team/team-level.md
index b97099c1..38e66190 100644
--- a/CCGS Skill Testing Framework/skills/team/team-level.md
+++ b/studio-tests/skills/team/team-level.md
@@ -40,6 +40,15 @@ summary report with verdict COMPLETE / BLOCKED and handoffs to `/design-review`,
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All team members produce outputs, document compiled and saved
diff --git a/CCGS Skill Testing Framework/skills/team/team-live-ops.md b/studio-tests/skills/team/team-live-ops.md
similarity index 86%
rename from CCGS Skill Testing Framework/skills/team/team-live-ops.md
rename to studio-tests/skills/team/team-live-ops.md
index 8aa2bc44..5c37143b 100644
--- a/CCGS Skill Testing Framework/skills/team/team-live-ops.md
+++ b/studio-tests/skills/team/team-live-ops.md
@@ -5,7 +5,7 @@
Orchestrates the live-ops team through a 7-phase planning pipeline to produce a
season or event plan. Coordinates live-ops-designer, economy-designer,
analytics-engineer, community-manager, narrative-director, and writer. Phase 0
-resolves `review_mode`, `automation` and `team.size` and the skill announces the
+resolves `review_mode`, `automation`, `team.size` and `workflow` and the skill announces the
active set before Phase 1 — `individual` spawns live-ops-designer + economy-designer,
`small` adds analytics-engineer + community-manager, `studio` adds writer +
narrative-director. Phases 3 and 4 (economy design and analytics) run
@@ -36,12 +36,21 @@ requiring user approval before handoff to production.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All 7 phases complete, season plan produced
**Fixture:**
-- Resolved config block: `team.size: studio`, `automation: collaborative`
+- Resolved config block: `team.size: studio`, `automation: collaborative`, `workflow: standard` (pinned: unset resolves to minimal, whose next steps use the brief's build order instead of `/sprint-plan`; Case 6 covers that)
- `design/live-ops/economy-rules.md` exists with current economy configuration
- `design/live-ops/ethics-policy.md` exists with the project ethics policy
- Game concept document exists at its standard path
@@ -171,6 +180,29 @@ requiring user approval before handoff to production.
---
+### Case 6: Workflow Minimal — The sprint step becomes the brief's build order
+
+**Fixture:**
+- Resolved config block: `workflow: minimal` (from `modes.rigor: minimal`), `team.size: studio` (pinned so the full pipeline runs), `automation: collaborative`
+- `design/game-brief.md` exists with a build order; no `production/sprints/` folder
+- `design/live-ops/economy-rules.md` and `design/live-ops/ethics-policy.md` exist, and the economy design raises no ethics flag
+
+**Input:** `/team-live-ops "Season 5: Harvest Moon"`
+
+**Expected behavior:**
+1. Phase 0 resolves `workflow` along with `review_mode`, `automation` and `team.size`
+2. The pipeline runs as in Case 1 and ends with Verdict: COMPLETE after the user approves the season plan
+3. Next Steps: `/design-review` on the season design document; instead of `/sprint-plan`, add the season's content work to the brief's build order, because `minimal` has no sprints; `/team-release` when the content is ready
+
+**Assertions:**
+- [ ] `workflow` is among the keys Phase 0 resolves
+- [ ] The scheduling step says to add the season's content work to the brief's build order
+- [ ] `/sprint-plan` is not recommended
+- [ ] `/design-review` and `/team-release` are still listed
+- [ ] The rest of the run (active-set line, parallel Phases 3 and 4, ethics review, "May I write" before the `design/live-ops/seasons/` documents) is unchanged by `workflow`
+
+---
+
## Protocol Compliance
- [ ] At the default `team.size: individual`, the run opens with an `Active set (team.size: individual): live-ops-designer + economy-designer` line and a `Not spawned this run:` line naming analytics-engineer, community-manager, narrative-director and writer — before any agent is spawned
@@ -182,7 +214,7 @@ requiring user approval before handoff to production.
- [ ] Error recovery: any BLOCKED agent is surfaced immediately with AskUserQuestion options (skip / retry / stop)
- [ ] Partial reports are produced if any phase blocks — work is never discarded
- [ ] Verdict: COMPLETE only after user approves the consolidated season plan; BLOCKED if any unresolved ethics violation exists
-- [ ] Next steps after a COMPLETE plan include `/design-review`, `/sprint-plan`, and `/team-release`; a run that ends BLOCKED on an ethics flag names the revision and re-run instead
+- [ ] Next steps after a COMPLETE plan include `/design-review`, `/sprint-plan` (at `workflow: minimal`, the brief's build order in its place), and `/team-release`; a run that ends BLOCKED on an ethics flag names the revision and re-run instead
---
diff --git a/CCGS Skill Testing Framework/skills/team/team-narrative.md b/studio-tests/skills/team/team-narrative.md
similarity index 88%
rename from CCGS Skill Testing Framework/skills/team/team-narrative.md
rename to studio-tests/skills/team/team-narrative.md
index 02773dee..38b5dfec 100644
--- a/CCGS Skill Testing Framework/skills/team/team-narrative.md
+++ b/studio-tests/skills/team/team-narrative.md
@@ -41,6 +41,15 @@ dependency is unresolved.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All five phases complete, narrative doc delivered
@@ -201,6 +210,37 @@ dependency is unresolved.
---
+### Case 6: `review_mode` gates nothing but the `small` roster — ND-CONSISTENCY runs in every mode
+
+**Fixture:**
+- `project.yaml`: `team.size: studio` for Runs A–C, `team.size: small` for Runs D–F
+ (pinned: the roster is the one thing `review_mode` still touches); `modes.review_mode`
+ is not set, so each run's `--review` value decides
+- `design/gdd/faction-intro.md`, character voice profiles and existing lore exist
+- Runs A and D: `/team-narrative faction introduction cutscene --review full`.
+ Runs B and E: `--review lean`. Runs C and F: `--review solo`
+
+**Expected behavior:**
+1. Runs A–C (`studio`): all six agents are active whatever the review mode, so the
+ active-set line, the phases and the agents spawned are identical
+2. Runs D–F (`small`): narrative-director + writer are active in all three. Run D
+ (`full`) adds localization-lead and world-builder; in Runs E and F they are
+ consulted through the writer and named in the `Not spawned this run:` line
+3. Phase 4 spawns `narrative-director` with ND-CONSISTENCY in all six runs: "This
+ phase runs in every review mode — it is this pipeline's own review, not an optional
+ director gate"
+4. No run spawns a CD-, TD-, PR- or AD-PHASE-GATE at any phase
+
+**Assertions:**
+- [ ] ND-CONSISTENCY is spawned in Phase 4 in every one of the six runs; `lean` and `solo` do not skip it
+- [ ] No director gate (CD-, TD-, PR- or AD-PHASE-GATE) is spawned in any run
+- [ ] Runs A–C show the same active set, phases and asks
+- [ ] At `small`, localization-lead and world-builder are spawned only in Run D (`full`) and named under `Not spawned this run:` in Runs E and F
+- [ ] At `small` in `lean` and `solo`, the lore and i18n work is still done, through the writer, and the output says so
+- [ ] The APPROVE / CONCERNS / REJECT answer of ND-CONSISTENCY decides whether Phase 5 starts in every mode
+
+---
+
## Protocol Compliance
- [ ] At the default `team.size: individual`, the run opens with `Active set (team.size: individual): writer.` and a `Not spawned this run:` line naming narrative-director, world-builder, art-director, level-designer and localization-lead, consulted through writer — before any agent is spawned
@@ -229,5 +269,5 @@ dependency is unresolved.
given a case; Case 4 covers only a concern the localization-lead returns as BLOCKED.
- The writer's "all lines under 120 characters" and "string keys not raw strings" checks
in Phase 5 are covered implicitly by Case 4's localization compliance scenario.
-- The `small` active set (review_mode-dependent localization-lead and world-builder) is not
- given its own case.
+- The `small` active set (review_mode-dependent localization-lead and world-builder) is
+ checked at the roster level in Case 6; its phase-by-phase run is not walked.
diff --git a/CCGS Skill Testing Framework/skills/team/team-polish.md b/studio-tests/skills/team/team-polish.md
similarity index 91%
rename from CCGS Skill Testing Framework/skills/team/team-polish.md
rename to studio-tests/skills/team/team-polish.md
index 8553e7ed..d7148340 100644
--- a/CCGS Skill Testing Framework/skills/team/team-polish.md
+++ b/studio-tests/skills/team/team-polish.md
@@ -11,7 +11,7 @@ tool; performance-analyst writes no game code) → visual polish
with Phase 2) → hardening (qa-tester) → sign-off (orchestrator collects all results
and issues READY FOR RELEASE, NOT ASSESSED or NEEDS MORE WORK — NOT ASSESSED when a
budget is uncommitted or a phase did not run). Phase 0 resolves `review_mode`,
-`automation` and `team.size` and the skill announces the active set before Phase 1
+`automation`, `team.size` and `workflow` and the skill announces the active set before Phase 1
— the default `individual` spawns performance-analyst + technical-artist only, so
no programmer is active and the report names the optimisation list as handed to
`/dev-story`; `small` adds sound-designer, qa-tester and engine-programmer (the full
@@ -48,6 +48,15 @@ conditionally only when Phase 1 identifies engine-level root causes.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Full pipeline completes, READY FOR RELEASE verdict
@@ -99,7 +108,7 @@ conditionally only when Phase 1 identifies engine-level root causes.
### Case 2: Performance Blocker — Frame budget violation cannot be fully resolved
**Fixture:**
-- Resolved config block: `team.size: small`, `automation: collaborative`
+- Resolved config block: `team.size: small`, `automation: collaborative`, `workflow: standard` (pinned: unset resolves to minimal, whose next step adds the issue to the brief's build order instead of `/sprint-plan update`; Case 8 covers that)
- Feature being polished: `particle-storm` VFX system
- Phase 1 identifies a frame budget violation: particle-storm costs 12ms on target hardware (budget is 6ms for this system)
- Phase 1's optimisation list assigns the particle work to technical-artist and an engine-level particle-update hot path to engine-programmer; after both are applied the cost is 9ms — still over the 6ms budget
@@ -184,7 +193,7 @@ conditionally only when Phase 1 identifies engine-level root causes.
### Case 5: Regression Found — Polish change broke an existing feature
**Fixture:**
-- Resolved config block: `team.size: small`, `automation: collaborative`
+- Resolved config block: `team.size: small`, `automation: collaborative`, `workflow: standard` (pinned for the same reason as Case 2)
- Feature being polished: `inventory-ui`
- Phases 1–4 complete successfully; performance and polish changes are applied
- Phase 5: qa-tester runs regression tests and finds that a shader optimization applied in Phase 3 broke the item highlight glow effect on hover — an existing feature that was working before the polish pass
@@ -260,6 +269,30 @@ conditionally only when Phase 1 identifies engine-level root causes.
---
+### Case 8: Workflow Minimal — NEEDS MORE WORK goes to the brief's build order
+
+**Fixture:**
+- Resolved config block: `workflow: minimal` (from `modes.rigor: minimal`), `team.size: small` (pinned so the full pipeline runs), `automation: collaborative`
+- `design/game-brief.md` exists with a build order; no `production/sprints/` folder
+- Budgets committed in `project.yaml` (as in Case 1)
+- Feature being polished: `particle-storm`, set up as in Case 2: after optimisation the cost is 9ms against a 6ms budget
+
+**Input:** `/team-polish particle-storm`
+
+**Expected behavior:**
+1. Phase 0 resolves `workflow` along with `review_mode`, `automation` and `team.size`
+2. The run proceeds as in Case 2 to Phase 6 and the verdict NEEDS MORE WORK, with the 3ms gap listed
+3. Next Steps: add the remaining issue to the brief's build order, because `minimal` has no sprints, then re-run `/team-polish` after the fix
+
+**Assertions:**
+- [ ] `workflow` is among the keys Phase 0 resolves
+- [ ] The scheduling step says to add the remaining issue to the brief's build order
+- [ ] `/sprint-plan update` is not recommended
+- [ ] A `/team-polish` re-run after the fix is still named
+- [ ] The verdict and the remaining-issue list are the same as in Case 2
+
+---
+
## Protocol Compliance
- [ ] At the default `team.size: individual`, the run opens with an `Active set (team.size: individual): performance-analyst + technical-artist` line and a `Not spawned this run:` line naming sound-designer, qa-tester, engine-programmer and tools-programmer — before any agent is spawned
@@ -277,7 +310,7 @@ conditionally only when Phase 1 identifies engine-level root causes.
- [ ] Verdict is exactly one of READY FOR RELEASE, NOT ASSESSED or NEEDS MORE WORK — a known problem is NEEDS MORE WORK even when something else went unchecked, and READY FOR RELEASE is reachable only when every measured metric had a committed budget and every phase ran
- [ ] At `team.size: individual`, sound-designer's audio polish and qa-tester's hardening are named as not run, so the verdict is NOT ASSESSED unless a known problem makes it NEEDS MORE WORK
- [ ] NEEDS MORE WORK verdict always lists specific remaining issues with severity, the measured gap where there is one, and a recommendation
-- [ ] Next Steps handoff references `/release-checklist` (on success), `/sprint-plan update` and a `/team-polish` re-run (on failure), `/gate-check` before handing off to release, and, on NOT ASSESSED, supplying the missing budgets or phases before a re-run
+- [ ] Next Steps handoff references `/release-checklist` (on success), `/sprint-plan update` (at `workflow: minimal`, the brief's build order in its place) and a `/team-polish` re-run (on failure), `/gate-check` before handing off to release, and, on NOT ASSESSED, supplying the missing budgets or phases before a re-run
- [ ] At `team.size: studio`, Phase 5's qa-tester is told to find how the polished feature breaks rather than confirm it holds, and the report says the adversarial pass ran; no engine specialist is added
---
diff --git a/CCGS Skill Testing Framework/skills/team/team-qa.md b/studio-tests/skills/team/team-qa.md
similarity index 92%
rename from CCGS Skill Testing Framework/skills/team/team-qa.md
rename to studio-tests/skills/team/team-qa.md
index ec15bf92..bd57d0f7 100644
--- a/CCGS Skill Testing Framework/skills/team/team-qa.md
+++ b/studio-tests/skills/team/team-qa.md
@@ -46,6 +46,15 @@ active set before Phase 1. The orchestrator-level verdict is COMPLETE or BLOCKED
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All stories pass manual QA, APPROVED verdict
@@ -287,6 +296,35 @@ active set before Phase 1. The orchestrator-level verdict is COMPLETE or BLOCKED
---
+### Case 9: `review_mode` gates nothing — the same cycle at full, lean and solo
+
+**Fixture:**
+- `project.yaml`: `team.size: small` (pinned: qa-lead and qa-tester both active),
+ `qa.level: standard` (pinned: a Logic story's automated test is its evidence);
+ `modes.review_mode` is not set, so each run's `--review` value decides
+- `production/sprints/sprint-04.md` lists 2 stories: 1 Logic (its unit test passes)
+ and 1 UI (screenshot retained); acceptance criteria populated
+- The most recent `production/qa/smoke-[date].md` verdict is PASS; no bugs on file
+- Run A: `/team-qa sprint-04 --review full`. Run B: `--review lean`. Run C: `--review solo`.
+ The tester marks both stories PASS in each run
+
+**Expected behavior:**
+1. Every run opens with the same active-set line
+2. Every run spawns `qa-lead` for the strategy (Phase 2) and the sign-off (Phase 6),
+ and `qa-tester` for test cases (Phase 4) — team members, not director gates
+3. No run spawns a CD-, TD-, PR- or AD-PHASE-GATE at any phase: "no phase below
+ spawns CD-, TD-, PR- or AD-PHASE-GATE, at any `review_mode`"
+4. The strategy ask, the QA plan ask, the evidence ask and the sign-off ask, and the
+ APPROVED verdict, are the same in all three runs
+
+**Assertions:**
+- [ ] No director gate is spawned in Run A (`full`), Run B (`lean`) or Run C (`solo`)
+- [ ] The agents spawned, the phases run and the asks made are identical across the three runs
+- [ ] The sign-off verdict is decided by the evidence and the verdict rules alone — the same APPROVED in all three runs; `--review full` does not add a reviewer and `--review solo` does not drop one
+- [ ] The Phase 6 brief to qa-lead is the same in all three runs and names no verdict
+
+---
+
## Protocol Compliance
- [ ] A manual-QA result is recorded only as the tester gave it — never filled in for them; an unanswered story stays unexecuted
diff --git a/CCGS Skill Testing Framework/skills/team/team-release.md b/studio-tests/skills/team/team-release.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/team/team-release.md
rename to studio-tests/skills/team/team-release.md
index 9867f0c1..d92d17fb 100644
--- a/CCGS Skill Testing Framework/skills/team/team-release.md
+++ b/studio-tests/skills/team/team-release.md
@@ -45,6 +45,15 @@ Closes with a post-release monitoring plan.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path (Single-Player) — All phases complete, version deployed
diff --git a/CCGS Skill Testing Framework/skills/team/team-ui.md b/studio-tests/skills/team/team-ui.md
similarity index 88%
rename from CCGS Skill Testing Framework/skills/team/team-ui.md
rename to studio-tests/skills/team/team-ui.md
index 813dc781..063cbb04 100644
--- a/CCGS Skill Testing Framework/skills/team/team-ui.md
+++ b/studio-tests/skills/team/team-ui.md
@@ -40,6 +40,15 @@ handoffs to `/ux-review`, `/code-review`, `/team-polish`.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Full pipeline from UX spec through polish succeeds
@@ -202,6 +211,40 @@ handoffs to `/ux-review`, `/code-review`, `/team-polish`.
---
+### Case 6: `review_mode` gates nothing — art-director stays in the roster at lean and solo
+
+**Fixture:**
+- `project.yaml`: `team.size: small` for Runs A–C, `team.size: individual` for Run D
+ (pinned: `small` is the smallest size that includes art-director and
+ accessibility-specialist); `modes.review_mode` is not set, so each run's `--review`
+ value decides
+- `design/gdd/game-concept.md`, `design/player-journey.md`,
+ `design/ux/interaction-patterns.md` and `design/accessibility-requirements.md`
+ (tier Standard) exist; `/ux-review` returns APPROVED
+- Run A: `/team-ui inventory screen --review full`. Run B: `--review lean`. Run C:
+ `--review solo`. Run D: `--review lean` at `individual`
+
+**Expected behavior:**
+1. Runs A–C open with the same active-set line for `team.size: small`:
+ ui-programmer + ux-designer + accessibility-specialist + art-director
+2. In all three, art-director is spawned for Phase 2 (visual design) and for the
+ Phase 4 review, and accessibility-specialist for Phase 4 — the review mode does
+ not skip a team member
+3. No run spawns a CD-, TD-, PR- or AD-PHASE-GATE at any phase: "no phase below
+ spawns CD-, TD-, PR- or AD-PHASE-GATE, at any `review_mode`"
+4. Run D (`individual`) names art-director and accessibility-specialist under `Not
+ spawned this run:`; their work is consulted through ui-programmer and ux-designer.
+ The size caused that, not `lean`
+
+**Assertions:**
+- [ ] art-director is spawned in Phase 2 and Phase 4 in Run A (`full`), Run B (`lean`) and Run C (`solo`)
+- [ ] The Phase 4 review spawns the same three agents in all three runs, in parallel
+- [ ] No director gate (CD-, TD-, PR- or AD-PHASE-GATE) is spawned in any run
+- [ ] Runs A–C show the same active set, phases and asks
+- [ ] In Run D art-director is not spawned, and the output attributes that to `team.size: individual`, not to `lean`
+
+---
+
## Protocol Compliance
- [ ] At the default `team.size: individual`, the run opens with an `Active set (team.size: individual): ui-programmer + ux-designer` line and a `Not spawned this run:` line naming art-director, accessibility-specialist and the engine UI specialist — before any agent is spawned
diff --git a/CCGS Skill Testing Framework/skills/utility/adopt.md b/studio-tests/skills/utility/adopt.md
similarity index 95%
rename from CCGS Skill Testing Framework/skills/utility/adopt.md
rename to studio-tests/skills/utility/adopt.md
index 9ccf49cb..e25323da 100644
--- a/CCGS Skill Testing Framework/skills/utility/adopt.md
+++ b/studio-tests/skills/utility/adopt.md
@@ -47,6 +47,15 @@ None. `/adopt` is a brownfield audit utility. No director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — All GDDs compliant, no BLOCKING or HIGH gaps
@@ -185,12 +194,12 @@ None. `/adopt` is a brownfield audit utility. No director gates apply.
- "This looks like a fresh project — no existing artifacts found. `/adopt` is for
projects with work to migrate. What would you like to do?"
- Options: "Run `/start`", "My artifacts are in a non-standard location", "Cancel"
-4. Skill stops — does not proceed to audit regardless of user selection
+4. The user picks "Run `/start`"; the skill says so and stops — no audit
**Assertions:**
- [ ] `AskUserQuestion` is used (not a plain text message) when no artifacts are found
- [ ] `/start` is presented as a named option
-- [ ] Skill stops after the question — no audit phases run
+- [ ] After `/start` or Cancel the skill stops — no audit phases run; "help me find them" leads to a search, not a stop
- [ ] No adoption plan file is written
---
@@ -280,6 +289,9 @@ None. `/adopt` is a brownfield audit utility. No director gates apply.
Not separately fixture-tested here.
- The systems-index.md parenthetical status value check (BLOCKING) is a special case
that triggers an immediate fix offer before writing the plan; not separately tested.
+- The "help me find them" path (search by heading, ask before each move as a
+ `file_deletions` decision, never overwrite, then rerun Phase 1) is not given a
+ fixture.
- Phase 6b reports the resolved review mode and writes nothing — `review_mode` is
fronted by `modes.rigor`, so pinning it would shadow the rigor expansion; Case 1
asserts that nothing is written for it.
diff --git a/CCGS Skill Testing Framework/skills/utility/asset-spec.md b/studio-tests/skills/utility/asset-spec.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/utility/asset-spec.md
rename to studio-tests/skills/utility/asset-spec.md
index 65bac3f8..134da1a8 100644
--- a/CCGS Skill Testing Framework/skills/utility/asset-spec.md
+++ b/studio-tests/skills/utility/asset-spec.md
@@ -51,6 +51,15 @@ No gate IDs and no `/gate-check`. The review mode controls drafting agents only:
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Character spec in lean mode
diff --git a/CCGS Skill Testing Framework/skills/utility/brainstorm.md b/studio-tests/skills/utility/brainstorm.md
similarity index 93%
rename from CCGS Skill Testing Framework/skills/utility/brainstorm.md
rename to studio-tests/skills/utility/brainstorm.md
index 1127fd5c..6dd50bd8 100644
--- a/CCGS Skill Testing Framework/skills/utility/brainstorm.md
+++ b/studio-tests/skills/utility/brainstorm.md
@@ -33,7 +33,7 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
- [ ] Has ≥2 phase headings
- [ ] Contains verdict keyword: COMPLETE (in both the Lean Brief flow and the full flow)
- [ ] Contains "May I write" language for both `design/game-brief.md` and `design/gdd/game-concept.md`
-- [ ] Has a next-step handoff at the end (`/map-systems` in the full flow's Path A; `/create-stories` in the Lean Brief flow)
+- [ ] Has a next-step handoff at the end (`/map-systems` in the full flow's design-first steps; `/create-stories` in the Lean Brief flow)
- [ ] Documents 4 director gates in full mode: CD-PILLARS, AD-CONCEPT-VISUAL, TD-FEASIBILITY, PR-SCOPE
- [ ] Documents a named skip note for each gate in lean and solo modes
@@ -55,6 +55,15 @@ Full flow only (`workflow: standard` or `full`):
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Full mode, 3 concepts, gates at their three points
@@ -69,15 +78,15 @@ Full flow only (`workflow: standard` or `full`):
**Expected behavior:**
1. Tier branch: `full` → full flow
2. Phase 1 asks discovery questions (favourite games as plain text; the
- Experience / Timeline / Dev level multi-tab `AskUserQuestion`)
-3. Phase 2 presents 3 concepts, then a plain-list `AskUserQuestion` (no tabs) to pick
+ Experience / Timeline / Dev level questions, asked together)
+3. Phase 2 presents 3 concepts, then one question with five options to pick
4. After pillars are locked, CD-PILLARS and AD-CONCEPT-VISUAL are spawned in
- parallel; their results are presented in a two-tab (Pillars / Visual anchor) `AskUserQuestion`
+ parallel; their results are presented as two questions asked together (Pillars / Visual anchor)
5. Phase 6 asks for platform and engine (the engine question always prompts);
TD-FEASIBILITY spawns after risks are identified, before scope tiers
6. PR-SCOPE spawns after scope tiers are defined
7. Skill asks "Game concept is ready. May I write it to `design/gdd/game-concept.md`?"
-8. Written after approval with a Visual Identity Anchor section; Path A next steps include `/map-systems`
+8. Written after approval with a Visual Identity Anchor section; the design-first next steps include `/map-systems`
9. Verdict is COMPLETE
**Assertions:**
@@ -103,7 +112,7 @@ Full flow only (`workflow: standard` or `full`):
**Expected behavior:**
1. Both gates were spawned in parallel; the skill collects both results
-2. Because CD-PILLARS returned REJECT, the two-tab question is **not** used: the
+2. Because CD-PILLARS returned REJECT, the two questions are **not** asked together: the
creative-director's feedback is presented in a Pillars question on its own,
with options `Lock in as-is` / `Revise [specific pillar]` / `Discuss further`
3. Pillar issues are resolved first; only then is the Visual anchor question
@@ -113,7 +122,7 @@ Full flow only (`workflow: standard` or `full`):
**Assertions:**
- [ ] CD-PILLARS feedback is shown to the user
- [ ] User is offered `Revise [specific pillar]` and `Discuss further` (and may `Lock in as-is`)
-- [ ] The first question after the REJECT has no Visual anchor tab
+- [ ] The first question after the REJECT has no Visual anchor question
- [ ] Visual anchor selection is not requested until the pillar issue is resolved
- [ ] `design/gdd/game-concept.md` is not written at this point
@@ -154,7 +163,7 @@ Full flow only (`workflow: standard` or `full`):
**Expected behavior:**
1. Tier branch: `minimal` → Lean Brief flow; Phases 1–5 are skipped
-2. From the hint, proposes 2–3 one-line concepts and asks one `AskUserQuestion` to pick or combine
+2. From the hint, proposes 2–3 one-line concepts and asks one question to pick or combine
3. Fills the brief fields conversationally (pitch, core loop, player goal & fail
state, MVP, out of scope, build order) and presents the brief for one confirmation
4. Asks "Brief is ready. May I write it to `design/game-brief.md`?" with
diff --git a/CCGS Skill Testing Framework/skills/utility/bug-report.md b/studio-tests/skills/utility/bug-report.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/utility/bug-report.md
rename to studio-tests/skills/utility/bug-report.md
index caf788cd..e7824903 100644
--- a/CCGS Skill Testing Framework/skills/utility/bug-report.md
+++ b/studio-tests/skills/utility/bug-report.md
@@ -53,6 +53,15 @@ None. `/bug-report` is an operational documentation skill. No director gates app
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — User describes a crash, full report produced
diff --git a/CCGS Skill Testing Framework/skills/utility/bug-triage.md b/studio-tests/skills/utility/bug-triage.md
similarity index 79%
rename from CCGS Skill Testing Framework/skills/utility/bug-triage.md
rename to studio-tests/skills/utility/bug-triage.md
index 89986e56..4ef0a890 100644
--- a/CCGS Skill Testing Framework/skills/utility/bug-triage.md
+++ b/studio-tests/skills/utility/bug-triage.md
@@ -17,7 +17,9 @@ the report groups bugs by priority, not severity. A deviation check flags
systemic problems (3+ bugs in one system in a sprint; 2+ S1/S2 in one story; a
bug filed against a Complete story). The verdict is `COMPLETE` when the report is
written, `COMPLETE` with no report when there are no bug files to triage, and
-`BLOCKED` when the user declines the write. No director gates apply.
+`BLOCKED` when the user declines the write. At `workflow: minimal` there are no
+sprints by design: with no sprint file the skill says so and names the P1 bugs as the
+next fixes, ahead of the next story in the brief's build order. No director gates apply.
---
@@ -39,6 +41,15 @@ None. `/bug-triage` is an operational triage skill. No director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Sprint mode, 5 bugs grouped by priority
@@ -152,6 +163,7 @@ None. `/bug-triage` is an operational triage skill. No director gates apply.
### Case 5: Director Gate Check — Full mode, no P1 bugs
**Fixture:**
+- `modes.workflow: standard` (pinned: unset resolves to minimal, which has no sprints by design)
- No sprint file in `production/sprints/`
- `production/qa/bugs/` holds two bugs, S3/P3 and S4/P3
@@ -172,6 +184,37 @@ None. `/bug-triage` is an operational triage skill. No director gates apply.
---
+### Case 6: Minimal workflow — no sprints by design, P1 bugs ahead of the next brief story
+
+**Fixture:**
+- `project.yaml`: `modes.workflow: minimal` (pinned: this case tests the `minimal`
+ wording, the opposite of Case 5)
+- No `production/sprints/` directory
+- `design/game-brief.md` lists a build order of three features; the next unbuilt one
+ is "Inventory screen"
+- `production/qa/bugs/` holds BUG-0001 (S1, P1, Audio), BUG-0002 (S3, P1, UI) and
+ BUG-0003 (S4, P3, Tutorial)
+
+**Input:** `/bug-triage` (no argument; no sprint file, so `full` mode)
+
+**Expected behavior:**
+1. No sprint file exists, so `full` mode runs
+2. Step 2b says there are no sprints by design at `workflow: minimal` — it does not
+ print "No sprint plan found — assigning to backlog only."
+3. The two P1 bugs are named as the next fixes, ahead of the next story in the
+ brief's build order ("Inventory screen")
+4. BUG-0003 goes to the backlog; no bug is given a `Sprint:` assignment
+5. The report is written after "May I write this triage report to
+ `production/qa/bug-triage-[date].md`?"; Verdict: COMPLETE
+
+**Assertions:**
+- [ ] The no-sprint note says there are no sprints at `workflow: minimal`, and the "No sprint plan found — assigning to backlog only." wording does not appear
+- [ ] BUG-0001 and BUG-0002 are named as the next fixes, before the next story of the brief's build order
+- [ ] No bug is assigned to a sprint, and none is flagged `Priority overflow`
+- [ ] The report is written only after the "May I write" ask, and the verdict is COMPLETE
+
+---
+
## Protocol Compliance
- [ ] Discovers bugs in `production/qa/bugs/*.md` before the fallbacks
diff --git a/CCGS Skill Testing Framework/skills/utility/day-one-patch.md b/studio-tests/skills/utility/day-one-patch.md
similarity index 87%
rename from CCGS Skill Testing Framework/skills/utility/day-one-patch.md
rename to studio-tests/skills/utility/day-one-patch.md
index ffd4758a..4a869759 100644
--- a/CCGS Skill Testing Framework/skills/utility/day-one-patch.md
+++ b/studio-tests/skills/utility/day-one-patch.md
@@ -55,6 +55,15 @@ producer, art-director) is spawned. The skill spawns working agents —
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Scope, rollback plan first, fixes, patch record
@@ -196,6 +205,29 @@ producer, art-director) is spawned. The skill spawns working agents —
---
+### Case 6: Deferred Bugs With No Sprint Plan — Scheduled into the brief's build order
+
+**Fixture:**
+- `project.yaml`: `project.stage: Release`; `modes.rigor: minimal` (workflow `minimal`, no sprints)
+- The most recent file in `production/gate-checks/` records a release-gate PASS
+- No `production/sprints/` folder; `design/game-brief.md` exists with a build order
+- `production/qa/bugs/` holds `BUG-0030` — S2, P1, 1-hour fix — and `BUG-0031` — S2, fix requires an architecture change
+
+**Input:** `/day-one-patch`
+
+**Expected behavior:**
+1. BUG-0030 is included and BUG-0031 is deferred to 1.1; the user approves the scope and the patch runs to the record
+2. The patch record lists BUG-0031 in its "Deferred to 1.1" table
+3. The skill tells the user to run `/bug-triage` to schedule the deferred bugs and, because the project has no sprint plan, to put them in the brief's build order rather than a 1.1 sprint
+
+**Assertions:**
+- [ ] Every deferred bug is in the record's "Deferred to 1.1" table
+- [ ] The skill points to `/bug-triage` for scheduling the deferred bugs
+- [ ] With no sprint plan, the destination named is the brief's build order, not a 1.1 sprint
+- [ ] No sprint file is created or required
+
+---
+
## Protocol Compliance
- [ ] Confirms Release/Polish stage and verifies the release-gate record before scoping
diff --git a/CCGS Skill Testing Framework/skills/utility/help.md b/studio-tests/skills/utility/help.md
similarity index 87%
rename from CCGS Skill Testing Framework/skills/utility/help.md
rename to studio-tests/skills/utility/help.md
index 4d692561..0ab4686b 100644
--- a/CCGS Skill Testing Framework/skills/utility/help.md
+++ b/studio-tests/skills/utility/help.md
@@ -47,6 +47,15 @@ None. `/help` is a read-only navigation skill. No director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Production stage with active sprint
@@ -274,6 +283,38 @@ None. `/help` is a read-only navigation skill. No director gates apply.
---
+### Case 8: Minimal path, no game brief — a built game is documented, not re-brainstormed
+
+**Fixture:**
+- `project.yaml` has `engine.name: "Godot"` and no `modes` block (`workflow` resolves
+ to `minimal`)
+- No `design/game-brief.md`, no `design/gdd/game-concept.md`, no stories under
+ `production/epics/`
+- Run A: `src/` holds 12 `.gd` files. Run B: `src/` holds 3 `.gd` files
+
+**Input:** `/help`
+
+**Expected behavior:**
+1. `workflow: minimal` goes to Step 4m; `artifact-check.sh --path minimal` reports
+ `engine-setup` PRESENT and `game-brief` not PRESENT
+2. Run A: the code root already holds the game (10 or more source files, the same
+ test Step 2 uses for `production`), so `→ Next up` is the game brief via
+ `/reverse-document design src/`, which writes `design/game-brief.md` from what
+ is built
+3. Run B: the code root is not yet a game, so `→ Next up` is the game brief via
+ `/brainstorm`
+4. `/create-stories` follows under "Coming up after that" in both
+5. Verdict is COMPLETE
+
+**Assertions:**
+- [ ] Run A's `→ Next up` is `/reverse-document design src/` (the code root for Godot), not `/brainstorm`, which on a built game would start a new idea
+- [ ] Run B's `→ Next up` is `/brainstorm`
+- [ ] The 10-source-file threshold decides between them: 12 files route to `/reverse-document`, 3 files do not
+- [ ] No phase label, concept doc, art bible, systems map or `/gate-check` is presented as required
+- [ ] Verdict is COMPLETE, and no file is written
+
+---
+
## Protocol Compliance
- [ ] Uses the injected config block for `project.stage` and `workflow` instead of re-reading them
@@ -295,3 +336,5 @@ None. `/help` is a read-only navigation skill. No director gates apply.
assert that listing.
- The minimal path's "every story Complete" branch (three ways on: play the
build, `/create-stories`, `/settings`) is not separately tested.
+- The `/reverse-document` route for a built game with no brief is Case 8; the code
+ root for Unity (`Assets/`) and Unreal (`Source/<Module>/`) is not given a fixture.
diff --git a/CCGS Skill Testing Framework/skills/utility/hotfix.md b/studio-tests/skills/utility/hotfix.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/utility/hotfix.md
rename to studio-tests/skills/utility/hotfix.md
index 0a1a446d..99ba5af3 100644
--- a/CCGS Skill Testing Framework/skills/utility/hotfix.md
+++ b/studio-tests/skills/utility/hotfix.md
@@ -63,6 +63,15 @@ choose the QA scope.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — S1 crash fixed with record, branch, approvals and backport
diff --git a/CCGS Skill Testing Framework/skills/utility/launch-checklist.md b/studio-tests/skills/utility/launch-checklist.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/utility/launch-checklist.md
rename to studio-tests/skills/utility/launch-checklist.md
index 1fecaf15..e69bdc20 100644
--- a/CCGS Skill Testing Framework/skills/utility/launch-checklist.md
+++ b/studio-tests/skills/utility/launch-checklist.md
@@ -42,6 +42,7 @@ if `project.stage` is not `Release` (`Polish`, an earlier stage, or unset), then
Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
+- [ ] Frontmatter sets `disable-model-invocation: true`: it runs only when the user types it, set in frontmatter rather than asked for in prose
- [ ] Has ≥2 phase headings
- [ ] Contains verdict keywords: READY, CONDITIONAL, NOT ASSESSED, NOT READY (Overall Status, first match NOT READY → NOT ASSESSED → CONDITIONAL → READY), and NOT ASSESSED for unassessable scans and cert tier
- [ ] Contains "May I write" language before writing the checklist, and creates no file or directory before the answer
@@ -59,6 +60,15 @@ Producer, Release Manager) is checklist text for humans, coordinated later via
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Steam project, clean scans, every section confirmed, READY
diff --git a/CCGS Skill Testing Framework/skills/utility/localize.md b/studio-tests/skills/utility/localize.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/utility/localize.md
rename to studio-tests/skills/utility/localize.md
index 542828bb..78ce7050 100644
--- a/CCGS Skill Testing Framework/skills/utility/localize.md
+++ b/studio-tests/skills/utility/localize.md
@@ -45,6 +45,15 @@ it spawns is `localization-lead` (an operations-tier agent), and only in the
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Extract — New Strings Keyed and Appended After Approval
diff --git a/CCGS Skill Testing Framework/skills/utility/onboard.md b/studio-tests/skills/utility/onboard.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/utility/onboard.md
rename to studio-tests/skills/utility/onboard.md
index 05d9699c..f8adbbf1 100644
--- a/CCGS Skill Testing Framework/skills/utility/onboard.md
+++ b/studio-tests/skills/utility/onboard.md
@@ -40,6 +40,15 @@ in its allowed tools) and no director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Programmer Role on a Godot Project
diff --git a/CCGS Skill Testing Framework/skills/utility/playtest-report.md b/studio-tests/skills/utility/playtest-report.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/utility/playtest-report.md
rename to studio-tests/skills/utility/playtest-report.md
index 1be408b2..7e0ee8a0 100644
--- a/CCGS Skill Testing Framework/skills/utility/playtest-report.md
+++ b/studio-tests/skills/utility/playtest-report.md
@@ -46,6 +46,15 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Analyze Notes, Findings Routed by Bucket
diff --git a/CCGS Skill Testing Framework/skills/utility/project-stage-detect.md b/studio-tests/skills/utility/project-stage-detect.md
similarity index 85%
rename from CCGS Skill Testing Framework/skills/utility/project-stage-detect.md
rename to studio-tests/skills/utility/project-stage-detect.md
index 716b0529..7c374699 100644
--- a/CCGS Skill Testing Framework/skills/utility/project-stage-detect.md
+++ b/studio-tests/skills/utility/project-stage-detect.md
@@ -52,6 +52,15 @@ None. `/project-stage-detect` is a diagnostic utility. It spawns no agents
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Configured Stage Matches the Artifacts
@@ -165,7 +174,7 @@ None. `/project-stage-detect` is a diagnostic utility. It spawns no agents
**Assertions:**
- [ ] No absent GDD, art bible, ADR, epic or sprint plan is listed as a gap
-- [ ] `/reverse-document` and `/sprint-plan` are not suggested
+- [ ] `/reverse-document` is not suggested for an absent GDD (this fixture has a brief; Case 7 covers the missing brief), and `/sprint-plan` is not suggested
- [ ] The Production completeness line refers to the brief's build order
- [ ] The configured Concept stage is not reported as a disagreement with the observed stage
- [ ] Report is still offered behind the "May I write" ask
@@ -232,6 +241,33 @@ None. `/project-stage-detect` is a diagnostic utility. It spawns no agents
---
+### Case 7: Minimal Workflow, No Game Brief — The follow-up depends on how much code exists
+
+**Fixture:**
+- Resolved workflow tier: `minimal`
+- No `project.stage` and no `production/stage.txt`; `engine.name: Godot` (code root `src/`)
+- No `design/game-brief.md`, no `design/gdd/` files, no sprint plans
+- Scenario (a): `src/` has 14 source files
+- Scenario (b): `src/` has 3 source files
+
+**Input:** `/project-stage-detect`
+
+**Expected behavior:**
+1. Skill uses the resolved tier `minimal`; the absent GDDs, ADRs, epics and sprint plans are still not gaps
+2. The absent `design/game-brief.md` is reported, and the Follow-Up Actions address it
+3. (a) The code root already holds the game (10 or more source files), so the follow-up is `/reverse-document design src/` — the brief is written from what is built — and not `/brainstorm`
+4. (b) With little code the follow-up is `/brainstorm`, not `/reverse-document`
+5. In both, `/sprint-plan` is not suggested; the report is offered behind the "May I write" ask
+
+**Assertions:**
+- [ ] The missing game brief is reported at `minimal`
+- [ ] (a) `/reverse-document design <code root>` is suggested, naming the resolved code root (`src/`), and `/brainstorm` is not
+- [ ] (b) `/brainstorm` is suggested and `/reverse-document` is not
+- [ ] The suggestion in both scenarios is conditioned on the source-file count (10 or more), as counted in the resolved code root
+- [ ] No GDD, ADR, epic or sprint-plan gap is reported, and `/sprint-plan` is not suggested
+
+---
+
## Protocol Compliance
- [ ] Runs `artifact-check.sh` before hand-scanning artifacts
diff --git a/CCGS Skill Testing Framework/skills/utility/prototype.md b/studio-tests/skills/utility/prototype.md
similarity index 84%
rename from CCGS Skill Testing Framework/skills/utility/prototype.md
rename to studio-tests/skills/utility/prototype.md
index 52e6d36b..87b9e4b6 100644
--- a/CCGS Skill Testing Framework/skills/utility/prototype.md
+++ b/studio-tests/skills/utility/prototype.md
@@ -64,6 +64,15 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Engine Prototype, PROCEED
@@ -72,7 +81,9 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
- `design/gdd/game-concept.md` describes a 2D platformer; `project.yaml` has
`engine.name: Godot` and `engine.language: GDScript`
- `prototypes/` has no `grapple-hook-concept/`
-- Review mode: `solo`
+- Review mode: `solo`; `modes.workflow: standard` (pinned: unset resolves to
+ minimal, which routes PROCEED to `/create-stories` and `/dev-story` instead of
+ the step 7 list — Case 6 covers that route)
- In the debrief the user reports the hypothesis CONFIRMED and answers PROCEED
**Input:** `/prototype grapple-hook traversal`
@@ -165,7 +176,9 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
**Fixture:**
- Project is in Production
-- Review mode: `full`
+- Review mode: `full`; `modes.workflow: standard` (pinned: unset resolves to minimal,
+ whose spike note and `active.md` wording Case 7 covers)
+- `production/sprints/sprint-004.md` is the current sprint and `active.md` shows it
**Input:** `/prototype rope-physics --spike`
@@ -180,6 +193,8 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
`prototypes/rope-physics-spike-[date]/SPIKE-NOTE.md` and clear the spike from
`production/session-state/active.md`?"; then writes the note (question, result
YES / NO / PARTIAL, what to do next) and updates `active.md`
+7. The note's "what to do next" offers: add to the current sprint / investigate
+ further / abandon the idea. `active.md` is cleared back to the current sprint state
**Assertions:**
- [ ] The intent widget and hypothesis/debrief phases are skipped
@@ -188,6 +203,7 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
- [ ] Output is `SPIKE-NOTE.md` in a `-spike-[date]` folder, not a REPORT.md
- [ ] No CD-PLAYTEST spawn or skip note, even though review mode is `full`
- [ ] No PROCEED / PIVOT / KILL verdict is issued
+- [ ] At `standard`, the note's next-step options say "add to current sprint", and `active.md` returns to the current sprint state
---
@@ -248,6 +264,37 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+### Case 7: Spike Mode at `workflow: minimal` — the build order, not a sprint
+
+**Fixture:**
+- `project.yaml`: `modes.workflow: minimal` (pinned: this case tests the `minimal`
+ wording, the opposite of Case 4); review mode `full`
+- No `production/sprints/` directory. `design/game-brief.md` lists a build order; the
+ story in progress is `production/epics/core/story-002.md` (`Status: In Progress`),
+ and `production/session-state/active.md` names it as the current task
+- The user answers YES to the spike question
+
+**Input:** `/prototype rope-physics --spike`
+
+**Expected behavior:**
+1. The spike runs as in Case 4, with the same asks: the spike folder, then one ask
+ naming `SPIKE-NOTE.md` and `active.md`
+2. `SPIKE-NOTE.md` holds the question tested, the result (YES / NO / PARTIAL) and
+ what to do next: add the mechanic to the brief's build order / investigate
+ further / abandon the idea. It does not offer "add to current sprint"
+3. `active.md` is updated to clear the spike and return to the story in progress
+ (story-002), not to a sprint state
+4. No CD gate and no PROCEED / PIVOT / KILL
+
+**Assertions:**
+- [ ] The note's next-step options name the brief's build order instead of the current sprint
+- [ ] After the write, `active.md` names story-002 as the current task and no sprint
+- [ ] The spike folder and the note-and-`active.md` write each follow an ask that names the files
+- [ ] No sprint file is created or referenced
+- [ ] No CD-PLAYTEST spawn or skip note and no PROCEED / PIVOT / KILL verdict is issued
+
+---
+
## Protocol Compliance
- [ ] Confirms intent with `AskUserQuestion` before building (unless `--spike`)
diff --git a/CCGS Skill Testing Framework/skills/utility/qa-plan.md b/studio-tests/skills/utility/qa-plan.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/utility/qa-plan.md
rename to studio-tests/skills/utility/qa-plan.md
index 3abe658d..f92bf7ce 100644
--- a/CCGS Skill Testing Framework/skills/utility/qa-plan.md
+++ b/studio-tests/skills/utility/qa-plan.md
@@ -43,6 +43,15 @@ its allowed tools) and no director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Sprint With Four Typed Stories
diff --git a/CCGS Skill Testing Framework/skills/utility/regression-suite.md b/studio-tests/skills/utility/regression-suite.md
similarity index 75%
rename from CCGS Skill Testing Framework/skills/utility/regression-suite.md
rename to studio-tests/skills/utility/regression-suite.md
index 2fae2892..93bc8e1c 100644
--- a/CCGS Skill Testing Framework/skills/utility/regression-suite.md
+++ b/studio-tests/skills/utility/regression-suite.md
@@ -46,6 +46,15 @@ in its allowed tools) and no director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Audit — Criteria Mapped, Formula Gap Raised to HIGH
@@ -85,7 +94,7 @@ in its allowed tools) and no director gates apply.
### Case 2: Update — Fixed Bug Without a Regression Test
**Fixture:**
-- `qa.level: standard`; `project.stage: Polish`
+- `qa.level: standard`; `modes.workflow: standard` (pinned: unset resolves to minimal, where the next-sprint wording does not apply); `project.stage: Polish`
- `production/sprints/sprint-007.md` is the current sprint plan; its one
`Status: Complete` story is `production/epics/inventory/story-003.md`
- `production/qa/bugs/BUG-0012.md` has `Status: Closed`, system `inventory`
@@ -187,8 +196,41 @@ in its allowed tools) and no director gates apply.
---
+### Case 6: Workflow Minimal With a Writing QA Level — "Next story" wording, gate requirement only at full
+
+**Fixture:**
+- `project.yaml`: `modes.workflow: minimal` (no sprints), `qa.level: standard` (pinned so the suite is generated), `project.stage: Polish`
+- No sprint plan; `design/game-brief.md` exists. `production/epics/inventory/story-003.md` has `Status: Complete`, and `tests/` holds no test for the inventory system
+- `production/qa/bugs/BUG-0012.md` has `Status: Closed`, system `inventory`; no test references it
+- `tests/regression-suite.md` exists with 6 registered tests and an old Last Updated date
+
+**Input:** `/regression-suite update`
+
+**Expected behavior:**
+1. The `qa.level` guard does not fire (`standard`); `update` mode is tier-independent, so it reads the completed stories and closed bugs
+2. BUG-0012 is MISSING REGRESSION TEST; the completed inventory story with no test and the stale manifest are reported as coverage drift
+3. After the "May I write/update" ask and the write, the follow-up lines say "next story" where they would say "next sprint": the missing tests belong in the next story, and the drift line suggests running `/regression-suite audit` at the next story boundary
+4. The gaps are described as advisory; the skill does not say `/gate-check` needs the suite at this `qa.level`
+5. Verdict COMPLETE
+
+**Assertions:**
+- [ ] The bug-gap line and the drift line say "next story" (or "story boundary") and the word "sprint" is not used for scheduling them
+- [ ] The HIGH-priority line, when a HIGH gap exists, also says "next story", not "next sprint"
+- [ ] The gaps are presented as advisory; `/gate-check` is not said to require the suite at `qa.level: standard`
+- [ ] No existing manifest entry is removed and the write follows the "May I write/update" ask
+- [ ] Verdict is COMPLETE
+
+**Case 6b — `qa.level: full`:** the same fixture with `qa.level: full` and `project.stage: Production`.
+
+**Assertions (6b):**
+- [ ] The wording is still "next story"
+- [ ] The output says phase gates require the regression suite at `qa.level: full`, so the gaps are not just advisory there
+
+---
+
## Protocol Compliance
+- [ ] At `workflow: minimal` the follow-up lines say "next story" in place of "next sprint"
- [ ] Stops before scanning at `qa.level: minimal`
- [ ] Reports `NOT ASSESSED` instead of a percentage when GDDs or tests are absent
- [ ] Asks "May I write/update `tests/regression-suite.md`" before any write
@@ -202,9 +244,11 @@ in its allowed tools) and no director gates apply.
- No-argument behaviour (runs `update` when a sprint is clearly active, else
asks A/B/C) is not tested.
-- At workflow tier `minimal`, `audit` maps coverage against the latest
+- Case 6 covers the workflow-`minimal` wording in `update` mode; at that tier
+ `audit` maps coverage against the latest
`production/qa/smoke-*.md` report instead of GDD criteria, and stops if none
exists; not separately tested.
-- Coverage-drift detection (new systems, stale manifest date) is not tested by a
- dedicated case.
+- Coverage-drift detection is exercised only through Case 6's completed story
+ without tests and stale manifest date; the new-system and revised-GDD
+ indicators have no dedicated case.
- The skill does not run tests; it maps criteria and bugs to test files by name.
diff --git a/CCGS Skill Testing Framework/skills/utility/release-checklist.md b/studio-tests/skills/utility/release-checklist.md
similarity index 98%
rename from CCGS Skill Testing Framework/skills/utility/release-checklist.md
rename to studio-tests/skills/utility/release-checklist.md
index b93b349a..838b85ed 100644
--- a/CCGS Skill Testing Framework/skills/utility/release-checklist.md
+++ b/studio-tests/skills/utility/release-checklist.md
@@ -53,6 +53,15 @@ advancement is `/gate-check`.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — PC Build on the Steam Tier
diff --git a/CCGS Skill Testing Framework/skills/utility/reverse-document.md b/studio-tests/skills/utility/reverse-document.md
similarity index 79%
rename from CCGS Skill Testing Framework/skills/utility/reverse-document.md
rename to studio-tests/skills/utility/reverse-document.md
index 1a7f7228..36398cfa 100644
--- a/CCGS Skill Testing Framework/skills/utility/reverse-document.md
+++ b/studio-tests/skills/utility/reverse-document.md
@@ -11,7 +11,8 @@ from), presents its findings with the questions code cannot answer, drafts the
document, and asks "May I write this to [output path]?".
The `design` output scales with the resolved workflow tier: an 8-section GDD at
-`full`, a 5-section GDD at `standard`, a one-page brief at `minimal`.
+`full`, a 5-section GDD at `standard`, a one-page brief at `minimal` (the whole-game `design/game-brief.md` when the path
+is the code root, `design/[system-name]-brief.md` for one system).
`architecture` and `concept` outputs are tier-independent. Intent the user did
not confirm is carried into the document marked `INTENT UNKNOWN — inferred from
implementation, not confirmed`, and every document carries a
@@ -39,6 +40,15 @@ None. `/reverse-document` is a documentation utility. No director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Well-Structured Source at `full` — 8-section GDD produced
@@ -216,12 +226,44 @@ None. `/reverse-document` is a documentation utility. No director gates apply.
---
+### Case 7: Minimal Tier, Path Is the Code Root — the whole-game brief
+
+**Fixture:**
+- `project.yaml`: `engine.name: Godot` (code root `src/`); `modes.rigor: minimal` (workflow `minimal`); no `system_overrides`
+- `src/` holds a small finished game: `src/gameplay/health_system.gd` (as in Case 1), `src/gameplay/enemy_ai.gd` (as in Case 2) and `src/main.gd` that starts the game loop — 14 source files in all
+- No `design/game-brief.md` exists
+- The user answers every `UNCLEAR INTENT AREAS` question and approves the write
+
+**Input:** `/reverse-document design src/`
+
+**Expected behavior:**
+1. The tier resolves to `minimal` from the config block; the path is the code root itself, so the target is the whole game, not one system
+2. Findings are presented and answered before any draft
+3. The draft is a one-page game brief in the `.claude/docs/templates/game-brief.md` format covering the whole game (pitch, core loop, what is built), not a GDD and not a brief for one system
+4. The provenance banner sits directly under the title
+5. Skill asks "May I write this to `design/game-brief.md`?" — not `design/gdd/`, and not a `design/[system-name]-brief.md` path
+6. File written on approval; verdict COMPLETE
+
+**Assertions:**
+- [ ] The output is a one-page brief in the game-brief format covering the whole game
+- [ ] The path is `design/game-brief.md`, not `design/[system-name]-brief.md` and not under `design/gdd/`
+- [ ] The provenance banner appears under the title, and any intent the user did not confirm is marked `INTENT UNKNOWN — inferred from implementation, not confirmed`
+- [ ] "May I write" names `design/game-brief.md` and is asked before the file is written
+- [ ] Verdict is COMPLETE
+
+**Case 7b — a path inside the code root:** the same fixture with `/reverse-document design src/gameplay/health_system.gd`.
+
+**Assertions (7b):**
+- [ ] The brief is written to `design/health-system-brief.md` (Case 6), never to `design/game-brief.md`
+
+---
+
## Protocol Compliance
- [ ] Reads the source before generating any content
- [ ] Stops at the Phase 3b sufficiency check when mechanics, formulas and values all count zero
- [ ] Waits for answers to the intent questions; unanswered ones are carried as `INTENT UNKNOWN`
-- [ ] `design` output matches the resolved tier (8 sections at `full`, 5 at `standard`, brief at `minimal`)
+- [ ] `design` output matches the resolved tier (8 sections at `full`, 5 at `standard`, brief at `minimal` — `design/game-brief.md` when the path is the code root, `design/[system-name]-brief.md` for one system)
- [ ] Emits the provenance banner under the title of every document it writes
- [ ] Asks "May I write" before creating any output file
- [ ] Verdict is COMPLETE (written) or BLOCKED (write declined)
@@ -232,7 +274,8 @@ None. `/reverse-document` is a documentation utility. No director gates apply.
- The `standard` tier (5-section GDD without Player Fantasy and Tuning Knobs)
follows Case 1's flow with a different section set; not separately
- fixture-tested. The `minimal` brief is Case 6.
+ fixture-tested. The `minimal` brief is Case 6 for one system and Case 7 for
+ the whole game.
- The `concept` type (prototype → `prototypes/[name]/CONCEPT.md` or
`design/concepts/[name].md`) is not separately tested.
- `guided` and `autonomous` automation modes change the write prompt per
diff --git a/studio-tests/skills/utility/settings.md b/studio-tests/skills/utility/settings.md
new file mode 100644
index 00000000..d68dccc7
--- /dev/null
+++ b/studio-tests/skills/utility/settings.md
@@ -0,0 +1,309 @@
+# Skill Test Spec: /settings
+
+## Skill Summary
+
+`/settings` shows and changes project configuration. It has four forms:
+`/settings` (view-all: every effective setting with its source), `/settings
+<key>` (view-one), `/settings <key>=<value>` (write to `project.yaml`) and
+`/settings --local <key>=<value>` (write a personal override to the gitignored
+`project.local.yaml`). Anything else, including an empty key or value, prints
+the usage block. It runs on the Sonnet model and reads every value through
+`yaml-helper.sh` (`resolve_setting`, `get_yaml_key`, `is_locally_overridable`,
+`validate_enum_value`), so a value the `modes.rigor` preset supplies is shown as
+`(derived from rigor: <level>)` rather than "(not set)".
+
+Every write is validated against the schema enums first, then confirmed with an
+`AskUserQuestion` approval gate (`[A] Yes, write` / `[B] No, cancel`). A
+`project.yaml` write is a `schema_changes` decision, so it is confirmed even in
+`autonomous` mode. `--local` refuses a key that is not on the local-override
+whitelist. A setting that `.claude/docs/effects-map.md` marks with a
+`> ### RESERVED` banner is stored when asked, but every form says nothing reads
+it. The skill gives no verdict: it prints and writes configuration. No director
+gates apply.
+
+---
+
+## Static Assertions (Structural)
+
+Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
+
+- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
+- [ ] Has ≥2 phase headings
+- [ ] No verdict keyword is required: the output is configuration, not a judgement (`/skill-test static` Check 3 gives a WARN, never a FAIL, for this skill)
+- [ ] Both write phases ask for approval with `AskUserQuestion` before the `Edit` or `Write`
+- [ ] The reserved set is derived from `effects-map.md`'s `> ### RESERVED` headings, not hardcoded
+- [ ] Points to `.claude/docs/settings-guidance.md` for which value to choose
+
+---
+
+## Director Gate Checks
+
+None. `/settings` is a configuration utility. No director gates apply.
+
+---
+
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
+## Test Cases
+
+### Case 1: Happy Path — view-all shows derived values, a local override and the legend
+
+**Fixture:**
+- `project.yaml`:
+ ```yaml
+ framework:
+ version: 1.2.0
+ modes:
+ rigor: full
+ automation: collaborative
+ docs:
+ density: terse
+ engine:
+ name: Godot
+ ```
+- `project.local.yaml`:
+ ```yaml
+ modes:
+ automation: autonomous
+ ```
+
+**Input:** `/settings`
+
+**Expected behavior:**
+1. Reports both files present and `Schema validation: ok`
+2. Lists every file leaf, then appends the rigor family the files do not set:
+ `modes.workflow`, `qa.level`, `modes.story_granularity`, `modes.review_mode`
+ and `team.size`, each annotated `(derived from rigor: full, …)`
+3. `docs.density: terse` is annotated `(project.yaml, locked)` — the explicit
+ value wins over the `thorough` that `rigor: full` would supply
+4. `modes.automation: autonomous` is annotated
+ `(LOCAL OVERRIDE — yaml has: collaborative)`
+5. Leaves are grouped by top-level section (`modes:`, `docs:`, `qa:`, …), not
+ by the file they came from
+6. Below the block, the two-line legend: `locked` means it cannot be overridden
+ in `project.local.yaml`, and does not mean fixed
+7. No file is written
+
+**Assertions:**
+- [ ] All five rigor-derived knobs appear with real values, none as "(not set)"
+- [ ] The explicit `docs.density` shows its own value and source, not the preset's
+- [ ] The local override names the `project.yaml` value it shadows
+- [ ] The `locked` legend is printed, and says a derived value can still be set explicitly
+- [ ] Nothing is written
+
+---
+
+### Case 2: View-one — a rigor-derived key says how to set it
+
+**Fixture:**
+- `project.yaml` sets `modes.rigor: standard` and no `qa.level`
+
+**Input:** `/settings qa.level`
+
+**Expected behavior:**
+1. Prints `Effective value: standard` and `Source: derived from rigor: standard`
+2. Adds the line `Set explicitly with: /settings qa.level=<value> (an explicit value wins over rigor)`
+3. `Locally overridden: no`; the whitelist line reads `locked — project-wide`
+
+**Assertions:**
+- [ ] The value comes from the rigor expansion, not "(not set)"
+- [ ] The "Set explicitly with" line is shown for a derived value
+- [ ] Nothing is written
+
+---
+
+### Case 3: Set-yaml — changing `modes.rigor` reports the six knobs it moves
+
+**Fixture:**
+- `project.yaml`:
+ ```yaml
+ modes:
+ rigor: minimal
+ automation: collaborative
+ docs:
+ density: thorough
+ ```
+- The user answers `[A] Yes, write`
+
+**Input:** `/settings modes.rigor=standard`
+
+**Expected behavior:**
+1. `validate_enum_value modes.rigor standard` passes
+2. `AskUserQuestion` asks ``Set `modes.rigor=standard` in `project.yaml`?``
+ with `[A] Yes, write` / `[B] No, cancel`
+3. The `Edit` anchors on the `modes:` line plus the `rigor: minimal` line and
+ changes only that value; no second `modes:` block is added
+4. Confirms ``Set `modes.rigor=standard` in `project.yaml`.`` and lists what
+ the six knobs resolve to now, re-read with `resolve_setting`:
+ `modes.workflow: standard`, `qa.level: standard`,
+ `modes.story_granularity: balanced`, `modes.review_mode: lean`,
+ `team.size: individual` (each derived from rigor: standard) and
+ `docs.density: thorough` (`project.yaml` — explicit, unchanged)
+
+**Assertions:**
+- [ ] Approval is asked before the file is edited
+- [ ] `project.yaml` still has exactly one `modes:` block, with `rigor: standard`
+- [ ] The six-knob list shows the explicit `docs.density` as unchanged, not as `balanced`
+- [ ] No other line of `project.yaml` changes
+
+---
+
+### Case 4: Invalid value — rejected before any question
+
+**Fixture:**
+- `project.yaml` sets `modes.review_mode: lean`
+
+**Input:** `/settings modes.review_mode=chaotic`
+
+**Expected behavior:**
+1. `validate_enum_value` returns 1; its message is shown verbatim:
+ `Invalid value 'chaotic' for 'modes.review_mode'. Allowed: ...`
+2. The skill exits: no approval question, no write
+
+**Assertions:**
+- [ ] The helper's error line is shown as it is, naming the allowed values
+- [ ] No `AskUserQuestion` is asked
+- [ ] `project.yaml` is unchanged
+
+---
+
+### Case 5: `--local` on a locked key — refused with the team-wide route
+
+**Fixture:**
+- `project.yaml` sets `engine.name: Godot`; no `project.local.yaml`
+
+**Input:** `/settings --local engine.name=Unity`
+
+**Expected behavior:**
+1. `is_locally_overridable engine.name` returns 1
+2. One line: ``engine.name cannot be locally overridden — it's a project-wide setting. Use `/settings engine.name=Unity` (no `--local`) to change it for the whole team.``
+3. The skill exits without writing
+
+**Assertions:**
+- [ ] The refusal names the `/settings <key>=<value>` route
+- [ ] No approval question is asked
+- [ ] No `project.local.yaml` is created
+
+---
+
+### Case 6: `--local` on a whitelisted key — creates the override file
+
+**Fixture:**
+- `project.yaml` exists with `modes.automation: collaborative`; no
+ `project.local.yaml`
+- The user answers `[A] Yes, write`
+
+**Input:** `/settings --local modes.automation=autonomous`
+
+**Expected behavior:**
+1. The whitelist and enum checks pass
+2. `AskUserQuestion` asks ``Set `modes.automation=autonomous` in `project.local.yaml` (your personal override, gitignored)?``
+3. `project.local.yaml` is created with the value inside its `modes:` parent
+ block
+4. Confirms ``Set `modes.automation=autonomous` in `project.local.yaml` (your override).``
+
+**Assertions:**
+- [ ] Approval is asked before the file is created
+- [ ] The new file nests the key under `modes:`, not as a dotted top-level line
+- [ ] `project.yaml` is unchanged
+
+---
+
+### Case 7: Reserved setting — stored on request, flagged on every form
+
+**Fixture:**
+- `.claude/docs/effects-map.md` is the live file; pick a key whose section
+ carries the `> ### RESERVED` banner (`accessibility.target` when this spec
+ was written — re-derive it with the skill's own grep)
+- `project.yaml` does not set that key; the user answers `[A] Yes, write`
+
+**Input:** `/settings accessibility.target=standard`, then `/settings`, then
+`/settings accessibility.target`
+
+**Expected behavior:**
+1. The write prints, before the approval question: "Note: `accessibility.target`
+ is RESERVED — no skill or hook reads it, so setting it will not change any
+ behaviour. Your value is stored either way."
+2. On yes the value is written — the skill never refuses a reserved key
+3. View-all annotates the leaf with `, reserved` and prints the reserved legend
+ below the block
+4. View-one prints "**`accessibility.target` is RESERVED — nothing reads it.**"
+ above the value block, not under it
+
+**Assertions:**
+- [ ] The warning comes before the approval question
+- [ ] The value is written after a yes
+- [ ] View-all and view-one both mark the key reserved
+- [ ] A key that only mentions the banner in prose (`platform.cert_tier`) is not marked reserved
+
+---
+
+### Case 8: Shadowed write and autonomous mode — still asked, with the shadow named
+
+**Fixture:**
+- `project.yaml` sets `modes.review_mode: lean` and `modes.automation: autonomous`
+- `project.local.yaml` sets `modes.review_mode: solo`
+- The user answers `[A] Yes, write`
+
+**Input:** `/settings modes.review_mode=full`
+
+**Expected behavior:**
+1. Before the approval question: "Note: this setting is currently locally
+ overridden in `project.local.yaml` (value: `solo`). Writing to `project.yaml`
+ will not change your effective value."
+2. The approval question is asked even though `modes.automation` is
+ `autonomous`: a `project.yaml` write is a `schema_changes` decision, which is
+ on the default always-ask list
+3. `project.yaml` gets `review_mode: full`; `project.local.yaml` is unchanged
+
+**Assertions:**
+- [ ] The shadow note names the local value and comes before the question
+- [ ] Autonomous mode does not skip the approval question
+- [ ] Only `project.yaml` is edited
+
+---
+
+### Case 9: Malformed operand — usage, no write
+
+**Fixture:**
+- `project.yaml` exists
+
+**Input:** `/settings --local modes.automation=` (and, separately,
+`/settings =full`)
+
+**Expected behavior:**
+1. The empty value (or empty key) routes to Phase 6
+2. The usage block is printed with its four forms and three examples
+3. Nothing is validated, asked or written
+
+**Assertions:**
+- [ ] Both inputs print the usage block
+- [ ] No approval question is asked and no file changes
+
+---
+
+## Protocol Compliance
+
+- [ ] Every write is preceded by an `AskUserQuestion` approval gate; `[B] No, cancel` leaves both files unchanged
+- [ ] Values are validated with `validate_enum_value` before the approval question
+- [ ] Values are read with `resolve_setting`, so derived values show with their rigor source
+- [ ] `--local` writes only whitelisted keys, and never creates `project.local.yaml` without a `project.yaml`
+- [ ] Reserved keys are flagged on view-all, view-one and both write paths
+- [ ] Every helper call runs from the project root in the same Bash command that sources `yaml-helper.sh`
+
+---
+
+## Coverage Notes
+
+- View-all with schema errors in one or both files, Phase 4's Case D (no clean
+ insertion point) and a session started in a subfolder are not separately
+ fixture-tested.
+- The missing-`project.yaml` stops (view-all, and `--local` with no base file)
+ and a missing `yaml-helper.sh` are not separately fixture-tested.
diff --git a/CCGS Skill Testing Framework/skills/utility/setup-engine.md b/studio-tests/skills/utility/setup-engine.md
similarity index 89%
rename from CCGS Skill Testing Framework/skills/utility/setup-engine.md
rename to studio-tests/skills/utility/setup-engine.md
index 433454bf..dd10efe2 100644
--- a/CCGS Skill Testing Framework/skills/utility/setup-engine.md
+++ b/studio-tests/skills/utility/setup-engine.md
@@ -43,6 +43,15 @@ None. `/setup-engine` is a technical configuration skill. No director gates appl
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Godot 4 + GDScript — Full engine configuration
@@ -50,10 +59,10 @@ None. `/setup-engine` is a technical configuration skill. No director gates appl
**Fixture:**
- `project.yaml` has no `engine` block; `technical-preferences.md` holds only placeholders
- No `design/gdd/game-concept.md` and no `design/game-brief.md`
-- `docs/engine-reference/godot/VERSION.md` already pins 4.6
+- `docs/engine-reference/godot/VERSION.md` already pins 4.7
- No `project.godot` at the repo root; the user approves every write
-**Input:** `/setup-engine godot 4.6`
+**Input:** `/setup-engine godot 4.7`
**Expected behavior:**
1. Full-spec mode: Section 2's guided selection is skipped
@@ -68,9 +77,9 @@ None. `/setup-engine` is a technical configuration skill. No director gates appl
6. `commands.build` export preset is asked, never defaulted; `commands.test` is
the gdUnit4 `GdUnitCmdTool.gd` command
7. Skill asks "May I write the `engine`, `specialists`, `naming`, and `commands` blocks to `project.yaml`?"
-8. Section 6 reads its coverage table: 4.6 is beyond the Godot row (~4.3), so
+8. Section 6 reads its coverage table: 4.7 is beyond the Godot row (~4.3), so
the knowledge risk is HIGH
-9. VERSION.md already pins 4.6 → nothing to regenerate; only its
+9. VERSION.md already pins 4.7 → nothing to regenerate; only its
`Installed at pin time` row is written, from the Section 3 probe
10. Skill proposes `project.godot` and asks before creating it; verdict COMPLETE
@@ -120,7 +129,7 @@ None. `/setup-engine` is a technical configuration skill. No director gates appl
- Placeholders only; the user never states that the project is Blueprint-primary
- The session runs on Windows (`uname -s` is neither `Linux` nor `Darwin`), so the Windows `commands` block applies
-**Input:** `/setup-engine unreal 5.7`
+**Input:** `/setup-engine unreal 5.8`
**Expected behavior:**
1. The primary-language question defaults to C++, so CLAUDE.md Language reads
@@ -137,7 +146,7 @@ None. `/setup-engine` is a technical configuration skill. No director gates appl
6. No `.uproject` is scaffolded; verdict COMPLETE
**Assertions:**
-- [ ] Engine field is set to Unreal Engine 5.7 and `engine.language` is `C++`
+- [ ] Engine field is set to Unreal Engine 5.8 and `engine.language` is `C++`
- [ ] Routing table includes `.uasset` and `.umap` entries
- [ ] ue-blueprint-specialist is assigned for Blueprint graphs
- [ ] `commands` carry the `# TODO: confirm these` comment
@@ -148,12 +157,12 @@ None. `/setup-engine` is a technical configuration skill. No director gates appl
### Case 4: Re-run on a Configured Project — blocks edited in place
**Fixture:**
-- `project.yaml` already has `engine` (Godot 4.6), `specialists`, `naming`, a
+- `project.yaml` already has `engine` (Godot 4.7), `specialists`, `naming`, a
`modes` block, and a `commands` block missing its `smoke` key
- `project.godot` exists at the repo root
-- `docs/engine-reference/godot/VERSION.md` pins 4.6
+- `docs/engine-reference/godot/VERSION.md` pins 4.7
-**Input:** `/setup-engine godot 4.6`
+**Input:** `/setup-engine godot 4.7`
**Expected behavior:**
1. Skill reads `project.yaml` before editing it
@@ -197,11 +206,11 @@ None. `/setup-engine` is a technical configuration skill. No director gates appl
### Case 6: Installed Editor Older Than the Chosen Version — ask, then record
**Fixture:**
-- As Case 1; `docs/engine-reference/godot/VERSION.md` pins 4.6
+- As Case 1; `docs/engine-reference/godot/VERSION.md` pins 4.7
- `godot --version` reports `4.5.1.stable`
- The user picks "pin the newer one and upgrade later"
-**Input:** `/setup-engine godot 4.6`
+**Input:** `/setup-engine godot 4.7`
**Expected behavior:**
1. Section 3 probes the installed editor and finds 4.5.1 — a mismatch
@@ -209,7 +218,7 @@ None. `/setup-engine` is a technical configuration skill. No director gates appl
installed version, pin the newer one and upgrade later, or pin the newer one
deliberately
3. The answer is recorded; the skill does not pick for the user
-4. VERSION.md already pins 4.6, so nothing is regenerated, but its
+4. VERSION.md already pins 4.7, so nothing is regenerated, but its
`Installed at pin time` row is written with 4.5.1
5. Verdict COMPLETE
@@ -225,15 +234,15 @@ None. `/setup-engine` is a technical configuration skill. No director gates appl
**Fixture:**
- As Case 1, on Windows; `godot --version` fails — `godot` is not on `PATH`
-- The probe finds `C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe`, which reports `4.6.1.stable`
+- The probe finds `C:/Program Files/Godot/Godot_v4.7.2-stable_win64.exe`, which reports `4.7.2.stable`
- The user names the export preset `Windows Desktop`
-**Input:** `/setup-engine godot 4.6`
+**Input:** `/setup-engine godot 4.7`
**Expected behavior:**
1. Section 3 reads the version from the executable it found — it does not report "no engine installed"
2. `build`, `test`, `run` and `smoke` each start with the quoted full path, as single-quoted scalars; `build` quotes its preset with double quotes:
- `build: '"C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe" --headless --export-debug "Windows Desktop"'`
+ `build: '"C:/Program Files/Godot/Godot_v4.7.2-stable_win64.exe" --headless --export-debug "Windows Desktop"'`
3. `test` keeps `--remote-debug tcp://127.0.0.1:0` and the gdUnit4 runner arguments after the path
4. `engine.path` records the executable
5. Verdict COMPLETE
@@ -252,6 +261,11 @@ None. `/setup-engine` is a technical configuration skill. No director gates appl
- Fresh project: no engine configured, no `project.yaml` engine block
- The engine question comes back skipped: the user closes it, or a headless run
returns every question as skipped
+- The sandbox carries the framework's `CLAUDE.md`. The rule this case checks is
+ stated there ("A skipped or dismissed question is not an answer") and in
+ `.claude/docs/automation-modes.md`, not in `/setup-engine`'s own files; a rule
+ `CLAUDE.md` loads counts as the skill's own (`/skill-test` spec mode, Step 3),
+ so a sandbox without it is set up wrong, not a skill FAIL
**Input:** `/setup-engine`
diff --git a/CCGS Skill Testing Framework/skills/utility/skill-improve.md b/studio-tests/skills/utility/skill-improve.md
similarity index 60%
rename from CCGS Skill Testing Framework/skills/utility/skill-improve.md
rename to studio-tests/skills/utility/skill-improve.md
index ece19a32..a85c1882 100644
--- a/CCGS Skill Testing Framework/skills/utility/skill-improve.md
+++ b/studio-tests/skills/utility/skill-improve.md
@@ -6,17 +6,19 @@
cycle on a single skill. It records a static baseline with
`/skill-test static [name]` (FAIL and WARN counts, and which of Checks 1–7
failed), then a category baseline with `/skill-test category [name]` when the
-skill has a `category:` in `CCGS Skill Testing Framework/catalog.yaml`. If both
+skill has a `category:` in `studio-tests/catalog.yaml`. If both
baselines are clean it stops with "No improvements needed." Otherwise it shows
a diagnosis, proposes before/after fixes, asks "May I write this improved
-version to `.claude/skills/[name]/SKILL.md`?", writes, re-runs the same tests,
+version to `.claude/skills/[name]/SKILL.md`?" (naming each `references/` file
+the fix changes too — a phase's fix goes in its `references/` file), writes,
+re-runs the same tests,
and shows a before → after comparison per dimension plus one combined line
(`Combined: 3 → 0 (improved)`).
Phase 6 compares the combined count (static FAILs + category FAILs + static
WARNs + category WARNs). Lower than baseline → "Score improved. Changes kept."
Same or worse → "Combined score did not improve." followed by "May I restore
-`.claude/skills/[name]/SKILL.md` to the content it had before this run?" — the
+`.claude/skills/[name]/SKILL.md` to the content it had before this run?" (naming every file Phase 5 wrote) — the
restore runs only on a yes, and writes back the copy recorded in Phase 5 (never
`git checkout`, which would also drop earlier uncommitted edits). No director gates apply.
@@ -40,6 +42,15 @@ None. `/skill-improve` is a meta-utility skill. No director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Check 4 FAIL and Check 5 WARN fixed, changes kept
@@ -90,7 +101,10 @@ None. `/skill-improve` is a meta-utility skill. No director gates apply.
**Expected behavior:**
1. Baseline recorded; fix proposed; "May I write …" approved; file written
2. The re-test comparison's combined line reads `Combined: [before] → [after] (worse)`,
- with the after count higher
+ with the after count higher; the after figures are what the re-run of
+ `/skill-test static some-skill` measured, not what the edit was meant to
+ achieve (the added handoff is not counted as clearing Check 5 unless the
+ re-run says so)
3. Skill reports "Combined score did not improve." and shows what changed and
why it may not have helped
4. Skill asks "May I restore `.claude/skills/some-skill/SKILL.md` to the content it had before this run?"
@@ -99,6 +113,7 @@ None. `/skill-improve` is a meta-utility skill. No director gates apply.
**Assertions:**
- [ ] Re-test combined count is compared to the baseline before finalizing
- [ ] A higher combined count takes the "did not improve" branch
+- [ ] The after score is read from the re-run of `/skill-test static`, never stated from the edit: the re-run is visible in the transcript, and the displayed after counts match its result (2 FAILs), not the 0 FAILs the edit aimed for
- [ ] The revert is asked for, not automatic
- [ ] The file is restored only after the user says yes, from the recorded copy — never via `git checkout`
- [ ] "Score improved. Changes kept." is NOT reported
@@ -108,8 +123,15 @@ None. `/skill-improve` is a meta-utility skill. No director gates apply.
### Case 3: Gate Skill — combined static + category baseline
**Fixture:**
-- `.claude/skills/gate-check/SKILL.md` has 1 static FAIL and 2 category FAILs
- (G2 and G4 of the `### gate` section in `CCGS Skill Testing Framework/quality-rubric.md`)
+- A sandbox copy of the live `gate-check` skill (its `SKILL.md` and all 12
+ `references/` files), with three planted defects — the live skill is clean,
+ so the case never depends on its current state:
+ - `SKILL.md` frontmatter has no `argument-hint:` line (static Check 1 FAIL)
+ - `references/4-assessment.md` has no "Name the omissions in the output"
+ paragraph (G2 FAIL — a narrow panel no longer names who was left out)
+ - `references/4-assessment.md` has its `solo` bullet changed to "run the
+ panel" (G4 FAIL — directors spawn in solo mode)
+- G2 and G4 are the `### gate` metrics in `studio-tests/quality-rubric.md`
- catalog gives `gate-check` `category: gate`; the user approves the write, and
the re-test is clean in both dimensions
@@ -118,14 +140,19 @@ None. `/skill-improve` is a meta-utility skill. No director gates apply.
**Expected behavior:**
1. Static baseline and category baseline (`gate rubric`) both recorded
2. Diagnosis names the static check and the two G-metrics with the exact text gap for each
-3. "May I write this improved version to `.claude/skills/gate-check/SKILL.md`?"
-4. Both `/skill-test static gate-check` and `/skill-test category gate-check` re-run
-5. The comparison ends `Combined: 3 → 0 (improved)`: "Score improved. Changes kept."
+3. The Check 1 fix goes in `SKILL.md`; the G2 and G4 fixes go in
+ `references/4-assessment.md`, not back into `SKILL.md`
+4. The write question names both files: "May I write this improved version to
+ `.claude/skills/gate-check/SKILL.md` and `.claude/skills/gate-check/references/4-assessment.md`?"
+5. Both `/skill-test static gate-check` and `/skill-test category gate-check` re-run
+6. The comparison ends `Combined: 3 → 0 (improved)`: "Score improved. Changes kept."
**Assertions:**
- [ ] Both static and category scores are captured in the baseline
- [ ] The combined count (FAILs + WARNs, both dimensions) is what Phase 6 compares
- [ ] All 3 failures are addressed in the proposed fix
+- [ ] Each fix lands in the file that holds the failing text — the phase fixes in `references/4-assessment.md`
+- [ ] The write question names every file the fix changes, not only `SKILL.md`
- [ ] Both test types are re-run after the write
- [ ] Outcome is "Score improved. Changes kept." with the combined before/after
@@ -134,10 +161,17 @@ None. `/skill-improve` is a meta-utility skill. No director gates apply.
### Case 4: Skill Already Clean — No improvements needed
**Fixture:**
-- `.claude/skills/brainstorm/SKILL.md` has 0 static FAILs and 0 WARNs
-- catalog gives `brainstorm` `category: utility`; U1 and U2 both pass
+- `.claude/skills/some-skill/SKILL.md` is written for the case to pass all 7
+ static checks with no WARN: the five frontmatter fields, an `argument-hint`
+ that matches its documented modes, three `## Phase N` headings, a `PASS` /
+ `FAIL` verdict, `Write` in `allowed-tools` with "May I write" before it, a
+ closing next-step section naming `/skill-test`, and no `context: fork`
+- catalog gives `some-skill` `category: utility`; U1 and U2 both pass
+- A purpose-built skill, not a live one such as `brainstorm`: whether a live
+ skill is clean today can only be known by running `/skill-test`, so it is not
+ a fixed fixture
-**Input:** `/skill-improve brainstorm`
+**Input:** `/skill-improve some-skill`
**Expected behavior:**
1. Static baseline 0/0 → proceeds to the category baseline (not an immediate stop)
@@ -201,6 +235,58 @@ None. `/skill-improve` is a meta-utility skill. No director gates apply.
---
+### Case 7: Split Skill Regression — every file named, recorded and restored
+
+**Fixture:**
+- A purpose-built skill `.claude/skills/split-skill/` with `SKILL.md` and two
+ files in `references/`: `1-gather.md` and `2-report.md`. The `references/`
+ files hold the phases' steps; `SKILL.md` holds the frontmatter and the
+ phase list
+- Static baseline: 0 FAILs and 2 WARNs — Check 7 in `SKILL.md` (the
+ `argument-hint` does not match the documented modes) and Check 5 in
+ `references/2-report.md` (the closing phase has no next-step section). The
+ verdict keywords and the "May I write" line both live in `references/2-report.md`
+- catalog gives `split-skill` no `category:`, so category checks are skipped
+- The fix changes `SKILL.md` (the hint) and `references/2-report.md`, but
+ the rewrite of `2-report.md` drops its verdict line and its "May I write"
+ line and adds only a bare "Next steps" heading: the re-test shows 2 FAILs
+ (Checks 3 and 4) and 1 WARN (Check 5), so the combined count rises from 2 to 3
+- `references/1-gather.md` is not changed by the fix
+- The user approves the write, then answers yes to the restore
+
+**Input:** `/skill-improve split-skill`
+
+**Expected behavior:**
+1. Phase 3 reads `SKILL.md` and every file in `references/` (`1-gather.md` and
+ `2-report.md`) before diagnosing
+2. The diagnosis names the file each gap is in: Check 7 in `SKILL.md`,
+ Check 5 in `references/2-report.md`
+3. The proposed fix puts the hint change in `SKILL.md` and the closing-phase
+ change in `references/2-report.md`; the write question names both files and
+ not `1-gather.md`
+4. Before writing, the current text of both changed files is recorded; both are
+ then written
+5. The re-run measures the new score; the comparison ends
+ `Combined: 2 → 3 (worse)`, and the skill reports "Combined score did not improve."
+6. The restore question names every file Phase 5 wrote: "May I restore
+ `.claude/skills/split-skill/SKILL.md` and
+ `.claude/skills/split-skill/references/2-report.md` to the content they had
+ before this run?"
+7. On yes: the recorded text of each file is written back with Write; no
+ `git checkout`; `1-gather.md` is not touched
+
+**Assertions:**
+- [ ] Both `references/` files are read during the diagnosis, not only `SKILL.md`
+- [ ] Each diagnosed gap names the file it is in (`SKILL.md` for Check 7, `references/2-report.md` for Check 5)
+- [ ] The phase fix is written to `references/2-report.md`, not folded back into `SKILL.md`
+- [ ] The text of every file the fix changes is recorded before the first write: both `SKILL.md` and `references/2-report.md`
+- [ ] The after score comes from the re-run of `/skill-test static split-skill`, not from the edit's intent
+- [ ] The restore question names both files the run wrote, and not `references/1-gather.md`
+- [ ] After the yes, both files hold exactly their pre-run text, and `references/1-gather.md` was never written
+- [ ] The restore uses the recorded copy, never `git checkout`
+
+---
+
## Protocol Compliance
- [ ] Always establishes a baseline before proposing any changes
diff --git a/CCGS Skill Testing Framework/skills/utility/skill-test.md b/studio-tests/skills/utility/skill-test.md
similarity index 72%
rename from CCGS Skill Testing Framework/skills/utility/skill-test.md
rename to studio-tests/skills/utility/skill-test.md
index 400ecbf1..01cd7747 100644
--- a/CCGS Skill Testing Framework/skills/utility/skill-test.md
+++ b/studio-tests/skills/utility/skill-test.md
@@ -5,20 +5,27 @@
`/skill-test` validates skills (`.claude/skills/*/SKILL.md`) and agents
(`.claude/agents/*.md`). It has four modes:
-- **static** `[name | all]`: skills only. Runs 7 structural checks (frontmatter,
+- **static** `[name | all]`: runs 7 structural checks on a skill (frontmatter,
phases, verdict keywords, ask-before-write language, next-step handoff, fork
- complexity, argument hint) and reports each as PASS / WARN / FAIL. Per-skill
- results are COMPLIANT, WARNINGS, NON-COMPLIANT or NOT ASSESSED. Writes nothing.
+ complexity, argument hint) and reports each as PASS / WARN / FAIL. A skill split
+ into `references/` files is read whole (`SKILL.md` and every references file) for
+ checks 2-5; the frontmatter checks (1, 6, 7) read `SKILL.md` only. Per-skill
+ results are COMPLIANT, WARNINGS, NON-COMPLIANT or NOT ASSESSED. It also runs
+ `.claude/scripts/agent-check.sh` and reports its agent and delegation lines as
+ observations that never change a verdict, and runs
+ `.claude/scripts/compat-inventory.sh` and reports each place the file depends on
+ something only Claude Code provides, by feature, the same way; given an agent
+ name, it reports only those observations, with no verdict. Writes nothing.
- **spec** `[skill-or-agent-name]`: resolves the name through
- `CCGS Skill Testing Framework/catalog.yaml`, reads the file and the spec at the
+ `studio-tests/catalog.yaml`, reads the file and the spec at the
entry's `spec:` path, plus `CLAUDE.md` and every file it imports with `@path`,
and marks each assertion — the spec's Static Assertions included, for a skill
as for an agent — PASS / PARTIAL / FAIL / NOT ASSESSED. Case and Overall
Verdicts are the worst result beneath them (FAIL, PARTIAL, NOT ASSESSED,
PASS). It then asks "May I write these results to
- `CCGS Skill Testing Framework/results/…` and update `catalog.yaml`?"
+ `studio-tests/results/…` and update `catalog.yaml`?"
- **category** `[name | all]`: scores the skill or agent against its section of
- `CCGS Skill Testing Framework/quality-rubric.md` (PASS / FAIL / WARN per
+ `studio-tests/quality-rubric.md` (PASS / FAIL / WARN per
metric) and asks "May I update `catalog.yaml` …?" before recording it.
- **audit** (also the no-argument default): coverage table of every skill and
every catalogued agent. Writes nothing and issues no verdict.
@@ -45,6 +52,15 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Static Mode — Well-formed skill, all 7 checks pass, COMPLIANT
@@ -106,12 +122,15 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
**Fixture:**
- `catalog.yaml` lists `gate-check` under `skills:` with
- `spec: CCGS Skill Testing Framework/skills/gate/gate-check.md`
-- That spec has 5 test cases and a Static Assertions list;
- `.claude/skills/gate-check/SKILL.md` exists
-- Suppose one of the spec's assertions reads "Balance values link to their
- source formula or rationale" — met only by `.claude/docs/coding-standards.md`
- (imported by `CLAUDE.md`), not by the skill or its gate files themselves
+ `spec: studio-tests/skills/gate/gate-check.md`
+- The sandbox's copy of that spec is the live one (9 test cases and a Static
+ Assertions list) with one Static Assertion added: "Balance values link to
+ their source formula or rationale" — met only by
+ `.claude/docs/coding-standards.md` (imported by `CLAUDE.md`), not by the skill
+ or its gate files themselves. The live spec has no such line, so the copy is
+ edited for the case
+- `.claude/skills/gate-check/` holds `SKILL.md` and 12 `references/` files
+ (6 phase files, 6 gate files)
- The user declines the results write
**Input:** `/skill-test spec gate-check`
@@ -119,8 +138,10 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
**Expected behavior:**
1. Skill resolves `gate-check` as a skill via the catalog and takes the spec
path from its `spec:` field
-2. Skill reads the skill, the spec, `CLAUDE.md` and its `@`-imported files
-3. The spec's Static Assertions are checked against the SKILL.md in a
+2. Skill reads the skill — `SKILL.md` and all 12 `references/` files — the
+ spec, `CLAUDE.md` and its `@`-imported files
+3. The spec's Static Assertions are checked against `SKILL.md` and its
+ `references/` files in a
`Static Assertions:` block before Case 1
4. Each assertion is marked PASS / PARTIAL / FAIL / NOT ASSESSED, with a Reason
for each non-PASS; the balance-values assertion is PASS, citing
@@ -128,13 +149,14 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
5. Each case gets a Case Verdict; the report ends with an Overall Verdict, the
worst result across the static assertions, the cases and Protocol Compliance
6. Skill asks "May I write these results to
- `CCGS Skill Testing Framework/results/skill-test-spec-gate-check-[date].md`
- and update `CCGS Skill Testing Framework/catalog.yaml`?"; on decline nothing is written
+ `studio-tests/results/skill-test-spec-gate-check-[date].md`
+ and update `studio-tests/catalog.yaml`?"; on decline nothing is written
**Assertions:**
- [ ] The spec path comes from the catalog `spec:` field
-- [ ] The spec's Static Assertions are evaluated against the SKILL.md, not skipped as "static mode's job"
-- [ ] All 5 test cases are evaluated, each with its own Case Verdict
+- [ ] The spec's Static Assertions are evaluated against `SKILL.md` and its `references/` files, not skipped as "static mode's job"
+- [ ] An assertion met only in a `references/` file is PASS, not FAIL for being absent from `SKILL.md`
+- [ ] All 9 test cases are evaluated, each with its own Case Verdict
- [ ] The balance-values assertion is PASS, and the report cites `coding-standards.md` as the file it came from
- [ ] Overall verdict is the worst result — FAIL, PARTIAL, NOT ASSESSED or PASS; an assertion-level NOT ASSESSED keeps it from PASS
- [ ] No file is written without approval (declined here, so nothing is written)
@@ -145,7 +167,8 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
**Fixture:**
- `.claude/skills/` contains 74 skill directories; 73 have a spec at the path
- their catalog entry names
+ their catalog entry names (in the sandbox, one skill's catalog `spec:` is
+ emptied and its spec file removed — every live skill has a spec)
- `catalog.yaml` has an `agents:` section with 49 entries, all with specs
**Input:** `/skill-test audit` (and, separately, `/skill-test` with no argument)
@@ -156,7 +179,7 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
2. Skill globs `.claude/skills/*/SKILL.md` for skills and reads the catalog's
`agents:` section for agents
3. For each skill: Has Spec (from the catalog `spec:` path, or a glob under
- `CCGS Skill Testing Framework/skills/`), last static/category dates and
+ `studio-tests/skills/`), last static/category dates and
results, category, priority
4. Separate SKILLS and AGENTS tables, a Top 5 Priority Gaps list, and the lines
`Skill coverage: 73/74 specs (99%)` and `Agent coverage: 49/49 specs (100%)`
@@ -175,7 +198,7 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
### Case 5: Category Mode — Gate Skill Evaluated Against Quality Rubric
**Fixture:**
-- `CCGS Skill Testing Framework/quality-rubric.md` has a `### gate` section with
+- `studio-tests/quality-rubric.md` has a `### gate` section with
metrics G1–G5
- `catalog.yaml` gives `gate-check` `category: gate`
- `.claude/skills/gate-check/SKILL.md` meets every metric except G2 — Director
@@ -189,7 +212,7 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
2. Skill reads the skill and the `CLAUDE.md` context, and evaluates G1–G5
3. Each metric is marked PASS, FAIL or WARN; G2 is FAIL with a quoted Gap line
4. Report ends `Verdict: FAIL (1 failure, 0 warnings)` and a Fix line
-5. Skill asks "May I update `CCGS Skill Testing Framework/catalog.yaml` to record
+5. Skill asks "May I update `studio-tests/catalog.yaml` to record
this category check (`last_category`, `last_category_result`) for gate-check?"
**Assertions:**
@@ -204,7 +227,7 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
**Fixture:**
- `catalog.yaml` lists `creative-director` under `agents:` with
- `spec: CCGS Skill Testing Framework/agents/directors/creative-director.md`
+ `spec: studio-tests/agents/directors/creative-director.md`
- `.claude/agents/creative-director.md` declares `model: opus`; there is no
`.claude/skills/creative-director/`
- The spec asserts "Model tier is `opus`"
@@ -291,7 +314,7 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
**Fixture:**
- `catalog.yaml` gives `some-skill` `category: tooling` — a category added to
the catalog before its rubric section was written
-- `CCGS Skill Testing Framework/quality-rubric.md` has no `tooling` section
+- `studio-tests/quality-rubric.md` has no `tooling` section
**Input:** `/skill-test category some-skill`
@@ -307,10 +330,48 @@ None. `/skill-test` is a meta-utility skill. No director gates apply.
---
+### Case 10: Static Mode — a split skill is read whole, but its frontmatter comes from SKILL.md
+
+**Fixture:**
+- `.claude/skills/split-skill/SKILL.md` has all five frontmatter fields, no
+ `context:` key, and two phase headings (`## Phase 1: Gather`, `## Phase 2: Report`)
+ that each say "Read `references/N-name.md` now and follow it". It holds no verdict
+ keyword, no ask-before-write language and no next-step handoff itself
+- `.claude/skills/split-skill/references/2-report.md` holds `Verdict: **COMPLETE**`,
+ the line "May I write this report to `production/qa/report.md`?" and a closing
+ "Next step: `/gate-check`"; `references/1-gather.md` holds only instructions
+- Run A: as above. Run B: the same skill, except `argument-hint:` is missing from
+ `SKILL.md` and appears only in a frontmatter-style block at the top of
+ `references/1-gather.md`
+
+**Input:** `/skill-test static split-skill`
+
+**Expected behavior:**
+1. Skill reads `SKILL.md` and every file in `references/` and runs the 7 checks on
+ them as one skill
+2. Run A: Checks 2, 3, 4 and 5 read the whole skill, so they PASS on the verdict
+ keyword, the "May I write" line and the handoff found in `references/2-report.md`;
+ Check 3 is not a FAIL for a verdict word absent from `SKILL.md`. Checks 1, 6 and 7
+ read the `SKILL.md` frontmatter: all PASS. Verdict COMPLIANT
+3. Run B: Check 1 reads `SKILL.md` only, so the missing `argument-hint:` is a FAIL
+ although the references file holds one; the verdict is NON-COMPLIANT with a
+ `Recommended:` line to add it to the `SKILL.md` frontmatter. Check 7 does not take
+ the hint from the references file either
+
+**Assertions:**
+- [ ] Run A: Checks 3, 4 and 5 PASS on text that appears only in `references/`
+- [ ] Run A: Check 3 is not a FAIL or WARN for a verdict word absent from `SKILL.md`
+- [ ] Run A: the verdict is COMPLIANT and nothing is written
+- [ ] Run B: Check 1 is FAIL — a frontmatter field found only in a `references/` file does not count
+- [ ] Run B: the verdict is NON-COMPLIANT and the `Recommended:` line names the `SKILL.md` frontmatter
+
+---
+
## Protocol Compliance
- [ ] Static mode checks exactly 7 structural assertions
-- [ ] Spec mode evaluates each test case from the spec file individually, and a skill spec's Static Assertions against the SKILL.md
+- [ ] Static mode reads a split skill's `SKILL.md` and `references/` files together for checks 2-5, and `SKILL.md` alone for the frontmatter checks (1, 6, 7)
+- [ ] Spec mode evaluates each test case from the spec file individually, and a skill spec's Static Assertions against the SKILL.md and its references/ files
- [ ] Each mode can report NOT ASSESSED — per skill in static mode, per assertion and overall in spec mode, and for a missing rubric section in category mode
- [ ] Audit mode covers all skills AND agents (not just one category)
- [ ] Spec and category modes accept an agent name as well as a skill name
diff --git a/CCGS Skill Testing Framework/skills/utility/smoke-check.md b/studio-tests/skills/utility/smoke-check.md
similarity index 72%
rename from CCGS Skill Testing Framework/skills/utility/smoke-check.md
rename to studio-tests/skills/utility/smoke-check.md
index 568106ec..5f0511e1 100644
--- a/CCGS Skill Testing Framework/skills/utility/smoke-check.md
+++ b/studio-tests/skills/utility/smoke-check.md
@@ -54,6 +54,15 @@ None. `/smoke-check` is a pre-QA utility skill. No director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Automated tests pass, manual items confirmed, PASS
@@ -315,6 +324,111 @@ None. `/smoke-check` is a pre-QA utility skill. No director gates apply.
---
+### Case 10: `quick` — no coverage scan, no Batch 3
+
+**Fixture:**
+- As Case 1: runner exits 0 with 12/12 passing; the developer says the build was
+ launched this session and selects no FAILED item in Batch 1 or Batch 2
+- One Logic story in the sprint has no matching test file (it would be MISSING
+ if scanned)
+- The sprint plan and QA plan exist
+
+**Input:** `/smoke-check quick`
+
+**Expected behavior:**
+1. Phases 1 and 2 run as normal; the automated tests PASS (12/12)
+2. Phase 3 is skipped and says so: "Coverage scan skipped — run
+ `/smoke-check sprint` for full coverage analysis."
+3. `AskUserQuestion` is used for Batch 1 and Batch 2 only; Batch 3 is not asked
+4. The report's Argument line reads `quick`, and its Test Coverage section reads
+ "Coverage: not checked (quick run) — run `/smoke-check sprint` before
+ hand-off." in place of story rows — the scan was skipped, not passed
+5. The unscanned Logic story is not reported as MISSING, no coverage row is
+ invented for it, and Missing Test Evidence reads "Not checked (quick run).",
+ not "All Logic and Integration stories have test coverage."
+6. The verdict is labelled: `PASS (quick — coverage and Batch 3 not checked)`
+7. Asks "May I write this smoke check report to `production/qa/smoke-[date].md`?"
+ and writes after approval
+
+**Assertions:**
+- [ ] The Phase 3 skip is announced with the "Coverage scan skipped" note, not silent
+- [ ] Batch 3 is never asked under `quick`; Batches 1 and 2 still are
+- [ ] The automated test run still happens: `quick` skips only Phase 3 and Batch 3
+- [ ] The report shows `Argument: quick` and carries no COVERED / MISSING / UNKNOWN rows
+- [ ] The report says coverage was not checked, in the Test Coverage and Missing Test Evidence sections, and never claims full coverage
+- [ ] The verdict line carries the `(quick — coverage and Batch 3 not checked)` label
+- [ ] No Batch 3 skip makes the verdict NOT ASSESSED: Batch 3 was not offered, so the "offered and skipped" rule does not fire
+- [ ] The report is still written only after "May I write" is approved
+
+---
+
+### Case 11: `--platform` — platform batches and a per-platform verdict table
+
+**Fixture:**
+- As Case 1: runner exits 0 with 12/12 passing; the developer says the build was
+ launched this session and selects no FAILED item in Batches 1, 2 or 3;
+ every story COVERED or EXPECTED
+- Console batch: the developer selects "UI outside TV safe zone / text clipped —
+ FAILED" and describes the clipped text on the pause menu
+- PC and mobile batches (variants below): nothing selected
+
+**Input:** `/smoke-check sprint --platform console`
+
+**Expected behavior:**
+1. Phases 1–3 run as in Case 1
+2. Phase 4 asks Batches 1–3, then the console batch (gamepad, TV safe zone,
+ keyboard/mouse fallback, cold start); the failure is followed by a request to
+ describe what is clipped
+3. The report has a Platform-Specific Results table with a Console row
+ (checks run, passed, failed 1, Platform Verdict FAIL) and no PC or Mobile row
+4. The overall verdict is FAIL: "Any platform with one or more FAIL checks
+ contributes to the overall FAIL verdict" — even though the automated tests
+ and Batches 1–3 passed
+5. Asks "May I write …"; writes after approval
+
+**Assertions:**
+- [ ] The console batch is asked in addition to Batches 1–3
+- [ ] The report contains the per-platform verdict table, with the Console row FAIL
+- [ ] The overall verdict is FAIL, driven by the console check alone
+- [ ] No PC or mobile batch is asked and no PC or Mobile row appears
+- [ ] The user's description of the failure is recorded in the report
+- [ ] Variant `--platform all`, nothing selected in any platform batch: the PC, console and mobile batches are all asked, the table has three rows each PASS, and the verdict is PASS
+- [ ] Variant `quick --platform pc`: Phase 3 and Batch 3 are skipped as in Case 10, the PC batch is still asked, and the table has a PC row
+
+---
+
+### Case 12: Phase files — each `references/` file is read before its phase, and again after compaction
+
+**Fixture:**
+- As Case 1 (valid setup, 12/12 passing, nothing selected in any batch)
+- The conversation is compacted during Phase 3, after the test run finished and
+ before the coverage scan's results are used
+
+**Input:** `/smoke-check`
+
+**Expected behavior:**
+1. `references/1-detect-setup.md` is read before the Phase 1 work, and likewise
+ `references/2-run-tests.md` before the test runner is invoked,
+ `references/3-coverage.md` before the story list is drawn,
+ `references/4-manual-checks.md` before the first `AskUserQuestion`,
+ `references/5-report.md` before the report is assembled and
+ `references/6-write-gate.md` before "May I write" is asked
+2. The reads happen phase by phase, in order — each phase's steps come from its
+ file, not from `SKILL.md`, which only names the file
+3. After the compaction, `references/3-coverage.md` is read again before the
+ scan continues ("Read it again if the conversation was compacted or resumed
+ during this phase"); the files of the finished phases are not read again
+4. The run ends as in Case 1: Verdict PASS, report written after approval
+
+**Assertions:**
+- [ ] Six Read calls on `references/1-…` through `6-…` appear in the transcript, one per phase, in phase order
+- [ ] Each file is read before the first action of its own phase (the runner for 2, the story scan for 3, `AskUserQuestion` for 4, the report for 5, the write question for 6)
+- [ ] `references/3-coverage.md` is read a second time after the compaction, before the coverage work continues
+- [ ] No other phase's file is re-read after the compaction
+- [ ] The reads change none of Case 1's results (Verdict PASS)
+
+---
+
## Protocol Compliance
- [ ] Uses `AskUserQuestion` for all manual smoke check batches (Batch 1, Batch 2, Batch 3), and Batch 1 asks whether the build was launched this session; "not launched" yields NOT ASSESSED
@@ -333,10 +447,11 @@ None. `/smoke-check` is a pre-QA utility skill. No director gates apply.
## Coverage Notes
-- The `quick` argument (skips the Phase 3 coverage scan and Batch 3) is not
- separately fixture-tested.
-- The `--platform` argument adds platform-specific `AskUserQuestion` batches and
- a per-platform verdict table; not separately tested here.
+- The `quick` argument (skips the Phase 3 coverage scan and Batch 3) is
+ Case 10; the `--platform` argument (platform batches and the per-platform
+ verdict table) is Case 11; the per-phase `references/` reads and the
+ re-read after compaction are Case 12. Each platform batch's individual
+ options are not enumerated.
- The runner-not-available path (NOT RUN, then NOT ASSESSED until the developer
confirms a result from their IDE or CI) is covered by the protocol compliance
assertions above.
diff --git a/CCGS Skill Testing Framework/skills/utility/soak-test.md b/studio-tests/skills/utility/soak-test.md
similarity index 83%
rename from CCGS Skill Testing Framework/skills/utility/soak-test.md
rename to studio-tests/skills/utility/soak-test.md
index 914a8beb..86ff7f05 100644
--- a/CCGS Skill Testing Framework/skills/utility/soak-test.md
+++ b/studio-tests/skills/utility/soak-test.md
@@ -18,7 +18,8 @@ The protocol document carries a Verdict section with PASS / PASS WITH CONCERNS /
NOT ASSESSED / FAIL for the tester to fill in after the session; a short soak
cannot return PASS. The skill asks "May I write this soak test protocol to
`production/qa/soak-test-[date]-[duration].md`?" before writing, and never runs
-the soak itself. No director gates apply.
+the soak itself. Its run steps end with `/bug-triage sprint`, or `/bug-triage full`
+at `workflow: minimal`, which has no sprints. No director gates apply.
---
@@ -30,7 +31,7 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
- [ ] Has ≥2 phase headings
- [ ] Contains verdict keywords: PASS, PASS WITH CONCERNS, NOT ASSESSED, FAIL
- [ ] Contains "May I write" collaborative protocol language before writing the protocol
-- [ ] Has a next-step handoff (`/bug-triage sprint` after the session; `/smoke-check` after fixing a FAIL)
+- [ ] Has a next-step handoff (`/bug-triage sprint` after the session, `/bug-triage full` at `workflow: minimal`; `/smoke-check` after fixing a FAIL)
---
@@ -40,12 +41,23 @@ None. `/soak-test` is a QA planning utility. No director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — 2-hour, all-focus soak on Godot
**Fixture:**
-- `project.yaml` has `engine.name: Godot` and `performance.target_framerate: 60`
+- `project.yaml` has `engine.name: Godot`, `performance.target_framerate: 60` and
+ `modes.workflow: standard` (pinned: unset resolves to minimal, which ends the run
+ steps with `/bug-triage full`, Case 6)
- `design/gdd/game-concept.md` states the intended session length
- The user approves the write
@@ -169,6 +181,28 @@ None. `/soak-test` is a QA planning utility. No director gates apply.
---
+### Case 6: Minimal workflow — the run steps end with `/bug-triage full`
+
+**Fixture:**
+- `project.yaml`: `engine.name: Godot`, `modes.workflow: minimal` (pinned: Case 1 pins
+ `standard`; this case tests the opposite)
+- No `production/sprints/` directory; the user approves the write
+
+**Input:** `/soak-test 1h all`
+
+**Expected behavior:**
+1. The protocol is built and written as in Case 2
+2. After writing, "Protocol written." lists the run steps; step 5 reads
+ `/bug-triage full`, since `workflow: minimal` has no sprints
+3. The closing line still says to run `/smoke-check` again after fixing a FAIL
+
+**Assertions:**
+- [ ] The post-session step is `/bug-triage full`, not `/bug-triage sprint`
+- [ ] Steps 1–4 and the `/smoke-check` line are unchanged from the `standard` run
+- [ ] The workflow is resolved from `project.yaml` and changes only that step
+
+---
+
## Protocol Compliance
- [ ] Parses `[duration] [focus]`, defaulting to `1h` and `all`
diff --git a/studio-tests/skills/utility/start.md b/studio-tests/skills/utility/start.md
new file mode 100644
index 00000000..48b98364
--- /dev/null
+++ b/studio-tests/skills/utility/start.md
@@ -0,0 +1,311 @@
+# Skill Test Spec: /start
+
+## Skill Summary
+
+`/start` is the first-time onboarding skill. Phase 1 reads the project with
+`project-state.sh` without printing it (engine, code root and source files,
+concept or brief, GDDs, ADRs, other work, and whether `origin` still points at
+the template repo); `source_files: unknown` is reported as an unknown code root,
+never as no code. Phase 2 asks where the user is with four options (A No idea
+yet, B Vague idea, C Clear concept, D Existing work); the engine is not asked
+here, `/setup-engine` chooses it.
+
+Phase 3 routes by answer and names only the immediate next step. Phase 4 works
+out the stage (A/B/C: `Concept`; D: from the GDD and ADR counts) and the rigor:
+kept when `modes.rigor` is set, otherwise inferred from what the user said
+(`settings-guidance.md` §3; no signal or no idea → `minimal`). It shows both on
+an assumptions card, which names `/settings` for later changes, and asks one
+question: `Save them` / `Don't save`. It asks no rigor question. Only an explicit
+yes writes: the stage through `set-stage.sh`
+(`project.yaml` and the legacy mirror `production/stage.txt`) and an inferred
+rigor through `config-set.sh`. Phase 5 asks the automation question unless the
+key is set, and writes the pick through `config-set.sh`. `/start` never writes
+any of the six knobs `modes.rigor` fronts (`modes.review_mode`,
+`modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`,
+`team.size`) or `production/review-mode.txt`.
+
+Phase 6 prints the path for the rigor (Path D's existing-work path included;
+at `minimal` a D user with no brief is told where the brief comes from) and
+asks which step to take first; Phase 7 prints a single "Type `[skill]` to
+begin." line and starts nothing. A returning user (engine set and a concept or
+brief present) skips onboarding. No director gates apply. Verdict: COMPLETE.
+
+---
+
+## Static Assertions (Structural)
+
+Checked against the SKILL.md by `/skill-test spec`, no fixture needed.
+
+- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
+- [ ] Has ≥2 phase headings
+- [ ] Contains verdict keyword: COMPLETE
+- [ ] States the write rule for every write: the stage and an inferred rigor only after an explicit yes to the save question that names `project.yaml` and `production/stage.txt`; `modes.automation` from the user's pick, and never when the save was declined
+- [ ] Has a next-step handoff at the end (Phase 7: "Type `[skill]` to begin.")
+
+---
+
+## Director Gate Checks
+
+None. `/start` is a utility setup skill. No director agents exist yet at the
+point this skill runs.
+
+---
+
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
+## Test Cases
+
+### Case 1: Happy Path — Fresh repo, Path A, rigor inferred
+
+**Fixture:**
+- No `project.yaml`, no `production/stage.txt`; `technical-preferences.md`
+ holds only placeholders (runs without the Fixture Defaults block)
+- No design documents, prototypes or source code; `origin` is the user's own repo
+- The user picks `A) No idea yet`, then `Save them`, then `Guided`
+
+**Input:** `/start`
+
+**Expected behavior:**
+1. Phase 1 runs `project-state.sh` without printing its rows
+2. Phase 2 offers exactly A–D; no engine question is asked
+3. Path A names only `/brainstorm open` as the next step and leaves the full path for later
+4. Phase 4 shows the card: stage `Concept`, rigor `minimal` with the reason (no
+ concept yet), and asks to save them to `project.yaml` and the stage to
+ `production/stage.txt`; it asks no rigor question
+5. After `Save them`, `set-stage.sh Concept` creates `project.yaml` and writes
+ `production/stage.txt`, and `config-set.sh modes.rigor minimal` adds the rigor
+6. Phase 5 asks the automation question; `config-set.sh modes.automation guided` runs on the pick
+7. Phase 6 prints the minimal 4-step path (`/setup-engine`, `/brainstorm`,
+ `/create-stories`, `/dev-story`) and asks which step to take first
+8. Phase 7 prints only "Type `[skill]` to begin."; verdict COMPLETE
+
+**Assertions:**
+- [ ] Phase 2 offers exactly the four A–D options and no engine choice
+- [ ] No rigor question is asked; the inferred `minimal` is on the card with its reason
+- [ ] Nothing is written before the explicit `Save them`
+- [ ] `project.stage` and `production/stage.txt` are both `Concept`
+- [ ] `project.yaml` ends up holding only `project.stage`, `modes.rigor` and `modes.automation` from `/start`: none of the six rigor-fronted knobs, and no `production/review-mode.txt`
+- [ ] `project.yaml` has exactly one `modes:` block, holding `rigor` and `automation`
+- [ ] Phase 6 prints the minimal 4-step path
+- [ ] The next skill is not started; Verdict is COMPLETE
+
+---
+
+### Case 2: Returning User — Onboarding skipped
+
+**Fixture:**
+- `project.yaml` has `engine.name: Godot` and `modes.rigor: minimal`; no explicit `modes.review_mode`
+- `design/game-brief.md` exists
+
+**Input:** `/start`
+
+**Expected behavior:**
+1. Phase 1 finds the engine set and the brief present
+2. The skill skips onboarding and names the engine (Godot) and the brief
+3. Review mode is reported as `solo` (from `modes.rigor: minimal`)
+4. The skill points to `/help`
+
+**Assertions:**
+- [ ] The A–D starting-point question is not asked
+- [ ] The message names the configured engine (Godot) and the brief path
+- [ ] Review mode is reported as `solo`, resolved from rigor
+- [ ] No write is made to `project.yaml` or `production/stage.txt`
+
+---
+
+### Case 3: Existing Work on Unity — Path D, stage from the files, rigor already set
+
+**Fixture:**
+- `project.yaml` has `engine.name: Unity`, `modes.rigor: standard` and
+ `modes.automation: collaborative`
+- C# scripts exist under `Assets/Scripts/`; `design/gdd/` holds 3 system GDDs;
+ no `design/gdd/game-concept.md`, no `docs/architecture/`
+- The user picks `D) Existing work` and `Save them`
+
+**Input:** `/start`
+
+**Expected behavior:**
+1. Phase 1 resolves the code root as `Assets/` and finds source files there (it
+ does not scan `src/` and conclude there is no code)
+2. Phase 3 D shares what it found (source files, 3 GDDs, engine Unity) and names
+ `/project-stage-detect` as the immediate step
+3. Phase 4's card shows stage `Systems Design` (GDDs, no ADRs) and rigor
+ `standard` as already set
+4. After the yes, `set-stage.sh "Systems Design"` writes both files; no rigor write
+5. Phase 5 says "Automation is `collaborative`" and asks nothing
+6. Phase 6 prints the existing-work path at `standard`: `/project-stage-detect`,
+ `/adopt`, `/design-system retrofit`, `/architecture-decision retrofit`,
+ `/architecture-review`, `/gate-check`
+
+**Assertions:**
+- [ ] Source files are found under `Assets/`, not reported as absent
+- [ ] Stage `Systems Design` is written to both `project.yaml` and `production/stage.txt`, after the yes
+- [ ] No rigor or automation question is asked, and neither key is rewritten
+- [ ] The existing-work path at `standard` includes the GDD, ADR and registry retrofit steps
+- [ ] Verdict is COMPLETE
+
+---
+
+### Case 4: Clone Still Wired to the Template Repo — remote note, never run
+
+**Fixture:**
+- Fresh project as in Case 1
+- `.git/config` has `[remote "origin"]` with url
+ `https://github.com/Donchitos/Claude-Code-Game-Studios.git`
+- The user picks `B) Vague idea` with the hint "a small weekend puzzler", then `Save them`
+
+**Input:** `/start`
+
+**Expected behavior:**
+1. `origin_url` matches the template repo case-insensitively
+2. Path B names `/brainstorm a small weekend puzzler` as the immediate step
+3. The card infers rigor `minimal` from "weekend" and "small"
+4. After the Phase 6 path, the skill adds once that `origin` still points at the
+ CCGS template repo, suggests `git remote rename origin template` then
+ `git remote add origin <your repo URL>`, and says to skip `UPGRADING.md`'s own
+ `git remote add template` step since that remote now exists
+5. The commands are suggested only; no git command is run
+
+**Assertions:**
+- [ ] The template-origin note appears exactly once, after the path
+- [ ] Both suggested commands are given as written above
+- [ ] The note says to skip `UPGRADING.md`'s `git remote add template` step after the rename, and why
+- [ ] No git command is executed
+- [ ] The card's rigor is `minimal`, with the user's words as the reason
+
+---
+
+### Case 5: Director Gate Check — No gate; start is a utility setup skill
+
+**Fixture:**
+- Fresh project and answers as in Case 1
+
+**Input:** `/start`
+
+**Expected behavior:**
+1. The skill completes the onboarding flow through Phase 7
+2. No director agent is handed any work
+3. No gate IDs (CD-*, TD-*, AD-*, PR-*) appear in the output
+
+**Assertions:**
+- [ ] No director gate runs
+- [ ] No gate skip messages appear (gates are absent, not suppressed)
+- [ ] The skill reaches COMPLETE without any gate verdict
+
+---
+
+### Case 6: Path D With Rigor Unset — inferred from the description, not asked
+
+**Fixture:**
+- `project.yaml` has `engine.name: Godot` and no `modes` block
+- `src/` holds GDScript files; `design/gdd/` holds 4 system GDDs; no
+ `docs/architecture/`
+- The user picks `D) Existing work` and says "a commercial game for Steam with
+ one clear core loop", then picks `Save them`, then `Collaborative`
+
+**Input:** `/start`
+
+**Expected behavior:**
+1. Phase 3 D names `/project-stage-detect` as the immediate step and prints no tiered path yet
+2. The card shows stage `Systems Design` and rigor `standard`, with the user's
+ words ("commercial", "Steam") as the reason, and the line naming `/settings`
+3. The save question offers only `Save them` / `Don't save`; no rigor question
+ is asked
+4. After `Save them`, `modes.rigor: standard` is written with the stage
+5. Phase 6 prints the existing-work path at `standard`, including
+ `/design-system retrofit`, `/architecture-decision retrofit` and
+ `/architecture-review`
+
+**Assertions:**
+- [ ] No tiered path is printed before the rigor is known
+- [ ] No rigor question is asked; the card names `/settings` as the way to change it
+- [ ] The written rigor is the inferred `standard`
+- [ ] None of the six rigor-fronted knobs is written; the file holds one `modes:` block
+
+---
+
+### Case 7: Existing `modes:` Block — rigor and automation go into it, never a second one
+
+**Fixture:**
+- `project.yaml` has `engine.name: Godot` and an existing block `modes:` with
+ only `review_mode: lean` under it; `modes.rigor` and `modes.automation` are
+ unset (runs without the Fixture Defaults block, since it tests how the keys
+ are added)
+- No `design/game-brief.md` and no concept, so this is not a returning user
+- The user picks `A) No idea yet`, `Save them`, then `Guided`
+
+**Input:** `/start`
+
+**Expected behavior:**
+1. `set-stage.sh Concept` adds the `project:` block to the existing file
+2. `config-set.sh modes.rigor minimal` and `config-set.sh modes.automation guided`
+ add both keys under the existing `modes:` block
+3. `review_mode: lean` is left as the user had it
+
+**Assertions:**
+- [ ] The finished `project.yaml` has exactly one `modes:` key, holding `review_mode`, `rigor` and `automation`
+- [ ] The existing `review_mode: lean` is unchanged and `/start` writes none of the other rigor-fronted knobs
+- [ ] There is one save question for the stage and rigor, and the automation pick needs no further ask
+
+---
+
+### Case 8: Path D at `minimal` With No Brief — names where the brief comes from
+
+**Fixture:**
+- `project.yaml` has `engine.name: Godot`, `modes.rigor: minimal` and
+ `modes.automation: collaborative`
+- `src/` holds 14 GDScript files; `design/gdd/` holds 2 system GDDs; no
+ `docs/architecture/`; no `design/game-brief.md` and no
+ `design/gdd/game-concept.md`
+- The user picks `D) Existing work` and `Save them`
+
+**Input:** `/start`
+
+**Expected behavior:**
+1. Phase 1 finds the engine set but no concept or brief, so the A–D question is asked
+2. Phase 3 D names `/project-stage-detect` as the immediate step
+3. The card shows `Systems Design` and rigor `minimal` as already set; Phase 5 asks nothing
+4. Phase 6 prints the existing-work path at `minimal`: `/project-stage-detect`,
+ `/adopt`, then the brief's source, with no GDD, ADR or registry retrofit
+5. With no brief and 10 or more source files, the brief's source is
+ `/reverse-document design src/`; `/brainstorm` is not offered as the source
+
+**Assertions:**
+- [ ] The minimal path lists `/project-stage-detect` and `/adopt`, and no `/design-system retrofit`, `/architecture-decision retrofit` or `/architecture-review`
+- [ ] With no `design/game-brief.md`, the path names `/reverse-document design src/` as the brief's source, with the code root filled in
+- [ ] `/brainstorm` is not named as the brief's source
+- [ ] Variant — `src/` holds only 4 source files: the brief's source is `/brainstorm`, and `/reverse-document` is not named
+- [ ] Variant — `design/game-brief.md` exists: this is the returning-user skip
+
+---
+
+## Protocol Compliance
+
+- [ ] Reads the project with `project-state.sh` before the first question, without printing it
+- [ ] Asks the starting-point question with options A–D; leaves the engine to `/setup-engine`
+- [ ] Never writes any of the six rigor-fronted knobs (`modes.review_mode`, `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`, `team.size`) or `production/review-mode.txt`
+- [ ] Shows the stage and rigor on a card and writes them only on an explicit yes; asks no rigor question
+- [ ] Skips the automation question when the key is set
+- [ ] Writes through `set-stage.sh` and `config-set.sh`, never by editing YAML by hand
+- [ ] Prints the existing-work path only in Phase 6, after the rigor is known
+- [ ] Never starts the next skill; a completed run (not the returning-user skip, which ends at its `/help` pointer) ends with "Type `[skill]` to begin." and Verdict COMPLETE
+
+---
+
+## Coverage Notes
+
+- Path C (clear concept, `Formalize it first` vs `Jump straight in`) is not
+ separately tested.
+- The `standard` and `full` paths for a new game follow Case 1 with the longer
+ pipeline; not separately tested.
+- The edge cases "picks D but project is empty" / "picks A but code exists" are
+ not separately tested.
+- `Don't save` (nothing written, the values kept for the run and reported as not
+ saved, and no automation write) is not separately tested.
diff --git a/CCGS Skill Testing Framework/skills/utility/test-helpers.md b/studio-tests/skills/utility/test-helpers.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/utility/test-helpers.md
rename to studio-tests/skills/utility/test-helpers.md
index 2036d1a6..8d3d90ac 100644
--- a/CCGS Skill Testing Framework/skills/utility/test-helpers.md
+++ b/studio-tests/skills/utility/test-helpers.md
@@ -42,6 +42,15 @@ None. `/test-helpers` is a scaffolding utility. No director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Player helper generated for Godot/GDScript
diff --git a/CCGS Skill Testing Framework/skills/utility/test-setup.md b/studio-tests/skills/utility/test-setup.md
similarity index 97%
rename from CCGS Skill Testing Framework/skills/utility/test-setup.md
rename to studio-tests/skills/utility/test-setup.md
index 3c6b9247..2a8753d8 100644
--- a/CCGS Skill Testing Framework/skills/utility/test-setup.md
+++ b/studio-tests/skills/utility/test-setup.md
@@ -39,6 +39,15 @@ None. `/test-setup` is a scaffolding utility. No director gates apply.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — Godot project, scaffolds GdUnit4 test structure
diff --git a/CCGS Skill Testing Framework/templates/agent-test-spec.md b/studio-tests/templates/agent-test-spec.md
similarity index 100%
rename from CCGS Skill Testing Framework/templates/agent-test-spec.md
rename to studio-tests/templates/agent-test-spec.md
diff --git a/CCGS Skill Testing Framework/templates/skill-test-spec.md b/studio-tests/templates/skill-test-spec.md
similarity index 95%
rename from CCGS Skill Testing Framework/templates/skill-test-spec.md
rename to studio-tests/templates/skill-test-spec.md
index c5a44934..dd387c2f 100644
--- a/CCGS Skill Testing Framework/templates/skill-test-spec.md
+++ b/studio-tests/templates/skill-test-spec.md
@@ -29,6 +29,15 @@ Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
---
+## Fixture Defaults
+
+Every case's `project.yaml` sets `modes.rigor: minimal` and
+`modes.automation: collaborative`, with no `project.local.yaml`, unless its own
+Fixture says otherwise. Rules: `studio-tests/CLAUDE.md` §
+Fixture defaults.
+
+---
+
## Test Cases
### Case 1: Happy Path — [brief name]