@deftai/directive-core 0.66.1 → 0.67.0

package/dist/doctor/paths.js

@@ -32,6 +32,61 @@ export function resolveVersion(frameworkRoot) {
     }
     return "dev";
 }
+/**
+ * Resolve the framework root for a CLI command running against `projectRoot`.
+ *
+ * Priority: explicit `--deft-root` / `--framework-root` → `DEFT_ROOT` env →
+ * maintainer source checkout at `projectRoot` (when `main.md` + framework markers
+ * are present, even if a dogfood `.deft/core` deposit also exists) → consumer
+ * deposit (`.deft/core`, legacy `deft/`) → maintainer checkout walk
+ * (`resolveDefaultFrameworkRoot`).
+ *
+ * Refs #2146 (npm global `deft` must not default to `node_modules/vbrief/schemas`).
+ */
+function isFrameworkSourceCheckoutAt(projectRoot) {
+    try {
+        if (!statSync(join(projectRoot, "main.md")).isFile()) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    return DEFT_REPO_POSITIVE_MARKERS.every((marker) => {
+        try {
+            return statSync(join(projectRoot, marker)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function resolveFrameworkRootForProject(projectRoot, explicitRoot) {
+    const explicit = explicitRoot?.trim();
+    if (explicit) {
+        return resolve(explicit);
+    }
+    const envRoot = process.env.DEFT_ROOT?.trim();
+    if (envRoot) {
+        return resolve(envRoot);
+    }
+    const root = resolve(projectRoot);
+    if (isFrameworkSourceCheckoutAt(root)) {
+        return root;
+    }
+    for (const rel of [join(".deft", "core"), "deft"]) {
+        const candidate = join(root, rel);
+        try {
+            if (statSync(candidate).isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return resolveDefaultFrameworkRoot();
+}
 /** Return the deft framework repo root (the directory containing `main.md`). */
 export function resolveDefaultFrameworkRoot() {
     const envRoot = process.env.DEFT_ROOT?.trim();

package/dist/doctor/types.d.ts

@@ -1,3 +1,4 @@
+import type { AdvisoryEvaluateResult } from "../agents-md-advisory/evaluate.js";
 export declare const EXIT_CLEAN = 0;
 export declare const EXIT_DRIFT = 1;
 export declare const EXIT_CONFIG_ERROR = 2;
@@ -30,6 +31,7 @@ export interface DoctorFlags {
     readonly json: boolean;
     readonly quiet: boolean;
     readonly full: boolean;
+    readonly network: boolean;
     readonly help: boolean;
     readonly projectRoot: string | null;
     readonly unknown: readonly string[];
@@ -60,7 +62,12 @@ export interface DoctorSeams {
         ok: boolean;
         stdout: string;
     };
+    readonly runNpmViewVersion?: () => {
+        ok: boolean;
+        version: string;
+    };
     readonly agentsRefreshPlan?: (projectRoot: string) => Record<string, unknown>;
+    readonly agentsMdAdvisoryEvaluate?: (projectRoot: string) => AdvisoryEvaluateResult;
     readonly readState?: (projectRoot: string) => DoctorState | null;
     readonly writeState?: (projectRoot: string, payload: {
         exitCode: number;

package/dist/intake/github-auth-modes.d.ts

@@ -48,6 +48,7 @@ export interface GitHubAuthModesCliArgs {
     githubAuthMode?: string | null;
     repo?: string;
     json?: boolean;
+    runGh?: GhRunner;
 }
 export declare function githubAuthModesMain(args: GitHubAuthModesCliArgs): number;
 export { probeRuntimeCapabilities };

package/dist/intake/github-auth-modes.js

@@ -257,6 +257,7 @@ export function resultToDict(result) {
 export function githubAuthModesMain(args) {
     const result = validateGithubAuthForWorker(args.githubAuthMode ?? null, {
         repo: args.repo ?? DEFAULT_VALIDATION_REPO,
+        runGh: args.runGh,
     });
     if (args.json) {
         process.stdout.write(`${JSON.stringify(resultToDict(result), null, 2)}\n`);

package/dist/intake/issue-ingest.d.ts

@@ -1,3 +1,4 @@
+import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
 import { type ScmCallFn } from "./reconcile-issues.js";
 export declare const INGEST_STATUSES: readonly ["proposed", "pending", "active"];
 export type IngestStatus = (typeof INGEST_STATUSES)[number];
@@ -22,8 +23,11 @@ export declare function scanProvenanceRefs(vbriefDir: string): Map<number, strin
 export declare function composeOverviewWithComments(body: string, comments: readonly IssueComment[]): string;
 export declare function issueCommentThread(issue: Record<string, unknown>): IssueComment[];
 export declare function issueCommentsAlreadyFetched(issue: Record<string, unknown>): boolean;
-export declare function buildIssueVbrief(issue: Record<string, unknown>, status: IngestStatus, repoUrl: string): [Record<string, unknown>, string];
-export declare function targetFilename(number: number, title: string): string;
+export declare function buildIssueVbrief(issue: Record<string, unknown>, status: IngestStatus, repoUrl: string, options?: {
+    infoRootKey?: typeof LEGACY_INFO_ROOT_KEY | typeof MIGRATED_INFO_ROOT_KEY;
+    infoVersion?: string;
+}): [Record<string, unknown>, string];
+export declare function targetFilename(number: number, title: string, artifactSuffix?: typeof LEGACY_ARTIFACT_SUFFIX | typeof MIGRATED_ARTIFACT_SUFFIX): string;
 export interface FetchIssueOptions {
     readonly cwd?: string | null;
     readonly cacheRoot?: string | null;

package/dist/intake/issue-ingest.js

@@ -1,5 +1,5 @@
 import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { cacheGet } from "../cache/operations.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
@@ -7,6 +7,7 @@ import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
 import { slugify, TODAY } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
+import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LEGACY_VBRIEF_VERSION, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, VBRIEF_VERSION, } from "../xbrief-migrate/constants.js";
 import { findAcHeading, parseCheckboxItems, parseListItems, sliceAcSection, stripCodeBlocks, stripFencedCodeBlocks, } from "./markdown-scanners.js";
 import { detectRepo, extractReferencesFromVbrief, fetchOpenIssues, GITHUB_ISSUE_REF_TYPES, LIFECYCLE_FOLDERS, parseIssueNumber, } from "./reconcile-issues.js";
 export const INGEST_STATUSES = ["proposed", "pending", "active"];
@@ -17,6 +18,53 @@ const STATUS_MAP = {
     pending: ["pending", "pending"],
     active: ["active", "running"],
 };
+function readDeclaredInfoVersion(vbriefDir, infoRootKey, artifactSuffix, fallbackVersion) {
+    const projectDefinitionPath = join(vbriefDir, `PROJECT-DEFINITION${artifactSuffix}`);
+    try {
+        const parsed = JSON.parse(readFileSync(projectDefinitionPath, "utf8"));
+        const info = parsed[infoRootKey];
+        if (info !== null && typeof info === "object" && !Array.isArray(info)) {
+            const declared = info.version;
+            if (typeof declared === "string" && declared.length > 0) {
+                return declared;
+            }
+        }
+    }
+    catch {
+        // Fall back to the schema-default version when no declaration is available.
+    }
+    return fallbackVersion;
+}
+/**
+ * Decide the emission format (`.xbrief.json` + `xBRIEFInfo` vs legacy `.vbrief.json`
+ * + `vBRIEFInfo`) for an ingested scope artifact.
+ *
+ * The decision is STRUCTURAL and keyed on the resolved lifecycle root directory
+ * (`vbriefDir`), which is itself produced by `resolveLifecycleLayout` / `resolveLifecycleRoot`
+ * -- the exact same layout-decision logic `project:render` uses. This guarantees the two
+ * surfaces cannot diverge (#2149 finding #1): whichever tree `resolveLifecycleLayout` selected
+ * (`xbrief/` when migrated, else `vbrief/`) is the tree ingest writes into, and the emission
+ * format always matches that directory.
+ *
+ * It deliberately does NOT content-scan the tree for legacy markers (`detectLegacyVbriefLayout`).
+ * A historical vBRIEF-serialized artifact sitting in `xbrief/completed/` is migrated content,
+ * not a legacy layout, and must NOT force legacy emission on a migrated project (#2149 finding #3).
+ */
+function resolveIngestEmissionLayout(vbriefDir) {
+    const migrated = basename(vbriefDir) === MIGRATED_ARTIFACT_DIR;
+    if (!migrated) {
+        return {
+            artifactSuffix: LEGACY_ARTIFACT_SUFFIX,
+            infoRootKey: LEGACY_INFO_ROOT_KEY,
+            infoVersion: LEGACY_VBRIEF_VERSION,
+        };
+    }
+    return {
+        artifactSuffix: MIGRATED_ARTIFACT_SUFFIX,
+        infoRootKey: MIGRATED_INFO_ROOT_KEY,
+        infoVersion: readDeclaredInfoVersion(vbriefDir, MIGRATED_INFO_ROOT_KEY, MIGRATED_ARTIFACT_SUFFIX, VBRIEF_VERSION),
+    };
+}
 const CONTROL_CHAR_LABELS = {
     "\b": "U+0008 backspace",
     "\t": "U+0009 tab",
@@ -230,7 +278,7 @@ export function issueCommentThread(issue) {
 export function issueCommentsAlreadyFetched(issue) {
     return Object.hasOwn(issue, ISSUE_COMMENT_THREAD_KEY);
 }
-export function buildIssueVbrief(issue, status, repoUrl) {
+export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
     const number = Number(issue.number);
     const title = (typeof issue.title === "string" && issue.title.length > 0
         ? issue.title
@@ -291,20 +339,23 @@ export function buildIssueVbrief(issue, status, repoUrl) {
         }
         plan.references = references;
     }
+    const infoRootKey = options.infoRootKey ?? LEGACY_INFO_ROOT_KEY;
+    const infoVersion = options.infoVersion ?? EMITTED_VBRIEF_VERSION;
+    const briefLabel = infoRootKey === MIGRATED_INFO_ROOT_KEY ? "xBRIEF" : "vBRIEF";
     return [
         {
-            vBRIEFInfo: {
-                version: EMITTED_VBRIEF_VERSION,
-                description: `Scope vBRIEF ingested from GitHub issue #${number}`,
+            [infoRootKey]: {
+                version: infoVersion,
+                description: `Scope ${briefLabel} ingested from GitHub issue #${number}`,
             },
             plan,
         },
         folder,
     ];
 }
-export function targetFilename(number, title) {
+export function targetFilename(number, title, artifactSuffix = LEGACY_ARTIFACT_SUFFIX) {
     const slug = slugify(title) || `issue-${number}`;
-    return `${TODAY}-${number}-${slug}.vbrief.json`;
+    return `${TODAY}-${number}-${slug}${artifactSuffix}`;
 }
 export function fetchFromCache(repo, number, options = {}) {
     const key = `${repo}/${number}`;
@@ -423,8 +474,12 @@ export function ingestOne(issue, options) {
         cwd: options.cwd,
         cacheRoot: options.cacheRoot,
     });
-    const [vbrief, folder] = buildIssueVbrief(enriched, options.status, options.repoUrl);
-    const filename = targetFilename(number, String(issue.title ?? ""));
+    const emissionLayout = resolveIngestEmissionLayout(options.vbriefDir);
+    const [vbrief, folder] = buildIssueVbrief(enriched, options.status, options.repoUrl, {
+        infoRootKey: emissionLayout.infoRootKey,
+        infoVersion: emissionLayout.infoVersion,
+    });
+    const filename = targetFilename(number, String(issue.title ?? ""), emissionLayout.artifactSuffix);
     const target = join(options.vbriefDir, folder, filename);
     if (options.dryRun) {
         return ["dryrun", target, `DRY-RUN would write ${folder}/${filename}`];
@@ -568,6 +623,7 @@ export function ingestSingleForAccept(n, repo, options = {}) {
         vbriefDir,
         status: options.status ?? "proposed",
         repoUrl,
+        cwd: root,
     });
     return [result, path];
 }

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.js

@@ -4,6 +4,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { contentRoot } from "../content-root.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 +229,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");

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/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