Release 1.1.0 — one config file, and a process weight you choose

`project.yaml` at the repo root is now the single source of truth for a
project's configuration, replacing `production/stage.txt`,
`production/review-mode.txt` and `.claude/docs/technical-preferences.md` (all
three still read as a fallback; nothing is force-deleted).

**`modes.rigor` — one question instead of six.** `minimal`, `standard` or
`full` fronts six knobs: `modes.workflow`, `docs.density`, `qa.level`,
`modes.story_granularity`, `modes.review_mode` and `team.size`. It defaults to
`minimal`, which is a change from 1.0's behaviour: the heavier tier was
measured costing several times more to reach working code without producing a
better result, and returning nothing when a fresh developer inherited the
project. Pin `modes.rigor: standard` to keep 1.0's process level.

Also in this release:

- `/settings` to view or change any setting, and `project.local.yaml` for
  per-developer preferences that should not be committed.
- `system_overrides` to hold one system to a higher standard than the rest of
  the project, and `testing.strict` to set per test type whether missing
  evidence blocks a story or warns.
- A story that changes anything the player sees is not closed until the game
  has been launched, observed, and a screenshot retained in
  `production/qa/evidence/`. A parse check is not a run. This holds at every
  rigor level, including `minimal`, where automated tests are waived but the
  look is not.
- The code root is engine-specific and enforced as such: Godot `src/`, Unity
  `Assets/`, Unreal `Source/<Module>/`. Two of the three will not build a
  project laid out any other way.
- Migration tooling for existing projects: `.claude/scripts/migrate-v1-config.sh`
  converts a 1.0 layout, non-destructively by default, with a report to review
  before `--finalize` deletes anything.
- Ask-before-write holds regardless of personal automation settings.

Upgrading from 1.0 or earlier: see UPGRADING.md. Full list of changes:
CHANGELOG.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016xvzG3i7pWQg4LjyDwWMXd

.claude/skills/reverse-document/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reverse-document
-description: "Generate design or architecture documents from existing implementation. Works backwards from code/prototypes to create missing planning docs."
+description: "Generate missing design or architecture docs from existing implementation — works backwards from code and prototypes."
 argument-hint: "<type> <path> (e.g., 'design src/gameplay/combat' or 'architecture src/core')"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Edit, Bash
@@ -35,6 +35,30 @@ appropriate design or architecture documentation. Use this when:
 - `src/core/event-system.cpp` → Specific file
 - `prototypes/stealth-mech/` → Prototype directory
 
+!`source "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/yaml-helper.sh" 2>/dev/null && resolve_config --keys workflow,system_overrides,automation`
+
+**Automation mode**: Resolve `modes.automation` (`project.local.yaml` →
+`project.yaml` → default `collaborative`). Every `AskUserQuestion` call and
+every file write follows `.claude/docs/automation-modes.md`
+(collaborative asks always · guided major-only · autonomous logs and proceeds;
+`automation_always_ask` categories always prompt).
+
+Resolved above — use as-is. No block → defaults in
+`.claude/docs/config-resolution.md`.
+
+**Resolve the workflow tier** for the target system: map `<path>` to a system
+name, then use the `system_overrides` row for that system if the block above
+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
+> writes an 8-section GDD and at `minimal` a one-page brief, so a wrong tier
+> produces the wrong artifact entirely.
+
 **Examples**:
 ```bash
 /reverse-document design src/gameplay/magic-system
@@ -90,6 +114,35 @@ appropriate design or architecture documentation. Use this when:
 - "The prototype emphasizes stealth over combat. Is that the intended pillar?"
 - "Players seem to exploit the grappling hook for speed. Feature or bug?"
 
+## Phase 3b: Sufficiency Check — is there enough here to document?
+
+**Run this before Phase 4, and stop here if it fails.** This skill infers a
+design from an implementation, so when the implementation is thin there is
+nothing to infer *from* — and the template below will happily accept invented
+content, because every section of it is mandatory.
+
+Count what Phase 2 actually found:
+
+| Signal | What counts |
+|---|---|
+| Mechanics | A named behaviour with observable rules — not a stub, not an empty class |
+| Formulas | An expression computing a gameplay value from inputs |
+| Values | A tuning constant with a use site |
+
+**If all three counts are zero, or the target path holds fewer than ~20 lines of
+non-boilerplate code, stop and say so:**
+
+> "`[path]` does not contain enough implementation to reverse-document.
+> Found: [N] mechanics, [N] formulas, [N] tuning values.
+> Reverse-documentation infers design from behaviour; with no behaviour to read,
+> anything I produce would be invention wearing the format of a design document.
+> If the design exists only in your head, `/design-system [name]` is the skill
+> that captures it — it asks rather than infers."
+
+**Do not proceed on a partial count by filling the rest.** A path with two
+mechanics and no formulas gets a document with two mechanics and an explicit
+`FORMULAS DISCOVERED: none found in the source` — see Phase 4.
+
 ## Phase 4: Present Findings
 
 Before drafting, show what you discovered:
@@ -115,8 +168,28 @@ UNCLEAR INTENT AREAS:
 Before I draft the design doc, could you clarify these points?
 ```
 
+> **Every section above may be empty, and an empty one must say so.** Write
+> `none found in the source` under the heading — never omit the heading (which
+> reads as "not looked for") and never populate it from what a system like this
+> usually has. The bracketed rows are *shapes*, not quotas: a source with one
+> mechanic yields one row, not four.
+>
+> This matters more here than in a report, because the output of this skill is not
+> a report — it is a **design document**, and `/design-review`, `/create-epics` and
+> `/create-stories` will read it as a statement of authored intent. A fabricated
+> formula in a GDD does not stay a documentation error; it becomes a requirement,
+> and then a story, and then code written to satisfy it.
+
 Wait for user to clarify intent before drafting.
 
+**If the user does not answer the `UNCLEAR INTENT AREAS` questions, do not draft
+the resolved version anyway.** Those questions exist because **code cannot tell
+you why** — it records what was built, never what was intended, and the gap
+between them is the entire content of a design document. Unanswered items are
+carried into the draft verbatim as open questions, in the document, marked
+`INTENT UNKNOWN — inferred from implementation, not confirmed`. An inferred
+intent presented as a settled one is the failure mode of this whole skill.
+
 ## Phase 5: Draft Document Using Template
 
 Based on type, use appropriate template:
@@ -127,12 +200,51 @@ Based on type, use appropriate template:
 | `architecture` | `templates/architecture-doc-from-code.md` | `docs/architecture/[decision-name].md` |
 | `concept` | `templates/concept-doc-from-prototype.md` | `prototypes/[name]/CONCEPT.md` or `design/concepts/[name].md` |
 
+**The `design` output scales with the workflow tier** (resolved in Phase 1):
+- **`full`** — generate a full 8-section GDD.
+- **`standard`** — generate a 5-section GDD (Overview, Detailed Design, Edge Cases,
+  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
+  `design/[system-name]-brief.md`.
+
+(`architecture` and `concept` outputs are tier-independent.)
+
 **Draft structure**:
 - Capture **what exists** (mechanics, patterns, implementation)
 - Document **why it exists** (intent clarified with user)
 - Identify **what's missing** (edge cases not handled, gaps in design)
 - Flag **follow-up work** (balance tuning, missing features)
 
+### Stamp the provenance — required, at the top of every document this skill writes
+
+A document produced here lands at the same path, in the same format, as one a
+designer wrote by hand, and **every downstream consumer treats the two
+identically**. `/design-review` checks it for completeness, `/create-epics`
+derives epics from it, `/create-stories` turns its lines into acceptance
+criteria. Nothing anywhere asks where it came from.
+
+The difference is not cosmetic: an authored GDD states **intent**, and this one
+states **observed behaviour plus inference**. When they disagree, the code is
+what needs changing in the first case and the document in the second — and a
+reader cannot tell which they are holding unless the document says.
+
+Emit this immediately under the title:
+
+```markdown
+> **Reverse-documented from implementation** — generated by `/reverse-document`
+> from `[path]` on `[date]`, at commit `[short-sha]`.
+> This records what the code **does**; intent marked `INTENT UNKNOWN` below was
+> inferred, not confirmed by the author. Where this document and the code
+> disagree, do not assume the document is the requirement.
+```
+
+Keep the banner on revision. If a human later confirms the intent and adopts the
+document as authored design, removing it is their explicit act — not a
+side effect of the next edit.
+
 ## Phase 6: Show Draft and Request Approval
 
 **Collaborative protocol**:
@@ -150,10 +262,22 @@ SECTIONS MARKED AS INCOMPLETE:
 - "[System] interaction with [other-system]" (not fully implemented yet)
 - "[Variant or feature]" (only [subset] implemented so far)
 
-May I write this to design/gdd/[system-name].md?
+May I write this to [output path]?
 ```
 
-Wait for approval. User may request changes before writing.
+Use the tier-correct output path in the prompt: `design/gdd/[system-name].md` for
+a `full`/`standard` GDD, or `design/[system-name]-brief.md` for a `minimal` brief.
+
+**At `collaborative`** — wait for approval; the user may request changes before
+writing. **At `guided`** — this is a *new* file, so `automation-modes.md:81`
+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
 
@@ -200,11 +324,11 @@ Would you like me to tackle any of these now?
 
 | If analyzing... | Use template... | Because... |
 |----------------|-----------------|------------|
-| `src/gameplay/*` | design-doc-from-implementation.md | Gameplay mechanics → GDD |
-| `src/core/*`, `src/ai/*` | architecture-doc-from-code.md | Core systems → ADR |
+| `<code root>/gameplay/*` | design-doc-from-implementation.md | Gameplay mechanics → GDD |
+| `<code root>/core/*`, `<code root>/ai/*` | architecture-doc-from-code.md | Core systems → ADR |
 | `prototypes/*` | concept-doc-from-prototype.md | Experiments → concept doc |
-| `src/networking/*` | architecture-doc-from-code.md | Technical systems → ADR |
-| `src/ui/*` | design-doc-from-implementation.md | UI/UX → design spec |
+| `<code root>/networking/*` | architecture-doc-from-code.md | Technical systems → ADR |
+| `<code root>/ui/*` | design-doc-from-implementation.md | UI/UX → design spec |
 
 ---