Policy & Scope Questionnaires

Pretorin uses questionnaire workflows to capture organizational policy information and system scope details. Both follow a similar lifecycle: answer questions, generate documents, review, and iterate.

Policy Questionnaire Workflow

Organization policies (e.g., Access Control Policy, Incident Response Policy) are defined at the org level and apply across systems.

1. List Available Policies

pretorin policy list

Or via MCP: list_org_policies

2. View Current State

# Show questionnaire state and saved review findings
pretorin policy show --policy <policy-id-or-name>

Or via MCP:

get_org_policy_questionnaire   # full state — direct equivalent of `policy show`
get_pending_policy_questions   # lightweight — only unanswered
get_policy_question_detail     # guidance and examples per question

Check Existing Narrative Coverage Before Editing

When the question is whether a generated policy already covers a concept, use the policy-scoped search instead of paging every section by hand:

pretorin policy search <policy-id-or-name> "privileged user tier categorization"

Or via MCP:

search_policy_narrative(policy_id, query, limit=5, min_similarity=0.6)

The result is ranked by similarity and includes the matched section ID, title, and a short excerpt. An empty match list means no section met the selected threshold. Use get_policy_narrative only when you need complete section content after the coverage check, especially before a surgical edit.

3. Answer Questions

Via CLI — Draft answers from your workspace:

# Preview proposed answers
pretorin policy populate --policy <policy-id>

# Apply answers to the platform
pretorin policy populate --policy <policy-id> --apply

Via MCP — Answer individually for precise control:

answer_policy_question(policy_id, question_id, answer)

Or batch-update multiple answers:

patch_org_policy_qa(policy_id, updates=[{question_id, answer}, ...])

4. Generate Policy Document

Once questions are answered, trigger AI document generation:

trigger_policy_generation(policy_id)

5. Review

Trigger an AI review of the policy:

trigger_policy_review(policy_id)
get_policy_review_results(policy_id)  # poll for results

Review results include findings with severity levels, affected sections, and recommended fixes.

6. Track Status

get_policy_workflow_state(policy_id)
get_policy_analytics(policy_id)

7. Reopen for Editing

Once a policy is approved it is locked. To edit it again, reopen it — this clears the approval record, bumps the version, and records a monitoring regression event + audit. Edit the policy, then re-approve it.

pretorin policy reopen --policy <policy-id-or-name>

Or via MCP: reopen_policy(policy_id)

Scope Questionnaire Workflow

Scope questionnaires are system+framework specific. They define what’s in scope, what’s excluded, and system boundary details.

1. View Current State

# Show scope questionnaire state and review findings
pretorin scope show --system "My System" --framework-id fedramp-moderate

Or via MCP:

get_scope(system_id, framework_id)                          # full state — direct equivalent of `scope show`
get_pending_scope_questions(system_id, framework_id)        # lightweight — only unanswered
get_scope_question_detail(system_id, framework_id, qid)     # guidance and examples per question

2. Answer Questions

Via CLI — Draft answers from your workspace:

# Preview proposed answers
pretorin scope populate --system "My System" --framework-id fedramp-moderate

# Apply answers to the platform
pretorin scope populate --system "My System" --framework-id fedramp-moderate --apply

Via MCP — Answer individually:

answer_scope_question(system_id, framework_id, question_id, answer)

Or batch-update:

patch_scope_qa(system_id, framework_id, updates=[{question_id, answer}, ...])

3. Generate Scope Document

trigger_scope_generation(system_id, framework_id)

4. Review

trigger_scope_review(system_id, framework_id)
get_scope_review_results(system_id, framework_id)

5. View Full Scope

get_scope(system_id, framework_id)

Returns scope narrative, excluded controls, and Q&A responses.

6. Reopen for Editing

A completed scope is locked. To edit it again, reopen it — this regresses the scope to in_progress and records a monitoring regression event + audit. Edit the narrative, then re-complete the scope to re-approve it.

pretorin scope reopen --system "My System" --framework-id fedramp-moderate

--system/-s and --framework-id/-f fall back to the active context if omitted.

Or via MCP: reopen_scope(system_id, framework_id)

Bulk questionnaire work

Policy and scope questionnaires keep their domain-specific workflows. A calling agent loads policy-question or scope-question, walks the bounded pending set, and uses the typed questionnaire writers and existing review APIs shown above.

The deprecated campaign policy and campaign scope command forms remain compatibility adapters through the 0.29.x release line and will not be removed before 0.30.0, but they are not mapped onto the four Plan-backed Campaign types (initial-pass, interim-pass, issue-triage, and evidence-review). New automation should enter the policy or scope workflow directly rather than relying on checkpoint/proposal/apply.

See Campaign workflow for the separate control, Issue, and evidence Campaign lifecycle.