@deftai/directive-content 0.87.0 → 0.89.0

package/tasks/engine-invoke.cjs

@@ -12,6 +12,29 @@
 
 const { spawnSync } = require("node:child_process");
 
+/**
+ * cmd.exe command separators / metacharacters. Free-text DEFT_ENGINE_CMD_JSON
+ * tokens (release --summary text, CLI_ARGS, #2547) may legitimately contain
+ * these; double-quoting renders them literal to cmd.exe's parser so a token can
+ * never break out of its argv slot (subprocess-scm-01 / #2911).
+ */
+const WIN32_CMD_METACHAR_RE = /[\s"&|<>^()%!]/;
+
+/**
+ * Quote a single argument for `cmd.exe /d /s /c` so that shell metacharacters
+ * stay inside one argv token. Mirrors tasks/engine-pm-run.cjs quoteWin32Arg but
+ * also quotes cmd.exe separators (& | < > ^ ( ) % !) because engine-invoke
+ * forwards operator free-text, not an allowlisted command.
+ * @param {string} arg
+ */
+function quoteWin32Arg(arg) {
+  const s = String(arg);
+  if (s.length > 0 && !WIN32_CMD_METACHAR_RE.test(s)) {
+    return s;
+  }
+  return `"${s.replace(/"/g, '""')}"`;
+}
+
 /** Minimal POSIX-ish shell word splitter (double/single quotes, escapes). */
 function shellSplit(input) {
   const out = [];
@@ -75,15 +98,8 @@ function main() {
     process.exit(2);
   }
 
-  let execPath;
-  let execArgv;
-  if (mode === "vendored") {
-    execPath = process.execPath;
-    execArgv = [target, ...argv];
-  } else if (mode === "global") {
-    execPath = target;
-    execArgv = argv;
-  } else {
+  const plan = buildSpawnPlan(mode, target, argv);
+  if (!plan) {
     console.error(`deft: engine-invoke unknown mode ${JSON.stringify(mode)}`);
     process.exit(2);
   }
@@ -97,11 +113,12 @@ function main() {
   // stdio inherit (not pipe): piped stdout/stderr deadlocks when the child emits
   // more than the OS pipe buffer before exit — observed as greenfield smoke
   // hanging then CI SIGTERM exit 143 with no output (#2554 / #2547).
-  const result = spawnSync(execPath, execArgv, {
+  const result = spawnSync(plan.command, plan.args, {
     stdio: "inherit",
     env: childEnv,
-    // Global deft/directive on Windows are .cmd shims; shell:false cannot spawn them (#2415).
-    shell: mode === "global" && process.platform === "win32",
+    // Never shell:true — even on win32 global (subprocess-scm-01 / #2911). The
+    // win32 .cmd shim is reached through a tightly quoted cmd.exe wrapper below.
+    shell: plan.shell,
     // CREATE_NO_WINDOW: hide console windows from Cursor Task / nested shells (#2563).
     windowsHide: true,
   });
@@ -109,8 +126,47 @@ function main() {
   process.exit(code === null ? 1 : code);
 }
 
+/**
+ * Resolve the concrete spawn command/args for a mode+target without ever using
+ * shell:true. On the win32 global path the target is a `.cmd` shim that Node
+ * refuses to spawn with shell:false (CVE-2024-27980 / #2415); shell:true would
+ * let cmd.exe re-parse free-text DEFT_ENGINE_CMD_JSON tokens (subprocess-scm-01
+ * / #2911). Instead route through `cmd.exe /d /s /c` with every token tightly
+ * quoted so metacharacters stay inside a single argv token — aligned with
+ * tasks/engine-pm-run.cjs executeAllowlisted().
+ *
+ * @param {string} mode
+ * @param {string} target
+ * @param {string[]} argv
+ * @param {{ platform?: string, nodePath?: string }} [opts]
+ * @returns {{ command: string, args: string[], shell: false } | null}
+ */
+function buildSpawnPlan(mode, target, argv, opts = {}) {
+  const platform = opts.platform || process.platform;
+  const nodePath = opts.nodePath || process.execPath;
+
+  let execPath;
+  let execArgv;
+  if (mode === "vendored") {
+    execPath = nodePath;
+    execArgv = [target, ...argv];
+  } else if (mode === "global") {
+    execPath = target;
+    execArgv = argv;
+  } else {
+    return null;
+  }
+
+  if (mode === "global" && platform === "win32") {
+    const commandLine = [execPath, ...execArgv].map(quoteWin32Arg).join(" ");
+    return { command: "cmd.exe", args: ["/d", "/s", "/c", commandLine], shell: false };
+  }
+
+  return { command: execPath, args: execArgv, shell: false };
+}
+
 if (require.main === module) {
   main();
 }
 
-module.exports = { shellSplit };
+module.exports = { shellSplit, quoteWin32Arg, buildSpawnPlan, WIN32_CMD_METACHAR_RE };

package/tasks/engine-invoke.test.cjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+"use strict";
+
+const assert = require("node:assert/strict");
+const { describe, it } = require("node:test");
+const {
+  shellSplit,
+  quoteWin32Arg,
+  buildSpawnPlan,
+  WIN32_CMD_METACHAR_RE,
+} = require("./engine-invoke.cjs");
+
+const WIN32 = { platform: "win32", nodePath: "/node" };
+const POSIX = { platform: "linux", nodePath: "/node" };
+
+/**
+ * Split a `cmd.exe`-quoted command line into top-level tokens, honouring
+ * double-quote grouping and the `""` escaped-quote convention. Used to assert
+ * that a metacharacter-bearing arg survives as exactly one argv token and is
+ * never seen by cmd.exe as a command separator.
+ * @param {string} line
+ */
+function splitCmdTokens(line) {
+  const tokens = [];
+  let cur = "";
+  let inQuote = false;
+  let started = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (inQuote) {
+      if (c === '"') {
+        if (line[i + 1] === '"') {
+          cur += '"';
+          i++;
+          continue;
+        }
+        inQuote = false;
+        continue;
+      }
+      cur += c;
+      continue;
+    }
+    if (c === '"') {
+      inQuote = true;
+      started = true;
+      continue;
+    }
+    if (c === " ") {
+      if (started) {
+        tokens.push(cur);
+        cur = "";
+        started = false;
+      }
+      continue;
+    }
+    started = true;
+    cur += c;
+  }
+  if (started) {
+    tokens.push(cur);
+  }
+  return tokens;
+}
+
+describe("shellSplit", () => {
+  it("keeps quoted free-text (apostrophes, spaces, metachars) as one token", () => {
+    assert.deepEqual(shellSplit(`release --summary "It's a & test"`), [
+      "release",
+      "--summary",
+      "It's a & test",
+    ]);
+  });
+});
+
+describe("quoteWin32Arg", () => {
+  it("passes safe tokens through unquoted", () => {
+    assert.equal(quoteWin32Arg("release"), "release");
+    assert.equal(quoteWin32Arg("--summary=fixed"), "--summary=fixed");
+  });
+
+  it("double-quotes whitespace, quotes, and cmd.exe metacharacters", () => {
+    assert.equal(quoteWin32Arg("a b"), '"a b"');
+    assert.equal(quoteWin32Arg("a&b"), '"a&b"');
+    assert.equal(quoteWin32Arg("a|b"), '"a|b"');
+    assert.equal(quoteWin32Arg("a>b"), '"a>b"');
+    assert.equal(quoteWin32Arg("a<b"), '"a<b"');
+    assert.equal(quoteWin32Arg("(a)"), '"(a)"');
+    assert.equal(quoteWin32Arg("%PATH%"), '"%PATH%"');
+    assert.equal(quoteWin32Arg("a^b"), '"a^b"');
+    assert.equal(quoteWin32Arg("a!b"), '"a!b"');
+  });
+
+  it("escapes embedded double quotes by doubling", () => {
+    assert.equal(quoteWin32Arg('a"b'), '"a""b"');
+  });
+
+  it("regex flags every cmd.exe separator", () => {
+    for (const meta of [" ", '"', "&", "|", "<", ">", "^", "(", ")", "%", "!"]) {
+      assert.ok(WIN32_CMD_METACHAR_RE.test(`x${meta}y`), meta);
+    }
+  });
+});
+
+describe("buildSpawnPlan — win32 global (subprocess-scm-01 / #2911)", () => {
+  it("never uses shell:true and routes through cmd.exe /d /s /c", () => {
+    const plan = buildSpawnPlan("global", "deft", ["release"], WIN32);
+    assert.equal(plan.shell, false);
+    assert.equal(plan.command, "cmd.exe");
+    assert.deepEqual(plan.args.slice(0, 3), ["/d", "/s", "/c"]);
+    assert.equal(plan.args[3], "deft release");
+  });
+
+  it("keeps injection-shaped free-text args as a single quoted token", () => {
+    const injections = [
+      "& calc.exe",
+      "&calc",
+      "| whoami",
+      "&& shutdown /s",
+      "; rm -rf /",
+      "$(reboot)",
+      "`reboot`",
+      "> C:\\pwn.txt",
+      "< C:\\secret",
+      "(malicious)",
+      "%USERPROFILE%",
+      "^escaped",
+      "!DELAYED!",
+    ];
+    for (const evil of injections) {
+      const plan = buildSpawnPlan("global", "deft", ["release", "--summary", evil], WIN32);
+      assert.equal(plan.shell, false, evil);
+      const commandLine = plan.args[3];
+      const tokens = splitCmdTokens(commandLine);
+      // deft + release + --summary + evil == 4 top-level tokens, evil intact.
+      assert.deepEqual(tokens, ["deft", "release", "--summary", evil], `injection ${evil}`);
+      // Any cmd.exe metacharacter must be neutralised inside a quoted span so it
+      // can never act as a bare command separator (POSIX-only chars like the
+      // backtick are literal to cmd.exe and need no quoting).
+      if (WIN32_CMD_METACHAR_RE.test(evil)) {
+        assert.ok(commandLine.includes(`"${evil.replace(/"/g, '""')}"`), `quoted ${evil}`);
+      }
+    }
+  });
+
+  it("routes end-to-end from a quoted DEFT_ENGINE_CMD string", () => {
+    const argv = shellSplit('release --summary "pwn & calc | whoami"');
+    const plan = buildSpawnPlan("global", "directive", argv, WIN32);
+    assert.equal(plan.shell, false);
+    assert.deepEqual(splitCmdTokens(plan.args[3]), [
+      "directive",
+      "release",
+      "--summary",
+      "pwn & calc | whoami",
+    ]);
+  });
+
+  it("leaves safe args unquoted for readability", () => {
+    const plan = buildSpawnPlan("global", "deft", ["session:start", "--json"], WIN32);
+    assert.equal(plan.args[3], "deft session:start --json");
+  });
+});
+
+describe("buildSpawnPlan — other paths keep shell:false", () => {
+  it("win32 vendored spawns node directly (no cmd.exe, no shell)", () => {
+    const plan = buildSpawnPlan("vendored", "/bin.js", ["release", "a&b"], WIN32);
+    assert.equal(plan.shell, false);
+    assert.equal(plan.command, "/node");
+    assert.deepEqual(plan.args, ["/bin.js", "release", "a&b"]);
+  });
+
+  it("posix global spawns the shim directly with shell:false", () => {
+    const plan = buildSpawnPlan("global", "deft", ["release", "a&b"], POSIX);
+    assert.equal(plan.shell, false);
+    assert.equal(plan.command, "deft");
+    assert.deepEqual(plan.args, ["release", "a&b"]);
+  });
+
+  it("posix vendored spawns node with shell:false", () => {
+    const plan = buildSpawnPlan("vendored", "/bin.js", ["release"], POSIX);
+    assert.equal(plan.shell, false);
+    assert.equal(plan.command, "/node");
+    assert.deepEqual(plan.args, ["/bin.js", "release"]);
+  });
+
+  it("returns null for unknown modes (caller exits 2)", () => {
+    assert.equal(buildSpawnPlan("bogus", "deft", ["release"], WIN32), null);
+  });
+});

package/tasks/pr.yml

@@ -124,3 +124,19 @@ tasks:
       - task: :engine:invoke
         vars:
           ENGINE_CMD: 'pr-watch {{.CLI_ARGS}}'
+
+  # pr:finish-loop -- walk-away PR shepherd (#871 Wave 5 / #2948).
+  # Grant-gated wrap of pr:watch until CLEAN; address path is agent-
+  # orchestrated (exit 1 on NEW_P0_P1). Respects requireHumanMerge —
+  # never force bot merge. Fail closed without finish-loop grant.
+  #
+  # Companion module: packages/core/src/finish-loop/
+  # Contract: content/contracts/finish-loop.md
+  finish-loop:
+    desc: "Walk-away PR finish loop: grant gate + pr:watch until CLEAN; exit 1 address / human-merge; exit 2 BLOCKED without grant (#871)"
+    deps: [":engine:_ts-build"]
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'pr-finish-loop {{.CLI_ARGS}}'

package/tasks/scm.yml

@@ -123,6 +123,26 @@ tasks:
         vars:
           ENGINE_CMD: 'github-body issue-fetch {{.CLI_ARGS}}'
 
+  body:issue:lint:
+    desc: "[#2960] Lint live issue body for CP1252/CP437-as-UTF-8 mojibake (same patterns as verify:encoding)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'github-body issue-lint {{.CLI_ARGS}}'
+
+  body:pr:lint:
+    desc: "[#2960] Lint live PR body for CP1252/CP437-as-UTF-8 mojibake (same patterns as verify:encoding)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'github-body pr-lint {{.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

@@ -47,6 +47,16 @@ tasks:
         vars:
           ENGINE_CMD: 'verify-biome-config --project-root "{{.DEFT_ROOT}}"'
 
+  contained-writes:
+    desc: "Inventory raw product write sinks outside the contained-write allowlist (#2951 / #2980). Default CLI remains fail-open; task check wires --enforce fail-closed. -- task verify:contained-writes [-- --enforce]"
+    deps:
+      - task: :engine:_ts-build
+    # Framework-source-only gate: scans packages/core/src in THIS repo.
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-contained-writes --project-root "{{.DEFT_ROOT}}" {{.CLI_ARGS}}'
+
   content-manifest:
     desc: "Verify the Content Manifest (conventions/content-manifest.json) classifies every git-tracked top-level entry (#1821). Fails on an unclassified entry, a stale classified path, an invalid bucket, or a duplicate path. Wave-1 shippability audit for the engine/content split (#1669)."
     deps:
@@ -59,6 +69,13 @@ tasks:
         vars:
           ENGINE_CMD: 'verify-content-manifest --project-root "{{.DEFT_ROOT}}"'
 
+  license-sync:
+    desc: "Drift guard for root LICENSE ↔ content/LICENSE.md and published package.json license fields (#2902). Three-state exit (0 clean / 1 drift / 2 config). Framework-source only."
+    # Framework-source-only gate: reads THIS repo's LICENSE + package manifests.
+    # Plain node script (no engine build required).
+    cmds:
+      - node "{{.DEFT_ROOT}}/scripts/verify-license-sync.mjs" --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:

package/templates/agent-prompt-preamble.md

@@ -352,6 +352,18 @@ Anti-pattern: reading only the issue body and building a dispatch envelope from
 
 Reference: AGENTS.md `## Issue body→comments reading (#2143)`, `## Umbrella current-shape convention (#1152)`, issue #2143.
 
+## 5.6.1 Typed escalation channel (#518 slim / #2948 Wave 5)
+
+When blocked on human input under multi-agent load, file a **typed** escalation instead of a synchronous interrupt storm:
+
+- Types: `cmd_approval` | `design_decision` | `approval` | `resource` | `external` | `question`
+- CLI: `deft escalation:file` / `list` / `resolve` / `batch-approve` (bulk only for non-dangerous `cmd_approval` + `question`)
+- Store: `.deft/escalations/<id>.json`
+- Mark write-scope shell / merge / release requests `dangerous: true` so they stay individual
+- Escalations are **not** implement authority — compose with `deft authz:grant` (Wave 1) after approval
+
+Contract + residual full priority-inbox UI: `content/contracts/escalation.md`.
+
 ## 5.7 Value feedback opt-in and gap escalation (#1709)
 
 Value attribution, budgeted session readbacks, and upstream gap escalation are gated on `plan.policy.valueFeedback` (default OFF). Workers MUST NOT emit value claims, session readback lines, or file upstream framework-gap issues unless the relevant sub-flag is ON and the operator has confirmed enablement where required.
@@ -529,6 +541,12 @@ Every worker MUST send a final status message before exiting its tool loop, rega
 
 ⊗ Emit `DONE` from a `drive-to: merge-ready` worker while merge-ready is false — a false-terminal `DONE` pulls the cohort monitor into inline Greptile fixes and violates Gap D (#2843 monitor-as-implementer recurrence).
 
+! **Thin DONE is not success (#2943):** A terminal message that lacks PR URL / merge evidence (no `PR #N`, no PR URL, no merge confirmation) is a **thin DONE** / failed-leaf signal for the parent monitor — re-dispatch or take over after ground truth. Prefer structured completion fields when the host supplies them (`prUrl`, `mergeStatus`, `emptyDiff`). Workers MUST NOT exit with mid-edit prose and call it `DONE` when the envelope required a PR or merge-ready outcome.
+
+! **Parent tool-first after leaf completion (#2943):** When a parent / monitor receives a leaf completion event (`subagent_announce`, parent-push, or host completion notify), its **first response** MUST be a **tool-first** ground-truth batch (`gh` / `git` / worktree or file status) **or** a host **yield** (`sessions_yield` on OpenClaw, or equivalent). ⊗ Multi-sentence progress-only first response with zero tools / yield — the OpenClaw text-repetition hang class (#2943).
+
+⊗ Treat thin DONE (no PR URL / merge evidence) as success (#2943).
+
 Per-step acks during the run are noise. ONE start message, ONE final message; intermediate messages only on `BLOCKED` / `FAILED`. The final message lets the dispatcher distinguish a clean exit from a silent timeout when the lifecycle event arrives.
 
 ## 12. Session ritual + `task verify:cache-fresh` gates before `start_agent` (#1348 / #1127)

package/templates/agents-entry.md

@@ -93,9 +93,13 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 
 ## Development Process
 
-### Implementation Intent Gate (#810)
+### Implementation Intent Gate (#810 / #1193)
 
-! `deft xbrief:preflight -- <path>` on `xbrief/active/` before code-writing; action-verb (`build`, `implement`, `ship`, `swarm`, `run agents`, `start agent`) (#810) — `commands.md` § Scope xBRIEF Lifecycle.
+! `deft xbrief:preflight -- <path>` on `xbrief/active/` before code-writing; action-verb (`build`, `implement`, `ship`, `swarm`, `run agents`, `start agent`) (#810). Slash-command sessions inherit only that verb (`DEFT_SESSION_SLASH_VERB`); non-implement verbs (`/github-issue`, `/triage`, …) MUST NOT authorize implement/push/PR/merge/deploy (#1193) — `commands.md` / `contracts/intent-ceiling.md`.
+
+## Human merge gate (#1193)
+
+! When `plan.policy.requireHumanMerge` is true (default if `autoDeployOnMerge`), agents may open PRs, may not merge. Override: `deft policy:allow-bot-merge -- --confirm` or `DEFT_ALLOW_BOT_MERGE=1` — `commands.md` / `contracts/intent-ceiling.md`.
 
 ### Story Start Gate
 

package/templates/project.md.template

@@ -39,6 +39,12 @@ cp secrets/[example].example secrets/[example]  # [Description]
 - **API**: [api.md](./docs/api.md)
 - **Deployment**: [deployment.md](./docs/deployment.md)
 
+## xBRIEF envelope (#2971)
+
+<!-- Copy sources for project identity / scope JSON must write 0.8 only. -->
+- ! New `xbrief/*.xbrief.json` MUST use `"xBRIEFInfo": { "version": "0.8" }` (schema const)
+- ⊗ Emit `"version": "0.6"` on any new write path — run `deft migrate:xbrief` for existing 0.6 docs
+
 ## Branching
 
 <!-- Uncomment the line below to allow direct commits to master (trunk-based workflow). -->

package/vbrief/schemas/vbrief-core.schema.json

@@ -609,12 +609,45 @@
           "minimum": 1,
           "description": "Maximum age, in hours, for .deft/ritual-state.json before the fail-closed session ritual verifier requires task session:start to run again. Default: 4."
         },
+        "requireHumanMerge": {
+          "type": "boolean",
+          "description": "When true, agents may open PRs but must not merge (#1193). Defaults true when autoDeployOnMerge is also true. Override: policy:allow-bot-merge --confirm or DEFT_ALLOW_BOT_MERGE=1."
+        },
+        "autoDeployOnMerge": {
+          "type": "boolean",
+          "description": "When true, merges to the default branch auto-deploy to production. Couples with requireHumanMerge defaulting (#1193)."
+        },
+        "hotfixCriteria": {
+          "$ref": "#/$defs/HotfixCriteria"
+        },
         "projectionProviders": {
           "$ref": "#/$defs/ProjectionProviderPolicies"
         }
       },
       "additionalProperties": true
     },
+    "HotfixCriteria": {
+      "type": "object",
+      "description": "Structural hotfix eligibility thresholds (#1193). Agent may label hotfix-candidate only; human promotes hotfix.",
+      "properties": {
+        "maxLines": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Max changed lines for a small-fix hotfix candidate. Default: 10."
+        },
+        "maxFiles": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Max changed files for a small-fix hotfix candidate. Default: 2."
+        },
+        "forbiddenPathGlobs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Path globs that never qualify as hotfix (deploy/CI/migrations/auth defaults apply when omitted)."
+        }
+      },
+      "additionalProperties": true
+    },
     "ProjectionProviderPolicies": {
       "type": "object",
       "description": "Projection provider artifact policies keyed by projection kind. Values point at durable artifacts; runner command strings are not canonical policy.",

package/vbrief/vbrief.md

@@ -1,10 +1,12 @@
 # vBRIEF Usage in Deft
 
-Canonical reference for vBRIEF file conventions within Deft-managed projects.
+> **Public name (#2907):** The sole current work-state name is **xBRIEF** under `xbrief/` (`.xbrief.json`). **vBRIEF** / `vbrief/` / `.vbrief.json` in this document are **legacy / schema-lineage** names (this path still hosts core schemas). Prefer xbrief in product docs and new guidance. Authoritative rename/history: [UPGRADING.md — xBRIEF rename](../UPGRADING.md#xbrief-rename-2034--2110--2907). Migrate on-disk layouts with `deft migrate:xbrief`.
+
+Canonical **schema and convention** reference for durable work-state files within Deft-managed projects (historical filename: vBRIEF).
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [context/working-memory.md](../context/working-memory.md) | [resilience/continue-here.md](../resilience/continue-here.md) | [context/long-horizon.md](../context/long-horizon.md) | [glossary.md](../glossary.md)
+**⚠️ See also**: [glossary.md](../glossary.md) | [UPGRADING.md — xBRIEF rename](../UPGRADING.md#xbrief-rename-2034--2110--2907) | [context/working-memory.md](../context/working-memory.md) | [resilience/continue-here.md](../resilience/continue-here.md)
 
 ---