Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Notes Commands

The notes command group is a deprecated compatibility alias for control issues. Prefer pretorin issues ... for new work. Existing local notes/ files remain supported for one compatibility window.

Issues are the durable home for independently supported gaps against control expectations and their governed treatment. Missing context, source/recipe availability, optional advice, evidence suggestions, and subtasks are not Issues. Narratives should describe implemented control state only, and evidence should describe artifacts and what they support only.

Create Local Note

pretorin notes create ac-02 fedramp-moderate \
  -c "Administrative accounts do not enforce MFA."

Creates a local markdown file at notes/<framework>/<control>/<slug>.md with YAML frontmatter. No markdown validation is applied to notes.

Options:

  • --content / -c — Note content (required)
  • --name / -n — Custom name (defaults to content summary)

Push Notes

pretorin notes push --dry-run
pretorin notes push

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

List Local Notes

pretorin notes list --local
pretorin notes list --local --framework fedramp-moderate

Use the --local flag to list local note files instead of platform notes.

List Platform Notes

pretorin notes list ac-02 fedramp-moderate --system "My System"

Add a Note (Direct to Platform)

pretorin notes add ac-02 fedramp-moderate \
  --content "Administrative accounts do not enforce MFA."

pretorin notes add ac-02 fedramp-moderate \
  --content "MFA verified" --system "My System"

Options:

  • --content / -c — Note content (required)
  • --system / -s — System name or ID (uses active context if omitted)

Resolve or Reopen a Note

# Resolve a note with an audit-trail justification
pretorin notes resolve ac-02 fedramp-moderate <note_id> --resolution-note "SSO config verified in IdP logs."

# Resolve with updated content and a resolution justification
pretorin notes resolve ac-02 fedramp-moderate <note_id> --resolution-note "SSO config verified." --content "Updated note text."

# Reopen a resolved note
pretorin notes resolve ac-02 fedramp-moderate <note_id> --reopen

Options:

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

Issue Admission Format

For legacy local-file creation, admit an Issue only when an independent observation proves one in-scope expectation unmet. Check existing Issues first, then preserve this contract in the Issue body and risk fields:

Expectation key: <stable key>
Unmet expectation: <exact in-scope expectation>
Observed gap: <one sentence, at most 20 words>
Observation basis: <independent source/workspace fact and locator>
Risk basis: <why the gap creates control risk>
Clearance condition: <what must become true>
Minimum evidence: <smallest artifacts that prove clearance>

Missing context, source/recipe availability, optional advice, evidence suggestions, and subtasks are not Issues. Prefer pretorin issues add for new work; agents use the stricter issue-create recipe.