## 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

# 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`.