@abelxiaoxing/cadence 1.4.0 → 1.5.0

package/src/delivery-compiler.ts

@@ -2,14 +2,12 @@ import { createHash } from "node:crypto";
 import { compareCanonicalStrings } from "./canonical.ts";
 import {
   assertPlanWithinChangeContract,
-  type ChangeContract,
   normalizeChangeContract,
 } from "./change-contract.ts";
 import {
   type AgentsImpact,
   type ImplementGraphBoundary,
   type ImplementGraphOutput,
-  type ImplementTaskBoundary,
   isAgentsPath,
   isValidRelativePath,
   type PhaseBoundary,
@@ -17,12 +15,25 @@ import {
   validateImplementGraphBoundary,
   validateVerificationContract,
 } from "./contracts.ts";
+import {
+  type DesignPlanDiagnostic,
+  DesignPlanValidationError,
+} from "./design-diagnostics.ts";
 import {
   assessImplementGraphReadiness,
   canonicalJson,
   hashCanonicalValue,
   type ImplementGraphReadiness,
 } from "./implement-graph.ts";
+import type {
+  ImplementPlan,
+  PlanAgentsCheckpointOperation,
+  PlanTaskDraft,
+  PlanTracking,
+  PlanVerification,
+} from "./implement-plan.ts";
+import { expandPlanDraft, preparePlanDraft } from "./plan-draft.ts";
+import { expandSingleTaskDraft } from "./single-task-draft.ts";
 import {
   bindDraftVerificationInputs,
   validateVerificationAdapterCapability,
@@ -103,40 +114,6 @@ export class DeliveryValidationError extends Error {
   }
 }
 
-export interface DesignPlanDiagnostic {
-  code: string;
-  taskId?: string;
-  phase?: string;
-  field?: string;
-  category?: string;
-  owner?: string;
-  verificationId?: string;
-  outputId?: string;
-  dependencyTaskId?: string;
-  producerTaskId?: string;
-  producerPhase?: string;
-}
-
-export class DesignPlanValidationError extends Error {
-  readonly diagnostics: readonly DesignPlanDiagnostic[];
-
-  constructor(message: string, diagnostics: readonly DesignPlanDiagnostic[]) {
-    const normalized = [
-      ...new Map(
-        diagnostics
-          .map((diagnostic) => structuredClone(diagnostic))
-          .sort((left, right) =>
-            compareCanonicalStrings(canonicalJson(left), canonicalJson(right)),
-          )
-          .map((diagnostic) => [canonicalJson(diagnostic), diagnostic]),
-      ).values(),
-    ];
-    super(message);
-    this.name = "DesignPlanValidationError";
-    this.diagnostics = Object.freeze(normalized);
-  }
-}
-
 const SAFE_PLAN_ERROR_CODE = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/u;
 
 function planErrorCode(error: unknown): string {
@@ -182,6 +159,22 @@ export function assessDeliveryTraceability(input: {
   plan: ImplementPlan;
 }): DeliveryTraceabilityAssessment {
   const diagnostics = new Set<string>();
+  let authorMarkdown = input.tasksMarkdown;
+  let bindings: string | undefined;
+  try {
+    const region = taskVerificationRegion(input.tasksMarkdown);
+    if (region) {
+      authorMarkdown =
+        input.tasksMarkdown.slice(0, region.start) +
+        input.tasksMarkdown.slice(region.end);
+      bindings = region.text;
+      if (bindings !== renderTasks(input.plan)) {
+        diagnostics.add("traceability-managed-region-stale");
+      }
+    }
+  } catch {
+    return { ok: false, diagnostics: ["traceability-managed-region-invalid"] };
+  }
   const headings = new Set<string>();
   for (const spec of input.specs) {
     if (!isValidRelativePath(spec.path) || !spec.path.endsWith("/spec.md")) {
@@ -206,7 +199,7 @@ export function assessDeliveryTraceability(input: {
     }
   }
   const references = [
-    ...input.tasksMarkdown.matchAll(/`(specs\/[^`\n]+\/spec\.md#[^`\n]+)`/gu),
+    ...authorMarkdown.matchAll(/`(specs\/[^`\n]+\/spec\.md#[^`\n]+)`/gu),
   ].flatMap((match) => (match[1] ? [match[1].trim()] : []));
   if (references.length === 0) diagnostics.add("traceability-reference-empty");
   const referenceSet = new Set(references);
@@ -220,9 +213,7 @@ export function assessDeliveryTraceability(input: {
     diagnostics.add("traceability-scenario-unowned");
   }
   const taskIds = input.plan.tasks.map((task) => task.taskId).sort();
-  if (
-    taskIds.some((taskId) => !input.tasksMarkdown.includes(`\`${taskId}\``))
-  ) {
+  if (taskIds.some((taskId) => !authorMarkdown.includes(`\`${taskId}\``))) {
     diagnostics.add("traceability-task-unmapped");
   }
   const verificationIds = input.plan.tasks
@@ -236,7 +227,8 @@ export function assessDeliveryTraceability(input: {
     .sort();
   if (
     verificationIds.some(
-      (verificationId) => !input.tasksMarkdown.includes(verificationId),
+      (verificationId) =>
+        !(bindings ?? authorMarkdown).includes(verificationId),
     )
   ) {
     diagnostics.add("traceability-verification-unmapped");
@@ -260,70 +252,16 @@ export function assessDeliveryTraceability(input: {
   };
 }
 
-export type PlanPhaseDraft = PhaseBoundary;
-
-export interface PlanTaskDraft extends Omit<ImplementTaskBoundary, "phases"> {
-  phases: {
-    red: PlanPhaseDraft;
-    green: PlanPhaseDraft;
-    refactor?: PlanPhaseDraft;
-  };
-  affectedVerification: StructuredVerificationContract;
-  repairVerification: StructuredVerificationContract;
-}
-
-export interface PlanVerification {
-  baseline: {
-    target: "task-red-contracts";
-    affected: "task-affected-contracts";
-    fullSuite: StructuredVerificationContract;
-    failureIdentity: "normalized";
-  };
-  change: {
-    affected: "task-affected-contracts";
-    fullSuite: StructuredVerificationContract;
-    postApply: StructuredVerificationContract;
-  };
-  artifactCorrection: {
-    maxAttempts: number;
-  };
-  repair: {
-    maxAttempts: number;
-    inBoundaryOnly: true;
-    approvalOnBoundaryExpansion: true;
-    attribution: ["pre-existing", "introduced", "unresolved", "environment"];
-  };
-  agentsCheckpoint: {
-    required: boolean;
-    verification: StructuredVerificationContract | null;
-    operations: PlanAgentsCheckpointOperation[];
-  };
-}
-
-export interface PlanAgentsCheckpointOperation {
-  target: string;
-  impact: Exclude<AgentsImpact, "none">;
-  taskIds: string[];
-  managedBlock: string | null;
-}
-
-export interface PlanTracking {
-  path: "tasks.md";
-  format: "markdown-checkbox";
-  taskIds: string[];
-  completionOwner: "parent";
-}
-
-export interface PlanDraft {
-  changeContract?: ChangeContract;
-  changeId: string;
-  tasks: PlanTaskDraft[];
-  outputs: ImplementGraphOutput[];
-  verification: PlanVerification;
-  tracking: PlanTracking;
-}
-
-export type ImplementPlan = PlanDraft;
+export type { DesignPlanDiagnostic } from "./design-diagnostics.ts";
+export { DesignPlanValidationError } from "./design-diagnostics.ts";
+export type {
+  ImplementPlan,
+  PlanAgentsCheckpointOperation,
+  PlanTaskDraft,
+  PlanTracking,
+  PlanVerification,
+} from "./implement-plan.ts";
+export type { PlanDraft, PlanPhaseDraft, PlanTaskInput } from "./plan-draft.ts";
 
 export interface CompiledDelivery {
   plan: ImplementPlan;
@@ -690,7 +628,7 @@ function normalizeVerification(
   return cloned;
 }
 
-function normalizePhase(value: unknown, readOnly = false): PlanPhaseDraft {
+function normalizePhase(value: unknown, readOnly = false): PhaseBoundary {
   if (
     !isRecord(value) ||
     !exactKeys(value, [
@@ -837,7 +775,7 @@ function normalizeTask(value: unknown): PlanTaskDraft {
 }
 
 function graphFromPlan(plan: ImplementPlan): ImplementGraphBoundary {
-  const stripPhase = (phase: PlanPhaseDraft): PhaseBoundary => ({
+  const stripPhase = (phase: PhaseBoundary): PhaseBoundary => ({
     read: phase.read,
     write: phase.write,
     delete: phase.delete,
@@ -1177,7 +1115,7 @@ function normalizeDraft(value: unknown): ImplementPlan {
   if (!draftGraph.ok) {
     throw new DesignPlanValidationError(
       `delivery-plan-invalid:${draftGraph.reason}`,
-      [draftGraph.diagnostic],
+      draftGraph.diagnostics ?? [draftGraph.diagnostic],
     );
   }
   const plan: ImplementPlan = {
@@ -1247,32 +1185,79 @@ function normalizeDraft(value: unknown): ImplementPlan {
   return plan;
 }
 
+const TASK_BINDINGS_START = "<!-- ABEL:VERIFICATION-BINDINGS:START -->";
+const TASK_BINDINGS_END = "<!-- ABEL:VERIFICATION-BINDINGS:END -->";
+
+function taskVerificationRegion(markdown: string) {
+  const markers = markdown.match(/<!-- ABEL:VERIFICATION-BINDINGS/gu) ?? [];
+  if (markers.length === 0) return undefined;
+  const match =
+    /^<!-- ABEL:VERIFICATION-BINDINGS:START -->\r?\n[\s\S]*?^<!-- ABEL:VERIFICATION-BINDINGS:END -->(?=\r?$)/mu.exec(
+      markdown,
+    );
+  if (markers.length !== 2 || !match) {
+    throw new DesignPlanValidationError("traceability-managed-region-invalid", [
+      { code: "traceability-managed-region-invalid", path: "tasks.md" },
+    ]);
+  }
+  return {
+    start: match.index,
+    end: match.index + match[0].length,
+    text: match[0],
+  };
+}
+
+// Only identity bindings are generated. Author task checkboxes and Scenario
+// ownership remain outside this region and are validated independently.
 function renderTasks(plan: ImplementPlan): string {
-  const lines = ["# Implementation tasks", ""];
-  for (const task of plan.tasks) {
-    lines.push(`- [ ] ${task.taskId} — ${task.objective}`);
+  const lines = [TASK_BINDINGS_START, "## Compiled verification bindings", ""];
+  for (const task of [...plan.tasks].sort((a, b) =>
+    compareCanonicalStrings(a.taskId, b.taskId),
+  )) {
     lines.push(
-      `  - Depends on: ${task.dependsOn.length > 0 ? task.dependsOn.join(", ") : "[]"}`,
+      `- Task \`${task.taskId}\` (${task.verificationMode ?? "behavior"})`,
     );
-    if (!task.verificationMode || task.verificationMode === "behavior")
-      lines.push(`  - Red verification: ${task.phases.red.verification.id}`);
-    else
-      lines.push(
-        `  - Evidence mode: ${task.verificationMode}; baseline and postconditions required`,
-      );
-    lines.push(`  - Green verification: ${task.phases.green.verification.id}`);
+    if (!task.verificationMode || task.verificationMode === "behavior") {
+      lines.push(`  - Red: \`${task.phases.red.verification.id}\``);
+    }
+    lines.push(`  - Green: \`${task.phases.green.verification.id}\``);
+    if (task.phases.refactor) {
+      lines.push(`  - Refactor: \`${task.phases.refactor.verification.id}\``);
+    }
   }
-  lines.push("");
+  lines.push(TASK_BINDINGS_END);
   return lines.join("\n");
 }
 
+export function bindTaskVerifications(
+  markdown: string,
+  plan: ImplementPlan,
+): string {
+  const region = taskVerificationRegion(markdown);
+  const bindings = renderTasks(plan);
+  if (region) {
+    return (
+      markdown.slice(0, region.start) + bindings + markdown.slice(region.end)
+    );
+  }
+  return `${markdown}${markdown.endsWith("\n") ? "\n" : "\n\n"}${bindings}\n`;
+}
+
 export function compileImplementPlan(
   draft: unknown,
   options: { consumerRoot: string; bindExecutionInputs?: boolean },
 ): CompiledDelivery {
   try {
+    draft = expandSingleTaskDraft(draft);
+    // Resolve omitted manifest command bytes before named definitions are
+    // validated and purpose identities are hashed. The second pass below
+    // binds execution inputs on the expanded contracts with their final IDs.
+    if (options.bindExecutionInputs)
+      draft = bindDraftVerificationInputs(options.consumerRoot, draft);
+    draft = expandPlanDraft(draft);
     if (options.bindExecutionInputs)
       draft = bindDraftVerificationInputs(options.consumerRoot, draft);
+    draft = preparePlanDraft(draft);
     const normalized = normalizeDraft(draft);
     const plan =
       isRecord(draft) && legacyPlans.get(draft) === JSON.stringify(draft)

package/src/delivery-revision.ts

@@ -0,0 +1,42 @@
+import type { ImplementPlan } from "./implement-plan.ts";
+import {
+  deliveryBoundPaths,
+  type EngineTaskRow,
+  taskApprovalBoundary,
+} from "./workflow-policy.ts";
+/** Compare authority only; retained bytes still require executor currentness and replay. */
+export function compareDeliveryRevision(
+  priorPlan: ImplementPlan | undefined,
+  nextPlan: ImplementPlan,
+  priorRows: readonly Pick<EngineTaskRow, "task_id">[],
+) {
+  const priorTasks = new Map(
+    (priorPlan?.tasks ?? []).map((task) => [task.taskId, task]),
+  );
+  const nextTasks = new Map(nextPlan.tasks.map((task) => [task.taskId, task]));
+  const priorBoundPaths = new Set(
+    priorPlan ? deliveryBoundPaths(priorPlan) : [],
+  );
+  const boundaryExpanded = deliveryBoundPaths(nextPlan).some(
+    (relative) => !priorBoundPaths.has(relative),
+  );
+  const compatible = new Set<string>();
+  if (priorPlan) {
+    for (const [taskId, priorTask] of priorTasks) {
+      const nextTask = nextTasks.get(taskId);
+      if (
+        nextTask &&
+        taskApprovalBoundary(priorPlan, priorTask) ===
+          taskApprovalBoundary(nextPlan, nextTask)
+      ) {
+        compatible.add(taskId);
+      }
+    }
+  }
+  const invalidated = new Set(
+    priorRows
+      .filter((row) => !compatible.has(row.task_id))
+      .map((row) => row.task_id),
+  );
+  return { compatible, invalidated, boundaryExpanded };
+}

package/src/design-control.ts

@@ -13,9 +13,11 @@ import {
   type ChangeContract,
   normalizeChangeContract,
 } from "./change-contract.ts";
+import { changeContractDiagnostics } from "./change-contract-schema.ts";
 import { isValidRelativePath } from "./contracts.ts";
 import {
   assessDeliveryTraceability,
+  bindTaskVerifications,
   compileGateAReceipt,
   compileImplementPlan,
   compileReadyReceipt,
@@ -26,6 +28,7 @@ import {
   parseImplementPlan,
   parseReadyReceipt,
 } from "./delivery-compiler.ts";
+import type { DesignPlanDiagnostic } from "./design-diagnostics.ts";
 import {
   type DesignArtifactOperationFacts,
   type DesignArtifactOperationOutcome,
@@ -33,6 +36,7 @@ import {
   type DesignStatusProjection,
 } from "./design-journal.ts";
 import { OpenSpecCliError, type OpenSpecDiagnostic } from "./openspec-cli.ts";
+import { planAuthoringSummary } from "./plan-draft-summary.ts";
 import { canonicalJson } from "./run-state.ts";
 import { RunStore } from "./run-store.ts";
 import { observeSafePath } from "./safe-path.ts";
@@ -199,7 +203,53 @@ function lifecycleOperationId(kind: string, runId: string): string {
     .slice(0, 32)}`;
 }
 
-export function validateDesignControlRequest(
+export class DesignControlValidationError extends DesignPlanValidationError {
+  constructor(diagnostics: readonly DesignPlanDiagnostic[]) {
+    super("invalid-design-control-request", diagnostics);
+  }
+}
+export function validateDesignControlRequest(value: unknown):
+  | { ok: true; value: DesignControlRequest }
+  | {
+      ok: false;
+      code: "invalid-design-control-request";
+      diagnostics: DesignPlanDiagnostic[];
+    } {
+  const parsed = parseDesignControlRequest(value);
+  if (parsed.ok) return parsed;
+  let diagnostics: DesignPlanDiagnostic[] = [];
+  if (
+    isRecord(value) &&
+    value.operation === "approve-gate" &&
+    value.gate === "gate-a" &&
+    typeof value.contract !== "string"
+  )
+    diagnostics = changeContractDiagnostics(value.contract);
+  if (!diagnostics.length) {
+    const field = !isRecord(value)
+      ? "request"
+      : typeof value.operation !== "string"
+        ? "operation"
+        : value.operation !== "start" &&
+            (typeof value.runId !== "string" || !IDENTIFIER.test(value.runId))
+          ? "runId"
+          : !["status", "validate-plan-draft"].includes(
+                String(value.operation),
+              ) &&
+              (typeof value.operationId !== "string" ||
+                !IDENTIFIER.test(value.operationId))
+            ? "operationId"
+            : value.operation === "approve-gate"
+              ? value.gate === "gate-a"
+                ? "contract"
+                : "gate"
+              : "request";
+    diagnostics = [{ code: "design-control-field-invalid", field }];
+  }
+  return { ...parsed, diagnostics };
+}
+
+function parseDesignControlRequest(
   value: unknown,
 ):
   | { ok: true; value: DesignControlRequest }
@@ -553,7 +603,8 @@ export class DesignController {
   async execute(value: unknown): Promise<Record<string, unknown>> {
     this.#assertOpen();
     const validation = validateDesignControlRequest(value);
-    if (!validation.ok) throw new Error(validation.code);
+    if (!validation.ok)
+      throw new DesignControlValidationError(validation.diagnostics);
     const request = validation.value;
     switch (request.operation) {
       case "start":
@@ -631,6 +682,30 @@ export class DesignController {
       completed: run.state === "completed",
       ...(run.pauseCode ? { pause: { code: run.pauseCode } } : {}),
       legalOperations,
+      nextStep: terminal
+        ? null
+        : !design.gates.gateA.current
+          ? {
+              operation: "approve-gate",
+              instruction:
+                "Read applicable instructions, the affected source and existing tests, and the verification manifest together. Resolve only remaining substantive choices; use existing same-task approval. Submit the accepted structured ChangeContract, not a prose placeholder.",
+            }
+          : !design.change
+            ? {
+                operation: "bind-change",
+                instruction: "Bind the approved change name to this runId.",
+              }
+            : !design.plan || !design.gates.gateB.current
+              ? {
+                  operation: "write-artifact",
+                  instruction:
+                    "Write proposal, design, specs, author task checkboxes with exact Scenario references, and plan-draft.json. Use the installed example named in the tool description; omit derived identities. Preflight then compile; compilation supplies verification bindings and Gate B.",
+                }
+              : {
+                  operation: "finalize-delivery",
+                  instruction:
+                    "Finalize the prepared artifacts. If tasks or the draft changed since compilation, preflight and compile again first. No separate Gate B approval is needed.",
+                },
       packetActions: terminal ? [] : ["finish"],
       design,
     };
@@ -866,6 +941,7 @@ export class DesignController {
         { code: "design-plan-draft-invalid", field: "plan-draft.json" },
       ]);
     }
+    const authoredDraft = structuredClone(draft);
     if (status.changeContract) {
       if (!draft || typeof draft !== "object" || Array.isArray(draft))
         throw new Error("change-contract-invalid");
@@ -888,7 +964,7 @@ export class DesignController {
         { code: "design-plan-change-mismatch", field: "changeId" },
       ]);
     }
-    return { status, compiled };
+    return { status, compiled, authoredDraft };
   }
 
   #validatePlanDraft(
@@ -897,11 +973,12 @@ export class DesignController {
       { operation: "validate-plan-draft" }
     >,
   ) {
-    const { compiled } = this.#readCompiledDraft(request.runId);
+    const { compiled, authoredDraft } = this.#readCompiledDraft(request.runId);
     return {
       operation: request.operation,
       runId: request.runId,
       valid: true,
+      summary: planAuthoringSummary(compiled.plan, authoredDraft),
       plan: {
         taskCount: compiled.plan.tasks.length,
         outputCount: compiled.plan.outputs.length,
@@ -931,7 +1008,29 @@ export class DesignController {
       if (!change) throw new Error("design-change-required");
       const readyPath = safeRelative(change, "ready.yaml");
       const gateAPath = safeRelative(change, "gate-a.yaml");
+      const tasksPath = safeRelative(change, "tasks.md");
+      if (observeSafePath(this.consumerRoot, tasksPath).kind === "absent") {
+        throw new DesignPlanValidationError(
+          "design-traceability-input-unavailable",
+          [{ code: "design-traceability-input-unavailable", path: "tasks.md" }],
+        );
+      }
+      const priorTasks = boundedArtifactBytes(this.consumerRoot, tasksPath);
+      const tasksBytes = Buffer.from(
+        bindTaskVerifications(
+          new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+            priorTasks,
+          ),
+          compiled.plan,
+        ),
+        "utf8",
+      );
+      if (tasksBytes.length > MAX_DESIGN_FILE_BYTES) {
+        throw new Error("design-artifact-content-too-large");
+      }
+      const tasksUnchanged = tasksBytes.equals(priorTasks);
       const unchanged =
+        tasksUnchanged &&
         status.gates.gateB.current &&
         status.plan?.rawSha256 === compiled.rawSha256 &&
         status.plan.canonicalHash === compiled.planHash;
@@ -940,6 +1039,16 @@ export class DesignController {
         removeSafeFile(this.consumerRoot, gateAPath);
       }
       this.#assertFinalizationLease(lease);
+      if (
+        !boundedArtifactBytes(this.consumerRoot, tasksPath).equals(priorTasks)
+      ) {
+        throw new Error("design-artifact-currentness-mismatch");
+      }
+      // The compilation journal commits only after both files are installed.
+      // A crash before that point can replay this deterministic projection;
+      // finalization always rechecks the plan and task bytes together.
+      if (!tasksUnchanged)
+        atomicWrite(this.consumerRoot, tasksPath, tasksBytes);
       atomicWrite(
         this.consumerRoot,
         safeRelative(change, "implement-plan.json"),