@deftai/directive-core 0.73.1 → 0.75.0

package/dist/swarm/complete-cohort.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { detectLifecycleFolder } from "../scope/decomposed-refs.js";
 import { runTransition } from "../scope/transition.js";
@@ -31,13 +31,13 @@ function rel(path, projectRoot) {
     }
 }
 function globResolve(pattern, projectRoot) {
-    const absPattern = pattern.startsWith("/") ? pattern : join(projectRoot, pattern);
+    const absPattern = isAbsolute(pattern) ? pattern : join(projectRoot, pattern);
     if (!absPattern.includes("*")) {
         return existsSync(absPattern) ? [resolve(absPattern)] : [];
     }
-    const slash = absPattern.lastIndexOf("/");
-    const dir = slash >= 0 ? absPattern.slice(0, slash) : projectRoot;
-    const glob = slash >= 0 ? absPattern.slice(slash + 1) : absPattern;
+    // Use path module to split directory/glob parts — platform-safe on both POSIX and Windows.
+    const dir = dirname(absPattern);
+    const glob = basename(absPattern);
     if (!existsSync(dir)) {
         return [];
     }
@@ -59,7 +59,7 @@ export function resolveCohortPaths(positional, cohortGlobs, projectRoot) {
         resolved.push(rp);
     };
     for (const raw of positional) {
-        const candidate = raw.startsWith("/") ? raw : join(projectRoot, raw);
+        const candidate = isAbsolute(raw) ? raw : join(projectRoot, raw);
         if (!existsSync(candidate)) {
             errors.push(`path does not exist: ${raw}`);
             continue;

package/dist/swarm/launch.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { basename, isAbsolute, join, resolve } from "node:path";
 import { inferGithubAuthMode } from "../intake/github-auth-modes.js";
 import { getPlatformCapabilities } from "../intake/platform-capabilities.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, stripArtifactSuffix, } from "../layout/resolve.js";
@@ -166,7 +166,7 @@ export function looksLikePath(token) {
 }
 function resolveOne(token, projectRoot, idMap, issueMap) {
     if (looksLikePath(token)) {
-        const candidate = token.startsWith("/") ? token : join(projectRoot, token);
+        const candidate = isAbsolute(token) ? token : join(projectRoot, token);
         if (!existsSync(candidate)) {
             return {
                 story: null,

package/dist/triage/bootstrap/gitignore.d.ts

@@ -8,7 +8,7 @@ export declare function gitignoreTriageCacheEntries(projectRoot: string): readon
 export declare function gitattributesTriageCacheGlob(projectRoot: string): string;
 export declare const GITATTRIBUTES_EVAL_RULE = "vbrief/.triage-cache/*.jsonl  merge=union";
 export declare const FORBIDDEN_BLANKET_EVAL_LINES: readonly string[];
-export declare const EVAL_README_BODY = "# `vbrief/.triage-cache/` -- triage working-set artefacts\n\nThis directory holds the append-only JSON-lines logs that the triage and\nslicing skills emit. The framework governs which files in here are tracked\nby git versus gitignored using a **hybrid policy** (#1144, child of #1119).\n\n## Tracking policy\n\n| File | Tracked? | Why |\n| --- | --- | --- |\n| `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. |\n| `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`. |\n| `summary-history.jsonl` | No -- **gitignored** | Operator-private observability for `task triage:summary` output time-series. Not load-bearing for any decision. |\n| `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. |\n| `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/`. |\n| `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. |\n\nThe gitignore lines live in the repo-root `.gitignore` (`vbrief/.triage-cache/candidates.jsonl`,\n`vbrief/.triage-cache/summary-history.jsonl`, `vbrief/.triage-cache/scope-lifecycle.jsonl`,\n`vbrief/.triage-cache/decompositions/`, and `vbrief/.triage-cache/doctor-state.json`). All paths\nnot listed above remain committed by default.\n\n## Fresh-clone regeneration\n\nOn a fresh clone (or any machine that has never run triage), `candidates.jsonl`\nis absent. Regenerate it with:\n\n```\ntask triage:bootstrap\n```\n\nThe bootstrap path detects the missing file, runs the auto-classifier, and\nwrites a fresh `vbrief/.triage-cache/candidates.jsonl`. It does NOT touch the tracked\n`slices.jsonl`; cohort records remain a team-shared resource.\n\n## `merge=union` policy for `*.jsonl`\n\nThe repo-root `.gitattributes` declares:\n\n```\nvbrief/.triage-cache/*.jsonl  merge=union\n```\n\nThe `union` merge driver concatenates both sides' appended lines on\nauto-merge, so two branches that each appended a different record to the\nsame JSON-lines file rebase cleanly without operator surgery. Two things\noperators should know:\n\n- **Concatenation, not set-union.** When two branches append DIFFERENT\n  records to the file, the merge driver concatenates both sides' lines\n  -- there is no smart deduplication of \"semantically similar\" records.\n  (Identical line-for-line appends collapse because git's three-way\n  merge sees them as the same change, but distinct records always\n  survive verbatim, even if a downstream reader would consider them\n  redundant.) The append-only writers in `scripts/candidates_log.py`\n  mint a fresh `decision_id` per call, so genuinely duplicate records\n  are not the expected case, but downstream readers MUST tolerate\n  multiple records describing the same logical decision.\n- **Single-operator scope only.** This is the foundational rebase\n  ergonomic for the single-operator case (operator A rebases their\n  feature branch onto a master that grew while they were AFK).\n  Multi-operator merge-conflict resolution is explicitly out of scope per\n  #1119 R4 (tracked separately as M1-M4 in #1183).\n\n## See also\n\n- Current Shape comment on #1144 for the canonical decisions (the source\n  of truth this README documents).\n- `.gitignore` -- selective gitignore entries for the operator-private\n  files.\n- `.gitattributes` -- the `merge=union` rule.\n- `scripts/candidates_log.py` -- the writer for `candidates.jsonl`.\n";
+export declare const EVAL_README_BODY = "# `vbrief/.triage-cache/` \u2014 triage working-set files\n\nThis directory holds JSON-lines logs and scratch files that Deft triage and\nslicing workflows emit. Deft configures your repo's `.gitignore` and\n`.gitattributes` so some files stay local while team-shared records can be\ncommitted.\n\n## What lives here\n\n| File | Committed? | Notes |\n| --- | --- | --- |\n| `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. |\n| `candidates.jsonl` | No | Your local triage accept / defer / reject stream. Re-create on a fresh clone with `deft triage:bootstrap`. |\n| `summary-history.jsonl` | No | Local history of `deft triage:summary` output; not required for day-to-day work. |\n| `scope-lifecycle.jsonl` | No | Local audit trail for scope demotions (`deft scope:demote`). Each operator's stream stays on their machine. |\n| `decompositions/` | No | Draft story-decomposition scratch. Produced child story xBRIEFs live in lifecycle folders via `deft scope:decompose`. |\n| `doctor-state.json` | No | Per-clone throttle state for `deft doctor` re-probe timing. |\n\nPaths listed as \"No\" above are added to `.gitignore` during bootstrap; anything\nnot listed remains committable by default. The selective ignore entries live in\nthe repo-root `.gitignore` (`vbrief/.triage-cache/candidates.jsonl`,\n`vbrief/.triage-cache/summary-history.jsonl`, `vbrief/.triage-cache/scope-lifecycle.jsonl`,\n`vbrief/.triage-cache/decompositions/`, and `vbrief/.triage-cache/doctor-state.json`).\n\n## Fresh clone\n\nIf `candidates.jsonl` is missing, run:\n\n```\ndeft triage:bootstrap\n```\n\nBootstrap rebuilds the local candidates log without altering committed\n`slices.jsonl`.\n\n## Merge behavior for `*.jsonl`\n\nThe repo-root `.gitattributes` may declare:\n\n```\nvbrief/.triage-cache/*.jsonl  merge=union\n```\n\nThe `union` merge driver concatenates both sides' appended lines on auto-merge,\nso parallel append-only edits to the same JSON-lines file rebase without manual\nconflict surgery. It does not dedupe semantically similar records \u2014 downstream\nreaders should tolerate duplicate-looking entries.\n\n## See also\n\n- `.gitignore` \u2014 selective ignore rules for operator-private files\n- `.gitattributes` \u2014 merge driver for committed JSON-lines logs\n";
 /** Layout-aware triage-cache README body for the active lifecycle tree (#2344 / #2349). */
 export declare function generateTriageCacheReadmeBody(projectRoot: string): string;
 /** Strip an inline `# ...` comment from a gitignore line. */

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/triage/queue/cache.d.ts

@@ -1,4 +1,18 @@
 import type { CachedIssue } from "./types.js";
+/** Neutral title shown when the scanner fences injection-shaped title text. */
+export declare const QUARANTINED_TITLE_PLACEHOLDER = "[quarantined title]";
+/**
+ * Read `meta.json` `scan_result.passed` for a cache entry.
+ * Returns `false` when the scanner hard-failed, `true` when it passed, and
+ * `null` when meta is missing/unreadable (legacy or incomplete entries).
+ */
+export declare function readCacheScanPassed(entryDir: string): boolean | null;
+/**
+ * Sanitize a queue title through the cache scanner.
+ * Returns `null` when the title hard-fails (omit the issue); otherwise a
+ * display title that never carries unfenced injection-shaped attacker text.
+ */
+export declare function sanitizeQueueTitle(rawTitle: string): string | null;
 /** Read slices.jsonl records. */
 export declare function resolveSlicesLogPath(options?: {
     readonly slicesLogPath?: string | null;

package/dist/triage/queue/cache.js

@@ -1,10 +1,58 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { scan } from "../../cache/scanner.js";
 import { resolveTriageCachePath } from "../cache-path.js";
 import { extractAuthor, extractMilestone } from "../scope-drift/cache-walker.js";
 import { CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE } from "./constants.js";
 import { hasActiveScopeIgnores, isRawIssueScopeIgnored, resolveScopeIgnores, } from "./scope-ignores-filter.js";
 import { blockedByIssueNumber, rankByIssueNumber } from "./scope-walk.js";
+/** Neutral title shown when the scanner fences injection-shaped title text. */
+export const QUARANTINED_TITLE_PLACEHOLDER = "[quarantined title]";
+/**
+ * Read `meta.json` `scan_result.passed` for a cache entry.
+ * Returns `false` when the scanner hard-failed, `true` when it passed, and
+ * `null` when meta is missing/unreadable (legacy or incomplete entries).
+ */
+export function readCacheScanPassed(entryDir) {
+    const metaPath = join(entryDir, "meta.json");
+    if (!existsSync(metaPath)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(metaPath, { encoding: "utf8" }));
+        if (typeof parsed !== "object" || parsed === null) {
+            return null;
+        }
+        const scanResult = parsed.scan_result;
+        if (typeof scanResult !== "object" || scanResult === null) {
+            return null;
+        }
+        const passed = scanResult.passed;
+        return typeof passed === "boolean" ? passed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Sanitize a queue title through the cache scanner.
+ * Returns `null` when the title hard-fails (omit the issue); otherwise a
+ * display title that never carries unfenced injection-shaped attacker text.
+ */
+export function sanitizeQueueTitle(rawTitle) {
+    const result = scan(rawTitle);
+    if (!result.passed) {
+        return null;
+    }
+    if (result.flags.some((flag) => flag.category === "injection-heading")) {
+        return QUARANTINED_TITLE_PLACEHOLDER;
+    }
+    if (result.flags.some((flag) => flag.category === "invisible-unicode")) {
+        const stripped = result.transformed_content.replace(/\r?\n+$/u, "");
+        return stripped.length > 0 ? stripped : QUARANTINED_TITLE_PLACEHOLDER;
+    }
+    return rawTitle;
+}
 function cachedState(issue) {
     if (issue === undefined) {
         return "";
@@ -158,9 +206,21 @@ export function loadCachedIssues(repo, options) {
         if (filterScopeIgnores && isRawIssueScopeIgnored(payload, scopeIgnores)) {
             continue;
         }
+        // Fail closed on scanner hard-fail: cachePut keeps raw.json but suppresses
+        // content.md when scan_result.passed is false. The queue must not promote
+        // those titles into the mandatory triage:queue agent context.
+        const scanPassed = readCacheScanPassed(entryDir);
+        if (scanPassed === false) {
+            continue;
+        }
+        const rawTitle = typeof payload.title === "string" ? payload.title : "";
+        const safeTitle = sanitizeQueueTitle(rawTitle);
+        if (safeTitle === null) {
+            continue;
+        }
         issues.push({
             number: n,
-            title: typeof payload.title === "string" ? payload.title : "",
+            title: safeTitle,
             state,
             labels: parseLabels(payload.labels),
             author: extractAuthor(payload),

package/dist/validate-content/validate-links.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, relative, resolve, sep } from "node:path";
 import { extractLinkTargets, shouldSkipLinkTarget } from "./link-parser.js";
 const EXCLUDE_DIRS = new Set([
     ".git",
@@ -55,7 +55,7 @@ function findBrokenLinks(cwd) {
         catch {
             continue;
         }
-        const rel = md.startsWith(`${root}/`) ? md.slice(root.length + 1) : md;
+        const rel = md.startsWith(root + sep) ? relative(root, md) : md;
         const lines = text.split("\n");
         for (let i = 0; i < lines.length; i += 1) {
             const line = lines[i] ?? "";

package/dist/value/readback.d.ts

@@ -71,6 +71,7 @@ export declare function runValueShow(options: {
     format?: "text" | "json";
     logPath?: string | null;
     policyOverride?: ValueFeedbackResolved;
+    now?: Date;
 }): ValueShowResult;
 export interface ValueShowCliArgs {
     window?: string;

package/dist/value/readback.js

@@ -415,7 +415,11 @@ export function runValueShow(options) {
         };
     }
     const windowMs = parseWindowMs(options.window);
-    const trend = computeValueShowTrend(root, { windowMs, logPath: options.logPath });
+    const trend = computeValueShowTrend(root, {
+        windowMs,
+        logPath: options.logPath,
+        now: options.now,
+    });
     const empty = trend.total === 0;
     if (options.format === "json") {
         return {

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/verify-env/toolchain-check.js

@@ -20,16 +20,31 @@ export const CONSUMER_TOOLS = [
 export const TOOLS = MAINTAINER_TOOLS;
 const DEFAULT_TIMEOUT_MS = 10_000;
 export function defaultCommandRunner(command, timeoutMs) {
+    const bin = command[0] ?? "";
+    const args = command.slice(1);
+    const trySpawn = (shell) => childProcess.execFileSync(bin, args, {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        stdio: ["ignore", "pipe", "pipe"],
+        shell,
+    });
     try {
-        const stdout = childProcess.execFileSync(command[0] ?? "", command.slice(1), {
-            encoding: "utf8",
-            timeout: timeoutMs,
-            stdio: ["ignore", "pipe", "pipe"],
-        });
+        const stdout = trySpawn(false);
         return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
     }
     catch (err) {
         const e = err;
+        // win32: npm global shims are `.cmd` and need shell/PATHEXT (#2467 / #2415).
+        if (e.code === "ENOENT" && process.platform === "win32") {
+            try {
+                const stdout = trySpawn(true);
+                return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
+            }
+            catch {
+                // Shell still failed — binary is absent (cmd.exe often exits 1, not ENOENT).
+                return { error: "not-found", message: "" };
+            }
+        }
         if (e.code === "ENOENT") {
             return { error: "not-found", message: "" };
         }

package/dist/verify-env/verify-hooks-installed.d.ts

@@ -5,6 +5,7 @@ export interface EvaluateResult {
     readonly stream: OutputStream;
 }
 export declare const REQUIRED_HOOKS: readonly ["pre-commit", "pre-push"];
+export declare const REQUIRED_HOOK_SUPPORT_FILES: readonly ["_deft-run.sh"];
 /** Substrings each hook must contain when it dispatches through the deft CLI (#2049). */
 export declare const PRE_COMMIT_DEFT_COMMANDS: readonly ["verify:branch", "verify:encoding"];
 export declare const PRE_PUSH_DEFT_COMMANDS: readonly ["preflight-gh"];
@@ -15,6 +16,7 @@ export type GitConfigReader = (projectRoot: string) => {
 export interface EvaluateOptions {
     readonly gitConfigReader?: GitConfigReader;
     readonly platform?: NodeJS.Platform;
+    readonly hookExecutable?: (hookPath: string) => boolean;
 }
 /** Drop shell ``#`` comment lines before pattern scans (#2049 shipped-hook false positives). */
 export declare function stripShellCommentLines(content: string): string;

package/dist/verify-env/verify-hooks-installed.js

@@ -2,6 +2,7 @@ import * as childProcess from "node:child_process";
 import { accessSync, constants, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 export const REQUIRED_HOOKS = ["pre-commit", "pre-push"];
+export const REQUIRED_HOOK_SUPPORT_FILES = ["_deft-run.sh"];
 /** Substrings each hook must contain when it dispatches through the deft CLI (#2049). */
 export const PRE_COMMIT_DEFT_COMMANDS = ["verify:branch", "verify:encoding"];
 export const PRE_PUSH_DEFT_COMMANDS = ["preflight-gh"];
@@ -52,7 +53,7 @@ function isDirectory(path) {
 function isPosix(platform) {
     return platform !== "win32";
 }
-function hookExecutable(hookPath) {
+function defaultHookExecutable(hookPath) {
     try {
         accessSync(hookPath, constants.X_OK);
         return true;
@@ -112,6 +113,7 @@ export function evaluate(projectRoot, options = {}) {
     const root = resolve(projectRoot);
     const gitReader = options.gitConfigReader ?? defaultGitConfigReader;
     const platform = options.platform ?? process.platform;
+    const hookExecutable = options.hookExecutable ?? defaultHookExecutable;
     if (!isDirectory(root)) {
         return {
             code: 2,
@@ -173,29 +175,29 @@ export function evaluate(projectRoot, options = {}) {
             };
         }
     }
+    const contentIssues = [];
+    const missingSupport = REQUIRED_HOOK_SUPPORT_FILES.filter((h) => !isFile(join(hooksDir, h)));
+    if (missingSupport.length > 0) {
+        contentIssues.push(`${hooksDir} is missing ${missingSupport.join(", ")} helper(s); pre-commit/pre-push source them at runtime`);
+    }
     const preCommitIssue = validateHookContent("pre-commit", readHookContent(join(hooksDir, "pre-commit")), PRE_COMMIT_DEFT_COMMANDS);
     if (preCommitIssue) {
-        return {
-            code: 1,
-            message: `❌ deft hooks wired but NON-FUNCTIONAL: ${preCommitIssue} (#2049).\n` +
-                "  Recovery: re-run the deft installer / `task setup` to refresh .githooks/.",
-            stream: "stderr",
-        };
+        contentIssues.push(`${preCommitIssue} (#2049)`);
     }
     const prePushContent = readHookContent(join(hooksDir, "pre-push"));
     const prePushIssue = validateHookContent("pre-push", prePushContent, PRE_PUSH_DEFT_COMMANDS);
     if (prePushIssue) {
-        return {
-            code: 1,
-            message: `❌ deft hooks wired but NON-FUNCTIONAL: ${prePushIssue} (#2049).\n` +
-                "  Recovery: re-run the deft installer / `task setup` to refresh .githooks/.",
-            stream: "stderr",
-        };
+        contentIssues.push(`${prePushIssue} (#2049)`);
     }
     if (prePushContent && prePushInvokesVerifyBranch(prePushContent)) {
+        contentIssues.push("pre-push must not invoke verify:branch (#1814)");
+    }
+    if (contentIssues.length > 0) {
         return {
             code: 1,
-            message: "❌ deft hooks wired but NON-FUNCTIONAL: pre-push must not invoke verify:branch (#1814).\n" +
+            message: "❌ deft hooks wired but NON-FUNCTIONAL:\n" +
+                contentIssues.map((issue) => `  - ${issue.replace(/\r?\n/g, " ")}`).join("\n") +
+                "\n" +
                 "  Recovery: re-run the deft installer / `task setup` to refresh .githooks/.",
             stream: "stderr",
         };
@@ -203,7 +205,7 @@ export function evaluate(projectRoot, options = {}) {
     return {
         code: 0,
         message: `✓ deft hooks installed and functional: core.hooksPath=${hooksPath}, ` +
-            `hooks ${REQUIRED_HOOKS.join(", ")} present and dispatch via deft CLI (#2049).`,
+            `hooks ${REQUIRED_HOOKS.join(", ")} plus ${REQUIRED_HOOK_SUPPORT_FILES.join(", ")} present and dispatch via deft CLI (#2049).`,
         stream: "stdout",
     };
 }

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.`,