gsd-pi 2.77.0-dev.eaa4973bc → 2.78.0-dev.aeeb2ca00

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

@@ -0,0 +1,370 @@
+// 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
+// ─── Tool policy constants (#4934) ────────────────────────────────────────
+// Reused across manifests so per-unit assignment stays declarative and the
+// allowed-path set for the docs policy lives in one reviewable place.
+const TOOLS_ALL = { mode: "all" };
+const TOOLS_PLANNING = { mode: "planning" };
+const TOOLS_DOCS = {
+    mode: "docs",
+    // Globs are resolved relative to project basePath. The set is intentionally
+    // narrow: top-level docs/, README, CHANGELOG, and any markdown at the
+    // project root. Projects with non-standard layouts (e.g. mintlify-docs/)
+    // will need this list extended in a follow-up; landed conservative now,
+    // expand on demand.
+    allowedPathGlobs: [
+        "docs/**",
+        "README.md",
+        "README.*.md",
+        "CHANGELOG.md",
+        "*.md",
+    ],
+};
+/**
+ * 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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_ALL,
+        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",
+        tools: TOOLS_ALL,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_PLANNING,
+        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",
+        tools: TOOLS_DOCS,
+        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/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/gate-runner.js

@@ -24,7 +24,8 @@ export class UokGateRunner {
     async run(id, ctx) {
         const gate = this.registry.get(id);
         if (!gate) {
-            return {
+            const now = new Date().toISOString();
+            const unknownResult = {
                 gateId: id,
                 gateType: "unknown",
                 outcome: "manual-attention",
@@ -33,16 +34,63 @@ export class UokGateRunner {
                 attempt: 1,
                 maxAttempts: 1,
                 retryable: false,
-                evaluatedAt: new Date().toISOString(),
+                evaluatedAt: now,
             };
+            insertGateRun({
+                traceId: ctx.traceId,
+                turnId: ctx.turnId,
+                gateId: unknownResult.gateId,
+                gateType: unknownResult.gateType,
+                unitType: ctx.unitType,
+                unitId: ctx.unitId,
+                milestoneId: ctx.milestoneId,
+                sliceId: ctx.sliceId,
+                taskId: ctx.taskId,
+                outcome: unknownResult.outcome,
+                failureClass: unknownResult.failureClass,
+                rationale: unknownResult.rationale,
+                findings: unknownResult.findings,
+                attempt: unknownResult.attempt,
+                maxAttempts: unknownResult.maxAttempts,
+                retryable: unknownResult.retryable,
+                evaluatedAt: unknownResult.evaluatedAt,
+            });
+            emitUokAuditEvent(ctx.basePath, buildAuditEnvelope({
+                traceId: ctx.traceId,
+                turnId: ctx.turnId,
+                category: "gate",
+                type: "gate-run",
+                payload: {
+                    gateId: unknownResult.gateId,
+                    gateType: unknownResult.gateType,
+                    outcome: unknownResult.outcome,
+                    failureClass: unknownResult.failureClass,
+                    attempt: unknownResult.attempt,
+                    maxAttempts: unknownResult.maxAttempts,
+                    retryable: unknownResult.retryable,
+                },
+            }));
+            return unknownResult;
         }
         let attempt = 0;
         let final = null;
         const maxAttemptsByFailureClass = RETRY_MATRIX;
-        while (attempt < 3) {
+        const maxAttemptsCeiling = Math.max(...Object.values(RETRY_MATRIX)) + 1;
+        while (attempt < maxAttemptsCeiling) {
             attempt += 1;
             const now = new Date().toISOString();
-            const result = await gate.execute(ctx, attempt);
+            let result;
+            try {
+                result = await gate.execute(ctx, attempt);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                result = {
+                    outcome: "fail",
+                    failureClass: "unknown",
+                    rationale: message,
+                };
+            }
             const failureClass = result.failureClass ?? (result.outcome === "pass" ? "none" : "unknown");
             const retryBudget = maxAttemptsByFailureClass[failureClass] ?? 0;
             const retryable = result.outcome !== "pass" && attempt <= retryBudget;
@@ -54,7 +102,7 @@ export class UokGateRunner {
                 rationale: result.rationale,
                 findings: result.findings,
                 attempt,
-                maxAttempts: Math.max(1, retryBudget),
+                maxAttempts: retryBudget + 1,
                 retryable,
                 evaluatedAt: now,
             };

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;
         },