@deftai/directive-core 0.105.0 → 0.107.0

package/dist/triage/evaluate/validity.js

@@ -0,0 +1,87 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { listXbriefHits } from "./xbrief-refs.js";
+const ADR_DIR = join("docs", "decisions");
+const CONTRACT_DIR = join("content", "contracts");
+function filesMentionIssue(dir, issue) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    const needle = `#${issue}`;
+    const hits = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".md")) {
+            continue;
+        }
+        const path = join(dir, name);
+        try {
+            const text = readFileSync(path, "utf8");
+            if (text.includes(needle) || text.includes(`/issues/${issue}`)) {
+                hits.push(path);
+            }
+        }
+        catch { }
+    }
+    return hits;
+}
+/**
+ * Evaluator-owned. Reads only `worktreeRoot` (detached origin/master).
+ * Must not accept a WIP census argument.
+ */
+export function evaluateValidity(worktreeRoot, issue) {
+    const completed = listXbriefHits(worktreeRoot, "completed").filter((hit) => hit.issue === issue);
+    const pending = listXbriefHits(worktreeRoot, "pending").filter((hit) => hit.issue === issue);
+    const active = listXbriefHits(worktreeRoot, "active").filter((hit) => hit.issue === issue);
+    const proposed = listXbriefHits(worktreeRoot, "proposed").filter((hit) => hit.issue === issue);
+    const adrHits = filesMentionIssue(join(worktreeRoot, ADR_DIR), issue);
+    const contractHits = filesMentionIssue(join(worktreeRoot, CONTRACT_DIR), issue);
+    if (completed.length > 0) {
+        return {
+            state: "likely-shipped",
+            evidence: `completed xbrief on origin/master: ${completed[0]?.path}`,
+            worktreePath: worktreeRoot,
+            sessionStartReadOnly: true,
+        };
+    }
+    if (pending.length > 0 || active.length > 0 || proposed.length > 0) {
+        const hit = pending[0] ?? active[0] ?? proposed[0];
+        return {
+            state: "partial",
+            evidence: `committed lifecycle xbrief on origin/master: ${hit?.path}`,
+            worktreePath: worktreeRoot,
+            sessionStartReadOnly: true,
+        };
+    }
+    if (adrHits.length > 0 || contractHits.length > 0) {
+        return {
+            state: "partial",
+            evidence: `ADR/contract mention on origin/master: ${adrHits[0] ?? contractHits[0] ?? ""}`,
+            worktreePath: worktreeRoot,
+            sessionStartReadOnly: true,
+        };
+    }
+    return {
+        state: "still-open",
+        evidence: "no origin/master lifecycle coverage, ADR, or contract mention",
+        worktreePath: worktreeRoot,
+        sessionStartReadOnly: true,
+    };
+}
+export function joinValidityWithGithub(validity, githubState) {
+    if (githubState === "closed" && validity.state === "still-open") {
+        return {
+            ...validity,
+            state: "likely-shipped",
+            evidence: `${validity.evidence}; GitHub issue state=closed`,
+        };
+    }
+    if (githubState === "open" && validity.state === "likely-shipped") {
+        return {
+            ...validity,
+            state: "needs-re-scope",
+            evidence: `${validity.evidence}; GitHub issue still open`,
+        };
+    }
+    return validity;
+}
+//# sourceMappingURL=validity.js.map

package/dist/triage/evaluate/value.d.ts

@@ -0,0 +1,12 @@
+import { type GithubIssueSnapshot, type ValueAdvice } from "./types.js";
+export declare class ReservedClearanceError extends Error {
+    name: string;
+}
+export declare function assertNoReservedClearance(text: string, label: string): void;
+/**
+ * Value MAY recommend critique via `critique-recommend:`.
+ * It MUST NOT stamp the reserved ADR-005 clearance grammar.
+ */
+export declare function buildValueAdvice(issue: GithubIssueSnapshot | null): ValueAdvice;
+export declare function formatValueField(advice: ValueAdvice): string;
+//# sourceMappingURL=value.d.ts.map

package/dist/triage/evaluate/value.js

@@ -0,0 +1,33 @@
+import { CRITIQUE_RECOMMEND_FIELD, RESERVED_CLEARANCE_RE, } from "./types.js";
+export class ReservedClearanceError extends Error {
+    name = "ReservedClearanceError";
+}
+export function assertNoReservedClearance(text, label) {
+    if (RESERVED_CLEARANCE_RE.test(text)) {
+        throw new ReservedClearanceError(`${label} must not emit the reserved clearance line ` +
+            "`design-critique: warranted | not warranted, because …`");
+    }
+}
+/**
+ * Value MAY recommend critique via `critique-recommend:`.
+ * It MUST NOT stamp the reserved ADR-005 clearance grammar.
+ */
+export function buildValueAdvice(issue) {
+    const labels = issue?.labels ?? [];
+    const stamped = labels.some((label) => label === "design-critique:mechanism-shaped");
+    const reason = stamped
+        ? "GitHub label design-critique:mechanism-shaped is present; author still stamps clearance"
+        : "no mechanism-shaped stamp; critique not recommended from evaluation";
+    const advice = {
+        [CRITIQUE_RECOMMEND_FIELD]: stamped,
+        reason,
+    };
+    assertNoReservedClearance(JSON.stringify(advice), "value advice");
+    return advice;
+}
+export function formatValueField(advice) {
+    const line = `${CRITIQUE_RECOMMEND_FIELD}: ${advice[CRITIQUE_RECOMMEND_FIELD] ? "true" : "false"}`;
+    assertNoReservedClearance(`${line}\n${advice.reason}`, "value field");
+    return `${line}\n${advice.reason}`;
+}
+//# sourceMappingURL=value.js.map

package/dist/triage/evaluate/wip-census.d.ts

@@ -0,0 +1,5 @@
+import type { WipCensus, WipHit } from "./types.js";
+/** Parent-owned. Evaluators must never receive this object. */
+export declare function collectWipCensus(projectRoot: string, issues: readonly number[]): WipCensus;
+export declare function wipHitsForIssue(census: WipCensus, issue: number): WipHit[];
+//# sourceMappingURL=wip-census.d.ts.map

package/dist/triage/evaluate/wip-census.js

@@ -0,0 +1,39 @@
+import { readPlanSequence } from "../../plan-sequence/store.js";
+import { listXbriefHits } from "./xbrief-refs.js";
+function hitsForIssues(hits, issues, kind) {
+    return hits
+        .filter((hit) => issues.has(hit.issue))
+        .map((hit) => ({ kind, path: hit.path, issue: hit.issue }));
+}
+/** Parent-owned. Evaluators must never receive this object. */
+export function collectWipCensus(projectRoot, issues) {
+    const wanted = new Set(issues);
+    const activeHits = listXbriefHits(projectRoot, "active");
+    const pendingHits = listXbriefHits(projectRoot, "pending");
+    const planHits = [];
+    const sequence = readPlanSequence(projectRoot);
+    if (sequence !== null) {
+        for (const entry of sequence.entries) {
+            const fromField = entry.issue;
+            const fromId = Number.parseInt(entry.id.trim().replace(/^#/u, ""), 10);
+            const asNumber = typeof fromField === "number" ? fromField : fromId;
+            if (!Number.isFinite(asNumber) || !wanted.has(asNumber)) {
+                continue;
+            }
+            planHits.push({
+                kind: "plan-sequence",
+                path: ".deft/plan-sequence.json",
+                issue: asNumber,
+            });
+        }
+    }
+    return {
+        active: hitsForIssues(activeHits, wanted, "active-xbrief"),
+        pending: hitsForIssues(pendingHits, wanted, "pending-xbrief"),
+        planSequence: planHits,
+    };
+}
+export function wipHitsForIssue(census, issue) {
+    return [...census.active, ...census.pending, ...census.planSequence].filter((hit) => hit.issue === issue);
+}
+//# sourceMappingURL=wip-census.js.map

package/dist/triage/evaluate/worktrees.d.ts

@@ -0,0 +1,8 @@
+import type { GitRunner } from "./types.js";
+export declare class EvaluatorWorktreeError extends Error {
+    name: string;
+}
+export declare function addEvaluatorWorktree(projectRoot: string, issue: number, invocationId: string, originSha: string, git?: GitRunner): string;
+/** Verb-owned remove. Not a shared core git-worktree helper. */
+export declare function removeEvaluatorWorktree(projectRoot: string, worktreePath: string, git?: GitRunner): void;
+//# sourceMappingURL=worktrees.d.ts.map

package/dist/triage/evaluate/worktrees.js

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { defaultGitRunner as swarmGitRunner, } from "../../swarm/worktrees.js";
+import { evaluatorWorktreePath } from "./paths.js";
+export class EvaluatorWorktreeError extends Error {
+    name = "EvaluatorWorktreeError";
+}
+function toSwarm(git) {
+    return (args, cwd) => git(args, cwd);
+}
+export function addEvaluatorWorktree(projectRoot, issue, invocationId, originSha, git = swarmGitRunner) {
+    const sha = originSha.trim();
+    if (sha.length === 0) {
+        throw new EvaluatorWorktreeError("originSha is required for a detached evaluator worktree");
+    }
+    const worktreePath = evaluatorWorktreePath(projectRoot, issue, invocationId);
+    mkdirSync(dirname(resolve(worktreePath)), { recursive: true });
+    const proc = toSwarm(git)(["worktree", "add", "--detach", worktreePath, sha], projectRoot);
+    if (proc.returncode !== 0) {
+        throw new EvaluatorWorktreeError(`git worktree add --detach failed for issue ${issue}: ${proc.stderr.trim() || "<no stderr>"}`);
+    }
+    return worktreePath;
+}
+function forceDeleteWorktreeDir(worktreePath) {
+    if (!existsSync(worktreePath)) {
+        return;
+    }
+    rmSync(worktreePath, { recursive: true, force: true });
+}
+function worktreeStillRegistered(git, projectRoot, worktreePath) {
+    const listed = git(["worktree", "list", "--porcelain"], projectRoot);
+    if (listed.returncode !== 0) {
+        return true;
+    }
+    const needle = resolve(worktreePath).replace(/\\/g, "/").toLowerCase();
+    for (const line of listed.stdout.split(/\r?\n/u)) {
+        if (!line.startsWith("worktree ")) {
+            continue;
+        }
+        const listedPath = line.slice("worktree ".length).replace(/\\/g, "/").toLowerCase();
+        if (listedPath === needle) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Verb-owned remove. Not a shared core git-worktree helper. */
+export function removeEvaluatorWorktree(projectRoot, worktreePath, git = swarmGitRunner) {
+    const runner = toSwarm(git);
+    const proc = runner(["worktree", "remove", "--force", worktreePath], projectRoot);
+    if (proc.returncode === 0) {
+        return;
+    }
+    const firstError = proc.stderr.trim() || "<no stderr>";
+    forceDeleteWorktreeDir(worktreePath);
+    runner(["worktree", "prune"], projectRoot);
+    const retry = runner(["worktree", "remove", "--force", worktreePath], projectRoot);
+    if (retry.returncode === 0) {
+        return;
+    }
+    forceDeleteWorktreeDir(worktreePath);
+    runner(["worktree", "prune"], projectRoot);
+    if (!worktreeStillRegistered(runner, projectRoot, worktreePath) && !existsSync(worktreePath)) {
+        return;
+    }
+    throw new EvaluatorWorktreeError(`git worktree remove failed for ${worktreePath}: ${firstError}; fallback: ${retry.stderr.trim() || "<no stderr>"}`);
+}
+//# sourceMappingURL=worktrees.js.map

package/dist/triage/evaluate/xbrief-refs.d.ts

@@ -0,0 +1,8 @@
+export interface XbriefHit {
+    readonly issue: number;
+    readonly path: string;
+    readonly folder: "active" | "pending" | "proposed" | "completed" | "cancelled";
+}
+export declare function issueNumbersFromXbriefJson(raw: unknown): number[];
+export declare function listXbriefHits(root: string, folder: XbriefHit["folder"]): XbriefHit[];
+//# sourceMappingURL=xbrief-refs.d.ts.map

package/dist/triage/evaluate/xbrief-refs.js

@@ -0,0 +1,60 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const ISSUE_URI_RE = /\/issues\/(\d+)\b/u;
+const ISSUE_HASH_RE = /(?:Issue\s+)?#(\d+)\b/u;
+function numbersFromUnknown(value, into) {
+    if (typeof value === "string") {
+        for (const re of [ISSUE_URI_RE, ISSUE_HASH_RE]) {
+            const match = re.exec(value);
+            if (match?.[1] !== undefined) {
+                into.add(Number.parseInt(match[1], 10));
+            }
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            numbersFromUnknown(item, into);
+        }
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const nested of Object.values(value)) {
+            numbersFromUnknown(nested, into);
+        }
+    }
+}
+export function issueNumbersFromXbriefJson(raw) {
+    const found = new Set();
+    if (raw === null || typeof raw !== "object") {
+        return [];
+    }
+    const plan = raw.plan;
+    numbersFromUnknown(plan?.references, found);
+    return [...found];
+}
+export function listXbriefHits(root, folder) {
+    const dir = join(root, "xbrief", folder);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    const hits = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".xbrief.json") && !name.endsWith(".vbrief.json")) {
+            continue;
+        }
+        const path = join(dir, name);
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        for (const issue of issueNumbersFromXbriefJson(parsed)) {
+            hits.push({ issue, path, folder });
+        }
+    }
+    return hits;
+}
+//# sourceMappingURL=xbrief-refs.js.map

package/dist/triage/help/registry-data.d.ts

@@ -23,6 +23,17 @@ export declare const registryData: {
             readonly see_also: readonly ["task triage:bootstrap", "task cache:fetch-all", "#1119 / D5"];
             readonly placeholder: false;
         };
+        readonly "task triage:evaluate": {
+            readonly name: "task triage:evaluate";
+            readonly summary: "Isolated validity + parent WIP census + value advice";
+            readonly refs: "(#3648)";
+            readonly description: "Stage A issue-eval: detached origin/master worktrees own validity and ADR/contract reads; the parent on the live working set owns WIP census (xbrief/active, xbrief/pending, plan-sequence); GitHub REST owns open PRs/issues/duplicates. Writes a gitignored sink under .deft-scratch/issue-eval/<sha12>/<invocation-id>/. No GitHub writes. No candidates-log row. Value may set critique-recommend: and must not emit the reserved design-critique clearance line. Fan-out default 4, override --concurrency N.";
+            readonly usage: "task triage:evaluate -- <N...> [--concurrency N] [--repo OWNER/NAME] [--json]";
+            readonly flags: readonly [readonly ["<N...>", "(required)", "Issue numbers to evaluate."], readonly ["--concurrency N", "4", "Parallel evaluator cap (bind, not a measured existing cap)."], readonly ["--repo OWNER/NAME", "(git remote / env)", "Upstream repo for REST reads."], readonly ["--json", "(off)", "Emit the structured EvaluateResult."], readonly ["--project-root PATH", "(cwd)", "Project root override (Taskfile threads USER_WORKING_DIR)."]];
+            readonly examples: readonly ["task triage:evaluate -- 3648", "task triage:evaluate -- 10 11 --concurrency 2 --json"];
+            readonly see_also: readonly ["task triage:queue", "task triage:accept", "skills/deft-directive-issue-eval/SKILL.md", "#3648"];
+            readonly placeholder: false;
+        };
         readonly "task triage:accept": {
             readonly name: "task triage:accept";
             readonly summary: "Mark issue accepted; chains into scope:promote w/ flag";
@@ -357,7 +368,7 @@ export declare const registryData: {
             readonly name: "task triage:metrics";
             readonly summary: "Attributed-value trend from the events ledger";
             readonly refs: "(#1709)";
-            readonly description: "Report value-feedback attribution trends from .deft-cache/events.jsonl: total signal count plus per-class (value, bypass, adoption, friction) and per-event breakdowns over a time window. Alias of the value:show handler. Requires plan.policy.valueFeedback.enabled (default OFF) — exits blocked when disabled; an empty ledger prints a no-signals message. In the maintainer repo, skipped unless DEFT_VALUE_SELF_DOGFOOD=1.";
+            readonly description: "Report value-feedback attribution trends from .deft-cache/events.jsonl: total signal count plus per-class (value, bypass, adoption, friction) and per-event breakdowns over a time window. Also composes a ceremony-cost rollup (#3508): last cold vs re-arm CLI process time, per-step ms, blocked-ritual count, recovery-tier distribution. Alias of the value:show handler. Attribution requires plan.policy.valueFeedback.enabled (default OFF) — exits blocked when disabled, but still prints the ceremony-cost section. An empty attribution ledger prints a no-signals message. In the maintainer repo, attribution is skipped unless DEFT_VALUE_SELF_DOGFOOD=1.";
             readonly usage: "task triage:metrics [-- --window=7d] [--format=text|json]";
             readonly flags: readonly [readonly ["--window WINDOW", "7d", "Time window (e.g. 7d, 30d, 24h)."], readonly ["--format text|json", "text", "Output shape (json emits the full trend object)."]];
             readonly examples: readonly ["task triage:metrics", "task triage:metrics -- --window=30d --format=json"];
@@ -444,12 +455,12 @@ export declare const registryData: {
         readonly "task scope:complete": {
             readonly name: "task scope:complete";
             readonly summary: "active/ -> completed/ (set status completed)";
-            readonly refs: "(#845)";
-            readonly description: "Mark an active vBRIEF complete and move it to vbrief/completed/. Terminal transition; use scope:undo if you need reversibility (refused on terminal actions per D15).";
-            readonly usage: "task scope:complete -- <file>";
-            readonly flags: readonly [readonly ["<file>", "(required)", "Path to vBRIEF."], readonly ["--project-root PATH", "(detected)", "Consumer project root override."]];
-            readonly examples: readonly ["task scope:complete -- vbrief/active/2026-05-19-foo.vbrief.json"];
-            readonly see_also: readonly ["task scope:fail", "task scope:cancel", "#1119 / #845"];
+            readonly refs: "(#845, #3041, #3721)";
+            readonly description: "Mark an active vBRIEF complete and move it to vbrief/completed/. Terminal transition; use scope:undo if you need reversibility (refused on terminal actions per D15). Code-bearing completion requires delivery evidence: --merge-commit and --pr. Those flags feed the delivery gate; they do not skip literal-AC.";
+            readonly usage: "task scope:complete -- <file> [--merge-commit SHA] [--pr N]";
+            readonly flags: readonly [readonly ["<file>", "(required)", "Path to vBRIEF."], readonly ["--project-root PATH", "(detected)", "Consumer project root override."], readonly ["--merge-commit SHA", "(required for code-bearing)", "Merge commit SHA for delivery evidence (#3041)."], readonly ["--pr N", "(required for code-bearing)", "Merged PR number for delivery evidence (#3041)."], readonly ["--pr-base BRANCH", "(optional)", "PR base branch for delivery evidence."], readonly ["--delivery-branch BRANCH", "(optional)", "Delivery branch tip for completed-tracked."]];
+            readonly examples: readonly ["task scope:complete -- vbrief/active/2026-05-19-foo.vbrief.json", "task scope:complete -- xbrief/active/story.xbrief.json --merge-commit abc123 --pr 42"];
+            readonly see_also: readonly ["task scope:fail", "task scope:cancel", "#1119 / #845", "#3041"];
             readonly placeholder: false;
         };
         readonly "task scope:fail": {
@@ -530,7 +541,7 @@ export declare const registryData: {
             readonly placeholder: false;
         };
     };
-    readonly categoriesTriage: readonly [readonly ["Session-start", readonly ["task triage:summary", "task verify:cache-fresh"]], readonly ["State verbs (mutate audit log)", readonly ["task triage:accept", "task triage:defer", "task triage:reject", "task triage:needs-ac", "task triage:mark-duplicate", "task triage:reset", "task triage:status", "task triage:history"]], readonly ["Read verbs", readonly ["task triage:queue", "task triage:audit", "task triage:show", "task triage:scope", "task triage:scope-drift", "task triage:classify"]], readonly ["Lifecycle", readonly ["task triage:bootstrap", "task triage:welcome", "task triage:reconcile"]], readonly ["Bulk variants", readonly ["task triage:bulk-accept", "task triage:bulk-reject", "task triage:bulk-defer", "task triage:bulk-needs-ac", "task triage:refresh-active", "task triage:smoketest"]], readonly ["Subscription mutation", readonly ["task triage:subscribe", "task triage:unsubscribe"]], readonly ["Archive / rotation", readonly ["task triage:audit:prune", "task triage:archive-list", "task triage:restore-from-archive", "task triage:audit-log:rotate", "task triage:metrics"]], readonly ["Framework eval (#1703)", readonly ["task eval:health", "task eval:triggers", "task eval:run", "task eval:report"]]];
+    readonly categoriesTriage: readonly [readonly ["Session-start", readonly ["task triage:summary", "task verify:cache-fresh"]], readonly ["State verbs (mutate audit log)", readonly ["task triage:accept", "task triage:defer", "task triage:reject", "task triage:needs-ac", "task triage:mark-duplicate", "task triage:reset", "task triage:status", "task triage:history"]], readonly ["Read verbs", readonly ["task triage:queue", "task triage:evaluate", "task triage:audit", "task triage:show", "task triage:scope", "task triage:scope-drift", "task triage:classify"]], readonly ["Lifecycle", readonly ["task triage:bootstrap", "task triage:welcome", "task triage:reconcile"]], readonly ["Bulk variants", readonly ["task triage:bulk-accept", "task triage:bulk-reject", "task triage:bulk-defer", "task triage:bulk-needs-ac", "task triage:refresh-active", "task triage:smoketest"]], readonly ["Subscription mutation", readonly ["task triage:subscribe", "task triage:unsubscribe"]], readonly ["Archive / rotation", readonly ["task triage:audit:prune", "task triage:archive-list", "task triage:restore-from-archive", "task triage:audit-log:rotate", "task triage:metrics"]], readonly ["Framework eval (#1703)", readonly ["task eval:health", "task eval:triggers", "task eval:run", "task eval:report"]]];
     readonly categoriesScope: readonly [readonly ["Promote / demote", readonly ["task scope:promote", "task scope:demote"]], readonly ["Activate / complete", readonly ["task scope:activate", "task scope:complete", "task scope:fail", "task scope:cancel", "task scope:block", "task scope:unblock"]], readonly ["Reversibility", readonly ["task scope:undo", "task scope:restore"]], readonly ["Decomposition", readonly ["task scope:decompose"]]];
     readonly scriptSubcommandMap: {
         readonly triage_actions: {
@@ -575,6 +586,9 @@ export declare const registryData: {
         readonly triage_reconcile: {
             readonly __default__: "task triage:reconcile";
         };
+        readonly triage_evaluate: {
+            readonly __default__: "task triage:evaluate";
+        };
         readonly triage_queue: {
             readonly queue: "task triage:queue";
             readonly show: "task triage:show";

package/dist/triage/help/registry-data.js

@@ -34,6 +34,35 @@ export const registryData = {
             see_also: ["task triage:bootstrap", "task cache:fetch-all", "#1119 / D5"],
             placeholder: false,
         },
+        "task triage:evaluate": {
+            name: "task triage:evaluate",
+            summary: "Isolated validity + parent WIP census + value advice",
+            refs: "(#3648)",
+            description: "Stage A issue-eval: detached origin/master worktrees own validity and ADR/contract reads; the parent on the live working set owns WIP census (xbrief/active, xbrief/pending, plan-sequence); GitHub REST owns open PRs/issues/duplicates. Writes a gitignored sink under .deft-scratch/issue-eval/<sha12>/<invocation-id>/. No GitHub writes. No candidates-log row. Value may set critique-recommend: and must not emit the reserved design-critique clearance line. Fan-out default 4, override --concurrency N.",
+            usage: "task triage:evaluate -- <N...> [--concurrency N] [--repo OWNER/NAME] [--json]",
+            flags: [
+                ["<N...>", "(required)", "Issue numbers to evaluate."],
+                ["--concurrency N", "4", "Parallel evaluator cap (bind, not a measured existing cap)."],
+                ["--repo OWNER/NAME", "(git remote / env)", "Upstream repo for REST reads."],
+                ["--json", "(off)", "Emit the structured EvaluateResult."],
+                [
+                    "--project-root PATH",
+                    "(cwd)",
+                    "Project root override (Taskfile threads USER_WORKING_DIR).",
+                ],
+            ],
+            examples: [
+                "task triage:evaluate -- 3648",
+                "task triage:evaluate -- 10 11 --concurrency 2 --json",
+            ],
+            see_also: [
+                "task triage:queue",
+                "task triage:accept",
+                "skills/deft-directive-issue-eval/SKILL.md",
+                "#3648",
+            ],
+            placeholder: false,
+        },
         "task triage:accept": {
             name: "task triage:accept",
             summary: "Mark issue accepted; chains into scope:promote w/ flag",
@@ -628,7 +657,7 @@ export const registryData = {
             name: "task triage:metrics",
             summary: "Attributed-value trend from the events ledger",
             refs: "(#1709)",
-            description: "Report value-feedback attribution trends from .deft-cache/events.jsonl: total signal count plus per-class (value, bypass, adoption, friction) and per-event breakdowns over a time window. Alias of the value:show handler. Requires plan.policy.valueFeedback.enabled (default OFF) — exits blocked when disabled; an empty ledger prints a no-signals message. In the maintainer repo, skipped unless DEFT_VALUE_SELF_DOGFOOD=1.",
+            description: "Report value-feedback attribution trends from .deft-cache/events.jsonl: total signal count plus per-class (value, bypass, adoption, friction) and per-event breakdowns over a time window. Also composes a ceremony-cost rollup (#3508): last cold vs re-arm CLI process time, per-step ms, blocked-ritual count, recovery-tier distribution. Alias of the value:show handler. Attribution requires plan.policy.valueFeedback.enabled (default OFF) — exits blocked when disabled, but still prints the ceremony-cost section. An empty attribution ledger prints a no-signals message. In the maintainer repo, attribution is skipped unless DEFT_VALUE_SELF_DOGFOOD=1.",
             usage: "task triage:metrics [-- --window=7d] [--format=text|json]",
             flags: [
                 ["--window WINDOW", "7d", "Time window (e.g. 7d, 30d, 24h)."],
@@ -782,15 +811,30 @@ export const registryData = {
         "task scope:complete": {
             name: "task scope:complete",
             summary: "active/ -> completed/ (set status completed)",
-            refs: "(#845)",
-            description: "Mark an active vBRIEF complete and move it to vbrief/completed/. Terminal transition; use scope:undo if you need reversibility (refused on terminal actions per D15).",
-            usage: "task scope:complete -- <file>",
+            refs: "(#845, #3041, #3721)",
+            description: "Mark an active vBRIEF complete and move it to vbrief/completed/. Terminal transition; use scope:undo if you need reversibility (refused on terminal actions per D15). Code-bearing completion requires delivery evidence: --merge-commit and --pr. Those flags feed the delivery gate; they do not skip literal-AC.",
+            usage: "task scope:complete -- <file> [--merge-commit SHA] [--pr N]",
             flags: [
                 ["<file>", "(required)", "Path to vBRIEF."],
                 ["--project-root PATH", "(detected)", "Consumer project root override."],
+                [
+                    "--merge-commit SHA",
+                    "(required for code-bearing)",
+                    "Merge commit SHA for delivery evidence (#3041).",
+                ],
+                [
+                    "--pr N",
+                    "(required for code-bearing)",
+                    "Merged PR number for delivery evidence (#3041).",
+                ],
+                ["--pr-base BRANCH", "(optional)", "PR base branch for delivery evidence."],
+                ["--delivery-branch BRANCH", "(optional)", "Delivery branch tip for completed-tracked."],
             ],
-            examples: ["task scope:complete -- vbrief/active/2026-05-19-foo.vbrief.json"],
-            see_also: ["task scope:fail", "task scope:cancel", "#1119 / #845"],
+            examples: [
+                "task scope:complete -- vbrief/active/2026-05-19-foo.vbrief.json",
+                "task scope:complete -- xbrief/active/story.xbrief.json --merge-commit abc123 --pr 42",
+            ],
+            see_also: ["task scope:fail", "task scope:cancel", "#1119 / #845", "#3041"],
             placeholder: false,
         },
         "task scope:fail": {
@@ -930,6 +974,7 @@ export const registryData = {
             "Read verbs",
             [
                 "task triage:queue",
+                "task triage:evaluate",
                 "task triage:audit",
                 "task triage:show",
                 "task triage:scope",
@@ -1024,6 +1069,9 @@ export const registryData = {
         triage_reconcile: {
             __default__: "task triage:reconcile",
         },
+        triage_evaluate: {
+            __default__: "task triage:evaluate",
+        },
         triage_queue: {
             queue: "task triage:queue",
             show: "task triage:show",

package/dist/triage/index.d.ts

@@ -13,6 +13,7 @@ export * as bulk from "./bulk/index.js";
 export * as cachePath from "./cache-path.js";
 export * from "./cache-path.js";
 export * as classify from "./classify/index.js";
+export * as evaluate from "./evaluate/index.js";
 export * as help from "./help/index.js";
 export * as queue from "./queue/index.js";
 export * as reconcile from "./reconcile/index.js";

package/dist/triage/index.js

@@ -13,6 +13,7 @@ export * as bulk from "./bulk/index.js";
 export * as cachePath from "./cache-path.js";
 export * from "./cache-path.js";
 export * as classify from "./classify/index.js";
+export * as evaluate from "./evaluate/index.js";
 export * as help from "./help/index.js";
 export * as queue from "./queue/index.js";
 export * as reconcile from "./reconcile/index.js";

package/dist/triage/welcome/writers.d.ts

@@ -1,4 +1,4 @@
-export declare function appendAuditEntry(projectRoot: string, entry: string): string;
+export declare function appendAuditEntry(projectRoot: string, entry: string, changed?: boolean): string;
 export declare function writeTriageScope(projectRoot: string, rules: Array<Record<string, unknown>>, options?: {
     presetLabel: string;
     actor?: string;

package/dist/triage/welcome/writers.js

@@ -4,6 +4,7 @@ import { containedWrite } from "../../fs/contained-write.js";
 import { assertWriteTargetSafe } from "../../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_ONBOARDING_KEY, PLAN_POLICY_KEY, } from "../../policy/plan-extensions.js";
+import { stampChangedToken } from "../../policy/resolve.js";
 import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
 import { AUDIT_LOG_REL_PATH, DEFAULT_RELIEF_AGE_DAYS, DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, WELCOME_AUDIT_TAG, } from "./constants.js";
 function projectDefinitionPath(projectRoot) {
@@ -12,9 +13,13 @@ function projectDefinitionPath(projectRoot) {
 function utcIso() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
-export function appendAuditEntry(projectRoot, entry) {
+export function appendAuditEntry(projectRoot, entry, changed = true) {
     const root = resolve(projectRoot);
     const logPath = join(root, AUDIT_LOG_REL_PATH);
+    const stamped = stampChangedToken(entry, changed);
+    if (!changed) {
+        return logPath;
+    }
     // #2980 wave D: product write sink routes through containedWrite.
     mkdirSync(root, { recursive: true });
     if (!existsSync(logPath)) {
@@ -28,7 +33,7 @@ export function appendAuditEntry(projectRoot, entry) {
     containedWrite({
         root,
         target: AUDIT_LOG_REL_PATH,
-        data: `${utcIso()} ${entry}\n`,
+        data: `${utcIso()} ${stamped}\n`,
         mode: "append",
     });
     return logPath;
@@ -102,7 +107,7 @@ export function writeTriageScope(projectRoot, rules, options = { presetLabel: "c
             `rule_count=${rules.length}`,
             `changed=${changed ? "true" : "false"}`,
         ].join(" ");
-        appendAuditEntry(projectRoot, auditEntry);
+        appendAuditEntry(projectRoot, auditEntry, changed);
         return [changed, auditEntry];
     });
 }
@@ -153,7 +158,7 @@ export function writeWipCapDecision(projectRoot, options = {}) {
             `acceptedDefault=${acceptedDefault ? "true" : "false"}`,
             `changed=${changed ? "true" : "false"}`,
         ].join(" ");
-        appendAuditEntry(projectRoot, auditEntry);
+        appendAuditEntry(projectRoot, auditEntry, changed);
         return [changed, auditEntry];
     });
 }
@@ -220,7 +225,7 @@ export function writeWipCap(projectRoot, wipCap, options = {}) {
         const changed = previous !== wipCap;
         const auditEntry = `actor=${actor} field=plan.policy.wipCap value=${wipCap} previous=${JSON.stringify(previous)} ` +
             `changed=${changed ? "true" : "false"}`;
-        appendAuditEntry(projectRoot, auditEntry);
+        appendAuditEntry(projectRoot, auditEntry, changed);
         return [changed, auditEntry];
     });
 }

package/dist/value/feedback-file.d.ts

@@ -1,6 +1,10 @@
 import { type GhRestSeams } from "../scm/gh-rest.js";
 export declare const DEFAULT_UPSTREAM_REPO = "deftai/directive";
 export declare const FRAMEWORK_GAP_TITLE_PREFIX = "[framework-gap]";
+/** Sole sanctioned title classification (#3713). Does not write `adoption-blocker`. */
+export declare const ADOPTION_BLOCKER_TITLE_TOKEN = "BLOCKER";
+/** Strip source prefix and the optional BLOCKER token so marked/unmarked titles dedup. */
+export declare function stripTitleClassificationTokens(title: string): string;
 export type FeedbackFileOutcome = "draft" | "filed" | "skipped-maintainer" | "blocked-policy" | "blocked-duplicate" | "blocked-no-confirm" | "error-bad-args" | "error-config" | "error-network";
 export interface FeedbackGapInput {
     readonly summary: string;
@@ -8,6 +12,11 @@ export interface FeedbackGapInput {
     readonly expected?: string;
     readonly actual?: string;
     readonly sessionNotes?: string;
+    /** Consumer hard-stop judgment. Advisory title token only — never applies a label. */
+    readonly adoptionBlocker?: boolean;
+    readonly flowAndVersion?: string;
+    readonly alternatives?: string;
+    readonly recoveryCost?: string;
 }
 export interface FeedbackFileOptions extends FeedbackGapInput {
     readonly projectRoot?: string | null;
@@ -29,10 +38,12 @@ export interface FeedbackFileResult {
 }
 /** True when the resolved project root is the directive maintainer source checkout. */
 export declare function isMaintainerFrameworkRepo(projectRoot: string): boolean;
-/** Normalize a title for duplicate comparison (#1709). */
+/** Normalize a title for duplicate comparison (#1709 / #3713). */
 export declare function normalizeForDedup(title: string): string;
 /** Build the upstream issue title for a framework-gap report. */
-export declare function buildFrameworkGapTitle(summary: string): string;
+export declare function buildFrameworkGapTitle(summary: string, options?: {
+    adoptionBlocker?: boolean;
+}): string;
 /** Build the structured framework-gap issue body. */
 export declare function buildFrameworkGapBody(input: FeedbackGapInput): string;
 export interface DuplicateMatch {
@@ -49,6 +60,10 @@ export interface FeedbackFileCliArgs {
     expected?: string;
     actual?: string;
     sessionNotes?: string;
+    adoptionBlocker?: boolean;
+    flowAndVersion?: string;
+    alternatives?: string;
+    recoveryCost?: string;
     confirm?: boolean;
     dryRun?: boolean;
     json?: boolean;