@deftai/directive-core 0.106.0 → 0.107.0

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";
@@ -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",
@@ -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/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;

package/dist/value/feedback-file.js

@@ -7,6 +7,21 @@ import { GhRestError, restCreateIssue, restIssueListPaginated, } from "../scm/gh
 import { resolveProjectRoot } from "../scope/project-context.js";
 export const DEFAULT_UPSTREAM_REPO = "deftai/directive";
 export const FRAMEWORK_GAP_TITLE_PREFIX = "[framework-gap]";
+/** Sole sanctioned title classification (#3713). Does not write `adoption-blocker`. */
+export const ADOPTION_BLOCKER_TITLE_TOKEN = "BLOCKER";
+const FRAMEWORK_GAP_PREFIX_RE = /^\[framework-gap\]\s*/i;
+const BLOCKER_TITLE_TOKEN_RE = /^BLOCKER\b[:\s-]*/i;
+/** Strip source prefix and the optional BLOCKER token so marked/unmarked titles dedup. */
+export function stripTitleClassificationTokens(title) {
+    let rest = title.trim();
+    let previous = "";
+    while (rest !== previous) {
+        previous = rest;
+        rest = rest.replace(FRAMEWORK_GAP_PREFIX_RE, "").trim();
+        rest = rest.replace(BLOCKER_TITLE_TOKEN_RE, "").trim();
+    }
+    return rest;
+}
 function sanitizeOneLine(value) {
     return value.replace(/\r?\n/g, " ").trim();
 }
@@ -18,23 +33,54 @@ function sectionOrPlaceholder(value, placeholder) {
 export function isMaintainerFrameworkRepo(projectRoot) {
     return isFrameworkRepoRoot(resolve(projectRoot));
 }
-/** Normalize a title for duplicate comparison (#1709). */
+/** Normalize a title for duplicate comparison (#1709 / #3713). */
 export function normalizeForDedup(title) {
-    return title
-        .trim()
-        .replace(/^\[framework-gap\]\s*/i, "")
+    return stripTitleClassificationTokens(title)
         .toLowerCase()
         .replace(/[^\p{L}\p{N}]+/gu, " ")
         .trim();
 }
 /** Build the upstream issue title for a framework-gap report. */
-export function buildFrameworkGapTitle(summary) {
+export function buildFrameworkGapTitle(summary, options) {
     const clean = sanitizeOneLine(summary);
+    if (options?.adoptionBlocker) {
+        const rest = stripTitleClassificationTokens(clean);
+        return `${FRAMEWORK_GAP_TITLE_PREFIX} ${ADOPTION_BLOCKER_TITLE_TOKEN} ${rest}`;
+    }
     if (clean.toLowerCase().startsWith(FRAMEWORK_GAP_TITLE_PREFIX.toLowerCase())) {
         return clean;
     }
     return `${FRAMEWORK_GAP_TITLE_PREFIX} ${clean}`;
 }
+function buildAdoptionImpactSection(input) {
+    if (!input.adoptionBlocker) {
+        return [];
+    }
+    return [
+        "## Adoption impact",
+        "",
+        "This report is a consumer hard-stop: the consumer cannot complete an intended Directive flow and has no reasonable workaround.",
+        "",
+        `Title token: \`${ADOPTION_BLOCKER_TITLE_TOKEN}\`. This token does not apply the \`adoption-blocker\` ranking label. A privileged actor applies that label after the body-evidence test.`,
+        "",
+        "### Affected consumer flow and version",
+        "",
+        sectionOrPlaceholder(input.flowAndVersion, "_(not provided)_"),
+        "",
+        "### Documented alternatives attempted",
+        "",
+        sectionOrPlaceholder(input.alternatives, "_(not provided — why documented alternatives are not a reasonable workaround)_"),
+        "",
+        "### Observed recovery cost",
+        "",
+        sectionOrPlaceholder(input.recoveryCost, "_(not provided)_"),
+        "",
+        "### Triage owner and date",
+        "",
+        "_(to be filled by a privileged actor when applying `adoption-blocker`)_",
+        "",
+    ];
+}
 /** Build the structured framework-gap issue body. */
 export function buildFrameworkGapBody(input) {
     const summary = sanitizeOneLine(input.summary);
@@ -59,6 +105,7 @@ export function buildFrameworkGapBody(input) {
         "",
         sectionOrPlaceholder(input.sessionNotes, "_(not provided)_"),
         "",
+        ...buildAdoptionImpactSection(input),
         "---",
         "_Filed via `task feedback:file` from a directive consumer project (Refs #1709 value-feedback gap escalation)._",
         "",
@@ -126,7 +173,7 @@ export function runFeedbackFile(options) {
     }
     const projectRoot = resolve(projectRootRaw);
     const repo = resolveRepo(options);
-    const title = buildFrameworkGapTitle(summary);
+    const title = buildFrameworkGapTitle(summary, { adoptionBlocker: options.adoptionBlocker });
     const body = buildFrameworkGapBody(options);
     if (isMaintainerFrameworkRepo(projectRoot)) {
         return {
@@ -254,6 +301,8 @@ export function parseFeedbackFileArgs(argv) {
             out.dryRun = true;
         else if (arg === "--json")
             out.json = true;
+        else if (arg === "--blocker")
+            out.adoptionBlocker = true;
         else if (arg === "--summary") {
             out.summary = argv[++i];
         }
@@ -287,6 +336,27 @@ export function parseFeedbackFileArgs(argv) {
         else if (arg?.startsWith("--session-notes=")) {
             out.sessionNotes = arg.slice("--session-notes=".length);
         }
+        else if (arg === "--flow" || arg === "--flow-and-version") {
+            out.flowAndVersion = argv[++i];
+        }
+        else if (arg?.startsWith("--flow=")) {
+            out.flowAndVersion = arg.slice("--flow=".length);
+        }
+        else if (arg?.startsWith("--flow-and-version=")) {
+            out.flowAndVersion = arg.slice("--flow-and-version=".length);
+        }
+        else if (arg === "--alternatives") {
+            out.alternatives = argv[++i];
+        }
+        else if (arg?.startsWith("--alternatives=")) {
+            out.alternatives = arg.slice("--alternatives=".length);
+        }
+        else if (arg === "--recovery-cost") {
+            out.recoveryCost = argv[++i];
+        }
+        else if (arg?.startsWith("--recovery-cost=")) {
+            out.recoveryCost = arg.slice("--recovery-cost=".length);
+        }
         else if (arg === "--repo") {
             out.repo = argv[++i];
         }
@@ -327,6 +397,10 @@ export function feedbackFileMain(argv) {
         expected: args.expected,
         actual: args.actual,
         sessionNotes: args.sessionNotes,
+        adoptionBlocker: args.adoptionBlocker,
+        flowAndVersion: args.flowAndVersion,
+        alternatives: args.alternatives,
+        recoveryCost: args.recoveryCost,
         confirm: args.confirm,
         dryRun: args.dryRun,
         json: args.json,

package/dist/vbrief-reconcile/labels.d.ts

@@ -9,6 +9,7 @@ export declare function computeDesiredLabels(plan: Record<string, unknown>, unre
 export declare class ScmLabelClient implements LabelClient {
     fetchLabels(repo: string, issueNumber: number): string[];
     apply(repo: string, issueNumber: number, add: readonly string[], remove: readonly string[]): void;
+    private applyMut;
 }
 export interface ReconcileLabelsOptions {
     readonly repo?: string | null;

package/dist/vbrief-reconcile/labels.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { applyDesignCritiqueCatalogChip, isDesignCritiqueCatalogChip, } from "../design-critique/exclusive-chip.js";
 import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
 import { extractIssueRef } from "../triage/reconcile/parse-uri.js";
@@ -69,6 +70,35 @@ export class ScmLabelClient {
         return names;
     }
     apply(repo, issueNumber, add, remove) {
+        const catalogAdds = add.filter(isDesignCritiqueCatalogChip);
+        if (catalogAdds.length > 0) {
+            const nextChip = catalogAdds[catalogAdds.length - 1];
+            const restAdd = add.filter((name) => !isDesignCritiqueCatalogChip(name));
+            const restRemove = remove.filter((name) => !isDesignCritiqueCatalogChip(name));
+            let applied = false;
+            const inner = {
+                fetchLabels: (r, n) => this.fetchLabels(r, n),
+                apply: (r, n, a, rem) => {
+                    applied = true;
+                    const addSet = new Set([...a, ...restAdd]);
+                    const removeSet = new Set([...rem, ...restRemove]);
+                    for (const name of addSet)
+                        removeSet.delete(name);
+                    this.applyMut(r, n, [...addSet], [...removeSet]);
+                },
+            };
+            applyDesignCritiqueCatalogChip(inner, repo, issueNumber, nextChip);
+            if (!applied && (restAdd.length > 0 || restRemove.length > 0)) {
+                this.applyMut(repo, issueNumber, restAdd, restRemove);
+            }
+            return;
+        }
+        this.applyMut(repo, issueNumber, add, remove);
+    }
+    applyMut(repo, issueNumber, add, remove) {
+        if (add.length === 0 && remove.length === 0) {
+            return;
+        }
         const args = ["edit", String(issueNumber), "--repo", repo];
         for (const name of add)
             args.push("--add-label", name);

package/dist/vbrief-validation/story-quality.d.ts

@@ -25,5 +25,12 @@ export interface StoryQualityParams {
     readonly swarm: JsonObject;
     readonly concurrentReady?: boolean;
 }
+/**
+ * Shared Gate A text for `readiness=ready` + `parallel_safe: false` (#3666 / #3252).
+ * Authoring (`scope:decompose`) and launch (`swarm:readiness` / `swarm:launch`)
+ * both emit this string. It must not recommend `readiness=sequential` as a
+ * launch remediation — Gate B rejects that value on the same call.
+ */
+export declare const READY_REQUIRES_PARALLEL_SAFE = "readiness=ready requires parallel_safe=true. This story is not eligible for concurrent swarm:launch; dispatch non-concurrent work via the interactive swarm-skill solo-worker path (that path is not gated by swarm:readiness exiting 0; exit 0 gates concurrent workers only; see #3669)";
 export declare function storyQualityIssues(params: StoryQualityParams): string[];
 //# sourceMappingURL=story-quality.d.ts.map

package/dist/vbrief-validation/story-quality.js

@@ -266,6 +266,13 @@ export function deprecatedSubitemsIssues(items, prefix = "plan.items") {
     visit(items, prefix);
     return issues;
 }
+/**
+ * Shared Gate A text for `readiness=ready` + `parallel_safe: false` (#3666 / #3252).
+ * Authoring (`scope:decompose`) and launch (`swarm:readiness` / `swarm:launch`)
+ * both emit this string. It must not recommend `readiness=sequential` as a
+ * launch remediation — Gate B rejects that value on the same call.
+ */
+export const READY_REQUIRES_PARALLEL_SAFE = "readiness=ready requires parallel_safe=true. This story is not eligible for concurrent swarm:launch; dispatch non-concurrent work via the interactive swarm-skill solo-worker path (that path is not gated by swarm:readiness exiting 0; exit 0 gates concurrent workers only; see #3669)";
 export function storyQualityIssues(params) {
     const issues = [];
     const concurrentReady = params.concurrentReady ?? true;
@@ -304,7 +311,7 @@ export function storyQualityIssues(params) {
         issues.push(...fileScopeIssues(params.swarm));
         issues.push(...verifyCommandIssues(params.swarm));
         if (params.swarm.parallel_safe === false) {
-            issues.push("readiness=ready requires parallel_safe=true; use readiness=sequential or needs_refinement for non-concurrent work");
+            issues.push(READY_REQUIRES_PARALLEL_SAFE);
         }
         if (params.swarm.file_scope_confidence === "low") {
             issues.push("readiness=ready requires file_scope_confidence above low");

package/dist/xbrief-migrate/agents-header.js

@@ -6,14 +6,14 @@ import { MIGRATED_ARTIFACT_DIR } from "./constants.js";
 import { isDirectory } from "./fs-helpers.js";
 /**
  * Bounded, ordered set of legacy crossover tokens rewritten in the UNMANAGED
- * region of a consumer AGENTS.md after `migrate:xbrief` (#2154 / Option A).
+ * region of a consumer AGENTS.md after `migrate:xbrief` (#2154 / Option A / #3637).
  *
  * Each entry is a mechanical path / verb literal — NOT freeform prose. The
  * casing-only `vBRIEF format` product-description token from the issue table is
- * intentionally excluded so freeform prose survives untouched. The tokens are
- * disjoint substrings (`.vbrief.json` has no trailing slash, `vbrief:preflight`
- * uses a colon, `vbrief/` requires a slash), so replacement order does not
- * change the result and a second pass is a guaranteed no-op (idempotent).
+ * intentionally excluded so freeform prose survives untouched. `.vbrief.json`
+ * and `vbrief:preflight` are substring hits. `vbrief/` is left-bound and only
+ * a hard hit when a child segment follows (`vbrief/active/...`); bare
+ * `vbrief/` and `x-vbrief/` are not rewritten. A second pass is a no-op.
  */
 /** Refuse migrate header writes that escape via repo-controlled symlinks (#2668). */
 function projectionTarget(projectDir, ...relSegments) {
@@ -26,6 +26,8 @@ export const LEGACY_HEADER_TOKENS = [
     { legacy: "vbrief:preflight", migrated: "xbrief:preflight" },
     { legacy: "vbrief/", migrated: "xbrief/" },
 ];
+const VBRIEF_DIR = "vbrief/";
+const XBRIEF_DIR = "xbrief/";
 function countOccurrences(haystack, needle) {
     if (needle.length === 0)
         return 0;
@@ -37,10 +39,70 @@ function countOccurrences(haystack, needle) {
     }
     return count;
 }
+/** `x-vbrief/` is not a `vbrief/` hit; ident/hyphen continue the token. */
+function isLeftBoundAt(text, index) {
+    if (index === 0)
+        return true;
+    return !/[A-Za-z0-9_-]/.test(text[index - 1]);
+}
+/** Child path segment after `vbrief/` — not whitespace, fence close, or EOS. */
+function hasVbriefChildSegment(text, index) {
+    const after = index + VBRIEF_DIR.length;
+    if (after >= text.length)
+        return false;
+    const ch = text[after];
+    return ch !== "/" && ch !== "`" && !/\s/.test(ch);
+}
+function isHardVbriefDirHit(text, index) {
+    return isLeftBoundAt(text, index) && hasVbriefChildSegment(text, index);
+}
+function hasHardVbriefDirHit(text) {
+    let index = text.indexOf(VBRIEF_DIR);
+    while (index !== -1) {
+        if (isHardVbriefDirHit(text, index))
+            return true;
+        index = text.indexOf(VBRIEF_DIR, index + VBRIEF_DIR.length);
+    }
+    return false;
+}
+/** Rewrite left-bound `vbrief/` + child; leave bare `vbrief/` and `x-vbrief/`. */
+function rewriteLeftBoundVbriefDir(slice) {
+    let out = "";
+    let cursor = 0;
+    let count = 0;
+    let index = slice.indexOf(VBRIEF_DIR);
+    while (index !== -1) {
+        out += slice.slice(cursor, index);
+        if (isHardVbriefDirHit(slice, index)) {
+            out += XBRIEF_DIR;
+            count += 1;
+        }
+        else {
+            out += VBRIEF_DIR;
+        }
+        cursor = index + VBRIEF_DIR.length;
+        index = slice.indexOf(VBRIEF_DIR, cursor);
+    }
+    out += slice.slice(cursor);
+    return { next: out, count };
+}
+function unmanagedHitsLegacyToken(unmanaged, legacy) {
+    if (legacy === VBRIEF_DIR)
+        return hasHardVbriefDirHit(unmanaged);
+    return unmanaged.includes(legacy);
+}
 /** Rewrite the bounded legacy tokens inside a single unmanaged text slice. */
 function rewriteSlice(slice, tally) {
     let next = slice;
     for (const { legacy, migrated } of LEGACY_HEADER_TOKENS) {
+        if (legacy === VBRIEF_DIR) {
+            const rewritten = rewriteLeftBoundVbriefDir(next);
+            if (rewritten.count === 0)
+                continue;
+            tally.set(legacy, (tally.get(legacy) ?? 0) + rewritten.count);
+            next = rewritten.next;
+            continue;
+        }
         const occurrences = countOccurrences(next, legacy);
         if (occurrences === 0)
             continue;
@@ -172,7 +234,7 @@ export function detectStaleUnmanagedHeader(projectRoot, readText = (path) => {
         cursor = end;
     }
     unmanaged += content.slice(cursor);
-    const matches = LEGACY_HEADER_TOKENS.filter((t) => unmanaged.includes(t.legacy)).map((t) => t.legacy);
+    const matches = LEGACY_HEADER_TOKENS.filter((t) => unmanagedHitsLegacyToken(unmanaged, t.legacy)).map((t) => t.legacy);
     return { stale: matches.length > 0, matches };
 }
 /** One-line doctor / ritual signpost for the #2154 stale-header regression. */
@@ -183,6 +245,6 @@ export function renderStaleHeaderLine(projectRoot, readText) {
     }
     return (`AGENTS.md header drift: xbrief/ tree present but the unmanaged AGENTS.md header still ` +
         `references legacy token(s) ${matches.join(", ")}. ` +
-        "Run `deft migrate:xbrief` (idempotent) to rewrite them, or hand-edit the header.");
+        "Hand-edit the unmanaged header path literals.");
 }
 //# sourceMappingURL=agents-header.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.106.0",
+  "version": "0.107.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -386,8 +386,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.106.0",
-    "@deftai/directive-types": "^0.106.0",
+    "@deftai/directive-content": "^0.107.0",
+    "@deftai/directive-types": "^0.107.0",
     "archiver": "^8.0.0"
   },
   "scripts": {