Narrative & Evidence Workflow

This is the core workflow for updating control implementations on the platform. Follow this sequence for any control update.

Workflow Steps

1. Resolve the Target

Identify the system_id, control_id, and framework_id for your update. Set the active context:

pretorin context set --system "My Application" --framework fedramp-moderate

2. Read Current State

Before making changes, understand what’s already there:

# Get full control context (requirements + current implementation)
pretorin control context ac-02 --framework-id fedramp-moderate
# Via MCP: get_control_context

# Get current narrative
pretorin narrative get ac-02 fedramp-moderate

# Search existing evidence
pretorin evidence search --control-id ac-02 --framework-id fedramp-moderate

# List existing notes
pretorin notes list ac-02 fedramp-moderate

3. Collect Observable Facts

Search your codebase and connected systems for evidence. Only document what is directly observable — never assume or fabricate implementation details.

Treat existing Pretorin narratives, notes, and status fields as a starting point, not proof that a control gap exists. Before writing a narrative update or gap note, inspect the relevant implementation in the workspace and connected systems. If those sources show stronger implementation than the current platform record, update the narrative to reflect the observed implementation and record any remaining evidence gap separately.

4. Draft Updates

Prepare three types of updates:

Narrative — How the control is implemented. Include TODO placeholders for unknowns:

[[PRETORIN_TODO]]
missing_item: SSO configuration details
reason: Not observable from current workspace and connected MCP systems
required_manual_action: Export IdP SAML configuration
suggested_evidence_type: configuration
[[/PRETORIN_TODO]]

Evidence — Specific artifacts demonstrating implementation (config files, code, policies).

Gap Notes — Unresolved items requiring manual follow-up:

Gap: Missing MFA enforcement evidence
Observed: TOTP library imported in auth module
Missing: MFA policy enforcement configuration
Why missing: IdP admin console not accessible via codebase
Manual next step: Screenshot MFA policy from Azure AD admin portal

5. Push Updates

# Push a single narrative file
pretorin narrative push-file ac-02 fedramp-moderate "My Application" narrative-ac02.md

# Upsert evidence (finds or creates, then links)
pretorin evidence upsert ac-02 fedramp-moderate \
  --name "RBAC Configuration" \
  --description "Role mapping in IdP" \
  --artifact-content "## Evidence\n\n- Role mapping is enforced in the IdP export." \
  --type configuration

# Cadenced evidence with audit-sufficiency metadata
pretorin evidence upsert ac-02 fedramp-moderate \
  --name "Quarterly Access Review" \
  --description "Output of quarterly access review query" \
  --artifact-content "## Evidence\n\n- Quarterly access review query output is attached as Markdown." \
  --type attestation \
  --coverage-start 2026-01-01 --coverage-end 2026-03-31 \
  --capture-query "SELECT user_id, last_login FROM users WHERE ..." \
  --cadence-days 90

# Add gap notes
pretorin notes add ac-02 fedramp-moderate \
  --content "Gap: Missing MFA evidence..."

# Start/reopen implementation authoring
pretorin control status ac-02 in_progress \
  --framework-id fedramp-moderate

CLI and MCP callers may only set in_progress. Stage-for-approval, approval, and not-applicable decisions happen in the Pretorin UI by a human.

Read-Only Draft Workflow

When you want AI drafts before any platform writes:

1. Resolve scope (system, control, framework)
2. Read current state (context, narrative, evidence, notes)
3. Generate drafts via pretorin agent run --skill narrative-generation or the MCP generate_control_artifacts tool
4. Review the draft — clearly separate candidate narrative, evidence gaps, and manual follow-up actions
5. Only push to the platform after explicit approval

Markdown Quality Rules

All narratives and evidence must pass markdown quality validation:

Narratives

• No markdown headings (#, ##, etc.)
• At least 2 rich markdown elements (code blocks, tables, lists, links)
• At least 1 structural element (code block, table, or list)
• No markdown images

Evidence

• No markdown headings
• At least 1 rich markdown element
• No markdown images

Continuous Compliance & Cadenced Evidence

Evidence created with --cadence-days carries a refresh cadence; the platform stores expires_at = created_at + cadence_days and emits evidence.expiring / evidence.expired monitoring events as the deadline approaches and passes.

To re-affirm that cadenced evidence is still current, prefer validate so the CLI compares the fresh source-material hash before marking current:

pretorin evidence validate <evidence_id>
# If unchanged, records re_verified; if changed, replaces the Markdown artifact
# with a drift note instead of silently marking stale evidence current.

This fails with HTTP 400 if the evidence has no cadence set. The --coverage-start / --coverage-end flags describe the period the evidence content covers (point-in-time if --coverage-end is omitted). The --capture-query flag records the query, filter, or command that produced the artifact — auditors use this for IPE (Information Produced by the Entity) reproducibility.

Linking Evidence to CCI Implementations

To attach evidence to a per-system CCI implementation row (rather than the control as a whole), use link-cci:

pretorin evidence link-cci <evidence_id> <cci_implementation_uuid>

The CCI implementation UUID comes from pretorin cci impl <cci_uuid>; the row must already exist on the platform. Add --override-system-mismatch --override-reason "<why>" to permit cross-system attachment.

Evidence Deduplication

pretorin evidence upsert and the MCP create_evidence tool use find-or-create logic by default (dedupe: true):

1. Search for an exact match on (name + description + type + control + framework) within the active system scope
2. If found, reuse the existing evidence item
3. If not found, create a new one
4. Ensure the evidence is linked to the specified control

The response indicates whether the evidence was created (new) or reused, along with the match_basis.