@deftai/directive-core 0.106.0 → 0.108.0

package/dist/verify-source/project-definition-mutation-boundary.js

@@ -0,0 +1,326 @@
+/**
+ * project-definition-mutation-boundary.ts -- mechanized production inventory for
+ * PROJECT-DEFINITION mutation identity (#3796).
+ *
+ * A convention that mutators "should" use the shared lock is not checkable: a
+ * caller can take the lock and then resolve, read, or write the artifact through
+ * its own path, and a helper-level test still passes while a production family
+ * split-brains. This scanner replaces that convention with a boundary.
+ *
+ * Two things are enforced:
+ *
+ * 1. **Boundary** -- outside the modules that own the protocol, no production
+ *    source may call the raw lock, the raw write sink, or the raw loader, and no
+ *    file that mutates PROJECT-DEFINITION may re-resolve the artifact path. The
+ *    mutation capability is the only way in.
+ * 2. **Inventory** -- the per-file census of mutation call expressions is
+ *    recorded. Adding or removing a mutation site is a deliberate edit to
+ *    {@link PRODUCTION_MUTATION_INVENTORY}, not a silent drift.
+ *
+ * Consumed fail-closed by `project-definition-mutation-boundary.test.ts`.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+/** The capability that owns load/parse/persist against the captured path. */
+export const MUTATION_CAPABILITY_MODULE = "packages/core/src/vbrief-build/project-definition-mutation.ts";
+/** The module that owns the lock protocol and the raw primitives it wraps. */
+export const MUTATION_PROTOCOL_MODULE = "packages/core/src/vbrief-build/project-definition-io.ts";
+/**
+ * This scanner. Excluded from its own scan: it names every pattern it looks for
+ * in prose and regex literals, so scanning it would count the rules as call
+ * sites and let the inventory drift by editing the gate.
+ */
+export const MUTATION_BOUNDARY_MODULE = "packages/core/src/verify-source/project-definition-mutation-boundary.ts";
+/**
+ * Raw primitives and the only production files allowed to call them. Anything
+ * else reaching for these is a bypass of the captured-path identity.
+ */
+export const RAW_MUTATION_CALL_RULES = [
+    {
+        label: "raw mutation lock",
+        pattern: /\bprojectDefinitionMutationLock\s*\(/,
+        allowedFiles: [MUTATION_CAPABILITY_MODULE],
+    },
+    {
+        label: "raw PROJECT-DEFINITION write sink",
+        pattern: /\batomicWriteProjectDefinition\s*\(/,
+        allowedFiles: [MUTATION_CAPABILITY_MODULE, MUTATION_PROTOCOL_MODULE],
+    },
+    {
+        label: "raw captured-path parser",
+        pattern: /\bparseProjectDefinitionAt\s*\(/,
+        allowedFiles: [MUTATION_CAPABILITY_MODULE, MUTATION_PROTOCOL_MODULE],
+    },
+    {
+        label: "raw unlocked loader",
+        pattern: /\bloadProjectDefinitionForMutation\s*\(/,
+        allowedFiles: [MUTATION_PROTOCOL_MODULE],
+    },
+];
+/** Resolver calls that would give a mutation section a second artifact identity. */
+export const RESOLVER_CALL_PATTERNS = [
+    /\bresolveProjectDefinitionPath\s*\(/,
+    /\bprojectDefinitionPath\s*\(/,
+];
+/** Marks a file as performing a PROJECT-DEFINITION mutation. */
+const MUTATION_CALL_PATTERN = /\bwithProjectDefinitionMutation\s*\(/g;
+/**
+ * Character offsets of each `withProjectDefinitionMutation(...)` argument list.
+ *
+ * Scoping to the section is what keeps the resolver rule precise: resolving the
+ * path *before* acquiring the lock is ordinary pre-check work, while resolving it
+ * *inside* the critical section is the second identity the contract forbids.
+ * String, template, and comment spans are skipped so their braces and parens do
+ * not throw off the match.
+ */
+export function extractMutationSections(text) {
+    const sections = [];
+    const call = /\bwithProjectDefinitionMutation\s*\(/g;
+    let match = call.exec(text);
+    while (match !== null) {
+        const open = match.index + match[0].length - 1;
+        const end = matchClosingParen(text, open);
+        if (end > open)
+            sections.push([open, end]);
+        call.lastIndex = end > open ? end : call.lastIndex;
+        match = call.exec(text);
+    }
+    return sections;
+}
+function matchClosingParen(text, openIndex) {
+    let depth = 0;
+    let i = openIndex;
+    while (i < text.length) {
+        const ch = text[i];
+        const next = text[i + 1];
+        if (ch === "/" && next === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i += 1;
+            i += 2;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            i = skipStringLiteral(text, i);
+            continue;
+        }
+        if (ch === "(")
+            depth += 1;
+        if (ch === ")") {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+        i += 1;
+    }
+    return openIndex;
+}
+function skipStringLiteral(text, startIndex) {
+    const quote = text[startIndex];
+    let i = startIndex + 1;
+    while (i < text.length) {
+        if (text[i] === "\\") {
+            i += 2;
+            continue;
+        }
+        if (text[i] === quote)
+            return i + 1;
+        i += 1;
+    }
+    return i;
+}
+/**
+ * Production mutation call expressions, per file.
+ *
+ * The counts are the #3796 census: **18** call expressions across 13 core files
+ * that previously took the shared lock, plus the **2** `packages/cli` policy
+ * writers (`wipCap`, `swarmSubagentBackend`) that previously wrote
+ * PROJECT-DEFINITION with no lock at all. `parity-scenarios.ts` is the fixture
+ * harness for the same protocol and is counted separately below.
+ */
+export const PRODUCTION_MUTATION_INVENTORY = Object.freeze({
+    "packages/cli/src/dispatch.ts": 2,
+    "packages/core/src/policy/ceremony-dial.ts": 1,
+    "packages/core/src/policy/host-hooks.ts": 1,
+    "packages/core/src/policy/org-force-on-migration.ts": 1,
+    "packages/core/src/policy/product-signal.ts": 1,
+    "packages/core/src/policy/require-human-merge.ts": 1,
+    "packages/core/src/policy/resolve.ts": 1,
+    "packages/core/src/policy/value-feedback.ts": 2,
+    "packages/core/src/render/project-render.ts": 2,
+    "packages/core/src/scope/project-definition-sync.ts": 1,
+    "packages/core/src/triage/scope-drift/add-ignore.ts": 1,
+    "packages/core/src/triage/scope/mutations-core.ts": 2,
+    "packages/core/src/triage/subscribe/index.ts": 1,
+    "packages/core/src/triage/welcome/writers.ts": 3,
+    "packages/core/src/vbrief-build/parity-scenarios.ts": 1,
+});
+/**
+ * The #3796 census, split by provenance so a drift failure says which family
+ * moved. 18 core call expressions across 13 files already took the shared lock;
+ * the 2 `packages/cli` policy writers did not; `parity-scenarios.ts` is the
+ * fixture harness for the same protocol.
+ */
+export const PREVIOUSLY_LOCKED_CORE_CALL_EXPRESSIONS = 18;
+export const PREVIOUSLY_LOCKED_CORE_FILES = 13;
+export const PREVIOUSLY_UNLOCKED_CLI_WRITERS = 2;
+export const PARITY_HARNESS_CALL_EXPRESSIONS = 1;
+const SCAN_ROOTS = ["packages/core/src", "packages/cli/src"];
+const TEST_PATH_MARKERS = [".test.ts", ".test.tsx", "/fixtures/"];
+function toPosix(p) {
+    return p.split(sep).join("/");
+}
+function isProductionSource(relPosix) {
+    return !TEST_PATH_MARKERS.some((marker) => relPosix.includes(marker));
+}
+function walkTsFiles(dir, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (name === "node_modules" || name === "dist" || name === ".git")
+            continue;
+        const full = join(dir, name);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            walkTsFiles(full, out);
+        }
+        else if (st.isFile() && (name.endsWith(".ts") || name.endsWith(".tsx"))) {
+            out.push(full);
+        }
+    }
+}
+/**
+ * A re-export (`export { x } from "..."`) forwards a symbol, it does not call
+ * it, so it is not a bypass. Import lines are likewise declarations.
+ */
+function isDeclarationLine(trimmed) {
+    return (trimmed.startsWith("import ") ||
+        trimmed.startsWith("export {") ||
+        trimmed.startsWith("export type {") ||
+        trimmed.startsWith("export *") ||
+        trimmed.startsWith("//") ||
+        trimmed.startsWith("*") ||
+        trimmed.startsWith("/*"));
+}
+/**
+ * Scan production TypeScript for mutation-identity bypasses and build the
+ * mutation call-expression inventory. The scan reads the filesystem, not the git
+ * index, so an unstaged or brand-new bypass is still caught.
+ */
+export function scanProjectDefinitionMutationBoundary(projectRoot) {
+    const files = [];
+    for (const root of SCAN_ROOTS) {
+        walkTsFiles(join(projectRoot, root), files);
+    }
+    const findings = [];
+    const inventory = {};
+    let filesScanned = 0;
+    for (const abs of files) {
+        const relPosix = toPosix(relative(projectRoot, abs));
+        if (!isProductionSource(relPosix) || relPosix === MUTATION_BOUNDARY_MODULE)
+            continue;
+        filesScanned += 1;
+        let text;
+        try {
+            text = readFileSync(abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        MUTATION_CALL_PATTERN.lastIndex = 0;
+        const mutationCalls = text.match(MUTATION_CALL_PATTERN)?.length ?? 0;
+        if (mutationCalls > 0)
+            inventory[relPosix] = mutationCalls;
+        const sections = mutationCalls > 0 ? extractMutationSections(text) : [];
+        const lines = text.split(/\r?\n/);
+        let offset = 0;
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i] ?? "";
+            const lineStart = offset;
+            offset += line.length + 1;
+            const trimmed = line.trim();
+            if (isDeclarationLine(trimmed))
+                continue;
+            for (const rule of RAW_MUTATION_CALL_RULES) {
+                if (rule.pattern.test(line) && !rule.allowedFiles.includes(relPosix)) {
+                    findings.push({ path: relPosix, line: i + 1, rule: rule.label, text: trimmed });
+                }
+            }
+            // Inside a critical section the artifact identity is the captured one.
+            const insideSection = sections.some(([start, end]) => lineStart >= start && lineStart <= end);
+            if (insideSection && relPosix !== MUTATION_CAPABILITY_MODULE) {
+                for (const pattern of RESOLVER_CALL_PATTERNS) {
+                    if (pattern.test(line)) {
+                        findings.push({
+                            path: relPosix,
+                            line: i + 1,
+                            rule: "artifact path re-resolved inside a mutation section",
+                            text: trimmed,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return { findings, inventory, filesScanned };
+}
+/** Render findings as a stable, reviewable report. */
+export function formatMutationBoundaryFindings(findings) {
+    return findings
+        .map((f) => `  ${f.path}:${f.line} [${f.rule}] ${f.text}`)
+        .sort()
+        .join("\n");
+}
+/**
+ * The fail-closed verdict: no bypass, and the mutation inventory still matches
+ * the recorded census. Adding or removing a mutation site is a deliberate edit
+ * to {@link PRODUCTION_MUTATION_INVENTORY} and the census constants above.
+ */
+export function evaluateProjectDefinitionMutationBoundary(projectRoot) {
+    const scan = scanProjectDefinitionMutationBoundary(projectRoot);
+    const errors = [];
+    if (scan.findings.length > 0) {
+        errors.push(`${scan.findings.length} raw resolver/lock/write bypass(es) outside the mutation capability:\n` +
+            formatMutationBoundaryFindings(scan.findings));
+    }
+    for (const [path, expected] of Object.entries(PRODUCTION_MUTATION_INVENTORY)) {
+        const actual = scan.inventory[path] ?? 0;
+        if (actual !== expected) {
+            errors.push(`${path}: expected ${expected} mutation call(s), found ${actual}`);
+        }
+    }
+    for (const path of Object.keys(scan.inventory)) {
+        if (!(path in PRODUCTION_MUTATION_INVENTORY)) {
+            errors.push(`${path}: mutation call site not in the recorded inventory`);
+        }
+    }
+    const total = Object.values(scan.inventory).reduce((sum, n) => sum + n, 0);
+    const expectedTotal = PREVIOUSLY_LOCKED_CORE_CALL_EXPRESSIONS +
+        PREVIOUSLY_UNLOCKED_CLI_WRITERS +
+        PARITY_HARNESS_CALL_EXPRESSIONS;
+    if (total !== expectedTotal) {
+        errors.push(`census total: expected ${expectedTotal} mutation call(s), found ${total}`);
+    }
+    const coreFiles = Object.keys(scan.inventory).filter((path) => path.startsWith("packages/core/") && !path.includes("parity-scenarios"));
+    if (coreFiles.length !== PREVIOUSLY_LOCKED_CORE_FILES) {
+        errors.push(`census files: expected ${PREVIOUSLY_LOCKED_CORE_FILES} core file(s), found ${coreFiles.length}`);
+    }
+    return { ok: errors.length === 0, errors, scan };
+}
+//# sourceMappingURL=project-definition-mutation-boundary.js.map

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.108.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -195,6 +195,10 @@
       "types": "./dist/pr-closing-keywords/index.d.ts",
       "default": "./dist/pr-closing-keywords/index.js"
     },
+    "./pr-closeout-attestable": {
+      "types": "./dist/pr-closeout-attestable/index.d.ts",
+      "default": "./dist/pr-closeout-attestable/index.js"
+    },
     "./pr-monitor": {
       "types": "./dist/pr-monitor/index.d.ts",
       "default": "./dist/pr-monitor/index.js"
@@ -386,8 +390,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.106.0",
-    "@deftai/directive-types": "^0.106.0",
+    "@deftai/directive-content": "^0.108.0",
+    "@deftai/directive-types": "^0.108.0",
     "archiver": "^8.0.0"
   },
   "scripts": {