@bridge_gpt/mcp-server 0.2.67 → 0.2.68

package/build/conductor/readiness-sections.js

@@ -197,6 +197,355 @@ export function presentRequiredChecks(supervisor) {
     };
 }
 // ---------------------------------------------------------------------------
+// Gate-profile wording (BAPI-1390) — shared with the readiness gate's rows
+// ---------------------------------------------------------------------------
+/**
+ * Render a server-validated check or command name for a remedy. The name is
+ * the ONLY payload value any remedy interpolates; backticks are swapped so it
+ * cannot close its own quoting.
+ */
+export function quotedSubject(subject, fallback) {
+    if (subject === null)
+        return fallback;
+    const safe = subject.replace(/`/g, "'");
+    return `\`${safe}\``;
+}
+/** Human words for the profile kind. `null` is an unknown kind, never a held one. */
+const GATE_PROFILE_KIND_LABELS = {
+    provider: "Provider",
+    local: "Local",
+    mixed: "Mixed",
+    none: "None",
+};
+/**
+ * One line describing a gate profile: kind, source, confirmation, revision,
+ * members, migration guard, and qualification state. Shared with the install
+ * doctor's section so the two surfaces cannot word the same profile apart.
+ * Only validated names are interpolated; everything else is a closed token.
+ */
+export function describeGateProfile(profile) {
+    const kind = profile.kind === null ? "Unknown" : GATE_PROFILE_KIND_LABELS[profile.kind] ?? "Unknown";
+    const source = profile.source === "legacy"
+        ? "legacy: pre-profile done-gate checks treated as a confirmed provider profile"
+        : profile.source;
+    const parts = [
+        `${kind} gate profile (${source}, ${profile.confirmed ? "confirmed" : "unconfirmed"}, revision ${profile.revision})`,
+    ];
+    if (profile.provider_checks.length > 0) {
+        parts.push(`provider checks: ${profile.provider_checks
+            .map((c) => `${quotedSubject(c.name, "")} ${c.outcome === "evidence_unavailable" ? "unavailable" : c.outcome ?? "unknown"}`)
+            .join(", ")}`);
+    }
+    if (profile.local_commands.length > 0) {
+        parts.push(`local commands: ${profile.local_commands.map((c) => quotedSubject(c.name, "")).join(", ")}`);
+    }
+    parts.push(profile.migration_guard === null
+        ? profile.migration_guard_required === true
+            ? "migration guard: unset (required)"
+            : "migration guard: none"
+        : `migration guard: ${profile.migration_guard.kind}${profile.migration_guard.name === null ? "" : ` ${quotedSubject(profile.migration_guard.name, "")}`}`);
+    if (profile.qualification_state !== null)
+        parts.push(`qualification: ${profile.qualification_state}`);
+    if (profile.kind === "none") {
+        parts.push("unattended runs proceed, but every child merge waits for approval (`merge-child`)");
+    }
+    return parts.join("; ");
+}
+/** Fixed copy for a known warning code. Only the validated name is interpolated. */
+export function describeGateProfileWarning(code, name) {
+    switch (code) {
+        case "provider_check_not_seen_on_epic_branches":
+            return `the check ${quotedSubject(name, "named in the gate profile")} has not been seen on an epic branch yet — this does not hold a launch`;
+        case "epic_branch_search_unavailable":
+            return "Bridge could not search epic branches for the gate-profile checks — this does not hold a launch";
+        default:
+            return "the gate profile reported a warning this CLI does not recognize — this does not hold a launch";
+    }
+}
+/** Section id for each known warn-only gate-profile code; anything else is generic. */
+const GATE_PROFILE_WARNING_SECTION_IDS = {
+    provider_check_not_seen_on_epic_branches: "supervisor-gate-profile-epic-branch-unseen",
+    epic_branch_search_unavailable: "supervisor-gate-profile-epic-branch-search",
+};
+/**
+ * BAPI-1390 — the gate-profile section plus its warn-only rows. Emitted ONLY
+ * when the server reported a profile, so an older server's report is
+ * byte-identical. Never `fatal`: the server's admission evidence decides holds;
+ * these sections describe. Warnings are `degraded` with copy that says they do
+ * not hold a launch, one section per known code (names joined) plus one
+ * generic section for codes this client does not recognize.
+ */
+export function gateProfileSections(profile) {
+    if (profile === undefined)
+        return [];
+    if (profile === null) {
+        return [
+            {
+                id: "supervisor-gate-profile",
+                label: "Supervisor gate profile",
+                status: "degraded",
+                detail: "the server reported no gate profile, so the CI gate is unverified",
+                remediation: "upgrade the Bridge API deploy so it reports the gate profile.",
+            },
+        ];
+    }
+    const detail = describeGateProfile(profile);
+    const held = profile.read_failed ||
+        profile.stored_malformed ||
+        profile.verdict === "denied" ||
+        profile.verdict === "unable_to_verify";
+    const sections = [];
+    if (held) {
+        sections.push({
+            id: "supervisor-gate-profile",
+            label: "Supervisor gate profile",
+            status: "degraded",
+            detail: profile.read_failed
+                ? `the stored gate profile could not be read — ${detail}`
+                : profile.stored_malformed
+                    ? `the stored gate profile is malformed — ${detail}`
+                    : `${profile.verdict === "denied" ? "denied" : "could not be verified"}${profile.reason ? ` (${profile.reason})` : ""} — ${detail}`,
+            remediation: "a repository administrator reviews the gate profile on the repository's Setup page; " +
+                "the server's launch evidence names the specific item.",
+        });
+    }
+    else if (profile.verdict === "confirmed" && profile.kind !== "none") {
+        sections.push({ id: "supervisor-gate-profile", label: "Supervisor gate profile", status: "ok", detail });
+    }
+    else {
+        sections.push({
+            id: "supervisor-gate-profile",
+            label: "Supervisor gate profile",
+            status: "degraded",
+            detail,
+            remediation: profile.kind === "none"
+                ? "no action is needed to launch; to let child merges proceed without approval, add checks to the gate profile."
+                : "a repository administrator confirms the gate profile; the server's launch evidence decides whether a run is held.",
+        });
+    }
+    const grouped = new Map();
+    for (const warning of profile.warnings) {
+        const id = GATE_PROFILE_WARNING_SECTION_IDS[warning.code] ?? "supervisor-gate-profile-warning";
+        const entry = grouped.get(id) ?? { code: warning.code, names: [] };
+        entry.names.push(warning.name);
+        grouped.set(id, entry);
+    }
+    for (const [id, { code, names }] of grouped) {
+        const named = names.filter((name) => name !== null);
+        sections.push({
+            id,
+            label: "Supervisor gate profile warning",
+            status: "degraded",
+            detail: code === "provider_check_not_seen_on_epic_branches" && named.length > 1
+                ? `the checks ${named.map((name) => quotedSubject(name, "")).join(", ")} have not been seen on an epic branch yet — this does not hold a launch`
+                : describeGateProfileWarning(code, named[0] ?? null),
+            remediation: "no action is needed to launch; this is a warning only.",
+        });
+    }
+    return sections;
+}
+// ---------------------------------------------------------------------------
+// BAPI-1405 — epic-branch CI rows (warn-only)
+// ---------------------------------------------------------------------------
+/** Stable section ids for the three epic-branch CI rows. */
+export const EPIC_BRANCH_CI_SECTION_IDS = {
+    reviewMode: "effective-review-mode",
+    decision: "epic-branch-ci-decision",
+    coverage: "epic-branch-ci-coverage-warning",
+};
+/** Row labels, shared by readiness and the install doctor. */
+export const EPIC_BRANCH_CI_SECTION_LABELS = {
+    reviewMode: "Effective review mode",
+    decision: "Epic-branch CI decision",
+    coverage: "Epic-branch CI coverage warning",
+};
+/** What every row says when the server did not report the block. Never "no warning". */
+export const EPIC_BRANCH_CI_UNREPORTED_DETAIL = "Unreported — upgrade the server";
+/** The one remediation an unreported block carries. */
+export const EPIC_BRANCH_CI_UNREPORTED_REMEDIATION = "upgrade the Bridge API deploy so it reports epic-branch CI facts; this does not hold a launch.";
+/** The single next step for evidence that may be out of date or uncertain. */
+export const EPIC_BRANCH_CI_RERUN_INSTALL_ADVICE = "Rerun install after workflow or ruleset changes.";
+/** Plain words for each effective review mode. */
+const EFFECTIVE_REVIEW_MODE_WORDS = {
+    repository_policy: "repository_policy — no review verdict is required for epic-branch merges",
+    verdict_protocol: "verdict_protocol — child merges wait for the claude-review verdict",
+    native_review_decision: "native_review_decision — child merges wait for GitHub's own review decision",
+    none: "none — no review signal gates child merges",
+};
+/** Plain words for each known no-CI reason. An unknown reason renders generically. */
+function describeNoCiReason(reason) {
+    switch (reason) {
+        case "gate_profile_none":
+            return "the gate profile is `none`, so no CI check gates child merges";
+        case "gate_profile_local_only":
+            return "the gate is local-only, so on a feature-branch run no provider check runs on epic-branch PRs";
+        case "triggers_do_not_cover_epic":
+            return "the evidence recorded at install says no pull_request trigger covers epic/**";
+        default:
+            return `the server reported a reason this CLI does not recognize (${reason})`;
+    }
+}
+/** One next step per known no-CI reason. */
+function noCiReasonNextStep(reason) {
+    switch (reason) {
+        case "gate_profile_none":
+            return "add provider checks to the gate profile";
+        case "gate_profile_local_only":
+            return "add a provider check to the gate profile if epic-branch PRs should run CI";
+        case "triggers_do_not_cover_epic":
+            return "add epic/** to your CI workflow's pull_request branches filter, then rerun install";
+        default:
+            return "upgrade this CLI to read the server's reason";
+    }
+}
+function yesNoUnknown(value) {
+    return value === null ? "could not tell" : value ? "yes" : "no";
+}
+/**
+ * The compact "recorded at install" evidence summary. Trigger coverage is
+ * worded as coverage, never as proof that CI runs.
+ */
+export function describeEpicBranchCiEvidence(evidence) {
+    return ("recorded at install: " +
+        `pull_request trigger covers epic/** ${yesNoUnknown(evidence.workflow_triggers_cover_epic)}; ` +
+        `approvals apply on epic/** ${yesNoUnknown(evidence.required_approvals_apply_to_epic)}; ` +
+        `observation quality ${evidence.observation_quality === "could_not_tell" ? "could not tell" : evidence.observation_quality}; ` +
+        `exemption outcome ${evidence.exemption_outcome === "not_exempt" ? "not exempt" : evidence.exemption_outcome}`);
+}
+/**
+ * One reason per "could not tell" in the evidence, each in plain words. Empty
+ * when nothing is uncertain. The shared next step is
+ * {@link EPIC_BRANCH_CI_RERUN_INSTALL_ADVICE}.
+ */
+export function epicBranchCiEvidenceUnknowns(evidence) {
+    const unknowns = [];
+    if (evidence.workflow_triggers_cover_epic === null) {
+        unknowns.push("trigger coverage could not tell: a workflow was not read confidently");
+    }
+    if (evidence.required_approvals_apply_to_epic === null) {
+        unknowns.push("approvals could not tell: the epic-branch rules were not readable");
+    }
+    if (evidence.observation_quality === "could_not_tell" &&
+        evidence.workflow_triggers_cover_epic !== null &&
+        evidence.required_approvals_apply_to_epic !== null) {
+        unknowns.push("observation quality could not tell: a finding was not confirmed");
+    }
+    if (evidence.exemption_outcome === "unknown") {
+        unknowns.push("exemption could not tell: the approval exemption was not confirmed");
+    }
+    return unknowns;
+}
+function effectiveReviewModeSection(block) {
+    const mode = block.effective_review_mode;
+    if (mode === null) {
+        return {
+            id: EPIC_BRANCH_CI_SECTION_IDS.reviewMode,
+            label: EPIC_BRANCH_CI_SECTION_LABELS.reviewMode,
+            status: "degraded",
+            detail: "the server reported a review mode this CLI does not recognize",
+            remediation: "upgrade this CLI so it can read the review mode; this does not hold a launch.",
+        };
+    }
+    return {
+        id: EPIC_BRANCH_CI_SECTION_IDS.reviewMode,
+        label: EPIC_BRANCH_CI_SECTION_LABELS.reviewMode,
+        status: "ok",
+        detail: EFFECTIVE_REVIEW_MODE_WORDS[mode],
+    };
+}
+function epicBranchCiDecisionSection(block) {
+    const choice = block.decision === "include"
+        ? "Include — child merges wait for the epic-branch CI checks"
+        : block.decision === "decline"
+            ? "Decline — child merges do not wait for CI checks on the epic branch; problems surface at the integration PR"
+            : "Not recorded — behaves like include";
+    const evidence = block.evidence;
+    const detail = evidence === null
+        ? `${choice}; no evidence was recorded at install`
+        : `${choice}; ${describeEpicBranchCiEvidence(evidence)}`;
+    const unknowns = evidence === null ? [] : epicBranchCiEvidenceUnknowns(evidence);
+    if (unknowns.length > 0) {
+        return {
+            id: EPIC_BRANCH_CI_SECTION_IDS.decision,
+            label: EPIC_BRANCH_CI_SECTION_LABELS.decision,
+            status: "degraded",
+            detail,
+            remediation: `${unknowns.join("; ")}. ${EPIC_BRANCH_CI_RERUN_INSTALL_ADVICE} This does not hold a launch.`,
+        };
+    }
+    return {
+        id: EPIC_BRANCH_CI_SECTION_IDS.decision,
+        label: EPIC_BRANCH_CI_SECTION_LABELS.decision,
+        status: "ok",
+        detail: block.decision === null
+            ? `${detail}; run install to record a decision`
+            : evidence === null
+                ? detail
+                : `${detail}. ${EPIC_BRANCH_CI_RERUN_INSTALL_ADVICE}`,
+    };
+}
+function epicBranchCiCoverageSection(block) {
+    const reasons = block.no_ci_reasons;
+    if (!block.no_ci_warning && reasons.length === 0) {
+        const triggers = block.evidence?.workflow_triggers_cover_epic ?? null;
+        return {
+            id: EPIC_BRANCH_CI_SECTION_IDS.coverage,
+            label: EPIC_BRANCH_CI_SECTION_LABELS.coverage,
+            status: "ok",
+            detail: triggers === null
+                ? "no warning from the gate profile; trigger coverage of epic/** was not recorded or could not be told at install"
+                : "no warning: the gate profile and the evidence recorded at install give no reason to expect epic-branch PRs to skip CI (trigger coverage does not guarantee CI runs)",
+        };
+    }
+    const described = reasons.map(describeNoCiReason);
+    return {
+        id: EPIC_BRANCH_CI_SECTION_IDS.coverage,
+        label: EPIC_BRANCH_CI_SECTION_LABELS.coverage,
+        status: "degraded",
+        detail: described.length === 0
+            ? "Warning: epic-branch PRs may run no CI (the server gave no reason)"
+            : `Warning: epic-branch PRs may run no CI — ${described.join("; ")}`,
+        remediation: (reasons.length === 0
+            ? "review the gate profile and your CI workflow triggers"
+            : reasons.map(noCiReasonNextStep).join("; ")) + ". This warning does not hold a launch.",
+    };
+}
+/**
+ * BAPI-1405 — the three warn-only epic-branch CI rows: **Effective review
+ * mode**, **Epic-branch CI decision**, and **Epic-branch CI coverage warning**.
+ *
+ * Always three rows, so an older server is visible: an absent or `null` block
+ * renders every row as {@link EPIC_BRANCH_CI_UNREPORTED_DETAIL}, never as "no
+ * warning". Never `fatal`: none of these rows may change an admission verdict,
+ * a readiness verdict, or an exit status. Status is carried by words in the
+ * detail as well as by the status field, never by color alone.
+ */
+export function epicBranchCiSections(block) {
+    if (block === undefined || block === null) {
+        return ["reviewMode", "decision", "coverage"].map((key) => ({
+            id: EPIC_BRANCH_CI_SECTION_IDS[key],
+            label: EPIC_BRANCH_CI_SECTION_LABELS[key],
+            status: "degraded",
+            detail: EPIC_BRANCH_CI_UNREPORTED_DETAIL,
+            remediation: EPIC_BRANCH_CI_UNREPORTED_REMEDIATION,
+        }));
+    }
+    return [
+        effectiveReviewModeSection(block),
+        epicBranchCiDecisionSection(block),
+        epicBranchCiCoverageSection(block),
+    ];
+}
+/**
+ * True when the server says the effective review mode is `repository_policy`,
+ * which requires no review verdict, so the claude-review workflow and the
+ * review-policy alignment rows have nothing to nag about. Absent block → false
+ * (older behavior is kept exactly).
+ */
+export function effectiveReviewModeIsRepositoryPolicy(readiness) {
+    return readiness?.epic_branch_ci?.effective_review_mode === "repository_policy";
+}
+// ---------------------------------------------------------------------------
 // Section builders
 // ---------------------------------------------------------------------------
 export function supervisorSection(readiness) {
@@ -253,7 +602,18 @@ export function supervisorSection(readiness) {
     // manufacture a finding out of a server that never answered.
     const alignment = s.review_policy_alignment;
     if (alignment !== null) {
-        if (alignment.status === "divergent" || alignment.status === "invalid") {
+        if (alignment.status === "divergent" && effectiveReviewModeIsRepositoryPolicy(readiness)) {
+            // BAPI-1405 — `repository_policy` requires no review verdict, so a
+            // divergent done-gate review signal is not a nag here. `invalid` still
+            // warns: an unreadable review configuration is its own problem.
+            sections.push({
+                id: "supervisor-review-alignment",
+                label: "Supervisor review-policy alignment",
+                status: "ok",
+                detail: "not applicable: the effective review mode is 'repository_policy', which requires no review verdict",
+            });
+        }
+        else if (alignment.status === "divergent" || alignment.status === "invalid") {
             sections.push({
                 id: "supervisor-review-alignment",
                 label: "Supervisor review-policy alignment",
@@ -279,6 +639,8 @@ export function supervisorSection(readiness) {
             });
         }
     }
+    // BAPI-1390 — nothing at all when the server did not report a profile.
+    sections.push(...gateProfileSections(readiness.gate_profile));
     return sections;
 }
 export function githubCredentialsSection(readiness) {
@@ -526,7 +888,9 @@ export function workflowSection(presence, reviewPolicySource, driftDetail) {
     // never `absent`, and the policy-applicability branch below does not apply
     // (a stale workflow only matters to a policy that consumes its verdict, and
     // the caller only classifies drift when it does).
-    if (presence === "drifted") {
+    // BAPI-1405: under `repository_policy` no verdict is consumed, so a drifted
+    // file falls through to the not-applicable branch below instead of nagging.
+    if (presence === "drifted" && reviewPolicySource !== "repository_policy") {
         return {
             id: "claude-review-workflow",
             label: "claude-review workflow",
@@ -540,7 +904,9 @@ export function workflowSection(presence, reviewPolicySource, driftDetail) {
     // review decision does not need the Claude workflow at all, so its absence is
     // not a gap. Reporting it as degraded there would train operators to ignore
     // this section.
-    if (reviewPolicySource === "native_review_decision" || reviewPolicySource === "none") {
+    if (reviewPolicySource === "native_review_decision" ||
+        reviewPolicySource === "none" ||
+        reviewPolicySource === "repository_policy") {
         return {
             id: "claude-review-workflow",
             label: "claude-review workflow",