@deftai/directive-core 0.73.0 → 0.74.0

package/dist/triage/bootstrap/gitignore.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, relative } from "node:path";
+import { assertProjectionContained, ProjectionContainmentError, } from "../../fs/projection-containment.js";
 import { MIGRATED_ARTIFACT_DIR, resolveLifecycleLayout } from "../../layout/resolve.js";
 import { resolveCandidatesLogPath, resolveTriageCachePath, TRIAGE_CACHE_DIR_NAME, triageCacheRelPath, } from "../cache-path.js";
 /** POSIX-style display path for `absPath` relative to `projectRoot` (#2109). */
@@ -85,78 +86,58 @@ const GITATTRIBUTES_EVAL_RATIONALE = "\n# Append-only JSON-lines logs under vbri
     "# without manual conflict surgery. Note: merge=union does NOT dedupe; see\n" +
     "# vbrief/.triage-cache/README.md for the operator-facing semantics.\n";
 const EVAL_ENTRIES_RATIONALE_SENTINEL = "# vbrief/.triage-cache/ tracking governance (#1144, N4 of #1119).";
-export const EVAL_README_BODY = `# \`vbrief/.triage-cache/\` -- triage working-set artefacts
+export const EVAL_README_BODY = `# \`vbrief/.triage-cache/\` — triage working-set files
 
-This directory holds the append-only JSON-lines logs that the triage and
-slicing skills emit. The framework governs which files in here are tracked
-by git versus gitignored using a **hybrid policy** (#1144, child of #1119).
+This directory holds JSON-lines logs and scratch files that Deft triage and
+slicing workflows emit. Deft configures your repo's \`.gitignore\` and
+\`.gitattributes\` so some files stay local while team-shared records can be
+committed.
 
-## Tracking policy
+## What lives here
 
-| File | Tracked? | Why |
+| File | Committed? | Notes |
 | --- | --- | --- |
-| \`slices.jsonl\` | Yes -- **committed** | Team-shared cohort records produced by slicing skills (D13 / #1132). New operators joining the team need to see prior cohort outputs to detect orphans and avoid re-slicing the same scope. |
-| \`candidates.jsonl\` | No -- **gitignored** | Operator-private triage decisions (#845 Story 2). Each operator's local accept / defer / reject stream is per-machine state; sharing it would conflate operators' timing + identity across the team. Re-derive on a fresh clone via \`task triage:bootstrap\`. |
-| \`summary-history.jsonl\` | No -- **gitignored** | Operator-private observability for \`task triage:summary\` output time-series. Not load-bearing for any decision. |
-| \`scope-lifecycle.jsonl\` | No -- **gitignored** | Operator-private scope-lifecycle audit decisions (D1 / #1121). Each demote (\`task scope:demote\`) appends one entry including a \`demote_meta\` block (\`was_promoted\`, \`original_promotion_decision_id\`, \`days_in_pending\`, \`demote_reason\`, \`demoted_from\`). Per-operator stream; sharing would conflate operators' demote timing across the team. Lightweight metrics over this log are tracked separately at #1180. |
-| \`decompositions/\` | No -- **gitignored** | Temporary story-decomposition proposal drafts. These JSON drafts are local scratch artifacts, not vBRIEFs; generated child story vBRIEFs are created by \`task scope:decompose\` in lifecycle folders, defaulting to \`vbrief/pending/\`. |
-| \`doctor-state.json\` | No -- **gitignored** | Per-machine \`task doctor\` throttle state (last exit code + timestamps) persisted to gate the 24h/4h re-probe window (#1308 / #1464). Local to each clone; never committed. |
+| \`slices.jsonl\` | Yes | Team-shared cohort records from slicing skills. New teammates use prior cohort outputs to spot orphans and avoid re-slicing the same scope. |
+| \`candidates.jsonl\` | No | Your local triage accept / defer / reject stream. Re-create on a fresh clone with \`deft triage:bootstrap\`. |
+| \`summary-history.jsonl\` | No | Local history of \`deft triage:summary\` output; not required for day-to-day work. |
+| \`scope-lifecycle.jsonl\` | No | Local audit trail for scope demotions (\`deft scope:demote\`). Each operator's stream stays on their machine. |
+| \`decompositions/\` | No | Draft story-decomposition scratch. Produced child story xBRIEFs live in lifecycle folders via \`deft scope:decompose\`. |
+| \`doctor-state.json\` | No | Per-clone throttle state for \`deft doctor\` re-probe timing. |
 
-The gitignore lines live in the repo-root \`.gitignore\` (\`vbrief/.triage-cache/candidates.jsonl\`,
+Paths listed as "No" above are added to \`.gitignore\` during bootstrap; anything
+not listed remains committable by default. The selective ignore entries live in
+the repo-root \`.gitignore\` (\`vbrief/.triage-cache/candidates.jsonl\`,
 \`vbrief/.triage-cache/summary-history.jsonl\`, \`vbrief/.triage-cache/scope-lifecycle.jsonl\`,
-\`vbrief/.triage-cache/decompositions/\`, and \`vbrief/.triage-cache/doctor-state.json\`). All paths
-not listed above remain committed by default.
+\`vbrief/.triage-cache/decompositions/\`, and \`vbrief/.triage-cache/doctor-state.json\`).
 
-## Fresh-clone regeneration
+## Fresh clone
 
-On a fresh clone (or any machine that has never run triage), \`candidates.jsonl\`
-is absent. Regenerate it with:
+If \`candidates.jsonl\` is missing, run:
 
 \`\`\`
-task triage:bootstrap
+deft triage:bootstrap
 \`\`\`
 
-The bootstrap path detects the missing file, runs the auto-classifier, and
-writes a fresh \`vbrief/.triage-cache/candidates.jsonl\`. It does NOT touch the tracked
-\`slices.jsonl\`; cohort records remain a team-shared resource.
+Bootstrap rebuilds the local candidates log without altering committed
+\`slices.jsonl\`.
 
-## \`merge=union\` policy for \`*.jsonl\`
+## Merge behavior for \`*.jsonl\`
 
-The repo-root \`.gitattributes\` declares:
+The repo-root \`.gitattributes\` may declare:
 
 \`\`\`
 vbrief/.triage-cache/*.jsonl  merge=union
 \`\`\`
 
-The \`union\` merge driver concatenates both sides' appended lines on
-auto-merge, so two branches that each appended a different record to the
-same JSON-lines file rebase cleanly without operator surgery. Two things
-operators should know:
-
-- **Concatenation, not set-union.** When two branches append DIFFERENT
-  records to the file, the merge driver concatenates both sides' lines
-  -- there is no smart deduplication of "semantically similar" records.
-  (Identical line-for-line appends collapse because git's three-way
-  merge sees them as the same change, but distinct records always
-  survive verbatim, even if a downstream reader would consider them
-  redundant.) The append-only writers in \`scripts/candidates_log.py\`
-  mint a fresh \`decision_id\` per call, so genuinely duplicate records
-  are not the expected case, but downstream readers MUST tolerate
-  multiple records describing the same logical decision.
-- **Single-operator scope only.** This is the foundational rebase
-  ergonomic for the single-operator case (operator A rebases their
-  feature branch onto a master that grew while they were AFK).
-  Multi-operator merge-conflict resolution is explicitly out of scope per
-  #1119 R4 (tracked separately as M1-M4 in #1183).
+The \`union\` merge driver concatenates both sides' appended lines on auto-merge,
+so parallel append-only edits to the same JSON-lines file rebase without manual
+conflict surgery. It does not dedupe semantically similar records — downstream
+readers should tolerate duplicate-looking entries.
 
 ## See also
 
-- Current Shape comment on #1144 for the canonical decisions (the source
-  of truth this README documents).
-- \`.gitignore\` -- selective gitignore entries for the operator-private
-  files.
-- \`.gitattributes\` -- the \`merge=union\` rule.
-- \`scripts/candidates_log.py\` -- the writer for \`candidates.jsonl\`.
+- \`.gitignore\` — selective ignore rules for operator-private files
+- \`.gitattributes\` — merge driver for committed JSON-lines logs
 `;
 /** Layout-aware triage-cache README body for the active lifecycle tree (#2344 / #2349). */
 export function generateTriageCacheReadmeBody(projectRoot) {
@@ -173,6 +154,12 @@ export function generateTriageCacheReadmeBody(projectRoot) {
 function stepOutcome(name, ok, message, details = {}, error = null) {
     return { name, ok, message, error, details };
 }
+function containmentFailure(stepName, err) {
+    const message = err instanceof ProjectionContainmentError
+        ? err.message
+        : `projection path containment refused: ${String(err)}`;
+    return stepOutcome(stepName, false, message, {}, message);
+}
 /** Strip an inline `# ...` comment from a gitignore line. */
 export function stripGitignoreInlineComment(line) {
     const stripped = line.trim();
@@ -198,7 +185,13 @@ function isCommentedGitignoreLine(raw, gitignoreLine) {
         body = body.slice(1);
     return body === gitignoreLine;
 }
-function ensureGitignoreLine(gitignorePath, line, stepName, createIfMissing, rationaleBlock, optInMessage) {
+function ensureGitignoreLine(projectRoot, gitignorePath, line, stepName, createIfMissing, rationaleBlock, optInMessage) {
+    try {
+        assertProjectionContained(projectRoot, gitignorePath);
+    }
+    catch (err) {
+        return containmentFailure(stepName, err);
+    }
     if (!existsSync(gitignorePath)) {
         if (!createIfMissing) {
             return stepOutcome(stepName, false, `.gitignore not present after the prior gitignore step; ${line} not written -- re-run bootstrap to retry`, { created: false, appended: false, skipped: "no-gitignore" }, "prior gitignore step did not create .gitignore");
@@ -251,7 +244,7 @@ function ensureGitignoreLine(gitignorePath, line, stepName, createIfMissing, rat
 }
 /** Append `.deft-cache/` to `.gitignore` when absent. */
 export function stepEnsureGitignoreEntry(projectRoot) {
-    return ensureGitignoreLine(`${projectRoot}/.gitignore`, GITIGNORE_LINE, "ensure_gitignore_entry", true, DEFT_CACHE_RATIONALE, `${GITIGNORE_LINE} is commented out (operator has opted in to commit the cache per docs/privacy-nfr.md NFR-2; not re-adding)`);
+    return ensureGitignoreLine(projectRoot, `${projectRoot}/.gitignore`, GITIGNORE_LINE, "ensure_gitignore_entry", true, DEFT_CACHE_RATIONALE, `${GITIGNORE_LINE} is commented out (operator has opted in to commit the cache per docs/privacy-nfr.md NFR-2; not re-adding)`);
 }
 function formatBlanketWarning(blanketPresent) {
     if (!blanketPresent)
@@ -274,7 +267,14 @@ function gitattributesHasEvalMergeUnion(body, glob) {
     }
     return false;
 }
-function ensureGitignoreSelectiveEntries(gitignorePath, stepName, entries) {
+function ensureGitignoreSelectiveEntries(projectRoot, stepName, entries) {
+    const gitignorePath = `${projectRoot}/.gitignore`;
+    try {
+        assertProjectionContained(projectRoot, gitignorePath);
+    }
+    catch (err) {
+        return containmentFailure(stepName, err);
+    }
     let existing;
     try {
         existing = readFileSync(gitignorePath, { encoding: "utf8" });
@@ -316,7 +316,14 @@ function ensureGitignoreSelectiveEntries(gitignorePath, stepName, entries) {
         rationale_already_present: rationaleAlreadyPresent,
     });
 }
-function ensureGitattributesMergeUnion(gitattributesPath, stepName, glob, ruleLine) {
+function ensureGitattributesMergeUnion(projectRoot, stepName, glob, ruleLine) {
+    const gitattributesPath = `${projectRoot}/.gitattributes`;
+    try {
+        assertProjectionContained(projectRoot, gitattributesPath);
+    }
+    catch (err) {
+        return containmentFailure(stepName, err);
+    }
     if (existsSync(gitattributesPath)) {
         let existing;
         try {
@@ -358,6 +365,12 @@ function ensureGitattributesMergeUnion(gitattributesPath, stepName, glob, ruleLi
 }
 function ensureEvalReadme(options) {
     const { projectRoot, readmePath, readmeRel, stepName } = options;
+    try {
+        assertProjectionContained(projectRoot, readmePath);
+    }
+    catch (err) {
+        return containmentFailure(stepName, err);
+    }
     try {
         readFileSync(readmePath, { encoding: "utf8" });
         return stepOutcome(stepName, true, `${readmeRel} already present (no-op)`, {
@@ -381,8 +394,6 @@ function ensureEvalReadme(options) {
 }
 /** Ensure the #1144 hybrid policy is encoded in the repo (idempotent). */
 export function stepEnsureGitignoreEvalEntries(projectRoot) {
-    const gitignorePath = `${projectRoot}/.gitignore`;
-    const gitattributesPath = `${projectRoot}/.gitattributes`;
     // Layout-aware (#2109): resolve the README under the active lifecycle `.eval`
     // dir (xbrief/ when migrated, else vbrief/) instead of a hardcoded vbrief/ path.
     const readmePath = resolveTriageCachePath(projectRoot, "README.md");
@@ -392,13 +403,13 @@ export function stepEnsureGitignoreEvalEntries(projectRoot) {
     const ruleLine = `${glob}  merge=union`;
     const stepName = "ensure_gitignore_eval_entries";
     const details = {};
-    const giResult = ensureGitignoreSelectiveEntries(gitignorePath, stepName, entries);
+    const giResult = ensureGitignoreSelectiveEntries(projectRoot, stepName, entries);
     if (!giResult.ok) {
         Object.assign(details, giResult.details);
         return stepOutcome(stepName, false, giResult.message, details, giResult.error ?? null);
     }
     Object.assign(details, giResult.details);
-    const gaResult = ensureGitattributesMergeUnion(gitattributesPath, stepName, glob, ruleLine);
+    const gaResult = ensureGitattributesMergeUnion(projectRoot, stepName, glob, ruleLine);
     if (!gaResult.ok) {
         Object.assign(details, gaResult.details);
         return stepOutcome(stepName, false, gaResult.message, details, gaResult.error ?? null);

package/dist/ts-check-lane/run-lane.d.ts

@@ -25,6 +25,8 @@ export declare const SKIP_NOTICE: string;
 /** Result of a single lane command invocation. Mirrors a subset of SpawnSyncReturns. */
 export interface RunnerResult {
     readonly status: number | null;
+    readonly signal?: NodeJS.Signals | null;
+    readonly error?: Error;
 }
 export type LaneRunner = (argv: readonly string[], cwd: string) => RunnerResult;
 export interface RunTsLaneOptions {
@@ -35,6 +37,8 @@ export interface RunTsLaneOptions {
     /** Injected sink for human-facing notices (defaults to stdout). */
     readonly out?: (message: string) => void;
 }
+/** Windows command shims (.cmd/.bat) need a shell; native executables do not. */
+export declare function shouldUseShellForCommand(command: string, platform?: NodeJS.Platform): boolean;
 export interface ResolvePnpmOptions {
     readonly env?: NodeJS.ProcessEnv;
     readonly platform?: NodeJS.Platform;

package/dist/ts-check-lane/run-lane.js

@@ -18,7 +18,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { posix, win32 } from "node:path";
 /**
  * Run order is deliberate: lint (cheapest, catches the biome class first),
  * then build, then the test suite.
@@ -31,11 +31,20 @@ export const LANE_COMMANDS = [
 export const SKIP_NOTICE = "[ts:check-lane] pnpm not found on PATH -- skipping the TypeScript lane " +
     "(build/lint/test). The TS engine stays validated by the dedicated CI job. " +
     "Install the Node toolchain (pnpm) to run the TS lane locally.";
-/** Default runner: a non-shell, inherited-stdio pnpm invocation. */
+/** Windows command shims (.cmd/.bat) need a shell; native executables do not. */
+export function shouldUseShellForCommand(command, platform = process.platform) {
+    return platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
+}
+/** Default runner: an inherited-stdio pnpm invocation. */
 function defaultRunner(argv, cwd) {
     const [command, ...rest] = argv;
-    const result = spawnSync(command ?? "", rest, { cwd, stdio: "inherit" });
-    return { status: result.status };
+    const commandPath = command ?? "";
+    const result = spawnSync(commandPath, rest, {
+        cwd,
+        stdio: "inherit",
+        shell: shouldUseShellForCommand(commandPath),
+    });
+    return { error: result.error, signal: result.signal, status: result.status };
 }
 /** Resolve the pnpm executable path, or null when it is not installed. */
 export function resolvePnpm(options = {}) {
@@ -49,11 +58,12 @@ export function resolvePnpm(options = {}) {
     const isWindows = platform === "win32";
     const exts = isWindows ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
     const sep = isWindows ? ";" : ":";
+    const joinPath = isWindows ? win32.join : posix.join;
     for (const dir of pathValue.split(sep)) {
         if (dir === "")
             continue;
         for (const ext of exts) {
-            const candidate = join(dir, `pnpm${ext}`);
+            const candidate = joinPath(dir, `pnpm${ext}`);
             if (exists(candidate)) {
                 return candidate;
             }
@@ -85,7 +95,11 @@ export function runTsLane(projectRoot, options) {
         // failure -- this mirrors the Python oracle, whose returncode is negative
         // (non-zero) for a signal-killed process.
         if (code === null) {
-            out(`[ts:check-lane] \`pnpm ${command.join(" ")}\` was killed by a signal before exit -- treating as failure.`);
+            if (result.error) {
+                out(`[ts:check-lane] \`pnpm ${command.join(" ")}\` failed to start: ${result.error.message}`);
+                return 1;
+            }
+            out(`[ts:check-lane] \`pnpm ${command.join(" ")}\` was killed by ${result.signal ?? "a signal"} before exit -- treating as failure.`);
             return 1;
         }
         if (code !== 0) {

package/dist/value/feedback-file.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { isFrameworkRepoRoot } from "../check/orchestrator.js";
+import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { isValueFeedbackPathAllowed, resolveValueFeedback } from "../policy/value-feedback.js";
 import { GhRestError, restCreateIssue, restIssueListPaginated, } from "../scm/gh-rest.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
@@ -146,8 +147,8 @@ export function runFeedbackFile(options) {
             body,
             repo,
             message: "[deft feedback] Blocked: plan.policy.valueFeedback upstreamPrompt is OFF. " +
-                "Enable with `task policy:enable-value-feedback -- --confirm` and set upstreamPrompt, " +
-                "or inspect via `task policy:show --field=valueFeedback`.\n",
+                `Enable with \`${policyColonInvocation("enable-value-feedback", " -- --confirm")}\` and set upstreamPrompt, ` +
+                `or inspect via \`${policyColonInvocation("show", " --field=valueFeedback")}\`.\n`,
         };
     }
     const offline = isOffline();

package/dist/value/readback.js

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { ALL_ATTRIBUTION_EVENT_NAMES } from "../events/attribution-constants.js";
 import { DEFAULT_EVENT_LOG, readEvents } from "../lifecycle/events.js";
+import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { MAX_LINE_CHARS } from "../triage/welcome/constants.js";
@@ -364,7 +365,7 @@ export function formatValueShowReport(trend) {
     if (trend.total === 0) {
         return (`[value] No attributed signals in the last ${trend.windowLabel} ` +
             "(ledger empty for this window).\n" +
-            "Inspect policy: `task policy:show --field=valueFeedback`.\n");
+            `Inspect policy: \`${policyColonInvocation("show", " --field=valueFeedback")}\`.\n`);
     }
     const classParts = ["value", "bypass", "adoption", "friction"]
         .filter((key) => trend.byClass[key] > 0)
@@ -409,7 +410,7 @@ export function runValueShow(options) {
             gated: true,
             empty: true,
             text: "[value] Blocked: plan.policy.valueFeedback is OFF. " +
-                "Enable with `task policy:enable-value-feedback -- --confirm`.\n",
+                `Enable with \`${policyColonInvocation("enable-value-feedback", " -- --confirm")}\`.\n`,
             trend: null,
         };
     }

package/dist/vbrief-reconcile/umbrellas.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
+import { createIssueComment, editIssueCommentBody, GitHubBodyError, } from "../intake/github-body.js";
 import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
 import { extractIssueRef } from "../triage/reconcile/parse-uri.js";
@@ -229,22 +230,22 @@ export class ScmUmbrellaClient {
         return comments;
     }
     editComment(repo, commentId, body) {
-        const proc = call(SCM_SOURCE, "api", ["-X", "PATCH", `repos/${repo}/issues/comments/${commentId}`, "--input", "-"], { input: JSON.stringify({ body }) });
-        if (proc.returncode !== 0) {
-            throw new UmbrellaScmError(`edit comment ${commentId} (${repo}) failed: ${(proc.stderr || "").trim()}`);
+        try {
+            editIssueCommentBody(repo, commentId, { body });
+        }
+        catch (exc) {
+            const message = exc instanceof GitHubBodyError ? exc.message : String(exc);
+            throw new UmbrellaScmError(`edit comment ${commentId} (${repo}) failed: ${message}`);
         }
     }
     createComment(repo, issueNumber, body) {
-        const proc = call(SCM_SOURCE, "api", ["-X", "POST", `repos/${repo}/issues/${issueNumber}/comments`, "--input", "-"], { input: JSON.stringify({ body }) });
-        if (proc.returncode !== 0) {
-            throw new UmbrellaScmError(`create comment #${issueNumber} (${repo}) failed: ${(proc.stderr || "").trim()}`);
-        }
         try {
-            const data = JSON.parse(proc.stdout || "{}");
-            return typeof data.id === "number" ? data.id : null;
+            const created = createIssueComment(repo, issueNumber, { body });
+            return typeof created.id === "number" ? created.id : null;
         }
-        catch {
-            return null;
+        catch (exc) {
+            const message = exc instanceof GitHubBodyError ? exc.message : String(exc);
+            throw new UmbrellaScmError(`create comment #${issueNumber} (${repo}) failed: ${message}`);
         }
     }
 }

package/dist/xbrief-migrate/migrate-project.js

@@ -205,6 +205,15 @@ export function runXbriefMigration(args, _io) {
         };
     }
     if (!isDirectory(legacyDir)) {
+        // Already on canonical xbrief/ with no vbrief/ tree — residual markers (e.g. a
+        // stale deposited v0.6 schema under xbrief/schemas/) are refreshed by update,
+        // not migrate:xbrief (#2368).
+        if (convergence.xbriefHasContent && !convergence.vbriefPresent) {
+            return {
+                kind: "noop",
+                message: "Project is already on the xbrief layout — residual legacy markers (e.g. a stale deposited schema) cannot be cleared by migrate:xbrief when no vbrief/ tree remains. Run `directive update` to refresh deposited schema files.",
+            };
+        }
         return {
             kind: "config",
             message: `Legacy markers detected but '${LEGACY_ARTIFACT_DIR}/' directory is missing.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.73.0",
+  "version": "0.74.0",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -281,8 +281,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.73.0",
-    "@deftai/directive-types": "^0.73.0",
+    "@deftai/directive-content": "^0.74.0",
+    "@deftai/directive-types": "^0.74.0",
     "archiver": "^8.0.0"
   },
   "scripts": {