Pretorin Compliance

Formally accept a canonical Issue's confirmed residual risk. The referenced evaluation must be the Issue's LATEST and already confirmed, and the Issue must still be open or in_progress. expires_at must be a timezone-aware future timestamp; review_frequency_days and next_review_at are only valid together and next_review_at must not exceed expires_at.

Declare the ordered execution steps for a draft plan and transition it to active. This gates writes that carry that plan_id: start_task returns a scope-pinned draft, the calling agent declares what it will do, then activate_plan enables platform writes citing that plan_id. plan_id is optional on Tier-1 writes, so this is a pre-action contract for the routed flow rather than a hard security control. Supplied steps must be pending and indexed contiguously from zero; the list may be empty when workflow-required semantic phases are already present. Those phases are expanded authoritatively in the returned plan. Concrete actions declare a phase; the agent selects each recipe id, version, and parameters, while the Plan enforces its start/end lifecycle receipt. Standalone and control-assessment Campaign work share this workflow contract; the Campaign contributes frozen scope and outcome gates, not recipe choices. Acceptance criteria are additive for Campaign children too. Also accepts a legacy plan that is already active but declares no steps: supplying its steps here is the way to make such a plan completable.

Admit one independently supported control gap as a canonical Issue. New MCP work must use an issue-create recipe context carrying the unmet expectation, observed gap and source basis, risk basis, explicit clearance condition, minimum evidence, and prior-Issue deduplication result. Do not create Issues for optional advice, missing context, evidence suggestions, subtasks, or ai_analysis findings; the platform review reconciler owns AI finding Issues. Keep matcher-facing content to one sentence of at most 20 words and begin the title with the expectation key.

Deprecated alias for add_control_issue.

Append a provisional risk evaluation for a canonical Issue. Confirm the determination with confirm_issue_risk_evaluation.

Answer one policy question. IMPORTANT: Before answering, you MUST (1) call get_policy_question_detail for guidance, and (2) research the local workspace — read source code, config files, existing policy documents, infrastructure definitions, and documentation to ground your answer in observable facts. Do not invent organizational facts, role titles, URLs, procedures, or policies. ANSWER-FIRST MODE — answer as many questions as possible directly from workspace evidence without involving the user. Submit these answers silently. GAP QUESTIONS — only for questions that require organizational knowledge not present in the workspace (e.g., role assignments, review frequencies, policy decisions, org-specific processes). Do NOT ask about things you can observe in code, config, CI, or docs. When you must ask, use this format: ── Gap Question [N of TOTAL gaps] ────────────────── [Short clarifying question — what you specifically need to know] Context: [1 sentence on what you already found] Suggested answers: a) [likely option] b) [alternative] c) Other ────────────────────────────────────────────────── Present ONE gap question at a time. Wait for the user's response, compose the final answer combining their input with workspace evidence, submit it, then move on.

Answer one scope question. IMPORTANT: Before answering, you MUST (1) call get_scope_question_detail for guidance, and (2) research the local workspace — read source code, config files, infrastructure definitions, and documentation to ground your answer in observable facts. Do not invent organizational facts, system names, network topologies, or boundaries. ANSWER-FIRST MODE — answer as many questions as possible directly from workspace evidence without involving the user. Submit these answers silently. INTERVIEW MODE — only for questions that require organizational knowledge not present in the workspace (e.g., role assignments, review frequencies, policy decisions, org-specific processes). Do NOT ask about things you can observe in code, config, CI, or docs. When you must ask, use this format: ── Scope Question [N of TOTAL] ────────────────── [Short clarifying question — what you specifically need to know] Context: [1 sentence on what you already found] Suggested answers: a) [likely option] b) [alternative] c) Other ────────────────────────────────────────────────── Present ONE clarifying question at a time. Wait for the user's response, compose the final answer combining their input with workspace evidence, submit it, then move on.

Deprecated checkpoint compatibility only. Apply stored legacy proposals to Pretorin workflow records. Plan-backed Campaigns have no generic coordinator apply phase.

Explicitly and idempotently approve one CCI implementation through the Pretorin MCP. The CCI must already be past not_started with a substantive committed narrative and approval-supporting scoped evidence (verified, checksummed pending recipe evidence or valid evidence); the server returns 409 with missing prerequisites otherwise. Approval is recorded with agent source and approval stamps. This operation does not approve the parent NIST/DoD control; a human must do that in the UI.

Approve a submitted canonical Issue treatment plan. Requires the plan to be pending_approval. Approval is what makes transition_issue_action legal on the plan's actions.

Explicitly and idempotently approve one assessment objective implementation through the Pretorin MCP. The objective must already be past not_started with a substantive committed narrative and approval-supporting scoped evidence; the server returns 409 with missing prerequisites otherwise. Approval is recorded with agent source and approval stamps and promotes the AI draft to the committed narrative. Issue-blind by design: it never consults control issues. This operation does not approve the parent control; a human does that in the UI. A Campaign worker must also provide its assigned child Plan coordinates and can approve only a grounded frozen objective whose objective-bound evidence requirements are authoritatively covered.

Explicitly and idempotently approve the workflow for one exact STIG rule after the rule is in scope through confirmed applicability or a checklist, its latest exact-rule result passes, verified/checksummed recipe remediation evidence (or valid evidence) is linked to the workflow, and every linked Issue is reconciled. The server returns 409 with missing prerequisites otherwise. Pass the internal STIG rule UUID returned by the traceability/checklist surfaces.

Attach one or more systems to a vendor (SR-5 / SA-9 system-of-record mapping). Pass system_ids as an array of system IDs.

Produce a DSSE-signed attestation over the current reviewed risk state. The server rejects stale or missing reviews; any mutation after review requires another explicit review. The statement is auditor-facing and must explain the determination.

Attest the current asset inventory state, setting its last_attested_at on the scope page. Use AFTER submit_asset_inventory_diff has the inventory in the desired state. The asset inventory is a living kind (rows + attestation), not a file upload — there is no evidence_id to pass. Requires an active workflow (call start_task first).

Attest a system_spec snapshot kind (boundary_diagram, network_dfd, ppsm, interconnection), setting its last_attested_at on the scope page. Typically called right after link_spec_snapshot. Pass the same `evidence_id` you linked, plus a `sufficiency` envelope describing the artifact's provenance. Requires an active workflow (call start_task first).

Persist cancellation for an exact local Plan-backed Campaign before delivery to its execution owner. Committed platform writes are never rolled back. This local safety operation remains available during platform authentication or consent outages.

Mark a plan as cancelled. Allowed only from 'active'. Idempotent: cancelling an already-cancelled plan is a no-op. Cannot cancel a completed plan. Cancellation skips the acceptance gate — a cancelled plan is 'stopped early', not 'delivered'.

Read-only first gate for Campaign execution. Inspect the local Python dependencies, selected agent runtime, embedded Hatchet runtime, and optional TUI observer separately. This tool makes no platform calls, downloads, installations, reservations, Campaigns, or Plans. Call it before source preflight or preview_campaign; continue only when launch_ready is true. Managed native runtimes reported in deferred_setup may be installed only after explicit START confirmation; configured or PATH runtimes in deferred_validation are launched for validation only after START.

Cheap, unauthenticated probe of session grounding. Call at session start before start_task to learn whether the client is authenticated, which platform API endpoint and system/framework are active locally, and what to do next. Reads local CLI config only — no platform calls — so it's always safe and fast. Returns suggested_next as a plain-English hint, e.g., 'Run `pretorin login`' or 'Call `start_task` with an intent_verb'.

Preflight source reachability and candidate recipes for one workflow/control. Use this after start_task and before opening recipe contexts.

Deprecated checkpoint compatibility only. Claim legacy prepared items for drafting with leases; Plan-backed Campaigns delegate dispatch and retries to embedded Hatchet.

Complete an approved canonical Issue plan. Requires the plan to be approved and EVERY action on it to be completed. This moves the Issue to verification_pending, NOT closed — closure is the separate verify_issue decision.

Mark a plan as completed. Allowed only from 'active'. Idempotent: completing an already-completed plan is a no-op. Cannot complete a cancelled plan. The plan must declare at least one step, every step must be completed or skipped, and skipped steps must include an outcome_summary explaining why. Incomplete work returns a structured plan_incomplete error whose problems[] lists every unresolved step at once: each entry carries a reason of 'no_steps_declared' (plan-level, no step_index), 'step_not_terminal', or 'skipped_step_missing_reason', with step_index and status on the step-level entries. If the plan declares acceptance_criteria[], each criterion is evaluated against current platform state before the transition; any failures return a structured acceptance_failed error with the full list of failing criteria, and the plan stays active so the agent can fix the gaps and retry.

Confirm a canonical Issue's risk evaluation — a governed determination, not a stronger append. Confirming supersedes or expires any active risk acceptance, recomputes gate_status, and can demote the control's approval gate. Requires the Issue to be open or in_progress. Use add_issue_risk_evaluation for a provisional assessment that decides nothing.

Create a platform-native custom policy from an explicit definition. Evidence Locker content is supporting material and must never be converted into a definition.

Upsert an evidence item on the platform (find-or-create by default) using a short summary plus a standalone Markdown evidence artifact within one active system/framework scope. Evidence artifacts must not contain section headers, standalone bold labels, or gap/issue/remediation-backlog discussion.

Create and link multiple evidence items within exactly one active system/framework scope. Evidence artifacts must not contain section headers, standalone bold labels, or gap/issue/remediation-backlog discussion.

Append an action or milestone to a draft canonical Issue treatment plan.

Create the next editable treatment-plan version for a canonical Issue.

Persist an agent-authored work plan locally to ~/.pretorin/plans/<id>.json. Plans are the persistence layer for the canonical agent execution contract — a declarative, resumable, auditable record of scope, intent, steps, expected outputs, and acceptance criteria. A future session can resume, replace, or audit the work via the returned plan id. Plans are local-only today; nothing in the platform contract changes when a plan is written. Returns the full plan record including the generated plan id. When steps are omitted, the plan is created as a draft and must be activated before platform writes.

Create a custom risk in a system's register. Pass `treatment` + `treatment_plan` + `treatment_due_date` to record a mitigation in one call. Auto-link is opt-in: supply `framework_id` AND `suggested_control_families` (and the system must have ControlImplementation rows for that framework) — otherwise the risk is created with zero links and the agent should follow up with link_risk_artifact.

Create an asset-scoped STIG checklist bound to a benchmark + asset. Returns the new checklist summary (including its id). Fails if one already exists for that (benchmark, asset), or if the benchmark/asset is unknown. Create-or-resolve a checklist this way before importing scanner output.

Create a new vendor entity. Required: name, provider_type (csp, saas, managed_service, internal). Optional: description, authorization_level, owner_user_id, inherent_risk.

Create a contact for a vendor. Requires the server-side `vendor.pii` scope (or an admin token). Setting is_primary auto-demotes the prior primary contact.

Create a contract for a vendor. Requires the server-side `vendor.pii` scope (or an admin token). status and is_expired are server-derived and cannot be set.

Delete an evidence item from the platform (system-scoped, requires WRITE access)

Delete an action while its canonical Issue treatment plan is still a draft.

Delete a vendor entity.

Delete an org-scoped custom or imported vendor assessment template.

Delete a vendor contact. Requires the server-side `vendor.pii` scope (or an admin token).

Delete a vendor contract. Requires the server-side `vendor.pii` scope (or an admin token).

Detach a system from a vendor.

Close a recipe execution context and return the RecipeResult summary (status, evidence, narrative, and Issue counts, errors, elapsed time). Pass recipe_context_id returned by start_recipe; legacy context_id is accepted only for backwards compatibility. Must be called once the recipe's work is complete; failure to call leaves the context in place until the 1-hour expiry sweep.

Export a checklist to a local file as DISA .ckl (XML) or .cklb (JSON). Regenerated on demand (air-gap/FIPS-safe; no eMASS connector needed). Writes to output_path and returns {path, format, size_bytes, sha256} — the raw file is written to disk, not inlined in the response. Read the written file for the checklist content. Refuses an existing output_path unless overwrite=true, and never writes through a symlink.

Mark an active plan as failed after an unrecoverable execution error. The terminal transition is sticky. Post-mortem delivery is best-effort and cannot change the failed result.

Generate read-only AI drafts for a control narrative, evidence recommendations, and recommended issues using the same Codex agent workflow as the CLI

AI-generate a grounded inheritance narrative for a control, using the vendor's evidence and documentation.

Synchronously generate or reuse the Risk Assessment Report (RAR) for one system/framework. Replay with force_regenerate=false is idempotent and returns the existing document ID with already_generated=true.

Read the active recipe set for the active (or given) scope — the curated subset of the cookbook provisioned for this compliance effort — plus a provisioning proposal: the recipes runnable on this host (candidates), source kinds ready but covered by no recipe (coverage_gaps), and active recipes whose pinned version has drifted (drift). Call this during preflight to seed the active set, and whenever deciding what to run.