@tekyzinc/gsd-t 4.0.25 → 4.0.27

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.0.27] - 2026-06-04 (M79 Diagram Quality - patch)
+
+### Fixed - scan-report diagrams were generic boilerplate, clashed with the dark theme, and one was actively misleading
+
+The HTML scan report's six diagrams had three problems. (1) Four of them rendered a hardcoded "Tasks/Projects/Auth" template because `collectScanData` never populated the `services`/`layers`/`endpoints`/`states` inputs the generators read. (2) The database-schema diagram picked the wrong schema file on large repos (a 5-table video shim instead of the 417-table `src/lib/schema/index.ts`) and emitted `unknown` column types — a misleading diagram is worse than none. (3) All diagrams rendered on a white background with sharp corners and shrink-wrapped labels, clashing with the report's dark theme. The sequence diagram also failed to render because `validate & sanitize` broke the Mermaid sequence parser.
+
+- `bin/scan-data-collector.js`: parse real `services`/`layers`/`endpoints` from `docs/architecture.md` and `states` from `docs/workflows.md` (strict transition-chain detection — prose noise yields `[]` so generators keep their good defaults).
+- `bin/scan-diagrams-generators.js`: `genSystemArchitecture` draws up to 12 real feature domains with rounded `classDef`s; `genSequence` uses `validate and sanitize` (no `&` entity).
+- `bin/scan-diagrams.js`: database-schema diagram suppressed by default via `SUPPRESSED_TYPES`; re-enable per call with `options.includeSchemaDiagram` once the schema extractor is fixed.
+- `bin/scan-renderer.js`: shared `MERMAID_CONFIG` (dark `base` theme, rounded corners, node padding/spacing) applied via `mmdc -c`, plus `-b transparent` so diagrams blend into the dark panel.
+- `test/m79-diagram-quality.test.js`: regression test (services extracted, schema suppressed + opt-in, sequence has no `&`, config injected).
+- `test/scan.test.js`, `test/verify-gates.js`: updated to the 5-diagrams-by-default contract (schema via opt-in).
+
+## [4.0.26] - 2026-06-03 (M78 Plain-English Grouped + Batched - patch)
+
+### Fixed - plain-english companion was a flat ungrouped list + would stall on large registers
+
+The non-technical companion (techdebt_in_plain_english.md) was generated by a SINGLE doc agent: it produced a flat list with no severity grouping, and would stall writing 300+ entries (the M75 register bug, unfixed for this doc). M78 gives it the register treatment: a dedicated Plain-English phase batches the (severity-sorted) findings, fans out bounded generator agents (shared concurrency gate), then assembles DETERMINISTICALLY with severity section headers (## Critical / High / Medium / Low) and chunk-writes. Removed from docTargets (no longer a single agent). +test/m78-plain-english-grouping.test.js (3 tests: grouped+complete+ordered, no mid-item chunk split, empty-severity omission). Also dropped the stale Render phase from meta.phases (removed back in M71). One-off: regrouped the existing Hilo plain-english doc by authoritative severity.
+
+Suite: 1318 pass / 0 fail / 4 skip.
+
 ## [4.0.25] - 2026-06-03 (M77 HTML Report Reads Deep-Scan Table Format - patch)
 
 ### Fixed - scan report showed 0 critical/0 high on a 322-finding register

package/bin/scan-data-collector.js

@@ -165,6 +165,55 @@ function parseQualityFindings(text) {
   return findings.slice(0, 3);
 }
 
+// M79: derive the diagram inputs (services/layers/endpoints/states) from the DEEP
+// living docs (docs/architecture.md, docs/workflows.md) so the architecture/data-flow
+// diagrams reflect the project's REAL feature domains instead of falling back to the
+// generic "Tasks/Projects" templates. Falls back to scan/architecture.md, then [].
+function parseServices(docArch) {
+  if (!docArch) return [];
+  // Top-level numbered domain sections: "## 5. Multi-Tenant School and Location Model"
+  const svc = [];
+  for (const m of docArch.matchAll(/^##\s+\d+\.\s+(.+?)\s*$/gm)) {
+    const name = m[1].trim();
+    // skip meta sections that aren't feature domains
+    if (/^(system overview|technology stack|application structure|table of contents)/i.test(name)) continue;
+    svc.push(name);
+  }
+  return svc;
+}
+function parseLayers(docArch) {
+  if (!docArch) return [];
+  // "### Controller Layer", "## 4. Authentication and Session Layer", etc.
+  const layers = [];
+  for (const m of docArch.matchAll(/^#{2,3}\s+(?:\d+\.\s+)?(.+?\bLayer)\s*$/gmi)) {
+    const n = m[1].trim(); if (!layers.includes(n)) layers.push(n);
+  }
+  return layers;
+}
+function parseEndpoints(docArch) {
+  if (!docArch) return [];
+  // real route lines like `GET /feature-flags/resolve/:flagKey` or `POST /api/...`
+  const eps = [];
+  for (const m of docArch.matchAll(/\b(GET|POST|PUT|PATCH|DELETE)\s+(\/[A-Za-z0-9_\-\/:{}.]+)/g)) {
+    const e = m[1] + ' ' + m[2]; if (!eps.includes(e)) eps.push(e);
+  }
+  return eps;
+}
+function parseStates(docWorkflows) {
+  if (!docWorkflows) return [];
+  // Only accept REAL state transitions written as "Draft -> Open" / "Draft → Open"
+  // where BOTH sides look like status enum values (short, capitalized, no spaces).
+  // If we can't find a genuine transition chain, return [] so the generator keeps
+  // its (good) default state machine rather than rendering doc-prose noise. (M79:
+  // a loose match previously pulled "Domains/Source/Schedule" from prose headers.)
+  const isState = (w) => /^[A-Z][A-Za-z]{1,14}$/.test(w) && /(Draft|Open|Progress|Review|Done|Block|Cancel|Pending|Active|Closed|Approved|Rejected|Queued|Failed|Complete)/i.test(w);
+  const states = [];
+  for (const m of docWorkflows.matchAll(/\b([A-Z][A-Za-z]+)\s*(?:->|→)\s*([A-Z][A-Za-z]+)\b/g)) {
+    if (isState(m[1]) && isState(m[2])) for (const s of [m[1], m[2]]) if (!states.includes(s)) states.push(s);
+  }
+  return states.length >= 3 ? states : [];
+}
+
 function collectScanData(projectRoot) {
   const scanDir = path.join(projectRoot, '.gsd-t', 'scan');
   const rs = (f) => read(path.join(scanDir, f));
@@ -175,6 +224,9 @@ function collectScanData(projectRoot) {
   const secText   = rs('security.md');
   const qualText  = rs('quality.md');
   const debtText  = rr('.gsd-t/techdebt.md');
+  // Deep living docs — the real architecture knowledge (M79).
+  const docArch   = rr('docs/architecture.md');
+  const docFlow   = rr('docs/workflows.md');
 
   let projectName = path.basename(projectRoot);
   try { projectName = JSON.parse(rr('package.json')).name || projectName; } catch {}
@@ -188,8 +240,15 @@ function collectScanData(projectRoot) {
   const qualFinds = parseQualityFindings(qualText);
   const findings  = secFinds.concat(qualFinds).slice(0, 10);
 
+  // Diagram inputs from the deep docs (M79).
+  const services  = parseServices(docArch);
+  const layers    = parseLayers(docArch);
+  const endpoints = parseEndpoints(docArch);
+  const states    = parseStates(docFlow);
+
   return { projectName, filesScanned, totalLoc, debtCritical, debtHigh, debtMedium,
-           testCoverage, domains, techDebt, findings };
+           testCoverage, domains, techDebt, findings,
+           services, layers, endpoints, states };
 }
 
 module.exports = { collectScanData };

package/bin/scan-diagrams-generators.js

@@ -2,14 +2,22 @@
 
 function genSystemArchitecture(analysisData) {
   try {
-    const services = (analysisData.services || []).slice(0, 4);
+    // M79: when real feature domains were extracted from docs/architecture.md, draw
+    // them as the system's services (User -> Backend -> each domain). Show up to 12.
+    const services = (analysisData.services || []).slice(0, 12);
     if (services.length >= 2) {
       const lines = ['graph TB',
-        '  classDef user fill:#0d2035,stroke:#06b6d4,color:#a5f3fc',
-        '  classDef svc fill:#1a0f3a,stroke:#7c3aed,color:#ddd6fe',
-        '  classDef db fill:#0a2318,stroke:#10b981,color:#a7f3d0',
-        '  User(["👤 User"]):::user'];
-      services.forEach((s, i) => { lines.push('  S' + i + '["' + s + '"]:::svc'); lines.push('  User --> S' + i); });
+        '  User(["👤 User"]):::user',
+        '  API["⚡ Backend / API"]:::core',
+        '  User -->|"HTTPS"| API'];
+      services.forEach((s, i) => {
+        const label = String(s).replace(/"/g, "'");
+        lines.push('  S' + i + '["' + label + '"]:::svc');
+        lines.push('  API --> S' + i);
+      });
+      lines.push('  classDef user fill:#0d2035,stroke:#22d3ee,color:#a5f3fc,rx:8,ry:8');
+      lines.push('  classDef core fill:#1a0f3a,stroke:#a78bfa,color:#ede9fe,rx:8,ry:8');
+      lines.push('  classDef svc fill:#0f1d3a,stroke:#60a5fa,color:#bfdbfe,rx:8,ry:8');
       return lines.join('\n');
     }
     return `graph TB
@@ -150,7 +158,7 @@ function genSequence(analysisData) {
   participant Queue
   User->>Client: Submit form
   Client->>API: ${ep}
-  API->>API: validate & sanitize
+  API->>API: validate and sanitize
   alt invalid input
     API-->>Client: 400 Bad Request
   else valid

package/bin/scan-diagrams.js

@@ -42,11 +42,20 @@ function buildPlaceholder(def, mmd) {
   };
 }
 
+// M79: the database-schema diagram is SUPPRESSED by default. The schema extractor
+// picks the wrong file on large repos (grabbed a 5-table video shim instead of the
+// 417-table src/lib/schema/index.ts) and emits `unknown` column types — a misleading
+// diagram is worse than none. Re-enable per-call with options.includeSchemaDiagram
+// once parseDrizzle/detectOrm are fixed to use the real schema.
+const SUPPRESSED_TYPES = new Set(['database-schema']);
+
 function generateDiagrams(analysisData, schemaData, options) {
   try {
     const { renderDiagram } = require('./scan-renderer');
+    const opts = options || {};
     const results = [];
     for (const def of DIAGRAM_DEFS) {
+      if (SUPPRESSED_TYPES.has(def.type) && !opts.includeSchemaDiagram) continue;
       try {
         const mmd = def.gen(analysisData, schemaData);
         const isDbSchema = def.type === 'database-schema';

package/bin/scan-renderer.js

@@ -17,19 +17,50 @@ function makePlaceholder() {
   return PLACEHOLDER_HTML;
 }
 
+// M79: shared Mermaid config — coherent dark palette that sits well on the report's
+// dark page, ROUNDED node corners, and generous PADDING/spacing so labels (e.g.
+// "assign", "resolve") aren't shrink-wrapped against the box edges. Applied to every
+// diagram via mmdc's -c flag so all diagrams share one consistent look.
+const MERMAID_CONFIG = {
+  theme: 'base',
+  themeVariables: {
+    background: '#0a0f1e',
+    primaryColor: '#172554',          // node fill (deep blue, reads on dark)
+    primaryBorderColor: '#3b82f6',
+    primaryTextColor: '#e2e8f0',
+    lineColor: '#64748b',
+    secondaryColor: '#1e1b4b',
+    tertiaryColor: '#0a2318',
+    fontFamily: 'ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif',
+    fontSize: '15px',
+    clusterBkg: '#0b1220',
+    clusterBorder: '#1e3a5f',
+    nodeBorder: '#3b82f6',
+    edgeLabelBackground: '#0b1220',
+  },
+  flowchart: { curve: 'basis', padding: 18, nodeSpacing: 55, rankSpacing: 70, htmlLabels: true, useMaxWidth: true },
+  state: { padding: 16, nodeSpacing: 55, rankSpacing: 70 },
+  sequence: { useMaxWidth: true, boxMargin: 12 },
+};
+
 function tryMmdc(mmdContent) {
   const ts = Date.now();
   const tmpIn = path.join(os.tmpdir(), 'gsd-scan-' + ts + '.mmd');
   const tmpOut = path.join(os.tmpdir(), 'gsd-scan-' + ts + '.svg');
+  const tmpCfg = path.join(os.tmpdir(), 'gsd-scan-' + ts + '.config.json');
   try {
     fs.writeFileSync(tmpIn, mmdContent, 'utf8');
-    execFileSync('mmdc', ['-i', tmpIn, '-o', tmpOut, '-t', 'dark', '--quiet'], { timeout: 30000, stdio: 'pipe' });
+    fs.writeFileSync(tmpCfg, JSON.stringify(MERMAID_CONFIG), 'utf8');
+    // -b transparent so the diagram blends into the report's dark panel instead of a
+    // white box; -c applies the shared theme/padding/rounded config.
+    execFileSync('mmdc', ['-i', tmpIn, '-o', tmpOut, '-c', tmpCfg, '-b', 'transparent', '--quiet'], { timeout: 30000, stdio: 'pipe' });
     const svg = fs.readFileSync(tmpOut, 'utf8');
     return { svgContent: stripSvgDimensions(svg), rendered: true, rendererUsed: 'mermaid-cli' };
   } catch { return null; }
   finally {
     try { fs.unlinkSync(tmpIn); } catch {}
     try { fs.unlinkSync(tmpOut); } catch {}
+    try { fs.unlinkSync(tmpCfg); } catch {}
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.0.25",
+  "version": "4.0.27",
   "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/workflows/gsd-t-scan.workflow.js

@@ -31,8 +31,8 @@ export const meta = {
     { title: "Probe",      detail: "volume probe → per-area slice list", model: "sonnet" },
     { title: "Deep Scan",  detail: "pipeline: per-slice deep finder → single verify" },
     { title: "Synthesis",  detail: "archive prior + write fresh register + git", model: "opus" },
-    { title: "Document",   detail: "living docs + 5 dimension files + plain-english (per-doc fan-out)" },
-    { title: "Render",     detail: "HTML scan report via gsd-t bin renderers (agent via Bash)" },
+    { 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" },
   ],
 };
 
@@ -645,8 +645,10 @@ const docTargets = [
     prompt: `Update or create \`${projectDir}/docs/requirements.md\`: functional requirements from routes/handlers/UI; technical from configs/package.json/runtime; non-functional from perf configs/rate limits/caching.` },
   { id: "readme", label: "README.md", merge: true,
     prompt: `Update or create \`${projectDir}/README.md\`: project name+description; tech stack+versions; getting-started/setup; brief architecture overview; link to docs/. If it exists, MERGE — preserve the user's structure/custom content.` },
-  { id: "techdebt-plain-english", label: ".gsd-t/techdebt_in_plain_english.md", needsRegister: true,
-    prompt: `Write \`${projectDir}/.gsd-t/techdebt_in_plain_english.md\` — a NON-TECHNICAL companion to the register for a non-engineer (founder/PM/stakeholder). FIRST read \`${projectDir}/.gsd-t/techdebt.md\` (Read tool) to get the EXACT TD-NNN ids/order — it was just written and IS the source of truth (the findings JSON has no TD ids). Cover EVERY item, one entry each: \`### TD-NNN — <plain-English name>\`; **What it is** (no jargon; define any unavoidable term in parentheses); **Why it matters** (business/user consequence); **Real-world analogy** (a concrete everyday comparison that genuinely maps to THIS item); **Severity in plain terms** (CRITICAL/HIGH/MEDIUM/LOW → "fix before launch"/"schedule soon"/"clean up eventually"). Open with a 2-3 sentence plain-English health summary + headline counts.` },
+  // NOTE (M78): the plain-english companion is NOT in docTargets — a single agent
+  // stalls writing 300+ entries (the M75 register bug). It has its own dedicated phase
+  // below: batched generation (bounded fan-out) + deterministic severity-grouped,
+  // chunked write.
 ];
 
 const docResults = await parallel(
@@ -674,6 +676,85 @@ const docsOk = docResults.filter(Boolean).filter((r) => r.status === "written" |
 const docsFailed = docResults.filter(Boolean).filter((r) => r.status === "failed");
 log(`document phase: ${docsOk.length}/${docTargets.length} written/merged${docsFailed.length ? `; ${docsFailed.length} failed (non-fatal): ${docsFailed.map((d) => d.doc).join(", ")}` : ""}`);
 
+// ─── Plain-English phase (M78) ───────────────────────────────────────────────
+// The non-technical companion can be 300+ entries — a single agent stalls writing
+// it (the M75 register bug). So: batch the (already severity-sorted) findings, fan
+// out bounded generator agents (each writes its batch's entries via the shared gate),
+// then ASSEMBLE deterministically with severity section headers, and chunk-write.
+phase("Plain-English");
+const peTarget = `${projectDir}/.gsd-t/techdebt_in_plain_english.md`;
+const sevLabel = { CRITICAL: "fix before launch", HIGH: "fix soon", MEDIUM: "schedule", LOW: "clean up eventually" };
+// Attach the deterministic TD number (matches the register: severity-sorted, tdStart+).
+const peItems = finalFindings.map((f, i) => ({
+  td: tdStart + i, severity: f.severity, title: ascii(f.title),
+  area: ascii(f.area), detail: ascii(f.detail || f.impact || "").slice(0, 500),
+}));
+const PE_BATCH = 36;
+const peBatches = [];
+for (let i = 0; i < peItems.length; i += PE_BATCH) peBatches.push(peItems.slice(i, i + PE_BATCH));
+const PE_SCHEMA = { type: "object", required: ["entries"], additionalProperties: false,
+  properties: { entries: { type: "array", items: { type: "object", required: ["td", "markdown"], properties: { td: { type: "integer" }, markdown: { type: "string" } } } } } };
+
+const peResults = await parallel(peBatches.map((batch, bi) => async () => {
+  const prompt = [
+    `Write NON-TECHNICAL ("plain English") companion entries for a tech-debt register, for a non-engineer stakeholder (founder/PM).`,
+    `For EACH finding below, produce one entry. Return JSON {entries:[{td, markdown}]} where markdown is EXACTLY:`,
+    `### TD-<td> - <plain-English name, no jargon>`,
+    `**What it is.** <1-2 sentences, no jargon; define any unavoidable term in parentheses>`,
+    `**Why it matters.** <business/user consequence>`,
+    `**Real-world analogy.** <a concrete everyday comparison that genuinely maps to THIS issue>`,
+    `**Severity.** <the plain-urgency phrase given per item>`,
+    `Keep the td number EXACTLY. ASCII punctuation only (hyphens, straight quotes — NO em-dashes/smart-quotes/ellipsis). No preamble.`,
+    ``,
+    `Findings (batch ${bi + 1}/${peBatches.length}):`,
+    "```json",
+    JSON.stringify(batch.map((it) => ({ ...it, severityPhrase: sevLabel[it.severity] || "review" }))),
+    "```",
+  ].join("\n");
+  try {
+    const r = await gatedAgent(prompt, { label: `plain-english ${bi + 1}/${peBatches.length}`, phase: "Plain-English", schema: PE_SCHEMA, model: "sonnet" });
+    return { bi, entries: (r && Array.isArray(r.entries)) ? r.entries : [] };
+  } catch (e) { return { bi, entries: [], failed: true }; }
+}));
+// Map td -> entry markdown, then assemble grouped by severity (deterministic headers).
+const peByTd = {};
+for (const r of peResults) for (const e of (r.entries || [])) if (e && e.td != null) peByTd[e.td] = ascii(e.markdown || "");
+const peFailed = peResults.filter((r) => r.failed).length;
+const peGroups = { CRITICAL: [], HIGH: [], MEDIUM: [], LOW: [] };
+for (const it of peItems) { const md = peByTd[it.td]; if (md && peGroups[it.severity]) peGroups[it.severity].push(md.trim()); }
+const peSevHead = { CRITICAL: "## 🔴 Critical", HIGH: "## 🟠 High", MEDIUM: "## 🟡 Medium", LOW: "## 🟢 Low" };
+const peHeader = [
+  `# Tech Debt - Plain English`, "",
+  `> Non-technical companion to .gsd-t/techdebt.md (Scan${scanNumber ? " #" + scanNumber : ""}, ${peItems.length} findings). One entry per item: what it is, why it matters, a real-world analogy, plain-urgency severity. Grouped by severity.`, "", "---",
+].join("\n");
+// Build chunks: header, then per-severity section (header + its entries), sub-split ≤30KB.
+const peChunks = [peHeader];
+for (const sev of ["CRITICAL", "HIGH", "MEDIUM", "LOW"]) {
+  const items = peGroups[sev];
+  if (!items.length) continue;
+  let buf = `\n${peSevHead[sev]} (${items.length})\n\n`;
+  for (const md of items) {
+    const piece = md + "\n\n";
+    if (buf.length + piece.length > 30000) { peChunks.push(buf); buf = ""; }
+    buf += piece;
+  }
+  if (buf.trim()) peChunks.push(buf);
+}
+let peWrote = 0;
+for (let ci = 0; ci < peChunks.length; ci++) {
+  const first = ci === 0;
+  const res = await gatedAgent(
+    [
+      first ? `Create the file \`${peTarget}\` (overwrite) with EXACTLY the content between markers, using the Write tool. Verbatim.`
+            : `APPEND EXACTLY the content between markers to the END of \`${peTarget}\` (do not overwrite; append) via a Bash heredoc \`cat >> ${peTarget} <<'GSDTEOF'\` … \`GSDTEOF\`. Verbatim.`,
+      `Reply ONLY "OK".`, "", "<<<C>>>", peChunks[ci], "<<<END>>>",
+    ].join("\n"),
+    { label: `plain-english write ${ci + 1}/${peChunks.length}`, phase: "Plain-English", model: "haiku" }
+  ).catch((e) => ({ _e: String(e && e.message) }));
+  if (typeof res === "string" && /ok/i.test(res)) peWrote++;
+}
+log(`plain-english: ${Object.values(peGroups).reduce((a, b) => a + b.length, 0)}/${peItems.length} entries, grouped by severity, ${peWrote}/${peChunks.length} chunks written${peFailed ? `; ${peFailed} gen batch(es) failed` : ""}`);
+
 // Commit the docs + dimension files + plain-english via a small agent (Bash git).
 const commitAgent = await agent(
   [