@deftai/directive-content 0.81.0 → 0.83.0

package/tasks/engine-pm-run.test.cjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { describe, it } = require("node:test");
+const {
+  buildDispatchSteps,
+  executeAllowlisted,
+  hasCmd,
+  parsePnpmPin,
+  runPackageScript,
+  validateScriptName,
+} = require("./engine-pm-run.cjs");
+
+describe("parsePnpmPin", () => {
+  it("accepts stable, prerelease, and build-metadata pins", () => {
+    for (const pin of ["pnpm@11.8.0", "pnpm@1.0.0-alpha.1", "pnpm@1.0.0+build.1"]) {
+      const result = parsePnpmPin(pin);
+      assert.equal(result.ok, true);
+    }
+  });
+
+  it("accepts missing/empty pins for unpinned fallback", () => {
+    assert.deepEqual(parsePnpmPin(undefined), { ok: true, semver: null, pin: null });
+    assert.deepEqual(parsePnpmPin(""), { ok: true, semver: null, pin: null });
+  });
+
+  it("rejects shell metacharacters and malformed pins before spawn", () => {
+    for (const pin of [
+      "pnpm@9.0.0; echo pwned",
+      "pnpm@9.0.0 & echo pwned",
+      "pnpm@^1.0.0",
+      "npm@1.0.0",
+      "pnpm@1.0.0 extra",
+      " pnpm@1.0.0",
+      "pnpm@1.0.0 ",
+      "pnpm@1.0.0\n",
+    ]) {
+      const result = parsePnpmPin(pin);
+      assert.equal(result.ok, false, pin);
+    }
+  });
+});
+
+describe("validateScriptName", () => {
+  it("accepts only declared script keys with safe names", () => {
+    const scripts = { build: "tsc", "test:unit": "vitest" };
+    assert.equal(validateScriptName("build", scripts), true);
+    assert.equal(validateScriptName("test:unit", scripts), true);
+    assert.equal(validateScriptName("missing", scripts), false);
+    assert.equal(validateScriptName("build;rm", scripts), false);
+  });
+});
+
+describe("buildDispatchSteps", () => {
+  it("preserves installed pnpm -> pinned corepack -> unpinned corepack order", () => {
+    const steps = buildDispatchSteps({
+      hasPnpm: true,
+      hasCorepack: true,
+      semver: "11.8.0",
+      script: "build",
+    });
+    assert.deepEqual(steps, [
+      { cmd: "pnpm", args: ["run", "build"] },
+      { cmd: "corepack", args: ["pnpm@11.8.0", "run", "build"] },
+      { cmd: "corepack", args: ["pnpm", "run", "build"] },
+    ]);
+  });
+});
+
+describe("runPackageScript security", () => {
+  function mkFixture(/** @type {Record<string, unknown>} */ pkgExtra) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "deft-engine-pm-run-"));
+    fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify(pkgExtra, null, 2), "utf8");
+    return dir;
+  }
+
+  it("rejects malicious pins before any execution call", () => {
+    const dir = mkFixture({
+      packageManager: "pnpm@9.0.0; echo pwned",
+      scripts: { build: "node -e \"\"" },
+    });
+    const sentinel = path.join(dir, "sentinel.txt");
+    let execCalls = 0;
+    const code = runPackageScript(dir, "build", {
+      execFileSync() {
+        execCalls += 1;
+        fs.writeFileSync(sentinel, "pwned", "utf8");
+      },
+    });
+    assert.equal(code, 3);
+    assert.equal(execCalls, 0);
+    assert.equal(fs.existsSync(sentinel), false);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("records exact argv on execution without shell:true", () => {
+    const dir = mkFixture({
+      packageManager: "pnpm@11.8.0",
+      scripts: { build: "tsc" },
+    });
+    /** @type {Array<{ cmd: string, args: string[], shell?: boolean, stdio?: string }>} */
+    const calls = [];
+    const code = runPackageScript(dir, "build", {
+      execFileSync(cmd, args, opts) {
+        calls.push({ cmd, args: [...args], shell: opts?.shell, stdio: opts?.stdio });
+        if (opts?.stdio === "inherit") {
+          return;
+        }
+      },
+    });
+    assert.equal(code, 0);
+    const execCalls = calls.filter((c) => c.stdio === "inherit");
+    assert.equal(execCalls.length, 1);
+    assert.equal(execCalls[0].shell, false);
+    assert.equal(execCalls[0].stdio, "inherit");
+    if (process.platform === "win32") {
+      assert.equal(execCalls[0].cmd, "cmd.exe");
+      assert.deepEqual(execCalls[0].args.slice(0, 3), ["/d", "/s", "/c"]);
+      assert.match(execCalls[0].args[3], /pnpm.*run.*build/);
+    } else {
+      assert.deepEqual(execCalls[0], {
+        cmd: "pnpm",
+        args: ["run", "build"],
+        shell: false,
+        stdio: "inherit",
+      });
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("allows probe hasCmd to use shell:true separately from execution", () => {
+    /** @type {Array<{ shell?: boolean, stdio?: string }>} */
+    const calls = [];
+    let probeAttempts = 0;
+    const execFn = (/** @type {string} */ _cmd, /** @type {string[]} */ _args, /** @type {{ shell?: boolean, stdio?: string }} */ opts) => {
+      if (opts?.stdio === "ignore") {
+        probeAttempts += 1;
+        if (probeAttempts === 1 && !opts.shell) {
+          throw new Error("probe without shell failed");
+        }
+      }
+      calls.push({ shell: opts?.shell, stdio: opts?.stdio });
+    };
+    assert.equal(hasCmd(execFn, "pnpm"), true);
+    assert.ok(calls.some((c) => c.shell === true && c.stdio === "ignore"));
+    const execCalls = calls.filter((c) => c.stdio === "inherit");
+    assert.equal(execCalls.length, 0);
+  });
+
+  it("rejects invalid package.json before probing PATH", () => {
+    const dir = mkFixture({ packageManager: "pnpm@11.8.0", scripts: { build: "tsc" } });
+    fs.writeFileSync(path.join(dir, "package.json"), "null", "utf8");
+    let execCalls = 0;
+    const code = runPackageScript(dir, "build", {
+      execFileSync() {
+        execCalls += 1;
+      },
+    });
+    assert.equal(code, 2);
+    assert.equal(execCalls, 0);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("rejects unknown scripts before probing PATH", () => {
+    const dir = mkFixture({ packageManager: "pnpm@11.8.0", scripts: { build: "tsc" } });
+    let execCalls = 0;
+    const code = runPackageScript(dir, "lint", {
+      execFileSync() {
+        execCalls += 1;
+      },
+    });
+    assert.equal(code, 2);
+    assert.equal(execCalls, 0);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("uses cmd.exe on win32 without shell:true on the Node spawn", () => {
+    if (process.platform !== "win32") {
+      return;
+    }
+    /** @type {{ cmd?: string, args?: string[], shell?: boolean } | null} */
+    let recorded = null;
+    executeAllowlisted(
+      (cmd, args, opts) => {
+        recorded = { cmd, args: [...args], shell: opts?.shell };
+      },
+      "pnpm",
+      ["run", "build"],
+      { cwd: process.cwd() },
+    );
+    assert.ok(recorded);
+    assert.equal(recorded.cmd, "cmd.exe");
+    assert.equal(recorded.args[0], "/d");
+    assert.equal(recorded.shell, false);
+    assert.match(recorded.args[3], /^pnpm run build$|^"pnpm" "run" "build"$/);
+  });
+});

package/tasks/engine.yml

@@ -20,71 +20,7 @@ tasks:
     cmds:
       - |
         set -eu
-        node -e "
-          const {execFileSync}=require('child_process');
-          const fs=require('fs');
-          const root=process.argv[1];
-          const script=process.argv[2];
-          const pkgPath=root+'/package.json';
-          if(!fs.existsSync(pkgPath)){
-            console.error('deft: package.json missing at '+root);
-            process.exit(2);
-          }
-          const pkg=JSON.parse(fs.readFileSync(pkgPath,'utf8'));
-          // Cross-platform probe (#2415): do NOT use Unix `sh -c 'command -v'` —
-          // Windows native Task often has no `sh` on PATH, so Corepack.cmd was
-          // invisible after #2411. Prefer a direct spawn (POSIX / real binaries);
-          // fall back to shell:true so PATHEXT resolves .cmd/.exe on win32.
-          // windowsHide (#2563): CREATE_NO_WINDOW so Cursor Task shells do not
-          // flood visible cmd.exe/conhost windows on every probe/build.
-          const spawnOpts=(extra)=>({stdio:'ignore',windowsHide:true,...extra});
-          const hasCmd=(name)=>{
-            try{
-              execFileSync(name,['--version'],spawnOpts());
-              return true;
-            }catch{
-              try{
-                execFileSync(name,['--version'],spawnOpts({shell:true}));
-                return true;
-              }catch{
-                return false;
-              }
-            }
-          };
-          const run=(cmd,args)=>{
-            execFileSync(cmd,args,{cwd:root,stdio:'inherit',shell:true,windowsHide:true});
-          };
-          const trySteps=(steps)=>{
-            for(const [cmd,args] of steps){
-              try{
-                run(cmd,args);
-                process.exit(0);
-              }catch{
-                // fall through to Corepack / next resolver
-              }
-            }
-          };
-          const envPm=String(process.env.DEFT_PACKAGE_MANAGER||'').trim().toLowerCase();
-          if(envPm==='npm'){
-            run('npm',['run',script]);
-            process.exit(0);
-          }
-          const pin=String(pkg.packageManager||'').trim();
-          const match=pin.match(/^pnpm@(.+)$/);
-          const steps=[];
-          if(hasCmd('pnpm')) steps.push(['pnpm',['run',script]]);
-          if(hasCmd('corepack')&&match) steps.push(['corepack',['pnpm@'+match[1],'run',script]]);
-          if(hasCmd('corepack')) steps.push(['corepack',['pnpm','run',script]]);
-          trySteps(steps);
-          console.error('deft: neither pnpm nor corepack is available to run \"'+script+'\".');
-          if(pin){
-            console.error('  Enable Corepack for the pinned manager: corepack enable && corepack prepare '+pin+' --activate');
-          }else{
-            console.error('  Install pnpm or enable Corepack (see package.json#packageManager).');
-          }
-          console.error('  Or set DEFT_PACKAGE_MANAGER=npm for an explicit npm build path.');
-          process.exit(127);
-        " "{{.DEFT_ROOT}}" "{{.PM_SCRIPT}}"
+        node "{{.TASKFILE_DIR}}/engine-pm-run.cjs" "{{.DEFT_ROOT}}" "{{.PM_SCRIPT}}"
 
   _ts-build:
     internal: true
@@ -115,76 +51,7 @@ tasks:
           if node "{{.TASKFILE_DIR}}/ts-build-fresh.cjs" "{{.DEFT_ROOT}}"; then
             exit 0
           fi
-          node -e "
-            const {execFileSync}=require('child_process');
-            const fs=require('fs');
-            const root=process.argv[1];
-            const script='build';
-            const pkgPath=root+'/package.json';
-            const pkg=JSON.parse(fs.readFileSync(pkgPath,'utf8'));
-            // Cross-platform probe (#2415): do NOT use Unix `sh -c 'command -v'` —
-            // Windows native Task often has no `sh` on PATH, so Corepack.cmd was
-            // invisible after #2411. Prefer a direct spawn (POSIX / real binaries);
-            // fall back to shell:true so PATHEXT resolves .cmd/.exe on win32.
-            // windowsHide (#2563): CREATE_NO_WINDOW so Cursor Task shells do not
-            // flood visible cmd.exe/conhost windows on every probe/build.
-            const spawnOpts=(extra)=>({stdio:'ignore',windowsHide:true,...extra});
-            const hasCmd=(name)=>{
-              try{
-                execFileSync(name,['--version'],spawnOpts());
-                return true;
-              }catch{
-                try{
-                  execFileSync(name,['--version'],spawnOpts({shell:true}));
-                  return true;
-                }catch{
-                  return false;
-                }
-              }
-            };
-            const run=(cmd,args)=>{
-              execFileSync(cmd,args,{cwd:root,stdio:'inherit',shell:true,windowsHide:true});
-            };
-            const markWarm=()=>{
-              try{
-                const dist=root+'/packages/cli/dist';
-                fs.mkdirSync(dist,{recursive:true});
-                fs.writeFileSync(dist+'/.deft-ts-build-stamp',new Date().toISOString());
-              }catch{}
-            };
-            const trySteps=(steps)=>{
-              for(const [cmd,args] of steps){
-                try{
-                  run(cmd,args);
-                  markWarm();
-                  process.exit(0);
-                }catch{
-                  // fall through to Corepack / next resolver
-                }
-              }
-            };
-            const envPm=String(process.env.DEFT_PACKAGE_MANAGER||'').trim().toLowerCase();
-            if(envPm==='npm'){
-              run('npm',['run',script]);
-              markWarm();
-              process.exit(0);
-            }
-            const pin=String(pkg.packageManager||'').trim();
-            const match=pin.match(/^pnpm@(.+)$/);
-            const steps=[];
-            if(hasCmd('pnpm')) steps.push(['pnpm',['run',script]]);
-            if(hasCmd('corepack')&&match) steps.push(['corepack',['pnpm@'+match[1],'run',script]]);
-            if(hasCmd('corepack')) steps.push(['corepack',['pnpm','run',script]]);
-            trySteps(steps);
-            console.error('deft: neither pnpm nor corepack is available to run \"'+script+'\".');
-            if(pin){
-              console.error('  Enable Corepack for the pinned manager: corepack enable && corepack prepare '+pin+' --activate');
-            }else{
-              console.error('  Install pnpm or enable Corepack (see package.json#packageManager).');
-            }
-            console.error('  Or set DEFT_PACKAGE_MANAGER=npm for an explicit npm build path.');
-            process.exit(127);
-          " "{{.DEFT_ROOT}}"
+          node "{{.TASKFILE_DIR}}/engine-pm-run.cjs" "{{.DEFT_ROOT}}" build --mark-warm
         fi
 
   invoke:

package/tasks/scm.yml

@@ -113,6 +113,16 @@ tasks:
         vars:
           ENGINE_CMD: 'github-body issue-edit {{.CLI_ARGS}}'
 
+  body:issue:fetch:
+    desc: "[#2607] Fetch live issue body to UTF-8 --out-file for safe read-modify-write"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'github-body issue-fetch {{.CLI_ARGS}}'
+
   body:comment:create:
     desc: "[#1555] Safely create an issue/PR comment body from --body-file and live gh read-back"
     dir: '{{.USER_WORKING_DIR}}'

package/tasks/verify.yml

@@ -59,6 +59,16 @@ tasks:
         vars:
           ENGINE_CMD: 'verify-content-manifest --project-root "{{.DEFT_ROOT}}"'
 
+  skill-external-fetch-gate:
+    desc: "Verify shipped skills do not pair external fetch/follow-through with execute/install without Security context mitigation (#1936 / #1532)."
+    deps:
+      - task: :engine:_ts-build
+    # Framework-source-only gate: scans THIS repo's content/skills tree.
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-skill-external-fetch-gate --project-root "{{.DEFT_ROOT}}"'
+
   contract-drift:
     desc: "Drift gate for the public contract layer (#1799). Asserts packages/types/schemas/vbrief-core-0.6.schema.json matches content/vbrief/schemas/vbrief-core.schema.json and that @deftai/directive-types Status/version constants align with the schema. Three-state exit (0 clean / 1 drift / 2 config error)."
     deps:
@@ -393,6 +403,16 @@ tasks:
         vars:
           ENGINE_CMD: 'verify:wip-cap --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
+  orphan-active:
+    desc: "Fail-closed orphan-active guard (#2321). Detects xbrief/active/ briefs with plan.status==running whose referenced GitHub issues are all closed and/or whose linked PR is merged — the stop-at:pr-open lifecycle leak. Remediation points at task scope:complete / scope:cancel or swarm finalize surfaces. Three-state exit (0 clean / 1 orphan / 2 config). Pass --skip-gh to rely on triage cache only."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:orphan-active --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
   agents-md-budget:
     desc: "Layered AGENTS.md budget instrument (#645 + #2450). Fail-closed relative ratchet: counts the managed section and the unmanaged region separately (the #1309 propagation duplicates content across the marker) and fails when either region grows past plan.policy.agentsMdBudget. Seeded at current size, so it ships green; growth past the ratchet fails. ADVISORY absolute north-star: also reports managed-section size vs ≤8 KB / ~2k tok (#2372 layered instrument) without affecting exit codes in Wave 1. Three-state exit (0 within / 1 over ratchet / 2 config error)."
     dir: '{{.USER_WORKING_DIR}}'

package/templates/agent-prompt-preamble.md

@@ -233,6 +233,8 @@ Reference: issue #2563; swarm skill Platform Requirements; env scrub + stdio inh
 
 ! Multi-line git commit / gh issue|pr|comment bodies: write UTF-8 (no BOM) to OS temp, then `git commit -F` / `gh --body-file` / `deft scm:body:* --body-file`. ⊗ bash heredocs, `<<<`, inline multi-line `--body`, or multi-line PS here-strings in the agent command box on Windows PowerShell — those patterns fail at parse time, split arguments, or get rewritten by host shell wrappers before git/gh runs. This applies to your own commit and PR tooling on win32; do not use bash heredocs even when user rules show POSIX patterns. `ghx` is read-only — mutations stay on live `gh`. Detail: `content/scm/github.md` § #2646 (#1417, #240, #798).
 
+! Issue-body read-modify-write on win32: `task scm:body:issue:fetch --out-file` then edit the body file then `task scm:body:issue:edit --body-file` (fail-closed postcondition verify, #2607). ⊗ Capture-concat of `gh api repos/.../issues/<N> --jq .body` into PowerShell variables — PS string[]/$OFS collapses newlines to spaces and silently destroys live bodies (#2744, #2087, #2741, #1492). Detail: `content/scm/github.md` § #2744.
+
 ## 4. pre-pr and review-cycle skills
 
 Before pushing any branch:
@@ -326,6 +328,7 @@ Use the canonical safe wrapper for issue bodies, PR bodies, and issue/PR comment
 task scm:body:comment:create -- --repo OWNER/REPO --issue 1555 --body-file "$bodyFile"
 task scm:body:comment:edit -- --repo OWNER/REPO --comment 123456789 --body-file "$bodyFile"
 task scm:body:issue:create -- --repo OWNER/REPO --title "Title" --body-file "$bodyFile"
+task scm:body:issue:fetch -- --repo OWNER/REPO --issue 1555 --out-file "$bodyFile"
 task scm:body:issue:edit -- --repo OWNER/REPO --issue 1555 --body-file "$bodyFile"
 task scm:body:pr:edit -- --repo OWNER/REPO --pr 42 --body-file "$bodyFile"
 ```
@@ -446,8 +449,10 @@ These rules bind **orchestrators** dispatching implementation, fix, or review-cy
 **Worker-owns-lifecycle (Gap C):**
 
 - ! When dispatching an implementation worker, the dispatch envelope MUST declare the unit-of-work boundary explicitly: `stop-at: pr-open` (worker opens PR and exits) OR `drive-to: merge-ready` (worker owns PR + Greptile review cycle + fix batches through merge-ready as ONE unit of work, spawning its own review poller per `skills/deft-directive-review-cycle/SKILL.md` monitoring tiers). Default for story implementation dispatches is `drive-to: merge-ready`.
+- ! **Post-merge scope lifecycle (#2321 / Gap C):** Workers scoped `stop-at: pr-open` MUST NOT run `task scope:complete` before exit — their activation checkpoint rides into master on merge. The **orchestrator** (or Phase 6 `task swarm:finalize-cohort` / `task swarm:complete-cohort` on the headless path) MUST run `task scope:complete` or `task scope:cancel` for each shipped story xBRIEF after its PR merges. Workers scoped `drive-to: merge-ready` (or `drive-to: merge`) MUST include `task scope:complete` on their active xBRIEF as part of the same unit of work (after merge when appropriate).
 - ! Workers scoped `drive-to: merge-ready` MUST drive to merge-ready in their own tool loop — pre-PR, push, PR open, review-cycle poll/fix loop, and the #1259 Step 6 fail-closed exit — without handing back at PR-open for the orchestrator to re-dispatch separate leaf agents for review or fixes.
 - ⊗ Re-dispatch a separate review-monitor or fix agent after an implementation worker exits at PR-open when the original envelope scoped `drive-to: merge-ready` — that split recreates cross-agent state-handoff hazards and terminal lifecycle gaps (#1878 / Gap C).
+- ⊗ Leave an `xbrief/active/` brief with `plan.status == running` on master after the story's issue is closed or its PR merged — `task verify:orphan-active` fails closed on that signature (#2321).
 
 **Background / independent dispatch (Gap D):**
 

package/templates/agents-entry.md

@@ -83,9 +83,9 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 
 ! When `plan.policy.allowDirectCommitsToMaster = true`, surface via `deft policy:show --field=allowDirectCommitsToMaster` (#746) — `.deft/core/scm/github.md` § Branch policy.
 
-## Windows PowerShell: multi-line git/gh bodies (#2646)
+## Windows PowerShell: multi-line git/gh bodies (#2646 / #2744)
 
-! Multi-line git commit / gh issue|pr|comment bodies: write UTF-8 (no BOM) to OS temp, then `git commit -F` / `gh --body-file` / `deft scm:body:* --body-file`. ⊗ bash heredocs, `<<<`, or inline multi-line `--body` on Windows PowerShell. Detail: `.deft/core/scm/github.md` § #2646. `ghx` is read-only — mutations stay on live `gh`.
+! Multi-line git commit / gh issue|pr|comment bodies: write UTF-8 (no BOM) to OS temp, then `git commit -F` / `gh --body-file` / `deft scm:body:* --body-file`. Issue-body RMW on win32: `deft scm:body:issue:fetch --out-file` then edit the file then `deft scm:body:issue:edit --body-file` (#2607 postcondition verify). ⊗ bash heredocs, `<<<`, inline multi-line `--body`, or PS capture-concat of `gh api --jq .body` (string[]/$OFS destroys bodies — #2087, #2741, #1492). Detail: `.deft/core/scm/github.md` § #2646 / #2744. `ghx` is read-only — mutations stay on live `gh`.
 
 ## Contextual guardrails (runtime-detect lazy-load)