@xenonbyte/da-vinci-workflow 0.1.19 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js"
@@ -22,6 +22,7 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "validate-assets": "node scripts/validate-assets.js",
+    "test:audit-context-delta": "node scripts/test-audit-context-delta.js",
     "test:audit-design-supervisor": "node scripts/test-audit-design-supervisor.js",
     "test:pencil-lock": "node scripts/test-pencil-lock.js",
     "test:mode-consistency": "node scripts/test-mode-consistency.js",

package/references/artifact-templates.md

@@ -592,6 +592,26 @@ Use this structure:
 - `Final runtime gate status`
 - Notes
 
+## Context Delta
+- One concise entry per checkpoint-adjacent event
+- Required fields:
+  - `time`
+  - `checkpoint_type`
+  - `goal`
+  - `decision`
+  - `constraints`
+  - `impact`
+  - `status`
+  - `next_action`
+- Optional field:
+  - `supersedes`
+- `supersedes` should reference an earlier entry in the same artifact by `time`, or by `checkpoint_type@time`
+- Parseable timestamp format differences are tolerated during audit (for example: `2026-03-28T12:00:00.000Z` and `2026-03-28 12:00:00Z`)
+- Keep entries as delta summaries, not transcript copies
+- Use this section as auxiliary recovery context only; it is not the phase source of truth
+- Context-delta expectation checks run automatically when this artifact includes `## Checkpoint Status` or `## MCP Runtime Gate`
+- If this artifact should be checked without those headings, add `- Context Delta Required: true` (accepted truthy values: `true`, `yes`, `on`, `1`)
+
 ## Checkpoint Status
 - `mcp runtime gate`
 - `design-source checkpoint`
@@ -630,6 +650,15 @@ Use this structure:
 ## 5. Verification
 - [ ] Check requirement coverage
 - [ ] Check Pencil coverage
+
+## Context Delta
+- Add concise checkpoint-adjacent entries when `task checkpoint` or execution planning decisions change
+- Required fields: `time`, `checkpoint_type`, `goal`, `decision`, `constraints`, `impact`, `status`, `next_action`
+- Optional field: `supersedes`
+- `supersedes` should reference an earlier entry in the same artifact by `time`, or by `checkpoint_type@time`
+- Parseable timestamp format differences are tolerated during audit
+- Keep this section auxiliary; route and phase decisions still come from artifact and checkpoint truth
+- If this artifact has no `## Checkpoint Status` or `## MCP Runtime Gate`, add `- Context Delta Required: true` (accepted truthy values: `true`, `yes`, `on`, `1`) when you still want audit expectation checks
 ```
 
 Prefer top-level task groups. They are required for execution checkpoints.
@@ -697,6 +726,15 @@ Use this structure:
 ## Outcome
 - PASS / WARN / BLOCK
 - Next action
+
+## Context Delta
+- Add concise entries after each `execution checkpoint`
+- Required fields: `time`, `checkpoint_type`, `goal`, `decision`, `constraints`, `impact`, `status`, `next_action`
+- Optional field: `supersedes`
+- `supersedes` should reference an earlier entry in the same artifact by `time`, or by `checkpoint_type@time`
+- Parseable timestamp format differences are tolerated during audit
+- Use entries to preserve short-horizon execution context; do not treat them as completion-gate truth
+- `## Outcome` alone does not enable context-delta expectation checks; add `- Context Delta Required: true` (or `yes` / `on` / `1`) when needed
 ```
 
 Recommended path:

package/references/checkpoints.md

@@ -23,6 +23,15 @@ Resume rule:
 
 - when artifacts already exist and the workflow was paused, `continue` should resume from the current artifact truth instead of restarting discovery
 
+Context-delta rule:
+
+- context deltas are auxiliary recovery notes, not authoritative phase truth
+- write context deltas only at existing checkpoint-adjacent boundaries
+- when context deltas conflict with current artifacts or checkpoint results, ignore those deltas for routing and continue from artifact truth
+- context-delta expectation checks auto-apply to artifacts that include `## Checkpoint Status` or `## MCP Runtime Gate`
+- when an artifact should opt in without those headings, add `- Context Delta Required: true` (accepted truthy values: `true`, `yes`, `on`, `1`)
+- when `supersedes` references parseable timestamps in different textual formats, treat them as the same point-in-time reference
+
 ## Visual Contract Rule
 
 Before broad Pencil page generation:
@@ -310,6 +319,7 @@ Automatic failures:
 - if the workflow claims the `.pen` source exists only "in memory", treat completion as `BLOCK`
 - if the workflow claims success after exporting PNGs but without a shell-visible `.pen`, treat completion as `BLOCK`
 - if the workflow reports completion without the required standard artifacts for the active stage, treat completion as `BLOCK`
+- missing or stale context-delta notes alone are `WARN`, not `BLOCK`
 
 ## `execution checkpoint`
 
@@ -350,3 +360,9 @@ Use this reporting shape:
 ```
 
 Do not create separate review artifacts unless the project explicitly requires them.
+
+Context-delta reporting notes:
+
+- keep entries concise and checkpoint-adjacent
+- do not dump full dialogue transcripts into workflow artifacts
+- do not create a separate top-level context ledger for this; use existing change artifacts

package/references/prompt-recipes.md

@@ -18,6 +18,9 @@ Keep these rules fixed:
 - do not default `intake` or `continue` into `build`
 - use `build` directly only when tasks, design bindings, and implementation readiness are already clear
 - continuation prompts should preserve existing artifact truth instead of restarting discovery
+- continuation routing should be decided from artifact and checkpoint truth before consulting any contextual delta notes
+- contextual delta notes are auxiliary recovery signals; they can enrich continuation wording but should not override phase routing
+- when contextual delta notes conflict with current artifacts, ignore those notes for routing and call out the conflict
 - when design artifacts exist but `tasks.md` does not, continuation should usually target `tasks`, not `build`
 - when tasks already exist and the task checkpoint is healthy, continuation should usually target `build`
 
@@ -96,6 +99,8 @@ Then output:
 
 - detected workflow state
 - missing or weak artifacts
+- latest contextual deltas that are still consistent with current artifact truth, when available
+- stale or conflicting contextual deltas, when detected
 - one executable continuation prompt
 - one more conservative continuation prompt when useful
 

package/scripts/test-audit-context-delta.js

@@ -0,0 +1,446 @@
+const assert = require("assert/strict");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const { auditProject } = require("../lib/audit");
+
+const repo = path.resolve(__dirname, "..");
+const cli = path.join(repo, "bin", "da-vinci.js");
+const fixture = JSON.parse(
+  fs.readFileSync(path.join(__dirname, "fixtures", "complex-sample.pen"), "utf8")
+);
+const changeId = "redesign-001";
+
+function runTest(name, fn) {
+  try {
+    fn();
+    console.log(`PASS ${name}`);
+  } catch (error) {
+    console.error(`FAIL ${name}`);
+    throw error;
+  }
+}
+
+function assertFixtureShape() {
+  assert.equal(typeof fixture.version, "string", "fixture.version must be a string");
+  assert.ok(fixture.version.length > 0, "fixture.version must be non-empty");
+  assert.ok(Array.isArray(fixture.children), "fixture.children must be an array");
+  assert.ok(fixture.children.length > 0, "fixture.children must include at least one top-level node");
+  assert.equal(typeof fixture.variables, "object", "fixture.variables must be an object");
+  assert.ok(fixture.variables && Object.keys(fixture.variables).length > 0, "fixture.variables must be non-empty");
+}
+
+function createHarness() {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), "da-vinci-audit-context-"));
+  return {
+    base,
+    home: path.join(base, "home")
+  };
+}
+
+function runCli(harness, args) {
+  const [command, ...rest] = args;
+  const result = spawnSync(process.execPath, [cli, command, "--home", harness.home, ...rest], {
+    cwd: repo,
+    encoding: "utf8",
+    maxBuffer: 8 * 1024 * 1024
+  });
+
+  return {
+    code: result.status,
+    stdout: (result.stdout || "").trim(),
+    stderr: (result.stderr || "").trim()
+  };
+}
+
+function expectOk(step, result) {
+  assert.equal(result.code, 0, `${step} failed:\n${result.stderr || result.stdout}`);
+}
+
+function writeJson(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(payload, null, 2));
+}
+
+function writeText(filePath, text) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, text);
+}
+
+function setupProject(harness, name, pencilDesignBody) {
+  const root = path.join(harness.base, name);
+  const daVinciDir = path.join(root, ".da-vinci");
+  const changeDir = path.join(daVinciDir, "changes", changeId);
+  const penPath = path.join(daVinciDir, "designs", `${name}.pen`);
+  const nodesFile = path.join(root, `${name}-nodes.json`);
+  const variablesFile = path.join(root, `${name}-variables.json`);
+
+  writeText(path.join(root, "DA-VINCI.md"), "# DA-VINCI\n");
+  writeText(path.join(daVinciDir, "project-inventory.md"), "# Inventory\n");
+  writeText(path.join(daVinciDir, "page-map.md"), "# Page Map\n");
+  writeText(
+    path.join(daVinciDir, "design-registry.md"),
+    `# Registry\n- Preferred .pen: .da-vinci/designs/${name}.pen\n`
+  );
+  writeText(path.join(changeDir, "design-brief.md"), "# Brief\n");
+  writeText(path.join(changeDir, "design.md"), "# Design\n");
+  writeText(path.join(changeDir, "pencil-bindings.md"), "# Bindings\n");
+  writeText(path.join(changeDir, "pencil-design.md"), pencilDesignBody);
+
+  writeJson(nodesFile, { nodes: fixture.children });
+  writeJson(variablesFile, { variables: fixture.variables });
+
+  expectOk(
+    `${name} begin`,
+    runCli(harness, ["pencil-session", "begin", "--project", root, "--pen", penPath])
+  );
+  expectOk(
+    `${name} persist`,
+    runCli(harness, [
+      "pencil-session",
+      "persist",
+      "--project",
+      root,
+      "--pen",
+      penPath,
+      "--nodes-file",
+      nodesFile,
+      "--variables-file",
+      variablesFile,
+      "--version",
+      fixture.version
+    ])
+  );
+  expectOk(
+    `${name} end`,
+    runCli(harness, [
+      "pencil-session",
+      "end",
+      "--project",
+      root,
+      "--pen",
+      penPath,
+      "--nodes-file",
+      nodesFile,
+      "--variables-file",
+      variablesFile,
+      "--version",
+      fixture.version
+    ])
+  );
+
+  return {
+    root
+  };
+}
+
+assertFixtureShape();
+
+runTest("completion audit warns when checkpoint-bearing artifacts have no concrete context delta", () => {
+  const harness = createHarness();
+  const project = setupProject(
+    harness,
+    "missing-context-delta",
+    [
+      "# Pencil Design",
+      "",
+      "## MCP Runtime Gate",
+      "- Final runtime gate status: PASS",
+      "",
+      "## Checkpoint Status",
+      "- `design checkpoint`: PASS",
+      "- `completion gate`: PASS",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(result.status, "WARN");
+  assert.equal(result.failures.length, 0);
+  assert.match(result.warnings.join("\n"), /Context Delta/i);
+});
+
+runTest("completion audit treats Context Delta Required truthy values as expectation signals", () => {
+  const harness = createHarness();
+  const project = setupProject(
+    harness,
+    "context-delta-required-yes",
+    [
+      "# Pencil Design",
+      "",
+      "- `Context Delta Required`: yes",
+      "",
+      "## Notes",
+      "- Explicit opt-in without checkpoint headings.",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(result.status, "WARN");
+  assert.equal(result.failures.length, 0);
+  assert.match(result.warnings.join("\n"), /Context Delta/i);
+});
+
+runTest("completion audit warns for context-delta and checkpoint status mismatches", () => {
+  const harness = createHarness();
+  const project = setupProject(
+    harness,
+    "stale-context-delta",
+    [
+      "# Pencil Design",
+      "",
+      "## MCP Runtime Gate",
+      "- Final runtime gate status: PASS",
+      "",
+      "## Checkpoint Status",
+      "- `design checkpoint`: PASS",
+      "",
+      "## Context Delta",
+      "- time: 2026-03-28T10:00:00.000Z",
+      "- checkpoint_type: design checkpoint",
+      "- goal: stabilize anchors",
+      "- decision: continue to mapping",
+      "- constraints: preserve behavior truth",
+      "- impact: keeps design pipeline moving",
+      "- status: WARN",
+      "- next_action: run mapping checkpoint",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(result.status, "WARN");
+  assert.equal(result.failures.length, 0);
+  assert.match(result.warnings.join("\n"), /status mismatch/i);
+});
+
+runTest("completion audit passes when context-delta and checkpoint status are aligned", () => {
+  const harness = createHarness();
+  const project = setupProject(
+    harness,
+    "healthy-context-delta",
+    [
+      "# Pencil Design",
+      "",
+      "## MCP Runtime Gate",
+      "- Final runtime gate status: PASS",
+      "",
+      "## Checkpoint Status",
+      "- `design checkpoint`: PASS",
+      "",
+      "## Context Delta",
+      "- time: 2026-03-28T11:00:00.000Z",
+      "- checkpoint_type: design checkpoint",
+      "- goal: stabilize anchors",
+      "- decision: continue to mapping",
+      "- constraints: preserve behavior truth",
+      "- impact: keeps design pipeline moving",
+      "- status: PASS",
+      "- next_action: run mapping checkpoint",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(result.status, "PASS");
+  assert.equal(result.failures.length, 0);
+  assert.equal(result.warnings.length, 0);
+});
+
+runTest("completion audit ignores verification outcome-only artifacts for context-delta expectations", () => {
+  const harness = createHarness();
+  const project = setupProject(
+    harness,
+    "outcome-only-verification",
+    [
+      "# Pencil Design",
+      "",
+      "## Notes",
+      "- No checkpoint headings in this artifact.",
+      ""
+    ].join("\n")
+  );
+
+  writeText(
+    path.join(project.root, ".da-vinci", "changes", changeId, "verification.md"),
+    [
+      "# Verification",
+      "",
+      "## Outcome",
+      "- PASS",
+      "- Next action: none",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(result.status, "PASS");
+  assert.equal(result.failures.length, 0);
+  assert.equal(result.warnings.length, 0);
+});
+
+runTest("completion audit warns when supersedes references missing context-delta entries", () => {
+  const harness = createHarness();
+  const project = setupProject(
+    harness,
+    "invalid-supersedes",
+    [
+      "# Pencil Design",
+      "",
+      "## MCP Runtime Gate",
+      "- Final runtime gate status: PASS",
+      "",
+      "## Checkpoint Status",
+      "- `design checkpoint`: PASS",
+      "",
+      "## Context Delta",
+      "- time: 2026-03-28T12:00:00.000Z",
+      "- checkpoint_type: design checkpoint",
+      "- goal: stabilize anchors",
+      "- decision: finish current anchor pass",
+      "- constraints: preserve behavior truth",
+      "- impact: keeps mapping handoff stable",
+      "- status: PASS",
+      "- next_action: prepare mapping checkpoint",
+      "",
+      "- time: 2026-03-28T13:00:00.000Z",
+      "- checkpoint_type: design checkpoint",
+      "- goal: finalize status consistency",
+      "- decision: retain PASS and continue",
+      "- constraints: keep traceability",
+      "- impact: no gating change",
+      "- status: PASS",
+      "- supersedes: 2026-03-28T09:00:00.000Z",
+      "- next_action: close design phase",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(result.status, "WARN");
+  assert.equal(result.failures.length, 0);
+  assert.match(result.warnings.join("\n"), /supersed/i);
+});
+
+runTest("completion audit accepts valid supersedes references to earlier context-delta entries", () => {
+  const harness = createHarness();
+  const project = setupProject(
+    harness,
+    "valid-supersedes",
+    [
+      "# Pencil Design",
+      "",
+      "## MCP Runtime Gate",
+      "- Final runtime gate status: PASS",
+      "",
+      "## Checkpoint Status",
+      "- `design checkpoint`: PASS",
+      "",
+      "## Context Delta",
+      "- time: 2026-03-28T12:00:00.000Z",
+      "- checkpoint_type: design checkpoint",
+      "- goal: stabilize anchors",
+      "- decision: finish current anchor pass",
+      "- constraints: preserve behavior truth",
+      "- impact: keeps mapping handoff stable",
+      "- status: PASS",
+      "- next_action: prepare mapping checkpoint",
+      "",
+      "- time: 2026-03-28T13:00:00.000Z",
+      "- checkpoint_type: design checkpoint",
+      "- goal: finalize status consistency",
+      "- decision: retain PASS and continue",
+      "- constraints: keep traceability",
+      "- impact: no gating change",
+      "- status: PASS",
+      "- supersedes: 2026-03-28T12:00:00.000Z",
+      "- next_action: close design phase",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(result.status, "PASS");
+  assert.equal(result.failures.length, 0);
+  assert.equal(result.warnings.length, 0);
+});
+
+runTest("completion audit accepts supersedes when timestamp formats differ but normalize to same time", () => {
+  const harness = createHarness();
+  const project = setupProject(
+    harness,
+    "normalized-time-supersedes",
+    [
+      "# Pencil Design",
+      "",
+      "## MCP Runtime Gate",
+      "- Final runtime gate status: PASS",
+      "",
+      "## Checkpoint Status",
+      "- `design checkpoint`: PASS",
+      "",
+      "## Context Delta",
+      "- time: 2026-03-28T12:00:00.000Z",
+      "- checkpoint_type: design checkpoint",
+      "- goal: stabilize anchors",
+      "- decision: pass design checkpoint",
+      "- constraints: preserve behavior truth",
+      "- impact: ready for mapping",
+      "- status: PASS",
+      "- next_action: run mapping checkpoint",
+      "",
+      "- time: 2026-03-28T13:00:00.000Z",
+      "- checkpoint_type: design checkpoint",
+      "- goal: retain continuity",
+      "- decision: keep status stable",
+      "- constraints: no regressions",
+      "- impact: no gate changes",
+      "- status: PASS",
+      "- supersedes: design checkpoint@2026-03-28 12:00:00Z",
+      "- next_action: continue implementation prep",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(result.status, "PASS");
+  assert.equal(result.failures.length, 0);
+  assert.equal(result.warnings.length, 0);
+});
+
+console.log("All audit context-delta tests passed.");

package/scripts/test-mode-consistency.js

@@ -286,4 +286,54 @@ runTest("design-supervisor review stays distinct from preferred adapters and is
   }
 });
 
+runTest("build prompts require completion audit and do not treat compile success as workflow completion", () => {
+  const buildPrompts = [
+    "commands/claude/dv/build.md",
+    "commands/codex/prompts/dv-build.md",
+    "commands/gemini/dv/build.toml"
+  ];
+
+  for (const file of buildPrompts) {
+    const content = read(file);
+    assert.match(content, /BUILD SUCCESSFUL/, `${file} should explicitly treat build success as compile-only evidence`);
+    assert.match(
+      content,
+      /da-vinci audit --mode completion --change <change-id> <project-path>/,
+      `${file} should require completion audit before terminal completion claims`
+    );
+    assert.match(
+      content,
+      /do not report `design complete` or `workflow complete`/i,
+      `${file} should prevent terminal completion claims while in-scope tasks remain`
+    );
+  }
+});
+
+runTest("continue prompts keep build routing blocked while design gates are unresolved", () => {
+  const continuePrompts = [
+    "commands/claude/dv/continue.md",
+    "commands/codex/prompts/dv-continue.md",
+    "commands/gemini/dv/continue.toml"
+  ];
+
+  for (const file of continuePrompts) {
+    const content = read(file);
+    assert.match(
+      content,
+      /missing shell-visible project-local `.pen`/,
+      `${file} should block build routing when project-local .pen persistence is unresolved`
+    );
+    assert.match(
+      content,
+      /active\/unclosed Pencil session/,
+      `${file} should block build routing when Pencil session is still active`
+    );
+    assert.match(
+      content,
+      /design-supervisor review still BLOCK\/unaccepted/,
+      `${file} should block build routing when required design-supervisor review has not cleared`
+    );
+  }
+});
+
 console.log("All mode consistency tests passed.");

package/scripts/test-pencil-session.js

@@ -149,4 +149,44 @@ runTest("pencil-session end fails when live payload is stale", () => {
   });
 });
 
+runTest("pencil-session end requires live payload unless force is used", () => {
+  const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+  const tempDir = createTempDir();
+  const projectRoot = path.join(tempDir, "project");
+  const homeDir = path.join(tempDir, "home");
+  const penPath = path.join(projectRoot, ".da-vinci", "designs", "cipher.pen");
+  const { nodesFile, variablesFile } = writePayloadFiles(tempDir, fixture);
+
+  beginPencilSession({
+    projectPath: projectRoot,
+    penPath,
+    homeDir
+  });
+  persistPencilSession({
+    projectPath: projectRoot,
+    penPath,
+    nodesFile,
+    variablesFile,
+    version: fixture.version,
+    homeDir
+  });
+
+  assert.throws(
+    () =>
+      endPencilSession({
+        projectPath: projectRoot,
+        penPath,
+        homeDir
+      }),
+    /without a live MCP snapshot/i
+  );
+
+  endPencilSession({
+    projectPath: projectRoot,
+    penPath,
+    homeDir,
+    force: true
+  });
+});
+
 console.log("All Pencil session tests passed.");