Issues Commands

The issues command group manages control implementation Issues. An Issue is the durable home for one justified gap against a control expectation and its governed treatment. Missing context, source availability, optional advice, evidence suggestions, and subtasks are not Issues.

Narratives should describe the implemented control state only. Evidence should describe the artifact and what it supports only. Do not use narratives or evidence descriptions as a workaround issue log.

Create Local Issue

pretorin issues create ac-02 fedramp-moderate \
  --title "ac-02.mfa-enforcement: Administrative MFA" \
  -c "Administrative accounts do not enforce MFA." \
  --likelihood high --impact very_high \
  --risk-basis "idp/policy-export.json:42 disables admin MFA, permitting password-only privileged access."

Creates a local markdown file at issues/<framework>/<control>/<slug>.md with YAML frontmatter. Existing local notes/ files remain supported through the deprecated pretorin notes compatibility commands.

Options:

• --content / -c — Issue content (required)
• --name / -n — Custom name (defaults to content summary)
• --title / -t — Short canonical Issue title
• --likelihood, --impact — Initial NIST 800-30 ratings (very_low through very_high; default moderate)
• --risk-basis — Rationale for the initial provisional risk evaluation

The risk fields are written into the file’s frontmatter and travel with it, so pretorin issues push intakes the Issue with the risk framing you intended instead of defaulting everything to moderate:

pretorin issues create ac-02 fedramp-moderate \
  -c "No MFA on the break-glass account." \
  --likelihood high --impact very_high \
  --risk-basis "Unmonitored privileged path with no compensating control."

Push Issues

pretorin issues push --dry-run
pretorin issues push

Batch-pushes all unsynced local issues to the platform. Issues are append-only on the platform. After a successful push, the local file’s platform_synced frontmatter is set to true.

List Issues

pretorin issues list --local
pretorin issues list --local --framework fedramp-moderate
pretorin issues list ac-02 fedramp-moderate --system "My System"

Use --local to list local issue files. Without --local, provide a control and framework to list platform issues for that control.

The platform listing shows each Issue’s issue_id, lifecycle status, gate status, and source. There is no blocking column: every canonical Issue gates its control. Every row of a single control’s listing shares one control_implementation_id, so that id is printed once in the header — those two ids are what the treatment subcommands below take as arguments.

Issues Inbox (system-wide)

pretorin issues inbox fedramp-moderate
pretorin issues inbox fedramp-moderate --status all --source ai_review
pretorin issues inbox fedramp-moderate --control ac-02 --limit 50 --offset 50

Lists issues across a whole system/framework instead of one control at a time — the fast way to find open remediation work without walking every control. Because both ids vary per row here, they are printed in a Treatment IDs key below the table, keyed to the row numbers, so the full untruncated ids stay copy-pasteable.

Options:

• --status — open (default), resolved, or all
• --source — manual, rfi, monitoring, cli, mapping, finding, ai_review, or all
• --control / -c — Narrow to a single control ID
• --limit, --offset — Pagination (limit 1–1000, default 500)
• --system / -s — System name or ID

Add an Issue

pretorin issues add ac-02 fedramp-moderate \
  --title "ac-02.mfa-enforcement: Administrative MFA" \
  --content "Administrative accounts do not enforce MFA." \
  --likelihood high \
  --impact very_high \
  --risk-basis "idp/policy-export.json:42 disables admin MFA, permitting password-only privileged access."

Options:

• --content / -c — Issue content (required)
• --title / -t — Short Issue title (defaults to the first content line)
• --likelihood, --impact — Initial NIST 800-30 risk ratings (very_low through very_high)
• --risk-basis — Rationale for the initial provisional risk evaluation
• --detected-at — Optional ISO 8601 detection timestamp
• --idempotency-key — Optional retry key that prevents duplicate creation
• --system / -s — System name or ID (uses active context if omitted)

The create response includes control_implementation_id; use it with the Issue ID for the treatment commands below.

Risk, POA&M, and Corrective Treatment

# Immutable risk history. risk-add appends a provisional assessment;
# risk-confirm records the governed determination.
pretorin issues risk-history <control_impl_id> <issue_id>
pretorin issues risk-add <control_impl_id> <issue_id> \
  --likelihood high --impact very_high \
  --residual-likelihood moderate --residual-impact moderate \
  --basis "Compensating monitoring reduces the expected residual exposure."

# Formal POA&M facts.
pretorin issues poam-set <control_impl_id> <issue_id> \
  --weakness-id V-2697 --detection-source quarterly-review \
  --asset-id privileged-directory --point-of-contact identity-operations

# Versioned plan and ordered work.
pretorin issues plan-create <control_impl_id> <issue_id> \
  --title "Close privileged-access coverage gap" \
  --narrative "Extend collection, route exceptions, and retain reviewer evidence." \
  --owner-id <user_id> --target-date 2026-10-31
pretorin issues action-add <control_impl_id> <issue_id> <plan_id> \
  --title "Extend IAM collector" --owner-id <user_id> --target-date 2026-10-15 \
  --ticket-provider github --ticket-id SEC-2697 --ticket-url https://tracker.example/SEC-2697
pretorin issues plan-submit <control_impl_id> <issue_id> <plan_id>

# Read one plan version (with its full approval lifecycle) or one action.
pretorin issues plan-get <control_impl_id> <issue_id> <plan_id>
pretorin issues action-get <control_impl_id> <issue_id> <plan_id> <action_id>

Available subcommands are risk-history, risk-add, risk-confirm, acceptance-history, accept, acceptance-revoke, poam-set, plan-list, plan-get, plan-create, plan-update, plan-submit, plan-approve, plan-reject, plan-opa-review, plan-complete, action-list, action-get, action-add, action-update, action-delete, action-transition, verify, and void. A WRITE or ADMIN API token is a first-class governed actor for all of them; the platform enforces every lifecycle precondition and returns an explanatory conflict when one is unmet.

The lifecycle runs: add the Issue → risk-confirm → plan-create / action-add → plan-submit → plan-approve → action-transition --status completed → plan-complete (which moves the Issue to verification_pending, not closed) → verify (which closes it). accept records a formal risk acceptance instead of remediating; void retires a finding that was never valid. Note that verify requires verification_pending specifically — plan-complete is what produces that state.

action-transition --status accepts pending, in_progress, blocked, completed, or cancelled. A blocked or cancelled transition requires --note.

CMMC Operational Plans of Action

A cmmc_opa plan carries its own eligibility basis and review cadence. Those three options are only valid together with --kind cmmc_opa, and the two review fields must be supplied as a pair:

pretorin issues plan-create <control_impl_id> <issue_id> \
  --kind cmmc_opa \
  --title "Operational plan for legacy segment" \
  --narrative "Compensating monitoring pending hardware refresh." \
  --opa-basis "Eligible under the CMMC operational-plan provision." \
  --review-frequency-days 90 \
  --next-review-at 2026-12-01T00:00:00+00:00

POA&M facts

poam-set is a full replacement, not a patch — every field the platform accepts is sent on each call, so any option you omit is cleared:

pretorin issues poam-set <control_impl_id> <issue_id> \
  --weakness-id V-2697 --detection-source quarterly-review \
  --asset-id privileged-directory --point-of-contact identity-operations \
  --operational-requirement --operational-requirement-id OR-14 \
  --deviation-rationale "Accepted deviation per ISSO memo 2026-04." \
  --comments "Tracked against the Q3 refresh."

--vendor-dependency/--no-vendor-dependency defaults to true when any --vendor-* option is set; pass it explicitly to override. --false-positive/--no-false-positive records the finding as a false positive.

Resolve or Reopen an Issue

pretorin issues resolve ac-02 fedramp-moderate <issue_id> --resolution-note "SSO config verified in IdP logs."
pretorin issues resolve ac-02 fedramp-moderate <issue_id> --reopen

Options:

• --system / -s — System name or ID
• --reopen — Reopen a resolved issue instead of resolving it
• --resolution-note / --justification — Required when resolving; stored as the closure audit trail

Update an Issue’s Metadata

pretorin issues update ac-02 fedramp-moderate <issue_id> -c "Revised gap description"
pretorin issues update ac-02 fedramp-moderate <issue_id> --pinned
pretorin issues update ac-02 fedramp-moderate <issue_id> --resolution-note "Corrected reference"

Edits content, pinned state, or an existing closure note without touching resolution state. The platform’s resolution field is omitted from the request entirely, so editing a closed Issue cannot reopen it as a side effect. At least one of --content, --pinned/--no-pinned, or --resolution-note is required.

Compatibility

pretorin notes ... remains available as a deprecated alias for one compatibility window. Existing ./notes/<framework>/<control>/<slug>.md files can still be listed and pushed through that command group. New local files should use ./issues/.