@tekyzinc/gsd-t 4.0.14 → 4.0.16

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [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
+
+`update-all` kept the propagated 7-tool subset fresh but never deleted tools GSD-T retired — the `DEPRECATED_BIN_STRAYS` sweep list only carried `gsd-t.js`. Result: 22 of 24 registered projects carried 11-17 dead `.cjs` files (the M61/M65 token-telemetry, unattended-relay, headless-spawn, and context-meter clusters), and the "already current" summary masked it. Surfaced when a project appeared not to update.
+
+- `bin/gsd-t.js`: added the 17 M61/M65-retired tools to `DEPRECATED_BIN_STRAYS`; generalized the stray sweep so retired `.cjs` are pruned only when they carry a GSD-T provenance marker (`_hasGsdtProvenance`) — a user's same-named file without the marker is left untouched. `gsd-t.js` keeps its bespoke "GSD-T CLI Installer" header match.
+- `test/bin-gsd-t-resilience.test.js`: +2 regression tests (retired-provenance `.cjs` swept; user-authored same-named `.cjs` survives).
+- One-off: pruned 273 retired `.cjs` across the 21 affected projects (proved no live requirers first — the only references were retirement-breadcrumb comments).
+
+Suite: 1269 pass / 0 fail / 4 skip — zero regressions.
+
 ## [4.0.14] - 2026-05-29 (M67 Scan Deep Document Phase — patch)
 
 ### Added — deterministic deep document cross-population in the scan Workflow

package/bin/gsd-t.js

@@ -2473,11 +2473,60 @@ const PROJECT_BIN_TOOLS = [
 
 // Files that older versions of this installer copied into project bin/ but
 // are no longer part of PROJECT_BIN_TOOLS. On each update-all pass, sweep the
-// project's bin/ and remove any stray file that still byte-matches the source
-// copy in this package — that proves it's an old installer artifact, not a
-// user's own file sharing the same name. User-owned files (byte-divergent)
-// are left alone.
-const DEPRECATED_BIN_STRAYS = ["gsd-t.js"];
+// project's bin/ and remove any stray that carries GSD-T provenance — that
+// proves it's an old installer artifact, not a user's own file sharing the
+// name. User-owned files (no GSD-T provenance marker) are left alone.
+//
+// M68: the M61/M65 retirement removed the token-telemetry + unattended +
+// headless-spawn + context-meter clusters from the package and from
+// PROJECT_BIN_TOOLS, but never added them here — so update-all kept the current
+// 7 tools fresh while leaving 11-17 dead .cjs lingering in every project's bin/.
+// Adding them closes that gap so future retirements prune cleanly.
+// Each retired tool maps to one or more VERBATIM header sentinels it actually
+// shipped with (recovered from git history at the commit before each was deleted).
+// A stray is swept only when its content contains the exact product header — proof
+// it was SHIPPED by this installer, not merely that it mentions "gsd-t". This is the
+// M68 red-team fix: the prior loose substring (`/gsd-t/` over 1200 chars) would have
+// deleted a user's own same-named helper that happened to reference a `.gsd-t/` path.
+// A user file can match only by reproducing a verbatim product header — implausible.
+const DEPRECATED_BIN_STRAY_SIGNATURES = {
+  "gsd-t.js": ["GSD-T CLI Installer"], // bespoke installer header
+  // M61 D3 — token telemetry / context-runway cluster
+  "gsd-t-token-capture.cjs": ["GSD-T Token Capture", "gsd-t-token-capture"],
+  "token-telemetry.cjs": ["GSD-T Token Telemetry"],
+  "token-budget.cjs": ["GSD-T Token Budget"],
+  "token-optimizer.cjs": ["GSD-T Token Optimizer"],
+  "runway-estimator.cjs": ["GSD-T Runway", "runway-estimator"],
+  // Verbatim shipped comment header (no bare "GSD-T" — red-team HIGH-1: a bare token
+  // would delete a user's same-named file that merely mentions GSD-T).
+  "context-budget-audit.cjs": ["Context Budget Audit — measures the static context cost"],
+  "context-meter-config.cjs": ["Context Meter config loader (M34)"],
+  "context-meter-config.test.cjs": ["context-meter-config"],
+  // M61 D2 — unattended relay + headless spawn cluster
+  "gsd-t-unattended.cjs": ["GSD-T Unattended", "gsd-t-unattended"],
+  "gsd-t-unattended-platform.cjs": ["GSD-T Unattended", "gsd-t-unattended"],
+  "gsd-t-unattended-safety.cjs": ["GSD-T Unattended", "gsd-t-unattended"],
+  "headless-auto-spawn.cjs": ["GSD-T Headless Auto-Spawn"],
+  "headless-exit-codes.cjs": ["GSD-T headless exit-code contract"],
+  "handoff-lock.cjs": ["GSD-T Handoff Lock — Fail-safe sentinel"],
+  "unattended-watch-format.cjs": ["bin/unattended-watch-format.cjs", "unattended watch-tick activity block"],
+  // M61 D1/D4 — misc retired
+  "log-tail.cjs": ["Log Tail — print the last N lines"], // verbatim shipped comment
+  "event-stream.cjs": ["bin/event-stream.cjs", "unattended supervisor watch-tick"],
+};
+const DEPRECATED_BIN_STRAYS = Object.keys(DEPRECATED_BIN_STRAY_SIGNATURES);
+
+// A stray is swept only if its first 1200 chars contain one of the VERBATIM header
+// sentinels the tool actually shipped with. "Mentions gsd-t" is NOT enough — that
+// would risk deleting a user's same-named file (red-team HIGH-1). Returns the matched
+// sentinel (for logging) or null.
+function _matchedStraySignature(name, content) {
+  const sigs = DEPRECATED_BIN_STRAY_SIGNATURES[name];
+  if (!sigs) return null;
+  const head = content.slice(0, 1200);
+  for (const s of sigs) if (head.includes(s)) return s;
+  return null;
+}
 
 function copyBinToolsToProject(projectDir, projectName) {
   const projectBinDir = path.join(projectDir, "bin");
@@ -2537,19 +2586,15 @@ function copyBinToolsToProject(projectDir, projectName) {
       if (!fs.existsSync(strayPath)) continue;
       try {
         const strayContent = fs.readFileSync(strayPath, "utf8");
-        const head = strayContent.slice(0, 400);
-        // Signature-match any version this installer ever shipped. The marker
-        // is unique enough to rule out user-owned files: node shebang + the
-        // verbatim JSDoc header "GSD-T CLI Installer". Matches every historical
-        // version of bin/gsd-t.js, not just the current one, so older strays
-        // (e.g. v3.13.11 left behind on v3.13.12+) are still swept.
-        const isOurs =
-          head.startsWith("#!/usr/bin/env node") &&
-          head.includes("GSD-T CLI Installer");
-        if (isOurs) {
+        const matched = _matchedStraySignature(stray, strayContent);
+        if (matched) {
           fs.unlinkSync(strayPath);
           cleaned++;
+          // Red-team fix (HIGH-2): name every deleted file so a destructive sweep
+          // across many projects is reconstructable from scrollback, not a bare count.
+          info(`${projectName} — removed retired bin/${stray} (matched shipped header "${matched.slice(0, 40)}")`);
         }
+        // No signature match → leave it alone (user's own same-named file).
       } catch {
         // leave the file alone on any read error
       }
@@ -4401,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

@@ -22,7 +22,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

@@ -22,7 +22,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

@@ -28,7 +28,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

@@ -20,13 +20,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
 
-Call the `Workflow` tool with:
+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
+```
+
+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 +71,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

@@ -31,7 +31,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

@@ -26,7 +26,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/package.json

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