gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

package/dist/resources/extensions/gsd/unit-context-manifest.js

@@ -0,0 +1,334 @@
+// GSD-2 — UnitContextManifest (#4782 phase 1).
+//
+// Declarative description of what context each auto-mode unit type needs
+// in its system prompt. Establishes the contract that later phases will
+// use to drive a single composeSystemPromptForUnit() — replacing the
+// per-unit-type branching currently spread across `auto-prompts.ts`.
+//
+// **Phase 1 ships the type + the data + a CI coverage guard.** It adds
+// zero wiring — no caller reads a manifest yet. Every unit type gets a
+// manifest that describes today's behavior as faithfully as possible, so
+// when the composer lands in phase 2 the migration can proceed manifest-
+// by-manifest without behavior change.
+//
+// Phased rollout tracking:
+//   - Phase 1 (this PR): schema + manifests + coverage test.
+//   - Phase 2: add composeSystemPromptForUnit(); migrate one low-risk
+//     unit type (e.g. reassess-roadmap) as the pilot.
+//   - Phase 3: migrate remaining unit types, tighten manifests per
+//     empirical usage, introduce skipWhen predicates absorbing the
+//     reassess opt-in gate from #4778.
+//   - Phase 4: introduce pipeline variants as declared sequences,
+//     absorbing the scope-classifier gates from #4781.
+//
+// Naming:
+//   - Artifact keys are STABLE strings (not paths). Path resolution is
+//     the composer's job; manifests describe intent, not disk layout.
+//   - Char budgets are nominal — blown budgets log a telemetry event,
+//     they do not truncate or error (the composer decides fallback).
+// ─── Artifact registry ────────────────────────────────────────────────────
+/**
+ * Stable identifiers for every artifact class a unit might inline, excerpt,
+ * or reference on-demand. Adding a new artifact class requires (a) a key
+ * here, (b) path/body resolution in the composer, and (c) updates to any
+ * manifest that should surface it.
+ */
+export const ARTIFACT_KEYS = [
+    // Milestone-scoped
+    "roadmap",
+    "milestone-context",
+    "milestone-summary",
+    "milestone-validation",
+    "milestone-research",
+    "milestone-plan",
+    // Slice-scoped
+    "slice-context",
+    "slice-research",
+    "slice-plan",
+    "slice-summary",
+    "slice-uat",
+    "slice-assessment",
+    // Task-scoped
+    "task-plan",
+    "task-summary",
+    "prior-task-summaries",
+    "dependency-summaries",
+    // Project-scoped
+    "requirements",
+    "decisions",
+    "project",
+    "templates",
+];
+// ─── Manifests ────────────────────────────────────────────────────────────
+// Phase 1 policy: every manifest encodes today's behavior. Skills = "all"
+// unless the unit type was already narrowed via the existing skill-manifest
+// resolver (#4779). Memory/knowledge policies reflect the defaults in
+// `bootstrap/system-context.ts`. Artifact classifications follow what
+// `auto-prompts.ts` inlines today for each unit type.
+const COMMON_BUDGET_LARGE = 1_500_000; // ~400K tokens
+const COMMON_BUDGET_MEDIUM = 750_000; // ~200K tokens
+const COMMON_BUDGET_SMALL = 250_000; // ~65K tokens
+/**
+ * Canonical unit types handled by auto-mode dispatch. The coverage test
+ * enumerates these against `UNIT_MANIFESTS` to catch manifest drift when
+ * a new unit type lands.
+ */
+export const KNOWN_UNIT_TYPES = [
+    "research-milestone",
+    "plan-milestone",
+    "discuss-milestone",
+    "validate-milestone",
+    "complete-milestone",
+    "research-slice",
+    "plan-slice",
+    "refine-slice",
+    "replan-slice",
+    "complete-slice",
+    "reassess-roadmap",
+    "execute-task",
+    "reactive-execute",
+    "run-uat",
+    "gate-evaluate",
+    "rewrite-docs",
+];
+export const UNIT_MANIFESTS = {
+    // ─── Milestone-scoped ────────────────────────────────────────────────
+    "research-milestone": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            // Phase 3 migration (#4782): matches today's actual
+            // buildResearchMilestonePrompt inlining order.
+            inline: ["milestone-context", "project", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "plan-milestone": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["project", "requirements", "decisions", "milestone-research", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "discuss-milestone": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["project", "requirements", "decisions", "milestone-context", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "validate-milestone": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: false,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["roadmap", "slice-summary", "slice-uat", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "complete-milestone": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: false,
+        preferences: "active-only",
+        artifacts: {
+            // #4780 landed slice-summary as excerpt for this unit; phase 2 of
+            // the architecture will read this manifest as the source of truth
+            // and retire the special-case wiring in auto-prompts.ts.
+            inline: ["roadmap", "milestone-context", "requirements", "decisions", "project", "templates"],
+            excerpt: ["slice-summary"],
+            onDemand: ["slice-summary"],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    // ─── Slice-scoped ────────────────────────────────────────────────────
+    "research-slice": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["roadmap", "milestone-research", "dependency-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "plan-slice": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["roadmap", "slice-research", "dependency-summaries", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "refine-slice": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["slice-plan", "slice-research", "dependency-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "replan-slice": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["slice-plan", "slice-research", "dependency-summaries", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "complete-slice": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: false,
+        preferences: "active-only",
+        artifacts: {
+            // Phase 3 migration (#4782): matches today's actual
+            // buildCompleteSlicePrompt inlining order. Overrides prepend +
+            // knowledge splice stay in the builder imperatively (see RFC
+            // #4924 — computed/prepend blocks are phase-4 composer work).
+            inline: ["roadmap", "slice-context", "slice-plan", "requirements", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "reassess-roadmap": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "critical-only",
+        codebaseMap: false,
+        preferences: "none",
+        artifacts: {
+            // Phase 2 pilot (#4782): manifest now matches today's actual
+            // buildReassessRoadmapPrompt behavior for equivalence. Phase 3
+            // will tighten this list once the composer reports real telemetry.
+            inline: ["roadmap", "slice-context", "slice-summary", "project", "requirements", "decisions"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    // ─── Task-scoped ─────────────────────────────────────────────────────
+    "execute-task": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["task-plan", "slice-plan", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: ["slice-research"],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "reactive-execute": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["slice-plan", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: ["slice-research"],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    // ─── Ancillary units ─────────────────────────────────────────────────
+    "run-uat": {
+        skills: { mode: "all" },
+        knowledge: "critical-only",
+        memory: "critical-only",
+        codebaseMap: false,
+        preferences: "active-only",
+        artifacts: {
+            // Phase 3 migration (#4782): manifest matches today's actual
+            // buildRunUatPrompt inlining. Prior phase-1 entry listed
+            // `slice-plan` aspirationally — the real builder inlines the UAT
+            // file, the slice SUMMARY (optional), and the project row.
+            inline: ["slice-uat", "slice-summary", "project"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_SMALL,
+    },
+    "gate-evaluate": {
+        skills: { mode: "all" },
+        knowledge: "critical-only",
+        memory: "critical-only",
+        codebaseMap: false,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["slice-plan", "prior-task-summaries"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_SMALL,
+    },
+    "rewrite-docs": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        artifacts: {
+            inline: ["project", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+};
+// ─── Lookup helper ────────────────────────────────────────────────────────
+/**
+ * Return the manifest for a unit type, or null when the type is unknown.
+ *
+ * Callers MUST treat null as "fall through to today's default behavior"
+ * rather than erroring — unknown unit types may be experimental and
+ * should not crash the composer.
+ */
+export function resolveManifest(unitType) {
+    return UNIT_MANIFESTS[unitType] ?? null;
+}

package/dist/resources/extensions/gsd/uok/audit.js

@@ -1,6 +1,8 @@
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { isStaleWrite } from "../auto/turn-epoch.js";
+import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
 function auditLogPath(basePath) {
@@ -22,9 +24,23 @@ export function buildAuditEnvelope(args) {
     };
 }
 export function emitUokAuditEvent(basePath, event) {
+    // Drop writes from a turn superseded by timeout recovery / cancellation.
+    if (isStaleWrite("uok-audit"))
+        return;
     try {
         ensureAuditDir(basePath);
-        appendFileSync(auditLogPath(basePath), `${JSON.stringify(event)}\n`, "utf-8");
+        const path = auditLogPath(basePath);
+        // proper-lockfile requires the target file to exist before locking.
+        // Touch it via open(O_APPEND|O_CREAT) so the first writer wins the race
+        // atomically at the kernel level.
+        if (!existsSync(path))
+            closeSync(openSync(path, "a"));
+        // onLocked: "skip" — audit writes are best-effort; under heavy contention
+        // POSIX O_APPEND atomicity still protects small line writes, so skipping
+        // the lock rather than stalling orchestration is the correct tradeoff.
+        withFileLockSync(path, () => {
+            appendFileSync(path, `${JSON.stringify(event)}\n`, "utf-8");
+        }, { onLocked: "skip" });
     }
     catch {
         // Best-effort: audit writes must never break orchestration.

package/dist/resources/extensions/gsd/uok/dispatch-envelope.js

@@ -0,0 +1,33 @@
+export function buildDispatchEnvelope(input) {
+    return {
+        action: input.action,
+        nodeKind: input.node?.kind,
+        unitType: input.unitType,
+        unitId: input.unitId,
+        prompt: input.prompt,
+        reason: {
+            reasonCode: input.reasonCode,
+            summary: input.summary,
+            evidence: input.evidence,
+            blockedBy: input.blockedBy,
+        },
+        gateVerdict: input.gateVerdict,
+        constraints: input.node
+            ? {
+                reads: input.node.reads,
+                writes: input.node.writes,
+                dependsOn: input.node.dependsOn,
+            }
+            : undefined,
+        trace: input.trace,
+    };
+}
+export function explainDispatch(envelope) {
+    const subject = envelope.unitType && envelope.unitId
+        ? `${envelope.unitType} ${envelope.unitId}`
+        : envelope.nodeKind ?? envelope.action;
+    const blocked = envelope.reason.blockedBy && envelope.reason.blockedBy.length > 0
+        ? ` Blocked by: ${envelope.reason.blockedBy.map((b) => `${b.kind}:${b.id}`).join(", ")}.`
+        : "";
+    return `[${envelope.reason.reasonCode}] ${subject}: ${envelope.reason.summary}.${blocked}`;
+}

package/dist/resources/extensions/gsd/uok/execution-graph.js

@@ -68,6 +68,16 @@ export function buildSidecarQueueNodes(queue) {
         metadata: { index },
     }));
 }
+export function buildExecutionGraphSnapshot(nodes, phase) {
+    const sorted = topologicalSort(nodes);
+    return {
+        capturedAt: new Date().toISOString(),
+        phase,
+        nodes: sorted,
+        order: sorted.map((node) => node.id),
+        conflicts: detectFileConflicts(nodes),
+    };
+}
 export async function scheduleSidecarQueue(queue) {
     if (queue.length <= 1)
         return [...queue];

package/dist/resources/extensions/gsd/uok/gitops.js

@@ -32,7 +32,7 @@ export function writeTurnGitTransaction(args) {
         },
     }));
 }
-export function writeTurnCloseoutGitRecord(basePath, record) {
+export function writeTurnCloseoutGitRecord(basePath, record, metadata) {
     writeTurnGitTransaction({
         basePath,
         traceId: record.traceId,
@@ -45,6 +45,7 @@ export function writeTurnCloseoutGitRecord(basePath, record) {
         status: record.failureClass === "git" ? "failed" : "ok",
         error: record.failureClass === "git" ? "git closeout failure" : undefined,
         metadata: {
+            ...(metadata ?? {}),
             turnStatus: record.status,
             finishedAt: record.finishedAt,
             activityFile: record.activityFile,

package/dist/resources/extensions/gsd/uok/loop-adapter.js

@@ -1,12 +1,35 @@
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
+import { acquireWriterToken, nextWriteRecord, releaseWriterToken } from "./writer.js";
 export function createTurnObserver(options) {
     let current = null;
+    let writerToken = null;
     const phaseResults = [];
+    function nextSequenceMetadata(category, operation, metadata) {
+        if (!writerToken)
+            return metadata ?? {};
+        const record = nextWriteRecord({
+            basePath: options.basePath,
+            token: writerToken,
+            category,
+            operation,
+            metadata,
+        });
+        return {
+            ...(metadata ?? {}),
+            writeSequence: record.sequence.sequence,
+            writerTokenId: record.writerToken.tokenId,
+        };
+    }
     return {
         onTurnStart(contract) {
             current = contract;
             phaseResults.length = 0;
+            writerToken = acquireWriterToken({
+                basePath: options.basePath,
+                traceId: contract.traceId,
+                turnId: contract.turnId,
+            });
             if (options.enableGitops) {
                 writeTurnGitTransaction({
                     basePath: options.basePath,
@@ -18,10 +41,10 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: {
+                    metadata: nextSequenceMetadata("gitops", "insert", {
                         iteration: contract.iteration,
                         sidecarKind: contract.sidecarKind,
-                    },
+                    }),
                 });
             }
             if (options.enableAudit) {
@@ -30,12 +53,12 @@ export function createTurnObserver(options) {
                     turnId: contract.turnId,
                     category: "orchestration",
                     type: "turn-start",
-                    payload: {
+                    payload: nextSequenceMetadata("audit", "append", {
                         iteration: contract.iteration,
                         unitType: contract.unitType,
                         unitId: contract.unitId,
                         sidecarKind: contract.sidecarKind,
-                    },
+                    }),
                 }));
             }
         },
@@ -59,7 +82,7 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: { action },
+                    metadata: nextSequenceMetadata("gitops", "update", { action }),
                 });
             }
             if (phase === "unit") {
@@ -73,7 +96,7 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: { action },
+                    metadata: nextSequenceMetadata("gitops", "update", { action }),
                 });
             }
             if (phase === "finalize") {
@@ -87,7 +110,7 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: { action },
+                    metadata: nextSequenceMetadata("gitops", "update", { action }),
                 });
             }
         },
@@ -102,14 +125,14 @@ export function createTurnObserver(options) {
                     turnId: merged.turnId,
                     category: "orchestration",
                     type: "turn-result",
-                    payload: {
+                    payload: nextSequenceMetadata("audit", "append", {
                         unitType: merged.unitType,
                         unitId: merged.unitId,
                         status: merged.status,
                         failureClass: merged.failureClass,
                         error: merged.error,
                         phaseCount: merged.phaseResults.length,
-                    },
+                    }),
                 }));
             }
             if (options.enableGitops) {
@@ -124,8 +147,12 @@ export function createTurnObserver(options) {
                     gitPushed: options.gitPush,
                     finishedAt: merged.finishedAt,
                 };
-                writeTurnCloseoutGitRecord(options.basePath, closeout);
+                writeTurnCloseoutGitRecord(options.basePath, closeout, nextSequenceMetadata("gitops", "update", { action: "record" }));
+            }
+            if (writerToken) {
+                releaseWriterToken(options.basePath, writerToken);
             }
+            writerToken = null;
             current = null;
             phaseResults.length = 0;
         },

package/dist/resources/extensions/gsd/uok/parity-report.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "../paths.js";
+function parityLogPath(basePath) {
+    return join(gsdRoot(basePath), "runtime", "uok-parity.jsonl");
+}
+function reportPath(basePath) {
+    return join(gsdRoot(basePath), "runtime", "uok-parity-report.json");
+}
+function increment(bucket, key) {
+    const normalized = key && key.trim().length > 0 ? key : "unknown";
+    bucket[normalized] = (bucket[normalized] ?? 0) + 1;
+}
+export function parseParityEvents(raw) {
+    return raw
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return { status: "error", error: "invalid parity json line" };
+        }
+    });
+}
+export function buildParityReport(events, sourcePath) {
+    const paths = {};
+    const statuses = {};
+    const criticalMismatches = [];
+    let fallbackInvocations = 0;
+    for (const event of events) {
+        increment(paths, event.path);
+        increment(statuses, event.status);
+        if (event.path === "legacy-fallback")
+            fallbackInvocations += 1;
+        if (event.status === "error") {
+            criticalMismatches.push(event.error ?? "parity event reported error");
+        }
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        sourcePath,
+        totalEvents: events.length,
+        paths,
+        statuses,
+        criticalMismatches,
+        fallbackInvocations,
+    };
+}
+export function writeParityReport(basePath) {
+    const sourcePath = parityLogPath(basePath);
+    const raw = existsSync(sourcePath) ? readFileSync(sourcePath, "utf-8") : "";
+    const report = buildParityReport(parseParityEvents(raw), sourcePath);
+    mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true });
+    writeFileSync(reportPath(basePath), JSON.stringify(report, null, 2) + "\n", "utf-8");
+    return report;
+}