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>

A WRITE or ADMIN API token is a first-class governed actor for all of these; 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.

Subcommand reference

Every subcommand below takes <control_impl_id> <issue_id> as its first two arguments. Additional positional arguments are shown in the Arguments column.

Preconditions and semantics worth knowing before you call these:

• risk-confirm is not a stronger risk-add. Confirming supersedes or expires any active risk acceptance on the Issue, recomputes its gate status, and can demote the owning control’s approval gate. Use risk-add to append a provisional assessment without deciding anything. On both commands, residual likelihood and impact must be supplied together.
• accept needs the Issue’s latest confirmed evaluation ID, and the Issue must still be open or in progress. --expires-at must be a timezone-aware ISO 8601 timestamp in the future; --review-frequency-days and --next-review-at must be supplied as a pair, and the review must be no later than the expiry.
• acceptance-revoke works at any point in the lifecycle, including on a closed Issue, and can demote the control’s approval gate. Only an active acceptance is revocable.
• plan-approve is what makes action-transition legal on that plan’s actions; the plan must be pending approval. plan-reject runs no readiness checks — an incomplete plan is still rejectable — and leaves the Issue’s gate and lifecycle state unchanged.
• plan-opa-review is only valid on an approved plan of kind cmmc_opa.
• action-add/action-update ticket fields travel together: --ticket-provider and --ticket-id must be supplied as a pair, and --ticket-url requires both and must be an absolute HTTP(S) URL. --kind accepts action or milestone.
• void is terminal and irreversible. A voided Issue becomes an immutable POA&M record that cannot be modified, reopened, or closed, and the platform accepts it from any non-voided state — including a properly verified one. That is why --force is mandatory rather than optional.

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

Closing, accepting, or voiding

# Governed closure: plan-complete produces verification_pending, verify closes.
pretorin issues plan-complete <control_impl_id> <issue_id> <plan_id> \
  --note "IAM collector extended; exception routing verified in staging."
pretorin issues verify <control_impl_id> <issue_id> \
  --note "Reviewed collector output and exception queue for two cycles."

# Formal risk acceptance instead of remediation.
pretorin issues accept <control_impl_id> <issue_id> <risk_evaluation_id> \
  --rationale "Residual exposure accepted pending the Q4 hardware refresh." \
  --expires-at 2027-01-31T00:00:00+00:00 \
  --review-frequency-days 90 --next-review-at 2026-11-01T00:00:00+00:00
pretorin issues acceptance-revoke <control_impl_id> <issue_id> <acceptance_id> \
  --reason "Refresh completed early; the compensating basis no longer applies."

# Retire a finding that was never valid.
pretorin issues void <control_impl_id> <issue_id> \
  --reason "Scanner matched a decommissioned host." --force

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 \
  --vendor-name "Example IdP" --vendor-product "Directory Cloud" \
  --vendor-check-in 2026-09-15 \
  --deviation-rationale "Accepted deviation per ISSO memo 2026-04." \
  --comments "Tracked against the Q3 refresh."

Options: --weakness-id, --detection-source, --asset-id (repeatable), --point-of-contact, --vendor-name, --vendor-product, --vendor-check-in, --vendor-dependency/--no-vendor-dependency, --operational-requirement/--no-operational-requirement, --operational-requirement-id, --deviation-rationale, --false-positive/--no-false-positive, and --comments.

--vendor-dependency/--no-vendor-dependency defaults to true when any --vendor-* option is set; pass it explicitly to override.

--false-positive and --operational-requirement are rejected for API tokens. Those two determinations still require an interactive session in the web UI, so an agent or CI run cannot set them. To retire a finding that was never valid, use pretorin issues void instead.

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/.