@deftai/directive-core 0.55.0

package/dist/platform/resolve-version.js

@@ -0,0 +1,303 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEV_FALLBACK, ENV_VAR } from "./constants.js";
+export { DEV_FALLBACK, ENV_VAR };
+export class NonPublishableVersionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NonPublishableVersionError";
+    }
+}
+const PRE_KIND_MAP = {
+    alpha: "a",
+    beta: "b",
+    rc: "rc",
+};
+const NON_PUBLISHABLE_KINDS = new Set(["test"]);
+const PRERELEASE_RANK = {
+    alpha: 0,
+    beta: 1,
+    rc: 2,
+    "": 3,
+};
+function frameworkRoot() {
+    const envRoot = process.env.DEFT_ROOT?.trim();
+    if (envRoot)
+        return resolve(envRoot);
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+}
+/** Parse `[v]X.Y.Z[-(rc|alpha|beta|test).N]` via linear scan. */
+function parsePep440Tag(version) {
+    let i = 0;
+    if (version[i] === "v" || version[i] === "V")
+        i += 1;
+    const readInt = () => {
+        const ch = version[i] ?? "";
+        if (i >= version.length || ch < "0" || ch > "9")
+            return null;
+        let n = 0;
+        while (i < version.length) {
+            const digit = version[i] ?? "";
+            if (digit < "0" || digit > "9")
+                break;
+            n = n * 10 + Number(digit);
+            i += 1;
+        }
+        return n;
+    };
+    const major = readInt();
+    if (major === null || version[i] !== ".")
+        return null;
+    i += 1;
+    const minor = readInt();
+    if (minor === null || version[i] !== ".")
+        return null;
+    i += 1;
+    const patch = readInt();
+    if (patch === null)
+        return null;
+    if (i >= version.length)
+        return { major, minor, patch, kind: null, num: null };
+    if (version[i] !== "-")
+        return null;
+    i += 1;
+    const kindStart = i;
+    while (i < version.length && version[i] !== ".")
+        i += 1;
+    if (i >= version.length || version[i] !== ".")
+        return null;
+    const kind = version.slice(kindStart, i);
+    if (!["rc", "alpha", "beta", "test"].includes(kind))
+        return null;
+    i += 1;
+    const num = readInt();
+    if (num === null || i !== version.length)
+        return null;
+    return { major, minor, patch, kind, num };
+}
+export function toPep440(version) {
+    if (typeof version !== "string") {
+        throw new Error(`version must be a string, got ${typeof version}`);
+    }
+    const candidate = version.trim();
+    if (!candidate)
+        throw new Error("version must be a non-empty string");
+    const parsed = parsePep440Tag(candidate);
+    if (parsed === null) {
+        throw new Error(`Cannot normalize ${JSON.stringify(candidate)} to PEP 440: expected [v]X.Y.Z or [v]X.Y.Z-(rc|alpha|beta|test).N`);
+    }
+    const base = `${parsed.major}.${parsed.minor}.${parsed.patch}`;
+    if (parsed.kind === null)
+        return base;
+    if (NON_PUBLISHABLE_KINDS.has(parsed.kind)) {
+        throw new NonPublishableVersionError(`Version ${JSON.stringify(candidate)} carries non-publishable pre-release tag ${JSON.stringify(parsed.kind)}.${parsed.num} -- release pipeline MUST skip pyproject.toml [project].version sync for this tag.`);
+    }
+    const pepKind = PRE_KIND_MAP[parsed.kind];
+    if (pepKind === undefined) {
+        throw new Error(`Unmapped pre-release kind ${JSON.stringify(parsed.kind)} for version ${JSON.stringify(candidate)}; add it to PRE_KIND_MAP or NON_PUBLISHABLE_KINDS to keep parser in lockstep with the publishability classifier.`);
+    }
+    return `${base}${pepKind}${parsed.num}`;
+}
+export function isPublishable(version) {
+    try {
+        toPep440(version);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function tagNameFromRef(ref) {
+    let candidate = ref.trim();
+    if (!candidate)
+        return "";
+    const parts = candidate.split(/\s+/);
+    if (parts.length >= 2)
+        candidate = parts[1] ?? candidate;
+    if (candidate.endsWith("^{}"))
+        candidate = candidate.slice(0, -3);
+    const prefix = "refs/tags/";
+    if (candidate.startsWith(prefix))
+        candidate = candidate.slice(prefix.length);
+    return candidate.trim();
+}
+function publishableTagSortKey(version) {
+    const candidate = version.trim();
+    const parsed = parsePep440Tag(candidate);
+    if (parsed === null) {
+        throw new Error(`Cannot sort ${JSON.stringify(candidate)}: expected [v]X.Y.Z or [v]X.Y.Z-(rc|alpha|beta).N`);
+    }
+    if (parsed.kind !== null && NON_PUBLISHABLE_KINDS.has(parsed.kind)) {
+        throw new NonPublishableVersionError(`Version ${JSON.stringify(candidate)} carries non-publishable pre-release tag ${JSON.stringify(parsed.kind)}.`);
+    }
+    const kind = parsed.kind ?? "";
+    const prereleaseRank = PRERELEASE_RANK[kind];
+    if (prereleaseRank === undefined) {
+        throw new Error(`Unmapped pre-release kind ${JSON.stringify(parsed.kind)} for ${JSON.stringify(candidate)}`);
+    }
+    return [parsed.major, parsed.minor, parsed.patch, prereleaseRank, parsed.num ?? 0];
+}
+export function latestPublishableTag(tags) {
+    let bestTag = null;
+    let bestKey = null;
+    for (const raw of tags) {
+        const tag = tagNameFromRef(raw);
+        if (!tag || !isPublishable(tag))
+            continue;
+        try {
+            const key = publishableTagSortKey(tag);
+            if (bestKey === null || compareTuple(key, bestKey) > 0) {
+                bestTag = tag;
+                bestKey = key;
+            }
+        }
+        catch { }
+    }
+    return bestTag;
+}
+function compareTuple(a, b) {
+    for (let i = 0; i < a.length; i += 1) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        if (av !== bv)
+            return av > bv ? 1 : -1;
+    }
+    return 0;
+}
+function readManifestTag(baseDir) {
+    const manifest = join(baseDir, "VERSION");
+    try {
+        if (!existsSync(manifest))
+            return null;
+        const text = readFileSync(manifest, "utf8");
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith("tag:") || trimmed.startsWith("ref:")) {
+                const colon = trimmed.indexOf(":");
+                let value = trimmed.slice(colon + 1).trim();
+                if ((value.startsWith("'") && value.endsWith("'")) ||
+                    (value.startsWith('"') && value.endsWith('"'))) {
+                    value = value.slice(1, -1);
+                }
+                if (value.startsWith("v"))
+                    value = value.slice(1);
+                const cleaned = value.trim();
+                if (cleaned)
+                    return cleaned;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function readDeftVersion(baseDir) {
+    const marker = join(baseDir, ".deft-version");
+    try {
+        if (!existsSync(marker))
+            return null;
+        let version = readFileSync(marker, "utf8").trim();
+        if (version.startsWith("v"))
+            version = version.slice(1);
+        return version || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function payloadIsOwnGitRoot(payloadDir) {
+    try {
+        const stdout = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: payloadDir,
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        const toplevel = stdout.trim();
+        if (!toplevel)
+            return false;
+        return resolve(toplevel) === resolve(payloadDir);
+    }
+    catch {
+        return false;
+    }
+}
+function fromEnv() {
+    const value = (process.env[ENV_VAR] ?? "").trim();
+    return value || null;
+}
+function fromGit(baseDir) {
+    if (!payloadIsOwnGitRoot(baseDir))
+        return null;
+    try {
+        const stdout = execFileSync("git", ["describe", "--tags", "--abbrev=0"], {
+            cwd: baseDir,
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        let tag = stdout.trim();
+        if (!tag)
+            return null;
+        if (tag.startsWith("v"))
+            tag = tag.slice(1);
+        return tag || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function latestLocalPublishableTag(repoRoot) {
+    const cwd = repoRoot ?? frameworkRoot();
+    try {
+        const stdout = execFileSync("git", ["tag", "--list"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        return latestPublishableTag(stdout.split("\n"));
+    }
+    catch {
+        return null;
+    }
+}
+export function latestRemotePublishableTag(remote = "origin", repoRoot) {
+    // Guard against second-order command injection: a remote beginning with "-"
+    // (e.g. "--upload-pack=<cmd>") would be parsed by git as an option and could
+    // execute an arbitrary command. Legitimate remote names/URLs never start with
+    // "-", so reject them outright; the "--" end-of-options separator below is the
+    // load-bearing barrier (git stops parsing options after it).
+    if (remote.startsWith("-"))
+        return null;
+    const cwd = repoRoot ?? frameworkRoot();
+    try {
+        const stdout = execFileSync("git", ["ls-remote", "--tags", "--refs", "--", remote], {
+            cwd,
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        return latestPublishableTag(stdout.split("\n"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve version using the documented priority chain. */
+export function resolveVersion(seams = {}) {
+    const base = seams.frameworkRoot ?? frameworkRoot();
+    const envValue = (seams.fromEnv ?? fromEnv)();
+    if (envValue)
+        return envValue;
+    const manifestValue = (seams.fromManifest ?? readManifestTag)(base);
+    if (manifestValue)
+        return manifestValue;
+    const deftVersionValue = (seams.fromDeftVersion ?? readDeftVersion)(base);
+    if (deftVersionValue)
+        return deftVersionValue;
+    const gitValue = (seams.fromGit ?? fromGit)(base);
+    if (gitValue)
+        return gitValue;
+    return DEV_FALLBACK;
+}
+//# sourceMappingURL=resolve-version.js.map

package/dist/platform/slug-normalize.d.ts

@@ -0,0 +1,9 @@
+import { DEFAULT_MAX_LEN, WINDOWS_RESERVED } from "./constants.js";
+export { DEFAULT_MAX_LEN, WINDOWS_RESERVED };
+/** Return a filesystem-safe slug (mirrors scripts/slug_normalize.py). */
+export declare function normalizeSlug(text: string | null | undefined, maxLen?: number): string;
+/** Return a collision-free slug relative to `existing`. */
+export declare function disambiguateSlug(slug: string, existing: ReadonlySet<string> | readonly string[], options?: {
+    maxLen?: number;
+}): string;
+//# sourceMappingURL=slug-normalize.d.ts.map

package/dist/platform/slug-normalize.js

@@ -0,0 +1,110 @@
+import { DEFAULT_MAX_LEN, WINDOWS_RESERVED } from "./constants.js";
+export { DEFAULT_MAX_LEN, WINDOWS_RESERVED };
+function stripCheckboxMarkers(text) {
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const atBoundary = i === 0 || text[i - 1] === " " || text[i - 1] === "\t";
+        if (atBoundary && text[i] === "[" && i + 2 < text.length && text[i + 2] === "]") {
+            const mid = text[i + 1];
+            if (mid === " " || mid === "x" || mid === "X") {
+                out += " ";
+                i += 3;
+                continue;
+            }
+        }
+        out += text[i] ?? "";
+        i += 1;
+    }
+    return out;
+}
+function collapseNonAlnum(text) {
+    let out = "";
+    let lastHyphen = false;
+    for (const ch of text) {
+        const lower = ch.toLowerCase();
+        const isAlnum = (lower >= "a" && lower <= "z") || (lower >= "0" && lower <= "9");
+        if (isAlnum) {
+            out += lower;
+            lastHyphen = false;
+        }
+        else if (!lastHyphen) {
+            out += "-";
+            lastHyphen = true;
+        }
+    }
+    return out;
+}
+function stripEdgeHyphens(text) {
+    let start = 0;
+    let end = text.length;
+    while (start < end && text[start] === "-")
+        start += 1;
+    while (end > start && text[end - 1] === "-")
+        end -= 1;
+    return text.slice(start, end);
+}
+function truncateAtWordBoundary(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    let truncated = text.slice(0, maxLen);
+    const nextChar = text[maxLen];
+    if (nextChar !== "-") {
+        const lastHyphen = truncated.lastIndexOf("-");
+        if (lastHyphen > Math.floor(maxLen / 2)) {
+            truncated = truncated.slice(0, lastHyphen);
+        }
+    }
+    return stripEdgeHyphens(truncated);
+}
+/** Return a filesystem-safe slug (mirrors scripts/slug_normalize.py). */
+export function normalizeSlug(text, maxLen = DEFAULT_MAX_LEN) {
+    if (!text)
+        return "untitled";
+    let limit = maxLen;
+    if (limit < 1)
+        limit = DEFAULT_MAX_LEN;
+    const decomposed = text.normalize("NFKD");
+    let asciiOnly = "";
+    for (const ch of decomposed) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (code >= 0x0300 && code <= 0x036f)
+            continue;
+        if (code <= 0x7f)
+            asciiOnly += ch;
+    }
+    const lowered = asciiOnly.toLowerCase();
+    const stripped = stripCheckboxMarkers(lowered);
+    const hyphenated = collapseNonAlnum(stripped);
+    let trimmed = stripEdgeHyphens(hyphenated);
+    if (trimmed.length > limit)
+        trimmed = truncateAtWordBoundary(trimmed, limit);
+    if (!trimmed)
+        return "untitled";
+    if (WINDOWS_RESERVED.has(trimmed))
+        return `${trimmed}-scope`;
+    return trimmed;
+}
+/** Return a collision-free slug relative to `existing`. */
+export function disambiguateSlug(slug, existing, options = {}) {
+    const maxLen = options.maxLen ?? DEFAULT_MAX_LEN;
+    const taken = existing instanceof Set ? existing : new Set(existing);
+    if (!taken.has(slug))
+        return slug;
+    const base = slug;
+    let n = 2;
+    while (n <= 10_000) {
+        const suffix = `-${n}`;
+        let candidate = base + suffix;
+        if (candidate.length > maxLen) {
+            const bodyBudget = Math.max(1, maxLen - suffix.length);
+            const trimmed = stripEdgeHyphens(base.slice(0, bodyBudget)) || base.slice(0, bodyBudget);
+            candidate = trimmed + suffix;
+        }
+        if (!taken.has(candidate))
+            return candidate;
+        n += 1;
+    }
+    throw new Error(`disambiguateSlug: unable to resolve collision for ${JSON.stringify(slug)} after ${n} attempts`);
+}
+//# sourceMappingURL=slug-normalize.js.map

package/dist/policy/autonomy.d.ts

@@ -0,0 +1,43 @@
+export declare const AUTONOMY_LEVELS: readonly ["observe", "escalate", "execute"];
+export declare const DEFAULT_AUTONOMY_LEVEL = "escalate";
+export declare const AUTONOMY_ACTION_ADVANCE = "advance";
+export declare const AUTONOMY_ACTION_HOLD = "hold";
+export declare const AUTONOMY_ACTION_RETREAT = "retreat";
+export declare const DEFAULT_AUTONOMY_ADVANCE_OVERRIDE_MAX = 0.05;
+export declare const DEFAULT_AUTONOMY_RETREAT_OVERRIDE_RATE = 0.2;
+export declare const DEFAULT_AUTONOMY_REWORK_BASELINE = 0.15;
+export declare const DEFAULT_AUTONOMY_MIN_SAMPLE_SIZE = 20;
+export interface AutonomyPolicy {
+    readonly enabled: boolean;
+    readonly default_level: string;
+    readonly min_sample_size: number;
+    readonly advance_override_max: number;
+    readonly retreat_override_rate: number;
+    readonly rework_baseline: number;
+    readonly gate_levels: Readonly<Record<string, string>>;
+    readonly source: "typed" | "default" | "default-on-error";
+    readonly error: string | null;
+    readonly configured: boolean;
+}
+export interface AutonomyRecommendation {
+    readonly current_level: string;
+    readonly recommended_level: string;
+    readonly action: string;
+    readonly rationale: string;
+    readonly gate_id: string | null;
+    readonly advisory: boolean;
+}
+/** Validate a plan.policy.autonomy payload. */
+export declare function validateAutonomy(value: unknown): string[];
+/** Resolve plan.policy.autonomy from PROJECT-DEFINITION. */
+export declare function resolveAutonomy(projectRoot: string): AutonomyPolicy;
+/** Recommend an autonomy-level flip from the dial signal (ADVISORY-ONLY). */
+export declare function recommendAutonomyLevel(currentLevel: string, options: {
+    override_rate: number;
+    rework_rate: number;
+    sample_size: number;
+    p0_reversal?: boolean;
+    policy?: AutonomyPolicy;
+    gate_id?: string | null;
+}): AutonomyRecommendation;
+//# sourceMappingURL=autonomy.d.ts.map

package/dist/policy/autonomy.js

@@ -0,0 +1,220 @@
+import { loadProjectDefinition } from "./resolve.js";
+export const AUTONOMY_LEVELS = ["observe", "escalate", "execute"];
+export const DEFAULT_AUTONOMY_LEVEL = "escalate";
+export const AUTONOMY_ACTION_ADVANCE = "advance";
+export const AUTONOMY_ACTION_HOLD = "hold";
+export const AUTONOMY_ACTION_RETREAT = "retreat";
+export const DEFAULT_AUTONOMY_ADVANCE_OVERRIDE_MAX = 0.05;
+export const DEFAULT_AUTONOMY_RETREAT_OVERRIDE_RATE = 0.2;
+export const DEFAULT_AUTONOMY_REWORK_BASELINE = 0.15;
+export const DEFAULT_AUTONOMY_MIN_SAMPLE_SIZE = 20;
+function isNumber(value) {
+    return typeof value === "number" && !Number.isNaN(value) && typeof value !== "boolean";
+}
+function defaultAutonomyPolicy(source, error = null) {
+    return {
+        enabled: true,
+        default_level: DEFAULT_AUTONOMY_LEVEL,
+        min_sample_size: DEFAULT_AUTONOMY_MIN_SAMPLE_SIZE,
+        advance_override_max: DEFAULT_AUTONOMY_ADVANCE_OVERRIDE_MAX,
+        retreat_override_rate: DEFAULT_AUTONOMY_RETREAT_OVERRIDE_RATE,
+        rework_baseline: DEFAULT_AUTONOMY_REWORK_BASELINE,
+        gate_levels: {},
+        source,
+        error,
+        configured: source === "typed",
+    };
+}
+function validateAutonomyGates(gates) {
+    if (typeof gates !== "object" || gates === null || Array.isArray(gates)) {
+        return ["plan.policy.autonomy.gates must be an object mapping gate-id -> level"];
+    }
+    const errors = [];
+    for (const [gid, level] of Object.entries(gates)) {
+        if (typeof gid !== "string" || gid.trim().length === 0) {
+            errors.push("plan.policy.autonomy.gates keys must be non-empty gate-id strings");
+        }
+        if (typeof level !== "string" ||
+            !AUTONOMY_LEVELS.includes(level)) {
+            errors.push(`plan.policy.autonomy.gates[${JSON.stringify(gid)}] must be one of ${JSON.stringify([...AUTONOMY_LEVELS].sort())}; got ${String(level)}`);
+        }
+    }
+    return errors;
+}
+/** Validate a plan.policy.autonomy payload. */
+export function validateAutonomy(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return [`plan.policy.autonomy must be an object; got ${typeof value}`];
+    }
+    const rec = value;
+    const errors = [];
+    if ("enabled" in rec && typeof rec.enabled !== "boolean") {
+        errors.push("plan.policy.autonomy.enabled must be a boolean");
+    }
+    if ("defaultLevel" in rec) {
+        const level = rec.defaultLevel;
+        if (typeof level !== "string" ||
+            !AUTONOMY_LEVELS.includes(level)) {
+            errors.push(`plan.policy.autonomy.defaultLevel must be one of ${JSON.stringify([...AUTONOMY_LEVELS].sort())}; got ${String(level)}`);
+        }
+    }
+    if ("minSampleSize" in rec) {
+        const mss = rec.minSampleSize;
+        if (typeof mss !== "number" || !Number.isInteger(mss) || mss < 0) {
+            errors.push(`plan.policy.autonomy.minSampleSize must be a non-negative integer; got ${String(mss)}`);
+        }
+    }
+    for (const key of ["advanceOverrideRateMax", "retreatOverrideRate", "reworkBaseline"]) {
+        if (key in rec) {
+            const rate = rec[key];
+            if (!isNumber(rate) || Number(rate) < 0 || Number(rate) > 1) {
+                errors.push(`plan.policy.autonomy.${key} must be a number between 0.0 and 1.0; got ${String(rate)}`);
+            }
+        }
+    }
+    if ("gates" in rec) {
+        errors.push(...validateAutonomyGates(rec.gates));
+    }
+    return errors;
+}
+function getPolicyBlock(data) {
+    const plan = data.plan;
+    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+        const policy = plan.policy;
+        if (typeof policy === "object" && policy !== null && !Array.isArray(policy)) {
+            return policy;
+        }
+    }
+    return {};
+}
+/** Resolve plan.policy.autonomy from PROJECT-DEFINITION. */
+export function resolveAutonomy(projectRoot) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return defaultAutonomyPolicy("default", err);
+    }
+    const policyBlock = getPolicyBlock(data);
+    if (!("autonomy" in policyBlock)) {
+        return defaultAutonomyPolicy("default");
+    }
+    const raw = policyBlock.autonomy;
+    const errors = validateAutonomy(raw);
+    if (errors.length > 0 || typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return defaultAutonomyPolicy("default-on-error", errors[0] ?? "autonomy must be an object");
+    }
+    const rec = raw;
+    const gateLevels = {};
+    const gates = rec.gates;
+    if (typeof gates === "object" && gates !== null && !Array.isArray(gates)) {
+        for (const [gid, level] of Object.entries(gates)) {
+            if (typeof gid === "string" && typeof level === "string") {
+                gateLevels[gid] = level;
+            }
+        }
+    }
+    return {
+        enabled: typeof rec.enabled === "boolean" ? rec.enabled : true,
+        default_level: typeof rec.defaultLevel === "string" ? rec.defaultLevel : DEFAULT_AUTONOMY_LEVEL,
+        min_sample_size: typeof rec.minSampleSize === "number" && Number.isInteger(rec.minSampleSize)
+            ? rec.minSampleSize
+            : DEFAULT_AUTONOMY_MIN_SAMPLE_SIZE,
+        advance_override_max: typeof rec.advanceOverrideRateMax === "number"
+            ? rec.advanceOverrideRateMax
+            : DEFAULT_AUTONOMY_ADVANCE_OVERRIDE_MAX,
+        retreat_override_rate: typeof rec.retreatOverrideRate === "number"
+            ? rec.retreatOverrideRate
+            : DEFAULT_AUTONOMY_RETREAT_OVERRIDE_RATE,
+        rework_baseline: typeof rec.reworkBaseline === "number"
+            ? rec.reworkBaseline
+            : DEFAULT_AUTONOMY_REWORK_BASELINE,
+        gate_levels: gateLevels,
+        source: "typed",
+        error: null,
+        configured: true,
+    };
+}
+function formatPct(value) {
+    return `${Math.round(value * 100)}%`;
+}
+/** Recommend an autonomy-level flip from the dial signal (ADVISORY-ONLY). */
+export function recommendAutonomyLevel(currentLevel, options) {
+    const pol = options.policy ?? defaultAutonomyPolicy("default");
+    const gateId = options.gate_id ?? null;
+    const cur = AUTONOMY_LEVELS.includes(currentLevel)
+        ? currentLevel
+        : pol.default_level;
+    const idx = AUTONOMY_LEVELS.indexOf(cur);
+    const overrideRate = options.override_rate;
+    const reworkRate = options.rework_rate;
+    const sampleSize = options.sample_size;
+    const p0Reversal = options.p0_reversal ?? false;
+    if (p0Reversal || overrideRate > pol.retreat_override_rate) {
+        const trigger = p0Reversal
+            ? "P0 reversal observed"
+            : `override rate ${formatPct(overrideRate)} > retreat threshold ${formatPct(pol.retreat_override_rate)}`;
+        if (idx === 0) {
+            return {
+                current_level: cur,
+                recommended_level: cur,
+                action: AUTONOMY_ACTION_HOLD,
+                rationale: `hold at ${cur}: ${trigger} but already at the most conservative ` +
+                    "level (Observe). ADVISORY: a human confirms.",
+                gate_id: gateId,
+                advisory: true,
+            };
+        }
+        const next = AUTONOMY_LEVELS[idx - 1] ?? cur;
+        return {
+            current_level: cur,
+            recommended_level: next,
+            action: AUTONOMY_ACTION_RETREAT,
+            rationale: `retreat: ${trigger} -- recommend ${next} ` +
+                "(restores required human clearances). ADVISORY: a human confirms.",
+            gate_id: gateId,
+            advisory: true,
+        };
+    }
+    const advanceOk = sampleSize >= pol.min_sample_size &&
+        overrideRate < pol.advance_override_max &&
+        reworkRate <= pol.rework_baseline;
+    if (advanceOk) {
+        const basis = `override ${formatPct(overrideRate)} < ${formatPct(pol.advance_override_max)}, ` +
+            `rework ${formatPct(reworkRate)} <= baseline ${formatPct(pol.rework_baseline)}, ` +
+            `sample ${sampleSize} >= ${pol.min_sample_size}`;
+        if (idx === AUTONOMY_LEVELS.length - 1) {
+            return {
+                current_level: cur,
+                recommended_level: cur,
+                action: AUTONOMY_ACTION_HOLD,
+                rationale: `hold at ${cur}: advance criteria met (${basis}) but already at ` +
+                    "the most permissive level (Execute).",
+                gate_id: gateId,
+                advisory: true,
+            };
+        }
+        const next = AUTONOMY_LEVELS[idx + 1] ?? cur;
+        return {
+            current_level: cur,
+            recommended_level: next,
+            action: AUTONOMY_ACTION_ADVANCE,
+            rationale: `advance: ${basis} -- recommend ${next} ` +
+                "(would reduce required human clearances). ADVISORY: a human " +
+                "confirms; no auto-ratchet.",
+            gate_id: gateId,
+            advisory: true,
+        };
+    }
+    return {
+        current_level: cur,
+        recommended_level: cur,
+        action: AUTONOMY_ACTION_HOLD,
+        rationale: `hold at ${cur}: override ${formatPct(overrideRate)}, rework ${formatPct(reworkRate)}, ` +
+            `sample ${sampleSize} -- advance criteria not met, no retreat trigger.`,
+        gate_id: gateId,
+        advisory: true,
+    };
+}
+//# sourceMappingURL=autonomy.js.map