@deftai/directive-core 0.86.0 → 0.88.0

package/dist/init-deposit/agent-hooks.js

@@ -1,9 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
-import { DIRECT_WRITE_HOOK_MATCHER, SPAWN_HOOK_MATCHER } from "../hooks/tools.js";
+import { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
 import { isHostHookDepositEnabled, loadHostHooksPolicyFromProject, } from "../policy/host-hooks.js";
-export { DIRECT_WRITE_HOOK_MATCHER, SPAWN_HOOK_MATCHER } from "../hooks/tools.js";
+export { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
 export const DEFT_HOOK_COMMAND_MARKER = "deft-hook";
 export const LEGACY_DEFT_HOOK_COMMAND_MARKER = "deft hook:dispatch";
 export const AGENT_HOOK_PATHS = [
@@ -103,6 +103,10 @@ function mergeNestedConfig(config, path, host, options = {}) {
         ...preTool,
         nestedGroup(host, "tool.before", DIRECT_WRITE_HOOK_MATCHER),
         nestedGroup(host, "tool.before", SPAWN_HOOK_MATCHER),
+        // Shell/Bash for runtimeAuthority scopes.push / scopes.merge (#2711)
+        nestedGroup(host, "tool.before", SHELL_HOOK_MATCHER),
+        // MCP push/merge (mcp__*, bare merge_pull_request / git_push, …) (#2711)
+        nestedGroup(host, "tool.before", MCP_HOOK_MATCHER),
     ];
     if (options.compact) {
         const preCompact = eventArray(hooks, "PreCompact", path).filter((entry) => !isManagedNestedGroup(entry));
@@ -164,6 +168,18 @@ function mergeCursorConfig(config, path) {
             failClosed: true,
             timeout: 5,
         },
+        {
+            command: command("cursor", "tool.before"),
+            matcher: SHELL_HOOK_MATCHER,
+            failClosed: true,
+            timeout: 5,
+        },
+        {
+            command: command("cursor", "tool.before"),
+            matcher: MCP_HOOK_MATCHER,
+            failClosed: true,
+            timeout: 5,
+        },
     ];
     hooks.preCompact = [...preCompact, { command: command("cursor", "session.compact"), timeout: 5 }];
     return { ...config, version: 1, hooks };
@@ -285,6 +301,14 @@ function hasNestedRegistration(config, host, options = {}) {
         preTool.some((entry) => {
             const group = object(entry);
             return group?.matcher === SPAWN_HOOK_MATCHER && nestedCommands(entry).includes(toolCommand);
+        }) &&
+        preTool.some((entry) => {
+            const group = object(entry);
+            return group?.matcher === SHELL_HOOK_MATCHER && nestedCommands(entry).includes(toolCommand);
+        }) &&
+        preTool.some((entry) => {
+            const group = object(entry);
+            return group?.matcher === MCP_HOOK_MATCHER && nestedCommands(entry).includes(toolCommand);
         });
     if (!base)
         return false;
@@ -315,6 +339,18 @@ function hasCursorRegistration(config) {
                 hook.matcher === SPAWN_HOOK_MATCHER &&
                 hook.failClosed === true);
         }) &&
+        preTool.some((entry) => {
+            const hook = object(entry);
+            return (hook?.command === command("cursor", "tool.before") &&
+                hook.matcher === SHELL_HOOK_MATCHER &&
+                hook.failClosed === true);
+        }) &&
+        preTool.some((entry) => {
+            const hook = object(entry);
+            return (hook?.command === command("cursor", "tool.before") &&
+                hook.matcher === MCP_HOOK_MATCHER &&
+                hook.failClosed === true);
+        }) &&
         preCompact.some((entry) => object(entry)?.command === command("cursor", "session.compact")));
 }
 /** Read-only registration probe shared by verify and doctor. */

package/dist/init-deposit/hygiene.d.ts

@@ -77,8 +77,24 @@ export interface PrunePackageAbsentDepositPathsResult {
  * Remove deposit files not shipped by `@deftai/directive-content`, preserving
  * generated deposit metadata such as `VERSION` (#2804). Subsumes the legacy
  * hard-coded `packages/` prune (#2347).
+ *
+ * Individual removal failures are reported but do not throw — callers that must
+ * refuse a VERSION stamp until the deposit matches the content package should
+ * use {@link reconcileDepositToContentPackage} (#2913).
  */
 export declare function prunePackageAbsentDepositPaths(deftDir: string, contentRoot: string, io: InitDepositIo): Promise<PrunePackageAbsentDepositPathsResult>;
+/**
+ * Fail-closed deposit reconcile against the installed content package (#2913).
+ *
+ * Runs {@link prunePackageAbsentDepositPaths}, then re-scans. If any
+ * package-absent path remains, throws so callers refuse the VERSION stamp
+ * (dst-only stale/malicious agent content must not survive a refresh).
+ *
+ * After a successful {@link replaceTree} full-swap this is typically a no-op
+ * verification; it also covers additive copy seams and the already-current
+ * refresh path that skips payload copy.
+ */
+export declare function reconcileDepositToContentPackage(deftDir: string, contentRoot: string, io: InitDepositIo): Promise<PrunePackageAbsentDepositPathsResult>;
 export interface PruneStrayDepositPathsResult {
     readonly pruned: string[];
 }

package/dist/init-deposit/hygiene.js

@@ -257,6 +257,10 @@ async function pruneEmptyParentsForFile(deftDir, contentDirs, relFile) {
  * Remove deposit files not shipped by `@deftai/directive-content`, preserving
  * generated deposit metadata such as `VERSION` (#2804). Subsumes the legacy
  * hard-coded `packages/` prune (#2347).
+ *
+ * Individual removal failures are reported but do not throw — callers that must
+ * refuse a VERSION stamp until the deposit matches the content package should
+ * use {@link reconcileDepositToContentPackage} (#2913).
  */
 export async function prunePackageAbsentDepositPaths(deftDir, contentRoot, io) {
     const absent = await findPackageAbsentDepositPaths(deftDir, contentRoot);
@@ -278,6 +282,28 @@ export async function prunePackageAbsentDepositPaths(deftDir, contentRoot, io) {
     }
     return { pruned, prunedDirs };
 }
+/**
+ * Fail-closed deposit reconcile against the installed content package (#2913).
+ *
+ * Runs {@link prunePackageAbsentDepositPaths}, then re-scans. If any
+ * package-absent path remains, throws so callers refuse the VERSION stamp
+ * (dst-only stale/malicious agent content must not survive a refresh).
+ *
+ * After a successful {@link replaceTree} full-swap this is typically a no-op
+ * verification; it also covers additive copy seams and the already-current
+ * refresh path that skips payload copy.
+ */
+export async function reconcileDepositToContentPackage(deftDir, contentRoot, io) {
+    const result = await prunePackageAbsentDepositPaths(deftDir, contentRoot, io);
+    const remaining = await findPackageAbsentDepositPaths(deftDir, contentRoot);
+    if (remaining.length > 0) {
+        const sample = remaining.slice(0, 5).join(", ");
+        const more = remaining.length > 5 ? ` (+${remaining.length - 5} more)` : "";
+        throw new Error(`deposit reconcile failed: ${remaining.length} package-absent path(s) remain under .deft/core ` +
+            `(e.g. ${sample}${more}). Refusing VERSION stamp until dst-only content is removed (#2913).`);
+    }
+    return result;
+}
 /**
  * Remove framework-source subdirectories from `.deft/core/` that are not
  * present in the deposited content package (#2347). Silently skips any path

package/dist/init-deposit/init-dispatch.js

@@ -21,6 +21,7 @@
  * dispatcher never re-implements deposit, refresh, or migrate behavior.
  */
 import { resolve } from "node:path";
+import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
 import { classify, plan } from "../resolution/index.js";
 import { runInitDepositCli } from "./init-deposit.js";
 import { runMigrateCli } from "./migrate.js";
@@ -119,6 +120,33 @@ export async function runInitDispatchCli(options) {
                 options.writeOut(text);
         },
     };
+    // #2926: root opt-out — do not scaffold/install/refresh when flag is present.
+    const optOut = detectNoDeftDirective(projectDir);
+    if (optOut.present) {
+        io.printf(`\n[directive init] ${NO_DEFT_DIRECTIVE_DISABLED_MESSAGE}\n`);
+        if (optOut.inconsistent) {
+            io.printf(`[directive init] ${NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE}\n`);
+        }
+        if (options.jsonOut) {
+            options.writeOut(`${JSON.stringify({
+                success: false,
+                action: "init",
+                disabled: true,
+                disabled_via: NO_DEFT_DIRECTIVE_FLAG_NAME,
+                inconsistent: optOut.inconsistent,
+                ...(optOut.inconsistent
+                    ? { inconsistent_policy: NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY }
+                    : {}),
+                deposit_present: optOut.depositPresent,
+                project_dir: projectDir,
+                message: optOut.inconsistent
+                    ? NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE
+                    : NO_DEFT_DIRECTIVE_DISABLED_MESSAGE,
+            }, null, 2)}\n`);
+        }
+        // Clean opt-out is a successful short-circuit; inconsistent state fails closed.
+        return optOut.inconsistent ? 1 : 0;
+    }
     const classification = classifyInitDispatch(projectDir, seams.classifySeams ?? {});
     const { decision, plan: resolutionPlan } = classification;
     printInitDispatchSummary(io, decision, resolutionPlan);

package/dist/init-deposit/prettierignore.js

@@ -9,7 +9,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { assertProjectionContained } from "../fs/projection-containment.js";
+import { assertDestinationNotSymlink } from "../fs/projection-containment.js";
 import { stripGitignoreInlineComment } from "../triage/bootstrap/gitignore.js";
 /** Directory ignore entry for the hybrid deposit. */
 export const PRETTIERIGNORE_DEFT_CORE_LINE = ".deft/core/";
@@ -18,7 +18,7 @@ const DEFT_CORE_COVERING_LINES = new Set([".deft/core/", ".deft/core", ".deft/co
 const DEFT_FRAMEWORK_PRETTIERIGNORE_HEADER = "# Deft framework: the vendored payload is outside the consumer Prettier gate (#2534).\n";
 function projectionTarget(projectDir) {
     const target = join(projectDir, ".prettierignore");
-    assertProjectionContained(projectDir, target);
+    assertDestinationNotSymlink(projectDir, target);
     return target;
 }
 function prettierIgnoreCoversLine(present, line) {

package/dist/init-deposit/refresh.js

@@ -12,19 +12,20 @@ import { existsSync, readFileSync, renameSync, statSync } from "node:fs";
 import { platform as osPlatform } from "node:os";
 import { join, resolve } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
-import { copyTree } from "../deposit/copy-tree.js";
+import { replaceTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
+import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
 import { runOrgForceOnMigration } from "../policy/org-force-on-migration.js";
 import { checkLocalEngineIntegrity, classify, ENGINE_PACKAGE, plan, renderGlobalInstall, resolveEngine, } from "../resolution/index.js";
 import { gitPorcelain } from "../story-ready/git.js";
 import { removeStaleMigratedFrameworkNarrative } from "../xbrief-migrate/migrate-project.js";
 import { writeAgentHookDeposit } from "./agent-hooks.js";
 import { ensureInitGitignoreLines, isDepositTrackedInGit } from "./gitignore.js";
-import { depositStagePaths, isInstallerManagedPath, printCommitGuidance, prunePackageAbsentDepositPaths, } from "./hygiene.js";
+import { depositStagePaths, isInstallerManagedPath, printCommitGuidance, reconcileDepositToContentPackage, } from "./hygiene.js";
 import { parseInitArgv } from "./init-deposit.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
 import { printMigrateNudgeIfNeeded } from "./migrate.js";
@@ -392,7 +393,9 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     // the resolved project tree. Writes nothing on refusal.
     assertDepositContained(projectDir, deftDir);
     const resolveContent = seams.resolveContentRoot ?? resolveInstalledContentRoot;
-    const copyContent = seams.copyContent ?? copyTree;
+    // #2913: default is full-tree replace (Go swapInCore parity), not additive copyTree.
+    // Injected seams.copyContent still wins (tests / specialized callers).
+    const copyContent = seams.copyContent ?? replaceTree;
     const readEngine = seams.readEngineVersion ?? readCorePackageVersion;
     const readPackageVersion = seams.readPackageVersion ?? readCorePackageVersion;
     const contentRoot = await resolveContent();
@@ -406,15 +409,19 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     const strategy = alreadyCurrent ? "no-op" : "file-swap";
     if (alreadyCurrent) {
         io.printf("[deft update] Framework payload already current; skipping payload copy.\n");
+        // #2913: still fail-closed reconcile so dst-only leftovers cannot linger when
+        // VERSION already matches (e.g. pre-#2804 additive deposits). Does not re-stamp.
+        await reconcileDepositToContentPackage(deftDir, contentRoot, io);
         migrateLegacyInstallManifest(projectDir, join(deftDir, "VERSION"));
     }
     else {
+        // Full-tree replace (or injected seam). Additive copy is no longer the default.
         await copyContent(contentRoot, deftDir);
         await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
-        // #2804 / #2347: prune deposit paths absent from the content package. The
-        // additive file-swap never removes them, causing stale bridge-era files to
-        // survive across upgrades until manually cleaned.
-        await prunePackageAbsentDepositPaths(deftDir, contentRoot, io);
+        // #2913 / #2804 / #2347: fail-closed delete-not-in-source BEFORE VERSION stamp.
+        // replaceTree already drops dst-only paths; reconcile verifies and covers
+        // additive seams. Throws => no VERSION rewrite (refuse stamp until clean).
+        await reconcileDepositToContentPackage(deftDir, contentRoot, io);
         const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
         const manifestFields = {
             ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
@@ -586,6 +593,30 @@ export async function runRefreshDepositCli(options) {
     // Legacy layouts keep their existing refusal path (thrown by runRefreshDeposit
     // and handled below), so classification is skipped for them.
     const projectDir = resolve(options.projectDir);
+    // #2926: root opt-out wins over update/refresh and ambient force-on.
+    const optOut = detectNoDeftDirective(projectDir);
+    if (optOut.present) {
+        const message = optOut.inconsistent
+            ? NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE
+            : NO_DEFT_DIRECTIVE_DISABLED_MESSAGE;
+        io.printf(`${message}\n`);
+        if (options.jsonOut) {
+            options.writeOut(`${JSON.stringify({
+                success: false,
+                action: "update",
+                disabled: true,
+                disabled_via: NO_DEFT_DIRECTIVE_FLAG_NAME,
+                inconsistent: optOut.inconsistent,
+                ...(optOut.inconsistent
+                    ? { inconsistent_policy: NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY }
+                    : {}),
+                deposit_present: optOut.depositPresent,
+                project_dir: projectDir,
+                message,
+            }, null, 2)}\n`);
+        }
+        return UPDATE_REFUSED_EXIT_CODE;
+    }
     const detectLegacy = options.seams?.detectLegacy ?? detectLegacyLayout;
     let classification = null;
     if (!detectLegacy(projectDir).legacy) {

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-emit.d.ts

@@ -1,11 +1,51 @@
 import type { ScmCallFn } from "./reconcile-issues.js";
 export declare const GITHUB_ISSUE_REF_TYPE = "x-xbrief/github-issue";
 export declare const EXTERNAL_TRUST_LEVEL = "external";
+/**
+ * Structured post-create failure: remote issue exists; local stamp/ledger may not.
+ * `createdUrl` is the durable handle for retry (also mirrored in process + OS-temp recovery).
+ */
 export declare class IssueEmitError extends Error {
-    constructor(message: string);
+    readonly createdUrl?: string;
+    constructor(message: string, options?: {
+        createdUrl?: string;
+    });
 }
+export declare function recoverySidecarPath(vbriefAbsPath: string): string;
+/**
+ * Always-on recovery after remote create: process memory + private OS-temp sidecar.
+ * Independent of project-contained ledger so dual local failure still reconciles on retry (#2880).
+ */
+export declare function rememberCreatedUrl(vbriefAbsPath: string, url: string): void;
+export declare function loadRecoveredUrl(vbriefAbsPath: string): string | undefined;
+export declare function clearRecoveredUrl(vbriefAbsPath: string): void;
+/** Project ledger first, then process/OS-temp recovery (#2880). */
+export declare function resolvePriorCreatedUrl(projectRoot: string, vbriefAbsPath: string): string | undefined;
+/**
+ * Record URL immediately after remote create. Project ledger is best-effort;
+ * recovery layers always run first so dual local failure cannot force re-create (#2880).
+ */
+export declare function recordCreatedUrlDurable(projectRoot: string, vbriefAbsPath: string, url: string): void;
+/** Contained durable map: abs vbrief path -> issue URL for in-flight emits (#2871). */
+export declare function pendingEmitLedgerPath(projectRoot: string): string;
+export declare function loadPendingEmitUrls(projectRoot: string): Record<string, string>;
+export declare function savePendingEmitUrl(projectRoot: string, vbriefAbsPath: string, url: string): void;
+export declare function clearPendingEmitUrl(projectRoot: string, vbriefAbsPath: string): void;
 export declare function loadVbrief(path: string): Record<string, unknown>;
-export declare function writeVbrief(path: string, data: Record<string, unknown>): void;
+/**
+ * Resolve project root and refuse unsafe write targets before any emit side-effect.
+ * Callers that create remote issues MUST invoke this before `fileIssue` so a
+ * containment refusal cannot leave an orphan GitHub issue (#2869 / #2871).
+ *
+ * ⊗ Do not fall back to `dirname(path)` as the containment root — that trusts a
+ * possibly-symlinked parent and would re-open the escape (Greptile P1 on #2871).
+ */
+export declare function assertVbriefWriteTargetSafe(path: string, projectRoot?: string | null): string;
+/**
+ * Persist an xBRIEF/vBRIEF JSON document. Gates the write target so a leaf or
+ * parent-directory symlink cannot divert the stamped file outside the project (#2869).
+ */
+export declare function writeVbrief(path: string, data: Record<string, unknown>, projectRoot?: string | null): void;
 export declare function vbriefTitle(data: Record<string, unknown>): string;
 export declare function existingGithubIssueRef(data: Record<string, unknown>): string | null | undefined;
 export declare function addGithubIssueReference(data: Record<string, unknown>, url: string): Record<string, unknown>;
@@ -23,12 +63,14 @@ export declare function emitSingle(path: string, options: {
     scmCall?: ScmCallFn;
     noNetwork?: boolean;
     displayPath?: string | null;
+    projectRoot?: string | null;
 }): EmitAction;
 export declare function emitPerVbrief(paths: string[], options: {
     repo: string;
     scmCall?: ScmCallFn;
     noNetwork?: boolean;
     displayPaths?: string[] | null;
+    projectRoot?: string | null;
 }): EmitAction[];
 export interface UmbrellaAction {
     result: "created" | "dryrun" | "skipped";
@@ -45,6 +87,7 @@ export declare function emitUmbrella(paths: string[], options: {
     noNetwork?: boolean;
     title?: string | null;
     displayPaths?: string[] | null;
+    projectRoot?: string | null;
 }): UmbrellaAction;
 export declare function expandPatterns(patterns: string[], root?: string | null): string[];
 export declare function isNoNetwork(dryRun: boolean): boolean;