@deftai/directive-core 0.87.0 → 0.88.0

package/dist/init-deposit/scaffold.js

@@ -9,7 +9,7 @@ import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync,
 import { mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { platform } from "node:os";
 import { dirname, join, relative } from "node:path";
-import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
+import { assertDestinationNotSymlink, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
@@ -17,10 +17,14 @@ import { installerManagedGuardEre } from "./hygiene.js";
 import { syncConsumerXbriefSchemas } from "./xbrief-projections.js";
 export { CANONICAL_INSTALL_ROOT };
 export const CORE_GLOB = ".deft/core/**";
-/** Refuse init/update projection writes that escape via repo-controlled symlinks (#2446). */
+/**
+ * Refuse init/update projection writes that escape via repo-controlled symlinks
+ * (#2446) OR that would follow an in-tree destination symlink on the write path
+ * (#2912). Every consumer projection sink in this module routes through here.
+ */
 function projectionTarget(projectDir, ...relSegments) {
     const target = join(projectDir, ...relSegments);
-    assertProjectionContained(projectDir, target);
+    assertDestinationNotSymlink(projectDir, target);
     return target;
 }
 const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";

package/dist/init-deposit/xbrief-projections.js

@@ -7,7 +7,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { join, relative } from "node:path";
-import { assertProjectionContained } from "../fs/projection-containment.js";
+import { assertDestinationNotSymlink } from "../fs/projection-containment.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
 import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
@@ -54,7 +54,7 @@ export function rewriteProjectedSchemaContent(content) {
  * Upstream vbrief/schemas/ may keep legacy paths; consumer copies must not (#2670).
  */
 export function assertProjectedSchemaDescriptionsRooted(projectDir, destinationDir) {
-    assertProjectionContained(projectDir, destinationDir);
+    assertDestinationNotSymlink(projectDir, destinationDir);
     if (!isDirectory(destinationDir))
         return;
     for (const rel of collectSchemaFiles(destinationDir)) {
@@ -66,7 +66,7 @@ export function assertProjectedSchemaDescriptionsRooted(projectDir, destinationD
     }
 }
 function writeFileIfChanged(projectDir, target, content) {
-    assertProjectionContained(projectDir, target);
+    assertDestinationNotSymlink(projectDir, target);
     const desired = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
     try {
         if (readFileSync(target).equals(desired))
@@ -91,7 +91,7 @@ export function syncConsumerXbriefSchemas(projectDir, deftDir) {
         throw new Error(`cannot project xbrief schemas: framework payload is missing ${CURRENT_CORE_SCHEMA}`);
     }
     const destinationDir = join(projectDir, MIGRATED_ARTIFACT_DIR, "schemas");
-    assertProjectionContained(projectDir, destinationDir);
+    assertDestinationNotSymlink(projectDir, destinationDir);
     mkdirSync(destinationDir, { recursive: true });
     let changed = false;
     for (const rel of collectSchemaFiles(sourceDir)) {
@@ -103,7 +103,7 @@ export function syncConsumerXbriefSchemas(projectDir, deftDir) {
         changed = writeFileIfChanged(projectDir, destination, projected) || changed;
     }
     const obsoleteDestination = join(destinationDir, OBSOLETE_CORE_SCHEMA);
-    assertProjectionContained(projectDir, obsoleteDestination);
+    assertDestinationNotSymlink(projectDir, obsoleteDestination);
     if (existsSync(obsoleteDestination)) {
         rmSync(obsoleteDestination, { force: true });
         changed = true;
@@ -117,7 +117,7 @@ function syncBareVersionMarkerWithPolicy(projectDir, version, allowRootFallback)
         return false;
     const canonicalRoot = join(projectDir, MIGRATED_ARTIFACT_DIR);
     if (existsSync(canonicalRoot)) {
-        assertProjectionContained(projectDir, join(canonicalRoot, ".deft-version"));
+        assertDestinationNotSymlink(projectDir, join(canonicalRoot, ".deft-version"));
     }
     let targetDir = projectDir;
     try {

package/dist/intake/issue-ingest.js

@@ -330,15 +330,24 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
     const labelNames = [];
     if (Array.isArray(labelsRaw)) {
         for (const lbl of labelsRaw) {
+            let rawName;
             if (typeof lbl === "string") {
-                labelNames.push(lbl);
+                rawName = lbl;
             }
             else if (lbl !== null && typeof lbl === "object" && !Array.isArray(lbl)) {
                 const name = lbl.name;
                 if (typeof name === "string" && name.length > 0) {
-                    labelNames.push(name);
+                    rawName = name;
                 }
             }
+            if (rawName === undefined || rawName.length === 0) {
+                continue;
+            }
+            // #2916: label names copy unchanged into narratives.Labels and plan.tags --
+            // agent-authoritative fields. Quarantine-scan them under the same contract as
+            // titles/body: hard-fail closed on credential-shaped labels, fence/omit
+            // injection-shaped labels. (cache-quarantine-06, tracker #2904)
+            labelNames.push(scanUntrustedIngestText(number, rawName));
         }
     }
     const [folder, planStatus] = STATUS_MAP[status];

package/dist/packs/pack-render.d.ts

@@ -17,11 +17,44 @@ export interface RenderRegistryEntry {
     readonly name_field?: string;
     readonly description_field?: string;
     readonly path_field?: string;
+    /**
+     * Pack-schema path pattern (mirrors content/vbrief/schemas/<pack>-pack.schema.json
+     * `path.pattern`). Enforced fail-closed before render so a malicious pack JSON
+     * cannot smuggle an off-shape projection path. Refs #2914 / #2904.
+     */
+    readonly path_pattern?: RegExp;
 }
+/** Non-zero exit code for a pack-render containment / schema refusal. */
+export declare const PACK_RENDER_REFUSED_EXIT_CODE = 2;
+/**
+ * Thrown, fail-closed, when a pack record's projection path escapes CONTENT_ROOT,
+ * violates the pack path schema, or a frontmatter field carries an injection
+ * payload (null byte / newline). Remediates AppSec finding skill-pack-supply-01
+ * from tracker #2904. Refs #2914.
+ */
+export declare class PackRenderContainmentError extends Error {
+    readonly pack: string;
+    readonly field: string;
+    readonly offendingValue: string;
+    constructor(message: string, details: {
+        pack: string;
+        field: string;
+        offendingValue: string;
+    });
+}
+/**
+ * Resolve a pack record's projection path against CONTENT_ROOT and refuse,
+ * fail-closed, any value that: is missing/empty/non-string, carries a null
+ * byte, is absolute, violates the pack's schema path pattern, or resolves
+ * outside CONTENT_ROOT (a `..` escape). Returns the contained absolute output
+ * path. Mirrors deposit/contain.ts segment containment. Refs #2914 / #2904.
+ */
+export declare function containedOutPath(packName: string, rawPath: unknown, cfg: RenderRegistryEntry): string;
 export declare const RENDER_REGISTRY: Record<string, RenderRegistryEntry>;
 export declare function renderCollection(pack: Record<string, unknown>, cfg: RenderRegistryEntry): string;
 export declare function renderSkillDocument(entry: Record<string, unknown>, cfg: RenderRegistryEntry): string;
 export declare function renderMarkdownDocument(entry: Record<string, unknown>, cfg: RenderRegistryEntry): string;
+export declare function targetsForPack(packName: string, pack: Record<string, unknown>, cfg: RenderRegistryEntry): Array<[string, string]>;
 export declare function collectTargets(packFilter?: string | null): Array<[string, string, string]>;
 export declare function render(pack: Record<string, unknown>): string;
 export declare function renderFile(source: string): string;

package/dist/packs/pack-render.js

@@ -1,6 +1,6 @@
 /** Port of scripts/pack_render.py — content-pack projection renderer (#1294, #1295). */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { contentRoot } from "../content-root.js";
 export function resolveRepoRoot() {
@@ -54,6 +54,138 @@ const SWARM_SPEC_BANNER = [
 ];
 export const BANNER = `${LESSONS_BANNER.join("\n")}\n`;
 export const DOC_TITLE = "# Lessons Learned";
+/** Non-zero exit code for a pack-render containment / schema refusal. */
+export const PACK_RENDER_REFUSED_EXIT_CODE = 2;
+/**
+ * Thrown, fail-closed, when a pack record's projection path escapes CONTENT_ROOT,
+ * violates the pack path schema, or a frontmatter field carries an injection
+ * payload (null byte / newline). Remediates AppSec finding skill-pack-supply-01
+ * from tracker #2904. Refs #2914.
+ */
+export class PackRenderContainmentError extends Error {
+    pack;
+    field;
+    offendingValue;
+    constructor(message, details) {
+        super(message);
+        this.name = "PackRenderContainmentError";
+        this.pack = details.pack;
+        this.field = details.field;
+        this.offendingValue = details.offendingValue;
+    }
+}
+/**
+ * Path-SEGMENT containment: is `child` equal to `parent` or nested under it?
+ * Uses `path.relative` so `/foo` is NOT treated as containing `/foobar`
+ * (mirrors deposit/contain.ts).
+ */
+function isContained(parent, child) {
+    if (parent === child) {
+        return true;
+    }
+    const rel = relative(parent, child);
+    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/** realpath with a resolve() fallback when the path does not exist yet. */
+function safeRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+/**
+ * Defense-in-depth: walk each EXISTING component from CONTENT_ROOT down to the
+ * resolved output and refuse any symlink that escapes CONTENT_ROOT. Mirrors the
+ * realpath-anchored segment walk in deposit/contain.ts so a symlinked content
+ * subtree cannot redirect a projection write outside the shippable-content root.
+ */
+function assertAncestorContained(packName, field, rawPath, rootReal, outPath) {
+    const rel = relative(rootReal, outPath);
+    const segments = rel.split(/[\\/]+/).filter((segment) => segment.length > 0);
+    let current = rootReal;
+    for (const segment of segments) {
+        current = join(current, segment);
+        let info;
+        try {
+            info = lstatSync(current);
+        }
+        catch {
+            // Component does not exist yet; nothing below it can exist either.
+            break;
+        }
+        if (info.isSymbolicLink()) {
+            let linkReal;
+            try {
+                linkReal = realpathSync(current);
+            }
+            catch {
+                throw new PackRenderContainmentError(`pack-render refused: ${packName} ${field} path component ${current} is a broken symlink`, { pack: packName, field, offendingValue: rawPath });
+            }
+            if (!isContained(rootReal, linkReal)) {
+                throw new PackRenderContainmentError(`pack-render refused: ${packName} ${field} path component ${current} is a symlink ` +
+                    `escaping CONTENT_ROOT (resolves to ${linkReal}, outside ${rootReal})`, { pack: packName, field, offendingValue: rawPath });
+            }
+            current = linkReal;
+        }
+    }
+}
+/**
+ * Resolve a pack record's projection path against CONTENT_ROOT and refuse,
+ * fail-closed, any value that: is missing/empty/non-string, carries a null
+ * byte, is absolute, violates the pack's schema path pattern, or resolves
+ * outside CONTENT_ROOT (a `..` escape). Returns the contained absolute output
+ * path. Mirrors deposit/contain.ts segment containment. Refs #2914 / #2904.
+ */
+export function containedOutPath(packName, rawPath, cfg) {
+    const field = cfg.path_field ?? "path";
+    if (typeof rawPath !== "string" || rawPath.length === 0) {
+        throw new PackRenderContainmentError(`pack-render refused: ${packName} entry has a missing/empty ${field}`, { pack: packName, field, offendingValue: String(rawPath) });
+    }
+    if (rawPath.includes("\0")) {
+        throw new PackRenderContainmentError(`pack-render refused: ${packName} ${field} contains a null byte`, { pack: packName, field, offendingValue: rawPath });
+    }
+    if (isAbsolute(rawPath) || /^[\\/]/.test(rawPath)) {
+        throw new PackRenderContainmentError(`pack-render refused: ${packName} ${field} must be a relative path (got absolute ${JSON.stringify(rawPath)})`, { pack: packName, field, offendingValue: rawPath });
+    }
+    if (cfg.path_pattern && !cfg.path_pattern.test(rawPath)) {
+        throw new PackRenderContainmentError(`pack-render refused: ${packName} ${field} ${JSON.stringify(rawPath)} violates the ` +
+            `${packName}-pack schema path pattern ${String(cfg.path_pattern)}`, { pack: packName, field, offendingValue: rawPath });
+    }
+    // Resolve with realpath semantics on the trusted root, then confirm segment
+    // containment. `resolve` collapses `..`, so an escape lands outside rootReal
+    // and is refused here even when it slipped past the schema pattern (where `.`
+    // can match a path separator).
+    const rootReal = safeRealpath(CONTENT_ROOT);
+    const outPath = resolve(rootReal, rawPath);
+    if (!isContained(rootReal, outPath)) {
+        throw new PackRenderContainmentError(`pack-render refused: ${packName} ${field} ${JSON.stringify(rawPath)} escapes CONTENT_ROOT ` +
+            `(resolves to ${outPath}, outside ${rootReal})`, { pack: packName, field, offendingValue: rawPath });
+    }
+    assertAncestorContained(packName, field, rawPath, rootReal, outPath);
+    return outPath;
+}
+/** Refuse a frontmatter field value that embeds a null byte. Refs #2914. */
+function assertNoNullByte(value, packName, field) {
+    if (value.includes("\0")) {
+        throw new PackRenderContainmentError(`pack-render refused: ${packName} frontmatter field ${field} contains a null byte`, { pack: packName, field, offendingValue: value });
+    }
+    return value;
+}
+/**
+ * Sanitize a single-line YAML frontmatter field (skill `name`): refuse null
+ * bytes and any CR/LF. An unescaped newline would inject arbitrary YAML keys or
+ * a premature `---` document break into the generated frontmatter. Refs #2914.
+ */
+function sanitizeSingleLineField(value, packName, field) {
+    assertNoNullByte(value, packName, field);
+    if (/[\r\n]/.test(value)) {
+        throw new PackRenderContainmentError(`pack-render refused: ${packName} frontmatter field ${field} must not contain a newline ` +
+            `(YAML frontmatter injection)`, { pack: packName, field, offendingValue: value });
+    }
+    return value;
+}
 export const RENDER_REGISTRY = {
     lessons: {
         mode: "collection",
@@ -73,6 +205,7 @@ export const RENDER_REGISTRY = {
         name_field: "id",
         description_field: "description",
         path_field: "path",
+        path_pattern: /^skills\/.+\/SKILL\.md$/,
         body_field: "body",
         banner: SKILLS_BANNER,
     },
@@ -82,6 +215,7 @@ export const RENDER_REGISTRY = {
         source: join(CONTENT_ROOT, "packs", "rules", "rules-pack-0.1.json"),
         items_field: "rules",
         path_field: "path",
+        path_pattern: /^(?:coding\/.+\.md|AGENTS\.md|main\.md)$/,
         body_field: "body",
         banner: RULES_BANNER,
     },
@@ -91,6 +225,7 @@ export const RENDER_REGISTRY = {
         source: join(CONTENT_ROOT, "packs", "strategies", "strategies-pack-0.1.json"),
         items_field: "strategies",
         path_field: "path",
+        path_pattern: /^strategies\/.+\.md$/,
         body_field: "body",
         banner: STRATEGIES_BANNER,
     },
@@ -100,6 +235,7 @@ export const RENDER_REGISTRY = {
         source: join(CONTENT_ROOT, "packs", "patterns", "patterns-pack-0.1.json"),
         items_field: "patterns",
         path_field: "path",
+        path_pattern: /^patterns\/.+\.md$/,
         body_field: "body",
         banner: PATTERNS_BANNER,
     },
@@ -109,6 +245,7 @@ export const RENDER_REGISTRY = {
         source: join(CONTENT_ROOT, "packs", "swarm-spec", "swarm-spec-pack-0.1.json"),
         items_field: "entries",
         path_field: "path",
+        path_pattern: /^swarm\/.+\.md$/,
         body_field: "body",
         banner: SWARM_SPEC_BANNER,
     },
@@ -166,12 +303,18 @@ function emitDescription(description) {
     return lines.join("\n");
 }
 export function renderSkillDocument(entry, cfg) {
-    const name = entry[cfg.name_field ?? "id"];
-    const description = entry[cfg.description_field ?? "description"];
+    // Sanitize every YAML frontmatter field so a malicious pack cannot inject
+    // unescaped frontmatter (newline -> extra key / premature `---`) or a null
+    // byte. Refs #2914 / #2904 (skill-pack-supply-01).
+    const nameField = cfg.name_field ?? "id";
+    const descriptionField = cfg.description_field ?? "description";
+    const name = sanitizeSingleLineField(String(entry[nameField]), "skills", nameField);
+    const description = assertNoNullByte(String(entry[descriptionField]), "skills", descriptionField);
     const body = entry[cfg.body_field] ?? "";
     const extra = entry.frontmatter_extra;
-    const extraBlock = typeof extra === "string" && extra.length > 0 ? `${extra}\n` : "";
-    const frontmatter = `---\nname: ${String(name)}\n${emitDescription(String(description))}\n${extraBlock}---\n`;
+    const extraStr = typeof extra === "string" ? assertNoNullByte(extra, "skills", "frontmatter_extra") : "";
+    const extraBlock = extraStr.length > 0 ? `${extraStr}\n` : "";
+    const frontmatter = `---\nname: ${name}\n${emitDescription(description)}\n${extraBlock}---\n`;
     return `${frontmatter}${bannerText(cfg.banner)}\n${String(body)}`;
 }
 export function renderMarkdownDocument(entry, cfg) {
@@ -182,7 +325,7 @@ const DOCUMENT_RENDERERS = {
     skill: renderSkillDocument,
     markdown: renderMarkdownDocument,
 };
-function targetsForPack(pack, cfg) {
+export function targetsForPack(packName, pack, cfg) {
     if (cfg.mode === "collection") {
         return [[cfg.output ?? "", renderCollection(pack, cfg)]];
     }
@@ -203,7 +346,10 @@ function targetsForPack(pack, cfg) {
         const pathField = cfg.path_field ?? "path";
         // Document projection targets (skills/rules/strategies/patterns) are
         // shippable content -- they live under content/ in the source repo (#1875).
-        const outPath = join(CONTENT_ROOT, String(record[pathField]));
+        // #2914: contain the pack-supplied path under CONTENT_ROOT and enforce the
+        // pack schema path pattern BEFORE render so a malicious pack JSON cannot
+        // write outside content/ via an absolute / `..` / null-byte path.
+        const outPath = containedOutPath(packName, record[pathField], cfg);
         targets.push([outPath, docRenderer(record, cfg)]);
     }
     return targets;
@@ -218,7 +364,7 @@ export function collectTargets(packFilter) {
             throw new Error(`pack source not found: ${cfg.source}`);
         }
         const pack = JSON.parse(readFileSync(cfg.source, "utf8"));
-        for (const [outPath, text] of targetsForPack(pack, cfg)) {
+        for (const [outPath, text] of targetsForPack(name, pack, cfg)) {
             targets.push([name, outPath, text]);
         }
     }

package/dist/packs/quarantine-ext.d.ts

@@ -2,6 +2,16 @@
 export declare const SUSPICIOUS_TOKENS: readonly string[];
 export declare const QUARANTINE_FENCE_OPEN = "```quarantined";
 export declare const QUARANTINE_FENCE_CLOSE = "```";
+/**
+ * Neutralize a body line so it cannot act as a CommonMark fence open/close.
+ * Used on content placed inside a ```quarantined wrapper (#2915 / cache-quarantine-03).
+ *
+ * A nested bare ``` (or longer run, optional ≤3-space indent) would otherwise
+ * early-close the outer fence and let following attacker text render outside
+ * the quarantined info-string. Break the delimiter run by inserting a backslash
+ * after the first fence character: ``` → `\`` , ~~~ → ~\~~ .
+ */
+export declare function neutralizeFenceLine(line: string): string;
 export declare function quarantineBody(rawMd: string): string;
 export declare function main(argv?: string[]): number;
 //# sourceMappingURL=quarantine-ext.d.ts.map

package/dist/packs/quarantine-ext.js

@@ -28,6 +28,26 @@ export const SUSPICIOUS_TOKENS = [
 ];
 export const QUARANTINE_FENCE_OPEN = "```quarantined";
 export const QUARANTINE_FENCE_CLOSE = "```";
+/**
+ * Neutralize a body line so it cannot act as a CommonMark fence open/close.
+ * Used on content placed inside a ```quarantined wrapper (#2915 / cache-quarantine-03).
+ *
+ * A nested bare ``` (or longer run, optional ≤3-space indent) would otherwise
+ * early-close the outer fence and let following attacker text render outside
+ * the quarantined info-string. Break the delimiter run by inserting a backslash
+ * after the first fence character: ``` → `\`` , ~~~ → ~\~~ .
+ */
+export function neutralizeFenceLine(line) {
+    const match = /^( {0,3})(`{3,}|~{3,})(.*)$/.exec(line);
+    if (match === null)
+        return line;
+    const indent = match[1] ?? "";
+    const delim = match[2] ?? "";
+    const rest = match[3] ?? "";
+    // One backslash after the first fence char breaks the delimiter run.
+    // Concat (not a template literal) so "\\" is unambiguously a single "\".
+    return indent + delim[0] + "\\" + delim.slice(1) + rest;
+}
 function isWordChar(ch) {
     return ((ch >= "A" && ch <= "Z") || (ch >= "a" && ch <= "z") || (ch >= "0" && ch <= "9") || ch === "_");
 }
@@ -133,14 +153,18 @@ export function quarantineBody(rawMd) {
                 sectionEnd += 1;
             }
             out.push(QUARANTINE_FENCE_OPEN);
-            out.push(...lines.slice(i, sectionEnd));
+            // #2915: neutralize nested fence lines so they cannot early-close.
+            for (const bodyLine of lines.slice(i, sectionEnd)) {
+                out.push(neutralizeFenceLine(bodyLine));
+            }
             out.push(QUARANTINE_FENCE_CLOSE);
             i = sectionEnd;
             continue;
         }
         if (isSuspicious(line)) {
             out.push(QUARANTINE_FENCE_OPEN);
-            out.push(line);
+            // #2915: neutralize in case the single line itself is fence-shaped.
+            out.push(neutralizeFenceLine(line));
             out.push(QUARANTINE_FENCE_CLOSE);
             i += 1;
             continue;

package/dist/policy/index.d.ts

@@ -4,6 +4,7 @@ export * from "./capacity.js";
 export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./host-hooks.js";
+export * from "./no-deft-directive.js";
 export * from "./org-force-on-migration.js";
 export * from "./plan-extensions.js";
 export * from "./policy-invocation.js";

package/dist/policy/index.js

@@ -12,6 +12,7 @@ export * from "./capacity.js";
 export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./host-hooks.js";
+export * from "./no-deft-directive.js";
 export * from "./org-force-on-migration.js";
 export * from "./plan-extensions.js";
 export * from "./policy-invocation.js";

package/dist/policy/no-deft-directive.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Official per-project opt-out flag for Directive (#2926).
+ *
+ * Presence of root `.no-deft-directive` means this project does not use
+ * Directive. Session ritual, doctor setup pressure, init/update install paths,
+ * and setup skills must honor the flag. Empty file or a short comment is enough.
+ *
+ * Product choices (v1):
+ * - Flag is **root-only** (workspace root the tool opened). Nested monorepo
+ *   package roots are a documented follow-up.
+ * - Flag **wins locally** over ambient trusted-org / product-signal force-on.
+ * - Flag + deposit (`.deft/core`) is **inconsistent**: doctor **warns**;
+ *   mutating install/update paths **fail closed**.
+ * - Creating the flag does **not** delete an existing deposit.
+ */
+/** Canonical root-only filename (lowercase). Presence = flag. */
+export declare const NO_DEFT_DIRECTIVE_FLAG_NAME = ".no-deft-directive";
+/** One-line operator message when Directive is disabled by the flag. */
+export declare const NO_DEFT_DIRECTIVE_DISABLED_MESSAGE = "Directive disabled via `.no-deft-directive`";
+/**
+ * Loud diagnosis when both the opt-out flag and a deposit exist.
+ * Product choice (#2926): doctor **warns**; install/update **fail closed**.
+ */
+export declare const NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE = "Inconsistent state: `.no-deft-directive` is present but a Directive deposit (`.deft/core`) also exists. Remove the flag to use Directive, or remove the deposit if opt-out is intentional.";
+/** Recorded product choice for inconsistent flag+deposit handling. */
+export declare const NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY: "warn-and-fail-closed";
+export interface NoDeftDirectiveSeams {
+    readonly isFile?: (path: string) => boolean;
+    readonly isDir?: (path: string) => boolean;
+}
+export interface NoDeftDirectiveState {
+    readonly present: boolean;
+    readonly flagPath: string;
+    readonly depositPresent: boolean;
+    /** True when flag and deposit are both present. */
+    readonly inconsistent: boolean;
+}
+/** Absolute path to the root flag file. */
+export declare function noDeftDirectiveFlagPath(projectRoot: string): string;
+/**
+ * Detect root `.no-deft-directive` and whether a deposit is also present.
+ * Presence is file-existence only (empty or short comment OK).
+ */
+export declare function detectNoDeftDirective(projectRoot: string, seams?: NoDeftDirectiveSeams): NoDeftDirectiveState;
+/** True when the root opt-out flag file exists. */
+export declare function isNoDeftDirectivePresent(projectRoot: string, seams?: NoDeftDirectiveSeams): boolean;
+/**
+ * Create the root opt-out flag. Optional one-line rationale becomes a `#` comment.
+ * Does not remove an existing deposit.
+ */
+export declare function createNoDeftDirectiveFlag(projectRoot: string, options?: {
+    rationale?: string;
+}): string;
+/**
+ * Remove the root opt-out flag when present.
+ * @returns true when a file was removed.
+ */
+export declare function removeNoDeftDirectiveFlag(projectRoot: string): boolean;
+//# sourceMappingURL=no-deft-directive.d.ts.map

package/dist/policy/no-deft-directive.js

@@ -0,0 +1,103 @@
+/**
+ * Official per-project opt-out flag for Directive (#2926).
+ *
+ * Presence of root `.no-deft-directive` means this project does not use
+ * Directive. Session ritual, doctor setup pressure, init/update install paths,
+ * and setup skills must honor the flag. Empty file or a short comment is enough.
+ *
+ * Product choices (v1):
+ * - Flag is **root-only** (workspace root the tool opened). Nested monorepo
+ *   package roots are a documented follow-up.
+ * - Flag **wins locally** over ambient trusted-org / product-signal force-on.
+ * - Flag + deposit (`.deft/core`) is **inconsistent**: doctor **warns**;
+ *   mutating install/update paths **fail closed**.
+ * - Creating the flag does **not** delete an existing deposit.
+ */
+import { existsSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { CANONICAL_INSTALL_ROOT } from "../init-deposit/constants.js";
+/** Canonical root-only filename (lowercase). Presence = flag. */
+export const NO_DEFT_DIRECTIVE_FLAG_NAME = ".no-deft-directive";
+/** One-line operator message when Directive is disabled by the flag. */
+export const NO_DEFT_DIRECTIVE_DISABLED_MESSAGE = "Directive disabled via `.no-deft-directive`";
+/**
+ * Loud diagnosis when both the opt-out flag and a deposit exist.
+ * Product choice (#2926): doctor **warns**; install/update **fail closed**.
+ */
+export const NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE = "Inconsistent state: `.no-deft-directive` is present but a Directive deposit (`.deft/core`) also exists. Remove the flag to use Directive, or remove the deposit if opt-out is intentional.";
+/** Recorded product choice for inconsistent flag+deposit handling. */
+export const NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY = "warn-and-fail-closed";
+function defaultIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultIsDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Absolute path to the root flag file. */
+export function noDeftDirectiveFlagPath(projectRoot) {
+    return resolve(projectRoot, NO_DEFT_DIRECTIVE_FLAG_NAME);
+}
+/**
+ * Detect root `.no-deft-directive` and whether a deposit is also present.
+ * Presence is file-existence only (empty or short comment OK).
+ */
+export function detectNoDeftDirective(projectRoot, seams = {}) {
+    const flagPath = noDeftDirectiveFlagPath(projectRoot);
+    const isFile = seams.isFile ?? defaultIsFile;
+    const isDir = seams.isDir ?? defaultIsDir;
+    const present = isFile(flagPath);
+    const depositPresent = isDir(join(projectRoot, CANONICAL_INSTALL_ROOT));
+    return {
+        present,
+        flagPath,
+        depositPresent,
+        inconsistent: present && depositPresent,
+    };
+}
+/** True when the root opt-out flag file exists. */
+export function isNoDeftDirectivePresent(projectRoot, seams = {}) {
+    return detectNoDeftDirective(projectRoot, seams).present;
+}
+/**
+ * Create the root opt-out flag. Optional one-line rationale becomes a `#` comment.
+ * Does not remove an existing deposit.
+ */
+export function createNoDeftDirectiveFlag(projectRoot, options = {}) {
+    const path = noDeftDirectiveFlagPath(projectRoot);
+    assertWriteTargetSafe(projectRoot, path);
+    if (defaultIsDir(path)) {
+        throw new Error(`${NO_DEFT_DIRECTIVE_FLAG_NAME} exists as a directory at ${path}; remove it before creating the opt-out flag file.`);
+    }
+    const rationale = options.rationale?.trim() ?? "";
+    const body = rationale.length > 0 ? `# ${rationale}\n` : "";
+    writeFileSync(path, body, "utf8");
+    return path;
+}
+/**
+ * Remove the root opt-out flag when present.
+ * @returns true when a file was removed.
+ */
+export function removeNoDeftDirectiveFlag(projectRoot) {
+    const path = noDeftDirectiveFlagPath(projectRoot);
+    if (!existsSync(path)) {
+        return false;
+    }
+    assertWriteTargetSafe(projectRoot, path);
+    if (defaultIsDir(path)) {
+        throw new Error(`${NO_DEFT_DIRECTIVE_FLAG_NAME} exists as a directory at ${path}; remove the directory manually before enabling Directive.`);
+    }
+    unlinkSync(path);
+    return true;
+}
+//# sourceMappingURL=no-deft-directive.js.map