Run a doctrine gate — Jarvis Docs

A doctrine gate captures fresh repository guidance, compares it with a baseline you selected, and asserts that it added no error findings. PRISM evaluates the repository; JARVIS admits execution under policy and stores receipts and audit records. This path makes no model call.

Availability and scope

Use a JARVIS build from unstable containing PR40 (the first such build is 0.3.0-beta.181). The website is published separately from main: this documentation update does not add the gate to main binaries or promote the runtime to a release. A default download may still lack it. PRISM needs the captured-audit and comparison interfaces merged into main in PR30. These source merges do not prove that an older installed package includes them. Run prism-harness audit describe --json, prism-harness audit compare-describe --json, and mnemos prism --help to check your installed command surface. Captured filesystem auditing currently requires Linux /proc/self/fd support. The recovery commands below additionally require an unstable build containing durable gate recovery (first source build: 0.3.0-beta.188). Its mnemos prism doctrine-gate --help advertises list, show and resume; the original beta.181 gate does not provide them.

The example uses a small project at /work/project, an operator-owned audit root /work, and a trusted PRISM executable at /opt/prism/prism-harness. Replace these absolute paths with your own. Use one executable and state home throughout; source and bundled PRISM builds deliberately have different implementation IDs.

1. Admit the tool explicitly

Create /work/audit-policy.yaml with this executable-specific policy:

defaults:
  shell: deny
allow:
  - command:
      argv_prefix: ["/opt/prism/prism-harness", "audit"]

This allows this PRISM executable's audit family, including descriptor, capture, replay and comparison commands. It does not allow arbitrary shell commands. Set:

export PRISM_HARNESS_BIN=/opt/prism/prism-harness

Use a private state directory: receipts and supervisor logs can contain captured repository guidance. The gate coordinates processes in a home controlled by one trusted operator; it does not authenticate a filesystem writer who can rewrite the database or replace lock files. Admit only the roots you intend to inspect. A link beyond /work remains outside the declared scope.

2. Capture and choose a baseline

mnemos prism doctrine-audit --project /work/project --audit-root /work \
  --command-id baseline-001 --policy /work/audit-policy.yaml \
  --home /work/jarvis-state --json

Inspect the capture response's receipt.artifact.result. Choose a baseline only when coverage is complete and you accept its findings. Existing errors may be explicitly accepted: the gate promises no added errors, not zero errors. Incomplete coverage cannot become a pin. A depth or inventory limit, unreadable input or unresolved link is uncertainty, never a passing substitute.

After inspection, explicitly select that capture:

mnemos prism doctrine-baseline set --project /work/project --audit-root /work \
  --baseline-command-id baseline-001 --expect-revision 0 \
  --policy /work/audit-policy.yaml --home /work/jarvis-state --json

This command creates revision 1. Baseline selection is explicit; neither "latest audit" nor a successful candidate silently replaces it.

3. Run the gate again

mnemos prism doctrine-gate --project /work/project --audit-root /work \
  --policy /work/audit-policy.yaml --home /work/jarvis-state --json

Run it twice: candidate and comparison IDs differ each time. The ordinary four FlowIR steps are capture, compare, assert, halt. Success requires a no_regression comparison and committed gate event/audit records.

Exit	Meaning
0	Gate passed: complete, comparable evidence with no added errors. Warnings and existing errors may remain.
1	Assertion failed: inspect comparison to distinguish regression from indeterminate evidence.
3	Current policy denied the action or requires approval.
4	An operation outcome is unresolved; recovery stopped without retrying it.
Other nonzero	Execution or persistence failed; never interpret it as a passed gate.

A failed response may have workflow_run_id: null if no workflow run could be created. Its original error is retained. Starting a fresh gate again creates a new observation. Use the explicit recovery commands below to inspect and continue an existing durable gate.

4. Exercise a regression and inspect it

In a disposable project only, append these lines to AGENTS.md:

Always format source files before review.
Never format source files before review.

Run the gate and expect exit 1. Save its returned candidate and comparison IDs. Inspect the exact comparison with those IDs and the returned baseline ID:

mnemos prism doctrine-compare --project /work/project --audit-root /work \
  --baseline-command-id baseline-001 --candidate-command-id GATE_CANDIDATE_ID \
  --command-id GATE_COMPARISON_ID --policy /work/audit-policy.yaml \
  --home /work/jarvis-state --json

This retrieves the recorded comparison under current admission, without a new capture. Its nested receipt.artifact.result.status retains the verdict. Restore the original file bytes and run a fresh gate: it should pass again. Replay proves something about the captured observation, not today's filesystem.

5. Adopt a new baseline deliberately

Capture another complete audit using a new ID, for example baseline-002, and inspect its findings. Then replace the current pin using its current revision:

mnemos prism doctrine-baseline show --project /work/project --audit-root /work \
  --policy /work/audit-policy.yaml --home /work/jarvis-state --json
mnemos prism doctrine-baseline set --project /work/project --audit-root /work \
  --baseline-command-id baseline-002 --expect-revision 1 \
  --policy /work/audit-policy.yaml --home /work/jarvis-state --json

Revision 0 creates an absent pin; revision 1 replaces revision 1 with revision 2. A repeated replacement with the stale revision fails BaselineConflict. An implementation upgrade needs a new compatible baseline. A pin changed during an active gate affects the next invocation; it does not change the active gate's captured baseline.

6. Inspect and recover an interrupted gate

Fresh invocations, with or without the explicit run verb, always create new IDs. They persist their original baseline and recipe intent before dispatch. To find a gate whose command was interrupted, use the same project, root, policy and state home:

mnemos prism doctrine-gate list --project /work/project --audit-root /work \
  --policy /work/audit-policy.yaml --home /work/jarvis-state --json
mnemos prism doctrine-gate show --gate-id GATE_ID \
  --project /work/project --audit-root /work \
  --policy /work/audit-policy.yaml --home /work/jarvis-state --json

Replace GATE_ID with an ID from runs, not a candidate command ID. List returns the newest 20 records; --limit accepts 1 through 100 and truncated reports whether more exist. Show includes revision, status, the original baseline revision, candidate/comparison IDs and their operation states. These commands expose metadata without invoking PRISM or returning captured source. An open record can represent an interrupted or currently active gate; it is not a claim that the original process has died.

After inspecting the record, supply its current revision explicitly:

mnemos prism doctrine-gate resume --gate-id GATE_ID --expect-revision REVISION \
  --project /work/project --audit-root /work \
  --policy /work/audit-policy.yaml --home /work/jarvis-state --json

Replace REVISION with the positive integer from show. Resume reserves a new revision under an exclusive process lock and re-enters only the original four recipe steps. Verified completed capture and comparison receipts are reused under their original IDs. The gate retains its original baseline even if you have since promoted a different pin. Current scope and policy admission still apply. The selected state database, project and audit-root metadata must remain resolvable; directory symlinks used as --home can be refused by home admission.

A completed response includes gate_id, revision and candidate_observed_at.started_at / finished_at in Unix seconds when a valid candidate exists. Show also exposes that observation time. Recovery retains these original capture times. Editing guidance after capture does not update that historical observation; start a fresh gate to check today's files. Resuming a completed record with its current revision returns its exact saved response and exit code without invoking PRISM. Keep the complete state home, including original receipts, supervisor run records and gate-associated workflow records. Missing or damaged historical evidence is refused; a saved response is not an independent archive.

Result	Next step
`GateBusy`	A live owner holds the gate lock. Let it finish or stop that owned process deliberately.
`GateConflict`	Your revision is stale. Inspect the record again before deciding whether to resume.
`OperationUnresolved` (exit 4)	A dispatched operation lacks a completed outcome. It is not retried; use a separate fresh gate when you need another observation.
`OperationFailed`	A failed operation claim is immutable. Inspect the history and start a separate fresh gate if appropriate.
`ImplementationChanged` or incompatible intent/descriptor	Restore the compatible tool/recipe implementation, or start a fresh gate with a compatible explicit baseline. Recovery cannot retarget its original evidence.

Do not delete lock files, reset claims or edit the state database to force recovery. The lock releases when its owning process dies; no timer or PID guess steals it. A gate intent and its audit entry commit together, as do its terminal response and completion audit. If completion persistence fails, the open intent can still be inspected and completed receipts can be reused. Gates created by older builds before intent persistence are not retroactively resumable. This is bounded recovery for this read-only recipe, not generic workflow continuation.

Archive a growing state home

Gate records and their lock files are retained; there is no automatic gate history reclamation in this version. To retire a growing home safely:

Stop every CLI, daemon and supervisor using that home and confirm they have stopped. Never infer this from a PID guess, timer or an apparently idle gate.
Archive the complete stopped home privately, preserving permissions and all database, journal/WAL, artifact, receipt and lock files together. Do not prune individual lock files or database rows while retaining an active home.
Use a new private home for new observations. Admit the same intended scope, capture and inspect a complete baseline, then select it with revision 0. Gate IDs and revisions belong to their original home; they do not transfer.
If historical recovery is needed, stop users of both homes and restore the complete archive at its original admitted location with its compatible executable and artifacts. Keep only one active copy of that original home. An archive is retained evidence, not a successful fresh gate.

Reference and boundaries

The adapter contract owns schemas, exact bounds, admission and durability semantics. The PRISM audit contract owns collection, replay, comparison and coverage. These are source-versioned contracts; select the revision matching your installed implementation.

This guide qualifies the declared project scope. It does not certify a complete workspace, authorize deployment, activate a schedule, or turn integrity digests into signatures. Full repository coverage may remain incomplete even when an explicit smaller doctrine profile passes.