Release 1.1.2 — the default path works end to end

Fix release for 1.1.1: the minimal path end to end, engine commands that
run on Godot, Unity and Unreal, hook warnings you can see, and verdicts
that say when they could not check. Details in CHANGELOG.md; upgrade
steps in UPGRADING.md (v1.1.1 → v1.1.2).

Fixes #67
Fixes #131

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

CCGS Skill Testing Framework/skills/analysis/tech-debt.md

@@ -2,24 +2,37 @@
 
 ## Skill Summary
 
-`/tech-debt` tracks, categorizes, and prioritizes technical debt across the
-codebase. It reads `docs/tech-debt-register.md` for the existing debt register
-and scans source files in `src/` for inline `TODO` and `FIXME` comments. It
-merges and sorts items by severity. No director gates are invoked. The skill
-asks "May I write to `docs/tech-debt-register.md`?" before updating. Verdicts:
-REGISTER UPDATED or NO NEW DEBT FOUND.
+`/tech-debt` tracks technical debt through four subcommands: `scan`, `add`,
+`prioritize` and `report`. With no subcommand it prints usage and stops with
+Verdict FAIL. `scan` searches the code root (resolved per engine: `src/`,
+`Assets/` or `Source/`) for `TODO`, `FIXME`, `HACK` and `@deprecated` markers,
+duplicated blocks, files over 500 lines and functions over 50 lines, sorts the
+findings into six debt categories, states how many files it covered, and asks
+"May I write these findings to `docs/tech-debt-register.md`?" before appending
+(never overwriting) entries — updating a matching `Open` row, and proposing an
+`Open` row whose pattern is gone as `Resolved [date]`. New rows follow the
+skill's Debt Register Format (next `TD-NNN`, ten columns, an `Added` date). A
+scan over zero source files is `NOT ASSESSED — no source files to scan`, an
+unresolved code root is `NOT ASSESSED — code root unresolved`, and both write
+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
+invoked. Verdicts: COMPLETE, BLOCKED (user declined a write), FAIL (missing
+subcommand), NOT ASSESSED.
 
 ---
 
 ## Static Assertions (Structural)
 
-Verified automatically by `/skill-test static` — no fixture needed.
+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 keywords: REGISTER UPDATED, NO NEW DEBT FOUND
-- [ ] Contains "May I write" language (skill writes to debt register)
-- [ ] Has a next-step handoff (what to do after register is updated)
+- [ ] Contains verdict keywords: COMPLETE, BLOCKED, FAIL, NOT ASSESSED
+- [ ] Contains "May I write" language (writes `docs/tech-debt-register.md`)
+- [ ] Has a next-step handoff (Phase 3: `/sprint-plan`, `/tech-debt report`)
 
 ---
 
@@ -32,140 +45,219 @@ invoked.
 
 ## Test Cases
 
-### Case 1: Happy Path — Inline TODOs plus existing register items merged
+### Case 1: Happy Path — Scan appends new findings to an existing register
 
 **Fixture:**
-- `docs/tech-debt-register.md` exists with 2 items (LOW and MEDIUM severity)
+- `project.yaml`: `engine.name: godot`; `modes.automation` unset (collaborative)
+- `docs/tech-debt-register.md` is in the skill's Debt Register Format and has 2 `Open` rows:
+  - TD-001 — Code Quality, Files `src/core/save_system.gd`: a `# HACK` workaround for a save-path bug. That `HACK` comment is no longer in the file
+  - TD-002 — Code Quality, Files `src/gameplay/combat.gd`: the `# TODO` comments in that file
 - `src/gameplay/combat.gd` has 2 `# TODO` comments and 1 `# FIXME` comment
-- `src/ui/hud.gd` has 0 inline debt comments
+- `src/ui/hud.gd` is 620 lines long; 12 source files in `src/` in total
 
-**Input:** `/tech-debt`
+**Input:** `/tech-debt scan`
 
 **Expected behavior:**
-1. Skill reads `docs/tech-debt-register.md` — finds 2 existing items
-2. Skill scans `src/` — finds 3 inline comments (2 TODOs, 1 FIXME)
-3. Skill checks whether inline comments already exist in the register (deduplication)
-4. Skill presents combined list sorted by severity (FIXME before TODO by default)
-5. Skill asks "May I write to `docs/tech-debt-register.md`?"
-6. User approves; register updated; verdict REGISTER UPDATED
+1. Skill resolves the code root to `src/` and scans it for debt indicators
+2. Findings include the 2 TODOs, the FIXME (treated as a bug disguised as debt) and `hud.gd` as a file over 500 lines
+3. Each finding is sorted into one of the six categories (Architecture, Code Quality, Test, Documentation, Dependency, Performance)
+4. The output states the denominator — 12 source files scanned
+5. Matching against the register: the 2 TODOs share TD-002's file and kind, so they update TD-002; TD-001's `HACK` is gone, so TD-001 is proposed as `Resolved [date]`; the FIXME and `hud.gd` become new rows TD-003 and TD-004
+6. Skill presents the findings and the TD-001 resolution, then asks "May I write these findings to `docs/tech-debt-register.md`?" — one approval covers both
+7. On approval, TD-001's Status becomes `Resolved YYYY-MM-DD` and the row stays; TD-002 is updated; TD-003 and TD-004 are appended with all ten columns, Status `Open`, `Added` set to today (`YYYY-MM-DD`) and Priority `—`
+8. Verdict: **COMPLETE** — scan findings written to register
 
 **Assertions:**
-- [ ] Inline comments are found by scanning `src/` recursively
-- [ ] Existing register items are not duplicated
-- [ ] Combined list is sorted by severity
-- [ ] "May I write" prompt appears before any write
-- [ ] Verdict is REGISTER UPDATED
+- [ ] The scan covers the resolved code root `src/` for TODO, FIXME, HACK, `@deprecated`, files >500 lines and functions >50 lines
+- [ ] Each finding is assigned one of the six debt categories
+- [ ] The number of files scanned is stated with the findings
+- [ ] "May I write" names `docs/tech-debt-register.md` and comes after the findings are shown
+- [ ] The two TODO findings update TD-002 instead of adding a duplicate row
+- [ ] TD-001 is proposed as `Resolved [date]` inside the same approval, and is kept in the register rather than deleted
+- [ ] New rows take the next IDs (TD-003, TD-004) and carry an `Added` date; the register is updated in place, never replaced
+- [ ] Verdict is COMPLETE
 
 ---
 
-### Case 2: Register Doesn't Exist — Offered to create it
+### Case 2: No Subcommand — Usage and FAIL
 
 **Fixture:**
-- `docs/tech-debt-register.md` does NOT exist
-- `src/` contains 4 inline TODO/FIXME comments
+- `docs/tech-debt-register.md` exists
+- `src/` contains source files with TODO comments
 
 **Input:** `/tech-debt`
 
 **Expected behavior:**
-1. Skill attempts to read `docs/tech-debt-register.md` — not found
-2. Skill informs user: "No tech-debt-register.md found"
-3. Skill offers to create the register with the inline items it found
-4. Skill asks "May I write to `docs/tech-debt-register.md`?" (create)
-5. User approves; register created with 4 items; verdict REGISTER UPDATED
+1. Phase 1 finds no subcommand
+2. Skill outputs usage listing `scan`, `add`, `prioritize` and `report`
+3. Skill stops — no scan runs and the register is not read or written
+4. Verdict: **FAIL** — missing required subcommand
 
 **Assertions:**
-- [ ] Skill does not crash when register file is absent
-- [ ] User is offered register creation (not silently skipping)
-- [ ] "May I write" prompt reflects file creation (not update)
-- [ ] Verdict is REGISTER UPDATED after creation
+- [ ] Usage lists the four subcommands
+- [ ] No scan is performed and no file is written
+- [ ] Verdict is FAIL, stating the subcommand is missing
 
 ---
 
-### Case 3: Resolved Item Detected — Marked resolved in register
+### Case 3: Empty Code Root — NOT ASSESSED, not a clean scan
 
 **Fixture:**
-- `docs/tech-debt-register.md` has 3 items; one references `src/gameplay/legacy_input.gd`
-- `src/gameplay/legacy_input.gd` has been deleted (refactored away)
-- The referenced TODO comment no longer exists in source
+- `project.yaml`: `engine.name: godot`
+- `src/` exists but contains no source files
+- `docs/tech-debt-register.md` exists with 3 entries
 
-**Input:** `/tech-debt`
+**Input:** `/tech-debt scan`
 
 **Expected behavior:**
-1. Skill reads register — finds 3 items
-2. Skill scans `src/` — does not find the source location referenced by item 2
-3. Skill flags item 2 as RESOLVED (source is gone)
-4. Skill presents the resolved item to user for confirmation
-5. On approval, register is updated with item 2 marked `Status: Resolved`
+1. Skill resolves the code root to `src/` and counts the files the scan covered: zero
+2. Skill reports **NOT ASSESSED — no source files to scan**, explaining that "no debt indicators found" would describe an empty search, not the codebase
+3. Skill stops: no "May I write" prompt, no register write, no COMPLETE verdict
 
 **Assertions:**
-- [ ] Skill checks whether each register item's source reference still exists
-- [ ] Missing source locations result in items being flagged as RESOLVED
-- [ ] User confirms before resolved items are written
-- [ ] RESOLVED items are kept in the register (not deleted) for audit history
+- [ ] A zero-file scan is reported as NOT ASSESSED — no source files to scan
+- [ ] Output does not claim "no debt found" or a clean codebase
+- [ ] The register is not written and no write is offered
+- [ ] No COMPLETE verdict is emitted
 
 ---
 
-### Case 4: Edge Case — CRITICAL debt item surfaces prominently
+### Case 3b: Code Root Unresolved — NOT ASSESSED, nothing scanned on a guess
 
 **Fixture:**
-- `src/core/network_sync.gd` has a comment: `# FIXME(CRITICAL): race condition in sync buffer — can corrupt save data`
-- `docs/tech-debt-register.md` exists with 5 lower-severity items
+- `project.yaml` has no `engine.name`; `.claude/docs/technical-preferences.md` reads `[TO BE CONFIGURED]`
+- Both `src/` and `Source/` exist and hold source files, so the tree does not decide the root
+- `docs/tech-debt-register.md` exists with 3 entries
 
-**Input:** `/tech-debt`
+**Input:** `/tech-debt scan`
 
 **Expected behavior:**
-1. Skill scans source and finds the CRITICAL-tagged FIXME
-2. Skill presents the CRITICAL item at the top of the output — before the full table
-3. Skill asks user to acknowledge the critical item before proceeding
-4. After acknowledgment, skill presents full debt table and asks to write
-5. Register is updated with CRITICAL item at top; verdict REGISTER UPDATED
+1. The code root cannot be resolved per `.claude/docs/code-root-resolution.md`
+2. Skill reports `NOT ASSESSED — code root unresolved` and stops
+3. Neither directory is scanned on a guess; no "May I write" prompt, no register write, no COMPLETE verdict
 
 **Assertions:**
-- [ ] CRITICAL items appear at the top of the output, not buried in the table
-- [ ] Skill surfaces CRITICAL items before asking to write
-- [ ] User acknowledgment of the CRITICAL item is requested
-- [ ] CRITICAL severity is preserved in the written register entry
+- [ ] Verdict is `NOT ASSESSED — code root unresolved`
+- [ ] No debt findings are reported from a guessed root
+- [ ] The register is not written and no write is offered
 
 ---
 
-### Case 5: Gate Compliance — No gate; register updated only with approval
+### Case 4: Add Mode — User declines the write
 
 **Fixture:**
-- Inline scan finds 2 new TODOs; register has 3 existing items
-- `review-mode.txt` contains `full`
+- `docs/tech-debt-register.md` exists with 4 entries
+- `modes.automation` unset (collaborative)
 
-**Input:** `/tech-debt`
+**Input:** `/tech-debt add`
 
 **Expected behavior:**
-1. Skill scans source and reads register; compiles combined debt list
-2. No director gate is invoked regardless of review mode
-3. Skill presents sorted debt table to user
-4. Skill asks "May I write to `docs/tech-debt-register.md`?"
-5. User approves; register updated; verdict REGISTER UPDATED
+1. Skill asks in plain text for the description and affected files
+2. Skill uses `AskUserQuestion` for the category — six options, Architecture through Performance
+3. Skill uses `AskUserQuestion` for the fix effort — S, M, L, XL
+4. Skill uses `AskUserQuestion` for the impact if left unfixed — Low, Med, High, Critical
+5. Skill presents the complete new entry
+6. Skill asks "May I append this entry to `docs/tech-debt-register.md`?"
+7. User declines — nothing is written
+8. Verdict: **BLOCKED** — user declined write
 
 **Assertions:**
+- [ ] Category is collected with `AskUserQuestion` offering the six debt categories
+- [ ] Effort is collected with `AskUserQuestion` offering S / M / L / XL
+- [ ] Impact is collected with `AskUserQuestion` offering Low / Med / High / Critical, so `prioritize` can score the row
+- [ ] The full entry is shown before the append prompt
+- [ ] On decline the register is unchanged and the verdict is BLOCKED
+
+---
+
+### Case 4a: Add Mode — Matches an Existing Open Entry
+
+**Fixture:**
+- `docs/tech-debt-register.md` exists with an `Open` entry for the same file
+  and the same category as the one the user is about to add
+
+**Input:** `/tech-debt add`
+
+**Expected behavior:**
+1. Steps 1–5 of Case 4 run as usual
+2. **Match before appending:** before the append ask, the skill shows the
+   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
+
+**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
+
+---
+
+### Case 4b: Report Mode Without a Register — NOT ASSESSED
+
+**Fixture:**
+- `docs/tech-debt-register.md` does not exist
+
+**Input:** `/tech-debt report`
+
+**Expected behavior:**
+1. Skill looks for the register and does not find it
+2. Verdict: **NOT ASSESSED** — no register to report on; run `/tech-debt scan` first
+3. No trend or totals are printed and nothing is written
+
+**Assertions:**
+- [ ] Verdict is NOT ASSESSED, not a report of zero items or a "stable" trend
+- [ ] The output names `/tech-debt scan` as the way to create the register
+- [ ] No file is written
+
+---
+
+### Case 5: Prioritize in Full Review Mode — Scored, re-sorted, approved
+
+**Fixture:**
+- `project.yaml`: `modes.review_mode: full`
+- `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)
+
+**Input:** `/tech-debt prioritize`
+
+**Expected behavior:**
+1. Skill reads `docs/tech-debt-register.md`
+2. Each item is scored `impact ÷ effort` (Impact Low 1 … Critical 4; Effort S 1 … XL 4): TD-001 3.0, TD-003 2.0, TD-002 0.3; TD-004 is listed after them as "not scored — Effort not judged"
+3. The register is re-sorted by score and the skill recommends which items belong in the next sprint
+4. No director gate is invoked regardless of review mode
+5. Skill presents the re-prioritized register, then asks "May I write the re-prioritized register back to `docs/tech-debt-register.md`?"
+6. On approval the file is written
+7. Verdict: **COMPLETE** — register re-prioritized and saved
+
+**Assertions:**
+- [ ] Items are scored `impact ÷ effort` from their own columns and re-sorted: TD-001, TD-003, TD-002
+- [ ] TD-004 gets no invented score; it is listed as not scored, naming the missing Effort
+- [ ] A next-sprint recommendation is given
 - [ ] No director gate is invoked in any review mode
-- [ ] Debt table is presented before any write prompt
-- [ ] "May I write" prompt appears before file update
-- [ ] Write only occurs with explicit user approval
+- [ ] The write happens only after the "May I write" prompt is approved
+- [ ] Verdict is COMPLETE
 
 ---
 
 ## Protocol Compliance
 
-- [ ] Reads `docs/tech-debt-register.md` and scans `src/` before compiling
-- [ ] Deduplicates inline comments against existing register items
-- [ ] Sorts combined list by severity
-- [ ] Always asks "May I write" before updating register
+- [ ] Requires a subcommand; without one prints usage and stops with FAIL
+- [ ] `scan` resolves the code root per engine (`src/`, `Assets/`, `Source/`) and states the number of files covered
+- [ ] A zero-file or unresolved-root scan is NOT ASSESSED and writes nothing
+- [ ] Every register write is preceded by a "May I write" / "May I append" prompt naming `docs/tech-debt-register.md`, after the content is shown
+- [ ] `scan` appends and never overwrites existing entries; a finding matching an `Open` row updates it, and an `Open` row whose pattern is gone is proposed `Resolved [date]`, never deleted
+- [ ] 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
-- [ ] Verdict is REGISTER UPDATED or NO NEW DEBT FOUND
+- [ ] Ends with the Phase 3 next steps (`/sprint-plan`, `/tech-debt report`)
 
 ---
 
 ## Coverage Notes
 
-- The case where `src/` is empty or absent is not tested; behavior follows
-  the NO NEW DEBT FOUND path for the inline scan, but register items would
-  still be read and presented.
-- TODO comments without severity tags are treated as LOW severity by default;
-  this classification detail is an implementation concern, not tested here.
+- `report` mode with a register (read-only summary by category and effort,
+  added and resolved counts from each row's `Added` and `Resolved` dates,
+  flagging items older than 3 sprints, Verdict COMPLETE — debt report generated)
+  is not tested here.
+- Unity and Unreal scans differ only in the resolved root (`Assets/`,
+  `Source/`) and are not tested separately.