@wrongstack/sdd 0.302.2 → 0.305.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { SpecParser } from './spec-parser.js';
 export { TaskGenerator, extractVerificationCommand, assessGeneratedTaskAtomicity, type TaskGeneratorOptions, type GeneratedTask, } from './task-generator.js';
+export { assertSpecTaskGraphCoverage, assertTaskGraphExecutionIntegrity, assertTaskGraphRequirementCoverage, evaluateTaskGraphRequirementCoverage, type TaskGraphRequirementCoverage, } from './requirement-coverage.js';
 export { TaskTracker, DefaultTaskStore, type TaskStore, type TaskTrackerOptions, type TaskTransition, type TaskTrackerChange, type TaskTrackerListener, } from '@wrongstack/core/tasking';
 export { TaskFlow, SpecDrivenDev, type TaskFlowPhase, type TaskFlowOptions, type TaskFlowExecutionContext, type TaskFlowEventMap, type TaskFlowEventName, type SpecDrivenDevOptions, } from './task-flow.js';
 export { SpecStore, type SpecStoreOptions, type SpecIndexEntry } from './spec-store.js';

package/dist/index.js

@@ -280,6 +280,11 @@ var TaskGenerator = class {
   }
   async generateFromSpec(spec) {
     const graph = await this.opts.taskTracker.createGraph(spec.id, spec.title);
+    graph.requiredRequirementIds = Array.from(
+      new Set(
+        (spec.requirements ?? []).map((requirement) => requirement.id.trim()).filter(Boolean)
+      )
+    );
     const overviewSection = spec.sections?.find((s) => s.type === "overview");
     if (overviewSection?.content) {
       const overview = {
@@ -303,41 +308,7 @@ var TaskGenerator = class {
       (a, b) => (priorityOrder[a.priority] ?? 9) - (priorityOrder[b.priority] ?? 9)
     );
     for (const req of sorted) {
-      const estimateHours = REQUIREMENT_ESTIMATE_HOURS[req.priority] ?? 1;
-      const tags = [req.type, req.priority];
-      const acLines = (req.acceptanceCriteria ?? []).map((ac) => `- ${ac}`).join("\n");
-      const blockedLine = req.blockedBy?.length ? `
-
-**Blocked by:** ${req.blockedBy.join(", ")}` : "";
-      const description = `${req.description}
-
-**Type:** ${req.type}` + (acLines ? `
-
-**Acceptance Criteria:**
-${acLines}` : "") + blockedLine;
-      const metadata = {
-        ...this.atomicityMetadata({
-          title: req.description,
-          description,
-          estimateHours,
-          acceptanceCriteria: req.acceptanceCriteria ?? []
-        })
-      };
-      if (this.opts.verificationFromAcceptance) {
-        const cmd = extractVerificationCommand(req.acceptanceCriteria ?? []);
-        if (cmd) metadata.verificationCommand = cmd;
-      }
-      this.opts.taskTracker.addNode({
-        title: req.description,
-        description,
-        type: "feature",
-        priority: req.priority,
-        status: "pending",
-        estimateHours,
-        tags,
-        specRequirementId: req.id,
-        ...Object.keys(metadata).length > 0 ? { metadata } : {}
-      });
+      this.addRequirementTask(req);
     }
     if (spec.apiEndpoints?.length) {
       const apiParent = this.opts.taskTracker.addNode({
@@ -401,6 +372,78 @@ ${acLines}` : "") + blockedLine;
     });
     return graph;
   }
+  /**
+   * Repair an LLM-authored or resumed graph against the authoritative spec.
+   * Missing requirements become deterministic tasks, so omission is never
+   * rewarded by a smaller task list or an earlier "complete" result.
+   */
+  ensureRequirementCoverage(spec, graph) {
+    if (graph.specId !== spec.id) {
+      throw new Error(
+        `Task graph spec mismatch: graph targets "${graph.specId}" but spec is "${spec.id}".`
+      );
+    }
+    graph.requiredRequirementIds = Array.from(
+      new Set(
+        (spec.requirements ?? []).map((requirement) => requirement.id.trim()).filter(Boolean)
+      )
+    );
+    const required = new Set(graph.requiredRequirementIds);
+    for (const node of graph.nodes.values()) {
+      if (node.specRequirementId && !required.has(node.specRequirementId)) {
+        delete node.specRequirementId;
+      }
+    }
+    const covered = new Set(
+      Array.from(graph.nodes.values()).flatMap(
+        (node) => node.specRequirementId ? [node.specRequirementId] : []
+      )
+    );
+    const added = [];
+    for (const requirement of spec.requirements ?? []) {
+      if (covered.has(requirement.id)) continue;
+      added.push(this.addRequirementTask(requirement));
+      covered.add(requirement.id);
+    }
+    return added;
+  }
+  addRequirementTask(req) {
+    const estimateHours = REQUIREMENT_ESTIMATE_HOURS[req.priority] ?? 1;
+    const tags = [req.type, req.priority];
+    const acLines = (req.acceptanceCriteria ?? []).map((ac) => `- ${ac}`).join("\n");
+    const blockedLine = req.blockedBy?.length ? `
+
+**Blocked by:** ${req.blockedBy.join(", ")}` : "";
+    const description = `${req.description}
+
+**Type:** ${req.type}` + (acLines ? `
+
+**Acceptance Criteria:**
+${acLines}` : "") + blockedLine;
+    const metadata = {
+      ...this.atomicityMetadata({
+        title: req.description,
+        description,
+        estimateHours,
+        acceptanceCriteria: req.acceptanceCriteria ?? []
+      })
+    };
+    if (this.opts.verificationFromAcceptance) {
+      const command = extractVerificationCommand(req.acceptanceCriteria ?? []);
+      if (command) metadata.verificationCommand = command;
+    }
+    return this.opts.taskTracker.addNode({
+      title: req.description,
+      description,
+      type: "feature",
+      priority: req.priority,
+      status: "pending",
+      estimateHours,
+      tags,
+      specRequirementId: req.id,
+      ...Object.keys(metadata).length > 0 ? { metadata } : {}
+    });
+  }
   async generateSubtasks(parentTaskId, spec) {
     const reqId = this.opts.taskTracker.getNode(parentTaskId)?.specRequirementId;
     if (!reqId) return;
@@ -421,6 +464,82 @@ ${acLines}` : "") + blockedLine;
   }
 };
 
+// src/requirement-coverage.ts
+function uniqueIds(ids) {
+  return Array.from(new Set(ids.map((id) => id.trim()).filter(Boolean)));
+}
+function evaluateTaskGraphRequirementCoverage(graph, requiredIds = graph.requiredRequirementIds ?? []) {
+  const requiredRequirementIds = uniqueIds(requiredIds);
+  const required = new Set(requiredRequirementIds);
+  const mapped = uniqueIds(
+    Array.from(graph.nodes.values()).flatMap(
+      (node) => node.specRequirementId ? [node.specRequirementId] : []
+    )
+  );
+  const mappedSet = new Set(mapped);
+  const missingRequirementIds = requiredRequirementIds.filter((id) => !mappedSet.has(id));
+  const unknownRequirementIds = mapped.filter((id) => !required.has(id));
+  return {
+    valid: missingRequirementIds.length === 0 && unknownRequirementIds.length === 0,
+    requiredRequirementIds,
+    missingRequirementIds,
+    unknownRequirementIds
+  };
+}
+function assertTaskGraphRequirementCoverage(graph, requiredIds = graph.requiredRequirementIds ?? []) {
+  const result = evaluateTaskGraphRequirementCoverage(graph, requiredIds);
+  if (result.valid) return;
+  const problems = [
+    result.missingRequirementIds.length ? `missing task coverage for ${result.missingRequirementIds.join(", ")}` : "",
+    result.unknownRequirementIds.length ? `tasks reference unknown requirements ${result.unknownRequirementIds.join(", ")}` : ""
+  ].filter(Boolean);
+  throw new Error(`Task graph requirement coverage is invalid: ${problems.join("; ")}.`);
+}
+function assertSpecTaskGraphCoverage(graph, spec) {
+  if (graph.specId !== spec.id) {
+    throw new Error(
+      `Task graph spec mismatch: graph targets "${graph.specId}" but execution received "${spec.id}".`
+    );
+  }
+  assertTaskGraphRequirementCoverage(
+    graph,
+    (spec.requirements ?? []).map((requirement) => requirement.id)
+  );
+}
+function assertTaskGraphExecutionIntegrity(graph) {
+  const dependencies = graph.edges.filter((edge) => edge.type === "depends_on");
+  for (const edge of dependencies) {
+    if (!graph.nodes.has(edge.from) || !graph.nodes.has(edge.to)) {
+      throw new Error(
+        `Task graph dependency ${edge.id} references a missing task (${edge.from} -> ${edge.to}).`
+      );
+    }
+    if (edge.from === edge.to) {
+      throw new Error(`Task graph dependency ${edge.id} is a self-cycle.`);
+    }
+  }
+  const indegree = new Map(Array.from(graph.nodes.keys(), (id) => [id, 0]));
+  const outgoing = /* @__PURE__ */ new Map();
+  for (const edge of dependencies) {
+    indegree.set(edge.to, (indegree.get(edge.to) ?? 0) + 1);
+    outgoing.set(edge.from, [...outgoing.get(edge.from) ?? [], edge.to]);
+  }
+  const ready = Array.from(indegree.entries()).filter(([, degree]) => degree === 0).map(([id]) => id);
+  let visited = 0;
+  while (ready.length > 0) {
+    const id = ready.shift();
+    visited += 1;
+    for (const dependent of outgoing.get(id) ?? []) {
+      const next = (indegree.get(dependent) ?? 0) - 1;
+      indegree.set(dependent, next);
+      if (next === 0) ready.push(dependent);
+    }
+  }
+  if (visited !== graph.nodes.size) {
+    throw new Error("Task graph dependency cycle prevents deterministic execution.");
+  }
+}
+
 // src/index.ts
 import {
   TaskTracker as TaskTracker3,
@@ -1845,6 +1964,7 @@ var AISpecBuilder = class {
   maxQuestions;
   sessionPath;
   sessionPersistence;
+  pendingSessionWrite = Promise.resolve();
   constructor(opts) {
     this.store = opts.store;
     this.minQuestions = opts.minQuestions ?? 2;
@@ -1868,27 +1988,31 @@ var AISpecBuilder = class {
   /** Save session state to the configured durable owner. */
   async saveSession() {
     if (!this.sessionPersistence && !this.sessionPath) return;
-    try {
-      if (this.sessionPersistence) {
-        await this.sessionPersistence.save(structuredClone(this.session));
-        return;
+    const snapshot = structuredClone(this.session);
+    this.pendingSessionWrite = this.pendingSessionWrite.then(async () => {
+      try {
+        if (this.sessionPersistence) {
+          await this.sessionPersistence.save(snapshot);
+          return;
+        }
+        const fsp7 = await import("node:fs/promises");
+        const path6 = await import("node:path");
+        const { atomicWrite: atomicWrite4 } = await import("@wrongstack/core/utils");
+        const sessionPath = expectDefined2(this.sessionPath);
+        await fsp7.mkdir(path6.dirname(sessionPath), { recursive: true });
+        await atomicWrite4(sessionPath, JSON.stringify(snapshot, null, 2));
+      } catch (error) {
+        console.warn(
+          JSON.stringify({
+            level: "warn",
+            event: "sdd.persist.failed",
+            message: String(error),
+            timestamp: Date.now()
+          })
+        );
       }
-      const fsp7 = await import("node:fs/promises");
-      const path6 = await import("node:path");
-      const { atomicWrite: atomicWrite4 } = await import("@wrongstack/core/utils");
-      const sessionPath = expectDefined2(this.sessionPath);
-      await fsp7.mkdir(path6.dirname(sessionPath), { recursive: true });
-      await atomicWrite4(sessionPath, JSON.stringify(this.session, null, 2));
-    } catch (error) {
-      console.warn(
-        JSON.stringify({
-          level: "warn",
-          event: "sdd.persist.failed",
-          message: String(error),
-          timestamp: Date.now()
-        })
-      );
-    }
+    });
+    await this.pendingSessionWrite;
   }
   /** Load session state from the configured durable owner. */
   async loadSession() {
@@ -1915,6 +2039,7 @@ var AISpecBuilder = class {
   }
   /** Delete the saved session from the configured durable owner. */
   async deleteSession() {
+    await this.pendingSessionWrite;
     if (this.sessionPersistence) {
       await this.sessionPersistence.delete();
       return;
@@ -2426,9 +2551,17 @@ var SddInterviewDriver = class {
    * emitted a parseable task array.
    */
   async ensureTaskGraph() {
-    if (this.graph) return this.graph;
     const spec = this.builder.getSession().spec;
     if (!spec) return null;
+    if (this.graph && this.tracker) {
+      const generator2 = new TaskGenerator({
+        taskTracker: this.tracker,
+        verificationFromAcceptance: process.env["WRONGSTACK_SDD_VERIFY_FROM_ACCEPTANCE"] === "1"
+      });
+      generator2.ensureRequirementCoverage(spec, this.graph);
+      await this.persistGraph(this.graph);
+      return this.graph;
+    }
     const tracker = new TaskTracker2({ store: this.o.graphStore });
     const generator = new TaskGenerator({
       taskTracker: tracker,
@@ -2550,6 +2683,10 @@ var SddInterviewDriver = class {
         if (depId && depId !== nodeId) tracker.addDependency(depId, nodeId);
       }
     }
+    new TaskGenerator({
+      taskTracker: tracker,
+      verificationFromAcceptance: process.env["WRONGSTACK_SDD_VERIFY_FROM_ACCEPTANCE"] === "1"
+    }).ensureRequirementCoverage(spec, graph);
     await this.persistGraph(graph);
     await this.builder.setTaskGraphId(graph.id);
     await this.builder.saveSession();
@@ -2562,6 +2699,8 @@ function normalizeTaskRef(ref) {
   return ref.trim().toLowerCase();
 }
 function addTaskToTracker(tracker, task) {
+  const rawRequirementId = task.specRequirementId ?? task.requirementId;
+  const specRequirementId = typeof rawRequirementId === "string" && rawRequirementId.trim() ? rawRequirementId.trim() : void 0;
   return tracker.addNode({
     title: String(task.title),
     description: String(task.description ?? ""),
@@ -2569,7 +2708,8 @@ function addTaskToTracker(tracker, task) {
     priority: TASK_PRIORITIES.includes(String(task.priority)) ? String(task.priority) : "medium",
     status: "pending",
     estimateHours: Number(task.estimateHours) || 2,
-    tags: Array.isArray(task.tags) ? task.tags.map(String) : []
+    tags: Array.isArray(task.tags) ? task.tags.map(String) : [],
+    ...specRequirementId ? { specRequirementId } : {}
   });
 }
 function isExplanatoryText(text) {
@@ -3772,6 +3912,10 @@ function applySddControlCommand(run, command) {
   });
 }
 function startSddRun(opts) {
+  assertTaskGraphExecutionIntegrity(opts.graph);
+  if (opts.graph.requiredRequirementIds !== void 0) {
+    assertTaskGraphRequirementCoverage(opts.graph);
+  }
   SddParallelRun.resetOrphans(opts.tracker);
   const run = new SddParallelRun({
     tracker: opts.tracker,
@@ -4912,6 +5056,8 @@ var AutoExecutor = class {
    * Execute all tasks in the graph, respecting dependencies.
    */
   async execute(graph, spec) {
+    assertSpecTaskGraphCoverage(graph, spec);
+    assertTaskGraphExecutionIntegrity(graph);
     this.stopped = false;
     this.retryMap.clear();
     const startTime = Date.now();
@@ -4980,7 +5126,7 @@ var AutoExecutor = class {
     const ready = [];
     for (const node of graph.nodes.values()) {
       if (node.status !== "pending") continue;
-      const blockers = graph.edges.filter((e) => e.type === "depends_on" && e.from === node.id).map((e) => graph.nodes.get(e.to)).filter(Boolean);
+      const blockers = graph.edges.filter((e) => e.type === "depends_on" && e.to === node.id).map((e) => graph.nodes.get(e.from)).filter(Boolean);
       const allBlockersDone = blockers.every((b) => b.status === "completed");
       if (allBlockersDone) {
         ready.push(node);
@@ -5041,11 +5187,11 @@ var AutoExecutor = class {
   }
   /** Get tasks that this task depends on. */
   getTaskDependencies(taskId, graph) {
-    return graph.edges.filter((e) => e.type === "depends_on" && e.from === taskId).map((e) => graph.nodes.get(e.to)).filter(Boolean);
+    return graph.edges.filter((e) => e.type === "depends_on" && e.to === taskId).map((e) => graph.nodes.get(e.from)).filter(Boolean);
   }
   /** Get tasks that depend on this task. */
   getTaskDependents(taskId, graph) {
-    return graph.edges.filter((e) => e.type === "depends_on" && e.to === taskId).map((e) => graph.nodes.get(e.from)).filter(Boolean);
+    return graph.edges.filter((e) => e.type === "depends_on" && e.from === taskId).map((e) => graph.nodes.get(e.to)).filter(Boolean);
   }
   /** Detect deadlock: all remaining tasks are blocked by failed tasks. */
   detectDeadlock(graph) {
@@ -5054,7 +5200,7 @@ var AutoExecutor = class {
     );
     if (remaining.length === 0) return false;
     return remaining.every((node) => {
-      const blockers = graph.edges.filter((e) => e.type === "depends_on" && e.from === node.id).map((e) => graph.nodes.get(e.to)).filter(Boolean);
+      const blockers = graph.edges.filter((e) => e.type === "depends_on" && e.to === node.id).map((e) => graph.nodes.get(e.from)).filter(Boolean);
       return blockers.some((b) => b.status === "failed");
     });
   }
@@ -5583,6 +5729,9 @@ export {
   TaskTracker3 as TaskTracker,
   analyzeCriticalPath,
   applySddLifecycle,
+  assertSpecTaskGraphCoverage,
+  assertTaskGraphExecutionIntegrity,
+  assertTaskGraphRequirementCoverage,
   assessGeneratedTaskAtomicity,
   assessTaskNodeAtomicity,
   buildBoardSnapshot,
@@ -5594,6 +5743,7 @@ export {
   createKanbanSddSessionPersistence,
   decomposeNonAtomicTasks,
   destroySddProject,
+  evaluateTaskGraphRequirementCoverage,
   extractVerificationCommand,
   gatherProjectContext,
   getTemplate,

package/dist/requirement-coverage.d.ts

@@ -0,0 +1,14 @@
+import type { Specification, TaskGraph } from '@wrongstack/core/types';
+export interface TaskGraphRequirementCoverage {
+    valid: boolean;
+    requiredRequirementIds: string[];
+    missingRequirementIds: string[];
+    unknownRequirementIds: string[];
+}
+/** Deterministic requirement-to-task coverage; no model judgment is involved. */
+export declare function evaluateTaskGraphRequirementCoverage(graph: TaskGraph, requiredIds?: readonly string[]): TaskGraphRequirementCoverage;
+export declare function assertTaskGraphRequirementCoverage(graph: TaskGraph, requiredIds?: readonly string[]): void;
+export declare function assertSpecTaskGraphCoverage(graph: TaskGraph, spec: Specification): void;
+/** Fail before dispatch when dependency edges cannot form an executable DAG. */
+export declare function assertTaskGraphExecutionIntegrity(graph: TaskGraph): void;
+//# sourceMappingURL=requirement-coverage.d.ts.map

package/dist/spec-builder.d.ts

@@ -27,6 +27,7 @@ export declare class AISpecBuilder {
     private readonly maxQuestions;
     private readonly sessionPath?;
     private readonly sessionPersistence?;
+    private pendingSessionWrite;
     constructor(opts: AISpecBuilderOptions);
     /** Save session state to the configured durable owner. */
     saveSession(): Promise<void>;

package/dist/task-generator.d.ts

@@ -1,5 +1,5 @@
 import type { TaskStore, TaskTracker } from '@wrongstack/core/tasking';
-import type { Specification, TaskGraph, TaskPriority, TaskType } from '@wrongstack/core/types';
+import type { Specification, TaskGraph, TaskNode, TaskPriority, TaskType } from '@wrongstack/core/types';
 import { type AtomicityRuleSetConfig } from '@wrongstack/kanban';
 /** Named estimate constants shared with the atomicity candidate mapping. */
 export declare const OVERVIEW_ESTIMATE_HOURS = 4;
@@ -62,6 +62,13 @@ export declare class TaskGenerator {
     /** metadata.atomicity payload when the option is enabled, else undefined. */
     private atomicityMetadata;
     generateFromSpec(spec: Specification): Promise<TaskGraph>;
+    /**
+     * Repair an LLM-authored or resumed graph against the authoritative spec.
+     * Missing requirements become deterministic tasks, so omission is never
+     * rewarded by a smaller task list or an earlier "complete" result.
+     */
+    ensureRequirementCoverage(spec: Specification, graph: TaskGraph): TaskNode[];
+    private addRequirementTask;
     generateSubtasks(parentTaskId: string, spec: Specification): Promise<void>;
 }
 export type { TaskStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/sdd",
-  "version": "0.302.2",
+  "version": "0.305.0",
   "license": "MIT",
   "description": "WrongStack Spec-Driven Development engine — standalone package extracted from @wrongstack/core. Task graph generation, tracking, execution, lifecycle management, and AI-driven spec building for SDD workflows.",
   "repository": {
@@ -27,9 +27,9 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@wrongstack/core": "0.302.2",
-    "@wrongstack/requirement-intake": "0.302.2",
-    "@wrongstack/kanban": "0.302.2"
+    "@wrongstack/core": "0.305.0",
+    "@wrongstack/kanban": "0.305.0",
+    "@wrongstack/requirement-intake": "0.305.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",