gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.710c06e97

package/src/resources/extensions/github-sync/templates.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Markdown formatters for GitHub sync issues, PR bodies, and comments.
+
 /**
  * Markdown formatters for GitHub issue bodies, PR descriptions,
  * and summary comments.
@@ -6,6 +9,38 @@
  * for the `gh` CLI body parameters.
  */
 
+import { buildPrEvidence } from "../gsd/pr-evidence.js";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Wrap a string in a CommonMark inline-code span, escaping any embedded
+ * backticks by selecting a fence longer than the longest backtick run inside
+ * the input. If the input begins or ends with a backtick, pad with a single
+ * space inside the fence (CommonMark requirement).
+ *
+ * Empty input returns an empty string (no fence) — there is nothing to render
+ * as code, and emitting an empty pair of backticks would produce literal
+ * backticks in GitHub-flavored markdown.
+ */
+export function inlineCode(s: string): string {
+  if (s.length === 0) return "";
+  let longestRun = 0;
+  let currentRun = 0;
+  for (const ch of s) {
+    if (ch === "`") {
+      currentRun++;
+      if (currentRun > longestRun) longestRun = currentRun;
+    } else {
+      currentRun = 0;
+    }
+  }
+  const fence = "`".repeat(longestRun + 1);
+  const needsPad = s.startsWith("`") || s.endsWith("`");
+  const pad = needsPad ? " " : "";
+  return `${fence}${pad}${s}${pad}${fence}`;
+}
+
 // ─── Milestone Issue Body ───────────────────────────────────────────────────
 
 export interface MilestoneData {
@@ -65,44 +100,34 @@ export interface SliceData {
 }
 
 export function formatSlicePRBody(data: SliceData): string {
-  const lines: string[] = [];
-
-  lines.push(`## ${data.id}: ${data.title}`);
-  lines.push("");
-
-  if (data.goal) {
-    lines.push("### Goal");
-    lines.push(data.goal);
-    lines.push("");
-  }
-
-  if (data.mustHaves?.length) {
-    lines.push("### Must-Haves");
-    for (const item of data.mustHaves) {
-      lines.push(`- ${item}`);
-    }
-    lines.push("");
-  }
-
-  if (data.demoCriterion) {
-    lines.push("### Demo Criterion");
-    lines.push(data.demoCriterion);
-    lines.push("");
-  }
-
-  if (data.tasks?.length) {
-    lines.push("### Tasks");
-    for (const task of data.tasks) {
-      const ref = task.issueNumber ? ` (#${task.issueNumber})` : "";
-      lines.push(`- [ ] ${task.id}: ${task.title}${ref}`);
-    }
-    lines.push("");
-  }
-
-  lines.push("---");
-  lines.push("*Auto-generated by GSD GitHub Sync*");
-
-  return lines.join("\n");
+  const summaries = [
+    data.goal ? `### Goal\n${data.goal}` : "",
+    data.mustHaves?.length ? `### Must-Haves\n${data.mustHaves.map((item) => `- ${item}`).join("\n")}` : "",
+    data.demoCriterion ? `### Demo Criterion\n${data.demoCriterion}` : "",
+    data.tasks?.length
+      ? `### Tasks\n${data.tasks.map((task) => {
+        const ref = task.issueNumber ? ` (#${task.issueNumber})` : "";
+        return `- [ ] ${task.id}: ${task.title}${ref}`;
+      }).join("\n")}`
+      : "",
+  ].filter(Boolean);
+  const issueRefs = (data.tasks ?? [])
+    .map((task) => task.issueNumber)
+    .filter((issueNumber): issueNumber is number => typeof issueNumber === "number")
+    .map((issueNumber) => `#${issueNumber}`);
+
+  return buildPrEvidence({
+    milestoneId: data.id,
+    subjectId: data.id,
+    subjectKind: "slice",
+    milestoneTitle: data.title,
+    changeType: "feat",
+    linkedIssue: issueRefs.length > 0 ? `Related issues: ${issueRefs.join(", ")}` : undefined,
+    summaries,
+    testsRun: data.demoCriterion ? [`Demo criterion: ${data.demoCriterion}`] : undefined,
+    rollbackNotes: ["Close this draft slice PR before merge or revert the slice squash commit from the milestone branch."],
+    how: "Generated by GSD GitHub Sync from the slice plan, task issues, and branch mapping.",
+  }).body;
 }
 
 // ─── Task Issue Body ────────────────────────────────────────────────────────
@@ -129,7 +154,7 @@ export function formatTaskIssueBody(data: TaskData): string {
   if (data.files?.length) {
     lines.push("### Files");
     for (const file of data.files) {
-      lines.push(`- \`${file}\``);
+      lines.push(`- ${inlineCode(file)}`);
     }
     lines.push("");
   }
@@ -228,53 +253,33 @@ function checkedList(items: string[] | undefined, emptyLabel: string): string[]
 }
 
 export function formatSwarmLanePRBody(data: SwarmLanePRData): string {
-  const lines: string[] = [];
   const laneLabel = SWARM_LANE_LABELS[data.lane.id];
-
-  lines.push("## Swarm lane");
-  lines.push("");
-  lines.push(`**Lane:** \`${laneLabel}\``);
-  lines.push(`**Branch:** \`${data.lane.branch}\``);
-  if (data.lane.owner) lines.push(`**Owner:** ${data.lane.owner}`);
-  if (data.lane.latestCommit) lines.push(`**Latest commit:** \`${data.lane.latestCommit}\``);
-  lines.push("");
-
-  lines.push("## Impact area");
-  lines.push("");
-  lines.push(data.impactArea);
-  lines.push("");
-
-  lines.push("## Changed contracts");
-  lines.push(...checkedList(data.lane.changedContracts, "No shared contracts changed"));
-  lines.push("");
-
-  lines.push("## Transition risks");
-  lines.push(...checkedList(data.transitionRisks, "No transition risks identified"));
-  lines.push("");
-
-  lines.push("## Rollback plan");
-  lines.push(...checkedList(data.rollbackPlan, "Revert this lane PR"));
-  lines.push("");
-
-  lines.push("## Test evidence");
-  lines.push(...checkedList(data.lane.testEvidence, "Test evidence pending"));
-  lines.push("");
-
-  if (data.lane.blockers?.length) {
-    lines.push("## Blockers");
-    for (const blocker of data.lane.blockers) lines.push(`- ${blocker}`);
-    lines.push("");
-  }
-
-  if (data.linkedIssue) {
-    lines.push(`Closes #${data.linkedIssue}`);
-    lines.push("");
-  }
-
-  lines.push("---");
-  lines.push("*Auto-generated by GSD GitHub Sync swarm routines*");
-
-  return lines.join("\n");
+  const summaries = [
+    [
+      "### Swarm lane",
+      `**Lane:** ${inlineCode(laneLabel)}`,
+      `**Branch:** ${inlineCode(data.lane.branch)}`,
+      data.lane.owner ? `**Owner:** ${data.lane.owner}` : "",
+      data.lane.latestCommit ? `**Latest commit:** ${inlineCode(data.lane.latestCommit)}` : "",
+    ].filter(Boolean).join("\n"),
+    `### Impact area\n${data.impactArea}`,
+    `### Changed contracts\n${checkedList(data.lane.changedContracts, "No shared contracts changed").join("\n")}`,
+    `### Transition risks\n${checkedList(data.transitionRisks, "No transition risks identified").join("\n")}`,
+  ].filter(Boolean);
+
+  return buildPrEvidence({
+    milestoneId: laneLabel,
+    subjectId: laneLabel,
+    subjectKind: "workflow",
+    milestoneTitle: laneLabel,
+    changeType: "refactor",
+    linkedIssue: data.linkedIssue ? `Closes #${data.linkedIssue}` : undefined,
+    summaries,
+    blockers: data.lane.blockers ?? [],
+    testsRun: data.lane.testEvidence,
+    rollbackNotes: data.rollbackPlan,
+    how: "Generated by GSD GitHub Sync swarm routines from lane evidence.",
+  }).body;
 }
 
 export function formatSwarmReleaseChecklistBody(data: SwarmReleaseChecklistData): string {
@@ -282,7 +287,7 @@ export function formatSwarmReleaseChecklistBody(data: SwarmReleaseChecklistData)
 
   lines.push(`# UOK Swarm Release Checklist`);
   lines.push("");
-  lines.push(`**Integration branch:** \`${data.integrationBranch}\``);
+  lines.push(`**Integration branch:** ${inlineCode(data.integrationBranch)}`);
   lines.push("");
 
   lines.push("## Lane summary");
@@ -291,9 +296,9 @@ export function formatSwarmReleaseChecklistBody(data: SwarmReleaseChecklistData)
   lines.push("|------|--------|-------|--------|--------|");
   for (const lane of data.lanes) {
     const owner = lane.owner ?? "";
-    const commit = lane.latestCommit ? `\`${lane.latestCommit}\`` : "";
+    const commit = lane.latestCommit ? inlineCode(lane.latestCommit) : "";
     const status = lane.blockers?.length ? "blocked" : "ready";
-    lines.push(`| \`${SWARM_LANE_LABELS[lane.id]}\` | \`${lane.branch}\` | ${owner} | ${commit} | ${status} |`);
+    lines.push(`| ${inlineCode(SWARM_LANE_LABELS[lane.id])} | ${inlineCode(lane.branch)} | ${owner} | ${commit} | ${status} |`);
   }
   lines.push("");
 

package/src/resources/extensions/github-sync/tests/inline-code.test.ts

@@ -0,0 +1,66 @@
+// Project/App: GSD-2
+// File Purpose: Tests for the inlineCode markdown helper and its use in PR body templates.
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { inlineCode, formatSwarmLanePRBody } from "../templates.ts";
+
+describe("inlineCode", () => {
+  it("wraps a plain string in single backticks", () => {
+    assert.equal(inlineCode("hello"), "`hello`");
+  });
+
+  it("uses a double-backtick fence when the input contains a single backtick", () => {
+    const out = inlineCode("a`b");
+    assert.equal(out, "``a`b``");
+  });
+
+  it("uses a 4-backtick fence when the input contains a run of three backticks", () => {
+    const out = inlineCode("x```y");
+    assert.equal(out, "````x```y````");
+  });
+
+  it("pads with a leading space when the input starts with a backtick", () => {
+    const out = inlineCode("`leading");
+    // longest run = 1 → fence length 2; leading backtick → pad both sides
+    assert.equal(out, "`` `leading ``");
+  });
+
+  it("pads with a trailing space when the input ends with a backtick", () => {
+    const out = inlineCode("trailing`");
+    assert.equal(out, "`` trailing` ``");
+  });
+
+  it("returns an empty string for empty input", () => {
+    // Documented invariant: empty input renders as nothing rather than as
+    // a literal pair of backticks (which GFM would render as the characters
+    // themselves, not as code).
+    assert.equal(inlineCode(""), "");
+  });
+
+  it("escapes a branch with embedded backticks inside formatSwarmLanePRBody", () => {
+    const malicious = "feature`evil";
+    const body = formatSwarmLanePRBody({
+      lane: {
+        id: "workflow",
+        branch: malicious,
+      },
+      impactArea: "test",
+      transitionRisks: [],
+      rollbackPlan: [],
+    });
+    // The branch must appear inside a properly fenced inline-code span,
+    // i.e. wrapped in the helper's chosen fence (here a double backtick).
+    assert.ok(
+      body.includes("``feature`evil``"),
+      `expected double-backtick fenced branch, got body:\n${body}`,
+    );
+    // And there must be no markdown break-out: the substring "evil" should
+    // never appear unfenced as a bare word adjacent to a closing single
+    // backtick (the unpatched template produced "`feature`evil`").
+    assert.ok(
+      !body.includes("`feature`evil`\n") && !body.includes("`feature`evil` "),
+      `expected no inline-code break-out, got body:\n${body}`,
+    );
+  });
+});

package/src/resources/extensions/github-sync/tests/templates.test.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Tests for GitHub sync markdown formatters.
+
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import {
@@ -57,6 +60,9 @@ describe("templates", () => {
       assert.ok(body.includes("Define all auth types"));
       assert.ok(body.includes("- User type"));
       assert.ok(body.includes("- Session type"));
+      assert.ok(body.includes("## Linked Issue"));
+      assert.ok(body.includes("## Tests Run"));
+      assert.ok(body.includes("## AI Assistance Disclosure"));
     });
 
     it("renders task checklist with issue links", () => {
@@ -71,6 +77,7 @@ describe("templates", () => {
       assert.ok(body.includes("- [ ] T01: Types (#43)"));
       assert.ok(body.includes("- [ ] T02: Schema"));
       assert.ok(!body.includes("T02: Schema (#"));
+      assert.ok(body.includes("Related issues: #43"));
     });
   });
 
@@ -163,9 +170,10 @@ describe("templates", () => {
       assert.ok(body.includes("`lane/writer`"));
       assert.ok(body.includes("Single-writer UOK metadata."));
       assert.ok(body.includes("- [ ] Writer token lifecycle regression"));
-      assert.ok(body.includes("- [ ] Disable writer sequence enrichment"));
-      assert.ok(body.includes("- [ ] npm run typecheck:extensions"));
+      assert.ok(body.includes("- Disable writer sequence enrichment"));
+      assert.ok(body.includes("- npm run typecheck:extensions"));
       assert.ok(body.includes("Closes #123"));
+      assert.ok(body.includes("## AI Assistance Disclosure"));
     });
 
     it("formats release checklist bodies from lane state", () => {

package/src/resources/extensions/gsd/auto/contracts.ts

@@ -0,0 +1,87 @@
+import type { GSDState } from "../types.js";
+
+export interface AutoSessionContext {
+  basePath: string;
+  trigger: "guided-flow" | "resume" | "auto-loop" | "manual";
+}
+
+export interface AutoStatus {
+  phase: "idle" | "running" | "paused" | "stopped" | "error";
+  activeUnit?: {
+    unitType: string;
+    unitId: string;
+  };
+  lastTransitionAt?: number;
+  transitionCount: number;
+}
+
+export interface AutoAdvanceResult {
+  kind: "advanced" | "blocked" | "paused" | "stopped" | "error";
+  reason?: string;
+  stateSnapshot?: GSDState;
+}
+
+export interface AutoOrchestrationModule {
+  start(sessionContext: AutoSessionContext): Promise<AutoAdvanceResult>;
+  advance(): Promise<AutoAdvanceResult>;
+  resume(): Promise<AutoAdvanceResult>;
+  stop(reason: string): Promise<AutoAdvanceResult>;
+  getStatus(): AutoStatus;
+}
+
+export interface DispatchAdapter {
+  decideNextUnit(): Promise<{
+    unitType: string;
+    unitId: string;
+    reason: string;
+    preconditions: string[];
+  } | null>;
+}
+
+export interface RecoveryAdapter {
+  classifyAndRecover(input: {
+    error: unknown;
+    unitType?: string;
+    unitId?: string;
+  }): Promise<{
+    action: "retry" | "escalate" | "stop";
+    reason: string;
+  }>;
+}
+
+export interface WorktreeAdapter {
+  prepareForUnit(unitType: string, unitId: string): Promise<void>;
+  syncAfterUnit(unitType: string, unitId: string): Promise<void>;
+  cleanupOnStop(reason: string): Promise<void>;
+}
+
+export interface HealthAdapter {
+  preAdvanceGate(): Promise<{ allow: boolean; reason?: string }>;
+  postAdvanceRecord(result: AutoAdvanceResult): Promise<void>;
+}
+
+export interface RuntimePersistenceAdapter {
+  ensureLockOwnership(): Promise<void>;
+  journalTransition(event: {
+    name: string;
+    reason?: string;
+    unitType?: string;
+    unitId?: string;
+  }): Promise<void>;
+}
+
+export interface NotificationAdapter {
+  notifyLifecycle(event: {
+    name: string;
+    detail?: string;
+  }): Promise<void>;
+}
+
+export interface AutoOrchestratorDeps {
+  dispatch: DispatchAdapter;
+  recovery: RecoveryAdapter;
+  worktree: WorktreeAdapter;
+  health: HealthAdapter;
+  runtime: RuntimePersistenceAdapter;
+  notifications: NotificationAdapter;
+}

package/src/resources/extensions/gsd/auto/custom-verify-retry-store.ts

@@ -0,0 +1,72 @@
+// Project/App: GSD-2
+// File Purpose: Persistence adapter for custom workflow verification retry counts.
+
+import { readFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "../atomic-write.js";
+import { gsdRoot } from "../paths.js";
+import type { AutoSession } from "./session.js";
+
+type RetrySession = Pick<AutoSession, "activeRunDir" | "basePath" | "verificationRetryCount">;
+
+interface RetryStoreLogDeps {
+  logFailure: (err: unknown) => void;
+}
+
+export function customVerifyRetryStateDir(s: Pick<AutoSession, "activeRunDir" | "basePath">): string {
+  return s.activeRunDir ? join(s.activeRunDir, "runtime") : join(gsdRoot(s.basePath), "runtime");
+}
+
+export function customVerifyRetryStatePath(s: Pick<AutoSession, "activeRunDir" | "basePath">): string {
+  return join(customVerifyRetryStateDir(s), "custom-verify-retries.json");
+}
+
+export function hydrateCustomVerifyRetryCounts(
+  s: RetrySession,
+  deps: RetryStoreLogDeps,
+): Map<string, number> {
+  if (s.verificationRetryCount.size > 0) {
+    return s.verificationRetryCount;
+  }
+
+  try {
+    const raw = JSON.parse(readFileSync(customVerifyRetryStatePath(s), "utf-8"));
+    const counts = raw && typeof raw === "object" && raw.counts && typeof raw.counts === "object"
+      ? raw.counts as Record<string, unknown>
+      : {};
+    for (const [key, value] of Object.entries(counts)) {
+      if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+        s.verificationRetryCount.set(key, Math.floor(value));
+      }
+    }
+  } catch (err) {
+    deps.logFailure(err);
+  }
+
+  return s.verificationRetryCount;
+}
+
+export function saveCustomVerifyRetryCounts(
+  s: RetrySession,
+  deps: RetryStoreLogDeps,
+): void {
+  const retryCounts = s.verificationRetryCount;
+  const filePath = customVerifyRetryStatePath(s);
+
+  try {
+    if (!retryCounts || retryCounts.size === 0) {
+      unlinkSync(filePath);
+      return;
+    }
+    mkdirSync(customVerifyRetryStateDir(s), { recursive: true });
+    atomicWriteSync(filePath, JSON.stringify({
+      counts: Object.fromEntries(retryCounts),
+      updatedAt: new Date().toISOString(),
+    }) + "\n");
+  } catch (err) {
+    const code = err && typeof err === "object" && "code" in err ? (err as { code?: string }).code : undefined;
+    if (code !== "ENOENT") {
+      deps.logFailure(err);
+    }
+  }
+}

package/src/resources/extensions/gsd/auto/loop-deps.ts

@@ -7,6 +7,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import type { AutoSession } from "./session.js";
+import type { ErrorContext } from "./types.js";
 import type { GSDPreferences } from "../preferences.js";
 import type { GSDState } from "../types.js";
 import type { SessionLockStatus } from "../session-lock.js";
@@ -24,6 +25,12 @@ import type { MergeReconcileResult } from "../auto-recovery.js";
 import type { UokTurnObserver } from "../uok/contracts.js";
 import type { PreflightResult } from "../clean-root-preflight.js";
 
+type PauseAutoFn = (
+  ctx?: ExtensionContext,
+  pi?: ExtensionAPI,
+  errorContext?: ErrorContext,
+) => Promise<void>;
+
 /**
  * Dependencies injected by the caller (auto.ts startAuto) so autoLoop
  * can access private functions from auto.ts without exporting them.
@@ -39,7 +46,7 @@ export interface LoopDeps {
     pi?: ExtensionAPI,
     reason?: string,
   ) => Promise<void>;
-  pauseAuto: (ctx?: ExtensionContext, pi?: ExtensionAPI) => Promise<void>;
+  pauseAuto: PauseAutoFn;
   clearUnitTimeout: () => void;
   updateProgressWidget: (
     ctx: ExtensionContext,
@@ -245,7 +252,7 @@ export interface LoopDeps {
     prefs: GSDPreferences | undefined;
     buildSnapshotOpts: () => CloseoutOptions & Record<string, unknown>;
     buildRecoveryContext: () => unknown;
-    pauseAuto: (ctx?: ExtensionContext, pi?: ExtensionAPI) => Promise<void>;
+    pauseAuto: PauseAutoFn;
   }) => void;
 
   // Prompt helpers
@@ -271,7 +278,7 @@ export interface LoopDeps {
   ) => Promise<"dispatched" | "continue" | "retry">;
   runPostUnitVerification: (
     vctx: VerificationContext,
-    pauseAuto: (ctx?: ExtensionContext, pi?: ExtensionAPI) => Promise<void>,
+    pauseAuto: PauseAutoFn,
   ) => Promise<VerificationResult>;
   postUnitPostVerification: (
     pctx: PostUnitContext,