@tekyzinc/gsd-t 4.6.11 → 4.7.10

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

@@ -4,6 +4,25 @@
 // Debug phase — up to 2 fix cycles per CLAUDE.md Prime Rule. If still failing
 // after 2 cycles, exit with `needs-human` so the human operator can step in.
 //
+// M89: Stated-Claims→classify→research wiring (auto-research-contract v1.2.0 §6.5/§1/§2/§3/§4/§7).
+// Each debug cycle embeds the Stated-Claims snippet (§6.5) so the debug agent tags failure-root
+// claims KNOWN|GUESSED. After each cycle, GUESSED claims are classified: external failure-root
+// → write §7 marker (status=uncited) → research agent (model:"fable") → cite → flip marker
+// (status=cited) — instead of a patch-guess (pairs with #33 circuit-breaker). Internal →
+// grep/Read; grep-empty → escalate to external (§5.1). The existing debug-cycle ternary
+// (model: cycle===1?"opus":(overrides["debug-cycle-2"]??"fable")) is PRESERVED; the research
+// stage is a SEPARATE agent() with its own bare "fable" literal. Idempotent per §4.1.
+//
+// M90 §3 D4-T3: Loop-ledger halt wired via inline runCli helper (option b).
+// After each cycle, append-cycle is called with the symptom as the assertion, the primary
+// edited file as the surface, and "unit" as the fileClass. After cycle 2 (end of loop),
+// read-exit-state is called; if haltedButNoReExamination=true (the same computed signature
+// appeared across both cycles — the ledger proves non-convergence), the workflow exits at
+// the cycle-2 boundary with the ledger's PREMISE_RE_EXAMINATION directive rather than the
+// generic `needs-human`. This is option (b): re-anchor the halt to the cycle-2 boundary,
+// keeping the existing 2-cycle cap unchanged and only changing the EXIT REASON when the
+// ledger fact proves non-convergence. Contract: unproven-assumption-doctrine-contract.md §3.2.
+//
 // args: { symptom, projectDir? }
 
 export const meta = {
@@ -55,6 +74,7 @@ async function generateBrief(projectDir, { kind = "execute", milestone, domain,
 
 const projectDir = _args.projectDir || ".";
 const symptom = _args.symptom || null;
+const milestone = _args.milestone || null; // tags loop-ledger halts so they scope to this milestone
 
 const DEBUG_CYCLE_SCHEMA = {
   type: "object",
@@ -68,9 +88,198 @@ const DEBUG_CYCLE_SCHEMA = {
       properties: { pass: { type: "integer" }, fail: { type: "integer" } },
     },
     nextStepsIfNotResolved: { type: "string" },
+    // M89 §6.5 — Stated Claims: raw [GUESSED:*] lines from the debug cycle agent
+    statedClaims: { type: "array", items: { type: "string" } },
+    // Primary artifact path for §7 marker writes (e.g. the file being debugged / a debug report)
+    artifactPath: { type: "string" },
   },
 };
 
+// M89 §7 — normalize claim-key (§4.1 exact-match key). Cycle-2 finding #1: collapse
+// EVERY non-word run to a space so the key is marker-syntax-safe; byte-identical across
+// all 4 workflows (m89-normalize-claim-key-parity).
+function normalizeClaimKey(claim) {
+  return claim.toLowerCase().replace(/[^\w]+/g, " ").trim();
+}
+function uncitedMarker(key) { return `<!-- auto-research-claim: class=external key=${key} status=uncited -->`; }
+function citedMarker(key)   { return `<!-- auto-research-claim: class=external key=${key} status=cited -->`; }
+
+// M89 §1 — classify via bin/gsd-t-research-gate.cjs (D1 envelope)
+async function classifyClaim(projectDir, claimText, phaseName) {
+  return runCli(projectDir, "research-gate", ["classify", claimText, "--json"], "gsd-t-research-gate.cjs", "classify-claim", true, phaseName);
+}
+
+// M89 §4.1 — exact key match idempotency
+function isAlreadyCited(artifactText, claimKey) {
+  return artifactText.includes(`auto-research-claim: class=external key=${claimKey} status=cited`);
+}
+
+// M89 §5.1 — grep repo for internal claim resolution
+async function grepForClaim(projectDir, claimText, phaseName) {
+  const escaped = claimText.replace(/'/g, "'\\''").slice(0, 200);
+  const prompt = [
+    `Decide whether THIS repo's own code/contracts/tests CONFIRM the SPECIFIC claim — not merely`,
+    `share vocabulary with it (Red Team MEDIUM). Project: \`${projectDir}\`. Claim: "${escaped}"`,
+    `Run: \`grep -r --include="*.js" --include="*.ts" --include="*.md" --include="*.cjs" -l "${escaped.slice(0, 60)}" "${projectDir}" 2>/dev/null | head -5\``,
+    `Then Read the candidates and judge: set found=true ONLY IF the repo content actually CONFIRMS`,
+    `the value/shape/behavior the claim asserts. Coincidental keyword overlap = found=false.`,
+    `If the claim is about an EXTERNAL system's behavior (3rd-party API, library, browser, protocol),`,
+    `grep CANNOT confirm it → found=false so it escalates to web research.`,
+    `Return JSON: { "found": <boolean>, "matches": ["<file>", ...] }. No other work.`,
+  ].join("\n");
+  const schema = { type: "object", required: ["found"], additionalProperties: true, properties: { found: { type: "boolean" }, matches: { type: "array", items: { type: "string" } } } };
+  const r = await agent(prompt, { label: "grep-internal-claim", model: "haiku", schema, phase: phaseName }).catch(() => ({ found: false, matches: [] }));
+  return r || { found: false, matches: [] };
+}
+
+// M89 §1.1 — AMBIGUOUS → LLM JUDGE (bare model:"fable" — NOT the ?? form; "judge" is not
+// a designated stage, so the bare literal passes the M85 tier-set check and stays DISTINCT
+// from the debug-cycle ternary). internal/external/uncertain; uncertain → research (never
+// guess-internal). On error → "uncertain" (fail toward research).
+const CLASSIFY_JUDGE_SCHEMA = {
+  type: "object", required: ["verdict"], additionalProperties: true,
+  properties: { verdict: { type: "string", enum: ["internal", "external", "uncertain"] }, reason: { type: "string" } },
+};
+async function judgeAmbiguous(claimText, phaseName) {
+  const prompt = [
+    `You are the M89 ambiguous-claim JUDGE (auto-research-contract §1.1). The mechanical string-fact`,
+    `classifier could not decide this GUESSED claim. Decide in natural language. Claim: "${claimText}"`,
+    `- "internal"  = about THIS repo's OWN code/contracts/tests — grep/Read can confirm.`,
+    `- "external"  = asserts an OUTSIDE system's behavior/shape/limit — needs web research.`,
+    `- "uncertain" = you cannot CONFIDENTLY place it internal — per M89 doctrine it is RESEARCHED, never guessed.`,
+    `Return JSON: { "verdict": "internal"|"external"|"uncertain", "reason": "<one line>" }. No file/web work in THIS step.`,
+  ].join("\n");
+  const r = await agent(prompt, { label: "classify-judge", model: "fable", schema: CLASSIFY_JUDGE_SCHEMA, phase: phaseName })
+    .catch((e) => ({ verdict: "uncertain", reason: `judge error: ${e && e.message}` }));
+  return (r && r.verdict) || "uncertain";
+}
+
+// M89 §2 — research result schema
+const RESEARCH_RESULT_SCHEMA = {
+  type: "object", required: ["ok", "gapKey"], additionalProperties: true,
+  properties: { ok: { type: "boolean" }, gapKey: { type: "string" }, citedBlock: { type: "string" }, sourceUrls: { type: "array", items: { type: "string" } }, fetchDates: { type: "array", items: { type: "string" } }, reason: { type: "string" } },
+};
+
+// M89 Research sub-routine: classify+cite one GUESSED claim (§1/§2/§3/§4/§5.1/§7)
+async function runResearchForClaim(projectDir, claimText, artifactPath, phaseName) {
+  const claimKey = normalizeClaimKey(claimText);
+
+  // FAIL-CLOSED (Red Team HIGH): artifactPath is self-reported + optional. An EXTERNAL (or
+  // ambiguous→escalated-external) guess MUST get its §7 uncited marker written SOMEWHERE so the
+  // §7 ENFORCE gate has something to fail on. Use a DETERMINISTIC FALLBACK ARTIFACT when none.
+  const claimSlug = claimKey.replace(/\s+/g, "-").slice(0, 80) || "claim";
+  const externalArtifact = artifactPath || `${projectDir}/.gsd-t/research/debug-${claimSlug}.md`;
+
+  // §4.1 idempotency check — read the path actually WRITTEN (externalArtifact = real OR
+  // fallback) so a re-run does not re-research a claim already cited in the fallback (MEDIUM).
+  {
+    const atxt = await agent(`Read \`${externalArtifact}\` and return JSON: { "text": "<content>" }. If missing: { "text": "" }.`,
+      { label: "read-artifact", model: "haiku", schema: { type: "object", required: ["text"], properties: { text: { type: "string" } }, additionalProperties: false }, phase: phaseName })
+      .catch(() => ({ text: "" }));
+    if (isAlreadyCited((atxt && atxt.text) || "", claimKey)) {
+      log(`Research: skip "${claimKey.slice(0, 50)}" — already cited (§4.1)`);
+      return;
+    }
+  }
+
+  const cls = await classifyClaim(projectDir, claimText, phaseName);
+  const envelope = cls.envelope;
+  if (!envelope || !envelope.ok) {
+    log(`Research: classify error — ${cls.stderr || JSON.stringify(envelope)}`);
+    return;
+  }
+
+  async function appendUncitedMarker(ap, key) {
+    if (!ap) return;
+    const m = uncitedMarker(key);
+    const sp = ap.replace(/'/g, "'\\''");
+    await agent(
+      `Ensure the parent dir exists, then append \`${m}\` to \`${ap}\` if not already present. Bash: \`mkdir -p "$(dirname '${sp}')" && { grep -qF '${m.replace(/'/g, "'\\''")}' '${sp}' 2>/dev/null || echo '${m.replace(/'/g, "'\\''")}' >> '${sp}'; }\`. Return JSON: { "done": true }.`,
+      { label: "write-uncited-marker", model: "haiku", schema: { type: "object", required: ["done"], properties: { done: { type: "boolean" } }, additionalProperties: true }, phase: phaseName }
+    ).catch(() => {});
+  }
+
+  async function flipAndCite(ap, key, citedBlock) {
+    if (!ap || !citedBlock) return;
+    const um = uncitedMarker(key);
+    const cm = citedMarker(key);
+    await agent(
+      `Ensure the parent dir of \`${ap}\` exists (Bash: \`mkdir -p "$(dirname '${ap.replace(/'/g, "'\\''")}')"\`). Then Edit \`${ap}\` (create if missing): replace \`${um}\` with \`${cm}\`, then append:\n${citedBlock}\nReturn JSON: { "done": true }.`,
+      { label: "flip-marker-cite", model: "haiku", schema: { type: "object", required: ["done"], properties: { done: { type: "boolean" }, action: { type: "string" } }, additionalProperties: true }, phase: phaseName }
+    ).catch(() => {});
+  }
+
+  // External-claim handler closure (reused by the ambiguous→judge path).
+  const doExternal = async () => {
+    log(`Research: external failure-root → research(fable) instead of patch-guess for "${claimKey.slice(0, 50)}"`);
+    await appendUncitedMarker(externalArtifact, claimKey);
+    const rr = await agent(
+      [
+        `Read \`${projectDir}/templates/prompts/research-subagent.md\` for the research protocol.`,
+        `Debug failure-root claim (external): "${claimText}"`,
+        `Gap-key: "${claimKey}"`,
+        `Emit ## Verified Facts (auto-research) block with source URL + fetch date. Append the trailer \`key: ${claimKey}\` on every fact line so the §7 gate matches by claim-key (Red Team MEDIUM #2). Return StructuredOutput JSON.`,
+      ].join("\n"),
+      { label: "research", model: "fable", schema: RESEARCH_RESULT_SCHEMA, phase: phaseName }
+    ).catch((e) => ({ ok: false, gapKey: claimKey, reason: String(e && e.message) }));
+
+    if (rr && rr.ok && rr.citedBlock) {
+      await flipAndCite(externalArtifact, claimKey, rr.citedBlock);
+      log(`Research: cited debug claim "${claimKey.slice(0, 50)}"`);
+    } else {
+      log(`Research: research failed for "${claimKey.slice(0, 50)}" — uncited marker remains`);
+    }
+  };
+
+  // Internal-claim handler closure (grep A3; grep-empty → escalate §5.1).
+  const doInternal = async () => {
+    log(`Research: internal debug claim → grep for "${claimText.slice(0, 50)}"`);
+    const gr = await grepForClaim(projectDir, claimText, phaseName);
+    if (gr.found) {
+      log(`Research: internal claim resolved by grep — no research needed`);
+    } else {
+      // §5.1 escalation
+      log(`Research: grep empty — escalating to external (§5.1): "${claimText.slice(0, 50)}"`);
+      await appendUncitedMarker(externalArtifact, claimKey);
+      const er = await agent(
+        [
+          `Read \`${projectDir}/templates/prompts/research-subagent.md\`.`,
+          `Debug escalation (§5.1 — grep returned nothing): "${claimText}"`,
+          `Gap-key: "${claimKey}"`,
+          `Emit ## Verified Facts (auto-research) block. Append the trailer \`key: ${claimKey}\` on every fact line so the §7 gate matches by claim-key (Red Team MEDIUM #2). Return StructuredOutput JSON.`,
+        ].join("\n"),
+        { label: "research", model: "fable", schema: RESEARCH_RESULT_SCHEMA, phase: phaseName }
+      ).catch((e) => ({ ok: false, gapKey: claimKey, reason: String(e && e.message) }));
+
+      if (er && er.ok && er.citedBlock) {
+        await flipAndCite(externalArtifact, claimKey, er.citedBlock);
+        log(`Research: escalated debug claim cited "${claimKey.slice(0, 50)}"`);
+      } else {
+        log(`Research: escalation research failed for "${claimKey.slice(0, 50)}"`);
+      }
+    }
+  };
+
+  // ── Dispatch by the 3-result classifier verdict (v1.3.0) ────────────────────
+  if (envelope.class === "external") {
+    await doExternal();
+  } else if (envelope.class === "internal") {
+    await doInternal();
+  } else {
+    // class:AMBIGUOUS — no string fact; the LLM judge decides (NOT regex). internal→grep;
+    // external→research; UNCERTAIN→research (uncertain = verify, NEVER guess-internal).
+    log(`Research: ambiguous debug claim → LLM judge for "${claimText.slice(0, 50)}" (when unsure, research)`);
+    const verdict = await judgeAmbiguous(claimText, phaseName);
+    log(`Research: ambiguous "${claimKey.slice(0, 50)}" → judge: ${verdict}`);
+    if (verdict === "internal") {
+      await doInternal();
+    } else {
+      if (verdict === "uncertain") log(`Research: judge UNCERTAIN → "${claimKey.slice(0, 50)}" treated external → research (no silent guess)`);
+      await doExternal();
+    }
+  }
+}
+
 if (!symptom) {
   log("debug: args.symptom required (description of failing test or error)");
   return { status: "failed", reason: "no-symptom" };
@@ -82,6 +291,11 @@ if (!pre.ok) return { status: "failed", reason: "preflight-failed", preflight: p
 const brief = await generateBrief(projectDir, { kind: "execute", id: "debug-brief" });
 
 let lastResult = null;
+// M90 §3 (fix-cycle: gate lifecycle) — track THIS run's per-signature cycle counts so the
+// non-convergence halt is RUN-SCOPED + REACHABLE within the 2-cycle debug cap (not dependent on
+// the global HALT_THRESHOLD=3 or stale cross-run ledger state). A signature seen in BOTH cycles
+// of THIS run = non-convergence at the cycle-2 boundary (option b).
+const thisRunSigCycles = {}; // { [signature]: maxCyclesSeenThisRun }
 for (let cycle = 1; cycle <= 2; cycle++) {
   phase(`Cycle ${cycle}`);
   const prompt = [
@@ -93,6 +307,14 @@ for (let cycle = 1; cycle <= 2; cycle++) {
     ``,
     `Steps: (1) read the relevant code, (2) form a hypothesis, (3) apply a fix, (4) run the affected test(s), (5) report.`,
     `Commit the fix with prefix "m61(debug-cycle${cycle})".`,
+    ``,
+    `**M89 STATED CLAIMS — REQUIRED (auto-research-contract §6.5):**`,
+    `Read \`${projectDir}/templates/prompts/stated-claims-snippet.md\` for the DETECT protocol.`,
+    `Before returning, emit a \`## Stated Claims\` section tagging every load-bearing claim`,
+    `[KNOWN] or [GUESSED:assumed|unknown|stale]. Key: when the failure root involves an external`,
+    `API/library behavior you ASSUMED (a guess), tag it GUESSED — the Research stage will`,
+    `verify it via web instead of letting you patch-guess. Include "statedClaims" array in`,
+    `StructuredOutput JSON: one per [GUESSED:*] line. Include "artifactPath" if relevant.`,
     `Return JSON per the schema.`,
   ].filter(Boolean).join("\n");
 
@@ -108,9 +330,99 @@ for (let cycle = 1; cycle <= 2; cycle++) {
     nextStepsIfNotResolved: "agent threw — investigate directly",
   }));
 
+  // M89 Research — classify GUESSED claims from this debug cycle (§6.5 trigger, separate from debug-cycle ternary)
+  if (Array.isArray(lastResult.statedClaims) && lastResult.statedClaims.length > 0) {
+    for (const claimLine of lastResult.statedClaims) {
+      const m = claimLine.match(/^\[GUESSED:[^\]]+\]\s*(.+)$/);
+      if (m) {
+        await runResearchForClaim(projectDir, m[1].trim(), lastResult.artifactPath || null, `Cycle ${cycle}`);
+      }
+    }
+  }
+
   if (lastResult.resolved) {
     return { status: "complete", cyclesUsed: cycle, finalResult: lastResult };
   }
+
+  // M90 §3 D4-T3 — append-cycle to the loop-ledger (option b: re-anchor halt to cycle-2 boundary).
+  // The symptom IS the assertion (the failing test/check); the primary edited file is the surface.
+  // The ledger tracks computed signatures cross-process — next cycle's append-cycle accumulates correctly.
+  // Uses the same runCli helper (inline agent()-Bash, no require/fs — M81 runtime-native invariant).
+  {
+    const primarySurface = (Array.isArray(lastResult.filesEdited) && lastResult.filesEdited.length > 0)
+      ? lastResult.filesEdited[0]
+      : "unknown";
+    const assertionArg = (symptom || "unknown-symptom").slice(0, 500);
+    const surfaceArg = String(primarySurface).slice(0, 200);
+    const ledgerAppend = await runCli(
+      projectDir,
+      "loop-ledger",
+      ["append-cycle",
+       "--assertion", assertionArg,
+       "--surface", surfaceArg,
+       "--fileClass", "unit",
+       ...(milestone ? ["--milestone", milestone] : []),
+       "--projectDir", projectDir],
+      "gsd-t-loop-ledger.cjs",
+      `loop-ledger-append-cycle-${cycle}`,
+      true,
+      `Cycle ${cycle}`
+    );
+    if (ledgerAppend.envelope) {
+      const env = ledgerAppend.envelope;
+      log(`M90 loop-ledger cycle ${cycle}: sig=${String(env.signature || "?").slice(0, 16)} cycles=${env.cycles} halted=${env.halted}`);
+      // RUN-SCOPED count: increment a LOCAL per-signature counter for each append IN THIS RUN —
+      // do NOT read env.cycles (that is the GLOBAL cumulative count across all prior runs; a stale
+      // count of 1 from a previous run would make cycle-1 here read 2 and falsely halt). The local
+      // count only reaches 2 when the SAME signature is appended in BOTH cycles of THIS run.
+      if (env.signature) {
+        thisRunSigCycles[env.signature] = (thisRunSigCycles[env.signature] || 0) + 1;
+      }
+    }
+  }
+}
+
+// M90 §3 (option b, fix-cycle: REACHABLE + RUN-SCOPED + AUTO-RESET) — after cycle 2, detect
+// non-convergence from THIS RUN's signatures, not the global HALT_THRESHOLD=3 (which the 2-cycle
+// debug loop can never reach) and not stale cross-run ledger state (which would brick verify).
+// A signature that appeared in BOTH cycles of this run (cycles>=2) IS the cycle-2-boundary halt.
+const nonConvergentSigs = Object.keys(thisRunSigCycles).filter((s) => thisRunSigCycles[s] >= 2);
+if (nonConvergentSigs.length > 0) {
+  log("M90 loop-ledger: non-convergence detected — same symptom-signature across both cycles of THIS run.");
+  log("PREMISE_RE_EXAMINATION: the fix strategy has not converged. Re-examine the premise, not patch further.");
+  // PERSIST the unresolved halt (detection != resolution — user decision, M90 verify fix-cycle 6).
+  // Debug DETECTING the loop is NOT the same as the premise being RE-EXAMINED. We MARK the
+  // signature as requiring re-examination (halted+pending) and LEAVE IT SET — so the verify
+  // R-FAIL-3 gate actually sees the unresolved loop and FAILS, blocking the build until a genuine
+  // re-examination runs `record-re-examination`. Auto-clearing here (the prior bug) made the gate
+  // vacuous: it could never fire. The brick-risk that motivated auto-clear is handled instead by
+  // run-LOCAL counting + the gitignored transient state file (a stale cross-run/cross-project halt
+  // can't reach an unrelated verify).
+  for (const sig of nonConvergentSigs) {
+    await runCli(
+      projectDir,
+      "loop-ledger",
+      ["mark-re-examination-required", "--signature", sig, ...(milestone ? ["--milestone", milestone] : []), "--projectDir", projectDir],
+      "gsd-t-loop-ledger.cjs",
+      "loop-ledger-mark-re-examination-required",
+      true,
+      "Cycle 2"
+    );
+  }
+  return {
+    status: "premise-re-examination",
+    reason: "M90 §3 R-LOOP-2: same computed symptom-signature across both debug cycles of this run. " +
+      "The fix strategy is non-converging. Per the Unproven-Assumption Doctrine (option b), " +
+      "this workflow exits with a PREMISE_RE_EXAMINATION directive instead of dispatching a 3rd patch. " +
+      "Action required: stop patching, research how others solved this class of problem, re-examine the premise.",
+    directive: "PREMISE_RE_EXAMINATION",
+    routeTo: "architectural-hook",
+    module: "bin/gsd-t-architectural-trigger.cjs",
+    contract: ".gsd-t/contracts/unproven-assumption-doctrine-contract.md §3.2",
+    cyclesUsed: 2,
+    finalResult: lastResult,
+    haltedSignatures: nonConvergentSigs,
+  };
 }
 
 return {