gsd-pi 2.81.0 → 2.82.0-dev.ed17d078d

package/dist/resources/extensions/gsd/state-reconciliation/drift/roadmap.js

@@ -0,0 +1,87 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 roadmap-divergence drift handler. Detects mismatches
+// between ROADMAP.md (parsed slice sequence + depends declarations) and the
+// DB slice rows for that milestone, then reconciles via the markdown
+// importer plus an explicit junction-table sync.
+import { existsSync, readFileSync } from "node:fs";
+import { getMilestone, getMilestoneSlices, isDbAvailable, syncSliceDependencies, } from "../../gsd-db.js";
+import { migrateHierarchyToDb } from "../../md-importer.js";
+import { findMilestoneIds } from "../../milestone-ids.js";
+import { parseRoadmap } from "../../parsers-legacy.js";
+import { resolveMilestoneFile } from "../../paths.js";
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function milestoneHasDivergence(basePath, milestoneId) {
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    if (!roadmapPath || !existsSync(roadmapPath))
+        return false;
+    let roadmap;
+    try {
+        roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
+    }
+    catch {
+        return false;
+    }
+    const dbSlices = getMilestoneSlices(milestoneId);
+    const dbSliceMap = new Map(dbSlices.map((s) => [s.id, s]));
+    for (let i = 0; i < roadmap.slices.length; i++) {
+        const roadmapSlice = roadmap.slices[i];
+        const expectedSequence = i + 1;
+        const dbSlice = dbSliceMap.get(roadmapSlice.id);
+        if (!dbSlice)
+            return true; // Roadmap has a slice the DB doesn't.
+        if (dbSlice.sequence !== expectedSequence)
+            return true;
+        if (!arraysEqual(dbSlice.depends, roadmapSlice.depends))
+            return true;
+    }
+    return false;
+}
+export function detectRoadmapDivergenceDrift(_state, ctx) {
+    if (!isDbAvailable())
+        return [];
+    const drifts = [];
+    for (const milestoneId of findMilestoneIds(ctx.basePath)) {
+        // Skip milestones that don't yet have a DB row — that's the
+        // unregistered-milestone drift handler's responsibility.
+        if (!getMilestone(milestoneId))
+            continue;
+        if (milestoneHasDivergence(ctx.basePath, milestoneId)) {
+            drifts.push({ kind: "roadmap-divergence", milestoneId });
+        }
+    }
+    return drifts;
+}
+/**
+ * Repair a milestone's roadmap divergence:
+ *   1. migrateHierarchyToDb upserts slice rows (sequence + depends JSON
+ *      update via ON CONFLICT DO UPDATE).
+ *   2. syncSliceDependencies updates the junction table per slice — the
+ *      importer only writes the JSON column, not the relational view.
+ */
+export function repairRoadmapDivergence(record, ctx) {
+    migrateHierarchyToDb(ctx.basePath);
+    const roadmapPath = resolveMilestoneFile(ctx.basePath, record.milestoneId, "ROADMAP");
+    if (!roadmapPath || !existsSync(roadmapPath))
+        return;
+    try {
+        const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
+        for (const slice of roadmap.slices) {
+            syncSliceDependencies(record.milestoneId, slice.id, slice.depends);
+        }
+    }
+    catch {
+        /* parse failure: detector will fire again next pass */
+    }
+}
+export const roadmapDivergenceHandler = {
+    kind: "roadmap-divergence",
+    detect: detectRoadmapDivergenceDrift,
+    repair: repairRoadmapDivergence,
+};

package/dist/resources/extensions/gsd/state-reconciliation/drift/sketch-flag.js

@@ -0,0 +1,50 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-sketch-flag drift handler. Relocated from
+// gsd-db.ts where autoHealSketchFlags previously lived with zero callers.
+//
+// Recovers from two scenarios (per ADR-011):
+//   1. Crash between gsd_plan_slice's PLAN.md write and the sketch flag flip.
+//   2. Flag-OFF downgrade: when progressive_planning is off, dispatch routes
+//      sketch slices to plan-slice, which writes PLAN.md but leaves
+//      is_sketch=1 — the next reconciliation pass clears it.
+import { existsSync } from "node:fs";
+import { getSketchedSliceIds, isDbAvailable, setSliceSketchFlag, } from "../../gsd-db.js";
+import { resolveSliceFile } from "../../paths.js";
+export function detectStaleSketchFlags(state, ctx) {
+    if (!isDbAvailable())
+        return [];
+    const mid = state.activeMilestone?.id;
+    if (!mid)
+        return [];
+    const sliceIds = getSketchedSliceIds(mid);
+    return sliceIds
+        .filter((sid) => {
+        const planPath = resolveSliceFile(ctx.basePath, mid, sid, "PLAN");
+        return planPath !== null && existsSync(planPath);
+    })
+        .map((sid) => ({ kind: "stale-sketch-flag", mid, sid }));
+}
+export function repairStaleSketchFlag(record) {
+    setSliceSketchFlag(record.mid, record.sid, false);
+}
+export const sketchFlagHandler = {
+    kind: "stale-sketch-flag",
+    detect: detectStaleSketchFlags,
+    repair: (record) => {
+        repairStaleSketchFlag(record);
+    },
+};
+/**
+ * Legacy entry point preserved for callers that supply a custom hasPlanFile
+ * predicate. Prefer the drift handler (sketchFlagHandler) for new code.
+ */
+export function autoHealSketchFlags(milestoneId, hasPlanFile) {
+    if (!isDbAvailable())
+        return;
+    const sliceIds = getSketchedSliceIds(milestoneId);
+    for (const sid of sliceIds) {
+        if (hasPlanFile(sid)) {
+            setSliceSketchFlag(milestoneId, sid, false);
+        }
+    }
+}

package/dist/resources/extensions/gsd/state-reconciliation/drift/stale-render.js

@@ -0,0 +1,124 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-render drift handler. Relocated from
+// markdown-renderer.ts as part of issue #5702. detectStaleRenders stays in
+// markdown-renderer.ts (it's a useful diagnostic primitive on its own); only
+// the detect+repair composition moves here. The previous repairStaleRenders
+// had zero callers in production code — wiring it through
+// reconcileBeforeDispatch closes that gap.
+import { detectStaleRenders, renderPlanCheckboxes, renderRoadmapCheckboxes, renderSliceSummary, renderTaskSummary, } from "../../markdown-renderer.js";
+import { logWarning } from "../../workflow-logger.js";
+// ─── Core (basePath-only — usable by both drift API and legacy wrapper) ──────
+function detectStaleRenderDriftFromBasePath(basePath) {
+    const entries = detectStaleRenders(basePath);
+    if (entries.length === 0)
+        return [];
+    // detectStaleRenders may emit multiple entries for the same path (one per
+    // mismatched checkbox). Dedupe by path; the repair re-renders the whole
+    // file in a single call. Prefer a reason the repair dispatcher can handle.
+    const seen = new Map();
+    for (const entry of entries) {
+        const currentReason = seen.get(entry.path);
+        if (currentReason === undefined ||
+            (!isRepairableStaleRenderReason(currentReason) && isRepairableStaleRenderReason(entry.reason))) {
+            seen.set(entry.path, entry.reason);
+        }
+    }
+    return Array.from(seen.entries()).map(([renderPath, reason]) => ({
+        kind: "stale-render",
+        renderPath,
+        reason,
+    }));
+}
+function isRepairableStaleRenderReason(reason) {
+    return (reason.includes("in roadmap") ||
+        reason.includes("in plan") ||
+        (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) ||
+        (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) ||
+        reason.includes("UAT.md missing"));
+}
+async function repairStaleRenderFromBasePath(record, basePath) {
+    const normPath = record.renderPath.replace(/\\/g, "/");
+    const reason = record.reason;
+    if (reason.includes("in roadmap")) {
+        const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
+        if (!milestoneMatch) {
+            throw new Error(`stale-render drift: roadmap path missing milestone segment: ${record.renderPath}`);
+        }
+        await renderRoadmapCheckboxes(basePath, milestoneMatch[1]);
+        return;
+    }
+    if (reason.includes("in plan")) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        if (!pathMatch) {
+            throw new Error(`stale-render drift: plan path missing milestone/slice segments: ${record.renderPath}`);
+        }
+        await renderPlanCheckboxes(basePath, pathMatch[1], pathMatch[2]);
+        return;
+    }
+    if (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//);
+        const taskMatch = reason.match(/^(T\d+)/);
+        if (!pathMatch || !taskMatch) {
+            throw new Error(`stale-render drift: task summary path/reason malformed: ${record.renderPath} reason=${reason}`);
+        }
+        await renderTaskSummary(basePath, pathMatch[1], pathMatch[2], taskMatch[1]);
+        return;
+    }
+    if (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        if (!pathMatch) {
+            throw new Error(`stale-render drift: slice summary path missing milestone/slice segments: ${record.renderPath}`);
+        }
+        await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
+        return;
+    }
+    if (reason.includes("UAT.md missing")) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        if (!pathMatch) {
+            throw new Error(`stale-render drift: UAT path missing milestone/slice segments: ${record.renderPath}`);
+        }
+        // renderSliceSummary handles both SUMMARY and UAT.
+        await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
+        return;
+    }
+    throw new Error(`stale-render drift: detector emitted unknown reason "${reason}" for ${record.renderPath}`);
+}
+// ─── Drift Handler API ───────────────────────────────────────────────────────
+export function detectStaleRenderDrift(_state, ctx) {
+    return detectStaleRenderDriftFromBasePath(ctx.basePath);
+}
+export async function repairStaleRender(record, ctx) {
+    await repairStaleRenderFromBasePath(record, ctx.basePath);
+}
+export const staleRenderHandler = {
+    kind: "stale-render",
+    detect: detectStaleRenderDrift,
+    repair: repairStaleRender,
+};
+// ─── Legacy entry point ──────────────────────────────────────────────────────
+/**
+ * Legacy bulk entry preserved for existing tests
+ * (tests/markdown-renderer.test.ts, tests/integration/integration-proof.test.ts).
+ * New code prefers the drift handler via `reconcileBeforeDispatch`. Matches the
+ * pre-ADR-017 behavior: silent per-entry error handling, returns the count of
+ * successful repairs.
+ */
+export async function repairStaleRenders(basePath) {
+    const drifts = detectStaleRenderDriftFromBasePath(basePath);
+    if (drifts.length === 0)
+        return 0;
+    let repaired = 0;
+    for (const drift of drifts) {
+        try {
+            await repairStaleRenderFromBasePath(drift, basePath);
+            repaired++;
+        }
+        catch (err) {
+            logWarning("renderer", `repair failed for ${drift.renderPath}: ${err.message}`);
+        }
+    }
+    if (repaired > 0) {
+        process.stderr.write(`markdown-renderer: repaired ${repaired} stale render(s)\n`);
+    }
+    return repaired;
+}

package/dist/resources/extensions/gsd/state-reconciliation/drift/stale-worker.js

@@ -0,0 +1,32 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-worker drift handler. Detects session-lock
+// artifacts whose owning PID is no longer alive (typical after SIGKILL or
+// laptop sleep where the heartbeat wasn't released cleanly), and clears them
+// before the next dispatch attempts to acquire the lock.
+import { effectiveLockFile, isSessionLockProcessAlive, readSessionLockData, removeStaleSessionLock, } from "../../session-lock.js";
+export function detectStaleWorkerDrift(_state, ctx) {
+    const data = readSessionLockData(ctx.basePath);
+    if (!data)
+        return [];
+    if (typeof data.pid !== "number")
+        return [];
+    if (isSessionLockProcessAlive(data))
+        return [];
+    return [
+        {
+            kind: "stale-worker",
+            lockPath: effectiveLockFile(),
+            pid: data.pid,
+        },
+    ];
+}
+export function repairStaleWorker(_record, ctx) {
+    // removeStaleSessionLock is idempotent: it re-reads lock state and is a
+    // no-op when the lock is held by an alive process. Safe under cap=2 retry.
+    removeStaleSessionLock(ctx.basePath);
+}
+export const staleWorkerHandler = {
+    kind: "stale-worker",
+    detect: detectStaleWorkerDrift,
+    repair: repairStaleWorker,
+};

package/dist/resources/extensions/gsd/state-reconciliation/errors.js

@@ -0,0 +1,41 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 typed reconciliation failure for Recovery Classification.
+/**
+ * Thrown by reconcileBeforeDispatch when:
+ *   - one or more repair functions throw within a pass (`failures` populated), or
+ *   - drift persists after the cap=2 lifecycle (`persistentDrift` populated).
+ *
+ * Recovery Classification recognizes this error via instanceof and maps it to
+ * failureKind "reconciliation-drift" with action "escalate".
+ */
+export class ReconciliationFailedError extends Error {
+    failures;
+    detectionFailures;
+    persistentDrift;
+    pass;
+    constructor(opts) {
+        super(formatMessage(opts));
+        this.name = "ReconciliationFailedError";
+        this.failures = opts.failures ?? [];
+        this.detectionFailures = opts.detectionFailures ?? [];
+        this.persistentDrift = opts.persistentDrift ?? [];
+        this.pass = opts.pass;
+    }
+}
+function formatMessage(opts) {
+    if (opts.detectionFailures && opts.detectionFailures.length > 0) {
+        const kinds = opts.detectionFailures.map((f) => f.handlerKind).join(", ");
+        const passSuffix = opts.pass !== undefined ? ` in pass ${opts.pass}` : "";
+        return `Reconciliation detect failed${passSuffix} for handlers: ${kinds}`;
+    }
+    if (opts.failures && opts.failures.length > 0) {
+        const kinds = opts.failures.map((f) => f.drift.kind).join(", ");
+        const passSuffix = opts.pass !== undefined ? ` in pass ${opts.pass}` : "";
+        return `Reconciliation repair failed${passSuffix} for drift kinds: ${kinds}`;
+    }
+    if (opts.persistentDrift && opts.persistentDrift.length > 0) {
+        const kinds = opts.persistentDrift.map((d) => d.kind).join(", ");
+        return `Reconciliation drift persisted after cap=2 passes: ${kinds}`;
+    }
+    return "Reconciliation failed";
+}

package/dist/resources/extensions/gsd/state-reconciliation/index.js

@@ -0,0 +1,99 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 drift-driven State Reconciliation Module entry point.
+// reconcileBeforeDispatch runs before every Dispatch decision and worker spawn.
+import { deriveState as defaultDeriveState, invalidateStateCache as defaultInvalidate, } from "../state.js";
+import { ReconciliationFailedError, } from "./errors.js";
+import { DRIFT_REGISTRY } from "./registry.js";
+export { ReconciliationFailedError } from "./errors.js";
+export { DRIFT_REGISTRY } from "./registry.js";
+const MAX_PASSES = 2;
+const defaultDeps = {
+    invalidateStateCache: defaultInvalidate,
+    deriveState: defaultDeriveState,
+};
+/**
+ * Drift-driven pre-dispatch reconciliation per ADR-017.
+ *
+ * Lifecycle: derive → detect drift → apply repairs → re-derive. Capped at
+ * MAX_PASSES (=2) cycles. The loop runs only when the prior pass fully
+ * succeeded but re-derive surfaces NEW drift (cascading repairs — e.g.
+ * fixing milestone registration uncovers a downstream completion-timestamp
+ * drift).
+ *
+ * Returns ok=true with `repaired` and terminal `blockers` populated.
+ * Throws ReconciliationFailedError when:
+ *   - any repair function throws within a pass, or
+ *   - drift persists after the cap.
+ */
+export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
+    const registry = deps.registry ?? DRIFT_REGISTRY;
+    const repaired = [];
+    for (let pass = 0; pass < MAX_PASSES; pass++) {
+        deps.invalidateStateCache();
+        const stateSnapshot = await deps.deriveState(basePath, deps.deriveStateOptions);
+        const ctx = { basePath, state: stateSnapshot };
+        const drift = await detectAllDrift(stateSnapshot, ctx, registry, pass);
+        if (drift.length === 0) {
+            return {
+                ok: true,
+                stateSnapshot,
+                repaired,
+                blockers: stateSnapshot.blockers ?? [],
+            };
+        }
+        const failures = [];
+        for (const record of drift) {
+            const handler = registry.find((h) => h.kind === record.kind);
+            if (!handler) {
+                failures.push({
+                    drift: record,
+                    cause: new Error(`No drift handler registered for kind "${record.kind}"`),
+                });
+                continue;
+            }
+            try {
+                await handler.repair(record, ctx);
+                repaired.push(record);
+            }
+            catch (cause) {
+                failures.push({ drift: record, cause });
+            }
+        }
+        if (failures.length > 0) {
+            throw new ReconciliationFailedError({ failures, pass });
+        }
+        // Pass fully succeeded; loop runs again to detect cascading drift.
+    }
+    // After MAX_PASSES, one more derive+detect to verify nothing persists.
+    deps.invalidateStateCache();
+    const finalState = await deps.deriveState(basePath, deps.deriveStateOptions);
+    const finalCtx = { basePath, state: finalState };
+    const persistent = await detectAllDrift(finalState, finalCtx, registry);
+    if (persistent.length > 0) {
+        throw new ReconciliationFailedError({ persistentDrift: persistent });
+    }
+    return {
+        ok: true,
+        stateSnapshot: finalState,
+        repaired,
+        blockers: finalState.blockers ?? [],
+    };
+}
+async function detectAllDrift(state, ctx, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+registry, pass) {
+    const collected = [];
+    for (const handler of registry) {
+        try {
+            const detected = await handler.detect(state, ctx);
+            collected.push(...detected);
+        }
+        catch (cause) {
+            throw new ReconciliationFailedError({
+                failures: [{ drift: { kind: handler.kind }, cause }],
+                pass,
+            });
+        }
+    }
+    return collected;
+}

package/dist/resources/extensions/gsd/state-reconciliation/registry.js

@@ -0,0 +1,24 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 drift handler registry. Single source of truth for
+// the catalog. Tests can override per-call via ReconciliationDeps.registry.
+import { completionTimestampHandler } from "./drift/completion.js";
+import { mergeStateHandler } from "./drift/merge-state.js";
+import { unregisteredMilestoneHandler } from "./drift/project-md.js";
+import { roadmapDivergenceHandler } from "./drift/roadmap.js";
+import { sketchFlagHandler } from "./drift/sketch-flag.js";
+import { staleRenderHandler } from "./drift/stale-render.js";
+import { staleWorkerHandler } from "./drift/stale-worker.js";
+// Each handler is parameterized over its specific DriftRecord variant for
+// internal type safety. The registry stores them under DriftHandler<any> so
+// handlers with disjoint repair parameter types coexist; the lifecycle matches
+// by kind before invoking repair, so this is sound at runtime.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const DRIFT_REGISTRY = [
+    sketchFlagHandler,
+    mergeStateHandler,
+    staleRenderHandler,
+    staleWorkerHandler,
+    unregisteredMilestoneHandler,
+    roadmapDivergenceHandler,
+    completionTimestampHandler,
+];

package/dist/resources/extensions/gsd/state-reconciliation/spawn-gate.js

@@ -0,0 +1,43 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 #5707 caller-closure helper. Parent processes that
+// spawn auto-loop workers must reconcile before spawn — otherwise each
+// worker independently detects+repairs the same drift, racing on shared
+// state. This helper centralises the reconcile+catch flow so the two
+// production spawn sites (commands/handlers/parallel.ts and auto/phases.ts
+// startSliceParallel) share one contract.
+import { reconcileBeforeDispatch, ReconciliationFailedError, } from "./index.js";
+/**
+ * Run reconciliation before spawning workers. Returns ok=true when the run
+ * completed without throwing (blockers ride along but don't fail the gate —
+ * spawn callers can choose how to handle them). On
+ * ReconciliationFailedError, returns ok=false with the error message so the
+ * caller can surface it to the user without re-throwing.
+ *
+ * Other unexpected errors propagate; they are not part of the drift
+ * taxonomy.
+ */
+export async function reconcileBeforeSpawn(basePath, deps = {}) {
+    const reconcileFn = deps.reconcile ?? reconcileBeforeDispatch;
+    try {
+        const result = await reconcileFn(basePath, deps);
+        if (result.blockers.length > 0) {
+            return {
+                ok: false,
+                reason: `Reconciliation blocker: ${result.blockers[0]}`,
+            };
+        }
+        const repairedKinds = result.repaired.map((d) => d.kind);
+        return {
+            ok: true,
+            reason: repairedKinds.length > 0
+                ? `repaired before spawn: ${repairedKinds.join(", ")}`
+                : undefined,
+        };
+    }
+    catch (err) {
+        if (err instanceof ReconciliationFailedError) {
+            return { ok: false, reason: err.message };
+        }
+        throw err;
+    }
+}

package/dist/resources/extensions/gsd/state-reconciliation/types.js

@@ -0,0 +1,3 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 types for drift-driven state reconciliation.
+export {};

package/dist/resources/extensions/gsd/state-reconciliation.js

@@ -1,27 +1,6 @@
 // Project/App: GSD-2
-// File Purpose: ADR-015 State Reconciliation module for pre-dispatch runtime invariants.
-import { deriveState, invalidateStateCache } from "./state.js";
-const defaultDeps = {
-    invalidateStateCache,
-    deriveState,
-};
-export async function reconcileBeforeDispatch(basePath, deps = defaultDeps, opts) {
-    deps.invalidateStateCache();
-    const stateSnapshot = await deps.deriveState(basePath, opts);
-    const blockers = stateSnapshot.blockers ?? [];
-    if (blockers.length > 0 || stateSnapshot.phase === "blocked") {
-        return {
-            ok: false,
-            reason: blockers[0] ?? `State reconciliation blocked in phase ${stateSnapshot.phase}`,
-            stateSnapshot,
-            repaired: ["derive-state-cache-invalidated"],
-            blockers,
-        };
-    }
-    return {
-        ok: true,
-        stateSnapshot,
-        repaired: ["derive-state-cache-invalidated"],
-        blockers,
-    };
-}
+// File Purpose: ADR-017 State Reconciliation Module — public entry point.
+// Re-exports the drift-driven implementation from the state-reconciliation/
+// folder so existing import paths (./state-reconciliation.js) keep working.
+export { reconcileBeforeDispatch, ReconciliationFailedError, DRIFT_REGISTRY, } from "./state-reconciliation/index.js";
+export { reconcileBeforeSpawn } from "./state-reconciliation/spawn-gate.js";

package/dist/resources/extensions/gsd/templates/knowledge.md

@@ -1,7 +1,7 @@
 # Project Knowledge
 
-Append-only register of project-specific rules, patterns, and lessons learned.
-Agents read this before every unit. Add entries when you discover something worth remembering.
+Project-specific rules plus projected patterns and lessons learned.
+Rules are maintained in this file. Patterns and lessons are persisted to the memories table and rendered here on the next session-start projection.
 
 ## Rules
 

package/dist/resources/extensions/gsd/tui/render-kit.js

@@ -0,0 +1,74 @@
+// Project/App: GSD-2
+// File Purpose: Shared terminal rendering helpers for GSD extension TUI surfaces.
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@gsd/pi-tui";
+export function safeLine(text, width, ellipsis = "…") {
+    if (width <= 0)
+        return "";
+    return truncateToWidth(text, width, ellipsis);
+}
+export function padRightVisible(text, width) {
+    if (width <= 0)
+        return "";
+    const truncated = safeLine(text, width);
+    const pad = Math.max(0, width - visibleWidth(truncated));
+    return truncated + " ".repeat(pad);
+}
+export function rightAlign(left, right, width) {
+    if (width <= 0)
+        return "";
+    if (!right)
+        return safeLine(left, width);
+    if (!left)
+        return safeLine(" ".repeat(Math.max(0, width - visibleWidth(right))) + right, width);
+    const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(right));
+    return safeLine(left + " ".repeat(gap) + right, width);
+}
+export function wrapVisibleText(text, width) {
+    if (width <= 0)
+        return [text];
+    return wrapTextWithAnsi(text, width).map((line) => visibleWidth(line) > width ? truncateToWidth(line, width, "…") : line);
+}
+export function renderBar(theme, width, color = "muted") {
+    return safeLine(theme.fg(color, "─".repeat(Math.max(0, width))), width, "");
+}
+export function renderKeyHints(theme, hints, width) {
+    return safeLine(theme.fg("dim", hints.filter(Boolean).join("  │  ")), width);
+}
+export function renderProgressBar(theme, done, total, width, options = {}) {
+    const barWidth = Math.max(0, width);
+    const pct = total > 0 ? Math.max(0, Math.min(1, done / total)) : 0;
+    const filled = Math.round(pct * barWidth);
+    const filledChar = options.filledChar ?? "█";
+    const emptyChar = options.emptyChar ?? "░";
+    return (theme.fg(options.filledColor ?? "success", filledChar.repeat(filled)) +
+        theme.fg(options.emptyColor ?? "dim", emptyChar.repeat(barWidth - filled)));
+}
+export function statusGlyph(theme, level) {
+    switch (level) {
+        case "active": return theme.fg("success", "●");
+        case "success": return theme.fg("success", "✓");
+        case "warning": return theme.fg("warning", "!");
+        case "error": return theme.fg("error", "x");
+        case "idle":
+        default: return theme.fg("dim", "○");
+    }
+}
+export function renderFrame(theme, inner, width, options = {}) {
+    if (width < 4)
+        return inner.map((line) => safeLine(line, width));
+    const borderColor = options.borderColor ?? "borderAccent";
+    const paddingX = Math.max(0, options.paddingX ?? 1);
+    const contentWidth = Math.max(0, width - 2 - paddingX * 2);
+    const border = (text) => theme.fg(borderColor, text);
+    const pad = " ".repeat(paddingX);
+    const lines = [border("╭" + "─".repeat(width - 2) + "╮")];
+    for (const line of inner) {
+        lines.push(border("│") +
+            pad +
+            padRightVisible(line, contentWidth) +
+            pad +
+            border("│"));
+    }
+    lines.push(border("╰" + "─".repeat(width - 2) + "╯"));
+    return lines.map((line) => safeLine(line, width, ""));
+}