gsd-secure-phase

name	gsd-secure-phase
description	Retroactively verify threat mitigations for a completed phase
argument-hint	[phase number]
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","Task","AskUserQuestion"]

Verify threat mitigations for a completed phase. Three states: - (A) SECURITY.md exists — audit and verify mitigations - (B) No SECURITY.md, PLAN.md with threat model exists — run from artifacts - (C) Phase not executed — exit with guidance

Output: updated SECURITY.md.

Verify threat mitigations for a completed phase. Confirm PLAN.md threat register dispositions are resolved. Update SECURITY.md.

<required_reading> @${CLAUDE_PLUGIN_ROOT}/references/ui-brand.md </required_reading>

<available_agent_types> Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):

• gsd-security-auditor — Verifies threat mitigation coverage </available_agent_types>

0. Initialize

INIT=$(node "$GSD_TOOLS" init phase-op "${PHASE_ARG}")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
AGENT_SKILLS_AUDITOR=$(node "$GSD_TOOLS" agent-skills gsd-security-auditor 2>/dev/null)

Parse: phase_dir, phase_number, phase_name, phase_slug, padded_phase.

AUDITOR_MODEL=$(node "$GSD_TOOLS" resolve-model gsd-security-auditor --raw)
SECURITY_CFG=$(node "$GSD_TOOLS" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")

If SECURITY_CFG is false: exit with "Security enforcement disabled. Enable via /gsd-settings."

Display banner: GSD > SECURE PHASE {N}: {name}

1. Detect Input State

SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
PLAN_FILES=$(ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)

• State A (SECURITY_FILE non-empty): Audit existing
• State B (SECURITY_FILE empty, PLAN_FILES and SUMMARY_FILES non-empty): Run from artifacts
• State C (SUMMARY_FILES empty): Exit — "Phase {N} not executed. Run /gsd-execute-phase {N} first."

2. Discovery

2a. Read Phase Artifacts

Read PLAN.md — extract <threat_model> block: trust boundaries, STRIDE register (threat_id, category, component, disposition, mitigation_plan).

2b. Read Summary Threat Flags

Read SUMMARY.md — extract ## Threat Flags entries.

2c. Build Threat Register

Per threat: { threat_id, category, component, disposition, mitigation_pattern, files_to_check }

3. Threat Classification

Classify each threat:

Status	Criteria
CLOSED	mitigation found OR accepted risk documented in SECURITY.md OR transfer documented
OPEN	none of the above

Build: { threat_id, category, component, disposition, status, evidence }

If threats_open: 0 → skip to Step 6 directly.

4. Present Threat Plan

Call AskUserQuestion with threat table and options:

1. "Verify all open threats" → Step 5
2. "Accept all open — document in accepted risks log" → add to SECURITY.md accepted risks, set all CLOSED, Step 6
3. "Cancel" → exit

5. Spawn gsd-security-auditor

Task(
  prompt="Read $HOME/.claude/agents/gsd-security-auditor.md for instructions.\n\n" +
    "<files_to_read>{PLAN, SUMMARY, impl files, SECURITY.md}</files_to_read>" +
    "<threat_register>{threat register}</threat_register>" +
    "<config>asvs_level: {SECURITY_ASVS}, block_on: {SECURITY_BLOCK_ON}</config>" +
    "<constraints>Never modify implementation files. Verify mitigations exist — do not scan for new threats. Escalate implementation gaps.</constraints>" +
    "${AGENT_SKILLS_AUDITOR}",
  subagent_type="gsd-security-auditor",
  model="{AUDITOR_MODEL}",
  description="Verify threat mitigations for Phase {N}"
)

Handle return:

• ## SECURED → record closures → Step 6
• ## OPEN_THREATS → record closed + open, present user with accept/block choice → Step 6
• ## ESCALATE → present to user → Step 6

6. Write/Update SECURITY.md

State B (create):

1. Read template from ${CLAUDE_PLUGIN_ROOT}/templates/SECURITY.md
2. Fill: frontmatter, threat register, accepted risks, audit trail
3. Write to ${PHASE_DIR}/${PADDED_PHASE}-SECURITY.md

State A (update):

1. Update threat register statuses, append to audit trail:

## Security Audit {date}
| Metric | Count |
|--------|-------|
| Threats found | {N} |
| Closed | {M} |
| Open | {K} |

ENFORCING GATE: If threats_open > 0 after all options exhausted (user did not accept, not all verified closed):

GSD > PHASE {N} SECURITY BLOCKED
{K} threats open — phase advancement blocked until threats_open: 0
▶ Fix mitigations then re-run: /gsd-secure-phase {N}
▶ Or document accepted risks in SECURITY.md and re-run.

Do NOT emit next-phase routing. Stop here.

7. Commit

node "$GSD_TOOLS" commit "docs(phase-${PHASE}): add/update security threat verification"

8. Results + Routing

Secured (threats_open: 0):

GSD > PHASE {N} THREAT-SECURE
threats_open: 0 — all threats have dispositions.
▶ /gsd-validate-phase {N}    validate test coverage
▶ /gsd-verify-work {N}       run UAT

Display /clear reminder.

<success_criteria>

• Security enforcement checked — exit if false
• Input state detected (A/B/C) — state C exits cleanly
• PLAN.md threat model parsed, register built
• SUMMARY.md threat flags incorporated
• threats_open: 0 → skip directly to Step 6
• User gate with threat table presented
• Auditor spawned with complete context
• All three return formats (SECURED/OPEN_THREATS/ESCALATE) handled
• SECURITY.md created or updated
• threats_open > 0 BLOCKS advancement (no next-phase routing emitted)
• Results with routing presented on success </success_criteria>

Phase: $ARGUMENTS — optional, defaults to last completed phase. Execute Preserve all workflow gates.