@martinloop/mcp 0.3.3 → 0.3.5

package/dist/resources.js

@@ -5,6 +5,7 @@ import { martinDoctorTool } from "./tools/doctor.js";
 import { martinTriageRunsTool } from "./tools/triage-runs.js";
 import { martinRunDossierTool } from "./tools/run-dossier.js";
 import { inspectRepoSignals, buildPolicyPackDefinition, buildRepoRiskMap } from "./tools/workflow-governance.js";
+import { readWorkflowState } from "./workflow-state.js";
 import { buildAttemptSnapshot, buildPersistedLoopPreview, buildVerificationHistorySnapshot, parseAttemptIndex, resolveMartinDiscoveryContext, toPrettyJson } from "./discovery-support.js";
 import { loadDetailedLoopRecord, readLedgerEvents } from "./tools/run-store.js";
 import { invalidArgumentsError, MartinToolError } from "./tools/tool-errors.js";
@@ -27,7 +28,8 @@ export const MARTIN_STATIC_RESOURCE_URIS = {
     commandMapGuide: "martin://guides/command-map",
     ideOnboardingGuide: "martin://guides/ide-onboarding",
     operatingRulesGuide: "martin://guides/operating-rules",
-    publishReadinessGuide: "martin://guides/publish-readiness"
+    publishReadinessGuide: "martin://guides/publish-readiness",
+    governanceStatus: "martin://agent/governance-status"
 };
 export const MARTIN_RESOURCE_TEMPLATES = [
     {
@@ -188,6 +190,13 @@ export const MARTIN_STATIC_RESOURCES = [
         title: "Martin Publish Readiness Guide",
         description: "Checklist-oriented guide for MCP publish readiness reviews.",
         mimeType: "text/markdown"
+    },
+    {
+        uri: MARTIN_STATIC_RESOURCE_URIS.governanceStatus,
+        name: "martin_governance_status",
+        title: "Martin Governance Status",
+        description: "Proactive governance status: whether work is governed, budget remaining, unreceipted runs, and recommended next action. Read this before starting agent work.",
+        mimeType: "application/json"
     }
 ];
 export function listMartinResources() {
@@ -237,6 +246,8 @@ export async function readMartinResource(input) {
             return jsonResource(input.uri, withDiscoveryMetadata(buildRepoRiskMap(inspectRepoSignals(context.workingDirectory)), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.verifierResults:
             return jsonResource(input.uri, withDiscoveryMetadata(await buildLatestVerifierEvidenceResource(context.runsRoot), context.runsRoot));
+        case MARTIN_STATIC_RESOURCE_URIS.governanceStatus:
+            return jsonResource(input.uri, withDiscoveryMetadata(await buildGovernanceStatusResource(context.runsRoot, context.workingDirectory), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.agentNextStep:
             return jsonResource(input.uri, withDiscoveryMetadata(await buildAgentNextStepResource(context.runsRoot), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.mcpUsageGuide:
@@ -565,6 +576,57 @@ function compactEmptyState(kind, runsRoot, warnings) {
         warnings
     };
 }
+async function buildGovernanceStatusResource(runsRoot, workingDirectory) {
+    const state = await readWorkflowState(runsRoot);
+    const mcpState = state.mcp ?? {};
+    const hasDoctor = Boolean(mcpState.doctor);
+    const hasPlan = Boolean(mcpState.plan);
+    const hasPreflight = Boolean(mcpState.preflight);
+    const governed = hasDoctor && hasPlan && hasPreflight;
+    const latest = await loadLatestRunForCompactResource(runsRoot);
+    const budgetRemaining = (!latest.empty && latest.detail)
+        ? buildPersistedLoopPreview(latest.detail.loop).remainingBudgetUsd
+        : null;
+    let unreceiptedRuns = 0;
+    try {
+        const inspection = await inspectLoopTool({ runsDir: runsRoot });
+        const total = inspection.loopCount ?? 0;
+        const completed = (inspection.statusBreakdown?.completed ?? 0) + (inspection.statusBreakdown?.failed ?? 0);
+        unreceiptedRuns = Math.max(0, total - completed);
+    }
+    catch {
+        // No runs yet
+    }
+    const missingSteps = [];
+    if (!hasDoctor)
+        missingSteps.push("martin_doctor");
+    if (!hasPlan)
+        missingSteps.push("martin_plan");
+    if (!hasPreflight)
+        missingSteps.push("martin_preflight");
+    const recommendedAction = !hasDoctor
+        ? "Run martin_doctor to confirm environment before any work."
+        : !hasPlan
+            ? "Run martin_plan with your objective to scope the task."
+            : !hasPreflight
+                ? "Run martin_preflight to validate the run contract before execution."
+                : "Governance complete. You may proceed with martin_run.";
+    return {
+        kind: "governance-status",
+        governed,
+        workflowReceipts: {
+            doctor: hasDoctor ? { recordedAt: mcpState.doctor.recordedAt } : null,
+            plan: hasPlan ? { recordedAt: mcpState.plan.recordedAt } : null,
+            preflight: hasPreflight ? { recordedAt: mcpState.preflight.recordedAt } : null
+        },
+        missingSteps,
+        budgetRemaining,
+        unreceiptedRuns,
+        recommendedAction,
+        requiredSequence: ["martin_doctor", "martin_plan", "martin_preflight", "martin_run", "martin_dossier"],
+        warning: governed ? undefined : "This session is NOT governed. Complete the required sequence before making changes."
+    };
+}
 function buildCurrentPoliciesResource(workingDirectory) {
     const signals = inspectRepoSignals(workingDirectory);
     const recommended = buildPolicyPackDefinition(undefined, signals);
@@ -626,173 +688,173 @@ function inferAgentNextStep(loop, verification) {
 }
 function buildMcpUsageGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin Loop MCP Usage
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Martin Loop exposes governed coding workflows over MCP. Use the server health and run-store views to decide when to preflight, execute, inspect, or escalate.
-
-## Recommended Flow
-
-1. Read \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` or call \`martin_doctor\` to confirm the environment and run-store visibility.
-2. Use the \`martin_governed_coding_kickoff\` prompt to frame a governed coding request.
-3. Call \`martin_preflight\` before \`martin_run\` when the task or safety envelope is non-trivial.
-4. After execution, inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`martin://runs/{loopId}\`, and \`martin://runs/{loopId}/verification\`.
-5. For low-context agents, read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, or \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\` before asking for full JSON.
-6. Read \`${MARTIN_STATIC_RESOURCE_URIS.triage}\` or call \`martin_triage_runs\` to prioritize which run needs attention first.
-7. Use \`martin_debug_failed_run\` when a loop exits failed, budget-bound, or escalated.
-
-## Current Martin MCP Surface
-
-- Tools: \`martin_run\`, \`martin_inspect\`, \`martin_status\`, \`martin_doctor\`, \`martin_preflight\`, \`martin_list_runs\`, \`martin_triage_runs\`, \`martin_get_run\`, \`martin_get_attempt\`, \`martin_get_verification_results\`, \`martin_run_dossier\`
-- Static resources: \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\`, \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`${MARTIN_STATIC_RESOURCE_URIS.triage}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestBudgetStatus}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestVerifierEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestRollbackEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.mcpUsageGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.publishReadinessGuide}\`
-- Resource templates: \`martin://runs/{loopId}\`, \`martin://runs/{loopId}/attempts/{attemptIndex}\`, \`martin://runs/{loopId}/verification\`
-- Prompts: \`martin_start\`, \`martin_preflight\`, \`martin_triage\`, \`martin_resume\`, \`martin_prove\`, \`martin_release_check\`, \`martin_governed_coding_kickoff\`, \`martin_debug_failed_run\`, \`martin_publish_readiness_review\`, \`martin_triage_run_store\`
-
-## Notes
-
-- Discovery helpers read the existing Martin run-store; they do not create new schema.
-- Verification history is derived from persisted \`verification.completed\` evidence in loop records and ledgers.
-- Attempt inspection stays aligned with the same loop selectors used by \`martin_status\` and \`martin_inspect\`.
+    return `# Martin Loop MCP Usage
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Martin Loop exposes governed coding workflows over MCP. Use the server health and run-store views to decide when to preflight, execute, inspect, or escalate.
+
+## Recommended Flow
+
+1. Read \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` or call \`martin_doctor\` to confirm the environment and run-store visibility.
+2. Use the \`martin_governed_coding_kickoff\` prompt to frame a governed coding request.
+3. Call \`martin_preflight\` before \`martin_run\` when the task or safety envelope is non-trivial.
+4. After execution, inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`martin://runs/{loopId}\`, and \`martin://runs/{loopId}/verification\`.
+5. For low-context agents, read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, or \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\` before asking for full JSON.
+6. Read \`${MARTIN_STATIC_RESOURCE_URIS.triage}\` or call \`martin_triage_runs\` to prioritize which run needs attention first.
+7. Use \`martin_debug_failed_run\` when a loop exits failed, budget-bound, or escalated.
+
+## Current Martin MCP Surface
+
+- Tools: \`martin_run\`, \`martin_inspect\`, \`martin_status\`, \`martin_doctor\`, \`martin_preflight\`, \`martin_list_runs\`, \`martin_triage_runs\`, \`martin_get_run\`, \`martin_get_attempt\`, \`martin_get_verification_results\`, \`martin_run_dossier\`
+- Static resources: \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\`, \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`${MARTIN_STATIC_RESOURCE_URIS.triage}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestBudgetStatus}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestVerifierEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestRollbackEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.mcpUsageGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.publishReadinessGuide}\`
+- Resource templates: \`martin://runs/{loopId}\`, \`martin://runs/{loopId}/attempts/{attemptIndex}\`, \`martin://runs/{loopId}/verification\`
+- Prompts: \`martin_start\`, \`martin_preflight\`, \`martin_triage\`, \`martin_resume\`, \`martin_prove\`, \`martin_release_check\`, \`martin_governed_coding_kickoff\`, \`martin_debug_failed_run\`, \`martin_publish_readiness_review\`, \`martin_triage_run_store\`
+
+## Notes
+
+- Discovery helpers read the existing Martin run-store; they do not create new schema.
+- Verification history is derived from persisted \`verification.completed\` evidence in loop records and ledgers.
+- Attempt inspection stays aligned with the same loop selectors used by \`martin_status\` and \`martin_inspect\`.
 `;
 }
 function buildAgentStartGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Agent Start Here
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use Martin Loop as the local governor before you spend agent tokens or retry a failed coding loop.
-
-## Cheap Default Flow
-
-1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\` first. It is the smallest "what should I do now?" payload.
-2. If no runs exist, call \`martin_doctor\`, then \`martin_preflight\`.
-3. If a run exists, read \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\` before reading full run JSON.
-4. If the verifier failed, use prompt \`martin_debug_failed_run\` or \`martin_triage\`.
-5. If you need a shareable receipt, read \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`.
-
-## Install Profiles
-
-- \`minimal\` (default): doctor, preflight, list, triage, dossier. Good for low tool bloat.
-- \`diagnostic\`: read-only inspection tools for debugging without execution.
-- \`full-local\`: all local tools, including \`martin_run\`.
-- \`github-review\`: review-oriented local profile for PR drafting and reviewer evidence.
-- \`starter\` and \`full\`: compatibility aliases.
-
-## Copy-Paste Agent Rule
-
-Before running or retrying an autonomous coding task, call Martin. Prefer compact resources first, then full dossiers only when the compact receipt says more evidence is needed. Never claim success unless Martin shows verifier-backed completion or a clear blocked reason.
+    return `# Agent Start Here
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use Martin Loop as the local governor before you spend agent tokens or retry a failed coding loop.
+
+## Cheap Default Flow
+
+1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\` first. It is the smallest "what should I do now?" payload.
+2. If no runs exist, call \`martin_doctor\`, then \`martin_preflight\`.
+3. If a run exists, read \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\` before reading full run JSON.
+4. If the verifier failed, use prompt \`martin_debug_failed_run\` or \`martin_triage\`.
+5. If you need a shareable receipt, read \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`.
+
+## Install Profiles
+
+- \`minimal\` (default): doctor, preflight, list, triage, dossier. Good for low tool bloat.
+- \`diagnostic\`: read-only inspection tools for debugging without execution.
+- \`full-local\`: all local tools, including \`martin_run\`.
+- \`github-review\`: review-oriented local profile for PR drafting and reviewer evidence.
+- \`starter\` and \`full\`: compatibility aliases.
+
+## Copy-Paste Agent Rule
+
+Before running or retrying an autonomous coding task, call Martin. Prefer compact resources first, then full dossiers only when the compact receipt says more evidence is needed. Never claim success unless Martin shows verifier-backed completion or a clear blocked reason.
 `;
 }
 function buildCommandMapGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin Command Map
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use this guide when an IDE or agent needs to know which Martin surface to call next.
-
-## Default Governed Sequence
-
-1. \`martin_doctor\` — confirm environment and visibility.
-2. \`martin_plan\` — propose the bounded approach without spending a run.
-3. \`martin_preflight\` — turn the plan into an explicit contract.
-4. \`martin_run\` — execute only after the contract is safe.
-5. \`martin_dossier\` — inspect what happened and what Martin prevented.
-6. \`martin_eval\` — convert the result into review posture when needed.
-
-## When To Use Which Surface
-
-- Need the smallest next action: \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`
-- Need a quick receipt: \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`
-- Need a shareable proof object: \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`
-- Need a full run review: \`martin_dossier\`
-- Need to decide whether to retry: \`martin_triage_runs\`
-- Need IDE setup guidance: \`${MARTIN_STATIC_RESOURCE_URIS.ideOnboardingGuide}\`
+    return `# Martin Command Map
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use this guide when an IDE or agent needs to know which Martin surface to call next.
+
+## Default Governed Sequence
+
+1. \`martin_doctor\` — confirm environment and visibility.
+2. \`martin_plan\` — propose the bounded approach without spending a run.
+3. \`martin_preflight\` — turn the plan into an explicit contract.
+4. \`martin_run\` — execute only after the contract is safe.
+5. \`martin_dossier\` — inspect what happened and what Martin prevented.
+6. \`martin_eval\` — convert the result into review posture when needed.
+
+## When To Use Which Surface
+
+- Need the smallest next action: \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`
+- Need a quick receipt: \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`
+- Need a shareable proof object: \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`
+- Need a full run review: \`martin_dossier\`
+- Need to decide whether to retry: \`martin_triage_runs\`
+- Need IDE setup guidance: \`${MARTIN_STATIC_RESOURCE_URIS.ideOnboardingGuide}\`
 `;
 }
 function buildIdeOnboardingGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin IDE Onboarding
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use this guide after the MCP server is installed so the host naturally uses MartinLoop during real work.
-
-## IDE Default Flow
-
-1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`
-2. Read \`${MARTIN_STATIC_RESOURCE_URIS.operatingRulesGuide}\`
-3. Use prompt \`martin_start\` or \`martin_governed_coding_kickoff\`
-4. Call \`martin_doctor\`
-5. Call \`martin_plan\`
-6. Call \`martin_preflight\`
-7. Only then call \`martin_run\`
-
-## Goal
-
-MartinLoop should become the normal path for coding work in the host, not a manual extra step the human has to remember.
+    return `# Martin IDE Onboarding
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use this guide after the MCP server is installed so the host naturally uses MartinLoop during real work.
+
+## IDE Default Flow
+
+1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`
+2. Read \`${MARTIN_STATIC_RESOURCE_URIS.operatingRulesGuide}\`
+3. Use prompt \`martin_start\` or \`martin_governed_coding_kickoff\`
+4. Call \`martin_doctor\`
+5. Call \`martin_plan\`
+6. Call \`martin_preflight\`
+7. Only then call \`martin_run\`
+
+## Goal
+
+MartinLoop should become the normal path for coding work in the host, not a manual extra step the human has to remember.
 `;
 }
 function buildOperatingRulesGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin Operating Rules
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use these rules inside the IDE or MCP host as the default MartinLoop operating posture.
-
-## Required Sequence Before Real Work
-
-1. \`martin_doctor\`
-2. \`martin_plan\`
-3. \`martin_preflight\`
-4. \`martin_run\`
-5. \`martin_dossier\`
-
-## Enforcement Rule
-
-Do not execute real coding work through MartinLoop until doctor and preflight have both been used for the current task.
-
-## Completion Rule
-
-Do not claim success until MartinLoop shows verifier-backed completion or an explicit blocked reason backed by evidence.
+    return `# Martin Operating Rules
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use these rules inside the IDE or MCP host as the default MartinLoop operating posture.
+
+## Required Sequence Before Real Work
+
+1. \`martin_doctor\`
+2. \`martin_plan\`
+3. \`martin_preflight\`
+4. \`martin_run\`
+5. \`martin_dossier\`
+
+## Enforcement Rule
+
+Do not execute real coding work through MartinLoop until doctor and preflight have both been used for the current task.
+
+## Completion Rule
+
+Do not claim success until MartinLoop shows verifier-backed completion or an explicit blocked reason backed by evidence.
 `;
 }
 function buildPublishReadinessGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin MCP Publish Readiness
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use this guide when reviewing whether the public MCP package is ready to publish, promote, or hand off for registry submission.
-
-## Review Areas
-
-1. Environment health: confirm \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` shows a sane working directory, runs root, and engine availability for the target mode.
-2. Discovery surface: verify tools, prompts, static resources, and resource templates are all discoverable and named consistently.
-3. Run evidence: inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\` and, when relevant, \`martin://runs/{loopId}/verification\` to confirm verification outcomes are explainable from persisted data.
-4. Packaging lane: run the MCP package test, build, and smoke-pack commands before calling the package publish-ready.
-5. Findings-first reporting: call out missing schema, integration gaps, triage-critical runs, and verification blockers before summarizing strengths.
-
-## Evidence Expectations
-
-- Prefer concrete run IDs, attempt indices, and verification summaries over vague statements.
-- Distinguish local package validation from live registry readiness.
-- If a discovery helper exists but is not yet wired into the server, report that as an integration gap instead of treating the capability as fully shipped.
+    return `# Martin MCP Publish Readiness
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use this guide when reviewing whether the public MCP package is ready to publish, promote, or hand off for registry submission.
+
+## Review Areas
+
+1. Environment health: confirm \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` shows a sane working directory, runs root, and engine availability for the target mode.
+2. Discovery surface: verify tools, prompts, static resources, and resource templates are all discoverable and named consistently.
+3. Run evidence: inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\` and, when relevant, \`martin://runs/{loopId}/verification\` to confirm verification outcomes are explainable from persisted data.
+4. Packaging lane: run the MCP package test, build, and smoke-pack commands before calling the package publish-ready.
+5. Findings-first reporting: call out missing schema, integration gaps, triage-critical runs, and verification blockers before summarizing strengths.
+
+## Evidence Expectations
+
+- Prefer concrete run IDs, attempt indices, and verification summaries over vague statements.
+- Distinguish local package validation from live registry readiness.
+- If a discovery helper exists but is not yet wired into the server, report that as an integration gap instead of treating the capability as fully shipped.
 `;
 }
 function withDiscoveryMetadata(value, runsRoot) {

package/dist/server-validation.js

@@ -148,6 +148,7 @@ function validateRunInput(args) {
         "maxUsd",
         "maxIterations",
         "maxTokens",
+        "verifyTimeoutMs",
         "maxMinutes",
         "maxFilesChanged",
         "maxCommands",
@@ -176,6 +177,7 @@ function validateRunInput(args) {
         ...optionalPositiveNumber(record.maxUsd, "maxUsd"),
         ...optionalPositiveInteger(record.maxIterations, "maxIterations"),
         ...optionalPositiveInteger(record.maxTokens, "maxTokens"),
+        ...optionalPositiveInteger(record.verifyTimeoutMs, "verifyTimeoutMs"),
         ...optionalPositiveInteger(record.maxMinutes, "maxMinutes"),
         ...optionalPositiveInteger(record.maxFilesChanged, "maxFilesChanged"),
         ...optionalPositiveInteger(record.maxCommands, "maxCommands"),

package/dist/server.js

@@ -43,6 +43,7 @@ import { createRunControlReceipt } from "./tools/run-controls.js";
 import { martinTriageRunsTool } from "./tools/triage-runs.js";
 import { runLoopTool } from "./tools/run-loop.js";
 import { MARTIN_ENGINE_VALUES } from "./tools/tool-support.js";
+import { classifyRoute } from "./vendor/core/index.js";
 import { createToolErrorResult, createToolSuccessResult } from "./tools/tool-response.js";
 import { MartinToolError, toToolFailure } from "./tools/tool-errors.js";
 import { normalizeLoopBudget } from "./tools/workflow-governance.js";
@@ -118,7 +119,7 @@ const verificationSchema = {
     type: "object",
     additionalProperties: true,
     properties: {
-        status: { type: "string", enum: ["passed", "failed", "unavailable"] },
+        status: { type: "string", enum: ["passed", "failed", "contradicted", "not_run"] },
         eventCount: { type: "integer" },
         ledgerEventCount: { type: "integer" },
         latestAttemptIndex: { type: "integer" },
@@ -1370,6 +1371,59 @@ export function createMartinMcpServer(serverInfo) {
                     oneOf: [{ required: ["file"] }, { required: ["loopId"] }, { required: ["latest"] }]
                 },
                 outputSchema: prReviewOutputSchema
+            },
+            {
+                name: "martin_estimate",
+                description: "Estimate the cost, recommended route, and Pre Work Burn for an objective without spending anything. Use before martin_run to understand what a task will cost.",
+                annotations: {
+                    readOnlyHint: true,
+                    idempotentHint: true
+                },
+                inputSchema: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        objective: {
+                            type: "string",
+                            description: "The coding task to estimate."
+                        },
+                        engine: {
+                            type: "string",
+                            enum: [...MARTIN_ENGINE_VALUES],
+                            description: "Which agent CLI would be used. Defaults to claude."
+                        },
+                        budgetUsd: {
+                            type: "number",
+                            exclusiveMinimum: 0,
+                            description: "Budget ceiling for estimation. Defaults to 5."
+                        },
+                        fileScope: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional file paths to scope the estimate."
+                        }
+                    },
+                    required: ["objective"]
+                },
+                outputSchema: {
+                    type: "object",
+                    additionalProperties: true,
+                    properties: {
+                        objective: { type: "string" },
+                        engine: { type: "string" },
+                        budgetUsd: { type: "number" },
+                        selectedMode: { type: "string" },
+                        confidence: { type: "number" },
+                        expectedCostUsd: { type: "number" },
+                        expectedPreworkBurnPct: { type: "number" },
+                        reason: { type: "array", items: { type: "string" } },
+                        blockedSteps: { type: "array", items: { type: "string" } },
+                        compressed: { type: "boolean" },
+                        compressionSummary: { type: "string" },
+                        recommendedBudgetUsd: { type: "number" }
+                    },
+                    required: ["objective", "engine", "budgetUsd", "selectedMode", "confidence", "expectedCostUsd", "expectedPreworkBurnPct", "reason"]
+                }
             }
         ]
     }));
@@ -1580,6 +1634,38 @@ export function createMartinMcpServer(serverInfo) {
                 const output = await martinReviewPrTool(input);
                 return createToolSuccessResult(output, `PR review verdict for ${output.loopId}: ${output.verdict}.`);
             }
+            if (name === "martin_estimate") {
+                const input = args;
+                const objective = input.objective;
+                const engine = input.engine ?? "claude";
+                const budgetUsd = input.budgetUsd ?? 5;
+                const fileScope = input.fileScope ?? [];
+                const route = classifyRoute({
+                    objective,
+                    verificationPlan: [],
+                    budgetUsd,
+                    allowedPaths: fileScope,
+                    scopedFileCount: fileScope.length > 0 ? fileScope.length : undefined
+                });
+                const recommendedBudgetUsd = route.selectedMode === "direct"
+                    ? Math.max(2, Math.round(route.expectedCostUsd * 3 * 100) / 100)
+                    : Math.max(5, Math.round(route.expectedCostUsd * 2 * 100) / 100);
+                const output = {
+                    objective,
+                    engine,
+                    budgetUsd,
+                    selectedMode: route.selectedMode,
+                    confidence: route.confidence,
+                    expectedCostUsd: route.expectedCostUsd,
+                    expectedPreworkBurnPct: route.expectedPreworkBurnPct,
+                    reason: route.reason,
+                    blockedSteps: route.blockedSteps,
+                    compressed: route.compressed,
+                    ...(route.compressionSummary ? { compressionSummary: route.compressionSummary } : {}),
+                    recommendedBudgetUsd
+                };
+                return createToolSuccessResult(output, `Estimate: ${route.selectedMode} route, ~$${route.expectedCostUsd.toFixed(2)} expected cost, ${route.expectedPreworkBurnPct}% pre-work burn. Recommended budget: $${recommendedBudgetUsd.toFixed(2)}.`);
+            }
             return createToolErrorResult(toToolFailure(new Error(`Unknown tool: ${name}`)));
         }
         catch (error) {

package/dist/tools/eval.js

@@ -15,15 +15,20 @@ export async function martinEvalTool(input) {
         verifiers: detail.loop.task?.verificationPlan ?? [],
         signals
     });
+    const observationMismatch = hasObservationMismatch(detail.loop.events ?? []);
     const checks = {
         taskCompletion: detail.loop.status === "completed" ? "passed" : detail.loop.status === "exited" ? "warning" : "failed",
         verifier: verification.status === "passed"
             ? "passed"
-            : verification.status === "failed"
+            : verification.status === "failed" || verification.status === "contradicted"
                 ? "failed"
                 : "warning",
-        diffDiscipline: (detail.loop.task?.allowedPaths?.length ?? 0) > 0 ? "passed" : "warning",
-        regressionRisk: verification.status === "passed" ? "passed" : "warning",
+        diffDiscipline: observationMismatch
+            ? "failed"
+            : (detail.loop.task?.allowedPaths?.length ?? 0) > 0
+                ? "passed"
+                : "warning",
+        regressionRisk: verification.status === "passed" && !observationMismatch ? "passed" : "warning",
         securityRisk: risk.level === "high" ? "failed" : risk.level === "medium" ? "warning" : "passed",
         reviewability: detail.loop.attempts.length > 0 && (detail.loop.events?.length ?? 0) > 0 ? "passed" : "warning"
     };
@@ -35,7 +40,7 @@ export async function martinEvalTool(input) {
     score -= checks.securityRisk === "failed" ? 20 : checks.securityRisk === "warning" ? 10 : 0;
     score -= checks.reviewability === "warning" ? 8 : 0;
     score = Math.max(0, score);
-    const grade = verification.status === "unavailable"
+    const grade = verification.status === "not_run" || observationMismatch
         ? "insufficient_evidence"
         : score >= 90
             ? "mergeable"
@@ -44,7 +49,14 @@ export async function martinEvalTool(input) {
                 : score >= 55
                     ? "needs_review"
                     : "blocked";
-    const warnings = [...detail.warnings, ...verification.warnings, ...risk.reasons];
+    const warnings = [
+        ...detail.warnings,
+        ...verification.warnings,
+        ...risk.reasons,
+        ...(observationMismatch
+            ? ["Change observation mismatch: adapter-reported files differ from repo-observed files."]
+            : [])
+    ];
     return {
         source: detail.source,
         sourceKind: detail.sourceKind,
@@ -64,3 +76,15 @@ export async function martinEvalTool(input) {
                         : `Run ${detail.loop.loopId} is blocked from promotion by verification or risk gaps.`
     };
 }
+function hasObservationMismatch(events) {
+    return events.some((event) => {
+        if (event.type !== "observation.reconciled") {
+            return false;
+        }
+        const observation = isRecord(event.payload?.["observation"]) ? event.payload?.["observation"] : undefined;
+        return observation?.["status"] === "mismatch";
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/tools/execution-policy.d.ts

@@ -0,0 +1,11 @@
+import { type ExecutionPolicy } from "../vendor/contracts/index.js";
+export interface CompileMcpExecutionPolicyInput {
+    workingDirectory: string;
+    maxUsd?: number;
+    maxIterations?: number;
+    maxTokens?: number;
+    verificationPlan?: string[];
+    allowedPaths?: string[];
+    deniedPaths?: string[];
+}
+export declare function compileMcpExecutionPolicy(input: CompileMcpExecutionPolicyInput): ExecutionPolicy;