@martinloop/mcp 0.3.8 → 0.5.0

package/dist/vendor/contracts/index.js

@@ -1,3 +1,12 @@
+/**
+ * Contracts for the Martin Loop agentic system.
+ *
+ * This module defines the core type contracts and data structures for autonomous agent loop management,
+ * including loop lifecycle states, task definitions, budget tracking, cost accounting, verification,
+ * patch decisions, telemetry, and governance policies. It provides the public API surface for
+ * creating and managing loop records, handling events, validating batches, and tracking
+ * portfolio snapshots and routing economics.
+ */
 export const FAILURE_CLASSES = [
     "logic_error",
     "hallucination",
@@ -53,6 +62,7 @@ export function createLoopRecord(draft, options = {}) {
         updatedAt: draft.updatedAt ?? now,
         ...(draft.receiptScope ? { receiptScope: draft.receiptScope } : {}),
         ...(draft.receiptIntegrity ? { receiptIntegrity: draft.receiptIntegrity } : {}),
+        ...(draft.terminationEnvelope ? { terminationEnvelope: draft.terminationEnvelope } : {}),
         ...(draft.teamId ? { teamId: draft.teamId } : {})
     };
 }
@@ -210,6 +220,8 @@ function nextStatus(current, eventType) {
             return "verifying";
         case "run.completed":
             return current === "failed" ? "failed" : "completed";
+        case "run.terminated":
+            return "exited";
         default:
             return current;
     }
@@ -223,5 +235,15 @@ export { DEFAULT_ROUTING_POLICY } from "./execution-policy.js";
 export { cloneContextGraphSnapshot } from "./context-graph.js";
 export { cloneIdentityAttestation, cloneIdentityClaims, cloneIdentityToken } from "./identity.js";
 export { cloneCircuitBreakDecision, cloneTrajectoryAssessment } from "./trajectory.js";
+export { EXIT_KINDS, EXIT_POLICY_VERSION, EXIT_EVALUATION_VERSION, EXIT_SIGNAL_VERSION, TERMINATION_ENVELOPE_VERSION } from "./exits.js";
 // ─── R4 Delivery — M1 Contract ──────────────────────────────────────────────
 export { ALLOWED_ACTION_TYPES, DELIVERY_MESSAGE_SCHEMA_VERSION, DELIVERY_RECORD_SCHEMA_VERSION, MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION } from "./delivery.js";
+// ─── Context Shadow — A-CTX-0 ────────────────────────────────────────────────
+export { CONTEXT_SHADOW_MANIFEST_VERSION, CONTEXT_C5_VERSION } from "./context-shadow.js";
+// ─── Context Runtime — A-CTX-1 ───────────────────────────────────────────────
+export { CONTEXT_MANIFEST_VERSION, CONTEXT_LEDGER_VERSION } from "./context-manifest.js";
+// ─── Track A — Verified Handoff ───────────────────────────────────────────────
+export { EVIDENCE_STATUSES, TEST_INTEGRITY_STATUSES, TEST_INTEGRITY_VERDICTS, VERIFIED_HANDOFF_OUTCOMES, } from "./verified-handoff.js";
+// ─── Context Handoff — A-CTX-2 ───────────────────────────────────────────────
+export { HANDOFF_SCHEMA_VERSION } from "./context-handoff.js";
+export { MISSION_SCHEMA_VERSION, MISSION_STATUSES, ALLOWED_MISSION_TRANSITIONS, createMissionRecord, isMissionTransitionAllowed } from './mission.js';

package/dist/vendor/contracts/mission.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Mission Governance contracts — C2
+ *
+ * A MissionRecord governs one software mission: intent → budget → runs →
+ * verification → decision → receipt. It never replaces LoopRecord; it
+ * aggregates above it.
+ *
+ * Invariants:
+ *   - One accountable human owner per mission.
+ *   - State transitions are append-only in the ledger.
+ *   - Ledger is the authority; mission.json is a rebuildable cache.
+ *   - A mission cannot become "verified" without verified run evidence.
+ *   - A mission cannot become "shipped" without an explicit ship decision.
+ *   - Unknown schema versions fail closed.
+ *   - Budgets cannot be raised silently.
+ */
+export declare const MISSION_SCHEMA_VERSION: "martin.mission.v1";
+export declare const MISSION_STATUSES: readonly ["planned", "running", "blocked", "verified", "shipped", "rolled_back", "killed"];
+export type MissionStatus = (typeof MISSION_STATUSES)[number];
+export declare const ALLOWED_MISSION_TRANSITIONS: Record<MissionStatus, readonly MissionStatus[]>;
+export type MissionDecision = "ship" | "retry" | "rollback" | "kill";
+export interface MissionBudget {
+    maxUsd: number;
+    maxTokens: number;
+    maxRuns: number;
+    maxConcurrentRuns: number;
+}
+export interface MissionCost {
+    /** Sum of actualUsd across all linked runs. */
+    totalActualUsd: number;
+    /** Number of linked runs with status "completed" (verified outcome). */
+    verifiedOutcomeCount: number;
+    /** Number of linked runs regardless of outcome. */
+    totalRunCount: number;
+}
+export type MissionRunRole = "primary" | "experiment" | "validation";
+export interface MissionRunLink {
+    loopId: string;
+    role: MissionRunRole;
+    attachedAt: string;
+    /** Set to true when the linked run completed with verification passed. */
+    verifiedOutcome?: boolean;
+    /** Actual cost of this run in USD. */
+    actualUsd?: number;
+}
+export interface MissionApproval {
+    approvalId: string;
+    kind: "ship" | "budget_increase" | "scope_change";
+    decision: "approved" | "denied";
+    approvedBy: string;
+    approvedAt: string;
+    note?: string;
+}
+export interface MissionOutcome {
+    decision: MissionDecision;
+    decidedAt: string;
+    decidedBy: string;
+    note?: string;
+}
+export type MissionEventKind = "mission.created" | "mission.status_changed" | "mission.run_attached" | "mission.run_verified" | "mission.approved" | "mission.closed" | "mission.collision_blocked";
+export interface MissionEvent {
+    eventId: string;
+    kind: MissionEventKind;
+    missionId: string;
+    timestamp: string;
+    payload: Record<string, unknown>;
+}
+export interface MissionRecord {
+    schemaVersion: typeof MISSION_SCHEMA_VERSION;
+    missionId: string;
+    /** Monotonically increasing write counter. Used for CAS enforcement. */
+    revision: number;
+    title: string;
+    objective: string;
+    ownerId: string;
+    workspaceId: string;
+    projectId: string;
+    status: MissionStatus;
+    budget: MissionBudget;
+    cost: MissionCost;
+    runLinks: MissionRunLink[];
+    approvals: MissionApproval[];
+    outcome?: MissionOutcome;
+    acceptanceCriteria: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MissionDraft {
+    missionId?: string;
+    title: string;
+    objective: string;
+    ownerId: string;
+    workspaceId: string;
+    projectId: string;
+    budget: MissionBudget;
+    acceptanceCriteria?: string[];
+}
+export declare function createMissionRecord(draft: MissionDraft, options?: {
+    now?: () => string;
+    idFactory?: (prefix: string) => string;
+}): MissionRecord;
+export declare function isMissionTransitionAllowed(from: MissionStatus, to: MissionStatus): boolean;

package/dist/vendor/contracts/mission.js

@@ -0,0 +1,64 @@
+/**
+ * Mission Governance contracts — C2
+ *
+ * A MissionRecord governs one software mission: intent → budget → runs →
+ * verification → decision → receipt. It never replaces LoopRecord; it
+ * aggregates above it.
+ *
+ * Invariants:
+ *   - One accountable human owner per mission.
+ *   - State transitions are append-only in the ledger.
+ *   - Ledger is the authority; mission.json is a rebuildable cache.
+ *   - A mission cannot become "verified" without verified run evidence.
+ *   - A mission cannot become "shipped" without an explicit ship decision.
+ *   - Unknown schema versions fail closed.
+ *   - Budgets cannot be raised silently.
+ */
+export const MISSION_SCHEMA_VERSION = "martin.mission.v1";
+// ─── Status and transitions ───────────────────────────────────────────────────
+export const MISSION_STATUSES = [
+    "planned",
+    "running",
+    "blocked",
+    "verified",
+    "shipped",
+    "rolled_back",
+    "killed"
+];
+export const ALLOWED_MISSION_TRANSITIONS = {
+    planned: ["running", "killed"],
+    running: ["blocked", "verified", "rolled_back", "killed"],
+    blocked: ["running", "rolled_back", "killed"],
+    verified: ["shipped", "running", "rolled_back", "killed"],
+    shipped: [],
+    rolled_back: ["running", "killed"],
+    killed: []
+};
+// ─── Factory ──────────────────────────────────────────────────────────────────
+export function createMissionRecord(draft, options = {}) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const makeId = options.idFactory ?? ((prefix) => `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`);
+    const ts = now();
+    return {
+        schemaVersion: MISSION_SCHEMA_VERSION,
+        missionId: draft.missionId ?? makeId("mission"),
+        revision: 0,
+        title: draft.title,
+        objective: draft.objective,
+        ownerId: draft.ownerId,
+        workspaceId: draft.workspaceId,
+        projectId: draft.projectId,
+        status: "planned",
+        budget: { ...draft.budget },
+        cost: { totalActualUsd: 0, verifiedOutcomeCount: 0, totalRunCount: 0 },
+        runLinks: [],
+        approvals: [],
+        acceptanceCriteria: draft.acceptanceCriteria ?? [],
+        createdAt: ts,
+        updatedAt: ts
+    };
+}
+// ─── Transition guard ─────────────────────────────────────────────────────────
+export function isMissionTransitionAllowed(from, to) {
+    return ALLOWED_MISSION_TRANSITIONS[from].includes(to);
+}

package/dist/vendor/contracts/operator.d.ts

@@ -1,8 +1,9 @@
-export declare const MARTIN_ERROR_CATEGORIES: readonly ["invalid_input", "environment", "auth", "not_found", "store_unreadable", "verification_failed", "policy_blocked", "budget_exit", "transient"];
+export declare const MARTIN_ERROR_CATEGORIES: readonly ["invalid_input", "environment", "auth", "not_found", "store_unreadable", "verification_failed", "policy_blocked", "budget_exit", "transient", "install_failed"];
 export type MartinErrorCategory = (typeof MARTIN_ERROR_CATEGORIES)[number];
 export type MartinOutputMode = "human" | "json" | "quiet";
 export interface MartinRunSelector {
     runsDir?: string;
+    workspaceId?: string;
     file?: string;
     loopId?: string;
     latest?: boolean;
@@ -10,6 +11,7 @@ export interface MartinRunSelector {
 }
 export interface MartinRunListFilters {
     runsDir?: string;
+    workspaceId?: string;
     limit?: number;
     status?: string;
     lifecycleState?: string;

package/dist/vendor/contracts/operator.js

@@ -7,5 +7,6 @@ export const MARTIN_ERROR_CATEGORIES = [
     "verification_failed",
     "policy_blocked",
     "budget_exit",
-    "transient"
+    "transient",
+    "install_failed"
 ];

package/dist/vendor/contracts/verified-handoff.d.ts

@@ -0,0 +1,100 @@
+import type { CostProvenance, LoopLifecycleState, LoopStatus, ReceiptIntegritySummary } from "./index.js";
+export declare const VERIFIED_HANDOFF_OUTCOMES: readonly ["VERIFIED", "STOPPED", "NEEDS_REVIEW"];
+export type VerifiedHandoffOutcome = (typeof VERIFIED_HANDOFF_OUTCOMES)[number];
+export declare const EVIDENCE_STATUSES: readonly ["PASSED", "FAILED", "CONTRADICTED", "NOT_RUN", "NOT_EVALUATED"];
+export type EvidenceStatus = (typeof EVIDENCE_STATUSES)[number];
+/**
+ * Granular internal/runtime state. Retained for diagnosis, policy,
+ * receipts and engineering review.
+ */
+export declare const TEST_INTEGRITY_STATUSES: readonly ["UNCHANGED", "AUTHORIZED_CHANGE", "PREVENTED", "DETECTED_AND_ROLLED_BACK", "DETECTED_NEEDS_REVIEW", "NOT_EVALUATED"];
+export type TestIntegrityStatus = (typeof TEST_INTEGRITY_STATUSES)[number];
+/**
+ * Stable public-facing verdict used by CLI, MCP, JSON/Markdown handoffs
+ * and the website. Do not make each renderer collapse states independently.
+ */
+export declare const TEST_INTEGRITY_VERDICTS: readonly ["VERIFIED", "TAMPERING_DETECTED", "NOT_EVALUATED"];
+export type TestIntegrityVerdict = (typeof TEST_INTEGRITY_VERDICTS)[number];
+export interface VerifiedHandoffCheckV1 {
+    command: string;
+    status: EvidenceStatus;
+    exitCode?: number;
+    timedOut?: boolean;
+    detail?: string;
+}
+export interface VerifiedHandoffRequirementV1 {
+    requirement: string;
+    status: "PROVEN" | "FAILED" | "UNRESOLVED" | "NOT_EVALUATED";
+    evidence?: string[];
+}
+export interface VerifiedHandoffScopeV1 {
+    status: "WITHIN_SCOPE" | "VIOLATION_REJECTED" | "NEEDS_REVIEW" | "NOT_EVALUATED";
+    allowedPaths: string[];
+    deniedPaths: string[];
+    changedFiles: string[];
+    violations: string[];
+}
+export interface VerifiedHandoffTestIntegrityV1 {
+    /** Public rendering contract. */
+    verdict: TestIntegrityVerdict;
+    /** Granular runtime state for diagnosis and evidence. */
+    status: TestIntegrityStatus;
+    protectedPaths: string[];
+    changedProtectedPaths: string[];
+    findings: Array<{
+        filePath: string;
+        issue: string;
+        severity: "high" | "medium" | "low";
+        detail: string;
+    }>;
+    summary: string;
+}
+export interface VerifiedHandoffRecoveryV1 {
+    rollbackBoundaryAvailable: boolean;
+    rollbackAttempted: boolean;
+    rollbackSucceeded?: boolean;
+    isolatedRef?: string;
+    nextCommand?: string;
+    summary: string;
+}
+export interface VerifiedHandoffV1 {
+    schemaVersion: "1.0.0";
+    handoffId: string;
+    loopId: string;
+    generatedAt: string;
+    task: {
+        title: string;
+        objective: string;
+    };
+    definitionOfDone: {
+        acceptanceCriteria: string[];
+        verificationPlan: string[];
+    };
+    outcome: VerifiedHandoffOutcome;
+    sourceStatus: {
+        status: LoopStatus;
+        lifecycleState: LoopLifecycleState;
+    };
+    verification: {
+        status: EvidenceStatus;
+        summary: string;
+        checks: VerifiedHandoffCheckV1[];
+        warnings: string[];
+    };
+    requirements: VerifiedHandoffRequirementV1[];
+    scope: VerifiedHandoffScopeV1;
+    testIntegrity: VerifiedHandoffTestIntegrityV1;
+    unresolvedWork: string[];
+    stopReason?: string;
+    recovery: VerifiedHandoffRecoveryV1;
+    usage: {
+        attempts: number;
+        actualUsd: number;
+        estimatedUsd?: number;
+        tokensIn: number;
+        tokensOut: number;
+        costProvenance: CostProvenance;
+    };
+    receiptIntegrity: ReceiptIntegritySummary;
+    nextAction: string;
+}

package/dist/vendor/contracts/verified-handoff.js

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: MartinLoop contributors
+// SPDX-License-Identifier: Apache-2.0
+export const VERIFIED_HANDOFF_OUTCOMES = [
+    "VERIFIED",
+    "STOPPED",
+    "NEEDS_REVIEW",
+];
+export const EVIDENCE_STATUSES = [
+    "PASSED",
+    "FAILED",
+    "CONTRADICTED",
+    "NOT_RUN",
+    "NOT_EVALUATED",
+];
+/**
+ * Granular internal/runtime state. Retained for diagnosis, policy,
+ * receipts and engineering review.
+ */
+export const TEST_INTEGRITY_STATUSES = [
+    "UNCHANGED",
+    "AUTHORIZED_CHANGE",
+    "PREVENTED",
+    "DETECTED_AND_ROLLED_BACK",
+    "DETECTED_NEEDS_REVIEW",
+    "NOT_EVALUATED",
+];
+/**
+ * Stable public-facing verdict used by CLI, MCP, JSON/Markdown handoffs
+ * and the website. Do not make each renderer collapse states independently.
+ */
+export const TEST_INTEGRITY_VERDICTS = [
+    "VERIFIED",
+    "TAMPERING_DETECTED",
+    "NOT_EVALUATED",
+];

package/dist/vendor/core/context-chain-gate.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Context Chain Gate — C1
+ *
+ * Converts chain verification evidence into a merge-gate decision and
+ * a PR comment (Infracost-style). Two things hard-fail. Everything else
+ * is configurable or comment-only.
+ *
+ * Hard failures (always block merge):
+ *   1. no_governance_receipt — no receipt at all
+ *   2. tamper_detected       — receipt hash does not match producer run
+ *
+ * Configurable gate (team decides; default: warn only):
+ *   3. verifier_failed — unverified claims, incomplete integrity,
+ *                        missing artifacts, unresolved assumptions
+ *
+ * Comment-only (never block, always visible):
+ *   - Cost: actual vs budget — money is already spent, blocking adds friction
+ *   - Chain lineage: chainId, producerRunId, consumerRunId
+ *   - Integrity state
+ *
+ * Standing rules:
+ *   - Pure functions, no side effects.
+ *   - evaluateChainGate never reads environment variables or config files.
+ *   - renderGatePrComment produces valid GitHub-flavored markdown.
+ *   - No fake data, no placeholder behaviour.
+ */
+import type { ContextHandoffReceipt } from "../contracts/index.js";
+import type { ChainIntegrityState, ContextHandoffVerification } from "../contracts/index.js";
+export interface ChainGateConfig {
+    /**
+     * When true, a failed verifier (unverified claims, incomplete integrity,
+     * missing artifacts, unresolved assumptions) blocks the merge.
+     * Default: false — warn in PR comment, do not block.
+     */
+    blockOnVerifierFailure: boolean;
+}
+export interface ChainGateCost {
+    actualUsd: number;
+    budgetUsd: number;
+}
+export interface ChainGateInput {
+    /** null means no receipt was provided — triggers the hard no_governance_receipt failure. */
+    receipt: ContextHandoffReceipt | null;
+    /** null when receipt is null. Must be provided when receipt is non-null. */
+    verification: ContextHandoffVerification | null;
+    cost?: ChainGateCost;
+    config?: Partial<ChainGateConfig>;
+}
+export type ChainGateConclusion = "failure" | "neutral" | "success";
+export interface ChainGateResult {
+    noGovernance: boolean;
+    tamperDetected: boolean;
+    verifierFailed: boolean;
+    shouldBlock: boolean;
+    conclusion: ChainGateConclusion;
+    failureReasonCode?: string;
+    failureMessage?: string;
+    cost?: ChainGateCost & {
+        exceeded: boolean;
+    };
+    integrity: ChainIntegrityState | "absent";
+}
+/**
+ * Evaluates whether the chain gate should block merge, and assembles
+ * the data needed for the PR comment.
+ *
+ * Call order:
+ *   1. Check for missing receipt (hard fail).
+ *   2. Check for tamper_detected integrity (hard fail).
+ *   3. Check verifier result against config (configurable gate).
+ *   4. Return success / neutral with full comment data.
+ */
+export declare function evaluateChainGate(input: ChainGateInput): ChainGateResult;
+export interface GatePrCommentOptions {
+    runId?: string;
+    chainId?: string;
+    handoffId?: string;
+    producerRunId?: string;
+    prNumber?: number;
+    headSha?: string;
+}
+/**
+ * Renders an Infracost-style GitHub PR comment summarising the gate result.
+ *
+ * Hard failures and cost overruns are shown prominently.
+ * Cost is always present when provided — never omitted, never a blocking signal.
+ * Lineage fields (chainId, producerRunId, runId) provide audit trail links.
+ */
+export declare function renderGatePrComment(result: ChainGateResult, options?: GatePrCommentOptions): string;

package/dist/vendor/core/context-chain-gate.js

@@ -0,0 +1,173 @@
+/**
+ * Context Chain Gate — C1
+ *
+ * Converts chain verification evidence into a merge-gate decision and
+ * a PR comment (Infracost-style). Two things hard-fail. Everything else
+ * is configurable or comment-only.
+ *
+ * Hard failures (always block merge):
+ *   1. no_governance_receipt — no receipt at all
+ *   2. tamper_detected       — receipt hash does not match producer run
+ *
+ * Configurable gate (team decides; default: warn only):
+ *   3. verifier_failed — unverified claims, incomplete integrity,
+ *                        missing artifacts, unresolved assumptions
+ *
+ * Comment-only (never block, always visible):
+ *   - Cost: actual vs budget — money is already spent, blocking adds friction
+ *   - Chain lineage: chainId, producerRunId, consumerRunId
+ *   - Integrity state
+ *
+ * Standing rules:
+ *   - Pure functions, no side effects.
+ *   - evaluateChainGate never reads environment variables or config files.
+ *   - renderGatePrComment produces valid GitHub-flavored markdown.
+ *   - No fake data, no placeholder behaviour.
+ */
+const DEFAULT_CONFIG = {
+    blockOnVerifierFailure: false
+};
+// ─── Gate evaluation ─────────────────────────────────────────────────────────
+/**
+ * Evaluates whether the chain gate should block merge, and assembles
+ * the data needed for the PR comment.
+ *
+ * Call order:
+ *   1. Check for missing receipt (hard fail).
+ *   2. Check for tamper_detected integrity (hard fail).
+ *   3. Check verifier result against config (configurable gate).
+ *   4. Return success / neutral with full comment data.
+ */
+export function evaluateChainGate(input) {
+    const config = { ...DEFAULT_CONFIG, ...input.config };
+    const costResult = input.cost !== undefined
+        ? { ...input.cost, exceeded: input.cost.actualUsd > input.cost.budgetUsd }
+        : undefined;
+    // ── Hard fail 1: no governance receipt ───────────────────────────────────
+    if (input.receipt === null || input.verification === null) {
+        return {
+            noGovernance: true,
+            tamperDetected: false,
+            verifierFailed: false,
+            shouldBlock: true,
+            conclusion: "failure",
+            failureReasonCode: "no_governance_receipt",
+            failureMessage: "No MartinLoop governance receipt was found for this run. " +
+                "Every AI-authored PR must carry a verified governance receipt.",
+            integrity: "absent",
+            ...(costResult !== undefined ? { cost: costResult } : {})
+        };
+    }
+    const integrity = input.verification.integrity;
+    // ── Hard fail 2: tampered receipt ─────────────────────────────────────────
+    if (integrity === "tamper_detected") {
+        return {
+            noGovernance: false,
+            tamperDetected: true,
+            verifierFailed: false,
+            shouldBlock: true,
+            conclusion: "failure",
+            failureReasonCode: "tamper_detected",
+            failureMessage: "Governance receipt integrity check failed: tamper detected. " +
+                "The receipt hash does not match the producer run record.",
+            integrity,
+            ...(costResult !== undefined ? { cost: costResult } : {})
+        };
+    }
+    // ── Configurable gate: verifier failed ───────────────────────────────────
+    const verifierFailed = !input.verification.ok;
+    const blockOnVerifier = verifierFailed && config.blockOnVerifierFailure;
+    if (blockOnVerifier) {
+        const first = input.verification.reasons[0];
+        return {
+            noGovernance: false,
+            tamperDetected: false,
+            verifierFailed: true,
+            shouldBlock: true,
+            conclusion: "failure",
+            failureReasonCode: first?.code ?? "verifier_failed",
+            failureMessage: first?.message ?? "Context chain verification failed.",
+            integrity,
+            ...(costResult !== undefined ? { cost: costResult } : {})
+        };
+    }
+    // ── Pass (or warn-only verifier failure) ──────────────────────────────────
+    return {
+        noGovernance: false,
+        tamperDetected: false,
+        verifierFailed,
+        shouldBlock: false,
+        conclusion: verifierFailed ? "neutral" : "success",
+        integrity,
+        ...(costResult !== undefined ? { cost: costResult } : {})
+    };
+}
+/**
+ * Renders an Infracost-style GitHub PR comment summarising the gate result.
+ *
+ * Hard failures and cost overruns are shown prominently.
+ * Cost is always present when provided — never omitted, never a blocking signal.
+ * Lineage fields (chainId, producerRunId, runId) provide audit trail links.
+ */
+export function renderGatePrComment(result, options = {}) {
+    const lines = [];
+    lines.push("## MartinLoop Governance");
+    lines.push("");
+    // Status headline
+    if (result.noGovernance) {
+        lines.push("🚫 **No governance receipt** — merge is blocked.");
+    }
+    else if (result.tamperDetected) {
+        lines.push("🚫 **Tampered receipt** — merge is blocked.");
+    }
+    else if (result.verifierFailed && result.shouldBlock) {
+        lines.push("⚠️ **Verifier failed** — merge is blocked (configured as required).");
+    }
+    else if (result.verifierFailed) {
+        lines.push("⚠️ **Verifier warnings** — merge is permitted, review recommended.");
+    }
+    else {
+        lines.push("✅ **Governance verified** — chain integrity confirmed.");
+    }
+    lines.push("");
+    lines.push("| Signal | Value | Status |");
+    lines.push("|--------|-------|--------|");
+    // Chain integrity
+    const integrityIcon = result.integrity === "verified"
+        ? "✅"
+        : result.integrity === "absent" || result.integrity === "tamper_detected"
+            ? "🚫"
+            : "⚠️";
+    lines.push(`| Chain integrity | \`${result.integrity}\` | ${integrityIcon} |`);
+    // Cost — always comment-only, never a block signal
+    if (result.cost !== undefined) {
+        const { actualUsd, budgetUsd, exceeded } = result.cost;
+        const costIcon = exceeded ? "⚠️" : "✅";
+        const delta = actualUsd - budgetUsd;
+        const costNote = exceeded
+            ? `over budget (+$${delta.toFixed(4)})`
+            : "within budget";
+        lines.push(`| Cost | \`$${actualUsd.toFixed(4)}\` / \`$${budgetUsd.toFixed(4)}\` | ${costIcon} ${costNote} |`);
+    }
+    // Lineage (audit trail, never a block signal)
+    if (options.chainId) {
+        lines.push(`| Chain ID | \`${options.chainId}\` | ℹ️ |`);
+    }
+    if (options.handoffId) {
+        lines.push(`| Handoff ID | \`${options.handoffId}\` | ℹ️ |`);
+    }
+    if (options.producerRunId) {
+        lines.push(`| Producer run | \`${options.producerRunId}\` | ℹ️ |`);
+    }
+    if (options.runId) {
+        lines.push(`| Consumer run | \`${options.runId}\` | ℹ️ |`);
+    }
+    // Failure detail
+    if (result.failureMessage) {
+        lines.push("");
+        lines.push(`> **Failure:** ${result.failureMessage}`);
+    }
+    lines.push("");
+    lines.push("_Powered by [MartinLoop](https://github.com/Keesan12/martin-loop) governance gate_");
+    return lines.join("\n");
+}