@deftai/directive-core 0.66.2 → 0.68.0

package/dist/layout/lifecycle-ref.js

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { hasArtifactSuffix } from "./resolve.js";
+/** Lifecycle folders searched when a folder-qualified ref dangles (#1926). */
+export const LIFECYCLE_SCOPE_FOLDERS = [
+    "proposed",
+    "pending",
+    "active",
+    "completed",
+    "cancelled",
+];
+function isLifecycleFolder(name) {
+    return LIFECYCLE_SCOPE_FOLDERS.includes(name);
+}
+function searchLifecycleFolders(lifecycleRoot, artifactBasename) {
+    for (const folder of LIFECYCLE_SCOPE_FOLDERS) {
+        const candidate = resolve(lifecycleRoot, folder, artifactBasename);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a lifecycle-relative artifact reference to an absolute path.
+ *
+ * When the direct path is missing but the ref names a lifecycle artifact
+ * (folder-qualified or bare basename), search all lifecycle folders for the
+ * same filename (#1926).
+ */
+export function resolveLifecycleArtifactRef(rel, lifecycleRoot, options = {}) {
+    const allowCrossFolderSearch = options.allowCrossFolderSearch ?? true;
+    const direct = resolve(lifecycleRoot, rel);
+    if (existsSync(direct)) {
+        return direct;
+    }
+    if (!allowCrossFolderSearch) {
+        return direct;
+    }
+    const parts = rel.split("/").filter(Boolean);
+    if (parts.length >= 2 && isLifecycleFolder(parts[0] ?? "")) {
+        const found = searchLifecycleFolders(lifecycleRoot, basename(rel));
+        if (found !== null) {
+            return found;
+        }
+    }
+    if (!rel.includes("/") && hasArtifactSuffix(rel)) {
+        const found = searchLifecycleFolders(lifecycleRoot, rel);
+        if (found !== null) {
+            return found;
+        }
+    }
+    return direct;
+}
+//# sourceMappingURL=lifecycle-ref.js.map

package/dist/platform/agents-consumer-header.d.ts

@@ -0,0 +1,13 @@
+/** Rot-prone unmanaged-header sections retired by Option A (#2065). */
+export declare const RETIRED_UNMANAGED_HEADER_SECTIONS: readonly ["## Status", "## Known Issues"];
+export interface ConsumerHeaderSeams {
+    readonly frameworkRoot?: string;
+    readonly readTemplate?: () => string | null;
+}
+/** Bounded unmanaged header scaffold for fresh consumer installs (#2065 Option A). */
+export declare function renderConsumerHeader(seams?: ConsumerHeaderSeams): string;
+/** Compose a greenfield AGENTS.md: bounded unmanaged header + attributed managed section. */
+export declare function composeGreenfieldAgentsMd(attributedManagedSection: string, seams?: ConsumerHeaderSeams): string;
+/** True when text contains rot-prone retired header patterns (#2065). */
+export declare function containsRetiredUnmanagedHeaderPatterns(text: string): boolean;
+//# sourceMappingURL=agents-consumer-header.d.ts.map

package/dist/platform/agents-consumer-header.js

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { contentRoot } from "../content-root.js";
+import { frameworkRoot } from "./agents-md.js";
+/** Rot-prone unmanaged-header sections retired by Option A (#2065). */
+export const RETIRED_UNMANAGED_HEADER_SECTIONS = ["## Status", "## Known Issues"];
+// "Next:" is a bare label, not a markdown heading like the two patterns above --
+// anchor it to the start of a line so prose that happens to contain "Next:"
+// mid-sentence (e.g. "See UPGRADING.md ... Next: run `deft triage:queue`") does
+// not false-positive (#2170 review).
+const RETIRED_NEXT_LABEL_PATTERN = /(^|\n)\s*Next:/;
+const CONSUMER_HEADER_TEMPLATE = "templates/agents-consumer-header.md";
+function readConsumerHeaderTemplate(seams = {}) {
+    if (seams.readTemplate)
+        return seams.readTemplate();
+    const root = frameworkRoot(seams);
+    const candidate = join(contentRoot(root), CONSUMER_HEADER_TEMPLATE);
+    try {
+        if (!existsSync(candidate))
+            return null;
+        return readFileSync(candidate, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Bounded unmanaged header scaffold for fresh consumer installs (#2065 Option A). */
+export function renderConsumerHeader(seams = {}) {
+    const template = readConsumerHeaderTemplate(seams);
+    if (template === null) {
+        return [
+            "# Project",
+            "",
+            "One-line project description (edit me).",
+            "",
+            "## Session orientation",
+            "",
+            "Scoped work → `xbrief/` lifecycle; ranked queue → `deft triage:queue`; tracked bugs → GitHub issues; identity → `xbrief/PROJECT-DEFINITION.xbrief.json`.",
+        ].join("\n");
+    }
+    return template.replace(/\r\n/g, "\n").replace(/\n$/, "");
+}
+/** Compose a greenfield AGENTS.md: bounded unmanaged header + attributed managed section. */
+export function composeGreenfieldAgentsMd(attributedManagedSection, seams = {}) {
+    const header = renderConsumerHeader(seams);
+    const managed = attributedManagedSection.replace(/\r\n/g, "\n").replace(/\n$/, "");
+    return `${header}\n\n${managed}\n`;
+}
+/** True when text contains rot-prone retired header patterns (#2065). */
+export function containsRetiredUnmanagedHeaderPatterns(text) {
+    const normalized = text.replace(/\r\n/g, "\n");
+    if (RETIRED_UNMANAGED_HEADER_SECTIONS.some((pattern) => normalized.includes(pattern))) {
+        return true;
+    }
+    return RETIRED_NEXT_LABEL_PATTERN.test(normalized);
+}
+//# sourceMappingURL=agents-consumer-header.js.map

package/dist/platform/agents-md.d.ts

@@ -1,3 +1,4 @@
+import { type LockDeps } from "../slice/lock.js";
 export interface ManagedSectionAttrs {
     readonly version: number;
     readonly sha: string | null;
@@ -27,5 +28,32 @@ export declare function attributeRenderManagedSection(rendered: string, attrs: {
 }): string;
 /** Compute AGENTS.md managed-section freshness plan (mirrors scripts/_agents_md.py). */
 export declare function agentsRefreshPlan(projectRoot: string, seams?: AgentsMdSeams): Record<string, unknown>;
+export interface ApplyAgentsRefreshOptions {
+    /** Compute state only, never write — mirrors `agents:refresh --check`. */
+    readonly check?: boolean;
+    /** Compute the plan but skip the write — mirrors `agents:refresh --dry-run`. */
+    readonly dryRun?: boolean;
+}
+export interface AgentsRefreshApplyResult {
+    readonly state: string;
+    readonly path: string;
+    /** True only when the managed section was written to disk on this call. */
+    readonly wrote: boolean;
+    /** True when the plan produced writable `new_content` for a writable state. */
+    readonly writable: boolean;
+}
+/**
+ * Serialize the AGENTS.md managed-section read->compute->write behind an advisory
+ * file lock and write atomically (temp file + rename), so concurrent
+ * install/upgrade/migrate/refresh writers cannot clobber one another's `session=`
+ * write or leave a partially-written file (#1329).
+ *
+ * Reuses the existing cross-process append lock (`withAppendLock`, keyed here on
+ * the AGENTS.md path -> `AGENTS.md.lock`) and atomic writer (`atomicWriteText`)
+ * rather than introducing a competing lock utility. The parallel
+ * `projectDefinitionMutationLock` remains owned by #1260; a general lock helper is
+ * deliberately not added here to avoid two competing mutation-lock utilities.
+ */
+export declare function applyAgentsRefresh(projectRoot: string, options?: ApplyAgentsRefreshOptions, seams?: AgentsMdSeams, lockDeps?: LockDeps): AgentsRefreshApplyResult;
 export declare function hasV3ManagedMarker(projectRoot: string, readText?: (path: string) => string | null): boolean;
 //# sourceMappingURL=agents-md.d.ts.map

package/dist/platform/agents-md.js

@@ -3,7 +3,10 @@ import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { atomicWriteText } from "../cache/io.js";
 import { contentRoot } from "../content-root.js";
+import { withAppendLock } from "../slice/lock.js";
+import { composeGreenfieldAgentsMd } from "./agents-consumer-header.js";
 import { AGENTS_MANAGED_CLOSE, AGENTS_MANAGED_OPEN_V3_LITERAL } from "./constants.js";
 import { findManagedOpenMarker } from "./linear-scan.js";
 /** Return the framework root (directory owning `templates/`). */
@@ -228,7 +231,9 @@ export function agentsRefreshPlan(projectRoot, seams = {}) {
             refreshed,
             session: sessionId,
             existing: null,
-            new_content: `${attributedRendered}\n`,
+            new_content: composeGreenfieldAgentsMd(attributedRendered, {
+                frameworkRoot: frameworkRoot(seams),
+            }),
         };
     }
     const normalised = existing.replace(/\r\n/g, "\n");
@@ -291,6 +296,38 @@ export function agentsRefreshPlan(projectRoot, seams = {}) {
         new_content: newContent,
     };
 }
+/** Managed-section states whose plan yields a new AGENTS.md body to write. */
+const AGENTS_REFRESH_WRITABLE_STATES = new Set(["absent", "missing", "stale"]);
+/**
+ * Serialize the AGENTS.md managed-section read->compute->write behind an advisory
+ * file lock and write atomically (temp file + rename), so concurrent
+ * install/upgrade/migrate/refresh writers cannot clobber one another's `session=`
+ * write or leave a partially-written file (#1329).
+ *
+ * Reuses the existing cross-process append lock (`withAppendLock`, keyed here on
+ * the AGENTS.md path -> `AGENTS.md.lock`) and atomic writer (`atomicWriteText`)
+ * rather than introducing a competing lock utility. The parallel
+ * `projectDefinitionMutationLock` remains owned by #1260; a general lock helper is
+ * deliberately not added here to avoid two competing mutation-lock utilities.
+ */
+export function applyAgentsRefresh(projectRoot, options = {}, seams = {}, lockDeps = {}) {
+    const agentsMd = join(projectRoot, "AGENTS.md");
+    return withAppendLock(agentsMd, () => {
+        const plan = agentsRefreshPlan(projectRoot, seams);
+        const state = String(plan.state ?? "unknown");
+        const path = String(plan.path ?? agentsMd);
+        const newContent = plan.new_content;
+        if (options.check === true ||
+            options.dryRun === true ||
+            !AGENTS_REFRESH_WRITABLE_STATES.has(state) ||
+            typeof newContent !== "string") {
+            const writable = AGENTS_REFRESH_WRITABLE_STATES.has(state) && typeof newContent === "string";
+            return { state, path, wrote: false, writable };
+        }
+        atomicWriteText(path, newContent);
+        return { state, path, wrote: true, writable: true };
+    }, lockDeps);
+}
 export function hasV3ManagedMarker(projectRoot, readText = defaultReadAgents) {
     const agentsMd = join(projectRoot, "AGENTS.md");
     const text = readText(agentsMd);

package/dist/platform/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./agents-consumer-header.js";
 export * from "./agents-md.js";
 export * from "./constants.js";
 export * from "./ip-risk.js";

package/dist/platform/index.js

@@ -1,3 +1,4 @@
+export * from "./agents-consumer-header.js";
 export * from "./agents-md.js";
 export * from "./constants.js";
 export * from "./ip-risk.js";

package/dist/policy/agents-md-advisory.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Advisory (consumer-side) AGENTS.md legibility budget (#2155).
+ *
+ * This is the consumer companion to the maintainer-only #645 ratchet
+ * (`plan.policy.agentsMdBudget`, fail-closed via `check:framework-source`). A
+ * consumer's AGENTS.md has a framework-owned managed section (rendered from the
+ * template; the consumer cannot act on its size) and an UNMANAGED region
+ * (project header + project-specific rules) that is theirs. Because we cannot
+ * know what a given project legitimately needs in that region, the framework
+ * has no business failing THEIR build over it. So this budget is:
+ *
+ * - unmanaged-focused (the managed section is excluded from the count),
+ * - a SOFT, operator-adjustable knob, generous by DEFAULT when unset, and
+ * - never fail-closing in the default advisory posture (advise -> observe ->
+ *   enforce per #1419).
+ *
+ * Raising `unmanagedSoftMaxLines` is the no-friction, documented way a consumer
+ * accepts legitimate growth and silences the advisory nudge.
+ */
+export interface AgentsMdAdvisoryConfig {
+    readonly unmanagedSoftMaxLines: number;
+}
+export type AgentsMdAdvisorySource = "typed" | "default" | "default-on-error";
+export interface AgentsMdAdvisoryResult {
+    readonly config: AgentsMdAdvisoryConfig;
+    readonly source: AgentsMdAdvisorySource;
+    /** Populated only when a malformed field forced a fallback to the default. */
+    readonly error: string | null;
+}
+/**
+ * Generous default soft budget for the consumer-authored (unmanaged) region.
+ *
+ * Deliberately generous: the empirical "map, not a manual" guidance
+ * (`content/docs/good-agents-md.md`) is about the whole file's front-door cost,
+ * but a compliance-heavy repo or a monorepo with real per-package rules may
+ * legitimately need a larger project section. This default only nudges once the
+ * unmanaged region gets genuinely large; the consumer raises the field to
+ * accept their own trade-off.
+ */
+export declare const DEFAULT_UNMANAGED_SOFT_MAX_LINES = 300;
+/** Canonical dotted-path name of the typed advisory soft-budget field. */
+export declare const FIELD_AGENTS_MD_ADVISORY_UNMANAGED_SOFT_MAX_LINES = "plan.policy.agentsMdAdvisory.unmanagedSoftMaxLines";
+/**
+ * Resolve the advisory soft budget from PROJECT-DEFINITION (#2155).
+ *
+ * NEVER throws and NEVER surfaces a hard config error: because the advisory is
+ * non-blocking by contract, any malformed input degrades gracefully to the
+ * generous default (`source: "default-on-error"`, `error` populated for
+ * optional display) rather than failing the caller.
+ */
+export declare function resolveAgentsMdAdvisory(projectRoot: string): AgentsMdAdvisoryResult;
+//# sourceMappingURL=agents-md-advisory.d.ts.map

package/dist/policy/agents-md-advisory.js

@@ -0,0 +1,63 @@
+import { readPlanPolicy } from "./plan-extensions.js";
+import { loadProjectDefinition } from "./resolve.js";
+/**
+ * Generous default soft budget for the consumer-authored (unmanaged) region.
+ *
+ * Deliberately generous: the empirical "map, not a manual" guidance
+ * (`content/docs/good-agents-md.md`) is about the whole file's front-door cost,
+ * but a compliance-heavy repo or a monorepo with real per-package rules may
+ * legitimately need a larger project section. This default only nudges once the
+ * unmanaged region gets genuinely large; the consumer raises the field to
+ * accept their own trade-off.
+ */
+export const DEFAULT_UNMANAGED_SOFT_MAX_LINES = 300;
+/** Canonical dotted-path name of the typed advisory soft-budget field. */
+export const FIELD_AGENTS_MD_ADVISORY_UNMANAGED_SOFT_MAX_LINES = "plan.policy.agentsMdAdvisory.unmanagedSoftMaxLines";
+function defaultConfig() {
+    return { unmanagedSoftMaxLines: DEFAULT_UNMANAGED_SOFT_MAX_LINES };
+}
+/**
+ * Resolve the advisory soft budget from PROJECT-DEFINITION (#2155).
+ *
+ * NEVER throws and NEVER surfaces a hard config error: because the advisory is
+ * non-blocking by contract, any malformed input degrades gracefully to the
+ * generous default (`source: "default-on-error"`, `error` populated for
+ * optional display) rather than failing the caller.
+ */
+export function resolveAgentsMdAdvisory(projectRoot) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return { config: defaultConfig(), source: "default-on-error", error: err };
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("agentsMdAdvisory" in policyBlock)) {
+        return { config: defaultConfig(), source: "default", error: null };
+    }
+    const rawAdvisory = policyBlock.agentsMdAdvisory;
+    if (typeof rawAdvisory !== "object" || rawAdvisory === null || Array.isArray(rawAdvisory)) {
+        return {
+            config: defaultConfig(),
+            source: "default-on-error",
+            error: "plan.policy.agentsMdAdvisory must be an object with unmanagedSoftMaxLines",
+        };
+    }
+    const block = rawAdvisory;
+    if (!("unmanagedSoftMaxLines" in block)) {
+        // Object present but the field unset: treat as unset -> generous default.
+        return { config: defaultConfig(), source: "default", error: null };
+    }
+    const raw = block.unmanagedSoftMaxLines;
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+        return {
+            config: defaultConfig(),
+            source: "default-on-error",
+            error: `${FIELD_AGENTS_MD_ADVISORY_UNMANAGED_SOFT_MAX_LINES} must be a non-negative integer; ` +
+                "falling back to the generous default",
+        };
+    }
+    return { config: { unmanagedSoftMaxLines: raw }, source: "typed", error: null };
+}
+//# sourceMappingURL=agents-md-advisory.js.map

package/dist/policy/agents-md-budget.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-region line-budget ratchet for AGENTS.md (#645).
+ *
+ * The budget is seeded at the CURRENT per-region line counts and forbids
+ * INCREASE, rather than encoding a static absolute ceiling. This decouples the
+ * gate from the reduction work (#1882): the file is by definition within its
+ * own seeded baseline, so the gate ships green, while any growth past the
+ * ratchet fails. Lowering a budget (a reduction PR) is always allowed; raising
+ * it is an explicit, reviewed diff to this typed field -- that diff IS the
+ * "was this growth deliberate?" checkpoint.
+ */
+export interface AgentsMdBudget {
+    readonly managedMaxLines: number;
+    readonly unmanagedMaxLines: number;
+}
+export type AgentsMdBudgetSource = "typed" | "unset" | "default-on-error";
+export interface AgentsMdBudgetResult {
+    readonly budget: AgentsMdBudget | null;
+    readonly source: AgentsMdBudgetSource;
+    readonly error: string | null;
+}
+/** Resolve plan.policy.agentsMdBudget from PROJECT-DEFINITION (#645). */
+export declare function resolveAgentsMdBudget(projectRoot: string): AgentsMdBudgetResult;
+//# sourceMappingURL=agents-md-budget.d.ts.map

package/dist/policy/agents-md-budget.js

@@ -0,0 +1,89 @@
+import { readPlanPolicy } from "./plan-extensions.js";
+import { loadProjectDefinition } from "./resolve.js";
+function pythonTypeName(value) {
+    if (value === null)
+        return "None";
+    if (Array.isArray(value))
+        return "list";
+    if (typeof value === "boolean")
+        return "bool";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "int" : "float";
+    if (typeof value === "string")
+        return "str";
+    if (typeof value === "object")
+        return "dict";
+    return typeof value;
+}
+function pythonRepr(value) {
+    if (value === undefined)
+        return "None";
+    if (typeof value === "string")
+        return `'${value}'`;
+    if (value === null)
+        return "None";
+    if (typeof value === "boolean")
+        return value ? "True" : "False";
+    return String(value);
+}
+function readRegion(block, key) {
+    if (!(key in block)) {
+        return { value: null, error: `plan.policy.agentsMdBudget.${key} is required` };
+    }
+    const raw = block[key];
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+        return {
+            value: null,
+            error: `plan.policy.agentsMdBudget.${key} must be a non-negative integer; got ${pythonTypeName(raw)} (${pythonRepr(raw)})`,
+        };
+    }
+    return { value: raw, error: null };
+}
+/** Resolve plan.policy.agentsMdBudget from PROJECT-DEFINITION (#645). */
+export function resolveAgentsMdBudget(projectRoot) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return { budget: null, source: "default-on-error", error: err };
+    }
+    const plan = data.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return {
+            budget: null,
+            source: "default-on-error",
+            error: "PROJECT-DEFINITION 'plan' is not an object",
+        };
+    }
+    const policyBlock = readPlanPolicy(plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("agentsMdBudget" in policyBlock)) {
+        return { budget: null, source: "unset", error: null };
+    }
+    const rawBudget = policyBlock.agentsMdBudget;
+    if (typeof rawBudget !== "object" || rawBudget === null || Array.isArray(rawBudget)) {
+        return {
+            budget: null,
+            source: "default-on-error",
+            error: `plan.policy.agentsMdBudget must be an object with managedMaxLines and unmanagedMaxLines; got ${pythonTypeName(rawBudget)}`,
+        };
+    }
+    const block = rawBudget;
+    const managed = readRegion(block, "managedMaxLines");
+    if (managed.error !== null) {
+        return { budget: null, source: "default-on-error", error: managed.error };
+    }
+    const unmanaged = readRegion(block, "unmanagedMaxLines");
+    if (unmanaged.error !== null) {
+        return { budget: null, source: "default-on-error", error: unmanaged.error };
+    }
+    return {
+        budget: {
+            managedMaxLines: managed.value,
+            unmanagedMaxLines: unmanaged.value,
+        },
+        source: "typed",
+        error: null,
+    };
+}
+//# sourceMappingURL=agents-md-budget.js.map

package/dist/policy/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./agents-md-advisory.js";
 export * from "./autonomy.js";
 export * from "./capacity.js";
 export * from "./decisions.js";

package/dist/policy/index.js

@@ -1,6 +1,7 @@
 import { readPlanPolicy } from "./plan-extensions.js";
 import { coerceLegacyNarrative, LEGACY_NARRATIVE_KEY, loadProjectDefinition } from "./resolve.js";
 import { DEFAULT_WIP_CAP } from "./wip.js";
+export * from "./agents-md-advisory.js";
 export * from "./autonomy.js";
 export * from "./capacity.js";
 export * from "./decisions.js";

package/dist/policy/resolve.js

@@ -1,6 +1,7 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve as pathResolve } from "node:path";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
 /** Filesystem-relative location of the project-definition vBRIEF (display/back-compat). */
 export const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
@@ -184,55 +185,64 @@ export function setPolicy(projectRoot, options) {
     if (!existsSync(path)) {
         throw new Error(`PROJECT-DEFINITION not found at ${path}`);
     }
-    const data = JSON.parse(readFileSync(path, { encoding: "utf8" }));
-    if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
-        if (data.plan === undefined) {
-            data.plan = {};
+    // Serialise the read-modify-write + audit-log append behind the shared
+    // PROJECT-DEFINITION mutation lock so a concurrent policy/ritual mutator
+    // cannot lose this update or desync the typed flag from the audit row (#1260).
+    return projectDefinitionMutationLock(projectRoot, () => {
+        const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
         }
-        else {
-            throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+        const data = parsed;
+        if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
+            if (data.plan === undefined) {
+                data.plan = {};
+            }
+            else {
+                throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+            }
         }
-    }
-    const plan = data.plan;
-    migrateLegacyPolicyKey(plan);
-    const existingPolicy = plan[PLAN_POLICY_KEY];
-    if (typeof existingPolicy !== "object" ||
-        existingPolicy === null ||
-        Array.isArray(existingPolicy)) {
-        if (existingPolicy === undefined) {
-            plan[PLAN_POLICY_KEY] = {};
+        const plan = data.plan;
+        migrateLegacyPolicyKey(plan);
+        const existingPolicy = plan[PLAN_POLICY_KEY];
+        if (typeof existingPolicy !== "object" ||
+            existingPolicy === null ||
+            Array.isArray(existingPolicy)) {
+            if (existingPolicy === undefined) {
+                plan[PLAN_POLICY_KEY] = {};
+            }
+            else {
+                throw new Error("plan.policy is not an object");
+            }
         }
-        else {
-            throw new Error("plan.policy is not an object");
+        const policyBlock = plan[PLAN_POLICY_KEY];
+        const previous = policyBlock.allowDirectCommitsToMaster;
+        policyBlock.allowDirectCommitsToMaster = Boolean(allowDirectCommits);
+        let legacyDropped = false;
+        const narratives = plan.narratives;
+        if (typeof narratives === "object" &&
+            narratives !== null &&
+            !Array.isArray(narratives) &&
+            LEGACY_NARRATIVE_KEY in narratives) {
+            delete narratives[LEGACY_NARRATIVE_KEY];
+            legacyDropped = true;
         }
-    }
-    const policyBlock = plan[PLAN_POLICY_KEY];
-    const previous = policyBlock.allowDirectCommitsToMaster;
-    policyBlock.allowDirectCommitsToMaster = Boolean(allowDirectCommits);
-    let legacyDropped = false;
-    const narratives = plan.narratives;
-    if (typeof narratives === "object" &&
-        narratives !== null &&
-        !Array.isArray(narratives) &&
-        LEGACY_NARRATIVE_KEY in narratives) {
-        delete narratives[LEGACY_NARRATIVE_KEY];
-        legacyDropped = true;
-    }
-    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { encoding: "utf8" });
-    const changed = previous !== Boolean(allowDirectCommits) || legacyDropped;
-    const parts = [
-        `actor=${actor}`,
-        `allowDirectCommitsToMaster=${allowDirectCommits ? "true" : "false"}`,
-        `previous=${pythonRepr(previous)}`,
-    ];
-    if (legacyDropped) {
-        parts.push("legacy-narrative-migrated=true");
-    }
-    if (note) {
-        parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
-    }
-    const auditEntry = parts.join(" ");
-    appendAuditLog(projectRoot, auditEntry);
-    return { changed, auditEntry };
+        atomicWriteProjectDefinition(path, data);
+        const changed = previous !== Boolean(allowDirectCommits) || legacyDropped;
+        const parts = [
+            `actor=${actor}`,
+            `allowDirectCommitsToMaster=${allowDirectCommits ? "true" : "false"}`,
+            `previous=${pythonRepr(previous)}`,
+        ];
+        if (legacyDropped) {
+            parts.push("legacy-narrative-migrated=true");
+        }
+        if (note) {
+            parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
+        }
+        const auditEntry = parts.join(" ");
+        appendAuditLog(projectRoot, auditEntry);
+        return { changed, auditEntry };
+    });
 }
 //# sourceMappingURL=resolve.js.map

package/dist/pr-merge-readiness/ci-gate.d.ts

@@ -0,0 +1,28 @@
+import type { CheckRunRecord } from "./gh.js";
+export type CiReadyState = "ready" | "blocked" | "not_ready_yet" | "skipped";
+export interface CiGateOptions {
+    readonly skipCi?: boolean;
+    readonly ignoreCheckNames?: readonly string[];
+}
+export interface CiCheckConclusion {
+    readonly name: string;
+    readonly status: string;
+    readonly conclusion: string;
+    readonly required: boolean;
+    readonly ignored: boolean;
+}
+export interface CiGateSummary {
+    readonly ready_state: CiReadyState;
+    readonly checked_count: number;
+    readonly ignored_checks: readonly string[];
+    readonly failed_required: readonly string[];
+    readonly pending_required: readonly string[];
+    readonly conclusions: readonly CiCheckConclusion[];
+}
+export interface CiGateResult {
+    readonly failures: readonly string[];
+    readonly summary: CiGateSummary;
+}
+export declare function buildCiSummaryLine(summary: CiGateSummary): string;
+export declare function evaluateCiGate(checkRuns: readonly CheckRunRecord[], options?: CiGateOptions): CiGateResult;
+//# sourceMappingURL=ci-gate.d.ts.map