@deftai/directive-runtime 0.129.3 → 0.129.5

package/tasks/materialize.cjs

@@ -16,12 +16,70 @@ const path = require("node:path");
 const PIN_PKG = path.join("node_modules", "@deftai", "directive-runtime");
 const LOCK_REL = path.join(".deft-scratch", "materialize-runtime.lock");
 const OVERLAY_REL = path.join(".deft-scratch", "materialize-runtime-overlay.json");
+/** Release cut-context marker (#5910). Active from release entry through bump/tag. */
+const CUT_CONTEXT_REL = path.join(".deft-scratch", "release-cut-context.json");
+const CUT_CONTEXT_SCHEMA = "deft.release.cut-context.v1";
 
 function fail(msg, code = 2) {
   console.error(`materialize:runtime: ${msg}`);
   process.exit(code);
 }
 
+function isCutContextActive(projectRoot) {
+  return fs.existsSync(path.join(projectRoot, CUT_CONTEXT_REL));
+}
+
+/**
+ * Named cut-context producer for the release cut worktree (#5910 P1).
+ * Write at release entry; clear after version bump/tag. While active,
+ * materialize:runtime refuses before it moves or replaces the pin.
+ * Shares the materialize lock so cut entry cannot race an in-flight replace.
+ */
+function writeReleaseCutContext(projectRoot, meta = {}) {
+  const root = path.resolve(projectRoot);
+  const dest = path.join(root, CUT_CONTEXT_REL);
+  const lockPath = acquireLock(root);
+  try {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const body = {
+      schema: CUT_CONTEXT_SCHEMA,
+      writtenAt: new Date().toISOString(),
+      projectRoot: root,
+      phase: meta.phase || "release-entry",
+      note:
+        meta.note ||
+        "Release cut-context active through version bump/tag; task materialize:runtime refuses pin replace (#5910).",
+    };
+    fs.writeFileSync(dest, `${JSON.stringify(body, null, 2)}\n`);
+    return body;
+  } finally {
+    releaseLock(lockPath);
+  }
+}
+
+function clearReleaseCutContext(projectRoot) {
+  const dest = path.join(path.resolve(projectRoot), CUT_CONTEXT_REL);
+  try {
+    fs.unlinkSync(dest);
+    return true;
+  } catch (err) {
+    if (err && err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
+/** Retire the materialize overlay after exact restore (#5910 P2/P4). */
+function retireMaterializeOverlay(projectRoot) {
+  const dest = path.join(path.resolve(projectRoot), OVERLAY_REL);
+  try {
+    fs.unlinkSync(dest);
+    return true;
+  } catch (err) {
+    if (err && err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
 function runNode(script, args, opts = {}) {
   const r = spawnSync(process.execPath, [script, ...args], {
     cwd: opts.cwd,
@@ -121,15 +179,14 @@ function materialize(projectRoot, opts = {}) {
   const root = path.resolve(projectRoot);
   const stageScript = path.join(root, "packages", "runtime", "scripts", "stage-bundle.mjs");
   const packScript = path.join(root, "packages", "runtime", "scripts", "pack-staged-runtime.mjs");
-  if (!fs.existsSync(stageScript) || !fs.existsSync(packScript)) {
-    throw new Error("stage-bundle/pack-staged-runtime scripts missing; run from framework-source checkout");
-  }
 
   const pinDir = path.join(root, PIN_PKG);
   if (fs.existsSync(pinDir) && !isCheckoutOwnedDir(pinDir, root)) {
     throw new Error(`refusing to mutate linked/shared pin at ${pinDir}`);
   }
 
+  // Hold the same lock as cut entry; check cut-context under the lock so a
+  // mid-flight cut cannot outlive an unlocked pre-check (#5910 Greptile P1).
   const lockPath = acquireLock(root);
   const priorPinUsable = fs.existsSync(path.join(pinDir, "dist", "bin.js"));
   let priorBackup = null;
@@ -137,6 +194,14 @@ function materialize(projectRoot, opts = {}) {
   let packDir;
   let extractDir;
   try {
+    if (isCutContextActive(root)) {
+      throw new Error(
+        `refusing materialize:runtime while release cut-context is active (${CUT_CONTEXT_REL}); keep the published pin through version bump/tag (#5910)`,
+      );
+    }
+    if (!fs.existsSync(stageScript) || !fs.existsSync(packScript)) {
+      throw new Error("stage-bundle/pack-staged-runtime scripts missing; run from framework-source checkout");
+    }
     stageDir = fs.mkdtempSync(path.join(os.tmpdir(), "deft-materialize-stage-"));
     packDir = fs.mkdtempSync(path.join(os.tmpdir(), "deft-materialize-pack-"));
     runNode(stageScript, [stageDir], { cwd: root });
@@ -156,6 +221,13 @@ function materialize(projectRoot, opts = {}) {
     if (entries.length !== 1) throw new Error(`expected one package folder in tgz, got ${entries.join(",")}`);
     const extracted = path.join(extractDir, entries[0]);
 
+    // Final cut-context check under lock immediately before pin move/replace.
+    if (isCutContextActive(root)) {
+      throw new Error(
+        `refusing materialize:runtime while release cut-context is active (${CUT_CONTEXT_REL}); keep the published pin through version bump/tag (#5910)`,
+      );
+    }
+
     const parent = path.dirname(pinDir);
     fs.mkdirSync(parent, { recursive: true });
     const stagingPin = path.join(parent, `.directive-runtime-next-${process.pid}`);
@@ -226,9 +298,33 @@ function materialize(projectRoot, opts = {}) {
 }
 
 if (require.main === module) {
-  const root = process.argv[2] || process.cwd();
+  const argv = process.argv.slice(2);
+  const flag = argv[0];
   try {
-    materialize(root);
+    if (flag === "--write-cut-context") {
+      const target = argv[1] || process.cwd();
+      const body = writeReleaseCutContext(target);
+      process.stdout.write(
+        `materialize:runtime: cut-context written ${path.join(path.resolve(target), CUT_CONTEXT_REL)}\n`,
+      );
+      process.stdout.write(`${JSON.stringify(body)}\n`);
+    } else if (flag === "--clear-cut-context") {
+      const cleared = clearReleaseCutContext(argv[1] || process.cwd());
+      process.stdout.write(
+        cleared
+          ? `materialize:runtime: cut-context cleared\n`
+          : `materialize:runtime: cut-context absent\n`,
+      );
+    } else if (flag === "--retire-overlay") {
+      const retired = retireMaterializeOverlay(argv[1] || process.cwd());
+      process.stdout.write(
+        retired
+          ? `materialize:runtime: overlay retired\n`
+          : `materialize:runtime: overlay absent\n`,
+      );
+    } else {
+      materialize(flag || process.cwd());
+    }
   } catch (err) {
     fail(err && err.message ? err.message : String(err), err && err.code ? Number(err.code) || 2 : 2);
   }
@@ -240,7 +336,12 @@ module.exports = {
   releaseLock,
   isCheckoutOwnedDir,
   movePath,
+  isCutContextActive,
+  writeReleaseCutContext,
+  clearReleaseCutContext,
+  retireMaterializeOverlay,
   PIN_PKG,
   LOCK_REL,
   OVERLAY_REL,
+  CUT_CONTEXT_REL,
 };

package/tasks/materialize.test.cjs

@@ -20,7 +20,14 @@ const {
   isCheckoutOwnedDir,
   movePath,
   materialize,
+  writeReleaseCutContext,
+  clearReleaseCutContext,
+  isCutContextActive,
+  retireMaterializeOverlay,
   LOCK_REL,
+  OVERLAY_REL,
+  CUT_CONTEXT_REL,
+  PIN_PKG,
 } = require("./materialize.cjs");
 
 const roots = [];
@@ -101,3 +108,104 @@ describe("materialize isolation (#5805 P4)", () => {
     releaseLock(lock);
   });
 });
+
+describe("release cut-context refuse (#5910 P1/P4)", () => {
+  function seedPublishedPin(root, version = "0.129.0") {
+    const pinDir = join(root, PIN_PKG);
+    mkdirSync(join(pinDir, "dist"), { recursive: true });
+    writeFileSync(
+      join(pinDir, "package.json"),
+      `${JSON.stringify({ name: "@deftai/directive-runtime", version }, null, 2)}\n`,
+    );
+    writeFileSync(join(pinDir, "dist", "bin.js"), "console.log('pin');\n");
+    writeFileSync(
+      join(root, "package.json"),
+      `${JSON.stringify(
+        { private: true, devDependencies: { "@deftai/directive-runtime": version } },
+        null,
+        2,
+      )}\n`,
+    );
+    return pinDir;
+  }
+
+  it("cut-context producer writes marker; materialize refuses before replace with prior pin intact", () => {
+    const root = tempRoot();
+    const pinDir = seedPublishedPin(root);
+    const priorPkg = readFileSync(join(pinDir, "package.json"), "utf8");
+    const body = writeReleaseCutContext(root, { phase: "release-entry" });
+    assert.equal(body.schema, "deft.release.cut-context.v1");
+    assert.equal(isCutContextActive(root), true);
+    assert.ok(existsSync(join(root, CUT_CONTEXT_REL)));
+
+    assert.throws(
+      () => materialize(root),
+      /refusing materialize:runtime while release cut-context is active|cut-context/i,
+    );
+    // Prior pin untouched — refuse happened before move/replace.
+    assert.equal(readFileSync(join(pinDir, "package.json"), "utf8"), priorPkg);
+    assert.equal(JSON.parse(priorPkg).version, "0.129.0");
+    assert.equal(existsSync(join(root, LOCK_REL)), false);
+    assert.equal(existsSync(join(root, OVERLAY_REL)), false);
+  });
+
+  it("cut entry shares the materialize lock (refuses while materialize holds it)", () => {
+    const root = tempRoot();
+    seedPublishedPin(root);
+    const lock = acquireLock(root);
+    assert.throws(
+      () => writeReleaseCutContext(root, { phase: "release-entry" }),
+      /another materialize|second writer|EEXIST|in progress/i,
+    );
+    assert.equal(isCutContextActive(root), false);
+    releaseLock(lock);
+    const body = writeReleaseCutContext(root, { phase: "release-entry" });
+    assert.equal(body.schema, "deft.release.cut-context.v1");
+    assert.equal(existsSync(join(root, LOCK_REL)), false);
+  });
+
+  it("without cut-context, missing stage scripts still fail after the cut guard", () => {
+    const root = tempRoot();
+    seedPublishedPin(root);
+    assert.equal(isCutContextActive(root), false);
+    assert.throws(() => materialize(root), /stage-bundle|pack-staged|missing/i);
+  });
+
+  it("clearReleaseCutContext retires the marker so materialize can proceed past the cut guard", () => {
+    const root = tempRoot();
+    seedPublishedPin(root);
+    writeReleaseCutContext(root);
+    assert.equal(clearReleaseCutContext(root), true);
+    assert.equal(isCutContextActive(root), false);
+    assert.throws(() => materialize(root), /stage-bundle|pack-staged|missing/i);
+  });
+
+  it("retireMaterializeOverlay removes the overlay marker after restore", () => {
+    const root = tempRoot();
+    mkdirSync(join(root, ".deft-scratch"), { recursive: true });
+    writeFileSync(join(root, OVERLAY_REL), `${JSON.stringify({ schema: "overlay" })}\n`);
+    assert.equal(retireMaterializeOverlay(root), true);
+    assert.equal(existsSync(join(root, OVERLAY_REL)), false);
+    assert.equal(retireMaterializeOverlay(root), false);
+  });
+
+  it("cut-context keeps published pin intact (bump-gate preconditions; not a full release run)", () => {
+    // Narrow pin-preservation proof (#5910 P4 / Greptile P2): cut-context at entry,
+    // materialize refuses, published pin + pin declaration stay aligned, no overlay.
+    // Full release-to-bump coverage stays on task release:e2e / release skill path.
+    const root = tempRoot();
+    const pinDir = seedPublishedPin(root, "0.129.0");
+    writeReleaseCutContext(root, { phase: "release-entry" });
+
+    assert.throws(() => materialize(root), /cut-context/i);
+    const installed = JSON.parse(readFileSync(join(pinDir, "package.json"), "utf8"));
+    assert.equal(installed.version, "0.129.0");
+    assert.equal(existsSync(join(root, OVERLAY_REL)), false);
+
+    // Version-bump gate preconditions only (not an executed bump).
+    const rootPkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    assert.equal(rootPkg.devDependencies["@deftai/directive-runtime"], "0.129.0");
+    assert.equal(installed.version, rootPkg.devDependencies["@deftai/directive-runtime"]);
+    assert.equal(isCutContextActive(root), true);
+  });
+});

package/tasks/materialize.yml

@@ -5,9 +5,21 @@ vars:
 
 tasks:
   runtime:
-    desc: "Build tip staged-runtime and replace this checkout node_modules/@deftai/directive-runtime only (#5805). No lockfile/location-spec mutation."
+    desc: "Build tip staged-runtime and replace this checkout node_modules/@deftai/directive-runtime only (#5805). No lockfile/location-spec mutation. Refuses while release cut-context is active (#5910)."
     dir: "{{.USER_WORKING_DIR}}"
     deps:
       - task: :engine:_ts-build
     cmds:
-      - node "{{.TASKFILE_DIR}}/materialize.cjs" "{{.USER_WORKING_DIR}}"
+      - node "{{.TASKFILE_DIR}}/materialize.cjs" "{{.USER_WORKING_DIR}}"
+
+  cut-context:
+    desc: "Write release cut-context marker (#5910). materialize:runtime refuses pin replace while active (entry through version bump/tag)."
+    dir: "{{.USER_WORKING_DIR}}"
+    cmds:
+      - node "{{.TASKFILE_DIR}}/materialize.cjs" --write-cut-context "{{.USER_WORKING_DIR}}"
+
+  clear-cut-context:
+    desc: "Clear release cut-context marker after version bump/tag (#5910)."
+    dir: "{{.USER_WORKING_DIR}}"
+    cmds:
+      - node "{{.TASKFILE_DIR}}/materialize.cjs" --clear-cut-context "{{.USER_WORKING_DIR}}"

package/templates/agents-entry.md

@@ -88,7 +88,7 @@ Deft runtime is pinned as `@deftai/directive-runtime`. Full guidelines: node_mod
 ! **Dual stop (#2442):** multi-iteration work MUST have success + failure/budget stop (max iters / no-progress / budget); single-turn exempt; halt with operator-visible report; ⊗ thrash. Defaults: build, swarm, review-cycle skills. See main.md Dual Stop Rule. Ledger #3143.
 ## Rule Authority [AXIOM]
 ! Prefer `task deft:*` over AGENTS.md prose. See main.md.
-! Merge chokepoint (#4379 / #2893): prefer `deft check`; else `task deft:check` on include-only consumers. One gate, not two runs.
+! Merge chokepoint (#4379 / #2893 / #6040): when the full gate runs (conflict-resolve / behind-rebase locally, or CI merge-gate (`check:merge`)), prefer `deft check`; else `task deft:check` on include-only consumers. Ordinary pre-PR is RWDL + `verify:ac` and does not require that full gate. One gate, not two runs.
 ## Thin Fail-Closed Design (#3265)
 ! One fail-closed `task deft:*` check + one remediation. See main.md.
 ## Writing bar (#3368)

package/vendor/directive-content/Taskfile.yml

@@ -419,7 +419,7 @@ tasks:
           ENGINE_CMD: 'check --framework-root "{{.TASKFILE_DIR}}" --project-root "{{.USER_WORKING_DIR}}"'
 
   test:coverage:
-    desc: "Run tests with coverage (alias for ts:test; canonical coverage path used by task check, #2528)"
+    desc: "On-demand tests with coverage (alias for ts:test). Merge path is coverage-free (#6041); release Step 5 and this task are the host coverage runs."
     cmds:
       - task: ts:test
 

package/vendor/directive-content/docs/scope-provenance.md

@@ -73,6 +73,10 @@ When an active implementation brief is **outside** the change set, membership is
 
 Membership-land (Path B activation) PRs that only touch nonterminal `xbrief|vbrief` under `proposed|pending|active` plus optional root `CHANGELOG.md` leave `metadata.productPullRequest` **unset**. Closing-keywords admits that brief-land shape when body has `deft-story: N` covering each changed nonterminal (`isBriefLandShapedDiff` + early return in `evaluateFullStoryMarkAdmission`). Optional `metadata.activationPullRequest` is provenance only — delivery readers ignore it. The stacked product PR stamps virgin `productPullRequest` on the existing null path; leftover keeps the original product stamp. ⊗ Write the activation PR number into `productPullRequest`. Legacy stamped activations unstamp once, then product stamps. Depth: `packages/core/src/pr-closing-keywords/main.ts`.
 
+### Path B activation vs product `verify:ac` (#5792)
+
+Scope-only Path B activation must be able to clear `deft check` before merge-base write authority exists. Check inventories the complete local change set (merge-base..HEAD ∪ dirty ∪ cached ∪ untracked, with rename origins) into `PrDiffPath`, then reuses the Path B witness (`evaluatePathBActivationAdmit`). Inventory base prefers typed `plan.policy.deliveryBranch` / remote default before `master`|`main`, and git-toplevel paths are remapped to `projectRoot` so nested consumers keep brief-land shape. When the inventory is brief-land shaped and the witness admits, check records one named disposition `path_b_activation_deferred` and **defers** product acceptance commands and artifact-clause execution — it does not selectively forgive opaque npm failures and does not bank as a later product verified-pass. Local check without a PR body uses inventory brief issue-ref identity instead of `deft-story` marks; when a PR body is present, mark coverage still applies. Any product path in the inventory, or `productPullRequest` set, restores full `verify:ac`. Write authority stays merge-base-only (`loadStoryWriteFenceFromMergeBase` unchanged). Depth: `packages/core/src/verify-ac/evaluate.ts`, `packages/core/src/check/cached-orchestrator.ts`.
+
 
 ## Historical ship-closeout for stale merged actives (#5403)