claude-code-workflow 7.2.27 → 7.2.28

package/.codex/skills/investigate/phases/05-verification-report.md

@@ -0,0 +1,240 @@
+# Phase 5: Verification & Report
+
+> **COMPACT PROTECTION**: This is a core execution phase. If context compression has occurred and this file is only a summary, **MUST `Read` this file again before executing any Step**. Do not execute from memory.
+
+Run full test suite, check for regressions, and generate the structured debug report.
+
+## Objective
+
+- Run the full test suite to verify no regressions were introduced
+- Generate a structured debug report for future reference
+- Output the report to `.workflow/.debug/` directory
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| investigation-report (phases 1-4) | Yes | All phases populated: evidence, root cause, fix_applied |
+| assign_task message | Yes | Phase 5 instruction |
+
+## Execution Steps
+
+### Step 1: Detect and Run Full Test Suite
+
+Detect the project's test framework by checking for project files, then run the full suite:
+
+| Detection file | Test command |
+|---------------|-------------|
+| `package.json` with `test` script | `npm test` |
+| `pytest.ini` or `pyproject.toml` | `pytest` |
+| `go.mod` | `go test ./...` |
+| `Cargo.toml` | `cargo test` |
+| `Makefile` with `test` target | `make test` |
+| None detected | Try `npm test`, `pytest`, `go test ./...` sequentially |
+
+```
+Bash: mkdir -p .workflow/.debug
+Bash: <detected test command>
+```
+
+Record test results:
+
+```
+test_results = {
+  total: <count>,
+  passed: <count>,
+  failed: <count>,
+  skipped: <count>,
+  regression_test_passed: true|false,
+  new_failures: []
+}
+```
+
+---
+
+### Step 2: Regression Check
+
+Verify specifically:
+
+1. The new regression test passes (check by test name from fix_applied.regression_test.test_name).
+2. All tests that were passing before the fix still pass.
+3. No new warnings or errors appeared in test output.
+
+**Decision table for new failures**:
+
+| New failure | Assessment | Action |
+|-------------|-----------|--------|
+| Related to fix (same module, same code path) | Fix introduced regression | Return to Phase 4 to adjust fix |
+| Unrelated to fix (different module, pre-existing) | Pre-existing failure | Document in pre_existing_failures, proceed |
+| Regression test itself fails | Fix is not working correctly | Return to Phase 4 |
+
+Classify failures:
+
+```
+regression_check_result = {
+  passed: true|false,
+  total_tests: <count>,
+  new_failures: ["<test names that newly fail>"],
+  pre_existing_failures: ["<tests that were already failing>"]
+}
+```
+
+---
+
+### Step 3: Generate Structured Debug Report
+
+Compile all investigation data into the final debug report JSON following the schema from `~/.codex/skills/investigate/specs/debug-report-format.md`:
+
+```
+debug_report = {
+  "bug_description": "<concise one-sentence description of the bug>",
+  "reproduction_steps": [
+    "<step 1>",
+    "<step 2>",
+    "<step 3: observe error>"
+  ],
+  "root_cause": "<confirmed root cause description with technical detail and file:line reference>",
+  "evidence_chain": [
+    "Phase 1: <error message X observed in module Y>",
+    "Phase 2: <pattern analysis found N similar occurrences>",
+    "Phase 3: hypothesis H<N> confirmed — <specific condition at file:line>"
+  ],
+  "fix_description": "<what was changed and why>",
+  "files_changed": [
+    {
+      "path": "<src/module/file.ts>",
+      "change_type": "add|modify|remove",
+      "description": "<brief description of changes to this file>"
+    }
+  ],
+  "tests_added": [
+    {
+      "file": "<src/module/__tests__/file.test.ts>",
+      "test_name": "<should handle null return from X>",
+      "type": "regression|unit|integration"
+    }
+  ],
+  "regression_check_result": {
+    "passed": true|false,
+    "total_tests": <count>,
+    "new_failures": [],
+    "pre_existing_failures": []
+  },
+  "completion_status": "DONE|DONE_WITH_CONCERNS|BLOCKED",
+  "concerns": [],
+  "timestamp": "<ISO-8601 timestamp>",
+  "investigation_duration_phases": 5
+}
+```
+
+**Field sources**:
+
+| Field | Source Phase | Description |
+|-------|-------------|-------------|
+| `bug_description` | Phase 1 | User-reported symptom, one sentence |
+| `reproduction_steps` | Phase 1 | Ordered steps to trigger the bug |
+| `root_cause` | Phase 3 | Confirmed cause with file:line reference |
+| `evidence_chain` | Phase 1-3 | Each item prefixed with "Phase N:" |
+| `fix_description` | Phase 4 | What code was changed and why |
+| `files_changed` | Phase 4 | Each file with change type and description |
+| `tests_added` | Phase 4 | Regression tests covering the bug |
+| `regression_check_result` | Phase 5 | Full test suite results |
+| `completion_status` | Phase 5 | Final status per protocol |
+| `concerns` | Phase 5 | Non-blocking issues (if any) |
+| `timestamp` | Phase 5 | When report was generated |
+| `investigation_duration_phases` | Phase 5 | Always 5 for complete investigation |
+
+---
+
+### Step 4: Write Report File
+
+Compute the filename:
+- `<slug>` = bug_description lowercased, non-alphanumeric characters replaced with `-`, truncated to 40 chars
+- `<date>` = current date as YYYY-MM-DD
+
+```
+Bash: mkdir -p .workflow/.debug
+Write: .workflow/.debug/debug-report-<date>-<slug>.json
+Content: <debug_report JSON with 2-space indent>
+```
+
+---
+
+### Step 5: Output Completion Status
+
+Determine status and output completion block:
+
+**Status determination**:
+
+| Condition | Status |
+|-----------|--------|
+| Regression test passes, no new failures, all quality checks met | DONE |
+| Fix applied but partial test coverage, minor warnings, or non-critical concerns | DONE_WITH_CONCERNS |
+| New test failures introduced by fix (unresolvable), or critical concern | BLOCKED |
+
+**DONE output**:
+
+```
+## STATUS: DONE
+
+**Summary**: Fixed <bug_description> — root cause was <root_cause_summary>
+
+### Details
+- Phases completed: 5/5
+- Root cause: <confirmed_root_cause.description>
+- Fix: <fix_description>
+- Regression test: <test_name> in <test_file>
+
+### Outputs
+- Debug report: .workflow/.debug/debug-report-<date>-<slug>.json
+- Files changed: <list>
+- Tests added: <list>
+```
+
+**DONE_WITH_CONCERNS output**:
+
+```
+## STATUS: DONE_WITH_CONCERNS
+
+**Summary**: Fixed <bug_description> with concerns
+
+### Details
+- Phases completed: 5/5
+- Concerns:
+  1. <concern> — Impact: low|medium — Suggested fix: <action>
+
+### Outputs
+- Debug report: .workflow/.debug/debug-report-<date>-<slug>.json
+- Files changed: <list>
+- Tests added: <list>
+```
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| `.workflow/.debug/debug-report-<date>-<slug>.json` | JSON file | Full structured investigation report |
+| Completion status block | Structured text output | Final status per Completion Status Protocol |
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| Full test suite executed | Test command ran and produced output |
+| Regression test passes | test_results.regression_test_passed: true |
+| No new failures introduced | regression_check_result.new_failures is empty (or documented as pre-existing) |
+| Debug report written | File exists at `.workflow/.debug/debug-report-<date>-<slug>.json` |
+| Completion status output | Status block follows protocol format |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Test framework not detected | Try common commands in order; document uncertainty in concerns |
+| New failures related to fix | Return to Phase 4 to adjust; do not write report until resolved |
+| New failures unrelated | Document as pre_existing_failures, set DONE_WITH_CONCERNS if impactful |
+| Report directory not writable | Try alternate path `.workflow/debug/`; document in output |
+| Test suite takes >5 minutes | Run regression test only; note full suite skipped in concerns |
+| Regression test was not added in Phase 4 | Document as DONE_WITH_CONCERNS concern |

package/.codex/skills/security-audit/agents/security-auditor.md

@@ -0,0 +1,341 @@
+# Security Auditor Agent
+
+Executes all 4 phases of the security audit: supply chain scan, OWASP Top 10 review, STRIDE threat modeling, and scored report generation. Driven by orchestrator via assign_task through each phase.
+
+## Identity
+
+- **Type**: `analysis`
+- **Role File**: `~/.codex/agents/security-auditor.md`
+- **task_name**: `security-auditor`
+- **Responsibility**: Read-only analysis (Phases 1–3) + Write (Phase 4 report output)
+- **fork_context**: false
+- **Reasoning Effort**: high
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern
+- Produce structured JSON output for every phase
+- Include file:line references in all code-level findings
+- Enforce scoring gates: quick-scan >= 8/10; comprehensive initial >= 2/10
+- Deduplicate findings that appear in multiple phases (keep highest severity, merge evidence)
+- Write phase output files to `.workflow/.security/` before reporting completion
+
+### MUST NOT
+
+- Skip phases in comprehensive mode — all 4 phases must complete in sequence
+- Proceed to next phase before writing current phase output file
+- Include sensitive discovered values (actual secrets, credentials) in JSON evidence fields — redact with `[REDACTED]`
+- Apply suppression (`@ts-ignore`, empty catch) — report findings as-is
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Bash` | execution | Run dependency audits, grep patterns, file discovery, directory setup |
+| `Read` | read | Load phase files, specs, previous audit reports |
+| `Write` | write | Output JSON phase results to `.workflow/.security/` |
+| `Glob` | read | Discover source files by pattern for scoping |
+| `Grep` | read | Pattern-based security scanning across source files |
+| `spawn_agent` | agent | Spawn inline subagent for OWASP CLI analysis (Phase 2) |
+| `wait_agent` | agent | Await inline subagent result |
+| `close_agent` | agent | Close inline subagent after result received |
+
+### Tool Usage Patterns
+
+**Setup Pattern**: Ensure work directory exists before any phase output.
+```
+Bash("mkdir -p .workflow/.security")
+```
+
+**Read Pattern**: Load phase spec before executing.
+```
+Read("~/.codex/skills/security-audit/phases/01-supply-chain-scan.md")
+Read("~/.codex/skills/security-audit/specs/scoring-gates.md")
+```
+
+**Write Pattern**: Output structured JSON after each phase.
+```
+Write(".workflow/.security/supply-chain-report.json", <json_content>)
+```
+
+---
+
+## Execution
+
+### Phase 1: Supply Chain Scan
+
+**Objective**: Detect vulnerable dependencies, hardcoded secrets, CI/CD injection risks, and LLM prompt injection vectors.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Phase spec | Yes | `~/.codex/skills/security-audit/phases/01-supply-chain-scan.md` |
+| Project root | Yes | Working directory with source files |
+
+**Steps**:
+
+1. Read `~/.codex/skills/security-audit/phases/01-supply-chain-scan.md` for full execution instructions.
+2. Run Step 1 — Dependency Audit: detect package manager and run npm audit / pip-audit / govulncheck.
+3. Run Step 2 — Secrets Detection: regex scan for API keys, AWS patterns, private keys, connection strings, JWT tokens.
+4. Run Step 3 — CI/CD Config Review: scan `.github/workflows/` for expression injection and pull_request_target risks.
+5. Run Step 4 — LLM/AI Prompt Injection Check: scan for user input concatenated into LLM prompts.
+6. Classify each finding with category, severity, file, line, evidence (redact actual secret values), remediation.
+7. Write output file.
+
+**Decision Table — Dependency Audit**:
+
+| Condition | Action |
+|-----------|--------|
+| npm / yarn lock file found | Run `npm audit --json` |
+| requirements.txt / pyproject.toml found | Run `pip-audit --format json`; fallback to `safety check --json` |
+| go.sum found | Run `govulncheck ./...` |
+| No lock files found | Log INFO finding: "No lock files detected"; continue |
+| Audit tool not installed | Log INFO finding: "<tool> not installed"; continue |
+
+**Decision Table — Secrets Detection**:
+
+| Pattern Match | Severity | Category |
+|---------------|----------|----------|
+| API key / secret / token with 16+ char value | Critical | secret |
+| AWS AKIA key pattern | Critical | secret |
+| `-----BEGIN PRIVATE KEY-----` | Critical | secret |
+| DB connection string with password | Critical | secret |
+| Hardcoded JWT token | High | secret |
+
+**Output**: `.workflow/.security/supply-chain-report.json` — schema per phase spec.
+
+---
+
+### Phase 2: OWASP Review
+
+**Objective**: Systematic code-level review against all 10 OWASP Top 10 2021 categories.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Phase spec | Yes | `~/.codex/skills/security-audit/phases/02-owasp-review.md` |
+| OWASP checklist | Yes | `~/.codex/skills/security-audit/specs/owasp-checklist.md` |
+| Supply chain report | Yes | `.workflow/.security/supply-chain-report.json` |
+
+**Steps**:
+
+1. Read `~/.codex/skills/security-audit/phases/02-owasp-review.md` for full execution instructions.
+2. Read `~/.codex/skills/security-audit/specs/owasp-checklist.md` for detection patterns.
+3. Run Step 1 — Identify target scope: discover source files excluding node_modules, dist, build, vendor, __pycache__.
+4. Run Step 2 — Spawn inline OWASP analysis subagent (see Inline Subagent section below).
+5. Run Step 3 — Manual pattern scanning: run targeted grep patterns per OWASP category (A01, A03, A05, A07).
+6. Run Step 4 — Consolidate: merge CLI analysis results with manual scan results; deduplicate.
+7. Set coverage field for each category: `checked` or `not_applicable`.
+8. Write output file.
+
+**Decision Table — Scope**:
+
+| Condition | Action |
+|-----------|--------|
+| Source files found | Proceed with full scan |
+| No source files detected | Report as BLOCKED with scope note |
+| Files > 500 | Prioritize: routes/, auth/, api/, handlers/ first |
+
+**Output**: `.workflow/.security/owasp-findings.json` — schema per phase spec.
+
+---
+
+## Inline Subagent: OWASP CLI Analysis (Phase 2, Step 2)
+
+**When**: After identifying target scope in Phase 2, Step 2.
+
+**Agent File**: `~/.codex/agents/cli-explore-agent.md`
+
+```
+spawn_agent({
+  task_name: "inline-owasp-analysis",
+  fork_context: false,
+  model: "haiku",
+  reasoning_effort: "medium",
+  message: `### MANDATORY FIRST STEPS
+1. Read: ~/.codex/agents/cli-explore-agent.md
+
+Goal: OWASP Top 10 2021 security analysis of this codebase.
+Systematically check each OWASP category:
+A01 Broken Access Control | A02 Cryptographic Failures | A03 Injection |
+A04 Insecure Design | A05 Security Misconfiguration | A06 Vulnerable Components |
+A07 Identification/Auth Failures | A08 Software/Data Integrity Failures |
+A09 Security Logging/Monitoring Failures | A10 SSRF
+
+Scope: @src/**/* @**/*.config.* @**/*.env.example
+
+Expected: JSON findings per OWASP category with severity, file:line, evidence, remediation.
+
+Constraints: Code-level analysis only | Every finding must have file:line reference | Focus on real vulnerabilities not theoretical risks`
+})
+const result = wait_agent({ targets: ["inline-owasp-analysis"], timeout_ms: 300000 })
+close_agent({ target: "inline-owasp-analysis" })
+```
+
+**Result Handling**:
+
+| Result | Action |
+|--------|--------|
+| Success | Integrate findings into owasp-findings.json consolidation step |
+| Timeout / Error | Continue with manual pattern scan results only; log warning |
+
+---
+
+### Phase 3: Threat Modeling
+
+**Objective**: Apply STRIDE framework to architecture components; identify trust boundaries and attack surface.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Phase spec | Yes | `~/.codex/skills/security-audit/phases/03-threat-modeling.md` |
+| Supply chain report | Yes | `.workflow/.security/supply-chain-report.json` |
+| OWASP findings | Yes | `.workflow/.security/owasp-findings.json` |
+
+**Steps**:
+
+1. Read `~/.codex/skills/security-audit/phases/03-threat-modeling.md` for full execution instructions.
+2. Run Step 1 — Architecture Component Discovery: scan for entry points, data stores, external services, auth modules.
+3. Run Step 2 — Trust Boundary Identification: map all 5 boundary types (external, service, data, internal, process).
+4. Run Step 3 — STRIDE per Component: evaluate all 6 categories (S, T, R, I, D, E) for each discovered component.
+5. Run Step 4 — Attack Surface Assessment: quantify public endpoints, external integrations, input points, privileged operations, sensitive data stores.
+6. Cross-reference Phase 1 and Phase 2 findings when populating `gaps` arrays.
+7. Write output file.
+
+**STRIDE Evaluation Decision Table**:
+
+| Component Type | Priority STRIDE Categories |
+|----------------|---------------------------|
+| api_endpoint | S (spoofing), T (tampering), D (denial-of-service), E (elevation) |
+| auth_module | S (spoofing), R (repudiation), E (elevation) |
+| data_store | T (tampering), I (information disclosure), R (repudiation) |
+| external_service | T (tampering), I (information disclosure), D (denial-of-service) |
+| worker | T (tampering), D (denial-of-service) |
+
+**Output**: `.workflow/.security/threat-model.json` — schema per phase spec.
+
+---
+
+### Phase 4: Report & Tracking
+
+**Objective**: Aggregate all findings, calculate score, compare trends, write dated report.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Phase spec | Yes | `~/.codex/skills/security-audit/phases/04-report-tracking.md` |
+| Scoring gates | Yes | `~/.codex/skills/security-audit/specs/scoring-gates.md` |
+| Supply chain report | Yes | `.workflow/.security/supply-chain-report.json` |
+| OWASP findings | Yes | `.workflow/.security/owasp-findings.json` |
+| Threat model | Yes | `.workflow/.security/threat-model.json` |
+| Previous audits | No | `.workflow/.security/audit-report-*.json` (for trend) |
+
+**Steps**:
+
+1. Read `~/.codex/skills/security-audit/phases/04-report-tracking.md` for full execution instructions.
+2. Aggregate all findings from phases 1–3 (supply-chain + owasp + STRIDE gaps).
+3. Deduplicate: same vulnerability across phases → keep highest severity, merge evidence, count once.
+4. Count files scanned (from phase outputs).
+5. Calculate score per formula: `base_score(10.0) - (weighted_sum / max(10, files_scanned))`.
+6. Find previous audit: `ls -t .workflow/.security/audit-report-*.json 2>/dev/null | head -1`.
+7. Compute trend direction and score_delta.
+8. Evaluate gate (initial vs. subsequent logic).
+9. Build remediation_priority list: rank by severity × effort (low effort + high impact = priority 1).
+10. Write dated report.
+11. Copy phase outputs to `.workflow/.security/` as latest copies.
+
+**Score Calculation**:
+
+| Severity | Weight |
+|----------|--------|
+| critical | 10 |
+| high | 7 |
+| medium | 4 |
+| low | 1 |
+
+Formula: `final_score = max(0, round(10.0 - (weighted_sum / max(10, files_scanned)), 1))`
+
+**Score Interpretation Table**:
+
+| Score Range | Rating | Meaning |
+|-------------|--------|---------|
+| 9.0 – 10.0 | Excellent | Minimal risk, production-ready |
+| 7.0 – 8.9 | Good | Acceptable risk, minor improvements needed |
+| 5.0 – 6.9 | Fair | Notable risks, remediation recommended |
+| 3.0 – 4.9 | Poor | Significant risks, remediation required |
+| 0.0 – 2.9 | Critical | Severe vulnerabilities, immediate action needed |
+
+**Gate Evaluation**:
+
+| Condition | Gate Result | Status |
+|-----------|------------|--------|
+| No previous audit AND score >= 2.0 | PASS | Baseline established |
+| No previous audit AND score < 2.0 | FAIL | DONE_WITH_CONCERNS |
+| Previous audit AND score >= previous_score | PASS | No regression |
+| Previous audit AND score within 0.5 of previous | WARN | DONE_WITH_CONCERNS |
+| Previous audit AND score < previous_score - 0.5 | FAIL | DONE_WITH_CONCERNS |
+
+**Trend Direction**:
+
+| Condition | direction field |
+|-----------|----------------|
+| No previous audit | `baseline` |
+| score_delta > 0.5 | `improving` |
+| -0.5 <= score_delta <= 0.5 | `stable` |
+| score_delta < -0.5 | `regressing` |
+
+**Output**: `.workflow/.security/audit-report-<YYYY-MM-DD>.json` — full schema per phase spec.
+
+---
+
+## Structured Output Template
+
+```
+## Summary
+- One-sentence completion status with phase completed and finding count
+
+## Score (Phase 4 / quick-scan)
+- Score: <N>/10 (<Rating>)
+- Gate: PASS|FAIL|WARN
+- Trend: <improving|stable|regressing|baseline> (delta: <+/-N.N>)
+
+## Findings
+- Critical: <N>  High: <N>  Medium: <N>  Low: <N>
+
+## Phase Outputs Written
+- .workflow/.security/supply-chain-report.json
+- .workflow/.security/owasp-findings.json (if Phase 2 completed)
+- .workflow/.security/threat-model.json (if Phase 3 completed)
+- .workflow/.security/audit-report-<date>.json (if Phase 4 completed)
+
+## Top Risks
+1. [severity] <title> — <file>:<line> — <remediation summary>
+2. [severity] <title> — <file>:<line> — <remediation summary>
+
+## Open Questions
+1. <Any scope ambiguity or blocked items>
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Phase spec file not found | Read from fallback path; report in Open Questions if unavailable |
+| Dependency audit tool missing | Log as INFO finding (category: dependency), continue with other steps |
+| No source files found | Report as BLOCKED with path; request scope clarification |
+| Inline subagent timeout (Phase 2) | Continue with manual grep results only; note in findings summary |
+| Phase output file write failure | Retry once; if still failing report as BLOCKED |
+| Previous audit parse error | Treat as baseline (no prior data); note in trend section |
+| Timeout approaching mid-phase | Output partial results with "PARTIAL" status, write what is available |