147 Workflow 097c5b9a

WORKFLOW.md - Orchestration Contracts

Version: 3.0.3 (20260209a) Purpose: Phase orchestration, structured data contracts, validation gates, FSM-enforced execution

Cross-References:

• Global constraints and data model: See SKILL.md
• FSM formal specification: See docs/SKILL-ARCHITECTURE-DESIGN.md §0.1-0.2

§1 Workflow State Machine (FSM)

8-Phase FSM Definition

┌─────────────────────────────────────────────────────────────────┐
│                    STRIDE Threat Modeling FSM                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  States: {INIT, P1, P2, P3, P4, P5, P6, P7, P8, P8R, DONE, ERROR}│
│                                                                  │
│  Transitions:                                                    │
│    δ(INIT, start) → P1                                          │
│    δ(Pn, pn_complete) → P(n+1)  where n ∈ {1..7}                │
│    δ(P8, p8_complete ∧ detailed) → P8R                          │
│    δ(P8, p8_complete ∧ ¬detailed) → DONE                        │
│    δ(P8R, p8r_complete) → DONE                                  │
│    δ(Pn, validation_fail) → ERROR                               │
│    δ(ERROR, recovery_success) → Pn  (rollback)                  │
│                                                                  │
│  Accepting States: {DONE}                                        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

State Transition Diagram

    INIT ──start──► P1 ──p1_complete──► P2 ──► P3 ──► P4 ──► P5 ──► P6 ──► P7 ──► P8 ──┬──► DONE
                     │                   │      │      │      │      │      │      │     │
                     └─validation_fail──►├──────┴──────┴──────┴──────┴──────┴──────┘     │
                                         ▼                                                │
                                       ERROR ──recovery_success──► (rollback)             │
                                                                                          │
                                         (if --detailed or user confirms)                 │
                                         P8 ──p8_complete∧detailed──► P8R ──p8r_complete──┘

Phase Internal 4-Gate Sub-FSM

Each Phase Pn internally follows:

ENTRY ──[check_pass]──► THINKING ──► PLANNING ──► EXECUTING ◄──loop──► REFLECTING ──► EXIT
  │                                                                                      │
  └──[check_fail]────────────────────────────────────────────────────────────────────────┘
                                                                            (emit pn_complete)

Entry Gate Details: See each @phases/P{N}-*.md file

§1.1 Data Flow Architecture

Principle: YAML is data (machine-readable), Markdown is report (human-readable). Separate concerns! Directory structure definition: See SKILL.md §2.2

DATA FLOW CHAIN (strict, no gaps):
  P1 → writes P1_project_context.yaml → P2 reads it
  P2 → writes P2_dfd_elements.yaml → P3 reads it
  ...
  P7 → writes P7_mitigation_plan.yaml → P8 reads it
  P8R (optional) → reads P6+P7+P8 YAML → writes P8R_manifest.yaml + VR-xxx.md files

❌ FORBIDDEN: P{N+1} reading P{N}'s .md report for data extraction
✅ REQUIRED: P{N+1} reading P{N}'s .yaml data file directly

§1.2 Session Initialization

Session ID Generation

Format Definition: See SKILL.md §2.4

SESSION_ID = {PROJECT_NAME}_{YYYYMMDD_HHMMSS}
Example: OPEN-WEBUI_20260130_143022

Directory Creation

SESSION_ID="${PROJECT_NAME}_$(date +%Y%m%d_%H%M%S)"
mkdir -p ".phase_working/${SESSION_ID}/data"
mkdir -p ".phase_working/${SESSION_ID}/reports"

Session Metadata Schema

# .phase_working/{SESSION_ID}/_session_meta.yaml
schema_version: "3.0.3 (20260209a)"
session_id: "{PROJECT}_{YYYYMMDD_HHMMSS}"
project_name: "PROJECT-NAME"
project_path: "/absolute/path"
started_at: "ISO8601"
language: "en"                    # en|zh|ja|ko
skill_version: "3.0.3 (20260209a)"
current_state: "P1"               # FSM current state

phases:
  P{N}:
    status: "pending|in_progress|completed|failed"
    started_at: null
    completed_at: null
    data_file: "data/P{N}_*.yaml"
    report_file: "reports/P{N}-*.md"
    validation:
      exit_code: null
      errors: []

Sessions Index (Optional)

# .phase_working/_sessions_index.yaml
sessions:
  - session_id: "OPEN-WEBUI_20260130_143022"
    project_name: "OPEN-WEBUI"
    started_at: "2026-01-30T14:30:22Z"
    status: "completed"
    current_phase: 8
  - session_id: "OPEN-WEBUI_20260129_100000"
    project_name: "OPEN-WEBUI"
    started_at: "2026-01-29T10:00:00Z"
    status: "completed"
    current_phase: 8

Todo Creation

Create 8 items at session start:

[
  {"content": "Phase 1: Project Understanding", "status": "pending"},
  {"content": "Phase 2: Call Flow & DFD Analysis", "status": "pending"},
  {"content": "Phase 3: Trust Boundary Evaluation", "status": "pending"},
  {"content": "Phase 4: Security Design Review", "status": "pending"},
  {"content": "Phase 5: STRIDE Threat Analysis", "status": "pending"},
  {"content": "Phase 6: Risk Validation", "status": "pending"},
  {"content": "Phase 7: Mitigation Planning", "status": "pending"},
  {"content": "Phase 8: Report Generation", "status": "pending"}
]

# If --detailed flag is set, also add:
# {"content": "Phase 8R: Detailed Risk Analysis (optional)", "status": "pending"}

§2 Phase Execution Protocol

FSM Enforcement: Phase transitions are governed by the FSM defined in §1. Entry Gate Details: See @phases/P{N}-*.md for per-phase 4-Gate protocol. Global Constraints: See SKILL.md §10-11 for execution invariants.

Phase Execution Algorithm

FOR each phase N in [1..8]:
  1. PRECONDITION: current_state == P{N-1}.completed (except P1)
  2. Read @phases/P{N}-*.md (instructions)
  3. Execute 4-Gate: ENTRY → THINKING → PLANNING → EXECUTING → REFLECTING → EXIT
  4. Write: data/P{N}_*.yaml (PRIMARY)
  5. Write: reports/P{N}-*.md (SECONDARY)
  6. PostToolUse hook validates YAML
  7. IF exit_code == 0: δ(P{N}, p{n}_complete) → P{N+1}
  8. IF exit_code != 0: δ(P{N}, validation_fail) → ERROR, then fix and retry

POST-P8 (Optional P8R):
  IF --detailed flag OR user confirms after P8:
    1. Read @phases/P8R-DETAILED-REPORT.md
    2. Read P6+P7+P8 YAML data
    3. Generate per-VR detailed analysis reports (12 elements each)
    4. Write: Risk_Assessment_Report/detailed/VR-{NNN}-{slug}.md
    5. Write: data/P8R_manifest.yaml

Checkpoint Phases (User Confirmation Required)

§3 Phase Data Contracts (YAML Files)

Complete Schema Definitions: See @assets/contracts/data-model.yaml

Contract Summary Table

Common Header (All Phases)

schema_version: "3.0.3 (20260209a)"
phase: {N}
generated_at: "ISO8601"
input_ref: "P{N-1}_*.yaml"  # Traceability (except P1)

P5 Threat ID Format

# Threat ID: T-{STRIDE}-{ElementID}-{Seq}
# Example: T-S-P001-001 (Spoofing threat for Process P-001)
threats:
  - id: T-S-P001-001
    stride_category: "S"
    element_id: "P-001"
    cwe_refs: ["CWE-287"]
    capec_refs: ["CAPEC-151"]

P6 Count Conservation (CRITICAL)

risk_summary:
  total_identified: 45      # From P5
  total_verified: 15        # Exploitable
  total_theoretical: 20     # Possible
  total_pending: 5          # Under investigation
  total_excluded: 5         # False positives
  # INVARIANT: 15 + 20 + 5 + 5 = 45

risk_details:
  - id: VR-001
    threat_refs: ["T-S-P001-001"]  # Links back to P5
    validation_status: "verified|theoretical|pending|excluded"

P7 Mitigation Priority

mitigation_plan:
  mitigations:
    - id: MIT-001
      risk_refs: ["VR-001"]  # Links back to P6
      priority: "P0|P1|P2|P3"
  roadmap:
    immediate: ["MIT-001"]   # P0: Fix now
    short_term: ["MIT-003"]  # P1: 7 days
    medium_term: ["MIT-004"] # P2: 30 days
    long_term: ["MIT-006"]   # P3: Backlog

§4 Validation Gates

Exit Codes

Phase-Specific Validation

Count Conservation

P5.threat_inventory.summary.total ==
  P6.risk_summary.total_verified +
  P6.risk_summary.total_theoretical +
  P6.risk_summary.total_pending +
  P6.risk_summary.total_excluded

§5 STRIDE per Element Matrix

§6 Error Recovery

Validation Failure

1. Read error message from validation output
2. Identify missing/invalid fields in YAML
3. Fix YAML data file
4. Re-run validation
5. Only then update report

Session Interruption

1. Check .phase_working/{SESSION_ID}/_session_meta.yaml
2. Find last phase with status: "completed"
3. Load that phase's YAML data file from data/ subdirectory
4. Resume from next phase

SESSION_ID Format: {PROJECT_NAME}_{YYYYMMDD_HHMMSS} Example: OPEN-WEBUI_20260130_143022

§7 Final Report Output

Directory Structure: See SKILL.md §2.2 for complete structure Naming Convention: See SKILL.md §2.3

Report Summary

Multi-Session Support

.phase_working/
├── _sessions_index.yaml                   ← Optional session index
├── {PROJECT}_{YYYYMMDD_HHMMSS}/          ← Historical sessions
└── {PROJECT}_{YYYYMMDD_HHMMSS}/          ← Current session (active)

Session isolation enables: Incremental analysis, historical comparison, rollback capability

End of WORKFLOW.md (~380 lines, ~4.5K tokens)