@tekyzinc/gsd-t 4.13.12 → 4.15.10

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

@@ -88,6 +88,7 @@ const PREFLIGHT_SCHEMA = {
   properties: {
     ok:                  { type: "boolean" },
     branch:              { type: "string" },
+    repoName:            { type: "string", description: "the project directory's basename (e.g. 'hilo-figma-atos') — used to suffix shared scan/doc files" },
     priorRegisterExists: { type: "boolean" },
     priorMaxTd:          { type: "integer", description: "highest TD-NNN in the prior register, 0 if none" },
     notes:               { type: "string" },
@@ -287,6 +288,46 @@ async function runCli(verb, target, label) {
   return r || { ok: false, reason: "graph-unavailable", via: "error" };
 }
 
+// Build the graph index (`gsd-t graph index`) when it is absent. The wired path
+// is documented "build index if absent, then query" but the BUILD step was never
+// wired — so on any project without a pre-built index (the common case), scan
+// silently grep-fell-back and the graph was NEVER used (observed on hilo-figma-atos
+// 2026-06-30: a 30M-token scan grep-fell-back because the index was never built).
+// `graph index` is a longer command than the verb queries → bigger timeout.
+// [RULE] scan-builds-index-when-absent
+async function runCliBuild() {
+  const prompt = [
+    `Build the GSD-T code-graph index for the project at \`${projectDir}\`, then report. Steps:`,
+    `1. If \`${projectDir}/bin/gsd-t.js\` exists, run: \`node ${projectDir}/bin/gsd-t.js graph index\` (via="local"). Otherwise run: \`gsd-t graph index\` (via="global"). Use cwd \`${projectDir}\`. This may take up to a few minutes on a large repo — wait for it to finish. Do NOT redirect stderr.`,
+    `2. Set ok=true if the command exits 0 (the index built). Set ok=false with a short reason + first ~200 chars of stderr otherwise.`,
+    `Do NOT do any other work. ONLY run this one build command and report the structured result.`,
+  ].join("\n");
+  const r = await agent(prompt, {
+    label: "graph:index-build",
+    phase: "Graph-Wiring",
+    model: "haiku",
+    schema: GRAPH_BUILD_SCHEMA,
+  }).catch((e) => ({ ok: false, reason: `agent-error: ${e && e.message}` }));
+  return r || { ok: false, reason: "build-failed" };
+}
+
+// M99 D2: persist a kind:'wiring' ledger line for this workflow.
+// M81 sandbox: all I/O through agent() Bash; no require/fs in the sandbox.
+// Uses the `gsd-t graph wiring-log` CLI shim (avoids embedding require() in strings).
+// [RULE] wiring-mode-three-states / [RULE] consumer-label-from-context-not-setenv
+async function persistWiringMode(mode) {
+  const consumer = "scan";
+  await agent(
+    [
+      `Persist one graph-wiring-mode ledger line for the scan workflow.`,
+      `Run: \`gsd-t graph wiring-log --consumer ${consumer} --mode ${mode} --project '${projectDir}'\``,
+      `If the command is not found, exit 0 (ledger write is optional).`,
+      `Return ONLY: {"ok": true} or {"ok": false, "reason": "<short reason>"}.`,
+    ].join("\n"),
+    { label: "scan:wiring-ledger", phase: "Graph-Wiring", model: "haiku", schema: { type: "object", required: ["ok"], properties: { ok: { type: "boolean" }, reason: { type: "string" } } } }
+  ).catch(() => null); // fail-open
+}
+
 // Preflight: an agent checks branch + whether a prior register exists, via Bash.
 // (No fs in the body — that was the bug.)
 phase("Preflight");
@@ -295,8 +336,9 @@ const pre = await agent(
     `You are the preflight check for a GSD-T deep scan of the project at \`${projectDir}\`.`,
     `Using Bash/Read tools, determine:`,
     `1. The current git branch (\`git -C ${projectDir} rev-parse --abbrev-ref HEAD\`; if not a git repo, report branch "(no-git)").`,
-    `2. Whether \`${projectDir}/.gsd-t/techdebt.md\` exists (priorRegisterExists).`,
-    `3. If it exists, the HIGHEST TD-NNN number in it (grep \`### TD-\`, parse the max integer; priorMaxTd). If absent, priorMaxTd=0.`,
+    `2. The repo name = the basename of the resolved project dir (\`basename "$(cd ${projectDir} && pwd)"\`) — e.g. "hilo-figma-atos". Report as repoName (used to label the team-shared share/ copies).`,
+    `3. Whether \`${projectDir}/.gsd-t/techdebt.md\` exists (priorRegisterExists).`,
+    `4. If it exists, the HIGHEST TD-NNN number in it (grep \`### TD-\`, parse the max integer; priorMaxTd). If absent, priorMaxTd=0.`,
     `Set ok=true unless something makes scanning impossible (e.g. projectDir does not exist). Return JSON per the schema.`,
   ].join("\n"),
   { label: "preflight", phase: "Preflight", schema: PREFLIGHT_SCHEMA, model: "haiku" }
@@ -306,7 +348,12 @@ if (!pre || !pre.ok) {
   return { status: "failed", reason: "preflight-failed", preflight: pre };
 }
 const tdStart = (pre.priorRegisterExists ? (pre.priorMaxTd || 0) : 0) + 1;
-log(`preflight ok — branch=${pre.branch}, priorRegister=${pre.priorRegisterExists}, TD numbering starts at TD-${tdStart}`);
+// #47: repo-name suffix for the TEAM-SHARED copies only. INTERNAL files keep their
+// fixed names (.gsd-t/techdebt.md, .gsd-t/scan/<dim>.md, docs/*.md) so all internal
+// tooling (promote-debt, gap-analysis, complete-milestone, …) keeps working — zero
+// blast radius. The repo suffix appears ONLY on the share/ exports at the end.
+const repoName = (pre.repoName && /^[A-Za-z0-9._-]+$/.test(pre.repoName)) ? pre.repoName : "project";
+log(`preflight ok — branch=${pre.branch}, repo=${repoName}, priorRegister=${pre.priorRegisterExists}, TD numbering starts at TD-${tdStart}`);
 
 // Volume probe — an agent measures the codebase (its own Bash) and carves slices.
 phase("Probe");
@@ -355,15 +402,31 @@ if (graphMode === "disabled") {
   // ZERO graph calls in this path — [RULE] no-graph-baseline-proven-graph-free.
   graphWiringMode = "disabled";
   log("graph-wiring: DISABLED (no-graph baseline mode — graph-query call-count == 0; AC-4 baseline)");
+  await persistWiringMode("disabled"); // M99 D2: persist wiring mode [RULE] wiring-mode-three-states
 } else {
   // graphMode === "wired": build index if absent, then query structural slice.
   // Step 1: check if index exists and is queryable.
-  const statusResult = await runCli("status", null, "status");
+  let statusResult = await runCli("status", null, "status");
+  // Step 1b: if the index is absent/unqueryable, BUILD it once, then re-probe.
+  // This is the previously-missing build step — without it scan grep-fell-back on
+  // every project lacking a pre-built index (hilo-figma-atos 2026-06-30).
+  // [RULE] scan-builds-index-when-absent
+  if (!statusResult || !statusResult.ok) {
+    log(`graph-wiring: index not queryable (${(statusResult && statusResult.reason) || "graph-unavailable"}) — building it now (gsd-t graph index)...`);
+    const buildResult = await runCliBuild();
+    if (buildResult && buildResult.ok) {
+      log(`graph-wiring: index build OK — re-probing status.`);
+      statusResult = await runCli("status", null, "status");
+    } else {
+      log(`graph-wiring: index build FAILED [${(buildResult && buildResult.reason) || "build-failed"}] — falling back to grep-mode.`);
+    }
+  }
   if (!statusResult || !statusResult.ok) {
-    // Graph unavailable — announce fallback, continue with intact grep-mode scan.
-    // [RULE] parser-fail-disables-loud-never-silent (from graph-query-cli-contract)
+    // Graph still unavailable after a build attempt — announce fallback, continue
+    // with intact grep-mode scan. [RULE] parser-fail-disables-loud-never-silent
     graphWiringMode = "fallback-announced";
-    log(`⚠ GRAPH-FALLBACK (ANNOUNCED): graph status probe returned not-ok [reason=${(statusResult && statusResult.reason) || "graph-unavailable"}, via=${(statusResult && statusResult.via) || "?"}] — scan continues in full grep-mode (today's architecture, intact). Structural findings from LLM reconstruction only. Build the index (gsd-t graph build) to enable graph-wired accuracy.`);
+    log(`⚠ GRAPH-FALLBACK (ANNOUNCED): graph unavailable after build attempt [reason=${(statusResult && statusResult.reason) || "graph-unavailable"}, via=${(statusResult && statusResult.via) || "?"}] — scan continues in full grep-mode (today's architecture, intact). Structural findings from LLM reconstruction only.`);
+    await persistWiringMode("fallback-announced"); // M99 D2 [RULE] wiring-mode-three-states
   } else {
     // Step 2: query the structural slice (dead-code + dangling + clusters).
     // These are the findings the deep-finders currently reconstruct by reading files (error-prone);
@@ -382,6 +445,7 @@ if (graphMode === "disabled") {
       // All three verbs returned graph-unavailable — announce fallback.
       graphWiringMode = "fallback-announced";
       log(`⚠ GRAPH-FALLBACK (ANNOUNCED): all structural-slice queries returned graph-unavailable — scan continues in full grep-mode. Dead-code / dangling / cluster findings from LLM reconstruction only.`);
+      await persistWiringMode("fallback-announced"); // M99 D2 [RULE] wiring-mode-three-states
     } else {
       // Structural slice assembled — will be injected into scanSlice finder agents.
       structuralSlice = {
@@ -396,8 +460,15 @@ if (graphMode === "disabled") {
         },
         tier: (deadCodeResult && deadCodeResult.tier) || (danglingResult && danglingResult.tier) || "unknown",
       };
-      graphWiringMode = "wired";
+      // M99 Red Team fix: emit "WIRED" (uppercase) to MATCH the --auto router
+      // producers (bin/gsd-t.js:3915) AND the rollup's comparison
+      // (gsd-t-graph-metrics-rollup.cjs:333 `=== "WIRED"`). Lowercase "wired" here
+      // fell through all three rollup branches → a successfully-wired scan reported
+      // WIRED:0, defeating success criterion 13 (the metric M99 exists to surface).
+      // [RULE] wiring-mode-casing-matches-rollup
+      graphWiringMode = "WIRED";
       log(`graph-wiring: WIRED — structural slice ready (dead-code: ${structuralSlice.deadCode.length} candidates, dangling: ${structuralSlice.dangling.length} edges, clusters: ${structuralSlice.clusters.length} groups, tier: ${structuralSlice.tier}). Slice will be INJECTED ADDITIVELY into scanSlice deep-finders. [RULE] scan-injects-structural-slice`);
+      await persistWiringMode("WIRED"); // M99 D2 [RULE] wiring-mode-three-states / wiring-mode-casing-matches-rollup
     }
   }
 }
@@ -722,6 +793,11 @@ function fmtChunks(today) {
   head.push(`**Date:** ${today}`);
   head.push(`**Slices run:** ${slices.length} | **Coverage:** ${coverageComplete ? `FULL - all ${slices.length} slices succeeded` : `PARTIAL - ${succeededCount}/${slices.length} succeeded`}`);
   head.push(`**Verified findings:** ${counts.total}`, "");
+  // M99 D2 T4: stamp graphWiringMode into the header (north-star: invisible fallback leaves a trace).
+  // A `fallback-announced` mode co-occurring with a same-window outcome:'hit' is the machine-visible
+  // NiceNote scan-#12 contradiction. [RULE] wiring-mode-three-states
+  const _wiringEmoji = { "wired": "✅", "fallback-announced": "⚠️", "disabled": "🚫", "pending": "⏳" };
+  head.push(`**Graph wiring:** ${_wiringEmoji[graphWiringMode] || "?"} \`${graphWiringMode}\` (WIRED = graph answered structural queries; fallback-announced = graph unavailable, fell back to grep; disabled = no-graph baseline)`, "");
   head.push(`> Effort estimates use GSD-T-native units (domain / wave / spawn / token-spend). Never human-hours.`);
   head.push(`> TD numbering continues from the prior register (if any, archived). This scan begins at **TD-${tdStart}**.`, "");
   if (!coverageComplete) head.push(`> ⚠️ **PARTIAL COVERAGE - ${failedSlices.length} of ${slices.length} codebase areas were NOT scanned this pass** (failed to return findings): ${ascii(failedSlices.join(", "))}. Findings UNDER-COUNT the real debt. Re-run (resume) for full coverage.`, "");
@@ -767,10 +843,15 @@ const today = (typeof todayAgent === "string" && /\d{4}-\d{2}-\d{2}/.test(todayA
 
 let archivePath = "";
 if (pre.priorRegisterExists) {
+  // #47: archive the prior register + ALL prior dimension files into
+  // .gsd-t/scan/archive/ with a DATETIME stamp so the user can diff new-vs-prior.
+  // Handles BOTH the new suffixed names and any legacy unsuffixed leftovers.
   const arch = await agent(
     [
-      `Archive the existing tech-debt register in \`${projectDir}\` via Bash, then report the archive path.`,
-      `Rename \`${projectDir}/.gsd-t/techdebt.md\` to \`${projectDir}/.gsd-t/techdebt_${today}.md\`; if that exists, append _2/_3. Use \`git mv\` if a git repo else \`mv\`. Reply with ONLY the resulting archive filename.`,
+      `Archive the existing scan outputs in \`${projectDir}\` into a dated archive folder so the user can diff new-vs-prior, then report the archive dir. Steps (via Bash):`,
+      `1. STAMP="$(date +%Y%m%d-%H%M)". ARCH="${projectDir}/.gsd-t/scan/archive". mkdir -p "$ARCH".`,
+      `2. Move each existing scan output into "$ARCH" with the STAMP appended before .md. For EACH that exists, move it: \`${projectDir}/.gsd-t/techdebt.md\`, \`${projectDir}/.gsd-t/techdebt_in_plain_english.md\`, and \`${projectDir}/.gsd-t/scan/<dim>.md\` for each dim in {architecture,security,quality,business-rules,contract-drift}. Target name: same basename + "-$STAMP.md" (e.g. techdebt-20260630-1542.md). Use \`git mv\` if a git repo else \`mv\`. Skip any that don't exist (no error).`,
+      `3. Reply with ONLY the archive dir path "$ARCH".`,
     ].join("\n"),
     { label: "synthesis:archive", phase: "Synthesis", model: "haiku" }
   ).catch(() => null);
@@ -783,7 +864,7 @@ const { chunks, lastTd } = fmtChunks(today);
 // each subsequent chunk is APPENDED. Done SEQUENTIALLY so the file builds in order and
 // each agent's prompt+output stays small enough to pass intact. The register path is
 // passed to each chunk; only the chunk content varies.
-const regPath = `${projectDir}/.gsd-t/techdebt.md`;
+const regPath = `${projectDir}/.gsd-t/techdebt.md`; // internal fixed name (shared copy suffixed in share/)
 let chunkOk = 0;
 for (let ci = 0; ci < chunks.length; ci++) {
   const isFirst = ci === 0;
@@ -901,7 +982,7 @@ log(`document phase: ${docsOk.length}/${docTargets.length} written/merged${docsF
 // 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 peTarget = `${projectDir}/.gsd-t/techdebt_in_plain_english.md`; // internal fixed name (shared copy suffixed in share/)
 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) => ({
@@ -991,11 +1072,27 @@ const peComplete = peActual === peExpectedEntries;
 if (!peComplete) log(`⚠ plain-english INCOMPLETE: wrote ${peActual}/${peExpectedEntries} entries (writer said ${typeof peWriteRes === "string" ? peWriteRes.trim().slice(0, 20) : JSON.stringify(peWriteRes).slice(0, 40)})`);
 log(`plain-english: ${peExpectedEntries}/${peItems.length} entries, grouped by severity, ${peChunks.length} chunks, on-disk count ${peActual ?? "?"} (${peComplete ? "COMPLETE" : "INCOMPLETE"})${peFailed ? `; ${peFailed} gen batch(es) failed` : ""}`);
 
-// Commit the docs + dimension files + plain-english via a small agent (Bash git).
+// #47: EXPORT-COPY the living docs into a share/ folder with the repo-name suffix —
+// the LAST scan step. Originals stay at their fixed docs/ names (GSD-T reads them by
+// hardcoded path under the No-Re-Research rule); the share/ copies are the team-shareable,
+// project-labeled set. Regenerated each scan (overwrite). The scan reports themselves are
+// already suffixed in place (techdebt-<repo>.md, scan/<dim>-<repo>.md).
+const shareAgent = await agent(
+  [
+    `Create a shareable, repo-labeled copy of this project's living docs in \`${projectDir}\` via Bash. Steps:`,
+    `1. \`mkdir -p ${projectDir}/share\`.`,
+    `2. COPY (do NOT move — keep the original at its fixed name) each of these that EXISTS into \`${projectDir}/share/\` with the repo name "${repoName}" suffixed before .md. Living docs: \`docs/architecture.md\`→\`share/architecture-${repoName}.md\`, \`docs/requirements.md\`→\`share/requirements-${repoName}.md\`, \`docs/workflows.md\`→\`share/workflows-${repoName}.md\`, \`docs/infrastructure.md\`→\`share/infrastructure-${repoName}.md\`, \`README.md\`→\`share/README-${repoName}.md\`. Scan reports: \`.gsd-t/techdebt.md\`→\`share/techdebt-${repoName}.md\`, \`.gsd-t/techdebt_in_plain_english.md\`→\`share/techdebt_in_plain_english-${repoName}.md\`, and each \`.gsd-t/scan/<dim>.md\`→\`share/<dim>-${repoName}.md\` for dim in {architecture,security,quality,business-rules,contract-drift} (NOTE these scan dimension files share basenames with the living-doc architecture — keep them distinct: prefer \`share/scan-<dim>-${repoName}.md\` for the .gsd-t/scan/ ones to avoid colliding with docs/architecture). Overwrite existing share/ files (always fresh). Skip any source that doesn't exist (no error).`,
+    `3. Reply with ONLY the count of files copied.`,
+  ].join("\n"),
+  { label: "share-export", phase: "Document", model: "haiku" }
+).catch(() => null);
+log(`share/ export: ${typeof shareAgent === "string" ? shareAgent.trim().slice(0, 40) : "done"} → ${projectDir}/share/`);
+
+// Commit the docs + dimension files + plain-english + share/ via a small agent (Bash git).
 const commitAgent = await agent(
   [
     `Commit the GSD-T scan's generated documents in \`${projectDir}\` via Bash git, IF it is a git repo (else report skipped).`,
-    `Stage: \`.gsd-t/scan\`, \`.gsd-t/techdebt_in_plain_english.md\`, \`docs\`, \`README.md\` (do NOT stage \`.gsd-t/scan/.doc-backup\` if present). Commit message: "scan: deep document cross-population (${docsOk.length} docs) + dimension files". Do NOT push. Return JSON per the schema (status "rendered" if committed, "skipped" if not a git repo / nothing to commit, "failed" on error; outputPath optional).`,
+    `Stage: \`.gsd-t/scan\`, \`.gsd-t/techdebt.md\`, \`.gsd-t/techdebt_in_plain_english.md\`, \`share\`, \`docs\`, \`README.md\` (do NOT stage \`.gsd-t/scan/.doc-backup\` if present; \`.gsd-t/scan/archive\` MAY be staged — the dated history is worth keeping). Commit message: "scan: deep document cross-population (${docsOk.length} docs) + dimension files + share/ export". Do NOT push. Return JSON per the schema (status "rendered" if committed, "skipped" if not a git repo / nothing to commit, "failed" on error; outputPath optional).`,
   ].join("\n"),
   { label: "commit-docs", phase: "Document", schema: RENDER_SCHEMA, model: "haiku" }
 ).catch((e) => ({ status: "failed", notes: String(e && e.message) }));

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

@@ -230,6 +230,23 @@ const VERDICT_SCHEMA = {
   },
 };
 
+// M99 D2: persist a kind:'wiring' ledger line. M81 sandbox: all I/O through agent() Bash.
+// Uses the `gsd-t graph wiring-log --auto` CLI shim (avoids embedding require() in strings).
+// [RULE] wiring-mode-three-states / [RULE] consumer-label-from-context-not-setenv
+async function persistWiringMode(phaseName) {
+  const consumer = "verify";
+  await agent(
+    [
+      `Persist one graph-wiring-mode ledger line for the verify workflow.`,
+      `Run: \`gsd-t graph wiring-log --consumer ${consumer} --auto --project '${projectDir}'\``,
+      `(--auto detects WIRED if the graph store exists, else fallback-announced)`,
+      `If the command is not found, exit 0 (ledger write is optional).`,
+      `Return ONLY: {"ok": true} or {"ok": false, "reason": "<short reason>"}.`,
+    ].join("\n"),
+    { label: "verify:wiring-ledger", phase: phaseName, model: "haiku", schema: { type: "object", required: ["ok"], properties: { ok: { type: "boolean" }, reason: { type: "string" } } } }
+  ).catch(() => null);
+}
+
 // ───── Script body ─────
 
 if (!milestone) {
@@ -244,6 +261,8 @@ if (!pre.ok) {
   return { status: "failed", reason: "preflight-failed", preflight: pre.envelope };
 }
 const brief = await generateBrief(projectDir, { kind: "verify", milestone, id: `verify-${(milestone || "m").toLowerCase()}` });
+// M99 D2: persist graphWiringMode for the verify consumer. [RULE] wiring-mode-three-states
+await persistWiringMode("Preflight");
 
 phase("Verify-Gate");
 const vg = await runVerifyGate(projectDir);