MCP and results

Your agent drives discerndiscern↗A tool that lets you hand real work to coding agents and still decide what joins your project. through the Model Context Protocol (MCP), an open standardStandard↗A measured limit your project holds, such as a maximum download size or a minimum test coverage. that lets a coding agent call a tool directly, and through the same commands on the command line. This page is the contract behind both: every tool and the inputs it accepts, the fields of each result, the exit codes, and the published schemas. Each tool's effect contract says whether it changes anything and where your approval is required, so you can see what your agent can do on its own.

A few terms recur. The gate runs your project's own commands, such as its formatter, linter, and tests, and Proof records which of them passed on one exact commit. The trunk is the project's shared branch, and a worktree is the separate copy of the project where one task happens. Checkpoints are review questions your agent answers when a change matches their trigger, grants record your permission to land changes, and a variance is your permission to land despite an unmet checkpointCheckpoint↗A review question your project asks your agent whenever a certain kind of change happens..

Tools that work on a project need a configured project, while discern_docs reads the bundled manual without one. To connect an agent, follow Connect a coding agent.

Every format describes the same operation and the same verdict.

Choose by the task and whoever reads the result: Markdown gives prioritized prose for reading and quoting, and JSON gives exact fields for selecting, validating, scripting, and lasting integrations. People and agents can use either.

Say your agent runs discern done in the recipe search worktreeWorktree↗A separate copy of your project, on its own branch, where one task's work happens. before it has committed its change. With --markdown, the refusal reads:

# `discern done`

## Current state

Completion requires a clean, committed tree — uncommitted: src/recipes.ts. No candidate was selected and no producer ran.

## Next action

Run `discern prepare`, review and commit the intended changes, then run `discern done`. For diagnostics before committing, use `discern test` or `discern done --standalone`; standalone results are transient.

With --json, shown here across several lines, the same refusal carries its exact fields:

{
  "ok": false,
  "verb": "done",
  "data": {
    "failed_stage": null,
    "scopes_changed": [],
    "gate_ran": false,
    "producer_executions": {}
  },
  "hints": [
    "Run `discern prepare`, review and commit the intended changes, then run `discern done`. For diagnostics before committing, use `discern test` or `discern done --standalone`; standalone results are transient."
  ],
  "error": "dirty_worktree",
  "message": "Completion requires a clean, committed tree — uncommitted: src/recipes.ts. No candidate was selected and no producer ran."
}

Both runs exit 1. Over MCP, your agent gets the Markdown in content and the JSON in structuredContent.

MCP carries both because hosts expose channels differently. content[0].text and structuredContent each explain the current state and the next action, and they complement each other instead of repeating the same JSON.

Every surface keeps one completion verdict, which the DiscernResult envelope defines: MCP isError is always the opposite of structuredContent.ok, and renderers choose and arrange facts but never reinterpret success.

--markdown, --json, and --render can't be combined. Each leaves out the surrounding terminal decoration and the narration of subprocesses. --render is a convenience: it passes the authored Markdown through discern's terminal renderer. It never prompts or pages, follows the terminal's width, theme, color, and character support, and writes no control sequences when redirected. JSON and Markdown stay the main result formats.

An authored Markdown presentation selects facts from the result's registered contract instead of dumping every JSON field. When present, its sections come in this order: current state, bounded evidence, authority and boundaries, owner attention, other actions, then the next action, which is why the recipe search refusal ends on what to run. Owner attention holds the decisions reserved for you. When several actions matter, the secondary ones come first, and the immediate next action closes the document. Supporting payloads where whitespace matters keep their exact content in the evidence section, including leading and trailing spaces. They include requested map or manual pages, setup instructions, diagnostic output, and terminal art.

status has its own size limit. Its default CLI JSON, MCP structuredContent, and live resource are bounded orientation views, with true counts of what they left out. discern status --verbose --json, or discern_status with verbose: true, selects full structured status. Both default surfaces name that route in hints, and Worktrees and status defines the fields and caps.

Default doctor JSON and discern_doctor return the environment and the actionable checks, without data.execution_model. Their hint names discern doctor --verbose --json, and MCP accepts verbose: true. The terminal doctor uses --verbose for per-step hints.

setup begin emits the operating contract and the first page, and setup step <n> emits one page. Each shares its parsed operational outline across its structured, terminal, and Markdown forms. setup done returns Proof, assurance, the derived inventory, and one action that's valid for the current phase.

The tools below return the same result contracts as the CLI, so use their structured fields for integrations, and their Markdown for reading or relaying an outcome.

Each tool's input object is strict, so it refuses a key it doesn't declare instead of dropping it. These are the accepted keys, and only discern_standards requires one, action.

An ordinary completion needs a clean, committed tree, as the recipe search refusal shows, and proves its HEAD.

• standalone: true gives transient diagnostics, including on a dirty tree, without Proof.
• policy_base takes a fetched comparison ref, only together with ci: true and standalone: true, for a hosted report.
• rerun: true checks an unchanged tree again.
• met and unmet record checkpoint conclusions, and can't be combined with ci: true.

None of these options grants landing authority, and none changes which checkout the agent works in.

For an ordinary acceptance, your agent leaves out action. From the effort's worktree, the call records the effort's submission, meaning the exact HEAD and its Proof, and lands it once discern verifies the landing authority. Without authority, it refuses without changing anything: the submission waits in the landing queue for you, and the agent relays the Proof lineProof↗discern's record of which of your project's checks passed, on exactly which commit..

• target selects a task by id, path, branch, or full local ref. A call from the main checkout must name one. With target, ordinary acceptance starts a walk: it lands the selected submission first, then other authorized submissions in queue order, and stops at the first refusal. data.landings records each attempt.
• Consent covers only the submitted commit. confirmed: true records consent you gave in the current conversation, and variance and approve_standard each require it.
• dry_run: true shows the landing queue and the selected task's verdict, and changes nothing.

When the trunk moved after the task's Proof, the call combines the change with the new trunk in an integration worktreeIntegration worktree↗A temporary copy of the project where discern checks a change combined with newer work before landing it., checks the combined code, and lands the exact result that passed, instead of landing your change on top of code its checks never saw. A conflict or a failed combined check goes back to the task's author. When a checkpoint questionQuestion↗Something discern asks your agent to judge, about a change or about the project as a whole. fires on the combined result, discern keeps the composition. Your agent answers the question on a follow-up call, with met, or unmet and a rationale, and the same landing continues. The refusal serves a composition_receipt, which the answer, and any varianceVariance↗Your permission to land a change even though your agent answered a checkpoint question unmet. decision over the combined result, must name, so a decision can't drift onto a composition it wasn't served for.

If checkpoint questions block an emergency plan, your agent first calls discern_accept with action: "emergency", prepare: true, and the reason. Preparation runs the checkpoint triggers and serves their questions, without running validation jobs. The agent records the questions it judges satisfied through met, an array of checkpoint ids, or one it judges unmet through unmet, with its rationale. It gets back a preparation receipt. That receipt goes in preparation_receipt on the later preview and on the confirmed call.

• A changed revision or declaration needs fresh preparation.
• An unmet answer lands only under your variance: the preview serves each one in data.emergency.variances, and the confirmed call names each checkpoint in variance.
• dry_run: true previews preparation without running triggers or recording answers.
• Preparation can't be combined with confirmation, or with transition recovery.

For the emergency itself, your agent calls discern_accept with action: "emergency" and a reason. You review the displayed trunk, the repair revision, each commit it lands, the reason, and the checks that failed, never ran, or have out-of-date evidence. Then your agent supplies confirmed and the plan's approval_token. The token expires after 15 minutes, and a changed plan needs fresh approval. discern builds the repair on the actual trunk, and composes no other queued work into it. When the repair already contains another task's unlanded work, data.emergency.carried names each such task, its branch, and its newest revision in the repair, because approving the plan lands that work too. Checkpoint judgments still come first. A loosened standard limit lands only under its recorded proposal: the preview serves each one in data.standard_approvals_required, and the confirmed call passes each token you approved in approve_standard. A plan that redefines or deletes a standard is refused.

The exception has its own record type, and can't serve as passing Proof. This action doesn't push, deploy, or change external branch protections. recover resumes an interrupted emergency by its landing id.

Every tool that works on a project accepts an optional path, which selects the discern project or worktree for that call. Pass an absolute filesystem path anywhere inside the checkout you mean, including another repository in a multi-repo workspace, and discern resolves the project root. Leave path out to use the checkout the MCP server currently targets. A relative path is rejected, because the server's process directory isn't the caller's directory. discern_docs needs no project.

After a successful discern_start, later calls use the new worktree by default. After discern_accept removes that worktree, the server points back at the surviving main checkout. Tools that need finished setup return a controlled setup_unfinished result until setup finishes.

discern_standards requires an action. action: "measure" accepts names, force, and pin. action: "propose" accepts an ordered proposals array of unique { name, reason } entries, and records every limit breach at once, in one transaction. A proposal's reason is a technical justification, and it grants no approval or landing authority. The scalar discern standards propose CLI command stays available for terminal use.

discern_refresh accepts dry_run: true. Its plan covers the agent filesAgent file↗An instruction file your coding agent reads when it works on your project., materialized skills, provider integrations, the Proof noteProof note↗A copy of a landed change's Proof, stored with its commit in Git. fetch configuration, the clone-local merge driver, the generated .gitattributes metadata, the maintained ADR index, removals, and planning errors. A preview has no steps, and a preview with planning errors returns ok: false with partial_refresh. A normal call applies only those targets, and reports steps.

MCP tools/list returns the full definitions, and each client chooses what to load at startup. discern lists the tools a session needs to start first: status, start, prepare, done, update, await, accept, and map. Progress comes next. The standalone test tool, which is expensive, comes after progress, for use on demand.

Cursor's strict profile keeps discern_await under the Agent CLI's 60-second transport limit. Gate calls can take longer, so there your agent runs discern done --markdown in a shell, and discern prepare --markdown or discern test --markdown when it wants those stages.

The long profile reserves 300 seconds for delivery and cancellation, and the strict profile reserves 15 seconds against Cursor's shortest verified surface. A watch returns as soon as its condition holds. When the budget runs out first, the result has ok: true and data.met: false, with a 15-character data.resume handle, and your agent continues with that handle instead of rebuilding the watch from what it observed. Handles are local to the repository, expire after 7 days, and share a 512-record cap. The CLI reports this not-yet result with exit 124, and MCP returns a normal tool result.

Over MCP, timeout can shorten a call but can't extend its profile, and timeout: 0 checks once without waiting. The CLI's --timeout isn't capped. The result reports data.requested_timeout_s and data.timeout_basis.

A long done, test, standards, or accept run, and every discern await or discern_await call, announces a progress handle as its first progress fact, in the form R1-XXXX-XXXX-XX, with the command that reads it back. So when a call is lost, your agent reads the run back instead of starting it again. The same facts reach a live terminal, MCP notifications/progress messages when the client supplies a progress token, and a journal under the repository's Git administration. A --json or --markdown run prints nothing while it runs, because its result envelope is its whole output.

Runs that don't do long work announce no handle: dry runs of done, standards, and accept, a done that refuses before its gate starts, a standards proposal, accept in queue mode, and an emergency acceptance. discern also announces no handle when it can't open its journal store.

An unfinished completion attempt holds a 60-second lease, which its live operation renews every 20 seconds. If another done reaches the same evidence while that lease is current, the result is error: "incomplete", failed_stage: null, and gate_ran: false, and data.completion.pending holds one row for the shared attempt: its attempt id, effective expiry, progress handleProgress handle↗A short code, such as R1-XXXX-XXXX-XX, that lets your agent read back a long-running command after losing track of it. when available, and next action. Your agent reads the existing operation with discern_progress, or discern progress <handle> on the command line, instead of starting another gate. A later call cancels the claim once its owner is gone or its lease has expired, then proceeds with a new, fenced attempt.

discern progress [handle], or discern_progress with handle and path, reads that operation back at any time, and changes nothing. With no handle, it reads the most recently started operation of the calling checkout, and refuses another checkout's operation by name. Every worktree of the repository shares one store, which keeps records for up to 7 days. When the store is full, discern evicts records in this order: unreadable records, finished await records, other finished operations, unfinished operations whose process is gone, and last, running operations.

Active waits stay visible when independent checks finish. The current state explains what can't start, why it's waiting, how long it has waited, and what happens next, and a wait for capacity includes the configured limit on concurrent runs and the latest observed use. A live process alone doesn't prove the work is advancing. Older records without wait facts can't supply this information.

When your agent returns to a checkout with an operation still running, discern_status includes the same current-state summary and the command that reads it back. So a queued operation stays visible through status as well as progress.

An active await records its target, requested condition, latest observation, and continuation. If the call stops, your agent reads the original call's progress and uses that continuation to keep the original watch, instead of starting another. An elapsed observation window means the condition is still unmet, and says nothing about whether the awaited work succeeded. Explicit cancellation ends automatic waiting.

Observers and executors differ: a reconnect read, an await watch, or a second session can stop, time out, or die without touching the run. The MCP call that's itself running a command isn't a separate observer. Its explicit cancellation, or its transport closing, cancels the executor, and the journal records the run as cancelled with its facts kept.

A read refuses, naming the condition, for a damaged or unknown handle, an empty store, another checkout's operation, an unreadable record, a record written by a newer discern, a store discern can't access, or no reachable repository.

Your project's own commands, such as its test runner or build, can report progress by printing lines to stdout or stderr. Say the recipe app's test runner prints these while it runs:

DISCERN_PROGRESS {"units":{"kind":"partitions","completed":3,"total":8},"results":{"passed":120,"failed":1,"skipped":2},"elapsed_ms":45210}
DISCERN_PROGRESS {"failure":{"name":"clearing the search box restores every recipe","message":"expected 3 recipes, got 0","file":"tests/recipes_test.ts","line":12,"reproduce":"deno test --filter 'clearing the search box' --seed 7 tests/recipes_test.ts"}}

Each line holds one JSON object, and every top-level field is optional.

• units carries kind and completed, which it requires, and total, where null or a missing total means unknown.
• results carries only the counts the producer has established. A missing or empty results leaves the counts unknown.
• active lists the labels of running work, and elapsed_ms is the producer's own elapsed time.
• partial: true marks counts that cover only part of the completed units. Once a producer reports partial counts, they stay marked partial.
• failure names the failing test or obligation. It requires name and message, and can add file, line, and a focused reproduce command that carries the recorded seed and instrumentation.

discern shows the counts and the failing test live, and keeps them for reconnect, but the lines change nothing about scheduling, verdicts, or evidence: the test job's exit status still decides whether it passed. discern ignores unknown keys, ignores a whole line that doesn't validate completely or carries no recognized fact, and drops lines over 16 KiB. The protocol is the same for any language or test runner.

discern_map and discern_docs share one way to find documents:

A search result carries target, path, section, title, description, match, an optional matching heading, a contextual snippet, and, where available, page_id and manual_kind. match is complete, partial, or metadata. The surrounding payload carries query, an optional scope, the full match count, truncated, and the returned results. A search with no matches is ok: true with an empty result list. Scores stay an implementation detail.

Results with match: "complete" rank first. When fewer than five qualify, strong partial matches can fill the unused slots, and each must cover enough of the query's terms, in proportion to its length. The ranker favors partial matches that add terms earlier results missed. Exact technical text, and phrases in titles, aliases, headings, or code, return only phrase matches. A longer query with no match can fall back to a close title or alias, but a query shorter than four characters gets no spelling suggestions.

Map search includes pages with publish: false, and docs search covers the public manual. Both are local, and leave queries out of the logbook. On the command line, use discern map --search <query> or discern docs --search <query>, optionally after a target.

path and target answer different questions. path chooses which project or worktree a project-operating MCP call uses. target chooses a region or document inside that project's map.

The recipe search refusal carries ok, verb, data, hints, error, and message, and no plan or steps, because nothing ran.

ok: true means every outcome the command's completion policy requires holds, so required writes, validation, compilation, cleanup, and final checks can't fail under a successful envelope. An explicitly optional degradation stays successful only when advisories[] carries its permitted kind, non-empty evidence, and next_action. Hints don't waive required work.

When diagnostics are sampled, the envelope shows a summary sample, with long messages and outputs cut short, and diagnostic_evidence points to the complete set.

ok and the execution state are independent contracts. A failed gate run can carry diagnostics and completed steps beside its classified error. A required failure late in a run keeps ok: false and can carry typed data about partial effects, and recovery, because ok: false doesn't imply a rollback. A refusal can carry a review plan without claiming dry_run: true. Serialization leaves out undefined fields, so a caller branches on ok, then verb, before reading data.

A failed JSON, Markdown, or MCP result always includes a registered next action: JSON and structuredContent carry it in hints, and Markdown puts it at the end, as the recipe search refusal does. Decisions for you sit in a separate Owner attention section, before the caller's actions. When message or the first diagnostics entry explains the fix, the hint points there. When recovery depends on a choice or a reported state, the hint names that state and the action. Consent, partial operations, unfinished setup, document lookup, and improvement thresholds use these specific instructions. So a caller never has to guess whether to retry, review, choose, or finish cleanup.

setup begin checks for the setup permission it needs before applying its plan, and ordinary acceptance checks permission separately for each landing. A result awaiting consent can still describe earlier tasks that already landed, so read its per-task outcomes before you retry. The result names the decision and the continuation command. Dry runs need no permission, because they only show the plan.

Setup consent isn't permission to write. A command that changes files first checks that it can write the targets its plan names. If it can't, it returns write_denied, with the exact path and a retry, and the phase stays unchanged. Read-only commands make no such check (Setup and integrations).

Setup pages carry the prose meant for you once. The compact spine.owner_moments projections keep each moment's identity, kind, phase, purpose, recommendation, option ids, wait boundary, and relay protection. Compatibility fields derive from the same moments, so the terminal, Markdown, JSON, and MCP share one authority without repeating the prose.

start, status, and green done results can carry data.landing_authority: authorized or conversation-required, with its source, scopes, evidence of uncovered paths, and warnings. Compact status and done results limit the uncovered paths to six examples, authored files first, beside the uncovered totals and scopes. A grant reported by start is prospective. A fact that's absent stays absent. Proof explains landing authority.

status names the project in data.project. Its default structured view keeps the main fleet row and at most six other rows, chosen by attention, the current checkout, recent activity, and name. Every repeated collection is capped at six. fleet_total and positive projection.omitted counts record the exact number of entries left out, under dotted paths with zero-based array indexes. Config refusals carry projection too.

Every sampled readable row carries one gate_proof, whose status is honored, report_only, missing, stale, dirty, unavailable, or read_failed. report_only is current for its commit, but can't authorize landing, because checkpoint review wasn't enforced. An honored marker carries a compact proof, with the branch, trunk, validated commit, diff counts, and Proof line. Rendered Proof pages, and the older fields that copied an honored Proof, don't appear in structured results. Collision rows keep their identities and shared-path counts.

discern status --verbose --json, and MCP verbose: true, restore the complete repeated collections and landing history, with projection: { mode: "full" } and no omission map. Terminal --verbose also shows collision paths and full Proof pages. Worktrees and status covers the terminal report and these views.

Green means the required checks passed for the recorded commit. It doesn't mean the change landed. A later edit makes Proof stale, because the code waiting to land differs from what passed. Only you can approve an exception for an unmet checkpoint, and no grant covers one.

For done, read data.completion as well as the top-level verdict:

An explicit CI report uses data.mode: "report", and reports checkpoint review without answering questions. Its feedback provides no landing Proof. checkpoint_drops keeps classified uncertainty about checkpoint enforcement.

discern_accept with action: "queue" returns the reviewed path, branch, head, and complete proof pointer under data.revision. data.submission carries the observed authority, and its state is planned for a dry run and queued once recorded. A queued result includes submission_id and submitted_at, and replaces, when present, names the previously queued commit.

Queue mode accepts target, path, and dry_run. It refuses landing consent, exception approvals, and integration answers, which belong to ordinary acceptance as separate decisions. Applying it checks the clean tree, the current Proof, and any separate checkpoint or standard decisions again. Queueing the same revision again keeps its place in the queue, and a later commit, or done, doesn't submit newer work by itself. Queueing schedules nothing in the background: to start landing, your agent calls discern_accept with target.

Ordinary acceptance returns data.queue: the landing queue, a view derived from the submissions. Each row is one submission whose commit hasn't landed. Rows that are pre-authorized come first, in grant order, then rows awaiting-owner, in submission order. discern status, the desk, and a dry_run: true preview show the same rows in the same order, and a dry run changes nothing.

After a landing, the top-level fields carry the outcome.

• data.landing records the exact effects: recovery_performed, trunk_landed, worktree_removed, and branch_deleted. Resource teardown appears as resource-destroy steps, and an unfinished cleanup as an acceptance-cleanup-incomplete advisory.
• data.landings records every landing the call attempted, with the selected submission first.
• data.consent names the consent source, and data.root names the surviving checkout, including when acceptance removed the calling worktree.
• data.proof_line is the landing's final Proof line, to relay word for word. JSON and MCP results carry only this line; the full Proof page appears in terminal output and in discern status --verbose.
• data.variances and data.standard_approvals list what the landing carried, and checkpoint_drops keeps classified uncertainty about checkpoint enforcement.
• data.scopes_changed names the configured scopes the landed paths matched, and data.proof_note reports the Proof note write and its fetch transport.

A refusal can carry data.integration_judgment, with the composition receipt under composition, the decision, and the ids it's awaiting. A refusal over a proposed limit change carries data.standard_approvals_required, with the exact approval tokens. The published schema defines every optional field. For recovery, see Recover an interrupted task.

An unlanded successful setup done carries Proof, the canonical completion inventory, the qualitative inventory.project_context, and the landing state. It carries no reactivation or improvement advice. Project context includes the derived handoff for the primary subsystem, the project principles, and the instruction sourcesInstruction source↗The file where your project writes its own instructions for coding agents..

After a successful setup accept, data.reactivation carries each provider's exact activation check, local recovery, and command-line fallback, from the provider registry. Platforms and providers lists them. data.activation_context explains why a fresh session is needed, and data.optional_improvement depends on activation being verified. A completion already on the trunk shows the same activation steps, in the same order.

A failed setup done tells unfinished authoring, uncommitted paths, and an exact owned rollback apart. A transaction names its stage, rollback, retained state, next_action, and recovery, and nested diagnostics keep their location, rule, and reproduce command.

Applied setup and upgrade results carry data.instruction_refresh. status: "complete" means the required instruction refresh finished, even when compiled is empty because every file was current. status: "partial" makes the top-level ok false, and carries the completed files, non-empty failure evidence, effects_preserved: true, and recovery: { command: "discern refresh", safe_to_retry: true }. A partial result reports the earlier scaffold or migrationMigration↗A numbered step that updates your project's discern setup to a newer format. effects, rather than pretending they rolled back.

Output metadata is advisory. A configured command's exit status decides the job's verdict, except for standards, where the command's DISCERN_METRIC value is the measurement contract.

Gate and standalone standards results carry each standard's direction, limit, optional margin, measurement, value, and verdict. A measured or replayed value also carries the gate's pin_eligible decision and, when it's true, the exact pin_target. Those fields describe mechanical eligibility; patterns applies the decision rule from the project's own history.

Patterns results always carry data.investigations. Each entry cites source ids that stay present in data.findings, repeats their observations and denominators with where the numbers came from, and states the shared evidence boundary, a bounded interpretation, a diagnostic action, and what would prove it wrong. An empty array means no registered relationship had enough evidence. Terminal, JSON, MCP, and sealed-archive reads use the same arithmetic.

cancelled marks a sibling stopped by a fail-fast failure, and fails a required completion. skipped marks a configured step that didn't run. A policy can separately treat a user's cancellation as a successful completion with no effect.

Every diagnostic includes tool, severity, message, and reproduce_cmd. It can also include normalized output, truncated, output_path, file, line, col, rule, and fix_available. When the recipe app's test for clearing the search box fails, the gate's diagnostic has tool: "test", message: "test failed (exit 1)", and reproduce_cmd: "deno test tests/", the test job's own command, with the runner's output in output. Use reproduce_cmd for the smallest direct rerun discern knows, and output_path when the inline capture was cut short.

The published schemas mark every fixed-set result value with x-discern-vocabulary. An open vocabulary is published as a string, with its known members at the schema root under the key the marker names, and grows in ordinary releases, so treat a value you don't recognize as opaque. A closed vocabulary is published as an enum, and changes only with a new major version of its schema.

The closed vocabularies are step outcome, diagnostic severity, validation mode, checkpoint mode, landing-authority kind, standard proposal direction, completion evidence purpose, requirement kind, and exception state, plus the release comparison's status and publication. Completion evidence purpose appears in the Proof note schema. Every other result vocabulary is open.

• Step kind (open): job, scope-gate, merge-check, standards-limits-check, tracked-artifacts-check, instructions-check, skills-check, tracked-refresh-check, resource-create, resource-destroy, git, task-metadata, setup-step, repository-ensure, checkout-clean-check, setup-ensure, env, refresh, tidy, standard.
• Step disposition (open): run, skip, gate.
• Step outcome (closed): ok, failed, skipped, cancelled.
• Diagnostic severity (closed): error, warning.
• failed_stage (open): fix, build, check, test, check/test, scope_gates, tree_drift, generated_drift, refresh_drift, tracked_artifacts, instructions, skills, skill_frontmatter, adr_numbers, adr_index, map_integrity, merge, standards, write_denied, validation_inputs.
• Advisory kind (open): acceptance-cleanup-incomplete, checkpoint-evidence-dropped, checkout-clean-observation-unavailable, doctor-warning, execution-cap-unavailable, generated-attribute-pattern-untranslated, governing-config-key-ignored, ignored-file-observation-unavailable, landing-authority-unverified, optional-resource-unavailable, proof-recording-unavailable, setup-unproven-completion, setup-machinery-commit-failed, setup-marker-commit-failed, standards-limits-unverified, uninstall-strip-incomplete.

The registered error slugs, published under x-discern-error-slugs, are: active_worktrees, ambiguous, apply_failed, awaiting_consent, awaiting_declaration, awaiting_standard_approval, awaiting_variance, below_min_score, brief_unparseable, checkout_failed, checkpoint_evidence_unavailable, config_template_unavailable, confirmation_required, conflict, desk_already_active, detached_head, diagrams_misaligned, dirty_worktree, edit_failed, gate_failed, gitignore_template_unavailable, identity_failed, incomplete, internal_error, invalid_arguments, invalid_config, invalid_config_file, invalid_migrated_config, invalid_settings_file, invalid_toml, invalid_value, no_docs, no_map, no_project, no_repository, no_trunk, not_main_checkout, not_on_setup_branch, not_on_trunk, partial_acceptance, partial_materialization, partial_refresh, pin_failed, precondition_failed, proposal_failed, proposal_stale, provisioned_resources, read_failed, renamed_command, renamed_config_key, report_only_proof, schema_version_too_new, script_not_a_command, script_not_executable, setup_plan_failed, setup_unfinished, skills_eject_failed, tables_malformed, templates_not_found, tidy_parse_failed, tidy_write_failed, unchanged_tree_rerun, unknown_category, unknown_command, unknown_key, unknown_standard, unknown_step, unknown_target, and write_denied.

{+target} accepts a slug, section/slug, or a path. discern computes a resource when it's read, and a client that doesn't attach resources automatically can call the matching tool instead. The MCP tools manifest lists every resource and resource template by name, kind, and URI, and none of those change within a major version.

In the quiet result modes, a result with ok: false always exits nonzero, as the recipe search refusal's exit 1 does, so a verb can't report exit 0 for a failed completion contract. A nonzero exit doesn't always mean ok: false: a discern await --json that reaches its budget exits 124 with ok: true. Predicates run with --json or --markdown always exit 0, and their boolean is in data. Bare config has and impact --has stay silent, and exit 0 or 1. identity and config reads are bare unless --json or --markdown asks for a result.

types/discern-json.d.ts in the matching release source archive provides release-pinned standalone TypeScript types, indexed by verb, command path, and MCP tool name. Each per-verb type intersects with DiscernResultState, so narrowing ok also narrows error, and planned and completed steps can't coexist. The result schema's x-discern-contracts metadata publishes each registered command's completion_policy, including its required_postconditions, optional_advisories, and its policy for refusal, cancellation, partial effects, no-ops, and who owns recovery.

The Compatibility page explains what each published contract promises across releases: the schema majors, the evolving members, the open and closed vocabularies, and the retirement rule. This section keeps the result-shape facts that page doesn't carry.

data.instruction_refresh.status: "partial" means a required refresh failed, even when earlier setup or upgrade effects remain. A successful setup accept with nothing to land carries data.completion = { status: "no_op", reason }, where reason tells no_git_repository apart from already_on_target.

The schemas use JSON Schema Draft 2020-12. Use the artifacts from the release you integrate with: the release source contains types/discern-json.d.ts, and the result schema publishes the x-discern-contracts metadata.