@tekyzinc/gsd-t 4.17.10 → 4.19.10

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.19.10] - 2026-07-07
+
+### Added — `/gsd-t-stories`: dev-team handoff user stories in the Tekyz format
+
+New standalone command that generates a development-team handoff document in the Tekyz user-stories format from any source — a scan register, a requirements doc, a design contract, or a reverse-engineered codebase. Reverse-engineered from the Tekyz Compass sample PRD: front matter → Application Flow Overview → User Stories grouped under Epics (id, story, workflow, grouped acceptance criteria, per-story flow diagram, mapped test-case table) → Scope Summary. Diagrams are authored as Mermaid but embedded as rendered PNGs (matching the sample's embedded-image flow charts), via `@mermaid-js/mermaid-cli`; output to `share/<Repo>-user-stories.md` (+ optional `.docx` via pandoc).
+
+- `commands/gsd-t-stories.md`: the new command (input classification, epic/story decomposition, Mermaid→PNG→embed pipeline, markdown + optional docx output).
+- `templates/playbooks/tekyz-user-stories-format.md`: bundled format reference (the exact structure + wording conventions).
+- `commands/gsd-t-help.md`, `README.md`, `templates/CLAUDE-global.md`: command reference + standalone-list ripple.
+- `test/filesystem.test.js`: command counts 52→53, gsdt 46→47.
+
+Distinct from `/gsd-t-prd` (which writes the internal `docs/prd.md`) — this is an external client/dev deliverable. Suite 2631/2631.
+
+## [4.18.10] - 2026-07-03
+
+### Added — Scan Consolidation Opportunities + type-grouped register; init-scan-setup repo adoption
+
+The scan register is now organized by TD **type within each severity**, and a new **Consolidation** phase (opus + graph-assisted) appends a **🧩 Consolidation Opportunities** section listing high-confidence clusters of findings that share a root and should be fixed as one workstream. `/gsd-t-init-scan-setup` gains a **Step 0 "Adopt a Foreign Repo"** sanitization pass and a **Step 4a completeness check**, so repos built by others (or plain Claude) run correctly on this machine and an incomplete/hand-driven scan is caught and re-run.
+
+- `templates/workflows/gsd-t-scan.workflow.js`: register `fmtChunks` groups by `typeOf(area)` within severity via a shared `orderedFindings` ordering (so consolidation TD-N ids match the register exactly); new `Consolidation` phase (opus, graph-assisted via `who-imports`/`who-calls`/`blast-radius`) emits `CG-N` groups (members/sharedRoot/recommendedAction/effort) appended at the end; `meta.phases` +1. Best-effort — any failure leaves the register intact.
+- `commands/gsd-t-init-scan-setup.md`: Step 0 adoption (settings reconciled vs global, CLAUDE.md regenerated from fresh scan, no foreign/stale workflow-script execution) + Step 4a post-scan completeness check + 8-phase scan description + corrected graph note (`graphDB/`).
+- `commands/gsd-t-scan.md`: synthesis/consolidation phase description.
+- `.gsd-t/backlog.md`: split logging item #48 → #48 (trace) + #49 (audit) with full specs.
+- Lints green: M71 runtime-native, M85 tier-policy, M76 ascii. Suite 2631/2631.
+
 ## [4.17.10] - 2026-07-01
 
 ### Changed — `/gsd-t-estimate` v2: generalized + supervised + adversarial, with a permanent Sheets service account

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.17.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.19.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.
@@ -187,6 +187,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/gsd-t-gap-analysis` | Requirements gap analysis — spec vs. existing code | Manual |
 | `/gsd-t-promote-debt` | Convert techdebt items to milestones | Manual |
 | `/gsd-t-estimate` | Turn any work doc (scan, requirements, feature/app spec) into a Tekyz client estimate (Google Sheet: T-Shirt Size + Team Mix) + matching PRD — supervised, with an operator-arbitrated Estimate Red Team | Manual |
+| `/gsd-t-stories` | Generate a dev-team handoff doc in the Tekyz user-stories format (stories + workflows + acceptance criteria + Mermaid flow diagrams + mapped test cases) from any source | Manual |
 | `/gsd-t-populate` | Auto-populate docs from existing codebase | Manual |
 | `/gsd-t-design-decompose` | Decompose design into element/widget/page contracts | Manual |
 

package/commands/gsd-t-help.md

@@ -364,6 +364,12 @@ Use these when user asks for help on a specific command:
 - **Updates**: the Tekyz estimate Google Sheet + `share/<Repo>-PRD-*.md` (and, if renumbered, the source doc/docs/scan files) + optional `share/<Repo>-estimate-redteam-notes.md`
 - **Use when**: You need a client-facing paid estimate + PRD (T-shirt sizing, dollar range, sign-off) from a scan OR a requirements/feature/app spec. **SUPERVISED** — judgment phases (sizing, adjustments, PRD, Red Team) pause for your review; **you are the final arbiter** of an Estimate Red Team that challenges the numbers. Rate + sheet template + factors are parameterized (default Tekyz). Encodes the Tekyz playbook (`~/.claude/playbooks/tekyz-estimation-and-prd-playbook.md`)
 
+### stories
+- **Summary**: Generate a dev-team handoff document in the Tekyz user-stories format — discrete user stories with workflows, grouped acceptance criteria, per-story flow diagrams (Mermaid rendered to embedded images), and mapped test-case tables — from any source (scan register, requirements doc, design contract, or a reverse-engineered codebase)
+- **Auto-invoked**: No
+- **Updates**: new deliverable `share/<Repo>-user-stories.md` (+ optional `.docx` via pandoc) + `share/media/*.png` (rendered diagrams) + `.gsd-t/user-stories/diagrams/*.mmd`
+- **Use when**: You need to hand a development team discrete, testable user stories in the Tekyz handoff style. Distinct from `/gsd-t-prd` (which writes the INTERNAL `docs/prd.md`) — this is an EXTERNAL client/dev deliverable. Diagrams are authored as Mermaid but embedded as rendered images (needs `@mermaid-js/mermaid-cli`). Format reference: `~/.claude/playbooks/tekyz-user-stories-format.md`
+
 ### populate
 - **Summary**: Auto-populate all living docs from existing codebase analysis
 - **Auto-invoked**: No

package/commands/gsd-t-init-scan-setup.md

@@ -4,6 +4,48 @@ One command to fully onboard a project into GSD-T. Combines project directory se
 
 Can be run from anywhere — does not require being in the project folder first.
 
+## Entry States (READ FIRST — the command is IDEMPOTENT and SAFE to re-run)
+
+This command behaves **identically and unambiguously** across all three entry states:
+
+- **(A) Greenfield** — brand-new project, no code, no `.gsd-t/`.
+- **(B) Existing, new to this machine** — has code and/or a `.gsd-t/` dir but is not in this machine's registry.
+- **(C) Already-registered, being re-run.**
+
+**Existing `.gsd-t/` artifacts are NEVER a reason to skip scan or setup.** The ONLY thing "already exists" skips is **re-creating directory structure** (Step 3). Steps 4 (scan) and 5 (setup) **ALWAYS run**, on every invocation, in every entry state.
+
+**Re-running is expected and safe.** Archiving an existing `techdebt.md` and regenerating scan docs + CLAUDE.md is the **designed behavior** of this command — it is NOT a destructive action and does NOT require user approval. Stale scan docs from a prior milestone are the exact failure this command exists to prevent. Never stop to ask permission for the archive/regenerate steps.
+
+## Step 0: Adopt a Foreign Repo — Sanitize Inherited Context (MANDATORY, runs FIRST)
+
+**Why:** projects are frequently imported that were built by others — with plain Claude Code, or with GSD-T on a *different* machine/context. Such a repo arrives carrying **foreign context**: a committed `.claude/settings.json`, a `CLAUDE.md` authored in another environment, and `.gsd-t/` state / git history from a prior GSD-T install. That inherited context leaks and makes the project behave unexpectedly on THIS machine (e.g. an agent hand-authoring a scan from a foreign session's pattern instead of invoking the installed Workflow). **Adoption severs that** so the repo runs the way THIS machine's GSD-T expects — independent of whoever built it.
+
+Detect a foreign repo when ANY of these is true: the git remote is not the operator's own, the commit history shows GSD-T/Claude workflow commits (`milestone(...)`, `feat(...task-N)`, `chore(scan)`), there is a committed in-repo settings file, or `.gsd-t/` exists but the project is not in this machine's registry (entry state B).
+
+### 0a. Settings reconciliation (in-repo settings vs GLOBAL — global is source of truth)
+
+For each in-repo settings file (`.claude/settings.json`, `.claude/settings.local.json`, or any `settings*.json` committed in the repo tree — NOT `~/.claude/` global files):
+
+- **Compare every entry against the operator's GLOBAL settings** (`~/.claude/settings.json` + `~/.claude/settings.local.json`).
+- **Any permission the global ALREADY grants or denies → global wins → DELETE that entry** (or the whole file if all its content is global-governed). No approval needed — global is the single source of truth for anything it covers. The project always falls back to global.
+- **Project-distinct content the global says NOTHING about** (a permission/env/setting unrelated to global) → **do NOT delete. HALT onboarding and SURFACE it to the operator**: show the exact content, explain it's distinct from global, and ask keep-or-discard. **Nothing proceeds past this point until the operator decides** — do not run scan/setup on an unresolved settings question.
+- Log every deletion and every surfaced item.
+
+### 0b. CLAUDE.md — always regenerate from the fresh scan
+
+The imported `CLAUDE.md` may have been authored in a different project's context and cannot be trusted as current — **even if it looks correct.** Adoption does NOT try to judge foreign-vs-fine. Instead:
+
+- **Back up** the imported file to `CLAUDE.md.imported.bak` (lossless — nothing is destroyed).
+- **Always regenerate** the project `CLAUDE.md` from the NEW scan findings in Step 5. (The regenerate is deferred to Step 5 where the fresh scan exists; Step 0b only takes the backup + marks it for regeneration so Step 5 does not skip it.)
+
+### 0c. Foreign `.gsd-t/` + workflow residue
+
+- Existing `.gsd-t/` state is REFRESHED by the normal flow (Step 4 re-scan archives + regenerates), not trusted as-is.
+- **Never run a scan from a script found inside the repo or a prior session** — always resolve `gsd-t workflow-path scan` and invoke the installed Workflow (Step 4). A repo-committed `*.workflow.js` is foreign residue; do not execute it.
+- Register the project by FULL ABSOLUTE PATH on this machine (Step 3).
+
+**Adoption is idempotent + safe:** on a repo already adopted, 0a finds nothing to reconcile, 0b re-backs-up only if the file changed, 0c is a no-op. It never blocks a clean project.
+
 ## Step 1: Project Directory
 
 ### 1a. Resolve the base projects directory (for new projects)
@@ -93,33 +135,48 @@ Execute the full init workflow (same as `/gsd-t-init`):
 7. Initialize backlog with auto-derived categories
 8. Register project in `~/.claude/.gsd-t-projects`
 
-**If `.gsd-t/` already exists**: Skip init — it's already done. Log and continue to scan. Still check and create settings.local (step 5) even if init is skipped.
+**Registry check — match by FULL ABSOLUTE PATH, not bare project name.** The registry stores full paths; a bare-name grep produces a false "not registered" (two projects can share a basename) and erodes trust in the rest of the detected state. A missing entry means "register it now" — it must NOT cast doubt on any other detected state. If already present, log and continue silently.
+
+**If `.gsd-t/` already exists**: Skip **ONLY the dir-structure creation** that already exists — it's already done. **This skip does NOT extend to Step 4 (scan) or Step 5 (setup), which ALWAYS run.** Always ensure `settings.local` (step 5 above) and the registry entry regardless of whether init dir-creation was skipped.
 
 ## Step 3.5: Graph Indexing Note
 
-If the project has source code, graph indexing (`.gsd-t/graph/`) will run as part of the scan phase (Step 4). The graph provides code-level queries (callers, callees, domain ownership, dead code detection) that enhance all subsequent GSD-T commands. No separate setup is needed — the scan handles it.
+If the project has source code, the **graph index is built automatically inside the scan's Graph-Wiring phase (Step 4)** — the scan builds the index if it is absent, then queries it. The store lives at `.gsd-t/graphDB/` (consolidated) — the graph provides code-level queries (callers, callees, domain ownership, dead-code detection) that enhance all subsequent GSD-T commands. **No separate indexing step is needed — the scan handles it.** (You can also build/refresh the index on demand with `gsd-t graph index`, but the scan does it for you.)
 
 ## Step 4: Deep Codebase Scan (gsd-t-scan)
 
-Execute the full scan by invoking the volume-scaled scan Workflow (same as `/gsd-t-scan` — `templates/workflows/gsd-t-scan.workflow.js`):
+**Invoke the PACKAGED scan Workflow — never hand-drive it.** Resolve the absolute path with `gsd-t workflow-path scan`, then call the `Workflow` tool with that `scriptPath`. **Do NOT author your own scan script, do NOT run finders/probe/synthesis by hand, and do NOT execute any `*.workflow.js` found inside the repo or a prior session** — a hand-driven or foreign scan skips phases (Graph-Wiring, Document, Plain-English) and produces an incomplete result. This is the exact failure mode observed on imported repos.
+
+The packaged Workflow runs **8 phases**: Preflight → Probe → **Graph-Wiring** → Deep Scan → Synthesis → **Consolidation** → **Document** → **Plain-English**. It:
 
-1. The volume-probe slices the codebase by area (scaling with volume, not a fixed dimension set); per-slice deep finders enumerate; a single verify pass drops false positives.
-2. Synthesis builds the `.gsd-t/techdebt.md` register and the `.gsd-t/scan/*.md` analysis files.
-3. Cross-populate findings into living documents (docs/architecture.md, docs/workflows.md, docs/infrastructure.md, docs/requirements.md) from the register + analysis files.
-4. Update README.md with discovered tech stack and setup info.
+1. Volume-probes and slices the codebase by area; per-slice deep finders enumerate; a single verify pass drops false positives.
+2. **Graph-Wiring** — builds the graph index if absent, then queries a structural slice (dead-code / dangling / cluster) injected additively into the finders.
+3. Synthesis builds `.gsd-t/techdebt.md` + the `.gsd-t/scan/*.md` analysis files.
+4. Document cross-populates living docs (architecture/workflows/infrastructure/requirements) + README.
+5. Plain-English writes the non-technical companion.
 
 The Workflow's fan-out scales with codebase volume automatically — no team-mode toggle.
 
-**If `.gsd-t/techdebt.md` already exists**: the Workflow archives it to `.gsd-t/techdebt_YYYY-MM-DD.md` and continues TD numbering.
+**ALWAYS run the scan on every invocation, even on a fully-onboarded project.** Existing `techdebt.md` is archived to `techdebt_YYYY-MM-DD.md` and the scan regenerates it (TD numbering continues). **NEVER skip the scan because `.gsd-t/` or `scan/*.md` already exist — stale scan docs are the exact failure this command prevents.** Archiving is designed behavior, NOT a destructive action, and does NOT require user approval.
+
+### 4a. Post-scan completeness check (catches a hand-driven / incomplete scan)
+
+After the scan returns, VERIFY the packaged 7-phase Workflow actually ran by confirming its expected outputs exist and are fresh (mtime within this run):
+
+- `.gsd-t/techdebt.md` (regenerated) **and** at least the 5 `.gsd-t/scan/*.md` dimension files
+- the merged living docs (architecture/workflows/infrastructure/requirements touched this run)
+- the plain-English companion (`.gsd-t/techdebt_in_plain_english.md` or equivalent)
+
+**If any are missing → LOUD failure, do not proceed:** "⛔ Incomplete scan — the packaged Workflow's Document / Plain-English / Graph-Wiring outputs are absent. This means the scan was hand-driven or a foreign/stale script ran instead of the installed Workflow. Re-run: resolve `gsd-t workflow-path scan` and invoke the `Workflow` tool." Then re-invoke correctly, once.
 
 ## Step 5: Generate Project CLAUDE.md (gsd-t-setup)
 
-Execute the full setup workflow (same as `/gsd-t-setup`):
+Execute the full setup workflow (same as `/gsd-t-setup`). **ALWAYS run — regenerate/refresh the project CLAUDE.md from the NEW scan findings; do NOT assume an existing CLAUDE.md is current.** If Step 0b flagged an imported CLAUDE.md (backed up to `CLAUDE.md.imported.bak`), this regeneration is what replaces it with a machine-correct version — do NOT skip it.
 
 1. Read global `~/.claude/CLAUDE.md` to understand what's already covered
-2. Use scan findings + auto-detection to populate project-specific sections
+2. Use the **fresh** scan findings + auto-detection to populate project-specific sections
 3. Remove any global duplicates from the project CLAUDE.md
-4. Generate and write the optimized CLAUDE.md
+4. Generate and write the optimized CLAUDE.md (refresh the existing one — don't skip because a CLAUDE.md already exists)
 
 At Level 3: skip questions that were auto-detected — only ask what's truly unknown.
 At Level 1-2: ask all targeted questions per the setup workflow.
@@ -136,7 +193,11 @@ Project Onboarded: {project name}
   Scan:     {N} tech debt items ({critical} critical, {high} high, {medium} medium, {low} low)
   Setup:    CLAUDE.md generated ({N} sections)
   Registry: {registered | already registered}
+```
+
+For an already-onboarded project (entry state B/C), the report reads as **"re-scanned and refreshed,"** never "nothing to do": show the archived `techdebt_YYYY-MM-DD.md` path, the fresh finding counts, and that CLAUDE.md was regenerated.
 
+```
 Next steps:
   → Review .gsd-t/techdebt.md for critical items
   → /gsd-t-milestone to define your first milestone
@@ -145,7 +206,7 @@ Next steps:
 
 ### Autonomy Behavior
 
-**Level 3 (Full Auto)**: Run all steps without pausing. Only stop if git remote is needed (requires user input) or if a scan reveals critical security blockers.
+**Level 3 (Full Auto)**: Run all steps without pausing. Only stop if git remote is needed (requires user input) or if a scan reveals critical security blockers. **"Already onboarded" NEVER means "nothing to do" — it means "re-scan and refresh."** Do NOT pause to ask permission for the archive/regenerate steps; re-running is expected and safe.
 
 **Level 1-2**: Pause after each major step (init, scan, setup) for user review before continuing.
 

package/commands/gsd-t-scan.md

@@ -41,7 +41,7 @@ The current scan architecture (enumerate + per-file deep-finders) is **KEPT FULL
 preflight → volume-probe → pipeline(per-slice deep finder → single verify) → synthesis → document → render
 ```
 
-**Why volume-scaled (M66):** the legacy scan hard-coded exactly 5 teammates (one per dimension) with zero volume scaling — a 5-file repo and a 1,809-file repo both got 5 agents, so a single `quality` agent sampled the top ~5 issues across the whole codebase and stopped. The volume-probe stage now measures the codebase (files, routes, ORM tables, components, top-level dirs) and carves it into **narrow slices** — one deep-finder agent per area, scaling from 1-3 slices on a tiny repo to 15-40 on a large one. Each finder OWNS its slice and is mandated to *enumerate, not sample*. A single verify pass confirms each finding against the real code and drops false positives. Synthesis dedups/merges/re-ranks into `techdebt.md` and continues TD numbering from the archived prior register.
+**Why volume-scaled (M66):** the legacy scan hard-coded exactly 5 teammates (one per dimension) with zero volume scaling — a 5-file repo and a 1,809-file repo both got 5 agents, so a single `quality` agent sampled the top ~5 issues across the whole codebase and stopped. The volume-probe stage now measures the codebase (files, routes, ORM tables, components, top-level dirs) and carves it into **narrow slices** — one deep-finder agent per area, scaling from 1-3 slices on a tiny repo to 15-40 on a large one. Each finder OWNS its slice and is mandated to *enumerate, not sample*. A single verify pass confirms each finding against the real code and drops false positives. Synthesis dedups/merges/re-ranks into `techdebt.md` (items **grouped by type within each severity** — Security/Vulnerability, Dead Code, Duplication, etc.) and continues TD numbering from the archived prior register. A **Consolidation** phase (opus + graph-assisted) then appends a **🧩 Consolidation Opportunities** section at the END of the register: high-confidence clusters of TDs that share a root and should be fixed as ONE workstream (duplicate-function families, batch dead-code deletions, a guard missing across N sites), each a candidate for a single consolidation milestone.
 
 **Deep document stage (M67):** after the register lands, a `document` phase fans out **one agent per document**, each drawing on the same slices + verified findings, to deterministically produce the full living-document set — `docs/architecture.md` (component map per feature-domain slice), `docs/workflows.md` (a user journey per slice), `docs/infrastructure.md`, `docs/requirements.md`, `README.md` (all merge-not-overwrite) — plus the five `.gsd-t/scan/*.md` dimension files (`architecture`, `security`, `quality`, `business-rules`, `contract-drift`) in the renderer's parsed formats. This replaces M66's non-deterministic "lead-agent follow-on" so the documents are as thorough as the register. The deterministic `bin/scan-*.js` renderers (schema extraction, diagrams, HTML report) run last, reading the deep `.gsd-t/scan/architecture.md`.
 

package/commands/gsd-t-stories.md

@@ -0,0 +1,68 @@
+# GSD-T: Stories — Dev-Handoff User Stories (Tekyz format) from any source
+
+You are generating a **development-team handoff document** in the Tekyz user-stories format: discrete user stories with workflows, grouped acceptance criteria, per-story flow diagrams (Mermaid rendered to embedded images), and mapped test cases. Input can be a GSD-T **scan register**, a **requirements doc**, a **design contract**, or an **existing codebase** (reverse-engineered). `$ARGUMENTS` may carry `--input <path>`, `--source <scan|requirements|design|code>`, `--prefix <PREFIX>`, `--phase-filter <MVP|...>`, `--docx`.
+
+**Canonical format reference (READ FIRST):** `~/.claude/playbooks/tekyz-user-stories-format.md` if present, else the bundled `templates/playbooks/tekyz-user-stories-format.md` in the GSD-T package. It encodes the exact structure + wording conventions reverse-engineered from the Tekyz sample (`Compass_Sample_PRD_2.docx`). This command FILLS that format from the real input.
+
+> **Client/dev-team deliverable — distinct from `/gsd-t-prd`.** `/gsd-t-prd` writes the INTERNAL `docs/prd.md` that feeds the GSD-T pipeline. THIS command emits an EXTERNAL, dev-ready handoff doc in the Tekyz user-story style, saved to `share/`.
+
+## Step 0: Inputs + Source Classification
+
+1. **Resolve the input** (from `$ARGUMENTS --input`, else auto-detect in priority order): `.gsd-t/techdebt.md` (scan) → `docs/requirements.md` → `.gsd-t/contracts/design-contract.md` / `.gsd-t/contracts/design/` → the codebase itself. If none usable → ask the user what to document.
+2. **Classify the source** so the extraction method matches:
+   - **scan register** → stories derive from the functional gaps/features implied by findings (each cluster of related TDs → a story; Reqs cross-ref the TD-N ids).
+   - **requirements doc** → each requirement / requirement-group → a story (Reqs cross-ref R-N/FR-N).
+   - **design contract** → each screen/widget/flow → a story.
+   - **codebase (reverse-engineer)** → walk real features (routes, pages, flows) and reverse-engineer the discrete user stories + test cases from what's built. **Use the code graph** (`gsd-t graph cluster` / `who-imports` / `who-calls`) to find feature clusters and real interaction paths — do NOT grep-guess the architecture.
+3. **Derive the story-id `PREFIX`** from the product name (Compass→`CMPS`, NiceNote→`NN`, Newman Avatar→`NAV`) unless `--prefix` is given. Confirm with the user.
+4. **Confirm scope** — which phases/epics to include — before generating.
+
+## Step 1: Application Flow Overview (§1)
+
+Produce the numbered end-to-end user journey (1..N major steps, plain language). Then author the **app-flow chart** as a single Mermaid flowchart of the whole journey and render+embed it (Step 4). This is the reader's map before the story detail.
+
+## Step 2: Decompose into Epics + Stories (§2)
+
+Group functionality into **Epics** (`EP-NN: <name>`), each with a `Phase:`. Under each epic, emit discrete stories. **A story is ONE coherent capability a user exercises** — not a whole feature area, not a single UI control. Right granularity = the sample's (e.g. "Avatar renders full-screen with state indicators" is one story; "Session controls: pause/resume/end" is another).
+
+For EACH story, author in EXACTLY this order (per the format reference):
+
+1. **`<PREFIX>-NNN — <Story Title>`** (sequential, zero-padded).
+2. **Meta line** — `*Phase: … | Reqs: <source ids> | Test Cases: <N>*`. `Reqs:` cross-references the source (TD-N / R-N / FR-N); `Test Cases:` = row count of this story's table.
+3. **Story:** `*As a <role>, I want <capability>, so that <benefit>.*` (strict template, one sentence.)
+4. **Workflow:** numbered concrete interaction steps (user action → system response), present tense.
+5. **Acceptance Criteria:** bulleted, **grouped by sub-area** with a bold sub-heading per group; include error/edge/recovery groups. Each bullet one testable assertion.
+6. **Flow Diagram:** a per-story Mermaid flowchart of THIS story's workflow → rendered PNG → embedded (Step 4).
+7. **Mapped Test Cases:** table `TC ID | Type | Test Title | Expected Result`. `TC-NNN` sequential across the whole doc; `Type` ∈ {Positive, Negative, Edge}; cover happy-path + failure + boundary; every acceptance-criteria group represented by ≥1 test case.
+
+**No confabulation** (`feedback_no_confabulated_examples`): every story, workflow step, and test case must trace to something in the actual input source. If the source is silent on a needed detail, mark it a `[TODO: confirm with client]` — never invent product specifics.
+
+## Step 3: Scope Summary (§3)
+
+A table mapping every story → phase → epic: `| Story ID | Title | Phase | Epic |`. Gives the team the MVP-vs-later-phase picture at a glance.
+
+## Step 4: Diagrams — Mermaid rendered to EMBEDDED images (MANDATORY method)
+
+Per the standing directive, diagrams are authored as Mermaid but **embedded as rendered images** (matching the sample's `<img>` flow charts) — NOT left as raw Mermaid text.
+
+1. Write each diagram's Mermaid source to `.gsd-t/user-stories/diagrams/<name>.mmd` (app-flow = `app-flow`, per-story = `<PREFIX>-NNN-flow`).
+2. Render each to PNG beside the deliverable: `mmdc -i <src>.mmd -o share/media/<name>.png` (Mermaid CLI `@mermaid-js/mermaid-cli`; fall back to `npx @mermaid-js/mermaid-cli -i … -o …`).
+3. **If `mmdc` is unavailable → HALT** and tell the user to install it (`npm i -g @mermaid-js/mermaid-cli`). Do NOT silently ship raw Mermaid where an embedded image is expected (`feedback_no_silent_degradation`).
+4. Embed each rendered PNG in the markdown at its `Flow Diagram:` / §1 position: `![Flow Diagram](media/<name>.png)`.
+5. Keep the `.mmd` source (editable, version-controllable) alongside the PNG.
+
+## Step 5: Assemble + Deliver
+
+1. Assemble front matter (product, "Prepared by Tekyz Inc.", version, source-of-truth note; SAMPLE disclaimer only if illustrative) + §1 + §2 + §3.
+2. **Write the markdown** to `share/<Repo>-user-stories.md`, with rendered diagram PNGs in `share/media/`.
+3. **If `--docx`** (or the user wants Word): convert with `pandoc share/<Repo>-user-stories.md -o share/<Repo>-user-stories.docx` — pandoc embeds the PNGs as real Word images, matching the handoff sample. Report if pandoc is missing (don't fail the markdown).
+4. **Report:** story count, epic count, total test cases, diagram count, and the output paths.
+
+## Document Ripple
+
+- New deliverable(s): `share/<Repo>-user-stories.md` (+ `.docx` if requested) + `share/media/*.png` + `.gsd-t/user-stories/diagrams/*.mmd`.
+- No living-doc changes (this is an external handoff artifact) — but log a `.gsd-t/progress.md` Decision Log entry noting the deliverable + source.
+
+## ▶ Next Up
+
+Standalone command — no auto-successor. After generating, hand the `share/<Repo>-user-stories.md` (or `.docx`) to the development team.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.17.10",
+  "version": "4.19.10",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -460,7 +460,7 @@ Add `**Also available:**` with `- /gsd-t-{alt} — {desc}` lines if alternatives
 | `setup` | `status` | |
 | `design-decompose` | `design-build` | `partition` (if domains needed first) |
 
-Commands with no successor (standalone): `quick`, `debug`, `brainstorm`, `status`, `help`, `resume`, `prompt`, `log`, `health`, `pause`, `estimate`, backlog commands.
+Commands with no successor (standalone): `quick`, `debug`, `brainstorm`, `status`, `help`, `resume`, `prompt`, `log`, `health`, `pause`, `estimate`, `stories`, backlog commands.
 
 Skip the hint if auto-advancing (Level 3 mid-wave) — only show when the user needs to manually invoke the next step.
 

package/templates/playbooks/tekyz-user-stories-format.md

@@ -0,0 +1,127 @@
+# Tekyz User-Stories / Dev-Handoff PRD Format
+
+> The canonical format for a Tekyz **development-team handoff** document: discrete user
+> stories with workflows, grouped acceptance criteria, per-story flow diagrams, and mapped
+> test cases. Reverse-engineered from `Compass_Sample_PRD_2.docx` (the sample Tekyz uses to
+> illustrate its requirements-documentation process). `/gsd-t-user-stories` emits THIS format.
+>
+> This is a REFERENCE for structure + exact wording conventions — not the content. The
+> command fills it from the actual input source (scan / requirements / design / codebase).
+
+---
+
+## Document skeleton (in order)
+
+```
+FRONT MATTER
+1. Application Flow Overview        (numbered end-to-end journey + app-flow chart)
+2. User Stories — Detailed Requirements
+     EP-NN: <Epic Name>            (epic grouping)
+       Phase: <MVP | Phase 1 | ...>
+       <PREFIX>-NNN — <Story Title>
+         meta line
+         Story:                    (As a … I want … so that …)
+         Workflow:                 (numbered steps)
+         Acceptance Criteria:      (grouped by sub-area, bulleted)
+         Flow Diagram:             (rendered Mermaid PNG, embedded as <img>)
+         Mapped Test Cases:        (table)
+3. <Phase> vs <Phase> Scope Summary  (story→phase→epic table)
+```
+
+---
+
+## FRONT MATTER (verbatim conventions)
+
+```
+**<PRODUCT NAME>**
+
+<one-line product descriptor>
+
+Product Requirements Document
+
+**Prepared by Tekyz Inc.**
+
+Version <X.Y> — <source-of-truth note, e.g. "Design file v2.x as source of truth">
+```
+
+If the doc is illustrative/sample, include the italic SAMPLE DOCUMENT disclaimer block.
+
+---
+
+## §1 — Application Flow Overview
+
+A numbered list (1..N) naming each major step of the end-to-end user journey in plain
+language (e.g. "First-Time User Launch: App opens directly into … onboarding"). Follow with:
+- an **app-flow chart** — a single Mermaid flowchart of the whole journey, rendered to PNG
+  and embedded (`![Application Flow](media/app-flow.png)`), matching the sample's companion chart.
+- the italic note that a complete flow chart accompanies the document.
+
+---
+
+## §2 — User Stories (the core; repeat per story)
+
+Group stories under **Epics**: `**EP-01: <Epic Name>**` then `**Phase: <phase>**`.
+
+Each story, in EXACTLY this order:
+
+**Story ID + title:** `**<PREFIX>-NNN — <Story Title>**`
+- `<PREFIX>` is a per-project story-id prefix (Compass used `CMPS`). Derive from the product
+  name (e.g. NiceNote → `NN`, Newman Avatar → `NAV`). Sequential, zero-padded to 3.
+
+**Meta line** (italic, pipe-separated):
+`*Phase: <phase> | Reqs: <R-… list> | Test Cases: <N>*`
+- `Reqs:` cross-references source requirement ids (from a scan register's TD-N, a requirements
+  doc's R-N/FR-N, or synthesized ids). `Test Cases:` = count of rows in the Mapped Test Cases table.
+
+**Story:** one sentence, italic, strict template:
+`*As a <role>, I want <capability>, so that <benefit>.*`
+
+**Workflow:** numbered steps (1..N) describing the concrete interaction sequence — what the
+user does and what the system does in response. Present tense, specific.
+
+**Acceptance Criteria:** bulleted, **grouped by sub-area** with a bold sub-heading per group
+(e.g. `**Talking State:**`, `**Error and Recovery:**`). Each bullet is a single testable
+assertion (state changed / content shown / constraint met). Include error/edge/recovery groups.
+
+**Flow Diagram:** a per-story Mermaid flowchart of THIS story's workflow, rendered to PNG and
+embedded (`![Flow Diagram](media/<PREFIX>-NNN-flow.png)`) — matching the sample's per-story `<img>`.
+
+**Mapped Test Cases:** a markdown table with columns **TC ID | Type | Test Title | Expected Result**.
+- `TC ID`: `TC-NNN` sequential across the whole document.
+- `Type`: one of **Positive | Negative | Edge**.
+- Cover the happy path (Positive), failure modes (Negative), and boundaries (Edge). Every
+  acceptance-criteria group should be represented by at least one test case.
+
+---
+
+## §3 — Scope Summary
+
+A table mapping every story to its phase + epic, so a team sees MVP vs later-phase scope at a glance:
+
+`| Story ID | Title | Phase | Epic |`
+
+---
+
+## Diagram pipeline (Mermaid → embedded image)
+
+Per the user directive, diagrams are **authored as Mermaid but EMBEDDED as rendered images**
+(like the sample's `<img>` flow charts) — not left as raw Mermaid text.
+
+1. Write each diagram's Mermaid source to `.gsd-t/user-stories/diagrams/<name>.mmd`.
+2. Render to PNG with the Mermaid CLI: `mmdc -i <name>.mmd -o media/<name>.png` (installed:
+   `@mermaid-js/mermaid-cli`; fall back to `npx @mermaid-js/mermaid-cli`). If `mmdc` is
+   unavailable, HALT and tell the user to install it — do NOT silently ship raw Mermaid where
+   an embedded image is expected (no-silent-degradation).
+3. Embed the PNG in the markdown: `![Flow Diagram](media/<name>.png)`.
+4. On `.docx` conversion, pandoc embeds these PNGs as real Word images — matching the sample.
+
+Keep the `.mmd` source (version-controllable, editable) alongside the rendered PNG.
+
+---
+
+## Output
+
+- Markdown deliverable → `share/<Repo>-user-stories.md` (GSD-T share convention), with a
+  `media/` dir of rendered diagram PNGs beside it.
+- Optional `.docx` (matching the handoff sample) via `pandoc share/<Repo>-user-stories.md
+  -o share/<Repo>-user-stories.docx` — embeds the PNGs as Word images.

package/templates/workflows/gsd-t-scan.workflow.js

@@ -34,7 +34,8 @@ export const meta = {
     { title: "Probe",         detail: "volume probe → per-area slice list", model: "sonnet" },
     { title: "Graph-Wiring",  detail: "M94-D6: build index if absent + query structural slice (dead-code/dangling/cluster) → inject into finders ADDITIVELY; fallback announced on graph-unavailable", model: "haiku" },
     { title: "Deep Scan",     detail: "pipeline: per-slice deep finder (graph-augmented when wired) → single verify" },
-    { title: "Synthesis",     detail: "archive prior + write fresh register + git", model: "opus" },
+    { title: "Synthesis",     detail: "archive prior + write fresh register (type-grouped within severity) + git", model: "opus" },
+    { title: "Consolidation", detail: "opus + graph-assisted: high-confidence clusters of TDs to fix as one workstream → appended to register", model: "opus" },
     { title: "Document",      detail: "living docs + 5 dimension files (per-doc fan-out)" },
     { title: "Plain-English", detail: "non-technical companion: batched gen + severity-grouped chunked write" },
   ],
@@ -785,6 +786,35 @@ function ascii(s) {
     .replace(/…/g, "...")              // ellipsis
     .replace(/[ \t]+\n/g, "\n");            // tidy trailing whitespace
 }
+
+// Register ordering — SINGLE source of truth so the formatter's TD-numbering and the
+// consolidation stage's TD references stay identical. Within each severity, findings
+// are sub-grouped by TYPE (derived from `area`). typeOf() maps free-text area→bucket;
+// unmatched → "Other". `orderedFindings` is the final, numbered sequence (TD-tdStart..).
+function typeOf(f) {
+  const a = String(f.area || "").toLowerCase() + " " + String(f.title || "").toLowerCase();
+  if (/(vuln|idor|auth|injection|xss|csrf|secret|privilege|tenant|security|rce|ssrf)/.test(a)) return "Security / Vulnerability";
+  if (/(dead.?code|unreachable|unused|orphan|never (called|used|imported))/.test(a)) return "Dead Code";
+  if (/(duplicat|redundant|reimplement|copy)/.test(a)) return "Duplication";
+  if (/(data.?integrity|race|concurren|transaction|idempoten|double|constraint)/.test(a)) return "Data Integrity / Concurrency";
+  if (/(perf|n\+1|slow|latency|batch|query.?count)/.test(a)) return "Performance";
+  if (/(contract.?drift|schema.?drift|api.?mismatch|404|endpoint.*(missing|not exist))/.test(a)) return "Contract Drift";
+  if (/(test|coverage|shallow|flaky)/.test(a)) return "Testing";
+  return "Other";
+}
+const TYPE_ORDER = ["Security / Vulnerability", "Dead Code", "Duplication", "Data Integrity / Concurrency", "Performance", "Contract Drift", "Testing", "Other"];
+const SEV_ORDER2 = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
+// Stable sort: severity, then type, then original index. Computed ONCE; both consumers use it.
+const orderedFindings = finalFindings
+  .map((f, i) => ({ f, i, t: typeOf(f) }))
+  .sort((a, b) => {
+    const sv = (SEV_ORDER2[a.f.severity] ?? 9) - (SEV_ORDER2[b.f.severity] ?? 9);
+    if (sv !== 0) return sv;
+    const tv = TYPE_ORDER.indexOf(a.t) - TYPE_ORDER.indexOf(b.t);
+    if (tv !== 0) return tv;
+    return a.i - b.i;
+  });
+
 function fmtChunks(today) {
   const sevHead = { CRITICAL: "🔴 Critical", HIGH: "🟠 High", MEDIUM: "🟡 Medium", LOW: "🟢 Low" };
   const head = [];
@@ -820,11 +850,17 @@ function fmtChunks(today) {
 
   const CHUNK_MAX = 30000;
   const chunks = [head.join("\n")];
-  let buf = "", n = tdStart, lastSev = null;
+  let buf = "", n = tdStart, lastSev = null, lastType = null;
   const flush = () => { if (buf) { chunks.push(buf); buf = ""; } };
-  for (const f of finalFindings) {
+  // Consume the shared `orderedFindings` (severity → type → original-index) so the
+  // TD numbers assigned here are IDENTICAL to those the consolidation stage references.
+  for (const { f, t } of orderedFindings) {
     let piece = "";
-    if (f.severity !== lastSev) { piece += `\n## ${sevHead[f.severity] || f.severity} Priority\n\n`; lastSev = f.severity; }
+    if (f.severity !== lastSev) { piece += `\n## ${sevHead[f.severity] || f.severity} Priority\n\n`; lastSev = f.severity; lastType = null; }
+    // Type sub-heading uses a bold marker line (NOT `###`) so it never collides with
+    // the `### TD-N` item headings that downstream tools grep for. ASCII hyphens only
+    // (M76: no em/en-dashes in fmtChunks literals).
+    if (t !== lastType) { piece += `**-- ${t} --**\n\n`; lastType = t; }
     piece += itemMd(f, n++);
     if (buf.length + piece.length > CHUNK_MAX) flush();
     buf += piece;
@@ -889,6 +925,99 @@ log(`register written in ${chunkOk}/${chunks.length} chunks (${counts.total} fin
 const synthesis = { status: "written", counts, archivePath, tdRange: `TD-${tdStart}..TD-${lastTd}`, finalFindings };
 log(`register written: ${JSON.stringify(synthesis.counts)} (${synthesis.tdRange})`);
 
+// ── Consolidation Opportunities (opus + graph-assisted) ────────────────────────
+// After the register is written (TD numbers final), cluster HIGH-CONFIDENCE groups
+// of TDs that share a root and should be fixed as ONE workstream (duplicate-function
+// families, batch dead-code deletions, a guard-pattern missing across N sites, god-file
+// splits). Only tight clusters — ungrouped TDs stay standalone (user directive). The
+// section is APPENDED to the END of the register, after all individual items.
+// Graph-assisted: an agent may run `gsd-t graph who-imports/who-calls/blast-radius`
+// (project-local bin first, else global) on a TD's files to confirm two TDs truly share
+// code before grouping — grounds the clustering in real relationships, not just prose
+// similarity. Best-effort: any failure leaves the register intact (no section).
+phase("Consolidation");
+try {
+  // Number from the SHARED `orderedFindings` so each TD-N here is EXACTLY the id the
+  // register wrote (severity → type → original-index — the single ordering source).
+  let _n = tdStart;
+  const consInput = orderedFindings.map(({ f }) => {
+    const td = _n++;
+    return `TD-${td} [${f.severity}] (${ascii(f.area) || "?"}) ${ascii(f.title)} @ ${(f.files && f.files[0]) || "?"}`;
+  }).join("\n");
+  const CONS_SCHEMA = {
+    type: "object", required: ["groups"], additionalProperties: false,
+    properties: {
+      groups: {
+        type: "array",
+        items: {
+          type: "object", required: ["title", "members", "sharedRoot", "recommendedAction"], additionalProperties: false,
+          properties: {
+            title: { type: "string" },
+            members: { type: "array", items: { type: "string" } },   // e.g. ["TD-75","TD-143"]
+            sharedRoot: { type: "string" },
+            recommendedAction: { type: "string" },
+            effort: { type: "string" },                              // GSD-T-native units
+          },
+        },
+      },
+      notes: { type: "string" },
+    },
+  };
+  const consAgent = await agent(
+    [
+      `You are identifying CONSOLIDATION OPPORTUNITIES in a tech-debt register — sets of findings that share a ROOT and should be fixed as ONE workstream, not one-by-one.`,
+      `Below are ${finalFindings.length} findings as "TD-N [SEVERITY] (area) title @ location".`,
+      ``,
+      `Group ONLY HIGH-CONFIDENCE clusters (user directive — tight, not loose themes):`,
+      `  • duplicate-functionality families (same logic implemented 2+ times / diverging copies)`,
+      `  • batch dead-code deletions (multiple never-used modules/components removable together)`,
+      `  • a single missing pattern repeated across N sites (e.g. the same auth guard absent on many routes)`,
+      `  • god-file / god-object splits touching several TDs`,
+      `  • the SAME remediation applied in multiple places`,
+      `Findings with no strong shared root MUST be left OUT (they stay standalone — do not force weak groupings).`,
+      ``,
+      `GRAPH-ASSIST (optional, strengthens confidence): to confirm two TDs truly share code, you MAY run the code graph via Bash on their files — try a project-local binary first then the global one:`,
+      `  \`${projectDir}/bin/gsd-t-graph-query-cli.cjs who-imports <file>\`  OR  \`gsd-t graph who-imports <file>\` (also who-calls / blast-radius). If the graph is unavailable, fall back to the location/area text — do NOT fail.`,
+      ``,
+      `Return "groups": each = { title, members: ["TD-N",...] (>=2), sharedRoot, recommendedAction (which to keep/delete/extract), effort (GSD-T-native units: domain/wave/spawn count — NEVER human-hours) }. If nothing clusters with high confidence, return groups: [].`,
+      ``,
+      consInput.slice(0, 140000),
+    ].join("\n"),
+    { label: "consolidation:cluster", phase: "Consolidation", schema: CONS_SCHEMA, model: "opus" }
+  ).catch((e) => { log(`consolidation cluster failed (non-fatal): ${e && e.message}`); return null; });
+
+  const groups = (consAgent && Array.isArray(consAgent.groups)) ? consAgent.groups : [];
+  if (groups.length) {
+    const cs = [
+      ``, `---`, ``, `## 🧩 Consolidation Opportunities`, ``,
+      `> High-confidence clusters of findings that share a root cause and should be addressed as ONE workstream (candidates for a single consolidation milestone). Findings not listed here have no strong shared root and stand alone. Effort is in GSD-T-native units.`, ``,
+    ];
+    groups.forEach((g, gi) => {
+      cs.push(`### CG-${gi + 1} - ${ascii(g.title)}`);
+      cs.push(`- **Members:** ${(g.members || []).map((m) => ascii(m)).join(", ")}`);
+      cs.push(`- **Shared root:** ${ascii(g.sharedRoot)}`);
+      cs.push(`- **Recommended action:** ${ascii(g.recommendedAction)}`);
+      if (g.effort) cs.push(`- **Effort:** ${ascii(g.effort)}`);
+      cs.push("");
+    });
+    if (consAgent.notes) cs.push(`> Notes: ${ascii(consAgent.notes)}`, "");
+    // Append via a bounded agent Bash heredoc (orchestrator has no fs).
+    const consBlock = cs.join("\n");
+    await agent(
+      [
+        `APPEND EXACTLY the content between the markers to the END of \`${regPath}\` (append — do NOT overwrite existing content). Use a Bash heredoc: \`cat >> ${regPath} <<'GSDTEOF'\` … \`GSDTEOF\`. After writing, reply ONLY "OK".`,
+        ``, `<<<CHUNK>>>`, consBlock, `<<<END_CHUNK>>>`,
+      ].join("\n"),
+      { label: "consolidation:write", phase: "Consolidation", model: "haiku" }
+    ).catch((e) => log(`consolidation append uncertain (non-fatal): ${e && e.message}`));
+    log(`consolidation: ${groups.length} high-confidence group(s) appended to register`);
+  } else {
+    log(`consolidation: no high-confidence clusters found (register unchanged)`);
+  }
+} catch (e) {
+  log(`consolidation phase failed (non-fatal — register intact): ${e && e.message}`);
+}
+
 // Document — per-doc fan-out. Each agent writes its file via Write/Edit (its tools).
 // The orchestrator passes the findings + (for plain-english) tells the agent to
 // READ the just-written register itself, since the orchestrator can't read it.