Changelog

All notable changes to the Pretorin CLI are documented here. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.24.2 - 2026-06-28

Changed

• Maintenance sweep — code health and documentation sync. No user-facing CLI, MCP, or schema changes. Deduplicated the evidence MCP handlers’ override-validation into a shared resolve_override_or_error helper, added InSpec/OpenSCAP scanner unit tests, refreshed uv.lock (no vulnerabilities), and re-synced every documentation reference surface — README, CLI.md/MCP.md, command reference, MCP tool counts (129 static + 22 per-recipe-script), framework pages, environment variables, and the llms.txt manifests — against live CLI/MCP behaviour, rebuilding the committed mdBook output.

0.24.1 - 2026-06-27

Fixed

• Binary distribution follow-ups. The release pipeline now mirrors the air-gap OCI archive and SBOMs to the public tap, includes every shipped SBOM in the signed SHA256SUMS, and verifies the air-gap archive token-free from the tap before declaring a stable release customer-ready.
• Keyed cosign verification docs and gates. Binary-distribution docs now include the required --insecure-ignore-tlog=true flag for keyed signatures without Rekor entries.
• Release hardening. The reusable binary build receives only explicit Apple notarization secrets, the Homebrew formula renderer fails closed when a real release manifest omits a platform asset, release tap pushes retry safely after rebase failures, and pretorin link --force no longer auto-removes a directory at the canonical MCP path.

0.24.0 - 2026-06-26

Added

• Scope artifacts — “scope” is now more than the questionnaire (epic #212). A complete capability to produce and connect the system-spec scope artifacts (authorization boundary, network data-flow diagram, PPSM, interconnection, and the asset inventory) so they appear attested on the platform’s scope page rather than as orphaned evidence rows.
  • scope-artifacts workflow + scope_artifacts intent verb. start_task routes scope-artifact intent to a dedicated workflow (distinct from the answer questionnaire loop) that walks each system-spec kind: produce → upload → link → attest.
  • Three system_spec MCP write tools — link_spec_snapshot, attest_spec_snapshot, attest_spec_inventory — wrapping the platform’s /spec/snapshots/* and /spec/inventory/attest endpoints. kind is free-form (validated against list_artifact_requirements) so the CLI can’t drift from the platform’s kind registry. All three are workflow-tier writes that thread plan_id / step_index and record PlanArtifacts (new kinds spec_snapshot_link, spec_attestation) into the plan’s produced_artifacts[] audit chain.
  • Plan completion gate all_required_spec_kinds_attested. A new typed AcceptanceCriterionKind whose evaluator refuses complete_plan until every required (non-toggled-off) system_spec kind on the system is attested — turning the epic’s Definition of Done into a machine-checkable gate. It fails closed: a read failure or malformed response refuses completion rather than passing vacuously. Workflows declare default gate criteria via a new acceptance_criteria field on the workflow manifest, and start_task seeds them onto the plan at instantiation.
  • General-purpose HTML evidence composer (pretorin.evidence.html). A reusable sibling to the markdown composer: compose_html_document wraps a body fragment (inline SVG diagram, a table) in a self-contained, design-consistent Pretorin-branded document shell (inline brand CSS, no external resources, no web-app chrome) with a provenance footer; render_table renders escaped brand-styled tables. Markdown stays the default; HTML is the opt-in path for rich-visual evidence. A documented SVG class vocabulary keeps agent-authored diagrams consistent without a layout engine.
  • scope-artifact-compose recipe — the first consumer of the composer; produces each snapshot-kind document (diagram or table) from reachable sources with redaction and provenance, ready for the workflow to upload + link + attest.
  • Richer diagram vocabulary + completeness guidance. The brand kit gained pt-cluster / pt-external / pt-actor / pt-flow-mgmt classes so boundary and network/DFD artifacts can represent the compute substrate, external systems, human actors (incl. developers/operators), and the management/control plane — not a “users → app → db” sketch. The recipe and workflow carry a Completeness checklist (actors, compute substrate, management plane, CI/CD, every external integration/identity provider, data stores, ingress/egress, public-vs-private connectivity) and direct the agent to reconcile the diagrams against the scope narrative (get_scope).
  • Clean, full-size diagrams. The recipe documents a generic layout technique — trust-tier lanes (actors → edge → compute substrate → managed services → externals), orthogonal connectors routed in the gutters, services columns ordered to match their consumers, and bundled egress trunks — so connectors and labels don’t cross. Out-of-scope systems are kept out of the diagram view (they belong in the scope narrative, not the boundary). A new wide document mode (compose_html_document(wide=True) → pt-doc-wide + a horizontally-scrolling pt-figure, plus a wide param on the compose recipe script) renders a large boundary/DFD at full size instead of squeezing it into the 760px prose column. An optional geometry helper pretorin.evidence.svg_layout (SvgCanvas + anchor + route_*) implements the layout moves — boxes, zone/cluster/boundary containers, orthogonal connectors with arrowheads, collision-aware labels, all emitting the pt-* classes — so agents don’t hand-roll diagram geometry; it’s an authoring aid, not an auto-router, and hand-written SVG stays fully supported.

Fixed

• start_task validation errors are now path-qualified for missing entities fields. Missing prompt-derived fields such as intent_verb and raw_prompt now surface as entities.intent_verb / entities.raw_prompt, plus a reminder that all prompt-derived inputs must be nested inside the entities object.
• end_recipe accepts recipe_context_id for parity with sibling MCP tools. The legacy context_id alias remains supported with a deprecation warning, empty or null context arguments now receive the canonical missing-argument error, and the MCP reference/workflow examples now teach recipe_context_id.
• Pending-question routing dead-end (#208). start_task routed a completed scope to the dead-end scope-question workflow because the router ran bool() on the get_pending_*_questions dict (always truthy) instead of reading pending_count. Fixed for both the scope and policy paths, and the scope-artifact intent now has a real destination.
• answer_scope_question / answer_policy_question doc mismatch (#209). The scope-q-answer / policy-q-answer recipes and the scope-question / policy-question workflows instructed the agent to pass a recipe_context_id the tools don’t accept; reconciled all four bodies to the actual schema (the active recipe context is applied server-side).
• Stale system_spec client payloads. link_snapshot sent evidence_id (server wants evidence_item_id); attest_snapshot / attest_inventory sent rationale instead of the required sufficiency envelope. Corrected to the platform contract.
• MCP schema enum drift. The start_task intent_verb enum and the create_plan acceptance-criterion kind enum are now pinned by tests to their Python source-of-truth (the IntentVerb Literal / ACCEPTANCE_CRITERION_KINDS) so a newly-added verb or kind can’t silently become unreachable over MCP.
• System-spec DX fixes (from live SOC 2 dogfooding). submit_asset_inventory_diff now documents the platform-validated enums for asset_type / environment / data_classification (a wrong value 422s); the sufficiency.canonical_source_id field is documented as requiring a bound-source reference (a free-form string is rejected by the platform — the other sufficiency fields are accepted on their own); and pretorin scope artifacts inventory scan no longer loses the [cloud-inventory] extra to Rich markup, so the SDK-missing hint correctly reads pip install 'pretorin[cloud-inventory]'.

Documentation

• Rewrote docs/src/workflows/system-spec.md to cover the new CLI/MCP path for producing and connecting the four snapshot kinds (no longer platform-UI-only) and corrected the stale kind taxonomy.
• Documented the three new MCP tools and the scope-artifacts workflow across the tool and workflow references.

0.23.10 - 2026-06-25

Fixed

• Recipe-context evidence tally and produced-evidence ids (end_recipe) — fixes walkthrough Bug #14 where end_recipe returned evidence_count: 6 after the agent’s 3 actual evidence creations and evidence_ids: [] despite those creations. Two bugs collapsed into one:

  • ContextStore.record_evidence_write was called inside _build_audit_metadata_for_write before the platform write happened. Every retry, every dedupe-hit, every payload-validation failure bumped the count without producing a row. The bump has moved to the handler’s post-write path and is now gated on EvidenceUpsertResult.created is True for the single-evidence path and on the batch result’s per-item status == "created" for the batch path. Dedupe reuses, link-only reuses, and errored items no longer move the count.
  • ExecutionContext.evidence_ids was an input-only field (evidence the caller passed to start_recipe for narrative-citing recipes), but RecipeResult.evidence_ids returned the same list, conflating “supplied” and “produced”. A new produced_evidence_ids: list[str] field carries the ids of new rows the recipe actually created, in creation order. The input evidence_ids field is preserved unchanged so existing narrative-recipe callers continue to work.

• Updated record_evidence_write signature — now accepts an optional evidence_id keyword that, when supplied, also appends the id to ctx.produced_evidence_ids. The legacy id-less form (count-only bump) is preserved for tests.

• Docstrings on ExecutionContext.evidence_count and the two evidence_ids fields rewritten to spell out the dedupe-exclusion semantics and the input-vs-produced distinction so future readers can’t recreate the same confusion.

• 4 new regression tests in tests/test_mcp_recipe_handlers.py: dedupe hits don’t bump the count, mixed create/dedupe scenarios count only created rows, input and produced id lists stay distinct end-to-end, and the batch path counts only items whose platform status is created. Full pytest suite green: 3105 passed.

• Plans Phase B3 — step_index=0 on campaign-workflow plans no longer short-circuits the B3 audit chain. resolve_plan_coordinates previously raised PlanStepError (“step_index 0 out of range; plan has 0 step(s)”) whenever a caller passed any step_index on a plan that didn’t pre-populate plan.steps — which is every campaign-workflow plan, because campaigns list their controls in scope.extra.control_filter rather than as explicit steps. The error short-circuited the handler before record_plan_artifact_safely could append to produced_artifacts[], silently breaking the B3 audit chain for every multi-control walkthrough in production. Discovered during the SOC 2 walkthrough on pretorin-public-platform: 13 successful MCP writes (status, link_evidence, create_evidence, update_narrative, resolve_control_issue) all carrying plan_id + step_index=0 produced zero produced_artifacts[] entries; the underlying record path was fine, the bounds check was wrong. The fix only enforces step_index < len(plan.steps) when the plan has at least one explicit step; for stepless plans (campaigns and anything similar), the write proceeds and step_index is dropped to None rather than stored as a pointer to a step that doesn’t exist — so the audit chain never claims an artifact came from a fictional step. Negative-integer rejection, bool rejection, and the in-range bounds check on plans that do declare steps are all preserved. Two regression tests added in tests/test_mcp_plan_coordinates.py.

• MCP tool schema docs — start_task / start_recipe / create_evidence / create_evidence_batch. Clarified three documentation gaps surfaced during the SOC 2 walkthrough:

  • start_task: tool description and the entities property description now explicitly call out that all prompt-derived fields (intent_verb, raw_prompt, system_id, framework_id, control_ids, scope_question_ids, policy_question_ids) must be nested inside the entities object, with only active_system_id / active_framework_id / skip_inspect at the top level. Flattening prompt entities was a common caller bug; such top-level copies are ignored by the handler (not rejected), so the route is decided from entities alone.
  • start_recipe: the recipe_version property description now points callers at get_recipe(recipe_id).manifest.version (or the version field returned by list_recipes) and warns against hard-coded values that will break when the recipe registry advances.
  • create_evidence / create_evidence_batch: the source_locator property description now explains the platform-side audit-metadata contract (issue #701), the handler’s auto-derive-from-code_line_numbers fallback, and that non-code sources (policy excerpts, docs, vendor reports, dashboards) must pass an explicit locator like section 3.7 / page 4 paragraph 2, otherwise the platform rejects the write with Missing: source_locator.

  Docs-only change — no schema shape, handler, or platform-contract changes. The three issues were observed during the SOC 2 CONF-001 walkthrough on pretorin-public-platform; the descriptions surface at MCP tool introspection time, so future agent callers see them without code changes.

Added

• pretorin plan prune — manual housekeeping for ~/.pretorin/plans/. Removes terminal plans (completed or cancelled) whose terminal timestamp is older than --older-than-days (default 30). Active plans are NEVER pruned regardless of age. Defaults to interactive confirmation; --yes skips the prompt, --dry-run previews the action without touching disk, --include-corrupt opts the operator into deleting unparseable plan files (the default reports them only).

0.23.9 - 2026-06-19

Added

• Plans Phase B4 polish - MAX_ACCEPTANCE_CRITERIA cap (32). The Plan model rejects any acceptance_criteria list longer than the cap via a @field_validator that fires at both create time and load time, with matching early-rejection guards in PlansStore.create and handle_create_plan so an over-cap input never reaches per-item Pydantic validation. The MCP create_plan inputSchema advertises maxItems: 32 so MCP clients can reject locally without a round-trip. Together these layers close a fan-out DoS surface where an agent (or hand-edited plan file) could declare thousands of criteria and force complete_plan to make a corresponding number of platform reads.
• Plans Phase B4 polish - log-on-exception in the acceptance fetcher adapter. _PretorianClientAcceptanceFetcher.get_narrative and get_evidence_count_for_control previously swallowed every PretorianClient exception silently and returned the fail-safe value (None / 0). They now also emit a logger.warning(...) carrying sanitized metadata - exception type plus HTTP status code when the exception is a PretorianClientError - but never the raw exception message, which could leak platform response bodies, validation values, URLs, or attacker-controlled newlines (log-injection surface). The fail-safe behaviour is unchanged: the acceptance evaluator still surfaces “no narrative found” / “0 evidence linked” failures so the gate stays deterministic, while transient platform / network issues now leave a debuggable trail.

Changed

• Backward compatible: no MCP / CLI / schema-shape changes. Existing plan files with <= 32 criteria load unchanged; plan files with > 32 criteria would now fail to load with a clear error citing the cap and the actual count - accepted regression to close the DoS surface, no such plans exist in practice today.
• Maintenance: shared control-annotation sync helpers. pretorin notes and pretorin issues are two CLI command groups over the same underlying platform concept (a control annotation) and their list/add/resolve flows were near-identical copies. The shared logic now lives in src/pretorin/cli/_control_annotations.py - a frozen AnnotationKind descriptor (NOTE / ISSUE) parameterises the platform-client method names and display terminology, and issues.py / notes.py shrink to thin call-throughs (~169 lines each removed). No CLI surface, flag, or output change; the refactor exists to prevent the two groups drifting apart.

Fixed

• Maintenance sweep: coverage, lint, version consistency, and a full documentation audit. Raised cli/issues.py from 17% to 100% line coverage with a new tests/test_cli_issues_coverage.py suite; applied ruff format to tests/evidence/test_audit_metadata.py; and verified the version is aligned across pyproject.toml, __init__.py, both changelogs, and the install-doc expected output. The accompanying docs audit re-synced every reference surface against the live CLI/MCP behaviour - README, CLI.md/MCP.md, the CLI command reference and feature pages, MCP tool counts and the OSCAL artifact category, framework counts and the tier-2 catalog, the USER environment variable, and the llms.txt / llms-full.txt manifests - then rebuilt the committed mdBook output and confirmed no dead or unresolved internal references remain.

0.23.8 - 2026-06-18

Fixed

• MCP start_task inspect-status system resolution (#191): inspect_status now resolves an explicitly named system to its canonical UUID before reading workflow state, pending families, pending scope questions, and compliance status. Unknown explicit system names fail as top-level MCP errors instead of returning an apparently successful response with per-section System not found errors. Active-context UUIDs still use the cheap path when no system is named.

0.23.7 - 2026-06-17

Added

• Plans flow - Phase B4: Plan.version + acceptance-criteria gate on complete_plan. The Plan model now carries a monotonic version: int counter (default 1) and an acceptance_criteria: list[AcceptanceCriterion] (default empty). All three mutation methods on PlansStore (update_step, complete, cancel) and their MCP handlers accept an optional expected_version for optimistic locking - mismatched versions return a structured version_conflict error with both expected and actual versions in the JSON body so the caller can reload and retry. complete_plan runs a server-side acceptance gate when the plan declares criteria: each criterion is evaluated against current platform state (narrative existence and length, evidence count linked to the control, AI-review status), and any failures return a structured acceptance_failed error carrying the full failed_criteria[] list so the agent fixes every gap in one shot. The plan stays active on a failed gate so the agent can address the gap and retry. Empty acceptance_criteria preserves pre-B4 behaviour (no gate, last-write-wins). A TOCTOU guard pins the plan version we evaluated against through the actual complete() write, so concurrent mutations between gate evaluation and state transition are detected.
• Four typed acceptance-criterion kinds (RFC Decision 3): narrative_min_chars (params: {min_chars: positive int}), every_claim_cites_evidence (no params; first-cut interpretation checks the narrative exists and the control has >= 1 linked evidence item), ai_narrative_reviewed (no params; only fires on AI-drafted narratives), min_evidence_count_per_control (params: {min: positive int}). Per-kind params shape is enforced by a pydantic model validator at create and load time (defence-in-depth against hand-edited plan files).
• New pretorin.plans_acceptance module with the per-kind evaluator functions and an orchestrator evaluate_plan_acceptance(plan, fetcher) that returns the structured failure list. Evaluators depend on a narrow PlanAcceptancePlatformFetcher protocol - the production adapter (_PretorianClientAcceptanceFetcher in the handler module) wraps PretorianClient with per-call memoisation so multiple criteria over the same scope share one round-trip per signal type; tests pass an in-memory fake. Fail-closed semantics: unknown criterion kind or unexpected evaluator exception is recorded as a failure, never a silent pass.
• MCP schema and CLI render: create_plan advertises acceptance_criteria array on each step item; update_plan_step, complete_plan, and cancel_plan advertise expected_version (integer, min 1). pretorin plan show renders version next to the plan id and a dedicated Acceptance criteria section listing each criterion with truncated inline params; sections are elided when empty so pre-B4 plans render unchanged.
• Vendor public-API parity for Phase 1 TPRM: pretorin vendor list now understands the paginated {items,total} vendor-list response introduced by the platform and fetches all matching pages by default; list filters/sorting are exposed across CLI and MCP (search, provider type, residual risk tier, owner, assessment status, sort key/direction). Vendor create/update now support owner_user_id and inherent_risk, and pretorin vendor history plus MCP get_vendor_history mirror the public /vendors/{id}/history endpoint.

Changed

• Backward compatible: PLAN_SCHEMA_VERSION stays at 1. Existing ~/.pretorin/plans/*.json files written before this version load cleanly with the new defaults applied (version=1, acceptance_criteria=[]), and step-status changes via update_step deliberately do not bump version per RFC Decision 2 (progress, not structural edit). 73 new regression tests cover the model invariants, the optimistic-locking conflict path, each evaluator’s pass/fail/edge cases, the orchestrator’s fail-closed behaviour, the MCP handler’s gate + structured-error mapping, and the CLI render of the new fields.
• Vendor inherent-risk vocabulary: CLI docs, tests, and MCP/skill descriptions now use the canonical four-band vocabulary low/moderate/high/critical. The deprecated input alias medium is accepted by CLI create/update, normalized to moderate, and warned in human-readable output.

0.23.6 - 2026-06-17

Added

• Public OSCAL artifact list/download (pretorin oscal artifacts). New read-only command group over the platform’s public OSCAL artifact endpoints, for the machine-readable export path (e.g. the FedRAMP RFC-0024 package pipeline): list (validated artifacts for a system, filterable by --type/--framework/--assessment), show <id> (metadata + two-tier validation report), download <id> (SHA-256-verified against checksum_sha256; the file is not written and the command exits non-zero on mismatch), and latest --type <type> [--download] (newest validated artifact of a type; exits non-zero when none exists). Only generation_state=succeeded + validation_status=valid artifacts are returned. Presigned download URLs are fetched without the platform token so credentials never reach object storage. Generation stays app-surface — the CLI is consumer-only. Adds read-only MCP tools list_oscal_artifacts / get_oscal_artifact. Mirrors monorepo#1100; depends on the public endpoints from monorepo#1150.

0.23.5 - 2026-06-15

Added

• Plans flow — Phase B2: typed PlanStep parameters. PlanStep now carries two new optional fields: recipe_version (string, max 50 chars, only valid when kind == "recipe") and params (free-form JSON-serialisable dict, capped at 8 KiB serialised via the new MAX_STEP_PARAMS_BYTES constant). A pydantic model validator rejects recipe_version on any non-recipe step at both create time and load time (defence-in-depth against hand-edited plan files), so a future auditor can trust that a versioned step actually points at a real recipe. The MCP create_plan inputSchema advertises both new fields on each step item, and pretorin plan show renders them inline — recipe_version as a v<version> suffix on the step line, params truncated to 100 chars on a ↳ params: continuation line (the full payload is always available via --json / get_plan).

Changed

• Backward compatible: PLAN_SCHEMA_VERSION stays at 1. Existing ~/.pretorin/plans/*.json files written before this version load cleanly with the new defaults applied (recipe_version=None, params={}), and update_plan_step preserves both fields across status transitions. New regression tests cover the round-trip, the legacy-load path, the size-cap and JSON-serialisability guards, and the model-validator’s reject-at-load behavior.

0.23.4 - 2026-06-13

Changed

• Automated maintenance + documentation sync: consolidated the duplicated inline error-and-exit pattern in the risk and vendor CLI surfaces onto the shared exit_with_error helper (pretorin risk create/update/attest/link add, pretorin vendor create/update/upload-doc), so validation failures are reported consistently and honor JSON output mode; added regression coverage for evidence audit-metadata handling; and refreshed the dependency lockfile. Doc sources, the MCP tool reference and overview, the CLI command reference, llms.txt manifests, and the rebuilt mdBook output were re-synced against the current CLI/MCP/agent surface. No behavior changes for end users.

0.23.3 - 2026-06-12

Fixed

• Active system/framework context is now enforced on every agent write path. Previously an agent could make platform writes against a system/framework that was not the active context: start_recipe opened a recipe-execution row with no scope check, an agent could bypass the existing write guards by passing allow_scope_override, and several framework-scoped workflow writes (answer_scope_question, trigger_scope_generation/_review, trigger_family_review, patch_scope_qa) never checked the active context at all. Enforcement is now on by default in the scope resolver (read-only handlers opt out explicitly), agents can no longer self-authorize a cross-context write — allow_scope_override is ignored on every agent path and removed from the MCP and built-in-agent tool schemas, remaining a human/CLI-only capability — and the bypassing workflow writes now go through the shared guard. Only switching the active context with pretorin context set moves the boundary. Scope: this closes the framework axis (same system, different framework); cross-system tools (risks/vendors/STIG/asset-inventory), checkpoint-driven campaign tools, and org-level policy writes are intentionally out of scope.

0.23.2 - 2026-06-11

Changed

• Managed Codex runtime pin: bumped the bundled Codex binary pin from rust-v0.135.0 to rust-v0.137.0 with refreshed SHA256 checksums for macOS arm64, macOS x64, and Linux x64.
• Codex pin automation now opens PRs: the scheduled GitHub Action now writes the generated runtime-pin update to an automation/codex-runtime-pin branch and opens or updates a pull request instead of creating a tracking issue. The macOS assessment job also reads annotated constants correctly when extracting the pinned checksum map.

0.23.1 - 2026-06-10

Added

• Plans flow — Phase B1: start_task instantiates a plan and returns plan_id. When the routing layer settles on a non-ambiguous, non-null selected_workflow, the engagement handler now persists a Plan record from the resolved scope and stamps the new EngagementSelection.plan_id field. Agents can drive subsequent execution from the plan via get_plan / update_plan_step / complete_plan. create_plan remains agent-callable for advanced cases per the resolved design decision. Backward compatible: every existing EngagementSelection field is preserved, agents that don’t read plan_id keep working unchanged.

Changed

• inspect_status, ambiguous routing, and hard cross-check errors continue to skip plan creation (read-only, undecided, and bogus-entity flows respectively). Plan-store failures during start_task are non-fatal: the routing decision still returns cleanly with plan_id=None, so a transient local disk problem doesn’t break the agent’s session.

0.23.0 - 2026-06-10

Added

• Agent-authored work plans (Phase A — plans foundation). Local plan persistence layer under ~/.pretorin/plans/<uuid>.json with atomic writes, traversal-safe UUID-only paths, schema versioning, and a state machine (active → completed | cancelled). The plan model captures workflow id, scope (system/framework/control), intent summary, intent inputs snapshot, ordered typed steps (kinds: recipe, policy_link, issue, note, other), and lifecycle timestamps.
• Six new MCP tools for plan lifecycle: create_plan, get_plan, list_recent_plans, update_plan_step, complete_plan, cancel_plan. All six expose schema-validated input schemas; plan reads (get_plan, list_recent_plans) are reference-tier and the four write tools also classify as reference rather than workflow-tier — in the destination model a plan is the result of routing, not gated behind it.
• pretorin plan CLI surface. Operator-side commands pretorin plan list, pretorin plan show <id-or-prefix>, pretorin plan cancel <id-or-prefix>; plan authorship is deliberately not exposed to the CLI (agent-side concern).
• Draft RFC docs/rfcs/draft-plans-flow.md documenting the six-phase platform view (prompt → routing → planning → execution → review → audit), what each of the four workflows does, the plan lifecycle, and three worked examples mapping concrete user prompts to instantiated plan records. Records the three design resolutions: create_plan stays agent-callable alongside start_task; plans are mutable with monotonic version bumps; complete_plan runs the acceptance-criteria gate server-side. Subsequent phases (B1–B4) land as patch releases.

0.22.19 - 2026-06-07

Changed

• Automated maintenance + documentation sync: lint, format, and mypy strict passes across the source tree; manual scanner test coverage raised from 0% to 100%; refactor that consolidates the duplicated _require_system_id guard used by the MCP artifact and risk handlers into a shared helper; dead-code removal (unused YELLOW color constant, unreachable codex_bin_dir property, unused client-config field, stale MCP smoke import); dependency lockfile refresh to the latest compatible versions. Doc sources, llms.txt manifests, README, and the rebuilt mdBook output were re-synced against the current CLI/MCP/agent surface — adding the v0.22.18 risk posture and DSSE risk-attestation commands to CLI.md, MCP.md, the CLI command reference, the risks feature page, and the LLM manifest; documenting the cloud-inventory dependency group and the AWS/Azure scanner environment variables; clarifying agent-skill runtime applicability; refreshing framework counts; and validating cross-references across every doc page. No behavior changes for end users.

0.22.18 - 2026-06-04

Added

• pretorin risk posture <system_id> — system-scoped risk posture summary mirroring the new GET /api/v1/public/systems/{id}/risks/posture endpoint. Returns inherent + residual distribution buckets, weighted-average residual, overdue-attestation count, and the top 5 risks by residual score.
• pretorin risk attest <system_id> <risk_id> --type ... --statement ... — produces a DSSE-signed attestation over the current risk state via POST /api/v1/public/systems/{id}/risks/{rid}/attest. The signed payload reuses the existing evidence attestation signer + key registry, so verifiers resolve trust uniformly. --type is validated client-side against residual_accepted | mitigation_approved | inherent_validated so typos don’t waste a network round-trip.
• pretorin risk attestations <system_id> <risk_id> — lists DSSE envelopes for a risk, newest first.
• PretorianClient.get_risk_posture, attest_risk, list_risk_attestations.

0.22.16 - 2026-06-01

Fixed

• Asset-inventory scans no longer report a hard failure as an empty result. The asset-inventory-azure-baseline recipe (and the AWS, Kubernetes, and IaC-workspace recipes) now distinguish “the scan broke” from “there are genuinely no assets”: failures are surfaced in an errors list instead of silently returning scanned: 0. pretorin scope artifacts inventory scan now exits non-zero and prints the cause when a scan reads nothing, and warns (without retiring assets) when a scan is only partial.

Added

• Optional cloud-inventory dependency group (pip install 'pretorin[cloud-inventory]') declaring the AWS and Azure SDKs the asset-inventory recipes need. Without it, scans return an actionable install hint instead of failing silently.
• AWS asset inventory now enumerates all opted-in regions concurrently (EC2 is regional); set AWS_REGION to scan a single region. Azure subscription is resolved from AZURE_SUBSCRIPTION_ID or the logged-in az default.

0.22.15 - 2026-05-30

Changed

• Automated maintenance + documentation sync: lint, type-check, and dependency-audit fixes, expanded test coverage on the issues writer/sync surface and API client retry paths, dead-code removal, plus refactor of the CLI’s repeated print error / sys.exit(1) pattern into a shared exit_with_error helper. Doc sources, llms.txt manifests, README, and the rebuilt mdBook output were re-synced against the current CLI/MCP/agent surface — adding the issues CLI page, evidence search RAG flags, DSSE attestation surfaces, recipe-scoped writes, and refreshed framework/MCP tool counts. No behavior changes for end users.

0.22.14 - 2026-05-29

Fixed

• pretorin update no longer trusts a stale “already latest” check as final: no-argument updates still check PyPI for user-facing context, but they now run the installer when that check reports the current version. This lets uv/pipx/pip confirm with a refreshed/no-cache install path instead of exiting early on stale CDN metadata, while avoiding downgrades when the installed version is newer than PyPI’s latest.
• PyPI-confirmed uv updates use an exact refreshed version: when the update check sees a newer version, uv-managed installs now run uv tool install --force --refresh pretorin==<version> instead of pretorin@latest. If verification still sees the old version, the manual recovery hint also names that exact refreshed command.

0.22.13 - 2026-05-29

Fixed

• pretorin update refreshes uv’s package index for latest installs: uv-managed no-argument updates now run uv tool install --force --refresh pretorin@latest, keeping uv as the resolver while forcing it past stale cached index data. This prevents the observed one-version-at-a-time upgrade path where a fresh 0.22.12 release first resolved only to 0.22.11.

0.22.12 - 2026-05-29

Fixed

• pretorin update restores latest/current feedback without reintroducing uv pinning: no-argument updates check PyPI first and print either “already on the latest version” or the available upgrade, but still dispatch uv’s unpinned pretorin@latest install path so the installer resolves against its own index view. Failed version checks now fall back to attempting the installer update instead of blocking the user.
• pipless venvs can update through uv: uv-created virtualenvs, plus other current Python environments that do not have pip but do have uv on PATH, now route pretorin update through uv pip install --python ... --upgrade --refresh pretorin instead of python -m pip. The installer subprocess also preserves detected uv/pipx tool homes for custom tool directories.
• pretorin update avoids local import shadowing: installer and verification subprocesses now run from the active venv root (or home directory fallback) and strip PYTHONPATH/PYTHONHOME, preventing untrusted working-directory files such as pip.py or pretorin.py from shadowing the real packages during self-update.

0.22.11 - 2026-05-29

Changed

• Evidence and narrative guidance plus write validation now keep gaps, missing evidence, ambiguity, and remediation work out of artifact text and record them only as control issues.
• Evidence Markdown now normalizes headings to report-safe bold section labels, with pretorin evidence format-markdown available for file/stdin reformatting.

0.22.10 - 2026-05-29

Added

• Control issues workflow: Added the first-class pretorin issues CLI, matching MCP/agent issue tools, local issue writer/sync support, and issue-driven campaign targeting with issues-fix plus --all-open-issues selectors.

Changed

• Legacy notes commands and tools remain compatibility aliases while docs, prompts, receipts, and campaign generation now prefer issue terminology for durable gaps and remediation work. Issue and note resolution requests also percent-encode path IDs and require explicit resolution justifications.

0.22.9 - 2026-05-28

Fixed

• MCP recipe-context audit trail hardening (#958, #959, #963, #964): get_control_implementation now reports the canonical narrative source, note writes require a dedicated control-note-attestation recipe context, narrative writes reject evidence-only or cross-control contexts, and workspace-capture markdown artifacts no longer get wrapped in an extra code fence that breaks nested fences.

0.22.8 - 2026-05-27

Added

• Evidence DSSE attestation: get/verify CLI + MCP (#150): New pretorin evidence attestation get and pretorin evidence attestation verify subcommands surface the platform’s DSSE in-toto attestation envelopes (ADR 0003) to auditors and CI pipelines. The verifier independently checks the ECDSA P-256 + SHA-256 signature over the DSSE PAE bytes, resolves the signing key through GET /api/v1/public/keys rather than trusting any embedded PEM, and honors key validity windows, revocation, and environment labels — exit 0 on success, 1 with a reason on failure. The matching get_evidence_attestation MCP tool lets external agents fetch the envelope (plus an optional lineage view) for any evidence record. New cryptography>=42.0.0 runtime dependency.

0.22.7 - 2026-05-26

Added

• Scoped evidence RAG search (#148): search_evidence now accepts a natural-language query across the CLI, MCP handler, and agent tool surface. Query mode searches attached evidence plus scoped reusable unattached evidence, including policy documents, before agents create new evidence.

Changed

• Agent and workflow guidance now tell control-update flows to search existing evidence semantically, link relevant unattached evidence, and cite those evidence IDs in updated narratives.

0.22.6 - 2026-05-23

Changed

• Automated maintenance + documentation sync (#147): lint/type-check fixes, test coverage and dead-code cleanups, dependency vulnerability patches, and version/registration consistency tweaks across the codebase. Doc sources, llms.txt manifests, and the rebuilt mdBook output were re-synced against the current CLI/MCP/agent surface, including the system-spec workflow entry, STIG/CCI tooling tables, and SOC 2 control-ID format notes. No behavior changes for end users.

0.22.5 - 2026-05-22

Fixed

• System-spec evidence type parity (#145): the CLI now accepts the platform’s five system_spec_* evidence types (system_spec_inventory_attestation, system_spec_boundary_diagram, system_spec_network_dfd, system_spec_ppsm, and system_spec_interconnection) across evidence validation, MCP/agent prompts, audit metadata source-type defaults, and CLI error/help output. This prevents system-spec snapshot evidence returned by the platform from being rejected or hidden by the CLI.

0.22.4 - 2026-05-22

Fixed

• MCP resolve_control_note no longer 400’s Claude-based clients: the tool’s input schema declared a top-level allOf to express “resolution_note is required when is_resolved is true”. Claude’s API rejects anyOf/oneOf/allOf at the top level of tool input_schemas, so every Claude Code / Claude Desktop request against any pretorin MCP tool failed before reaching the handler. The conditional requirement now lives in the handler — the constraint is preserved, and the schema is Claude-API compatible.
• pretorin update detects uv/pipx installs outside the default folders: the installer detector now reads uv’s uv-receipt.toml and pipx’s pipx_metadata.json from the running venv before falling back to path heuristics. This keeps custom uv/pipx tool installs from falling through to python -m pip, which fails in tool venvs that intentionally omit pip.
• Update notices point at pretorin update: passive CLI/MCP status prompts no longer hardcode pip install --upgrade pretorin, so uv, pipx, and pip users all get the same installer-aware upgrade path.

0.22.3 - 2026-05-22

Fixed

• pretorin update no longer fails right after a fresh release: previous design pre-resolved the latest version via PyPI’s JSON metadata API and passed it to uv as a strict ==X.Y.Z pin. The JSON API can return a version moments before uv’s simple-index resolver sees it, so the pinned install failed with “No solution found.” Now pretorin update dispatches uv tool install --force pretorin@latest directly and lets uv be the single source of truth.
• Explicit-version updates use --refresh: pretorin update X.Y.Z passes --refresh to uv (and --no-cache-dir to pip/pipx) so the installer re-fetches the index before resolving.

Removed

• JSON-API pre-resolution + post-install verify dance: pretorin update no longer pre-resolves the target version or re-spawns Python after the install to verify. The installer’s exit code is the source of truth.

0.22.2 - 2026-05-21

Fixed

• Legacy agent — OpenAI strict-mode tool schemas (#136 bug 1): 20 platform tool definitions in pretorin.agent.tools declared optional parameters in properties without listing them in required. OpenAI’s strict-mode function-calling validator rejected the entire tools array before any model turn. Added _to_strict_schema which normalizes schemas at the SDK boundary: every property gets added to required, and optional properties become nullable unions (["string", "null"]).
• Codex agent — unhelpful “Connection lost” error (#136 bug 2): pretorin agent run (Codex runtime) was swallowing the exception class and chained cause. Now prints the exception class, caused by chain, and active runtime context (model + base_url) so the operator can tell which connection failed; same diagnostic block also wired into the legacy runtime.

0.22.1 - 2026-05-21

Fixed

• inventory show always reported empty (#133 follow-up): the CLI read the response under payload["assets"] but the platform returns asset rows under "items". Same bug caused inventory scan to misclassify every row as added (it diffed against an empty existing inventory). Both paths now read payload["items"].
• artifacts toggle always 422’d (#133 follow-up): the client posted {"optional": ...} but the server’s PATCH schema is keyed on toggled_off. Renamed the wire field while keeping the user-facing --optional/--required flag unchanged. The artifacts list renderer now reads either toggled_off or legacy optional defensively.

0.22.0 - 2026-05-21

Added

• System spec CLI + MCP surface (#133): new pretorin scope artifacts ... command group wraps the public /api/v1/public/systems/{id}/spec/* endpoints from monorepo PR #859. Operators can artifacts list, inventory show [--as-of T], inventory upload <csv>, inventory scan <source>, and artifacts toggle <kind> --optional --rationale "...". Three matching MCP tools (list_artifact_requirements, get_asset_inventory, submit_asset_inventory_diff) expose the same surface to AI agents. The diff endpoint accepts recipe_context_id but does not require it — the 11-field audit-metadata envelope is reserved for evidence writes.
• Four asset-inventory recipes: asset-inventory-aws-baseline (live EC2 via boto3), asset-inventory-azure-baseline (live Compute VMs via azure-mgmt-compute), asset-inventory-k8s-baseline (kubectl-driven enumeration of nodes + Deployment/StatefulSet/DaemonSet), and asset-inventory-iac-workspace (static parse of .tf / .tf.json / K8s YAML / CloudFormation files in the cwd — no cloud credentials required). All four ship as tier: official.

0.21.4 - 2026-05-19

Fixed

• MCP start-task routing and capture preflight (#126, #127): inspect_status now returns a bounded no-workflow status bundle without running the full routing cross-check, and platform validation outages now surface as structured upstream errors instead of false “not found” messages.
• AI-guidance evidence expectations (#127): start_task.suggested_capture_plan now falls back from control context to get_control(...).ai_guidance.evidence_expectations, so enriched controls such as AU-04 retain their recipe preflight plan even when the system control-context endpoint is unavailable.

Changed

• Workspace capture fallback (#127): workspace-capture is now the generic workspace evaluation/capture fallback for broad or unclassified evidence expectations, and capture-plan metadata identifies whether a recipe came from an expectation match or the fallback path.

Removed

• Legacy document requirements API: removed the obsolete get_document_requirements client/MCP surface and pretorin frameworks documents command. Evidence requirements are derived from AI guidance.

0.21.3 - 2026-05-19

Fixed

• pretorin update works on uv tool and pipx installs: the update command now detects how pretorin was installed by inspecting sys.executable and dispatches to uv tool upgrade pretorin or pipx upgrade pretorin when appropriate. Previously it always shelled out to python -m pip install --upgrade, which fails with No module named pip on recent uv versions because tool venvs no longer ship pip. Pinned upgrades (pretorin update X.Y.Z) route to uv tool install --force / pipx install --force so they work on isolated tool venvs too. Failure paths and the post-upgrade “ran but version unchanged” hint now name the right installer.

0.21.2 - 2026-05-18

Changed

• MCP recipe-required telemetry (#121): evidence and narrative producer guardrails now emit a PRETORIN_TELEMETRY_EVENT with event_type="recipe_required" and non-content shape metadata, letting operators compute the combined workflow/recipe bypass rate for the post-v0.21 trigger watch.

0.21.1 - 2026-05-16

Maintenance

• Automated maintenance + documentation sync pass (#122): lint/type-check fixes, test coverage improvements, dead-code removal, dependency vulnerability patches, version/registration consistency, and a repository-wide doc resync against the v0.21 surface (CLI/MCP/agent references, llms.txt manifests, and a fresh mdBook rebuild).

0.21.0 - 2026-05-15

Added

• Recipe/source MCP producer surface (#118): recipes can declare requires.sources, MCP exposes list_connected_sources and check_sources, start_task returns suggested_capture_plan, and list_recipes(system_id=...) filters to source-eligible recipes while failing open on older platform deployments.
• Narrative recipe support (#118): start_recipe accepts evidence_ids, update_narrative requires a narrative-producing recipe context with cited evidence ids, and the built-in evidence-narrative-compose recipe provides the canonical narrative path.
• Workspace capture floor recipe (#118): workspace-capture generalizes code capture for readable workspace files such as runbooks, policy drafts, scripts, configs, and exported reports.

Changed

• Recipe-only MCP writes (#118): MCP create_evidence, create_evidence_batch, and update_narrative now reject agent writes without recipe_context_id using a structured recipe_required error.

0.20.1 - 2026-05-15

Fixed

• Control note resolution parity (#760): MCP, CLI, and built-in agent note-resolution tools now expose and forward resolution_note, matching the platform UI’s audit-trail requirement for closing notes. pretorin notes resolve accepts --resolution-note / --justification, and local validation prevents closing a note without a justification.

0.20.0 - 2026-05-14

Changed

• MCP tool prefix dropped (#113, phase 3): every server-side tool name lost its leading pretorin_. Hosts see mcp__pretorin__check_context instead of mcp__pretorin__pretorin_check_context. Recipe-script tools follow the same rule (recipe_<id>__<script> instead of pretorin_recipe_<id>__<script>). Breaking change for any agent that hardcoded the old names — re-install the bundled skill (pretorin skill install) or update local references. Tier metadata, the intent-verb map, and the workflow-body schema-bundling regex all moved with the rename. The handler function names (handle_create_evidence, etc.) are unchanged — this only affects the wire-level tool identifier.

Added

• Cross-harness MCP tool surface (#113, phases 0-2): the MCP server now ships a small set of cross-harness discovery + grounding tools so Cursor, Codex, vanilla Agents SDK, and any other client can ground a session without depending on the initialize instructions block.
  • check_context — cheap, unauthenticated probe. Returns {connected, active_system, active_framework_id, suggested_next, pending_attention} with a deterministic next-step hint. Call once at session start.
  • list_tools — compact catalog. One short record per tool (name, purpose, tier, requires_workflow) plus tier counts. Cross-harness alternative to fetching every tool’s full schema just to browse. Tiers: default, reference, workflow, recipe.
  • get_instructions — callable mirror of the server’s instructions block, for harnesses that don’t render it.
  • Errors-as-instructions: write tools that fail because there’s no active routing context now return a structured {error: "workflow_required", message, routing_hint} payload (still isError=true) instead of plain-text errors. routing_hint.suggested_intent_verb tells the agent the exact start_task call to make. Backed by a new WorkflowRoutingError exception class.
  • Workflow schema bundling: get_workflow now bundles required_tool_schemas — the full MCP Tool definitions for every tool the workflow body references. One round trip equips the agent.
  • Telemetry: structured single-line JSON events emitted on stderr (PRETORIN_TELEMETRY_EVENT {...}) on successful start_task and on WorkflowRoutingError raises. Feeds the phase-4 trigger decision in the RFC. Opt out with PRETORIN_MCP_TELEMETRY_DISABLED=1.
  • pretorin mcp-smoke-test command: end-to-end harness that exercises every new behavior in-process — useful for verifying an install or PR.

0.19.0 - 2026-05-13

Added

• Markdown evidence artifacts and structured provenance (#112): JSON evidence writes now send short description summaries plus standalone Markdown artifact_content, with source/capture context in audit_metadata (source_label, source_locator, source_excerpt, content_hash, capture_method, and related fields). Batch evidence follows the same per-item contract. Added pretorin evidence validate to compare fresh source-material hashes before re-verifying; drifted sources update the existing evidence artifact with a drift_note instead of silently calling mark-current.

0.18.2 - 2026-05-09

Maintenance

• Automated maintenance + documentation sync pass (#111): lint/type-check fixes, test coverage improvements, dead-code removal, dependency vulnerability patches, version/registration consistency, and a repository-wide doc resync against the v0.18 surface (CLI/MCP/agent references, llms.txt manifests, and a fresh mdBook rebuild).

0.18.1 - 2026-05-09

Added

• Continuous compliance — --cadence-days flag and mark-current command (#108 PR B): pretorin evidence upsert accepts --cadence-days <int> to opt new evidence into a refresh cadence; the platform then computes expires_at server-side and includes the row in the daily freshness sweep. New pretorin evidence mark-current <id> subcommand re-affirms that evidence is still current — bumps expires_at by the cadence, transitions expired→valid, writes a re_verified lineage row, and auto-resolves any open evidence.expiring/evidence.expired monitoring events. EvidenceCreate carries the new refresh_cadence_days field. PretorianClient.mark_evidence_current() is the corresponding API client method.

0.18.0 - 2026-05-08

Added

• Auditor sufficiency fields on evidence writes (#108): pretorin evidence upsert gains --coverage-start, --coverage-end, and --capture-query flags so callers can populate the new auditor sufficiency columns. The MCP create_evidence tool accepts the same arguments. EvidenceCreate and EvidenceBatchItemCreate now carry data_coverage_start_at, data_coverage_end_at, and capture_query. Pairs with the platform-side schema; auditors get clear answers to the seven sufficiency questions (source-system, capture-vs-coverage timestamps, producer authority, capture context, in-scope binding, control mapping, reliability) without walking attestation chains.

0.17.8 - 2026-05-08

Fixed

• Evidence audit metadata serialization: pretorin evidence upsert and MCP evidence writes now serialize audit_metadata.captured_at using Pydantic JSON mode before handing payloads to httpx. Previously, recipe/agent-stamped evidence failed locally with TypeError: Object of type datetime is not JSON serializable before the platform request was sent.
• Source verification JSON safety: evidence create and batch-create now normalize source-verification snapshots to JSON primitives, so attested contexts with datetime values do not break evidence writes.

0.17.7 - 2026-05-07

Fixed

• MCP recipe-script context resolution (#104): scanner recipes invoked over MCP (manual-attestation, inspec-baseline, openscap-baseline, cloud-aws-baseline, cloud-azure-baseline) now correctly receive the active system_id / framework_id. The dispatcher previously read these from PretorianClient instead of Config, so every script ran with ctx.system_id == None and the platform returned System not found. As a bonus, PRETORIN_SYSTEM_ID / PRETORIN_FRAMEWORK_ID env-var overrides now flow through end-to-end.
• Recipe import error in scope/policy questionnaire redactors (#103): scope-q-answer and policy-q-answer no longer fail at import with cannot import name 'redact_secrets'. Both scripts now use the public redact() helper from pretorin.evidence.redact and unpack the (str, RedactionResult) return shape.

Documentation

• Customer-managed air-gapped install guide: new page walking operators of customer-managed / air-gapped Pretorin platform deployments through pointing the CLI at their private platform — non-secret platform validation (smoke test, embedding readiness, AI provider checks), CLI configuration via PRETORIN_PLATFORM_API_BASE_URL / pretorin login --base-url, and tenant-scoped CLI smoke tests. Linked from the configuration reference. See Customer-managed air-gapped installs.

0.17.6 - 2026-05-06

Added

• Risk-management CLI + MCP surface (#100): you can now populate a system’s risk register directly from the CLI or from any MCP-connected agent — list, create, seed from library templates, update with mitigation, link controls/evidence/vendors as artifacts, and refresh the AI-generated summary. End-to-end wrappers around the platform’s public /systems/{system_id}/risks* endpoints. New pretorin risk command group: list, show, create, seed, update, refresh-summary, link add/link rm, and library list. Matching MCP tools: list_risks, get_risk, create_risk, seed_risks, update_risk, link_risk_artifact, unlink_risk_artifact, refresh_risk_summary, list_risk_library. Tool descriptions encode workflow gotchas — risks are system-scoped, control auto-link is opt-in (requires framework_id + matching ControlImplementation rows), mitigation is recorded via update_risk (no separate /mitigate endpoint), and AI summary refresh is best-effort.

0.17.5 - 2026-05-06

Fixed

• pretorin cci impl panel now surfaces the impl row id (the id field in the platform response) so agents can chain directly into evidence link-cci without re-querying.
• Panel header now displays the CCI human label (CCI-000007) by reading the platform’s cci_identifier field. The earlier code read a non-existent cci_uuid field and silently fell back to the URL arg.
• Removed dead-code rendering loop for emass_* fields that the platform does not return.

0.17.4 - 2026-05-06

Added

• CCI implementation read endpoint (#97): pretorin cci impl <cci_uuid> and MCP tool get_cci_implementation wrap the new platform GET /systems/{system_id}/cci-implementations/{cci_uuid} endpoint, returning the live per-system impl row.
• Evidence link target-type extensions (#97): new sibling commands pretorin evidence link-cci and pretorin evidence link-stig plus MCP tools link_evidence_to_cci_implementation and link_evidence_to_stig_rule_workflow. Both honor the platform’s override_system_mismatch + override_reason gate; the STIG variant lazy-creates the workflow row when none exists.
• Agent guidance on STIG-to-CCI traceability: SKILL.md and the single-control workflow playbook clarify that the STIG-rule → CCI relationship is catalog-level (DISA-defined). Use get_cci_chain(nist_control_id, system_id) for “what tests this CCI on this system.”

0.17.3 - 2026-05-05

Fixed

• Scope and policy generation MCP tools now request AI review in the same durable generation job by default, matching the platform workflow while preserving an include_review=false opt-out.

0.17.2 - 2026-05-02

Documentation

• Repository-wide documentation sync to current v0.17 surfaces: README recipes table, getting-started, CLI/MCP reference, frameworks selection + custom-framework authoring, recipes/workflows, agent overview, env-vars reference, llms.txt manifests, and a fresh mdBook rebuild.

Fixed

• Test isolation: test_install_default_writes_to_all_known_agents now performs filesystem assertions inside the Path.home() patch context so CI runs do not depend on the runner’s real home directory.

0.17.1 - 2026-04-30

Added

• Custom framework authoring CLI (#90): end-to-end build / validate / upload workflow around the platform’s unified.json revision-lifecycle endpoints. New pretorin frameworks commands: init-custom, validate-custom, build-custom, upload-custom (--publish to ship immediately), fork-framework, rebase-fork, revisions, export-oscal.
• Vendored unified-framework toolchain at pretorin.frameworks: bundled JSON Schema validator, OSCAL ↔ unified converters with lossless round-trip, and the 12-format custom-catalog converter ported from the monorepo data/tools/.
• Framework revision lifecycle client methods on PretorianClient: create_custom_draft, publish_draft, fork_framework, create_rebase_draft, list_revisions. Structured validation_report is preserved through PretorianClientError.details on 400.
• jsonschema>=4.0.0 added as a runtime dependency.

Documentation

• New page covering the full custom-framework workflow: Custom frameworks.

0.17.0 - 2026-04-30

Added

• Recipe extensibility system (RFC 0001): full implementation of the three-layer routing model — engagement → workflow → recipe. Calling AI agents now route through deterministic Python rules to a workflow playbook, then pick recipes per item from a discoverable menu instead of freelancing.
• start_task MCP tool: pure-function rule cascade over agent-extracted entities. Cross-checks against platform state (hallucinated control ids → hard error; wrong-framework / cross-system writes → ambiguous response). Bundles inspect summary into the response.
• Workflow registry + 4 built-in playbooks: single-control, scope-question, policy-question, campaign. list_workflows and get_workflow MCP tools.
• Recipe registry + 8 built-in recipes: code-evidence-capture, inspec-baseline, openscap-baseline, cloud-aws-baseline, cloud-azure-baseline, manual-attestation, scope-q-answer, policy-q-answer.
• Recipe authoring surface: pretorin recipe list / show / new / validate / run CLI commands. Four loader paths with clear precedence: explicit > project > user > built-in. Per-script MCP tools auto-registered as recipe_<safe_id>__<script>.
• Recipe execution context: start_recipe / end_recipe; every platform write inside the context auto-stamps producer_kind="recipe", recipe id, and recipe version.
• Audit-trail metadata: EvidenceAuditMetadata is stamped on every CLI / agent / MCP / campaign-apply evidence write. Build helpers at pretorin.evidence.audit_metadata are the single construction surface.
• Recipe selection on every drafting call: draft_control_artifacts consults the recipe registry before falling through to freelance. The decision is recorded as RecipeSelection on the response.
• pretorin.evidence.redact + pretorin.evidence.markdown: shared primitives for secret redaction and audit-grade markdown composition.
• Bundled pretorin skill v0.17.0: teaches the calling agent about the routing model. New “Engagement (Routing)” section flags start_task as the FIRST call.
• Authoring docs at docs/src/recipes/: index, manifest reference, script contract, writer tools, testing, publishing, workflows, engagement, worked example.

Changed (BREAKING)

• pretorin scan CLI command removed. All scanner functionality moved to recipes. Migrate to pretorin recipe run <recipe-id> (e.g., pretorin recipe run inspec-baseline --param stig_id=RHEL_9_STIG) or invoke via MCP.
• ScanOrchestrator removed. Manifest fetch + rule filter + summary helpers extracted to pretorin.scanners.manifest and shared across scanner recipes.

Removed

• src/pretorin/cli/scan.py and src/pretorin/scanners/orchestrator.py.
• The deprecated rejected_invalid_type campaign-apply telemetry counter (deprecated in 0.16.0).

0.16.3 - 2026-04-26

Fixed

• CCI chain test fix: test_cci_chain_with_system_status now correctly mocks resolve_execution_context so CCI status rendering is exercised. No production code changes.

0.16.2 - 2026-04-21

Fixed

• pretorin campaign controls --family case-insensitive resolution (#84): --family cc6 now resolves to canonical CC6 before hitting the backend. Unknown families raise a structured error listing available families and pointing at pretorin frameworks families <framework-id>. Same fix applied to prepare_campaign MCP handler.

0.16.1 - 2026-04-21

Added

• Gap questions for policy and scope Q&A: MCP tool descriptions guide agents through answer-first workflow with structured gap questions for organizational knowledge gaps.

0.16.0 - 2026-04-21

Changed (BREAKING)

• evidence_type is now required on every CLI, MCP, agent, and workflow write path (#79). CLI paths hard-error when the user omits -t/--type; every other path runs a client-side normalizer before submission.

Added

• Evidence provenance fields: CLI sends code_file_path, code_line_numbers, code_snippet, code_repository, code_commit_hash on all evidence creation paths. Auditors can trace evidence to source files and commits.
• Source verification mapping: Attested source identities mapped to platform’s SourceVerificationPayload with source_type and source_role.
• pretorin evidence upload: Upload files (screenshots, PDFs, configs) as evidence with SHA-256 integrity verification.
• upload_evidence MCP tool: Agents and recipes can upload evidence files via MCP.
• File reference validation: Campaign apply reads actual file content as canonical snippet, validates paths and line ranges.
• Code provenance on local evidence: Frontmatter supports code_* fields for local evidence create and push.
• pretorin.evidence.types module: canonical 13-type enum, AI-drift alias map, and normalize_evidence_type() with fuzzy matching.

Changed

• Evidence models include code provenance fields. Campaign extracts code_* and relevance_notes from AI recommendations.
• upsert_evidence() creates enriched evidence as new record when provenance fields are provided.
• AI generation prompt requests code file paths and line numbers in evidence recommendations.

Fixed

• SOC2 campaign batches with non-canonical evidence_type strings now succeed end-to-end via the normalizer.
• Non-campaign write paths can no longer silently tag missing-type evidence as policy_document.

0.15.5 - 2026-04-20

Fixed

• Campaign --apply runs no longer flood the evidence locker with AI-authored summaries typed as policy_document (issue #77). The pipeline now wires recommended_notes through to the platform as real gap notes, rejects evidence recommendations with missing or invalid evidence_type (turning them into synthesized gap notes), and emits a structured campaign.apply.control telemetry line for post-ship measurement.
• Partial failures in the per-control notes write now raise PretorianClientError with the failing indexes, mirroring the existing evidence-batch behavior so checkpoint resumes are idempotent.
• Evidence batch result mapping now aligns offsets to the original recommendation index via the accepted-items list and asserts length match, fixing a latent index-drift bug that appeared once any recommendation was rejected mid-loop.
• Completion note now fires when all pending work has landed across runs, not only when something new was written in the current run.

Changed

• evidence_type is now required on EvidenceBatchItemCreate. The campaign batch write path no longer silently tags missing types as policy_document; pydantic validation raises instead. Other evidence write paths (CLI, MCP, direct API) keep their existing defaults.
• Agent drafting prompts (_build_generation_task, _draft_control_fix, _WORKFLOW_GUARDRAILS, codex system prompt, [[PRETORIN_TODO]] template) now list every valid evidence type verbatim and state that an empty evidence_recommendations list is a valid result — gaps belong in recommended_notes.
• _WORKFLOW_GUARDRAILS merged in the evidence-collection skill’s “concrete, auditable artifacts” language so narrative-generation skill callers inherit the same rules.

0.15.4 - 2026-04-18

Changed

• Updated 6 dependencies to resolve 7 known vulnerabilities (cryptography, pygments, pyjwt, pytest, python-multipart, requests)
• Added CLAUDE.md and AGENTS.md for AI agent context

0.15.3 - 2026-04-18

Fixed

• pretorin update now checks PyPI before running pip, skipping reinstall when already current
• pretorin update verifies the installed version after pip runs, detecting silent failures in pipx/uv-managed environments

Added

• pretorin update [VERSION] accepts an optional version argument to install a specific release

0.15.2 - 2026-04-18

Changed

• Documentation sync: rebuilt all docs to match current codebase

0.15.1 - 2026-04-17

Added

• pretorin evidence delete <evidence-id> command with --yes flag for non-interactive workflows
• MCP tool delete_evidence for programmatic evidence deletion within system scope
• API client method delete_evidence for the public DELETE endpoint

0.15.0 - 2026-04-16

Added

• Source manifest requirement policy: declare which external sources a system expects and gate compliance writes on their presence
• pretorin context manifest command for viewing the resolved manifest and evaluating it against detected sources
• Manifest loading from four layered sources: env var, repo-local .pretorin/source-manifest.json, per-system user config, or inline config key
• Family-level source requirements with three requirement levels (required/recommended/optional) and write blocking on missing required sources
• Manifest evaluation results in write provenance (manifest_status and missing_required_sources fields)

Changed

• _enforce_source_attestation now evaluates manifest requirements after the existing MISMATCH check
• resolve_execution_context and build_write_provenance accept optional control_id for family-level manifest enforcement

0.14.0 - 2026-04-10

Changed

• MCP and agent write workflows now treat the active CLI context as a strict execution boundary by default, with an explicit allow_scope_override escape hatch for intentional cross-scope writes
• Control-scoped MCP and agent workflows now route through one shared scope-validation path so exact control lookup happens in the resolved framework before any write proceeds
• Agent guidance now tells built-in workflows to resolve an exact user-supplied control in the active framework before doing broader discovery
• pretorin mcp-serve now emits a non-blocking stderr update prompt when a newer CLI release is available, so MCP-only users can discover upgrades without interrupting active tool calls

Fixed

• apply_campaign now reports apply: true after a successful apply run and persists that state back to the checkpoint summary
• Stored active context and campaign checkpoints are now validated against the current API environment before campaign reads or writes proceed
• Control-scoped MCP and agent updates now refuse silent remaps like cm-04.02 to a different control when the exact control does not resolve in the active framework

Added

• get_cli_status and the status://cli MCP resource expose local CLI version, update availability, and upgrade guidance to MCP hosts and agents

0.13.1 - 2026-04-07

Added

• get_stig MCP tool for STIG benchmark detail
• get_cci_chain MCP tool for full Control → CCI → SRG → STIG rule traceability

0.13.0 - 2026-04-07

Added

• Complete STIG/CCI MCP tools: list_stigs, get_stig, list_stig_rules, get_stig_rule, list_ccis, get_cci, get_cci_chain, get_cci_status, get_stig_applicability, infer_stigs, get_test_manifest, submit_test_results
• STIG/CCI agent tools for OpenAI Agents SDK
• pretorin stig CLI group: list, show, rules, applicable, infer
• pretorin cci CLI group: list, show, chain
• pretorin scan CLI group: doctor, manifest, run, results
• Scanner orchestration module with support for OpenSCAP, InSpec, AWS/Azure Cloud Scanners, and Manual review

0.12.0 - 2026-04-04

Added

• Vendor management CLI: pretorin vendor list/create/get/update/delete/upload-doc/list-docs
• MCP vendor tools: list_vendors, create_vendor, get_vendor, update_vendor, delete_vendor, upload_vendor_document, list_vendor_documents, link_evidence_to_vendor
• Inheritance/responsibility MCP tools: set_control_responsibility, get_control_responsibility, remove_control_responsibility, generate_inheritance_narrative, get_stale_edges, sync_stale_edges

0.11.0 - 2026-04-02

Added

• Campaign CLI: pretorin campaign controls/policy/scope/status
• Campaign MCP tools: prepare_campaign, claim_campaign_items, get_campaign_item_context, submit_campaign_proposal, apply_campaign, get_campaign_status
• External-agent-first campaign pattern with checkpoint persistence and lease-based concurrency
• Campaign builtin executor for local execution

0.10.0 - 2026-03-28

Added

• Workflow state and analytics MCP tools: get_workflow_state, get_analytics_summary, get_family_analytics, get_policy_analytics
• Family operations MCP tools: get_pending_families, get_family_bundle, trigger_family_review, get_family_review_results
• Policy workflow MCP tools: get_pending_policy_questions, get_policy_question_detail, answer_policy_question, get_policy_workflow_state, trigger_policy_generation, trigger_policy_review, get_policy_review_results
• Scope workflow MCP tools: get_pending_scope_questions, get_scope_question_detail, answer_scope_question, trigger_scope_generation, trigger_scope_review, get_scope_review_results
• ExecutionScope for thread-safe parallel agent execution

0.9.7 - 2026-03-25

Fixed

• Aligned CLI control status validation with the platform status enum set used by that release
• Aligned MCP control status validation with the live platform status enum set to match public API behavior
• Synced package version metadata and release notes so PyPI builds publish a consistent CLI version

Changed

• Updated CLI and MCP coverage tests to reflect the platform control status contract used by public control workflows

0.8.7 - 2026-03-23

Added

• MCP questionnaire tooling for scope and organization policy workflows

Changed

• MCP documentation now reflects the full 29-tool surface, including batch evidence support

0.8.6 - 2026-03-23

Added

• pretorin context show --quiet for compact shell-friendly context checks
• pretorin context show --check to fail fast when stored scope is missing, stale, or unverified

Changed

• context show caches the last known system name so offline and stale context output stays human-friendly

Fixed

• context show validates stored context against the platform instead of silently treating deleted systems as active

0.8.5 - 2026-03-23

Fixed

• Reset active system/framework context when logging into a different API endpoint or with a different API key
• Model API base URL now follows the configured platform public API endpoint during login
• scope populate --json --apply and policy populate --json --apply now persist questionnaire updates
• Larger Codex subprocess line buffer for policy questionnaire responses

0.8.0 - 2026-03-07

Added

• MCP generate_control_artifacts for read-only AI drafting of control narratives and evidence-gap assessments
• Shared AI drafting workflow helper for structured MCP/CLI parity

Changed

• MCP system-scoped tools now resolve friendly system names the same way the CLI does
• Codex Desktop MCP configuration can be pinned to the UV-managed Pretorin wrapper

0.7.0 - 2026-03-07

Fixed

• Control implementation parsing tolerant of notes: null deployments
• Compatibility fallback for control note reads when /notes endpoint returns 405
• Compatibility fallback for evidence search on system-scoped evidence routes
• Agent --no-stream crash on literal [[PRETORIN_TODO]] blocks

Changed

• MCP and legacy agent evidence search tools accept optional system_id context

0.6.1 - 2026-03-05

Fixed

• Added required MCP registry ownership marker for PyPI validation

0.6.0 - 2026-03-05

Added

• Shared markdown quality validator for auditor-readable artifacts
• Dedicated tests for markdown quality guardrails
• CLI/MCP/agent parity for reading notes via dedicated endpoint

Changed

• Narrative and evidence update flows enforce markdown quality checks before push/upsert
• Agent prompts require auditor-ready markdown (lists/tables/code/links)
• Source tagging normalized to cli across write paths

Removed

• Markdown image usage from narrative/evidence authoring contract (temporarily)

0.5.4 - 2026-03-05

Added

• pretorin narrative get to read current control narratives
• pretorin notes list and pretorin notes add for control-note management
• pretorin evidence search for platform evidence visibility
• pretorin evidence upsert for find-or-create evidence with control linking
• Shared compliance workflow helpers (system resolution, evidence dedupe/upsert, TODO blocks, gap notes)
• MCP get_control_notes tool

Changed

• create_evidence now upserts by default (dedupe: true)
• pretorin evidence push uses find-or-create upsert logic
• Agent skill prompts include no-hallucination guidance and gap note format

Removed

• Automatic control status updates from CLI evidence push workflow

0.5.3 - 2026-03-02

Fixed

• CI lint failure formatting
• CLI model key precedence: OPENAI_API_KEY → config.api_key → config.openai_api_key

0.5.2 - 2026-02-27

Fixed

• Rich markup MarkupError crash in login flow
• Evidence type mismatch (documentation → policy_document)
• CMMC control ID casing preserved (no longer incorrectly lowercased)
• monitoring push checks active context before requiring --system
• pretorin login skips prompt when already authenticated
• Demo script --json flag position and stdin handling

Changed

• Default evidence type changed to policy_document
• Valid evidence types aligned with API
• Added .pretorin/ and evidence/ to .gitignore

0.5.0 - 2026-02-27

Added

• Context management (context list/set/show/clear)
• Evidence commands (evidence create/list/push/search/upsert)
• Narrative push (narrative push)
• Monitoring events (monitoring push)
• Codex agent runtime (agent run with skills, agent doctor/install/version/skills)
• Agent MCP management (agent mcp-list/mcp-add/mcp-remove)
• Code review (review run/status)
• 14 new MCP tools for system, evidence, narrative, monitoring, notes, and control operations
• Control ID normalization (zero-padding)
• Interactive demo walkthrough script
• Beta messaging across CLI, MCP, and README

Changed

• Platform API base URL changed to /api/v1/public
• Evidence and linking scoped to system
• update_control_status() changed from PATCH to POST

Removed

• pretorin narrative generate — use pretorin agent run --skill narrative-generation
• pretorin_generate_narrative MCP tool

Security

• MCP mutation handler parameter validation
• Client-side enum validation
• Path traversal protection in evidence writer
• TOML injection prevention in Codex config writer
• Connection error URL display

0.2.0 - 2026-02-06

Added

• --json flag for machine-readable output
• pretorin frameworks family/metadata/submit-artifact commands
• Full AI Guidance rendering on control detail view
• .mcp.json for Claude Code auto-discovery
• Usage examples in command docstrings

Changed

• Control references shown by default (replaced --references with --brief)
• Default controls limit changed to 0 (show all)

0.1.0 - 2025-02-03

Added

• Initial public release
• CLI commands for browsing compliance frameworks
• Authentication commands (login, logout, whoami)
• Configuration management
• MCP server with 7 tools and analysis resources
• Self-update functionality
• Rich terminal output with Rome-bot mascot
• Docker support
• GitHub Actions CI/CD
• Integration test suite

Supported Frameworks

• NIST SP 800-53 Rev 5
• NIST SP 800-171 Rev 2/3
• FedRAMP (Low, Moderate, High)
• CMMC Level 1, 2, and 3