@loopover/engine 1.0.0

package/dist/ai-policy-map.js

@@ -0,0 +1,377 @@
+const AI_POLICY_ALLOWED = {
+    allowed: true,
+    matchedPhrase: null,
+    source: "none",
+};
+const AI_FATIGUE_NONE = {
+    level: "none",
+    priorityAdjustment: "none",
+    score: 0,
+    recheckAfterHours: 168,
+    evidence: [],
+};
+const BAN_PHRASES = [
+    {
+        phrase: "no ai-generated pull requests",
+        pattern: /\bno\s+ai[-\s]+generated\s+(?:pull\s+requests|prs|contributions)\b/i,
+    },
+    {
+        phrase: "ai-generated prs are rejected",
+        pattern: /\bai[-\s]+generated\s+(?:prs?|pull\s+requests|contributions?)\s+(?:are|will\s+be)\s+(?:banned|rejected|not\s+accepted)\b/i,
+    },
+    {
+        phrase: "do not submit ai-generated code",
+        pattern: /\bdo\s+not\s+(?:use|submit)\s+ai[-\s]+(?:written|generated)\s+code\b/i,
+    },
+    {
+        phrase: "llm-generated code is not accepted",
+        pattern: /\b(?:ai|llm)[-\s]+generated\s+code\s+(?:is|will\s+be)\s+(?:rejected|not\s+accepted)\b/i,
+    },
+];
+const AI_ATTRIBUTION_PATTERNS = [
+    /\bai[-\s]?(?:generated|assisted|authored)\b/iu,
+    /\b(?:llm|chatgpt|copilot|codex|claude)[-\s]+(?:generated|assisted|authored)\b/iu,
+    /\b(?:automation|bot)[-\s]?(?:generated|submitted|authored)\b/iu,
+];
+const AI_DOC_LANGUAGE_PATTERNS = [
+    /\bai\b/iu,
+    /\bllm\b/iu,
+    /\bautomation\b/iu,
+    /\bautomated\s+(?:prs?|pull\s+requests|contributions?)\b/iu,
+    /\bgenerated\s+(?:code|prs?|pull\s+requests|contributions?)\b/iu,
+];
+const TERSE_REJECTION_RESPONSES = new Set(["terse_rejection", "template_rejection"]);
+const FATIGUE_CACHE_TTL_HOURS = 24;
+function parseInstant(value) {
+    if (value === null || value === undefined)
+        return null;
+    const ms = value instanceof Date ? value.getTime() : Date.parse(value);
+    if (!Number.isFinite(ms))
+        return null;
+    return new Date(ms).toISOString();
+}
+function requireNow(value) {
+    const parsed = parseInstant(value);
+    return parsed ? new Date(parsed) : new Date();
+}
+function hoursBetween(left, right) {
+    return Math.max(0, (right.getTime() - new Date(left).getTime()) / 3_600_000);
+}
+function recencyWeight(observedAt, now, halfLifeDays) {
+    if (!observedAt)
+        return 0.35;
+    const ageDays = hoursBetween(observedAt, now) / 24;
+    return Math.exp(-ageDays / halfLifeDays);
+}
+function roundScore(value) {
+    return Math.round(Math.min(1, Math.max(0, value)) * 1_000_000) / 1_000_000;
+}
+function roundHours(value) {
+    return Math.round(Math.max(0, value) * 1_000_000) / 1_000_000;
+}
+function collapseInline(value) {
+    return value.replace(/[\r\n\t]+/gu, " ").replace(/\s{2,}/gu, " ").trim();
+}
+function metadataText(pr) {
+    return [pr.title, ...(pr.labels ?? []), pr.authorLogin].filter((value) => Boolean(value)).join(" ");
+}
+function isAiAttributed(pr) {
+    const text = metadataText(pr);
+    return AI_ATTRIBUTION_PATTERNS.some((pattern) => pattern.test(text));
+}
+function isClosedWithoutMerge(pr) {
+    const state = pr.state.trim().toLowerCase();
+    if (state === "merged")
+        return false;
+    if (parseInstant(pr.mergedAt))
+        return false;
+    return state === "closed" || state === "rejected" || state === "declined";
+}
+function isTerseRejection(pr) {
+    const response = pr.maintainerResponse?.trim().toLowerCase();
+    const reviewDecision = pr.reviewDecision?.trim().toLowerCase();
+    const closeReason = pr.closeReason?.trim().toLowerCase();
+    return ((response ? TERSE_REJECTION_RESPONSES.has(response) : false) ||
+        reviewDecision === "changes_requested" ||
+        closeReason === "spam" ||
+        closeReason === "not_planned");
+}
+function docText(change) {
+    return [change.addedText, ...(change.addedPhrases ?? [])].filter((value) => Boolean(value)).join(" ");
+}
+function aiPolicyDocSource(path) {
+    const normalized = collapseInline(path);
+    if (normalized === "AI-USAGE.md")
+        return "AI-USAGE.md";
+    if (normalized === "CONTRIBUTING.md")
+        return "CONTRIBUTING.md";
+    return null;
+}
+function isAiDocLanguage(change) {
+    const source = aiPolicyDocSource(change.path);
+    if (!source)
+        return false;
+    const text = docText(change);
+    if (!text.trim())
+        return false;
+    if (!scanAiPolicyText(text, source).allowed) {
+        return false;
+    }
+    return AI_DOC_LANGUAGE_PATTERNS.some((pattern) => pattern.test(text));
+}
+function evidence(kind, weight, summary, observedAt) {
+    return {
+        kind,
+        weight: roundScore(weight),
+        summary: collapseInline(summary),
+        observedAt,
+    };
+}
+function fatigueLevel(score, hasCluster) {
+    if (score >= 0.72 || (hasCluster && score >= 0.58))
+        return "defer";
+    if (score >= 0.4)
+        return "deprioritize";
+    if (score >= 0.18)
+        return "watch";
+    return "none";
+}
+function priorityAdjustment(level) {
+    if (level === "defer")
+        return "defer";
+    if (level === "deprioritize" || level === "watch")
+        return "deprioritize";
+    return "none";
+}
+function recheckAfterHours(level) {
+    if (level === "defer")
+        return 12;
+    if (level === "deprioritize")
+        return 24;
+    if (level === "watch")
+        return 48;
+    return 168;
+}
+function fatigueMultiplier(level) {
+    if (level === "defer")
+        return 0.05;
+    if (level === "deprioritize")
+        return 0.35;
+    if (level === "watch")
+        return 0.7;
+    return 1;
+}
+function finiteScore(value, fallback) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(1, Math.max(0, value));
+}
+function isCacheFresh(cache, now) {
+    const computedAt = parseInstant(cache?.computedAt);
+    if (!cache || !computedAt)
+        return false;
+    return hoursBetween(computedAt, now) <= FATIGUE_CACHE_TTL_HOURS;
+}
+function cacheMatchesRepo(cache, repoFullName) {
+    if (!cache)
+        return false;
+    try {
+        return normalizeRepoFullName(cache.repoFullName) === normalizeRepoFullName(repoFullName);
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeRepoFullName(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!/^[a-z0-9_.-]+\/[a-z0-9_.-]+$/u.test(normalized)) {
+        throw new Error("AI policy fatigue cache entries require a repo full name in owner/name form.");
+    }
+    return normalized;
+}
+function addHours(instant, hours) {
+    return new Date(new Date(instant).getTime() + hours * 3_600_000).toISOString();
+}
+function cacheVerdict(cache) {
+    const computedAt = parseInstant(cache.computedAt);
+    return {
+        ...cache.verdict,
+        evidence: [
+            evidence("cache_fresh", 0, `cached fatigue verdict reused from ${computedAt ?? "unknown time"}`, computedAt),
+            ...cache.verdict.evidence,
+        ],
+    };
+}
+function markdownSafe(value) {
+    return collapseInline(value).replace(/[\\`*_[\]<>|]/gu, "\\$&");
+}
+function renderEvidenceItem(item) {
+    const observed = item.observedAt ? ` (${item.observedAt})` : "";
+    return `- ${markdownSafe(item.kind)}: ${item.weight.toFixed(6)}${observed} - ${markdownSafe(item.summary)}`;
+}
+/**
+ * Conservative by design (#2305): explicit ban phrases deny a repo, but ambiguous or absent policy text stays
+ * allowed. False negatives can be tightened with new literal phrases; false positives would hide valid work.
+ */
+export function scanAiPolicyText(content, source) {
+    const text = content ?? "";
+    if (source === "none" || text.trim().length === 0) {
+        return { allowed: true, matchedPhrase: null, source };
+    }
+    for (const ban of BAN_PHRASES) {
+        if (ban.pattern.test(text)) {
+            return { allowed: false, matchedPhrase: ban.phrase, source };
+        }
+    }
+    return { allowed: true, matchedPhrase: null, source };
+}
+export function resolveAiPolicyVerdict(docs) {
+    // An empty or whitespace-only AI-USAGE.md carries no policy and must fall through to CONTRIBUTING.md,
+    // exactly as an absent (null/undefined) file does — otherwise a stub AI-USAGE.md silently fails open and
+    // swallows a real ban declared in CONTRIBUTING.md (#2305).
+    if (docs.aiUsage !== null && docs.aiUsage !== undefined && docs.aiUsage.trim().length > 0) {
+        return scanAiPolicyText(docs.aiUsage, "AI-USAGE.md");
+    }
+    if (docs.contributing !== null && docs.contributing !== undefined) {
+        return scanAiPolicyText(docs.contributing, "CONTRIBUTING.md");
+    }
+    return { ...AI_POLICY_ALLOWED };
+}
+export function resolveAiPolicyFatigueVerdict(input) {
+    const hardPolicy = resolveAiPolicyVerdict(input.docs);
+    const now = requireNow(input.now);
+    if (!hardPolicy.allowed) {
+        return {
+            ...hardPolicy,
+            fatigue: {
+                level: "none",
+                priorityAdjustment: "none",
+                score: 0,
+                recheckAfterHours: 168,
+                evidence: [
+                    evidence("formal_ban_overrides", 0, `formal AI policy ban from ${hardPolicy.source} remains authoritative`, null),
+                ],
+            },
+        };
+    }
+    if (isCacheFresh(input.cache, now) && cacheMatchesRepo(input.cache, input.repoFullName)) {
+        return {
+            ...hardPolicy,
+            fatigue: cacheVerdict(input.cache),
+        };
+    }
+    const evidenceItems = [];
+    const aiAttributedClosed = (input.pullRequests ?? []).filter((pr) => isAiAttributed(pr) && isClosedWithoutMerge(pr));
+    const terseRejected = aiAttributedClosed.filter(isTerseRejection);
+    if (aiAttributedClosed.length > 0) {
+        const newest = aiAttributedClosed
+            .map((pr) => parseInstant(pr.closedAt) ?? parseInstant(pr.createdAt))
+            .filter((value) => Boolean(value))
+            .sort()
+            .at(-1) ?? null;
+        evidenceItems.push(evidence("ai_attributed_closed_pr", Math.min(0.35, 0.18 + aiAttributedClosed.length / 20), `${aiAttributedClosed.length} closed AI-attributed PR metadata row(s) observed`, newest));
+    }
+    if (terseRejected.length >= 2) {
+        const newest = terseRejected
+            .map((pr) => parseInstant(pr.closedAt) ?? parseInstant(pr.createdAt))
+            .filter((value) => Boolean(value))
+            .sort()
+            .at(-1) ?? null;
+        const ratio = terseRejected.length / Math.max(1, aiAttributedClosed.length);
+        evidenceItems.push(evidence("terse_ai_attributed_rejection_cluster", Math.min(0.62, ratio * 0.45 + Math.min(0.17, terseRejected.length / 20)), `${terseRejected.length}/${aiAttributedClosed.length} AI-attributed closed PRs have terse or templated rejection metadata`, newest));
+    }
+    for (const change of input.docChanges ?? []) {
+        if (!isAiDocLanguage(change))
+            continue;
+        const observedAt = parseInstant(change.changedAt);
+        const weight = 0.28 * recencyWeight(observedAt, now, 30);
+        evidenceItems.push(evidence("recent_ai_doc_language", weight, `${change.path} added AI/automation language short of a formal ban phrase`, observedAt));
+    }
+    const totalScore = roundScore(evidenceItems.reduce((sum, item) => sum + item.weight, 0));
+    const hasCluster = evidenceItems.some((item) => item.kind === "terse_ai_attributed_rejection_cluster");
+    const level = fatigueLevel(totalScore, hasCluster);
+    const fatigue = {
+        level,
+        priorityAdjustment: priorityAdjustment(level),
+        score: totalScore,
+        recheckAfterHours: recheckAfterHours(level),
+        evidence: evidenceItems,
+    };
+    return {
+        ...hardPolicy,
+        fatigue: fatigue.evidence.length === 0 ? { ...AI_FATIGUE_NONE } : fatigue,
+    };
+}
+export function renderAiPolicyFatigueMarkdown(verdict) {
+    const fatigue = verdict.fatigue ?? AI_FATIGUE_NONE;
+    const lines = [
+        "# AI Policy Fatigue",
+        "",
+        `Hard policy allowed: ${verdict.allowed ? "yes" : "no"}`,
+        `Policy source: ${markdownSafe(verdict.source)}`,
+        `Fatigue level: ${fatigue.level}`,
+        `Priority adjustment: ${fatigue.priorityAdjustment}`,
+        `Fatigue score: ${fatigue.score.toFixed(6)}`,
+        `Recheck after: ${fatigue.recheckAfterHours}h`,
+        "",
+        "## Evidence",
+        "",
+        fatigue.evidence.length === 0 ? "- none" : fatigue.evidence.map(renderEvidenceItem).join("\n"),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+export function applyAiPolicyFatigueToRankInput(rankInput, verdict) {
+    const fatigue = verdict.fatigue ?? AI_FATIGUE_NONE;
+    const multiplier = verdict.allowed ? fatigueMultiplier(fatigue.level) : 0;
+    const reasons = [];
+    if (!verdict.allowed) {
+        reasons.push(`formal AI policy denial from ${verdict.source}`);
+    }
+    if (fatigue.priorityAdjustment !== "none") {
+        reasons.push(`AI-fatigue ${fatigue.priorityAdjustment} signal (${fatigue.level})`);
+    }
+    for (const item of fatigue.evidence.slice(0, 3)) {
+        reasons.push(item.summary);
+    }
+    return {
+        potential: roundScore(finiteScore(rankInput.potential, 0) * multiplier),
+        feasibility: finiteScore(rankInput.feasibility, 0),
+        laneFit: finiteScore(rankInput.laneFit, 0),
+        freshness: finiteScore(rankInput.freshness, 0),
+        dupRisk: verdict.allowed ? finiteScore(rankInput.dupRisk, 1) : 1,
+        fatigueLevel: fatigue.level,
+        priorityAdjustment: verdict.allowed ? fatigue.priorityAdjustment : "defer",
+        fatigueMultiplier: multiplier,
+        deferUntilHours: verdict.allowed && fatigue.priorityAdjustment === "defer" ? fatigue.recheckAfterHours : null,
+        reasons,
+    };
+}
+export function createAiPolicyFatigueCacheEntry(input) {
+    return {
+        repoFullName: normalizeRepoFullName(input.repoFullName),
+        computedAt: requireNow(input.computedAt).toISOString(),
+        verdict: input.verdict,
+    };
+}
+export function describeAiPolicyFatigueCache(cache, now) {
+    const computedAt = parseInstant(cache?.computedAt);
+    const current = requireNow(now);
+    if (!cache || !computedAt) {
+        return {
+            repoFullName: cache?.repoFullName ? collapseInline(cache.repoFullName).toLowerCase() : "unknown",
+            computedAt: null,
+            expiresAt: null,
+            ageHours: null,
+            fresh: false,
+        };
+    }
+    const ageHours = roundHours(hoursBetween(computedAt, current));
+    const expiresAt = addHours(computedAt, FATIGUE_CACHE_TTL_HOURS);
+    return {
+        repoFullName: normalizeRepoFullName(cache.repoFullName),
+        computedAt,
+        expiresAt,
+        ageHours,
+        fresh: ageHours <= FATIGUE_CACHE_TTL_HOURS,
+    };
+}

package/dist/ams-policy-spec.d.ts

@@ -0,0 +1,56 @@
+import { type PortfolioConvergenceThresholds } from "./portfolio/non-convergence.js";
+/** Whether a real attempt is allowed to actually submit (open a PR), or only compute + log its decision.
+ *  Mirrors `src/settings/autonomy.ts`'s deny-by-default dial: "observe" still runs every real signal/decision,
+ *  it just never lets `wouldBeAction` become a real write. */
+export type AmsSubmissionMode = "observe" | "enforce";
+/** The strictest self-review slop band still allowed to reach submission (`isSlopBandWithinThreshold`,
+ *  submission-gate.ts). Lower = stricter: "clean" only lets the cleanest band through. */
+export type AmsSlopThreshold = "clean" | "low" | "elevated" | "high";
+/** The three Governor cap ceilings (`GovernorCapLimits`, budget-cap.ts) for one attempt. */
+export type AmsCapLimits = {
+    /** Maximum cumulative budget/cost units (may be fractional, e.g. a dollar cost) permitted for one attempt. */
+    budget: number;
+    /** Maximum cumulative turns/iterations permitted for one attempt. */
+    turns: number;
+    /** Termination ceiling: maximum elapsed session time in milliseconds for one attempt. */
+    elapsedMs: number;
+};
+/** Per-operator AMS execution policy parsed from `.gittensory-ams.yml`. See {@link DEFAULT_AMS_POLICY_SPEC}. */
+export type AmsPolicySpec = {
+    /** Whether a real attempt may actually submit. Default: "observe" (deny-by-default). */
+    submissionMode: AmsSubmissionMode;
+    /** The strictest self-review slop band still allowed to reach submission. Default: "low" (conservative). */
+    slopThreshold: AmsSlopThreshold;
+    /** Governor cap ceilings for one attempt. Default: { budget: 5, turns: 20, elapsedMs: 1_800_000 } (30 min). */
+    capLimits: AmsCapLimits;
+    /** Non-convergence detector thresholds. Default: {@link DEFAULT_PORTFOLIO_CONVERGENCE_THRESHOLDS}. */
+    convergenceThresholds: PortfolioConvergenceThresholds;
+    /** Hard ceiling on the iterate loop's own iteration count (IterateLoopInput.maxIterations). Default: 3. */
+    maxIterations: number;
+    /** Per-iteration turn budget passed to the coding-agent driver (IterateLoopInput.maxTurnsPerIteration).
+     *  Default: 6. */
+    maxTurnsPerIteration: number;
+};
+/** The tolerant parser result for `.gittensory-ams.yml`. Mirrors `ParsedMinerGoalSpec`'s present/warnings shape. */
+export type ParsedAmsPolicySpec = {
+    present: boolean;
+    spec: AmsPolicySpec;
+    warnings: string[];
+};
+/**
+ * The safe defaults applied when a field is absent from `.gittensory-ams.yml` (or the file itself is
+ * missing). Deep-frozen: a shared singleton, clone before layering overrides on top.
+ */
+export declare const DEFAULT_AMS_POLICY_SPEC: Readonly<AmsPolicySpec>;
+/**
+ * Tolerantly normalize an already-parsed `.gittensory-ams.yml` object into a {@link ParsedAmsPolicySpec}.
+ * Never throws: malformed shapes degrade to safe defaults and accumulate warnings.
+ */
+export declare function parseAmsPolicySpec(raw: unknown): ParsedAmsPolicySpec;
+/**
+ * Parse raw `.gittensory-ams.yml` file content (JSON or YAML). Malformed content degrades to an absent
+ * policy spec with a warning rather than throwing, mirroring `parseMinerGoalSpecContent`.
+ */
+export declare function parseAmsPolicySpecContent(content: string | null | undefined): ParsedAmsPolicySpec;
+/** The documented `.gittensory-ams` file-discovery order (first match wins), mirroring `MINER_GOAL_SPEC_FILENAMES`. */
+export declare const AMS_POLICY_SPEC_FILENAMES: readonly [".gittensory-ams.yml", ".github/gittensory-ams.yml", ".gittensory-ams.json", ".github/gittensory-ams.json"];

package/dist/ams-policy-spec.js

@@ -0,0 +1,165 @@
+import { parse as parseYaml } from "yaml";
+import { DEFAULT_PORTFOLIO_CONVERGENCE_THRESHOLDS } from "./portfolio/non-convergence.js";
+/**
+ * The safe defaults applied when a field is absent from `.gittensory-ams.yml` (or the file itself is
+ * missing). Deep-frozen: a shared singleton, clone before layering overrides on top.
+ */
+export const DEFAULT_AMS_POLICY_SPEC = Object.freeze({
+    submissionMode: "observe",
+    slopThreshold: "low",
+    capLimits: Object.freeze({ budget: 5, turns: 20, elapsedMs: 1_800_000 }),
+    convergenceThresholds: Object.freeze({ ...DEFAULT_PORTFOLIO_CONVERGENCE_THRESHOLDS }),
+    maxIterations: 3,
+    maxTurnsPerIteration: 6,
+});
+const MAX_AMS_POLICY_SPEC_BYTES = 8_192;
+function cloneDefaultAmsPolicySpec() {
+    return {
+        submissionMode: DEFAULT_AMS_POLICY_SPEC.submissionMode,
+        slopThreshold: DEFAULT_AMS_POLICY_SPEC.slopThreshold,
+        capLimits: { ...DEFAULT_AMS_POLICY_SPEC.capLimits },
+        convergenceThresholds: { ...DEFAULT_AMS_POLICY_SPEC.convergenceThresholds },
+        maxIterations: DEFAULT_AMS_POLICY_SPEC.maxIterations,
+        maxTurnsPerIteration: DEFAULT_AMS_POLICY_SPEC.maxTurnsPerIteration,
+    };
+}
+function emptyAmsPolicySpec(warnings = []) {
+    return { present: false, spec: cloneDefaultAmsPolicySpec(), warnings };
+}
+function normalizeSubmissionMode(value, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (value === "observe" || value === "enforce")
+        return value;
+    warnings.push(`AmsPolicySpec field "submissionMode" must be one of observe, enforce; falling back to "${fallback}".`);
+    return fallback;
+}
+function normalizeSlopThreshold(value, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (value === "clean" || value === "low" || value === "elevated" || value === "high")
+        return value;
+    warnings.push(`AmsPolicySpec field "slopThreshold" must be one of clean, low, elevated, high; falling back to "${fallback}".`);
+    return fallback;
+}
+function normalizePositiveNumber(value, field, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        warnings.push(`AmsPolicySpec field "${field}" must be a non-negative number; falling back to ${fallback}.`);
+        return fallback;
+    }
+    return value;
+}
+/** Like normalizePositiveNumber, but floors to a whole count -- for fields that are semantically integer
+ *  counts (an iteration/turn budget), matching MinerGoalSpec's own normalizePositiveInteger convention. */
+function normalizeNonNegativeInteger(value, field, fallback, warnings) {
+    const normalized = normalizePositiveNumber(value, field, fallback, warnings);
+    return Math.floor(normalized);
+}
+function normalizeCapLimits(value, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push('AmsPolicySpec field "capLimits" must be a mapping; falling back to defaults.');
+        return fallback;
+    }
+    const record = value;
+    return {
+        budget: normalizePositiveNumber(record.budget, "capLimits.budget", fallback.budget, warnings),
+        turns: normalizePositiveNumber(record.turns, "capLimits.turns", fallback.turns, warnings),
+        elapsedMs: normalizePositiveNumber(record.elapsedMs, "capLimits.elapsedMs", fallback.elapsedMs, warnings),
+    };
+}
+function normalizeConvergenceThresholds(value, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push('AmsPolicySpec field "convergenceThresholds" must be a mapping; falling back to defaults.');
+        return fallback;
+    }
+    const record = value;
+    return {
+        maxConsecutiveFailures: normalizePositiveNumber(record.maxConsecutiveFailures, "convergenceThresholds.maxConsecutiveFailures", fallback.maxConsecutiveFailures, warnings),
+        maxReenqueues: normalizePositiveNumber(record.maxReenqueues, "convergenceThresholds.maxReenqueues", fallback.maxReenqueues, warnings),
+    };
+}
+function hasConfiguredPolicyFields(spec) {
+    return (spec.submissionMode !== DEFAULT_AMS_POLICY_SPEC.submissionMode ||
+        spec.slopThreshold !== DEFAULT_AMS_POLICY_SPEC.slopThreshold ||
+        spec.capLimits.budget !== DEFAULT_AMS_POLICY_SPEC.capLimits.budget ||
+        spec.capLimits.turns !== DEFAULT_AMS_POLICY_SPEC.capLimits.turns ||
+        spec.capLimits.elapsedMs !== DEFAULT_AMS_POLICY_SPEC.capLimits.elapsedMs ||
+        spec.convergenceThresholds.maxConsecutiveFailures !== DEFAULT_AMS_POLICY_SPEC.convergenceThresholds.maxConsecutiveFailures ||
+        spec.convergenceThresholds.maxReenqueues !== DEFAULT_AMS_POLICY_SPEC.convergenceThresholds.maxReenqueues ||
+        spec.maxIterations !== DEFAULT_AMS_POLICY_SPEC.maxIterations ||
+        spec.maxTurnsPerIteration !== DEFAULT_AMS_POLICY_SPEC.maxTurnsPerIteration);
+}
+function utf8ByteLength(value) {
+    let bytes = 0;
+    for (const char of value) {
+        const codePoint = char.codePointAt(0);
+        if (codePoint <= 0x7f)
+            bytes += 1;
+        else if (codePoint <= 0x7ff)
+            bytes += 2;
+        else if (codePoint <= 0xffff)
+            bytes += 3;
+        else
+            bytes += 4;
+    }
+    return bytes;
+}
+/**
+ * Tolerantly normalize an already-parsed `.gittensory-ams.yml` object into a {@link ParsedAmsPolicySpec}.
+ * Never throws: malformed shapes degrade to safe defaults and accumulate warnings.
+ */
+export function parseAmsPolicySpec(raw) {
+    if (raw === undefined || raw === null)
+        return emptyAmsPolicySpec();
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return emptyAmsPolicySpec(["AmsPolicySpec must be a mapping of fields; ignoring malformed config and falling back to safe defaults."]);
+    }
+    const record = raw;
+    const warnings = [];
+    const spec = {
+        submissionMode: normalizeSubmissionMode(record.submissionMode, DEFAULT_AMS_POLICY_SPEC.submissionMode, warnings),
+        slopThreshold: normalizeSlopThreshold(record.slopThreshold, DEFAULT_AMS_POLICY_SPEC.slopThreshold, warnings),
+        capLimits: normalizeCapLimits(record.capLimits, DEFAULT_AMS_POLICY_SPEC.capLimits, warnings),
+        convergenceThresholds: normalizeConvergenceThresholds(record.convergenceThresholds, DEFAULT_AMS_POLICY_SPEC.convergenceThresholds, warnings),
+        maxIterations: normalizeNonNegativeInteger(record.maxIterations, "maxIterations", DEFAULT_AMS_POLICY_SPEC.maxIterations, warnings),
+        maxTurnsPerIteration: normalizeNonNegativeInteger(record.maxTurnsPerIteration, "maxTurnsPerIteration", DEFAULT_AMS_POLICY_SPEC.maxTurnsPerIteration, warnings),
+    };
+    if (!hasConfiguredPolicyFields(spec)) {
+        warnings.push("AmsPolicySpec contained no recognized non-default policy fields; falling back to safe defaults.");
+        return { present: false, spec: cloneDefaultAmsPolicySpec(), warnings };
+    }
+    return { present: true, spec, warnings };
+}
+/**
+ * Parse raw `.gittensory-ams.yml` file content (JSON or YAML). Malformed content degrades to an absent
+ * policy spec with a warning rather than throwing, mirroring `parseMinerGoalSpecContent`.
+ */
+export function parseAmsPolicySpecContent(content) {
+    if (content === undefined || content === null || content.trim() === "")
+        return emptyAmsPolicySpec();
+    if (utf8ByteLength(content) > MAX_AMS_POLICY_SPEC_BYTES) {
+        return emptyAmsPolicySpec([`AmsPolicySpec content exceeded ${MAX_AMS_POLICY_SPEC_BYTES} bytes; ignoring it and falling back to safe defaults.`]);
+    }
+    const trimmed = content.trim();
+    const looksLikeJson = trimmed.startsWith("{") || trimmed.startsWith("[");
+    let parsed;
+    try {
+        parsed = looksLikeJson ? JSON.parse(trimmed) : parseYaml(trimmed);
+    }
+    catch {
+        return emptyAmsPolicySpec([
+            looksLikeJson
+                ? "AmsPolicySpec content was not valid JSON; ignoring it and falling back to safe defaults."
+                : "AmsPolicySpec content was not valid YAML; ignoring it and falling back to safe defaults.",
+        ]);
+    }
+    return parseAmsPolicySpec(parsed);
+}
+/** The documented `.gittensory-ams` file-discovery order (first match wins), mirroring `MINER_GOAL_SPEC_FILENAMES`. */
+export const AMS_POLICY_SPEC_FILENAMES = [".gittensory-ams.yml", ".github/gittensory-ams.yml", ".gittensory-ams.json", ".github/gittensory-ams.json"];

package/dist/calibration-dashboard.d.ts

@@ -0,0 +1,23 @@
+import { type Phase7CalibrationLoopResult } from "./phase7-calibration-loop.js";
+export type CalibrationDashboardStatus = "on_track" | "below_baseline" | "insufficient_signal" | "disabled";
+/** One labeled row in the dashboard: a metric name, its formatted value, and a short detail line. */
+export type CalibrationDashboardRow = {
+    label: string;
+    value: string;
+    detail: string;
+};
+/** The read-only dashboard projection of a calibration-loop result. */
+export type CalibrationDashboardView = {
+    status: CalibrationDashboardStatus;
+    headline: string;
+    rows: readonly CalibrationDashboardRow[];
+    holdReasons: readonly string[];
+};
+/** Classify the overall calibration state for the dashboard's headline banner. */
+export declare function resolveCalibrationDashboardStatus(result: Phase7CalibrationLoopResult): CalibrationDashboardStatus;
+/**
+ * Project a computed {@link Phase7CalibrationLoopResult} into a read-only dashboard view. Pure and deterministic;
+ * adds no computation of its own. `holdReasons` are surfaced verbatim so an operator can see why an autonomy
+ * increase is (or isn't) permitted.
+ */
+export declare function buildCalibrationDashboardView(result: Phase7CalibrationLoopResult): CalibrationDashboardView;