spec-driven-remediation

Spec-Driven Remediation

Apply automated and guided fixes to story, epic, and context files based on structured audit findings from /validate-stories. Every step uses Execute-Verify-Record to prevent token optimization bias from skipping phases.

Audit findings are the input. Fixed files are the output. User approval gates every structural change.

If ambiguous or conflicts detected: HALT and use ask the user

---

Execution Model

See .claude/rules/core/anti-skip-behavior.md for the canonical execution contract (expand inline; do not wait passively or offer execution options; honor every step of every phase; Self-Check violation taxonomy; Token-Optimization-Bias prohibition; governed by ADR-076). After invocation, execute Phase State Initialization immediately.

---

Anti-Skip Enforcement Contract

Enforced structurally outside LLM control, not by this prose — by the framework's deterministic gates wired for this workflow: the devforgeai-validate phase gates, the settings.json-registered .codex/hooks/ scripts, and .codex/hooks/phase-steps-registry.json (ADR-076). Behavioral residue: .claude/rules/core/anti-skip-behavior.md.

---

Parameter Extraction

Extract parameters from conversation context markers set by /fix-story command. See references/parameter-extraction.md for the extraction algorithm.

Command Integration

Context Marker	Set By	Description
$FIX_MODE	/fix-story	Input mode: audit_file, story_id, or epic_id
$AUDIT_FILE	/fix-story	Path to audit file
$DRY_RUN	/fix-story	true = preview only, no file modifications
$AUTO_ONLY	/fix-story	true = skip interactive and ADR fixes
$FINDING_FILTER	/fix-story	F-NNN for single finding, "all" for everything

---

Phase State Initialization [MANDATORY FIRST]

Derive SESSION_ID from audit file name:

SESSION_ID = "FIX-" + basename(AUDIT_FILE).replace(".md", "")
# Example: "FIX-custody-chain-audit-stories-413-424"

devforgeai-validate phase-init ${SESSION_ID} --workflow=remediation --project-root=.

Exit Code	Meaning	Action
0	New workflow	State file created. Set CURRENT_PHASE = "00".
1	Existing workflow	Resume. Check checkpoint file for CURRENT_PHASE.
2	Invalid session ID	HALT. Verify audit file path.
127	CLI not installed	Continue without enforcement (backward compatibility).

Resume Detection: If resuming, read checkpoint:

inspect `{project-root}/tmp/.remediation-checkpoint-${SESSION_ID}.yaml`

Extract current_phase and phase_completion to determine where to resume.

---

Phase Orchestration Loop

FOR phase_num in range(CURRENT_PHASE, 06):
    phase_id = format(phase_num, "02d")

    1. ENTRY GATE: devforgeai-validate phase-check ${SESSION_ID} --workflow=remediation --from={prev} --to={phase_id}
       IF exit != 0: HALT

    2. LOAD: inspect `phases/{phase_files[phase_id]}`

    3. EXECUTE: Follow every step in the phase file (EXECUTE-VERIFY-RECORD triplets)
       - Each step's EXECUTE instruction tells you exactly what to do
       - Each step's VERIFY instruction tells you how to confirm it happened
       - Each step's RECORD instruction tells you what CLI command to call

    4. RECORD: devforgeai-validate phase-record ${SESSION_ID} --workflow=remediation --phase={phase_id}

    5. EXIT GATE: devforgeai-validate phase-complete ${SESSION_ID} --workflow=remediation --phase={phase_id} --checkpoint-passed
       IF exit != 0: HALT

Dry Run Skip Path: If $DRY_RUN == true, Phase 02 exits early and skips directly to Phase 05 (report only, no modifications).

Phase	Name	File
00	Context Loading + Finding Extraction	phases/phase-00-context-loading.md
01	Finding Triage + Classification	phases/phase-01-triage.md
02	Safety Preview	phases/phase-02-preview.md
03	Fix Execution	phases/phase-03-execution.md
04	Post-Fix Verification	phases/phase-04-verification.md
05	Fix Report + Session Record	phases/phase-05-reporting.md

---

State Persistence

Phase State: devforgeai/workflows/${SESSION_ID}-remediation-phase-state.json Session Memory: .claude/memory/sessions/${SESSION_ID}-remediation-session.md Checkpoint: {project-root}/tmp/.remediation-checkpoint-${SESSION_ID}.yaml References: references/checkpoint-schema.md, references/memory-file-operations.md

---

Workflow Completion Validation

IF completed_count < 6: HALT "WORKFLOW INCOMPLETE - {completed_count}/6 phases"
IF completed_count == 6: "All 6 phases completed - Remediation workflow passed"

---

Success Criteria

• All findings loaded and classified correctly
• Automated fixes applied only after user confirmation
• Interactive fixes presented with clear resolution options
• All applied fixes pass post-fix verification
• Fix report generated with accurate summary
• Session record appended to audit file for resume capability
• No files modified without user approval (--dry-run respected)
• Deferred items properly marked with AUDIT-DEFERRED comments

---

Reference Files

Phase Execution (phases/ directory)

File	Phase
phase-00-context-loading.md	Context Loading + Finding Extraction
phase-01-triage.md	Finding Triage + Classification
phase-02-preview.md	Safety Preview
phase-03-execution.md	Fix Execution
phase-04-verification.md	Post-Fix Verification
phase-05-reporting.md	Fix Report + Session Record

Supporting References (references/ directory)

File	Purpose
fix-actions-catalog.md	Classification matrix and fix procedures for each finding type
fix-verification-workflow.md	Per-type verification procedures and feedback loop protocol
context-validation.md	Context file constraint validation rules
checkpoint-schema.md	Checkpoint YAML schema for remediation sessions
memory-file-operations.md	Session memory file read/write operations
parameter-extraction.md	Audit file resolution and parameter extraction algorithm

Templates (assets/templates/ directory)

File	Purpose
fix-report-template.md	Fix session report markdown template
checkpoint-template.yaml	Checkpoint YAML structure template