@deftai/directive-core 0.66.2 → 0.67.0

package/dist/verify-source/biome-config.js

@@ -0,0 +1,97 @@
+/**
+ * biome-config.ts -- guard against #2190 (biome check . reports
+ * recommended-preset diagnostics as errors vs warnings non-deterministically
+ * on a pinned biome version).
+ *
+ * A preset-inherited rule severity can silently change tier across a biome
+ * version bump (or, per #2190, apparently even across runs on the identical
+ * pinned version). Pinning `noUnusedVariables` / `noNonNullAssertion` to an
+ * explicit non-"error" severity in biome.json makes the tier config-owned so
+ * it cannot flip a required CI check to failing on pre-existing diagnostics.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** The two rules #2190 observed flipping severity in CI (see docs/analysis/2026-07-02-2190-biome-determinism.md). */
+export const GUARDED_RULES = [
+    { group: "correctness", rule: "noUnusedVariables" },
+    { group: "style", rule: "noNonNullAssertion" },
+];
+/** Severity levels biome accepts that never fail the build. */
+const NON_ERROR_LEVELS = new Set(["warn", "info", "off"]);
+function extractSeverity(rulesNode, group, rule) {
+    if (typeof rulesNode !== "object" || rulesNode === null) {
+        return null;
+    }
+    const groupNode = rulesNode[group];
+    if (typeof groupNode !== "object" || groupNode === null) {
+        return null;
+    }
+    const ruleNode = groupNode[rule];
+    if (typeof ruleNode === "string") {
+        return ruleNode;
+    }
+    if (typeof ruleNode === "object" && ruleNode !== null) {
+        const level = ruleNode.level;
+        return typeof level === "string" ? level : null;
+    }
+    return null;
+}
+/**
+ * Parse a biome.json document (already JSON.parse'd) and report the explicit
+ * severity declared for each guarded rule.
+ */
+export function findRuleSeverities(biomeConfig, rules = GUARDED_RULES) {
+    const linter = typeof biomeConfig === "object" && biomeConfig !== null
+        ? biomeConfig.linter
+        : null;
+    const rulesNode = typeof linter === "object" && linter !== null
+        ? linter.rules
+        : null;
+    return rules.map(({ group, rule }) => ({
+        group,
+        rule,
+        severity: extractSeverity(rulesNode, group, rule),
+    }));
+}
+/**
+ * Evaluate biome.json at `projectRoot` and fail closed when a guarded rule
+ * has no explicit severity, or an explicit severity of "error".
+ */
+export function evaluateBiomeConfigGuard(projectRoot = ".") {
+    const path = join(projectRoot, "biome.json");
+    let raw;
+    try {
+        raw = readFileSync(path, { encoding: "utf8" });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { code: 2, findings: [], message: `biome-config: cannot read ${path}: ${msg}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { code: 2, findings: [], message: `biome-config: ${path} is not valid JSON: ${msg}` };
+    }
+    const findings = findRuleSeverities(parsed);
+    const bad = findings.filter((f) => f.severity === null || !NON_ERROR_LEVELS.has(f.severity));
+    if (bad.length > 0) {
+        const lines = bad.map((f) => `  linter.rules.${f.group}.${f.rule}: ${f.severity === null ? "not explicitly set (inherits preset default)" : `"${f.severity}"`}`);
+        return {
+            code: 1,
+            findings,
+            message: "biome-config: guarded rule(s) lack an explicit non-error severity in biome.json (#2190 " +
+                "-- a preset-inherited severity can flip to error non-deterministically):\n" +
+                `${lines.join("\n")}\n` +
+                '  Fix: declare "warn" (or "info") explicitly under linter.rules.<group>.<rule> in biome.json.',
+        };
+    }
+    return {
+        code: 0,
+        findings,
+        message: `biome-config: ${findings.length} guarded rule(s) have explicit non-error severities (#2190).`,
+    };
+}
+//# sourceMappingURL=biome-config.js.map

package/dist/verify-source/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./biome-config.js";
 export * from "./code-structure-validate.js";
 export * from "./content-manifest.js";
 export { CANONICAL_SCHEMA_REL, type ContractDriftOptions, type ContractDriftResult, evaluateContractDrift, PUBLISHED_SCHEMA_REL, } from "./contract-drift.js";

package/dist/verify-source/index.js

@@ -1,3 +1,4 @@
+export * from "./biome-config.js";
 export * from "./code-structure-validate.js";
 export * from "./content-manifest.js";
 export { CANONICAL_SCHEMA_REL, evaluateContractDrift, PUBLISHED_SCHEMA_REL, } from "./contract-drift.js";

package/dist/xbrief-migrate/agents-header.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Bounded, ordered set of legacy crossover tokens rewritten in the UNMANAGED
+ * region of a consumer AGENTS.md after `migrate:xbrief` (#2154 / Option A).
+ *
+ * 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).
+ */
+export declare const LEGACY_HEADER_TOKENS: ReadonlyArray<{
+    readonly legacy: string;
+    readonly migrated: string;
+}>;
+export interface HeaderTokenReplacement {
+    readonly legacy: string;
+    readonly migrated: string;
+    readonly count: number;
+}
+export interface HeaderRewriteResult {
+    readonly content: string;
+    readonly changed: boolean;
+    readonly replacements: HeaderTokenReplacement[];
+}
+/**
+ * Rewrite known legacy `vbrief` crossover tokens in the UNMANAGED region(s) of
+ * an AGENTS.md document, leaving every `<!-- deft:managed-section ... -->` block
+ * byte-for-byte intact. Idempotent: running on already-migrated content is a
+ * no-op. Managed sections are located by literal markers on the raw text so no
+ * line-ending normalisation is performed (UTF-8 / CRLF safe).
+ */
+export declare function rewriteUnmanagedHeaderTokens(content: string): HeaderRewriteResult;
+export interface HeaderPatchOutcome {
+    readonly kind: "patched" | "clean" | "absent" | "failed";
+    readonly path: string;
+    readonly replacements: HeaderTokenReplacement[];
+    readonly error?: string;
+}
+/**
+ * Read AGENTS.md at `projectRoot`, rewrite legacy tokens in the unmanaged
+ * header, and write the result back only when something changed. Returns a
+ * structured outcome so the caller can log a LEGACY-REPORT-style summary.
+ *
+ * Non-fatal: a write failure (read-only file, full disk) is captured as a
+ * `failed` outcome rather than thrown, so a post-migration header patch can
+ * never crash a migration that already succeeded.
+ */
+export declare function patchAgentsMdHeader(projectRoot: string, seams?: {
+    readText?: (path: string) => string | null;
+    writeText?: (path: string, text: string) => void;
+}): HeaderPatchOutcome;
+/** Human-readable one-line summary of a header patch outcome (LEGACY-REPORT style). */
+export declare function renderHeaderPatchSummary(outcome: HeaderPatchOutcome): string;
+export interface StaleHeaderDetection {
+    readonly stale: boolean;
+    readonly matches: string[];
+}
+/**
+ * Detect the #2154 half-migrated state: the `xbrief/` tree exists (lifecycle
+ * migration + managed-section refresh already happened) yet the UNMANAGED
+ * AGENTS.md header still references legacy `vbrief` path / verb literals — a
+ * regression `deft doctor` cannot see because the managed-section byte compare
+ * passes (#1308). Returns the matched legacy tokens for the signpost.
+ */
+export declare function detectStaleUnmanagedHeader(projectRoot: string, readText?: (path: string) => string | null): StaleHeaderDetection;
+/** One-line doctor / ritual signpost for the #2154 stale-header regression. */
+export declare function renderStaleHeaderLine(projectRoot: string, readText?: (path: string) => string | null): string;
+//# sourceMappingURL=agents-header.d.ts.map

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

@@ -0,0 +1,179 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { iterManagedSections } from "../platform/agents-md.js";
+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).
+ *
+ * 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).
+ */
+export const LEGACY_HEADER_TOKENS = [
+    { legacy: ".vbrief.json", migrated: ".xbrief.json" },
+    { legacy: "vbrief:preflight", migrated: "xbrief:preflight" },
+    { legacy: "vbrief/", migrated: "xbrief/" },
+];
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = haystack.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+/** 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) {
+        const occurrences = countOccurrences(next, legacy);
+        if (occurrences === 0)
+            continue;
+        tally.set(legacy, (tally.get(legacy) ?? 0) + occurrences);
+        next = next.replaceAll(legacy, migrated);
+    }
+    return next;
+}
+/**
+ * Rewrite known legacy `vbrief` crossover tokens in the UNMANAGED region(s) of
+ * an AGENTS.md document, leaving every `<!-- deft:managed-section ... -->` block
+ * byte-for-byte intact. Idempotent: running on already-migrated content is a
+ * no-op. Managed sections are located by literal markers on the raw text so no
+ * line-ending normalisation is performed (UTF-8 / CRLF safe).
+ */
+export function rewriteUnmanagedHeaderTokens(content) {
+    const managed = iterManagedSections(content);
+    const tally = new Map();
+    let out = "";
+    let cursor = 0;
+    for (const [start, end] of managed) {
+        // Unmanaged slice before this managed block: eligible for rewrite.
+        out += rewriteSlice(content.slice(cursor, start), tally);
+        // Managed block: preserved verbatim.
+        out += content.slice(start, end);
+        cursor = end;
+    }
+    // Trailing unmanaged slice after the last managed block (or the whole file
+    // when there is no managed section at all).
+    out += rewriteSlice(content.slice(cursor), tally);
+    const replacements = LEGACY_HEADER_TOKENS.filter((t) => tally.has(t.legacy)).map((t) => ({
+        legacy: t.legacy,
+        migrated: t.migrated,
+        count: tally.get(t.legacy) ?? 0,
+    }));
+    return { content: out, changed: out !== content, replacements };
+}
+/**
+ * Read AGENTS.md at `projectRoot`, rewrite legacy tokens in the unmanaged
+ * header, and write the result back only when something changed. Returns a
+ * structured outcome so the caller can log a LEGACY-REPORT-style summary.
+ *
+ * Non-fatal: a write failure (read-only file, full disk) is captured as a
+ * `failed` outcome rather than thrown, so a post-migration header patch can
+ * never crash a migration that already succeeded.
+ */
+export function patchAgentsMdHeader(projectRoot, seams = {}) {
+    const agentsPath = join(projectRoot, "AGENTS.md");
+    const readText = seams.readText ??
+        ((path) => {
+            try {
+                if (!existsSync(path))
+                    return null;
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return null;
+            }
+        });
+    const writeText = seams.writeText ?? ((path, text) => writeFileSync(path, text, "utf8"));
+    const existing = readText(agentsPath);
+    if (existing === null) {
+        return { kind: "absent", path: agentsPath, replacements: [] };
+    }
+    const result = rewriteUnmanagedHeaderTokens(existing);
+    if (!result.changed) {
+        return { kind: "clean", path: agentsPath, replacements: [] };
+    }
+    try {
+        writeText(agentsPath, result.content);
+    }
+    catch (err) {
+        return {
+            kind: "failed",
+            path: agentsPath,
+            replacements: [],
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    return { kind: "patched", path: agentsPath, replacements: result.replacements };
+}
+/** Human-readable one-line summary of a header patch outcome (LEGACY-REPORT style). */
+export function renderHeaderPatchSummary(outcome) {
+    if (outcome.kind === "absent") {
+        return "AGENTS.md unmanaged header: no AGENTS.md present — nothing to patch.";
+    }
+    if (outcome.kind === "clean") {
+        return "AGENTS.md unmanaged header: no legacy vbrief tokens found — nothing to patch.";
+    }
+    if (outcome.kind === "failed") {
+        return (`AGENTS.md unmanaged header: patch failed (${outcome.error ?? "unknown error"}) — ` +
+            "re-run `deft migrate:xbrief` (idempotent) or hand-edit the header.");
+    }
+    const total = outcome.replacements.reduce((sum, r) => sum + r.count, 0);
+    const detail = outcome.replacements.map((r) => `${r.legacy} ×${r.count}`).join(", ");
+    return `AGENTS.md unmanaged header: rewrote ${total} legacy vbrief token(s) -> xbrief (${detail}).`;
+}
+/**
+ * Detect the #2154 half-migrated state: the `xbrief/` tree exists (lifecycle
+ * migration + managed-section refresh already happened) yet the UNMANAGED
+ * AGENTS.md header still references legacy `vbrief` path / verb literals — a
+ * regression `deft doctor` cannot see because the managed-section byte compare
+ * passes (#1308). Returns the matched legacy tokens for the signpost.
+ */
+export function detectStaleUnmanagedHeader(projectRoot, readText = (path) => {
+    try {
+        if (!existsSync(path))
+            return null;
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}) {
+    if (!isDirectory(join(projectRoot, MIGRATED_ARTIFACT_DIR))) {
+        return { stale: false, matches: [] };
+    }
+    const content = readText(join(projectRoot, "AGENTS.md"));
+    if (content === null) {
+        return { stale: false, matches: [] };
+    }
+    const managed = iterManagedSections(content);
+    let unmanaged = "";
+    let cursor = 0;
+    for (const [start, end] of managed) {
+        unmanaged += content.slice(cursor, start);
+        cursor = end;
+    }
+    unmanaged += content.slice(cursor);
+    const matches = LEGACY_HEADER_TOKENS.filter((t) => unmanaged.includes(t.legacy)).map((t) => t.legacy);
+    return { stale: matches.length > 0, matches };
+}
+/** One-line doctor / ritual signpost for the #2154 stale-header regression. */
+export function renderStaleHeaderLine(projectRoot, readText) {
+    const { stale, matches } = detectStaleUnmanagedHeader(projectRoot, readText);
+    if (!stale) {
+        return "AGENTS.md header drift: none -- unmanaged header has no legacy vbrief path literals.";
+    }
+    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.");
+}
+//# sourceMappingURL=agents-header.js.map

package/dist/xbrief-migrate/fs-helpers.d.ts

@@ -0,0 +1,3 @@
+/** True when `path` exists and is a directory; false on any stat error. */
+export declare function isDirectory(path: string): boolean;
+//# sourceMappingURL=fs-helpers.d.ts.map

package/dist/xbrief-migrate/fs-helpers.js

@@ -0,0 +1,11 @@
+import { statSync } from "node:fs";
+/** True when `path` exists and is a directory; false on any stat error. */
+export function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=fs-helpers.js.map

package/dist/xbrief-migrate/index.d.ts

@@ -1,3 +1,4 @@
+export { detectStaleUnmanagedHeader, type HeaderPatchOutcome, type HeaderRewriteResult, type HeaderTokenReplacement, LEGACY_HEADER_TOKENS, patchAgentsMdHeader, renderHeaderPatchSummary, renderStaleHeaderLine, rewriteUnmanagedHeaderTokens, type StaleHeaderDetection, } from "./agents-header.js";
 export { detectLegacyVbriefLayout, type LegacyVbriefLayoutDetection, } from "./detect.js";
 export { BUILTIN_ALLOW_LIST, type DriftEvaluateOptions, type DriftEvaluateResult, type DriftFinding, type DriftScanMode, evaluateXbriefDrift, LEGACY_REFERENCE_PREFIX, scanCorpusToken, } from "./drift-gate.js";
 export { emitXbriefMigration, runXbriefMigration, runXbriefMigrationCli, type XbriefMigrationArgs, type XbriefMigrationIo, type XbriefMigrationOutcome, } from "./migrate-project.js";

package/dist/xbrief-migrate/index.js

@@ -1,3 +1,4 @@
+export { detectStaleUnmanagedHeader, LEGACY_HEADER_TOKENS, patchAgentsMdHeader, renderHeaderPatchSummary, renderStaleHeaderLine, rewriteUnmanagedHeaderTokens, } from "./agents-header.js";
 export { detectLegacyVbriefLayout, } from "./detect.js";
 export { BUILTIN_ALLOW_LIST, evaluateXbriefDrift, LEGACY_REFERENCE_PREFIX, scanCorpusToken, } from "./drift-gate.js";
 export { emitXbriefMigration, runXbriefMigration, runXbriefMigrationCli, } from "./migrate-project.js";

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

@@ -1,19 +1,13 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { checkGitClean } from "../migrate-preflight/index.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
+import { patchAgentsMdHeader, renderHeaderPatchSummary } from "./agents-header.js";
 import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, } from "./constants.js";
 import { detectLegacyVbriefLayout } from "./detect.js";
+import { isDirectory } from "./fs-helpers.js";
 import { renderXbriefMigrationLine, xbriefMigrationGuidance } from "./signpost.js";
 import { rewriteEmbeddedTokens, transformArtifactV06ToV08Transactional } from "./transforms.js";
-function isDirectory(path) {
-    try {
-        return statSync(path).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
 function collectFiles(root, acc = []) {
     if (!isDirectory(root)) {
         return acc;
@@ -177,6 +171,26 @@ export function emitXbriefMigration(outcome, io, options = {}) {
         }
     }
 }
+/**
+ * Rewrite legacy `vbrief` crossover tokens in the UNMANAGED AGENTS.md header
+ * after lifecycle migration + agents:refresh (#2154). The managed section is
+ * left byte-for-byte intact; only the freeform header/tail path literals are
+ * patched. Idempotent and non-fatal — a header with no legacy tokens is a
+ * clean no-op, and a write failure surfaces as a `failed` outcome on stderr
+ * rather than an exception. Always returns 0; the migration itself already
+ * succeeded, so a header-patch hiccup must not fail the whole command.
+ */
+function runHeaderPatch(projectRoot, io) {
+    const outcome = patchAgentsMdHeader(projectRoot);
+    const summary = `${renderHeaderPatchSummary(outcome)}\n`;
+    if (outcome.kind === "failed") {
+        io.writeErr(summary);
+    }
+    else {
+        io.writeOut(summary);
+    }
+    return 0;
+}
 /** End-to-end migrate:xbrief handler including optional agents:refresh (#2110). */
 export function runXbriefMigrationCli(args, io) {
     const outcome = runXbriefMigration(args, io);
@@ -184,6 +198,11 @@ export function runXbriefMigrationCli(args, io) {
     if (code !== 0 || outcome.kind !== "migrated") {
         return code;
     }
-    return runAgentsRefresh(resolve(args.projectRoot), args.frameworkRoot, io);
+    const projectRoot = resolve(args.projectRoot);
+    const refreshCode = runAgentsRefresh(projectRoot, args.frameworkRoot, io);
+    if (refreshCode !== 0) {
+        return refreshCode;
+    }
+    return runHeaderPatch(projectRoot, io);
 }
 //# sourceMappingURL=migrate-project.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.66.2",
+  "version": "0.67.0",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,6 +30,14 @@
       "types": "./dist/wip-cap/index.d.ts",
       "default": "./dist/wip-cap/index.js"
     },
+    "./agents-md-budget": {
+      "types": "./dist/agents-md-budget/index.d.ts",
+      "default": "./dist/agents-md-budget/index.js"
+    },
+    "./agents-md-advisory": {
+      "types": "./dist/agents-md-advisory/index.d.ts",
+      "default": "./dist/agents-md-advisory/index.js"
+    },
     "./xbrief-migrate": {
       "types": "./dist/xbrief-migrate/index.d.ts",
       "default": "./dist/xbrief-migrate/index.js"
@@ -237,8 +245,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.66.2",
-    "@deftai/directive-types": "^0.66.2",
+    "@deftai/directive-content": "^0.67.0",
+    "@deftai/directive-types": "^0.67.0",
     "archiver": "^8.0.0"
   },
   "scripts": {