@loopover/engine 1.0.0

package/dist/finding-severity-calibration.js

@@ -0,0 +1,457 @@
+// Opt-in structured finding-severity calibration signal (#1955 calibration family).
+//
+// This module is the pure engine half of finding-severity calibration. The hosted review stack decides whether a
+// repo is currently opted in from its resolved `.gittensory.yml`/private config; the miner replay harness can then
+// ingest only the structured per-severity-tier finding fields exposed here — how many findings the review raised at
+// each severity tier (blocker/warning/advisory/nit) and how many of those were subsequently CONFIRMED (a true
+// positive that pointed at a real, acted-on issue). No raw review text, secrets, trust values, rewards, rankings, or
+// maintainer evidence are represented in this type surface.
+//
+// The score measures how well-CALIBRATED a review's severity assignments are: a confirmed blocker is worth much more
+// than a confirmed nit, and a review that raises blockers which are then dismissed (false positives at the tier that
+// most interrupts a maintainer) calibrates poorly. It composes with the objective-anchor and pairwise-judge signals
+// exactly like the other calibration signals in this family.
+const TIER_ORDER = ["blocker", "warning", "advisory", "nit"];
+// Severity weight for scoring: a confirmed blocker is worth far more than a confirmed nit, and a dismissed blocker
+// (false positive at the most disruptive tier) is penalized far more than a dismissed nit.
+const TIER_WEIGHT = {
+    blocker: 1,
+    warning: 0.6,
+    advisory: 0.3,
+    nit: 0.1,
+};
+const DEFAULT_STRUCTURED_FINDING_SEVERITY_WEIGHT = 0.2;
+const DEFAULT_COMPOSITE_WEIGHTS = {
+    objectiveAnchor: 0.45,
+    pairwiseJudge: 0.35,
+    structuredFindingSeverity: 0.2,
+};
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function finiteNonNegative(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 0)
+        return 0;
+    return value;
+}
+function finiteNonNegativeInt(value) {
+    if (value === undefined || !Number.isFinite(value) || value < 0)
+        return 0;
+    return Math.floor(value);
+}
+function roundScore(value) {
+    return Math.round(Math.min(1, Math.max(0, value)) * 1_000_000) / 1_000_000;
+}
+function normalizeRepoFullName(value) {
+    const trimmed = value.trim().toLowerCase();
+    if (!/^[a-z0-9_.-]+\/[a-z0-9_.-]+$/u.test(trimmed))
+        return null;
+    return trimmed;
+}
+function normalizeId(value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > 160 || /[\r\n\0]/u.test(trimmed))
+        return null;
+    return trimmed;
+}
+function normalizeObservedAt(value) {
+    if (!value)
+        return null;
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms))
+        return null;
+    return new Date(ms).toISOString();
+}
+function normalizeBoolean(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "on"].includes(normalized))
+        return true;
+    if (["false", "0", "no", "off"].includes(normalized))
+        return false;
+    return undefined;
+}
+function normalizeOptionalWeight(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const number = typeof value === "number" ? value : typeof value === "string" ? Number(value.trim()) : Number.NaN;
+    if (!Number.isFinite(number) || number < 0)
+        return undefined;
+    return number;
+}
+function clampConfidence(value) {
+    if (value === undefined)
+        return 1;
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.min(1, Math.max(0, value));
+}
+function normalizeTier(value) {
+    const normalized = value.trim().toLowerCase().replace(/[_\s-]+/gu, "_");
+    if (normalized === "block" || normalized === "blocked" || normalized === "blocking" || normalized === "critical") {
+        return "blocker";
+    }
+    if (normalized === "warn" || normalized === "warnings" || normalized === "major")
+        return "warning";
+    if (normalized === "info" ||
+        normalized === "informational" ||
+        normalized === "suggestion" ||
+        normalized === "advice") {
+        return "advisory";
+    }
+    if (normalized === "nitpick" || normalized === "minor" || normalized === "trivial" || normalized === "style") {
+        return "nit";
+    }
+    if (TIER_ORDER.includes(normalized))
+        return normalized;
+    return null;
+}
+/**
+ * Aggregate raw per-tier inputs into one normalized signal per tier: sum totals, sum confirmed (each entry's
+ * confirmed is clamped to its own total), drop tiers whose total is zero, and derive the confirmation rate and the
+ * severity-weighted per-tier score. Confidence discounts the effective confirmation the same way it does for the
+ * gate-verdict signal. Deterministic and returned in TIER_ORDER.
+ */
+function normalizeTiers(tiers) {
+    const byTier = new Map();
+    for (const item of tiers) {
+        const tier = normalizeTier(item.tier);
+        if (!tier)
+            continue;
+        const total = finiteNonNegativeInt(item.total);
+        if (total <= 0)
+            continue;
+        const confirmedRaw = Math.min(total, finiteNonNegativeInt(item.confirmed));
+        // A low confidence in the confirmation labelling shrinks the credited confirmations toward zero (never above the
+        // raw count), so an unverified "all confirmed" claim cannot inflate the calibration score.
+        const confirmed = Math.min(total, Math.round(confirmedRaw * clampConfidence(item.confidence)));
+        const existing = byTier.get(tier);
+        if (existing) {
+            existing.total += total;
+            existing.confirmed += confirmed;
+        }
+        else {
+            byTier.set(tier, { total, confirmed });
+        }
+    }
+    return TIER_ORDER.flatMap((tier) => {
+        const bucket = byTier.get(tier);
+        if (!bucket)
+            return [];
+        const confirmed = Math.min(bucket.total, bucket.confirmed);
+        const confirmationRate = roundScore(confirmed / bucket.total);
+        return [
+            {
+                tier,
+                total: bucket.total,
+                confirmed,
+                confirmationRate,
+                weight: TIER_WEIGHT[tier],
+                score: confirmationRate,
+            },
+        ];
+    });
+}
+/**
+ * The per-PR calibration score: the severity-and-volume-weighted mean of the per-tier confirmation rates, so a
+ * confirmed blocker moves the score far more than a confirmed nit, and a tier with more findings carries more weight
+ * than a tier with a single finding. Returns null when there is no weighted volume (which only happens for an empty
+ * tier list, already rejected upstream).
+ */
+function scoreTiers(tiers) {
+    let weightedRate = 0;
+    let weightSum = 0;
+    for (const tier of tiers) {
+        const weight = tier.weight * tier.total;
+        weightedRate += weight * tier.confirmationRate;
+        weightSum += weight;
+    }
+    if (weightSum <= 0)
+        return null;
+    return roundScore(weightedRate / weightSum);
+}
+function averageSignals(signals) {
+    if (signals.length === 0)
+        return null;
+    return roundScore(signals.reduce((sum, signal) => sum + signal.score, 0) / signals.length);
+}
+function isFindingSeverityCalibrationIngestion(value) {
+    return isRecord(value) && Array.isArray(value.accepted) && Array.isArray(value.rejected);
+}
+function sanitizeFindingSeverityCalibrationIngestion(ingestion) {
+    const accepted = [];
+    const rejected = [];
+    for (const signal of ingestion.accepted) {
+        if (!isRecord(signal) || !Array.isArray(signal.tiers))
+            continue;
+        const repoFullName = typeof signal.repoFullName === "string" ? normalizeRepoFullName(signal.repoFullName) : null;
+        const replayRunId = typeof signal.replayRunId === "string" ? normalizeId(signal.replayRunId) : null;
+        const reviewRunId = typeof signal.reviewRunId === "string" ? normalizeId(signal.reviewRunId) : null;
+        if (!repoFullName || !replayRunId || !reviewRunId)
+            continue;
+        const tierInputs = signal.tiers.flatMap((tier) => {
+            if (!isRecord(tier) ||
+                typeof tier.tier !== "string" ||
+                typeof tier.total !== "number" ||
+                typeof tier.confirmed !== "number") {
+                return [];
+            }
+            return [
+                {
+                    tier: tier.tier,
+                    total: tier.total,
+                    confirmed: tier.confirmed,
+                },
+            ];
+        });
+        const tiers = normalizeTiers(tierInputs);
+        const score = scoreTiers(tiers);
+        if (tiers.length === 0 || score === null)
+            continue;
+        accepted.push({
+            repoFullName,
+            replayRunId,
+            reviewRunId,
+            observedAt: typeof signal.observedAt === "string" ? normalizeObservedAt(signal.observedAt) : null,
+            tiers,
+            score,
+        });
+    }
+    for (const row of ingestion.rejected) {
+        if (!isRecord(row))
+            continue;
+        const repoFullName = typeof row.repoFullName === "string"
+            ? (normalizeRepoFullName(row.repoFullName) ?? normalizeId(row.repoFullName))
+            : null;
+        const replayRunId = typeof row.replayRunId === "string" ? normalizeId(row.replayRunId) : null;
+        const reviewRunId = typeof row.reviewRunId === "string" ? normalizeId(row.reviewRunId) : null;
+        const reason = row.reason;
+        if (!repoFullName ||
+            !replayRunId ||
+            !reviewRunId ||
+            !["not_opted_in", "empty_tiers", "invalid_repo", "invalid_run_id"].includes(reason)) {
+            continue;
+        }
+        rejected.push({ repoFullName, replayRunId, reviewRunId, reason });
+    }
+    return { accepted, rejected };
+}
+function normalizeCompositeWeights(weights) {
+    const raw = {
+        objectiveAnchor: finiteNonNegative(weights?.objectiveAnchor, DEFAULT_COMPOSITE_WEIGHTS.objectiveAnchor),
+        pairwiseJudge: finiteNonNegative(weights?.pairwiseJudge, DEFAULT_COMPOSITE_WEIGHTS.pairwiseJudge),
+        structuredFindingSeverity: finiteNonNegative(weights?.structuredFindingSeverity, DEFAULT_COMPOSITE_WEIGHTS.structuredFindingSeverity),
+    };
+    const total = raw.objectiveAnchor + raw.pairwiseJudge + raw.structuredFindingSeverity;
+    if (total <= 0)
+        return DEFAULT_COMPOSITE_WEIGHTS;
+    return {
+        objectiveAnchor: raw.objectiveAnchor / total,
+        pairwiseJudge: raw.pairwiseJudge / total,
+        structuredFindingSeverity: raw.structuredFindingSeverity / total,
+    };
+}
+function markdownSafe(value) {
+    return value.replace(/[\r\n]+/gu, " ").replace(/[\\`*_[\]<>|]/gu, "\\$&");
+}
+function markdownList(values) {
+    if (values.length === 0)
+        return "- none";
+    return values.map((value) => `- ${markdownSafe(value)}`).join("\n");
+}
+function renderTierRows(tiers) {
+    if (tiers.length === 0)
+        return "| Tier | Total | Confirmed | Rate | Weight |\n| --- | ---: | ---: | ---: | ---: |\n";
+    return [
+        "| Tier | Total | Confirmed | Rate | Weight |",
+        "| --- | ---: | ---: | ---: | ---: |",
+        ...tiers.map((tier) => `| ${markdownSafe(tier.tier)} | ${tier.total} | ${tier.confirmed} | ${tier.confirmationRate.toFixed(6)} | ${tier.weight.toFixed(6)} |`),
+    ].join("\n");
+}
+function renderContributingRepo(signal) {
+    return [
+        `### ${markdownSafe(signal.repoFullName)}`,
+        "",
+        `- replayRunId: ${markdownSafe(signal.replayRunId)}`,
+        `- reviewRunId: ${markdownSafe(signal.reviewRunId)}`,
+        `- observedAt: ${signal.observedAt ? markdownSafe(signal.observedAt) : "n/a"}`,
+        `- score: ${signal.score.toFixed(6)}`,
+        "",
+        renderTierRows(signal.tiers),
+    ].join("\n");
+}
+function renderRejectedRow(row) {
+    return `| ${markdownSafe(row.repoFullName)} | ${markdownSafe(row.replayRunId)} | ${markdownSafe(row.reviewRunId)} | ${markdownSafe(row.reason)} |`;
+}
+/**
+ * Resolve the explicit per-repo opt-in from a parsed `.gittensory.yml`-style object. Default is opted out. The
+ * preferred path is `miner.calibration.shareStructuredFindingSeverity`; `calibration.shareStructuredFindingSeverity`
+ * is accepted as a narrow alias so private-config surfaces can place the field at top level if needed.
+ */
+export function resolveFindingSeverityCalibrationConfig(manifest) {
+    const warnings = [];
+    const root = isRecord(manifest) ? manifest : {};
+    const miner = isRecord(root.miner) ? root.miner : {};
+    const minerCalibration = isRecord(miner.calibration) ? miner.calibration : {};
+    const topCalibration = isRecord(root.calibration) ? root.calibration : {};
+    const optInRaw = minerCalibration.shareStructuredFindingSeverity ?? topCalibration.shareStructuredFindingSeverity ?? undefined;
+    const optIn = normalizeBoolean(optInRaw);
+    if (optInRaw !== undefined && optIn === undefined) {
+        warnings.push("miner.calibration.shareStructuredFindingSeverity must be a boolean-like value; defaulting to false.");
+    }
+    const weightRaw = minerCalibration.structuredFindingSeverityWeight ?? topCalibration.structuredFindingSeverityWeight;
+    const weight = normalizeOptionalWeight(weightRaw);
+    if (weightRaw !== undefined && weight === undefined) {
+        warnings.push("miner.calibration.structuredFindingSeverityWeight must be a non-negative finite number; using default.");
+    }
+    return {
+        shareStructuredFindingSeverity: optIn === true,
+        structuredFindingSeverityWeight: weight ?? DEFAULT_STRUCTURED_FINDING_SEVERITY_WEIGHT,
+        warnings,
+    };
+}
+/**
+ * Ingest only currently opted-in structured finding-severity signals. The opt-in check happens at ingestion time, so
+ * a maintainer opt-out immediately prevents additional calibration rows from contributing even if older collected
+ * data exists elsewhere.
+ */
+export function ingestFindingSeverityCalibrationSignals(signals) {
+    const accepted = [];
+    const rejected = [];
+    for (const signal of signals) {
+        const repoFullName = normalizeRepoFullName(signal.repoFullName);
+        const replayRunId = normalizeId(signal.replayRunId);
+        const reviewRunId = normalizeId(signal.reviewRunId);
+        if (!repoFullName) {
+            rejected.push({
+                repoFullName: signal.repoFullName,
+                replayRunId: signal.replayRunId,
+                reviewRunId: signal.reviewRunId,
+                reason: "invalid_repo",
+            });
+            continue;
+        }
+        if (!replayRunId || !reviewRunId) {
+            rejected.push({
+                repoFullName,
+                replayRunId: signal.replayRunId,
+                reviewRunId: signal.reviewRunId,
+                reason: "invalid_run_id",
+            });
+            continue;
+        }
+        if (!signal.optedIn) {
+            rejected.push({ repoFullName, replayRunId, reviewRunId, reason: "not_opted_in" });
+            continue;
+        }
+        const tiers = normalizeTiers(signal.tiers);
+        const score = scoreTiers(tiers);
+        if (tiers.length === 0 || score === null) {
+            rejected.push({ repoFullName, replayRunId, reviewRunId, reason: "empty_tiers" });
+            continue;
+        }
+        accepted.push({
+            repoFullName,
+            replayRunId,
+            reviewRunId,
+            observedAt: normalizeObservedAt(signal.observedAt),
+            tiers,
+            score,
+        });
+    }
+    return { accepted, rejected };
+}
+export function computeFindingSeverityCompositeCalibrationScore(input) {
+    const ingestion = isFindingSeverityCalibrationIngestion(input.findingSeverity)
+        ? sanitizeFindingSeverityCalibrationIngestion(input.findingSeverity)
+        : ingestFindingSeverityCalibrationSignals(input.findingSeverity);
+    const objectiveAnchorScore = typeof input.objectiveAnchor === "number" ? roundScore(input.objectiveAnchor) : input.objectiveAnchor.score;
+    const pairwiseJudgeScore = input.pairwise === null
+        ? null
+        : typeof input.pairwise === "number"
+            ? roundScore(input.pairwise)
+            : input.pairwise.pairwiseJudgeScore;
+    const structuredFindingSeverityScore = averageSignals(ingestion.accepted);
+    const rawWeights = normalizeCompositeWeights(input.weights);
+    const usableWeights = {
+        objectiveAnchor: rawWeights.objectiveAnchor,
+        pairwiseJudge: pairwiseJudgeScore === null ? 0 : rawWeights.pairwiseJudge,
+        structuredFindingSeverity: structuredFindingSeverityScore === null ? 0 : rawWeights.structuredFindingSeverity,
+    };
+    const total = usableWeights.objectiveAnchor + usableWeights.pairwiseJudge + usableWeights.structuredFindingSeverity;
+    const weights = total <= 0
+        ? { objectiveAnchor: 1, pairwiseJudge: 0, structuredFindingSeverity: 0 }
+        : {
+            objectiveAnchor: usableWeights.objectiveAnchor / total,
+            pairwiseJudge: usableWeights.pairwiseJudge / total,
+            structuredFindingSeverity: usableWeights.structuredFindingSeverity / total,
+        };
+    const compositeScore = roundScore(objectiveAnchorScore * weights.objectiveAnchor +
+        (pairwiseJudgeScore ?? 0) * weights.pairwiseJudge +
+        (structuredFindingSeverityScore ?? 0) * weights.structuredFindingSeverity);
+    return {
+        compositeScore,
+        objectiveAnchorScore,
+        pairwiseJudgeScore,
+        structuredFindingSeverityScore,
+        weights,
+        audit: {
+            contributingRepos: ingestion.accepted.map((signal) => ({
+                repoFullName: signal.repoFullName,
+                replayRunId: signal.replayRunId,
+                reviewRunId: signal.reviewRunId,
+                observedAt: signal.observedAt,
+                score: signal.score,
+                tiers: signal.tiers,
+            })),
+            rejected: ingestion.rejected,
+        },
+    };
+}
+/**
+ * Render a deterministic, public-safe Markdown report for a structured finding-severity calibration result. The
+ * report is local-run evidence: it includes aggregate scores, normalized weights, opted-in contributors, and rejected
+ * rows, but never accepts or emits raw review text or private scoring fields.
+ */
+export function renderFindingSeverityCalibrationAuditMarkdown(result) {
+    const lines = [
+        "# Structured Finding-Severity Calibration",
+        "",
+        `Composite score: ${result.compositeScore.toFixed(6)}`,
+        "",
+        "## Component Scores",
+        "",
+        `- objectiveAnchor: ${result.objectiveAnchorScore.toFixed(6)}`,
+        `- pairwiseJudge: ${result.pairwiseJudgeScore === null ? "n/a" : result.pairwiseJudgeScore.toFixed(6)}`,
+        `- structuredFindingSeverity: ${result.structuredFindingSeverityScore === null ? "n/a" : result.structuredFindingSeverityScore.toFixed(6)}`,
+        "",
+        "## Effective Weights",
+        "",
+        `- objectiveAnchor: ${result.weights.objectiveAnchor.toFixed(6)}`,
+        `- pairwiseJudge: ${result.weights.pairwiseJudge.toFixed(6)}`,
+        `- structuredFindingSeverity: ${result.weights.structuredFindingSeverity.toFixed(6)}`,
+        "",
+        "## Contributing Repos",
+        "",
+        result.audit.contributingRepos.length === 0
+            ? "_No opted-in structured finding-severity signals contributed._"
+            : result.audit.contributingRepos.map(renderContributingRepo).join("\n\n"),
+        "",
+        "## Rejected Rows",
+        "",
+    ];
+    if (result.audit.rejected.length === 0) {
+        lines.push("- none");
+    }
+    else {
+        lines.push("| Repo | Replay run | Review run | Reason |", "| --- | --- | --- | --- |", ...result.audit.rejected.map(renderRejectedRow));
+    }
+    const contributingRepos = result.audit.contributingRepos.map((repo) => repo.repoFullName);
+    lines.push("", "## Contributing Repo Summary", "", markdownList(contributingRepos));
+    return `${lines.join("\n")}\n`;
+}

package/dist/fleet-run-manifest.d.ts

@@ -0,0 +1,41 @@
+/** One target repo in a fleet run, with its own concurrent-worktree budget. */
+export type FleetRunManifestRepo = {
+    /** Canonical `owner/repo`. Compatible with opportunity-fanout's target normalization (a splittable pair). */
+    repoFullName: string;
+    /**
+     * Max concurrent worktrees (in-flight attempts) this repo may hold at once. A positive integer (`>= 1`); a
+     * non-integer is floored, a value below 1 falls back to the default. Default: 1.
+     */
+    maxConcurrentWorktrees: number;
+};
+/** Fleet run-manifest: the repos to work across and how to split the concurrency budget. See {@link DEFAULT_FLEET_RUN_MANIFEST}. */
+export type FleetRunManifest = {
+    /** Target repos, de-duplicated by `repoFullName` (first entry wins). Default: [] (no repos in scope). */
+    repos: readonly FleetRunManifestRepo[];
+    /**
+     * Total concurrent worktrees across the whole fleet, regardless of per-repo budgets. A positive integer
+     * (`>= 1`); floored, sub-1 falls back to the default. Default: 1.
+     */
+    totalConcurrentWorktrees: number;
+};
+/** Tolerant parser result: the normalized manifest plus warnings and whether the file expressed any non-default
+ *  field. Mirrors {@link ParsedMinerGoalSpec}'s present/warnings shape. */
+export type ParsedFleetRunManifest = {
+    present: boolean;
+    manifest: FleetRunManifest;
+    warnings: string[];
+};
+/** Safe defaults applied when a field is absent (or the file is missing): no repos in scope, one worktree total.
+ *  Deep-frozen shared singleton — clone before layering overrides. */
+export declare const DEFAULT_FLEET_RUN_MANIFEST: FleetRunManifest;
+/**
+ * Tolerantly normalize an already-parsed run-manifest object into a {@link ParsedFleetRunManifest}. Never throws:
+ * malformed shapes degrade to safe defaults and accumulate warnings so a fleet run can surface "your run-manifest
+ * had problems" without hard-failing. Mirrors {@link parseMinerGoalSpec}.
+ */
+export declare function parseFleetRunManifest(raw: unknown): ParsedFleetRunManifest;
+/**
+ * Parse raw run-manifest file content (JSON or YAML). Malformed content degrades to an absent manifest with a
+ * warning rather than throwing, mirroring {@link parseMinerGoalSpecContent}.
+ */
+export declare function parseFleetRunManifestContent(content: string | null | undefined): ParsedFleetRunManifest;

package/dist/fleet-run-manifest.js

@@ -0,0 +1,151 @@
+import { parse as parseYaml } from "yaml";
+/** Safe defaults applied when a field is absent (or the file is missing): no repos in scope, one worktree total.
+ *  Deep-frozen shared singleton — clone before layering overrides. */
+export const DEFAULT_FLEET_RUN_MANIFEST = Object.freeze({
+    repos: Object.freeze([]),
+    totalConcurrentWorktrees: 1,
+});
+const MAX_FLEET_RUN_MANIFEST_BYTES = 65_536;
+const MAX_MANIFEST_REPOS = 500;
+function cloneDefaultFleetRunManifest() {
+    return { ...DEFAULT_FLEET_RUN_MANIFEST, repos: [...DEFAULT_FLEET_RUN_MANIFEST.repos] };
+}
+function emptyFleetRunManifest(warnings = []) {
+    return { present: false, manifest: cloneDefaultFleetRunManifest(), warnings };
+}
+/** `owner/repo` with exactly one slash and non-empty halves; anything else → null. Same shape the goal-spec /
+ *  portfolio-queue validators use, so a manifest repo is directly compatible with opportunity-fanout targets. */
+function normalizeRepoFullName(value) {
+    if (typeof value !== "string")
+        return null;
+    const [owner, repo, extra] = value.trim().split("/");
+    if (!owner || !repo || extra !== undefined)
+        return null;
+    return `${owner}/${repo}`;
+}
+function normalizePositiveInteger(value, field, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        warnings.push(`FleetRunManifest field "${field}" must be a positive whole number; falling back to ${fallback}.`);
+        return fallback;
+    }
+    const normalized = Math.floor(value);
+    if (normalized >= 1)
+        return normalized;
+    warnings.push(`FleetRunManifest field "${field}" must be >= 1 after flooring; falling back to ${fallback}.`);
+    return fallback;
+}
+// A repo entry may be a bare `"owner/repo"` string (uses the default per-repo budget) or a `{ repoFullName,
+// maxConcurrentWorktrees? }` mapping. Anything else, or an unparseable repo name, is skipped with a warning.
+function normalizeRepoList(value, warnings) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`FleetRunManifest field "repos" must be a list; ignoring a ${typeof value} value.`);
+        return [];
+    }
+    const result = [];
+    const seen = new Set();
+    for (const [index, entry] of value.entries()) {
+        if (index >= MAX_MANIFEST_REPOS) {
+            warnings.push(`FleetRunManifest field "repos" exceeded ${MAX_MANIFEST_REPOS} entries; extra entries ignored.`);
+            break;
+        }
+        let repoFullName;
+        let maxConcurrentWorktrees = DEFAULT_FLEET_RUN_MANIFEST.totalConcurrentWorktrees;
+        if (typeof entry === "string") {
+            repoFullName = normalizeRepoFullName(entry);
+        }
+        else if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+            const record = entry;
+            repoFullName = normalizeRepoFullName(record.repoFullName);
+            maxConcurrentWorktrees = normalizePositiveInteger(record.maxConcurrentWorktrees, "maxConcurrentWorktrees", 1, warnings);
+        }
+        else {
+            warnings.push(`FleetRunManifest "repos" skipped a non-string, non-mapping entry.`);
+            continue;
+        }
+        if (repoFullName === null) {
+            warnings.push(`FleetRunManifest "repos" skipped an entry with an invalid "owner/repo" name.`);
+            continue;
+        }
+        if (seen.has(repoFullName)) {
+            warnings.push(`FleetRunManifest "repos" skipped a duplicate entry for ${repoFullName}.`);
+            continue;
+        }
+        seen.add(repoFullName);
+        result.push({ repoFullName, maxConcurrentWorktrees });
+    }
+    return result;
+}
+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;
+}
+function hasConfiguredManifestFields(manifest) {
+    return manifest.repos.length > 0 || manifest.totalConcurrentWorktrees !== DEFAULT_FLEET_RUN_MANIFEST.totalConcurrentWorktrees;
+}
+/**
+ * Tolerantly normalize an already-parsed run-manifest object into a {@link ParsedFleetRunManifest}. Never throws:
+ * malformed shapes degrade to safe defaults and accumulate warnings so a fleet run can surface "your run-manifest
+ * had problems" without hard-failing. Mirrors {@link parseMinerGoalSpec}.
+ */
+export function parseFleetRunManifest(raw) {
+    if (raw === undefined || raw === null)
+        return emptyFleetRunManifest();
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return emptyFleetRunManifest([
+            "FleetRunManifest must be a mapping of fields; ignoring malformed config and falling back to safe defaults.",
+        ]);
+    }
+    const record = raw;
+    const warnings = [];
+    const manifest = {
+        repos: normalizeRepoList(record.repos, warnings),
+        totalConcurrentWorktrees: normalizePositiveInteger(record.totalConcurrentWorktrees, "totalConcurrentWorktrees", DEFAULT_FLEET_RUN_MANIFEST.totalConcurrentWorktrees, warnings),
+    };
+    if (!hasConfiguredManifestFields(manifest)) {
+        warnings.push("FleetRunManifest contained no recognized non-default fields; falling back to safe defaults.");
+        return { present: false, manifest: cloneDefaultFleetRunManifest(), warnings };
+    }
+    return { present: true, manifest, warnings };
+}
+/**
+ * Parse raw run-manifest file content (JSON or YAML). Malformed content degrades to an absent manifest with a
+ * warning rather than throwing, mirroring {@link parseMinerGoalSpecContent}.
+ */
+export function parseFleetRunManifestContent(content) {
+    if (content === undefined || content === null || content.trim() === "")
+        return emptyFleetRunManifest();
+    if (utf8ByteLength(content) > MAX_FLEET_RUN_MANIFEST_BYTES) {
+        return emptyFleetRunManifest([
+            `FleetRunManifest content exceeded ${MAX_FLEET_RUN_MANIFEST_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 emptyFleetRunManifest([
+            looksLikeJson
+                ? "FleetRunManifest content was not valid JSON; ignoring it and falling back to safe defaults."
+                : "FleetRunManifest content was not valid YAML; ignoring it and falling back to safe defaults.",
+        ]);
+    }
+    return parseFleetRunManifest(parsed);
+}

package/dist/focus-manifest/guidance.d.ts

@@ -0,0 +1,21 @@
+import type { FocusManifest, FocusManifestGuidance } from "../types/predicted-gate-types.js";
+export declare function isFocusManifestPublicSafe(text: string): boolean;
+/**
+ * Match a changed path against a manifest path pattern. Supports exact paths, directory
+ * prefixes (`src/` or `src`), and `*` wildcards (`**` collapses to `*`).
+ */
+export declare function matchesManifestPath(path: string, pattern: string): boolean;
+/**
+ * Build deterministic, public-safe guidance from a focus manifest for a concrete change set.
+ * Explains why changed paths are preferred or discouraged and surfaces manifest-driven blockers
+ * without leaking maintainer-private notes into public next steps.
+ */
+export declare function buildFocusManifestGuidance(args: {
+    manifest: FocusManifest;
+    changedPaths: string[];
+    labels?: string[] | undefined;
+    linkedIssueCount?: number | undefined;
+    testFileCount?: number | undefined;
+    passedValidationCount?: number | undefined;
+}): FocusManifestGuidance;
+export type { FocusManifest, FocusManifestGuidance, PreMergeCheck } from "../types/predicted-gate-types.js";