@tekyzinc/gsd-t 4.0.15 → 4.0.17

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.0.17] - 2026-06-02 (M70 Workflow Invocation Guard — patch)
+
+### Fixed — workflow commands no longer get hand-driven instead of invoking the Workflow
+
+A brand-new session running `/gsd-t-scan` (via the `/gsd` auto-router) read the v4.0.16 command file and STILL hand-drove an 18-slice fan-out — "skip task-list overhead and drive the fan-out directly … proven fallback pattern" — skipping the deterministic synthesis/document/render stages, so it produced only the register (no `.gsd-t/scan/*.md`, no merged living docs, no plain-English doc). Two compounding causes: the command file's prose *described the workflow's internals* and read like a to-do list, and the `/gsd` router's "execute the command's full workflow" was ambiguous between "invoke the tool" and "do the work yourself."
+
+- `commands/gsd-t-scan.md`: prepended a strong imperative guard — STOP, your only job is to resolve the path + call the `Workflow` tool; do NOT volume-probe, carve slices, spawn finders, or fall back to a hand-driven run; hand-driving is a FAILURE. Reframed the explanatory prose as "what the Workflow does (background — NOT your to-do list)."
+- `commands/gsd-t-{execute,verify,wave,integrate,debug}.md`: concise version of the same guard near the top.
+- `~/.claude/commands/gsd.md` (router): clarified that "execute the command's full workflow" means follow the command file's instruction to invoke the `Workflow` tool — not improvise the work.
+- `test/m70-workflow-invocation-guard.test.js`: +7 tests asserting every workflow-backed command carries the guard near the top (regression lock).
+
+Suite: 1285 pass / 0 fail / 4 skip — zero regressions.
+
+## [4.0.16] - 2026-06-02 (M69 Workflow scriptPath Resolution — patch)
+
+### Fixed — workflow commands now run from any project, not just the GSD-T source repo
+
+Every workflow-backed command (`gsd-t-scan`, `-execute`, `-verify`, `-wave`, `-integrate`, `-debug`, and the 6 `-phase`-runner commands) hard-coded a relative `scriptPath: "templates/workflows/..."`. That path only resolves when CWD is the GSD-T source repo; from any consumer project the workflow script (which ships inside the installed package, not the project) is unreachable, so `Workflow({scriptPath})` silently fails and the agent falls back to a hand-driven run. This is why a deep scan in a consumer project produced the register but not the 5 `.gsd-t/scan/*.md` dimension files — the M67 Document phase never executed.
+
+- `bin/gsd-t.js`: new `gsd-t workflow-path <name>` subcommand — prints the ABSOLUTE path to `gsd-t-<name>.workflow.js` resolved from the CLI's own `PKG_ROOT`. Accepts name aliases (with/without `gsd-t-` prefix or `.workflow.js` suffix). Exit 0 + path; exit 4 + available list on unknown name; exit 64 on missing arg. Resolves from any CWD (works for global/local/npx installs since it follows the invoked binary).
+- `commands/gsd-t-{scan,execute,verify,wave,integrate,debug,partition,plan,impact,milestone,prd,doc-ripple,design-decompose}.md` (13 files): replaced the relative `scriptPath` with an instruction to resolve the absolute path first via `gsd-t workflow-path <name>`.
+- `templates/CLAUDE-global.md`, `commands/gsd-t-help.md`: documented the resolution requirement + the new subcommand.
+- `test/m69-workflow-path.test.js`: +6 tests (resolves known/aliased/all-8 workflows, CWD-independence, exit 4 unknown, exit 64 usage).
+
+Effect: `/gsd-t-scan` (and all workflow commands) now run correctly from any registered project with no special prompt or absolute-path workaround.
+
+### Added — `.gsd-t/techdebt_in_plain_english.md` scan output
+
+The scan Document phase now also writes a non-technical companion to the tech-debt register: every TD item restated in layman's terms, why it matters in business/user consequences, and a concrete real-world analogy, with severity translated into plain urgency. For founders/PMs/stakeholders who need the findings without the jargon.
+
+- `templates/workflows/gsd-t-scan.workflow.js`: +1 `docTargets` entry (`techdebt-plain-english`); included in the document-phase git commit.
+- `commands/gsd-t-scan.md`: Document Ripple lists the new output.
+
+Suite: 1278 pass / 0 fail / 4 skip — zero regressions.
+
 ## [4.0.15] - 2026-06-01 (M68 update-all Retired-Tool Prune — patch)
 
 ### Fixed — update-all now prunes bin tools retired in M61/M65

package/bin/gsd-t.js

@@ -4446,6 +4446,43 @@ if (require.main === module) {
       const code = runParallelCli(args.slice(1), process.env);
       process.exit(code);
     }
+    case "workflow-path": {
+      // M69 — print the ABSOLUTE path to a GSD-T workflow script, resolved from
+      // this CLI's own install root. Command files shell out to this instead of
+      // hard-coding a relative `templates/workflows/...` scriptPath, which only
+      // resolves when CWD is the GSD-T source repo — from any consumer project
+      // the relative path is unresolvable and `Workflow({scriptPath})` silently
+      // fails, forcing a hand-driven fallback (the HiloAviation scan incident).
+      //
+      // Usage: gsd-t workflow-path <name>   (name with or without the
+      //        `gsd-t-` prefix / `.workflow.js` suffix). Exit 0 + path on stdout;
+      //        exit 4 + error on stderr if the workflow is unknown.
+      const raw = (args[1] || "").trim();
+      if (!raw) {
+        process.stderr.write("usage: gsd-t workflow-path <name>\n");
+        process.exit(64);
+      }
+      const wfDir = path.join(PKG_ROOT, "templates", "workflows");
+      // Normalize: strip a leading "gsd-t-" and a trailing ".workflow.js"/".js",
+      // then rebuild the canonical filename.
+      const stem = raw
+        .replace(/\.workflow\.js$/, "")
+        .replace(/\.js$/, "")
+        .replace(/^gsd-t-/, "");
+      const file = path.join(wfDir, `gsd-t-${stem}.workflow.js`);
+      if (!fs.existsSync(file)) {
+        const avail = fs.existsSync(wfDir)
+          ? fs.readdirSync(wfDir)
+              .filter((f) => f.endsWith(".workflow.js"))
+              .map((f) => f.replace(/^gsd-t-/, "").replace(/\.workflow\.js$/, ""))
+              .join(", ")
+          : "(workflows dir missing)";
+        process.stderr.write(`gsd-t workflow-path: unknown workflow "${raw}". Available: ${avail}\n`);
+        process.exit(4);
+      }
+      process.stdout.write(file + "\n");
+      process.exit(0);
+    }
     case "preflight": {
       // M55 D5 — `gsd-t preflight` thin dispatcher to bin/cli-preflight.cjs.
       const { spawnSync } = require("child_process");

package/commands/gsd-t-debug.md

@@ -1,5 +1,8 @@
 # GSD-T: Debug — Systematic Debugging with Contract Awareness
 
+> **⛔ Invoke the Workflow tool — do not hand-drive.** Your only job is to resolve the workflow path (`gsd-t workflow-path debug`) and call the `Workflow` tool as the steps below instruct. Do NOT reconstruct the workflow stages in your own reasoning, spawn finder/worker subagents yourself, or fall back to a hand-driven run — that skips the deterministic stages and produces an incomplete result. The prose below describes what the Workflow does internally; it is background, not a to-do list for you.
+
+
 You are the lead agent. Debug a failing test or runtime error by invoking the canonical Workflow script at `templates/workflows/gsd-t-debug.workflow.js`.
 
 ## What this command does
@@ -22,7 +25,10 @@ Call the `Workflow` tool with:
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-debug.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path debug` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path debug`>",
   args: {
     symptom: "describe the failing test or runtime error in one sentence",
     projectDir: "."

package/commands/gsd-t-design-decompose.md

@@ -18,7 +18,10 @@ Capture the design reference from `$ARGUMENTS` (Figma URL / image path). If Figm
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-phase.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path phase` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path phase`>",
   args: {
     phase: "design-decompose",
     projectDir: ".",

package/commands/gsd-t-doc-ripple.md

@@ -18,7 +18,10 @@ Read the recent commit range (or `$ARGUMENTS` if a specific scope is given) and
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-phase.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path phase` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path phase`>",
   args: {
     phase: "doc-ripple",
     projectDir: ".",

package/commands/gsd-t-execute.md

@@ -1,5 +1,8 @@
 # GSD-T: Execute — Run Domain Tasks
 
+> **⛔ Invoke the Workflow tool — do not hand-drive.** Your only job is to resolve the workflow path (`gsd-t workflow-path execute`) and call the `Workflow` tool as the steps below instruct. Do NOT reconstruct the workflow stages in your own reasoning, spawn finder/worker subagents yourself, or fall back to a hand-driven run — that skips the deterministic stages and produces an incomplete result. The prose below describes what the Workflow does internally; it is background, not a to-do list for you.
+
+
 You are the lead agent. Execute the current milestone by invoking the canonical Workflow script at `templates/workflows/gsd-t-execute.workflow.js`.
 
 ## What this command does
@@ -22,7 +25,10 @@ Call the `Workflow` tool with:
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-execute.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path execute` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path execute`>",
   args: {
     milestone: "M{NN}",
     domains: ["m{NN}-d1-...", "m{NN}-d2-...", ...],

package/commands/gsd-t-help.md

@@ -432,6 +432,11 @@ Use these when user asks for help on a specific command:
 - **Files**: `.gsd-t/backlog-settings.md`
 - **Use when**: Customizing the classification dimensions for your project
 
+### workflow-path (M69)
+- **Summary**: Prints the ABSOLUTE path to a GSD-T workflow script (`gsd-t-<name>.workflow.js`) resolved from the CLI's own install root. Command files shell out to this instead of hard-coding a relative `templates/workflows/...` scriptPath — which only resolves from the GSD-T source repo, so from any consumer project `Workflow({scriptPath})` would silently fail and fall back to a hand-driven scan (the HiloAviation incident).
+- **Auto-invoked**: Yes — by every workflow-backed command (`gsd-t-scan`, `-execute`, `-verify`, `-wave`, `-integrate`, `-debug`, and the `-phase` runner) at Workflow-invocation time.
+- **CLI**: `gsd-t workflow-path <name>` (name with or without the `gsd-t-` prefix / `.workflow.js` suffix). Exit 0 + absolute path on stdout; exit 4 + available list on unknown name; exit 64 on missing arg.
+
 ### preflight (M55)
 - **Summary**: Deterministic state-precondition check (`bin/cli-preflight.cjs`); 6 built-in checks (branch-guard, contracts-stable, deps-installed, manifest-fresh, ports-free, working-tree-state). Exit 0/4. Pluggable, zero-dep, captureSpawn-exempt.
 - **Auto-invoked**: Yes — by `gsd-t-execute` Step 1 and `gsd-t verify-gate` Track 1

package/commands/gsd-t-impact.md

@@ -18,7 +18,10 @@ Read `.gsd-t/progress.md`, the relevant domain `tasks.md`, and `docs/architectur
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-phase.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path phase` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path phase`>",
   args: {
     phase: "impact",
     milestone: "M{NN}",

package/commands/gsd-t-integrate.md

@@ -1,5 +1,8 @@
 # GSD-T: Integrate — Wire Domains Together
 
+> **⛔ Invoke the Workflow tool — do not hand-drive.** Your only job is to resolve the workflow path (`gsd-t workflow-path integrate`) and call the `Workflow` tool as the steps below instruct. Do NOT reconstruct the workflow stages in your own reasoning, spawn finder/worker subagents yourself, or fall back to a hand-driven run — that skips the deterministic stages and produces an incomplete result. The prose below describes what the Workflow does internally; it is background, not a to-do list for you.
+
+
 You are the lead agent. Integrate cross-domain work by invoking the canonical Workflow script at `templates/workflows/gsd-t-integrate.workflow.js`.
 
 ## What this command does
@@ -28,7 +31,10 @@ Call the `Workflow` tool with:
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-integrate.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path integrate` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path integrate`>",
   args: {
     milestone: "M{NN}",
     domains: ["m{NN}-d1-...", "m{NN}-d2-..."],  // domains that just completed

package/commands/gsd-t-milestone.md

@@ -18,7 +18,10 @@ Read `.gsd-t/progress.md` (current version + completed milestones), `docs/requir
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-phase.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path phase` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path phase`>",
   args: {
     phase: "milestone",
     projectDir: ".",

package/commands/gsd-t-partition.md

@@ -22,7 +22,10 @@ Call the `Workflow` tool with:
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-phase.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path phase` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path phase`>",
   args: {
     phase: "partition",
     milestone: "M{NN}",

package/commands/gsd-t-plan.md

@@ -18,7 +18,10 @@ Read `.gsd-t/progress.md` and each domain's `scope.md`/`constraints.md`. The par
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-phase.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path phase` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path phase`>",
   args: {
     phase: "plan",
     milestone: "M{NN}",

package/commands/gsd-t-prd.md

@@ -18,7 +18,10 @@ Read any existing `docs/requirements.md`, `docs/architecture.md`, and `.gsd-t/pr
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-phase.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path phase` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path phase`>",
   args: {
     phase: "prd",
     projectDir: ".",

package/commands/gsd-t-scan.md

@@ -1,8 +1,30 @@
 # GSD-T: Scan — Deep Codebase Analysis and Tech Debt Discovery
 
-You are the lead agent. Run a deep codebase scan by invoking the canonical Workflow script at `templates/workflows/gsd-t-scan.workflow.js`.
-
-## What this command does
+> ## ⛔ STOP — READ THIS FIRST. Your ONLY job is to invoke the Workflow tool.
+>
+> **You MUST NOT perform the scan yourself.** Do NOT run a volume probe by hand, do NOT
+> "carve the codebase into N slices," do NOT spawn deep-finder agents/teammates yourself,
+> do NOT "skip task-list overhead and drive the fan-out directly," and do NOT fall back to
+> any hand-driven or "proven fallback" pattern. The slicing, fan-out, verify, synthesis, and
+> document stages all happen **inside the Workflow script** — not in your reasoning.
+>
+> **The ONLY correct action is exactly two steps (Step 1 + Step 2 below):**
+> 1. Bash: `gsd-t workflow-path scan` → capture the absolute path it prints.
+> 2. Call the **`Workflow`** tool with that `scriptPath` and the `args` shown in Step 2.
+>
+> If you find yourself reading source files, counting files, listing routes, or spawning
+> Agent/Task subagents to find tech debt — **STOP. You are doing it wrong.** That work belongs
+> to the Workflow. Hand-driving the scan is a FAILURE: it skips the deterministic
+> synthesis/document/render stages, so it produces an incomplete result (no
+> `.gsd-t/scan/*.md` dimension files, no merged living docs, no plain-English doc).
+>
+> The prose below explains what the Workflow does internally — it is **background, not a
+> to-do list for you.** Read it as "what will happen when I call the tool," never as "steps I
+> should execute myself."
+
+You are the lead agent. Your sole responsibility is to invoke the canonical scan Workflow (resolve its absolute path in Step 1, then call the `Workflow` tool in Step 2). Everything else is the Workflow's job.
+
+## What the Workflow does (background — NOT your to-do list)
 
 Replaces the legacy 5-teammate prose scan with a single deterministic, **volume-scaled** Workflow:
 
@@ -20,13 +42,19 @@ Each stage is a schema-validated `agent()` call (or deterministic CLI). Finders
 
 Read `CLAUDE.md`, `.gsd-t/progress.md`, `.gsd-t/contracts/`, and any existing `.gsd-t/techdebt.md` (the Workflow archives and continues from it). This tells the scan what's already known so it dedups rather than re-discovers.
 
-## Step 2: Invoke the scan Workflow
+## Step 2: Resolve the workflow path, then invoke
+
+First resolve the ABSOLUTE path to the workflow script (the workflow ships inside the installed `@tekyzinc/gsd-t` package, NOT in the current project — a bare relative `templates/workflows/...` path only resolves when CWD is the GSD-T source repo, so from any other project `Workflow()` cannot find it). Run via Bash:
+
+```bash
+gsd-t workflow-path scan
+```
 
-Call the `Workflow` tool with:
+It prints the absolute path (exit 0). Use that exact string as `scriptPath`. If `gsd-t` is not on PATH, fall back to `npx @tekyzinc/gsd-t workflow-path scan`, or derive it from the package: `node -e "const p=require('child_process').execSync('npm root -g').toString().trim(); console.log(p+'/@tekyzinc/gsd-t/templates/workflows/gsd-t-scan.workflow.js')"`. Do NOT fall back to a relative path or a hand-driven scan — that produces an incomplete result (the original bug). Then call the `Workflow` tool with:
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-scan.workflow.js",
+  scriptPath: "<absolute path printed by `gsd-t workflow-path scan`>",
   args: {
     projectDir: ".",        // the project to scan
     scanNumber: 12,         // optional — for the register header
@@ -65,6 +93,7 @@ Present a summary: headline volume totals, findings by severity, the top critica
 The scan Workflow updates ALL of these deterministically (no manual follow-on):
 
 - `.gsd-t/techdebt.md` — fresh register (synthesis; prior one archived to `.gsd-t/techdebt_YYYY-MM-DD.md`)
+- `.gsd-t/techdebt_in_plain_english.md` — non-technical companion to the register: every TD item in layman's terms, why it matters, and a real-world analogy (document phase)
 - `.gsd-t/scan/{architecture,security,quality,business-rules,contract-drift}.md` — dimension analysis files (document phase)
 - `docs/architecture.md`, `docs/workflows.md`, `docs/infrastructure.md`, `docs/requirements.md`, `README.md` — living docs, **merged not overwritten** (document phase)
 - HTML scan report via `bin/scan-report.js` (render phase)

package/commands/gsd-t-verify.md

@@ -1,5 +1,8 @@
 # GSD-T: Verify — Quality Gates
 
+> **⛔ Invoke the Workflow tool — do not hand-drive.** Your only job is to resolve the workflow path (`gsd-t workflow-path verify`) and call the `Workflow` tool as the steps below instruct. Do NOT reconstruct the workflow stages in your own reasoning, spawn finder/worker subagents yourself, or fall back to a hand-driven run — that skips the deterministic stages and produces an incomplete result. The prose below describes what the Workflow does internally; it is background, not a to-do list for you.
+
+
 You are the lead agent. Verify the current milestone by invoking the canonical Workflow script at `templates/workflows/gsd-t-verify.workflow.js`.
 
 ## What this command does
@@ -31,7 +34,10 @@ Call the `Workflow` tool with:
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-verify.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path verify` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path verify`>",
   args: {
     milestone: "M{NN}",
     projectDir: ".",

package/commands/gsd-t-wave.md

@@ -1,5 +1,8 @@
 # GSD-T: Wave — Full Cycle Orchestration
 
+> **⛔ Invoke the Workflow tool — do not hand-drive.** Your only job is to resolve the workflow path (`gsd-t workflow-path wave`) and call the `Workflow` tool as the steps below instruct. Do NOT reconstruct the workflow stages in your own reasoning, spawn finder/worker subagents yourself, or fall back to a hand-driven run — that skips the deterministic stages and produces an incomplete result. The prose below describes what the Workflow does internally; it is background, not a to-do list for you.
+
+
 You are the lead agent. Run a milestone wave end-to-end by invoking the canonical Workflow script at `templates/workflows/gsd-t-wave.workflow.js`.
 
 ## What this command does
@@ -26,7 +29,10 @@ Call the `Workflow` tool with:
 
 ```js
 {
-  scriptPath: "templates/workflows/gsd-t-wave.workflow.js",
+  // Resolve the ABSOLUTE path FIRST via Bash: `gsd-t workflow-path wave` (the
+  // workflow ships in the installed @tekyzinc/gsd-t package, not this project — a
+  // bare relative path only resolves from the GSD-T source repo). Use its stdout here:
+  scriptPath: "<absolute path printed by `gsd-t workflow-path wave`>",
   args: {
     milestone: "M{NN}",
     domains: ["m{NN}-d1-...", "m{NN}-d2-...", ...],  // domains for this wave only, per integration-points

package/commands/gsd.md

@@ -196,7 +196,7 @@ Valid command slugs: `quick`, `debug`, `feature`, `execute`, `milestone`, `proje
 → /gsd ──▶ continue /gsd-t-quick
 ```
 
-This MUST be the very first line of your response. Then immediately execute that command's full workflow, passing `$ARGUMENTS` through.
+This MUST be the very first line of your response. Then immediately **read and follow that command file's instructions** (`~/.claude/commands/gsd-t-{slug}.md`), passing `$ARGUMENTS` through. "Execute the command's full workflow" means **do what the command file says** — for workflow-backed commands (scan, execute, verify, wave, integrate, debug, and the phase-runner commands) that means **invoke the `Workflow` tool as the command instructs**. It does NOT mean improvise the work yourself, hand-drive a fan-out, or reconstruct the workflow's stages in your own reasoning. If the command file says "invoke the Workflow tool," you invoke the Workflow tool — full stop.
 
 **Do NOT ask "is this the right command?" — just route and go.** The user can interrupt with Esc if it's wrong.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.0.15",
+  "version": "4.0.17",
   "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

@@ -319,7 +319,7 @@ Routine GSD-T actions (milestone → partition → plan → execute → verify
 
 ## GSD-T Workflows (M61 — v4.0.10+)
 
-GSD-T workflows live at `templates/workflows/`. Each workflow is a self-contained native Workflow script that handles one phase of the GSD-T lifecycle. Command files (`commands/gsd-t-*.md`) are thin invokers that call `Workflow({scriptPath, args})`.
+GSD-T workflows live at `templates/workflows/`. Each workflow is a self-contained native Workflow script that handles one phase of the GSD-T lifecycle. Command files (`commands/gsd-t-*.md`) are thin invokers that call `Workflow({scriptPath, args})`. The `scriptPath` MUST be resolved to an absolute path at invoke time via `gsd-t workflow-path <name>` (M69) — the workflow ships inside the installed `@tekyzinc/gsd-t` package, not the consumer project, so a bare relative `templates/workflows/...` path only resolves from the GSD-T source repo and silently breaks `Workflow()` everywhere else.
 
 Canonical scripts:
 - `gsd-t-execute.workflow.js` — preflight → brief → file-disjointness → parallel(domain workers) → integrate → verify-gate

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

@@ -43,7 +43,7 @@ export const meta = {
     { title: "Probe",       detail: "volume probe → derive per-area slice list", model: "haiku" },
     { title: "Deep Scan",   detail: "pipeline: per-slice deep finder → single verify" },
     { title: "Synthesis",   detail: "dedup / merge / re-rank into techdebt.md", model: "opus" },
-    { title: "Document",    detail: "deep living-doc + dimension-file cross-population (per-doc fan-out)" },
+    { title: "Document",    detail: "deep living-doc + dimension-file + plain-English cross-population (per-doc fan-out)" },
     { title: "Render",      detail: "schema extraction + diagrams + HTML report" },
   ],
 };
@@ -463,6 +463,13 @@ if (!fs.existsSync(registerPath)) {
 }
 log(`register written: ${JSON.stringify(synthesis.counts)}`);
 
+// Read the synthesized register so the plain-English doc can mirror its EXACT
+// TD-NNN ids / order (red-team HIGH-1: raw findings carry no TD ids, so a doc
+// built only from findings would invent divergent numbering and break the
+// cross-reference to techdebt.md). The register exists here (confirmed above).
+let registerText = "";
+try { registerText = fs.readFileSync(registerPath, "utf8"); } catch (_) {}
+
 // ─── Document — deep living-doc + dimension-file cross-population (M67) ───
 // M66 made the register deep but left doc cross-population as a non-deterministic
 // "lead agent follow-on" — effectively dropped. M67 fans out one agent PER DOCUMENT,
@@ -577,15 +584,51 @@ const docTargets = [
     id: "readme", label: "README.md", merge: true,
     prompt: `Update or create \`README.md\`: project name + description; tech stack + versions discovered; getting-started/setup (from infrastructure findings); brief architecture overview; link to \`docs/\` for detail. If it exists, MERGE — update tech-stack + setup sections but preserve the user's existing structure and custom content.`,
   },
+  {
+    id: "techdebt-plain-english", label: ".gsd-t/techdebt_in_plain_english.md",
+    needsRegister: true, // red-team HIGH-1: must receive the synthesized register (TD-NNN ids live there, not in findings)
+    prompt: `Write \`.gsd-t/techdebt_in_plain_english.md\` — a NON-TECHNICAL companion to the tech-debt register, written for a smart reader who is NOT an engineer (e.g. a founder, PM, or stakeholder). Cover EVERY item in the register (one entry per TD-NNN, in the same severity order), using the EXACT TD-NNN ids from the register provided below. For each item:\n` +
+      `- **Heading**: \`### TD-NNN — <the plain-English name of the problem>\` (keep the TD-NNN id so it cross-references the technical register, but rename the title into everyday language — no jargon).\n` +
+      `- **What it is** (1-2 sentences): explain the problem with ZERO technical terms. If a technical word is unavoidable, define it in parentheses the way you'd explain it to a friend.\n` +
+      `- **Why it matters** (1-2 sentences): the business/user consequence — what could go wrong, who is affected, what it costs.\n` +
+      `- **Real-world analogy**: a concrete everyday comparison that makes the risk intuitive (e.g. "This is like leaving the spare house key under the doormat — convenient, but anyone who thinks to look can get in." for a hardcoded secret). The analogy must genuinely map to THIS specific item, not be generic.\n` +
+      `- **Severity in plain terms**: translate CRITICAL/HIGH/MEDIUM/LOW into urgency a non-engineer feels ("fix before launch" / "schedule soon" / "clean up eventually").\n` +
+      `Open with a 2-3 sentence plain-English summary of the overall health of the codebase and the headline counts. Derive everything from the verified findings — do not invent items or analogies that don't fit. This file is the layman's lens on the same findings as \`.gsd-t/techdebt.md\`.`,
+  },
 ];
 
 const docResults = await parallel(
   docTargets.map((d) => async () => {
     const isLiving = !!d.merge;
+    // red-team HIGH-1: targets that mirror the register (plain-english) get the
+    // synthesized register text — the authoritative source of TD-NNN ids/order —
+    // not just the raw findings.
+    // red-team MEDIUM: do NOT silently truncate the register — a large register
+    // (e.g. 119 items ≈ 180KB) sliced to a small cap would drop the entire
+    // MEDIUM/LOW tail while the prompt says "cover EVERY item" (silent-cap
+    // anti-pattern the workflow forbids elsewhere). Cap generously, and if we DO
+    // hit it, tell the agent explicitly + log it so completeness loss is visible.
+    const REGISTER_CAP = 400000;
+    let registerBlock = "";
+    if (d.needsRegister) {
+      const truncated = registerText.length > REGISTER_CAP;
+      if (truncated) {
+        log(`⚠ register (${registerText.length} bytes) exceeds the ${REGISTER_CAP}-byte plain-english injection cap — the tail will be missing from techdebt_in_plain_english.md. Consider splitting the register.`);
+      }
+      registerBlock = [
+        "",
+        "Synthesized register (.gsd-t/techdebt.md) — use these EXACT TD-NNN ids/order:",
+        truncated ? "⚠ NOTE: the register was truncated to fit; cover every item you CAN see and end with a line noting that items beyond the last shown TD-NNN were omitted due to size." : "",
+        "```markdown",
+        registerText.slice(0, REGISTER_CAP),
+        "```",
+      ].join("\n");
+    }
     const prompt = [
       `You are the documentation agent for ONE document in a GSD-T deep scan.`,
       ``,
       baseCtx,
+      registerBlock,
       ``,
       d.prompt,
       ``,
@@ -680,7 +723,7 @@ if (render.ok) {
 // aren't versioned.
 const commit = spawnSync(
   "git",
-  ["add", "-A", ".gsd-t/scan", "docs", "README.md", ":!.gsd-t/scan/.doc-backup"],
+  ["add", "-A", ".gsd-t/scan", ".gsd-t/techdebt_in_plain_english.md", "docs", "README.md", ":!.gsd-t/scan/.doc-backup"],
   { cwd: projectDir, stdio: "pipe" }
 );
 if (commit.status === 0) {