@deftai/directive-core 0.107.0 → 0.109.0

package/dist/validate-content/deposit-required.js

@@ -0,0 +1,147 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * C1 declared deposit closure (#3601 / #3899).
+ *
+ * Required consumer-deposit paths are a closed typed declaration, not a
+ * regex over AGENTS.md RFC2119 prose. Existence checks reuse existsSync
+ * the same way validate-links.ts does, against a staged pack root (the
+ * prepack flatten), not the source checkout.
+ */
+export const DEPOSIT_REQUIRED_SCHEMA = "deft.deposit-required-paths.v1";
+export const DEPOSIT_REQUIRED_REL = "contracts/deposit-required-paths.json";
+export const DEPOSIT_PREFIX = ".deft/core/";
+/** Parser-visible field. Not a scan of ! / backtick paths. */
+const DEPOSIT_REQUIRED_COMMENT = /<!--\s*deposit-required:\s+(\S+)\s*-->/g;
+export function extractDepositRequiredComments(source) {
+    const out = [];
+    const re = new RegExp(DEPOSIT_REQUIRED_COMMENT.source, "g");
+    let match = re.exec(source);
+    while (match !== null) {
+        const path = match[1];
+        if (path !== undefined) {
+            out.push(path);
+        }
+        match = re.exec(source);
+    }
+    return out;
+}
+export function parseDepositRequiredDeclaration(jsonText) {
+    let _data;
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`deposit-required: invalid JSON (${reason})`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("deposit-required: expected an object");
+    }
+    const data = parsed;
+    if (data.schema !== DEPOSIT_REQUIRED_SCHEMA) {
+        throw new Error("deposit-required: expected schema " +
+            DEPOSIT_REQUIRED_SCHEMA +
+            ", got " +
+            String(data.schema));
+    }
+    if (!Array.isArray(data.paths) || data.paths.length === 0) {
+        throw new Error("deposit-required: paths must be a non-empty array of strings");
+    }
+    const paths = [];
+    for (const item of data.paths) {
+        if (typeof item !== "string" ||
+            !item.startsWith(DEPOSIT_PREFIX) ||
+            item.includes("\\") ||
+            item.includes("..")) {
+            throw new Error(`deposit-required: invalid path ${String(item)}`);
+        }
+        paths.push(item);
+    }
+    return { schema: DEPOSIT_REQUIRED_SCHEMA, paths };
+}
+export function packRelativeFromDepositPath(declared) {
+    if (!declared.startsWith(DEPOSIT_PREFIX)) {
+        throw new Error(`deposit-required: not a deposit path: ${declared}`);
+    }
+    return declared.slice(DEPOSIT_PREFIX.length);
+}
+/** Prepack mapping used by @deftai/directive-content. */
+export function sourcePathForPackRelative(repoRoot, packRelative) {
+    const rel = packRelative.replace(/\\/g, "/");
+    if (rel === "main.md" ||
+        rel === "SKILL.md" ||
+        rel === "Taskfile.yml" ||
+        rel.startsWith("tasks/") ||
+        rel.startsWith(".githooks/")) {
+        return join(repoRoot, ...rel.split("/"));
+    }
+    return join(repoRoot, "content", ...rel.split("/"));
+}
+export function evaluateDepositClosure(options) {
+    const missing = [];
+    for (const declared of options.paths) {
+        const rel = packRelativeFromDepositPath(declared);
+        const target = join(options.packRoot, ...rel.split("/"));
+        if (!existsSync(target)) {
+            missing.push(declared);
+        }
+    }
+    return { ok: missing.length === 0, missing, checked: options.paths.length };
+}
+export function loadDepositRequiredDeclaration(filePath) {
+    return parseDepositRequiredDeclaration(readFileSync(filePath, "utf8"));
+}
+export function resolveDeclarationFile(root) {
+    const underContent = join(root, "content", DEPOSIT_REQUIRED_REL);
+    if (existsSync(underContent)) {
+        return underContent;
+    }
+    const underRoot = join(root, DEPOSIT_REQUIRED_REL);
+    if (existsSync(underRoot)) {
+        return underRoot;
+    }
+    return null;
+}
+export function evaluateInstalledDepositClosure(projectRoot) {
+    const deftDir = join(projectRoot, ".deft", "core");
+    const declarationPath = resolveDeclarationFile(deftDir) ?? resolveDeclarationFile(projectRoot);
+    if (declarationPath === null) {
+        return { skipped: true, missing: [], declarationPath: null, error: null };
+    }
+    if (!existsSync(deftDir)) {
+        return { skipped: true, missing: [], declarationPath, error: null };
+    }
+    try {
+        const declaration = loadDepositRequiredDeclaration(declarationPath);
+        const result = evaluateDepositClosure({ packRoot: deftDir, paths: declaration.paths });
+        return { skipped: false, missing: result.missing, declarationPath, error: null };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { skipped: false, missing: [], declarationPath, error: reason };
+    }
+}
+export function renderDeclaredDepositClosureLine(result) {
+    if (result.skipped) {
+        return "Deposit required-paths: skip -- no C1 declaration in this tree.";
+    }
+    if (result.error) {
+        return ("Deposit required-paths: fail -- could not read C1 declaration (" +
+            result.error +
+            "). Run directive update to refresh the deposit (#3601 C1).");
+    }
+    if (result.missing.length === 0) {
+        return "Deposit required-paths: ok -- declared C1 paths exist in .deft/core.";
+    }
+    const sample = result.missing.slice(0, 5).join(", ");
+    const extra = result.missing.length > 5 ? ` (+${String(result.missing.length - 5)} more)` : "";
+    return ("Deposit required-paths: fail -- " +
+        String(result.missing.length) +
+        " declared path(s) missing from .deft/core. Examples: " +
+        sample +
+        extra +
+        ". Run directive update to refresh the deposit (#3601 C1).");
+}
+//# sourceMappingURL=deposit-required.js.map

package/dist/validate-content/index.d.ts

@@ -1,5 +1,6 @@
 export { resolveCapacityAllocation } from "./capacity-policy.js";
 export { computeReport, renderReport } from "./capacity-show.js";
+export * as depositRequired from "./deposit-required.js";
 export { isDatePrefixedVbriefFilename } from "./filename.js";
 export { extractLinkTargets, shouldSkipLinkTarget } from "./link-parser.js";
 export * from "./types.js";

package/dist/validate-content/index.js

@@ -1,5 +1,6 @@
 export { resolveCapacityAllocation } from "./capacity-policy.js";
 export { computeReport, renderReport } from "./capacity-show.js";
+export * as depositRequired from "./deposit-required.js";
 export { isDatePrefixedVbriefFilename } from "./filename.js";
 export { extractLinkTargets, shouldSkipLinkTarget } from "./link-parser.js";
 export * from "./types.js";

package/dist/validate-content/validate-links.d.ts

@@ -18,8 +18,7 @@ export interface ValidateLinksOptions {
     readonly linkCheckStrict?: boolean;
     readonly argv?: readonly string[];
 }
-/**
- * Validate internal markdown links. Faithful to `scripts/validate-links.py`.
- */
+/** Collect broken internal markdown links under cwd. Used by packed-fixture tests (#3937). */
+export declare function collectBrokenLinks(cwd: string): BrokenLink[];
 export declare function evaluate(options?: ValidateLinksOptions): EvaluateResult;
 //# sourceMappingURL=validate-links.d.ts.map

package/dist/validate-content/validate-links.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
+import { evaluateLiveProcedureTargets, formatLiveProcedureFailure, } from "../deposit/live-procedure-targets.js";
 import { NON_PRODUCT_DIRS } from "../fs/non-product-dirs.js";
 import { extractLinkTargets, shouldSkipLinkTarget } from "./link-parser.js";
 /**
@@ -43,7 +44,8 @@ function collectMarkdownFiles(root) {
     walk(root, []);
     return out.sort();
 }
-function findBrokenLinks(cwd) {
+/** Collect broken internal markdown links under cwd. Used by packed-fixture tests (#3937). */
+export function collectBrokenLinks(cwd) {
     const broken = [];
     const root = resolve(cwd);
     for (const md of collectMarkdownFiles(root)) {
@@ -82,13 +84,38 @@ function findBrokenLinks(cwd) {
 /**
  * Validate internal markdown links. Faithful to `scripts/validate-links.py`.
  */
+function contentRootForC3(cwd) {
+    const underContent = join(cwd, "content");
+    return existsSync(underContent) ? underContent : cwd;
+}
+function extraMarkdownForC3(cwd) {
+    const extras = [];
+    for (const name of ["main.md", "SKILL.md"]) {
+        const absolutePath = join(cwd, name);
+        if (existsSync(absolutePath)) {
+            extras.push({ relativePath: name, absolutePath });
+        }
+    }
+    return extras;
+}
 export function evaluate(options = {}) {
     const cwd = resolve(options.cwd ?? ".");
     const strict = options.strict === true ||
         options.linkCheckStrict === true ||
         (options.argv ?? []).includes("--strict") ||
         process.env.LINK_CHECK_STRICT === "1";
-    const broken = findBrokenLinks(cwd);
+    const c3 = evaluateLiveProcedureTargets({
+        stagedRoot: contentRootForC3(cwd),
+        extraFiles: extraMarkdownForC3(cwd),
+    });
+    if (c3.uniqueTargets.length > 0) {
+        return {
+            code: 1,
+            message: formatLiveProcedureFailure(c3),
+            stream: "stdout",
+        };
+    }
+    const broken = collectBrokenLinks(cwd);
     if (broken.length === 0) {
         return {
             code: 0,

package/dist/vbrief-activate/activate.d.ts

@@ -6,8 +6,13 @@ export interface ActivateOptions {
     readonly now?: Date;
 }
 /**
- * Pure activator — returns ``{ exitCode, message }``. Faithful to
- * ``scripts/vbrief_activate.py::activate``.
+ * Pure activator -- returns ``{ exitCode, message }``. Ported from
+ * ``scripts/vbrief_activate.py::activate`` under the #1782 byte-identical
+ * parity contract, with one deliberate divergence: the Python oracle created a
+ * ``vBRIEFInfo`` when the artifact carried no envelope, and that behaviour is
+ * NOT preserved (#3933). Envelope handling now follows the shared lifecycle
+ * policy -- stamp whichever envelope exists, refuse an envelope-less artifact
+ * by name.
  */
 export declare function activate(vbriefPath: string, options?: ActivateOptions): ActivateResult;
 //# sourceMappingURL=activate.d.ts.map

package/dist/vbrief-activate/activate.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, unli
 import { basename, dirname, resolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
+import { BRIEF_ENVELOPE_KEYS, missingEnvelopeMessage, stampExistingEnvelopes, } from "../lifecycle/brief-envelope.js";
 import { evaluateEffortActivateGate } from "../scope/effort-activate-gate.js";
 import { utcNowIso } from "../scope/vbrief-json.js";
 import { pythonJsonPretty } from "../vbrief-build/json.js";
@@ -57,8 +58,13 @@ function loadVbrief(vbriefPath) {
     return { payload: payload, error: null };
 }
 /**
- * Pure activator — returns ``{ exitCode, message }``. Faithful to
- * ``scripts/vbrief_activate.py::activate``.
+ * Pure activator -- returns ``{ exitCode, message }``. Ported from
+ * ``scripts/vbrief_activate.py::activate`` under the #1782 byte-identical
+ * parity contract, with one deliberate divergence: the Python oracle created a
+ * ``vBRIEFInfo`` when the artifact carried no envelope, and that behaviour is
+ * NOT preserved (#3933). Envelope handling now follows the shared lifecycle
+ * policy -- stamp whichever envelope exists, refuse an envelope-less artifact
+ * by name.
  */
 export function activate(vbriefPath, options = {}) {
     const now = options.now ?? new Date();
@@ -143,19 +149,26 @@ export function activate(vbriefPath, options = {}) {
         }
         throw err;
     }
-    planObj.status = TARGET_STATUS;
-    let info = payload.vBRIEFInfo;
-    if (info === undefined) {
-        info = {};
-        payload.vBRIEFInfo = info;
+    for (const key of BRIEF_ENVELOPE_KEYS) {
+        if (!(key in payload)) {
+            continue;
+        }
+        const env = payload[key];
+        if (env === null || typeof env !== "object" || Array.isArray(env)) {
+            return {
+                exitCode: 1,
+                message: `vBRIEF at ${vbriefPath} has a non-object \`${key}\` -- malformed.`,
+            };
+        }
     }
-    if (info === null || typeof info !== "object" || Array.isArray(info)) {
-        return {
-            exitCode: 1,
-            message: `vBRIEF at ${vbriefPath} has a non-object \`vBRIEFInfo\` -- malformed.`,
-        };
+    // #3933: stamp the envelope the brief already carries; never create one. A
+    // manufactured version-less `vBRIEFInfo` wins schema resolution over a valid
+    // `xBRIEFInfo`, so the brief this verb just moved would fail validation.
+    const stampedEnvelopes = stampExistingEnvelopes(payload, utcNowIso(now));
+    if (stampedEnvelopes.length === 0) {
+        return { exitCode: 1, message: missingEnvelopeMessage(`vBRIEF at ${vbriefPath}`) };
     }
-    info.updated = utcNowIso(now);
+    planObj.status = TARGET_STATUS;
     try {
         mkdirSync(activeDir, { recursive: true });
     }

package/dist/vbrief-build/index.d.ts

@@ -3,7 +3,8 @@ export { DEFAULT_STATUS_FOR_FOLDER, DEPRECATION_SENTINEL, EMITTED_VBRIEF_VERSION
 export { pythonJsonPretty } from "./json.js";
 export { cmdVbriefBuild, run, usage } from "./main.js";
 export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, SAMPLE_PROJECT_MD, SAMPLE_ROADMAP_MD, SAMPLE_SPEC_MD, SAMPLE_SPEC_VBRIEF, } from "./parity-scenarios.js";
-export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, projectDefinitionPath, } from "./project-definition-io.js";
+export { atomicWriteProjectDefinition, CONFIGURED_PROJECT_DEFINITION_LABEL, loadProjectDefinitionForMutation, type MutationLockDeps, ProjectDefinitionLockError, parseProjectDefinitionAt, projectDefinitionArtifactLabel, projectDefinitionMutationLock, projectDefinitionPath, } from "./project-definition-io.js";
+export { type ProjectDefinitionMutation, withProjectDefinitionMutation, } from "./project-definition-mutation.js";
 export { loadProjectInvariants, parseProjectInvariantsField } from "./project-invariants-io.js";
 export { buildScopeVbriefFromReconciled, defaultStatusForFolder, folderForStatus, migrationTimestamp, planStatusMatchesFolder, } from "./routing.js";
 export { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";

package/dist/vbrief-build/index.js

@@ -3,7 +3,8 @@ export { DEFAULT_STATUS_FOR_FOLDER, DEPRECATION_SENTINEL, EMITTED_VBRIEF_VERSION
 export { pythonJsonPretty } from "./json.js";
 export { cmdVbriefBuild, run, usage } from "./main.js";
 export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, SAMPLE_PROJECT_MD, SAMPLE_ROADMAP_MD, SAMPLE_SPEC_MD, SAMPLE_SPEC_VBRIEF, } from "./parity-scenarios.js";
-export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, projectDefinitionPath, } from "./project-definition-io.js";
+export { atomicWriteProjectDefinition, CONFIGURED_PROJECT_DEFINITION_LABEL, loadProjectDefinitionForMutation, ProjectDefinitionLockError, parseProjectDefinitionAt, projectDefinitionArtifactLabel, projectDefinitionMutationLock, projectDefinitionPath, } from "./project-definition-io.js";
+export { withProjectDefinitionMutation, } from "./project-definition-mutation.js";
 export { loadProjectInvariants, parseProjectInvariantsField } from "./project-invariants-io.js";
 export { buildScopeVbriefFromReconciled, defaultStatusForFolder, folderForStatus, migrationTimestamp, planStatusMatchesFolder, } from "./routing.js";
 export { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";

package/dist/vbrief-build/parity-scenarios.js

@@ -2,7 +2,7 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { createScopeVbrief, referenceWithDefaultTrust, slugify } from "./build.js";
 import { pythonJsonPretty } from "./json.js";
-import { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, } from "./project-definition-io.js";
+import { withProjectDefinitionMutation } from "./project-definition-mutation.js";
 import { buildScopeVbriefFromReconciled, folderForStatus, planStatusMatchesFolder, } from "./routing.js";
 import { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";
 import { createSpeckitScopeVbrief, dependenciesForItem, edgeNodes, migrateSpeckitPlan, speckitIpIndex, speckitIpSlug, } from "./speckit.js";
@@ -209,11 +209,11 @@ export function runParityScenario(name, ctx) {
             const pdPath = join(vbriefDir, "PROJECT-DEFINITION.xbrief.json");
             writeFileSync(pdPath, pythonJsonPretty(seed), "utf8");
             let roundtrip = {};
-            projectDefinitionMutationLock(ctx.fixtureRoot, () => {
-                const [data, path] = loadProjectDefinitionForMutation(ctx.fixtureRoot);
+            withProjectDefinitionMutation(ctx.fixtureRoot, (mutation) => {
+                const data = mutation.load();
                 data.plan.policy = { wipCap: 12 };
-                atomicWriteProjectDefinition(path, data);
-                roundtrip = JSON.parse(readFileSync(path, "utf8"));
+                mutation.persist(data);
+                roundtrip = JSON.parse(readFileSync(mutation.artifactPath, "utf8"));
             });
             return { scenario: name, ok: true, payload: roundtrip };
         }

package/dist/vbrief-build/project-definition-io.d.ts

@@ -1,4 +1,15 @@
 import type { JsonObject } from "./types.js";
+/** Setup override for a noncanonical PROJECT-DEFINITION path. */
+export declare const ENV_PROJECT_PATH = "DEFT_PROJECT_PATH";
+/**
+ * Constant display label for a PROJECT-DEFINITION reached through the
+ * `DEFT_PROJECT_PATH` override (#3796). A configured path is operator- or
+ * environment-supplied data, so lock and loader diagnostics name this label
+ * instead of interpolating the raw path. Matches the label already used by
+ * `verify:vbrief-conformance` so one artifact reads the same way on every
+ * diagnostic surface.
+ */
+export declare const CONFIGURED_PROJECT_DEFINITION_LABEL = "<configured PROJECT-DEFINITION>";
 /**
  * Absolute path to the PROJECT-DEFINITION artifact. Layout-aware (#2302):
  * resolves `xbrief/PROJECT-DEFINITION.xbrief.json` on a migrated tree, else the
@@ -6,14 +17,63 @@ import type { JsonObject } from "./types.js";
  * name the path that actually applies to the project's layout.
  */
 export declare function projectDefinitionPath(projectRoot: string): string;
+/**
+ * Control-safe label for an artifact path in a human diagnostic (#3796).
+ * A configured artifact collapses to {@link CONFIGURED_PROJECT_DEFINITION_LABEL};
+ * a layout-resolved canonical artifact keeps its path because the layout
+ * resolver derived it rather than reading it from configuration.
+ */
+export declare function projectDefinitionArtifactLabel(artifactPath: string): string;
+/** Result of probing whether a recorded lock owner PID is still running. */
+export type ProcessLiveness = "dead" | "alive" | "unknown";
+/**
+ * Why an acquisition attempt could not take the lock. Only `contended` is
+ * ordinary traffic; the rest fail closed to manual recovery (#3796).
+ */
+export type LockBlockedReason = "contended" | "owner-alive" | "owner-liveness-unknown" | "malformed-lock-directory" | "legacy-file-sidecar";
 export interface MutationLockDeps {
     readonly sleepMs?: (ms: number) => void;
-    readonly now?: () => number;
+    /**
+     * Monotonic millisecond clock. One budget is derived from a single reading of
+     * this clock and shared by every retry and recovery branch (#3796), so a
+     * wall-clock step or a recovery detour cannot extend the acquisition window.
+     */
+    readonly monotonicNowMs?: () => number;
+    /** Total acquisition budget in milliseconds. */
+    readonly acquisitionBudgetMs?: number;
+    /**
+     * Three-state liveness oracle. Only `dead` authorises an automatic reap;
+     * `alive` (including possible PID reuse) and `unknown` fail closed.
+     */
+    readonly probeProcess?: (pid: number) => ProcessLiveness;
+    readonly writeOwner?: (fd: number, payload: string) => number;
+    readonly renameLock?: (source: string, destination: string) => void;
+    /** Test seam: fires after the stale owner entry is unlinked, before `rmdir`. */
+    readonly beforeLockDirRemove?: (lockPath: string) => void;
 }
-/** Serialise PROJECT-DEFINITION read-modify-write critical sections. */
-export declare function projectDefinitionMutationLock<T>(projectRoot: string, fn: () => T, deps?: MutationLockDeps): T;
+/** Acquisition failed within the shared budget. `reason` names the blocker. */
+export declare class ProjectDefinitionLockError extends Error {
+    readonly reason: LockBlockedReason;
+    constructor(message: string, reason: LockBlockedReason);
+}
+/**
+ * Serialise PROJECT-DEFINITION read-modify-write critical sections.
+ *
+ * Acquisition publishes a fully-materialised, non-empty owner directory by
+ * renaming it onto the public lock pathname, so no contender can observe a
+ * partial lock. Prefer {@link withProjectDefinitionMutation} in
+ * `project-definition-mutation.ts`: it binds load/parse/persist to the captured
+ * artifact path so a caller cannot lock one identity and write another (#3796).
+ */
+export declare function projectDefinitionMutationLock<T>(projectRoot: string, fn: (artifactPath: string) => T, deps?: MutationLockDeps): T;
 /** Read PROJECT-DEFINITION.vbrief.json and return ``(data, path)``. */
 export declare function loadProjectDefinitionForMutation(projectRoot: string): [JsonObject, string];
+/**
+ * Load and parse the PROJECT-DEFINITION at an already-captured path (#3796).
+ * Diagnostics name the artifact through {@link projectDefinitionArtifactLabel}
+ * so a configured path is never interpolated raw.
+ */
+export declare function parseProjectDefinitionAt(path: string): JsonObject;
 /** Atomically write ``data`` to ``path`` as pretty-printed JSON. */
 export declare function atomicWriteProjectDefinition(path: string, data: JsonObject): void;
 //# sourceMappingURL=project-definition-io.d.ts.map