claude-code-workflow 7.2.26 → 7.2.28

package/.codex/skills/security-audit/phases/04-report-tracking.md

@@ -0,0 +1,300 @@
+# Phase 4: Report & Tracking
+
+> **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.
+
+Generate scored audit report, compare with previous audits, and track security trends.
+
+## Objective
+
+- Calculate security score from all phase findings
+- Compare with previous audit results (if available)
+- Generate date-stamped report in `.workflow/.security/`
+- Track improvement or regression trends
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| `.workflow/.security/supply-chain-report.json` | Yes | Phase 1 findings |
+| `.workflow/.security/owasp-findings.json` | Yes | Phase 2 findings |
+| `.workflow/.security/threat-model.json` | Yes | Phase 3 findings (STRIDE gaps) |
+| `.workflow/.security/audit-report-*.json` | No | Previous audit reports for trend comparison |
+| `~/.codex/skills/security-audit/specs/scoring-gates.md` | Yes | Scoring formula and gate thresholds |
+
+## Execution Steps
+
+### Step 1: Aggregate Findings
+
+Collect all findings from phases 1–3 and classify by severity.
+
+**Aggregation Formula**:
+
+```
+All findings =
+  supply-chain-report.findings
+  + owasp-findings.findings
+  + threat-model threats (where gaps array is non-empty)
+```
+
+**Deduplication Rule**:
+
+| Condition | Action |
+|-----------|--------|
+| Same vulnerability appears in multiple phases | Keep highest-severity classification; merge evidence; count as single finding |
+| Same file:line in different categories | Merge into one finding; note all phases that detected it |
+| Unique finding per phase | Include as-is |
+
+---
+
+### Step 2: Calculate Score
+
+Apply scoring formula from `~/.codex/skills/security-audit/specs/scoring-gates.md`.
+
+**Scoring Formula**:
+
+```
+Base score = 10.0
+
+For each finding:
+  penalty = severity_weight / total_files_scanned
+  - Critical: weight = 10  (each critical finding has outsized impact)
+  - High:     weight = 7
+  - Medium:   weight = 4
+  - Low:      weight = 1
+
+Weighted penalty = SUM(finding_weight * count_per_severity) / normalization_factor
+Final score = max(0, 10.0 - weighted_penalty)
+
+Normalization factor = max(10, total_files_scanned)
+```
+
+**Severity Weights**:
+
+| Severity | Weight | Criteria | Examples |
+|----------|--------|----------|----------|
+| Critical | 10 | Exploitable with high impact, no user interaction needed | RCE, SQL injection with data access, leaked production credentials, auth bypass |
+| High | 7 | Exploitable with significant impact, may need user interaction | Broken authentication, SSRF, privilege escalation, XSS with session theft |
+| Medium | 4 | Limited exploitability or moderate impact | Reflected XSS, CSRF, verbose error messages, missing security headers |
+| Low | 1 | Informational or minimal impact | Missing best-practice headers, minor info disclosure, deprecated dependencies without known exploit |
+
+**Score Interpretation**:
+
+| Score | 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 |
+
+**Example Score Calculations**:
+
+| Findings | Files Scanned | Weighted Sum | Penalty | Score |
+|----------|--------------|--------------|---------|-------|
+| 1 critical | 50 | 10 | 0.2 | 9.8 |
+| 2 critical, 3 high | 50 | 41 | 0.82 | 9.2 |
+| 5 critical, 10 high | 50 | 120 | 2.4 | 7.6 |
+| 10 critical, 20 high, 15 medium | 100 | 300 | 3.0 | 7.0 |
+| 20 critical | 20 | 200 | 10.0 | 0.0 |
+
+---
+
+### Step 3: Gate Evaluation
+
+**Daily quick-scan gate** (Phase 1 only):
+
+| Result | Condition | Action |
+|--------|-----------|--------|
+| PASS | score >= 8.0 | Continue. No blocking issues. |
+| WARN | 6.0 <= score < 8.0 | Log warning. Review findings before deploy. |
+| FAIL | score < 6.0 | Block deployment. Remediate critical/high findings. |
+
+**Comprehensive audit gate** (all phases):
+
+Initial/baseline audit (no previous audit exists):
+
+| Result | Condition | Action |
+|--------|-----------|--------|
+| PASS | score >= 2.0 | Baseline established. Plan remediation. |
+| FAIL | score < 2.0 | Critical exposure. Immediate triage required. |
+
+Subsequent audits (previous audit exists):
+
+| Result | Condition | Action |
+|--------|-----------|--------|
+| PASS | score >= previous_score | No regression. Continue improvement. |
+| WARN | score within 0.5 of previous | Marginal change. Review new findings. |
+| FAIL | score < previous_score - 0.5 | Regression detected. Investigate new findings. |
+
+Production readiness target: score >= 7.0
+
+---
+
+### Step 4: Trend Comparison
+
+Find and compare with previous audit reports.
+
+**Execution**:
+
+```bash
+# Find previous audit reports
+ls -t .workflow/.security/audit-report-*.json 2>/dev/null | head -5
+```
+
+**Trend Direction Decision Table**:
+
+| Condition | direction |
+|-----------|-----------|
+| No previous audit file found | `baseline` |
+| score_delta > 0.5 | `improving` |
+| -0.5 <= score_delta <= 0.5 | `stable` |
+| score_delta < -0.5 | `regressing` |
+
+Compare current vs. previous:
+- Delta per OWASP category (new findings vs. resolved findings)
+- Delta per STRIDE category
+- New findings vs. resolved findings (by title/file comparison)
+- Overall score trend
+
+**Trend JSON Format**:
+
+```json
+{
+  "trend": {
+    "current_date": "2026-03-29",
+    "current_score": 7.5,
+    "previous_date": "2026-03-22",
+    "previous_score": 6.8,
+    "score_delta": 0.7,
+    "new_findings": 2,
+    "resolved_findings": 5,
+    "direction": "improving",
+    "history": [
+      { "date": "2026-03-15", "score": 5.2, "total_findings": 45 },
+      { "date": "2026-03-22", "score": 6.8, "total_findings": 32 },
+      { "date": "2026-03-29", "score": 7.5, "total_findings": 29 }
+    ]
+  }
+}
+```
+
+---
+
+### Step 5: Generate Report
+
+Assemble and write the final scored report.
+
+**Execution**:
+
+```bash
+# Ensure directory exists
+mkdir -p .workflow/.security
+
+# Write report with date stamp
+DATE=$(date +%Y-%m-%d)
+cp "${WORK_DIR}/audit-report.json" ".workflow/.security/audit-report-${DATE}.json"
+
+# Also maintain latest copies of phase outputs
+cp "${WORK_DIR}/supply-chain-report.json" ".workflow/.security/" 2>/dev/null || true
+cp "${WORK_DIR}/owasp-findings.json" ".workflow/.security/" 2>/dev/null || true
+cp "${WORK_DIR}/threat-model.json" ".workflow/.security/" 2>/dev/null || true
+```
+
+Build `remediation_priority` list: rank by severity weight × inverse effort (low effort + high impact = priority 1).
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| `.workflow/.security/audit-report-<YYYY-MM-DD>.json` | JSON | Full scored report with trend, top risks, remediation priority |
+
+```json
+{
+  "report": "security-audit",
+  "version": "1.0",
+  "timestamp": "ISO-8601",
+  "date": "YYYY-MM-DD",
+  "mode": "comprehensive|quick-scan",
+  "score": {
+    "overall": 7.5,
+    "rating": "Good",
+    "gate": "PASS|FAIL",
+    "gate_threshold": 8
+  },
+  "findings_summary": {
+    "total": 0,
+    "by_severity": { "critical": 0, "high": 0, "medium": 0, "low": 0 },
+    "by_phase": {
+      "supply_chain": 0,
+      "owasp": 0,
+      "stride": 0
+    },
+    "by_owasp": {
+      "A01": 0, "A02": 0, "A03": 0, "A04": 0, "A05": 0,
+      "A06": 0, "A07": 0, "A08": 0, "A09": 0, "A10": 0
+    },
+    "by_stride": { "S": 0, "T": 0, "R": 0, "I": 0, "D": 0, "E": 0 }
+  },
+  "top_risks": [
+    {
+      "rank": 1,
+      "title": "Most critical finding",
+      "severity": "critical",
+      "source_phase": "owasp",
+      "remediation": "How to fix",
+      "effort": "low|medium|high"
+    }
+  ],
+  "trend": {
+    "previous_date": "YYYY-MM-DD or null",
+    "previous_score": 0,
+    "score_delta": 0,
+    "new_findings": 0,
+    "resolved_findings": 0,
+    "direction": "improving|stable|regressing|baseline"
+  },
+  "phases_completed": ["supply-chain-scan", "owasp-review", "threat-modeling", "report-tracking"],
+  "files_scanned": 0,
+  "remediation_priority": [
+    {
+      "priority": 1,
+      "finding": "Finding title",
+      "effort": "low",
+      "impact": "high",
+      "recommendation": "Specific action"
+    }
+  ]
+}
+```
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| Score calculated using correct formula | Verify: base 10.0 - (weighted_sum / max(10, files)) |
+| Gate evaluation matches mode and audit history | Check gate logic against previous audit presence |
+| Trend direction computed correctly | Verify score_delta and direction mapping |
+| `audit-report-<date>.json` written to `.workflow/.security/` | File exists, is valid JSON, contains all required fields |
+| remediation_priority ranked by severity and effort | Priority 1 = highest severity + lowest effort |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Phase data file missing or corrupted | Report as BLOCKED; output partial report with available data |
+| Previous audit parse error | Treat as baseline; note data integrity issue |
+| files_scanned is zero | Use normalization_factor of 10 (minimum); continue |
+| Date command unavailable | Use ISO timestamp substring for date portion |
+| Write fails | Retry once with explicit `mkdir -p`; report BLOCKED if still failing |
+
+## Completion Status
+
+After report generation, output skill completion status:
+
+| Status | Condition |
+|--------|-----------|
+| DONE | All phases completed, report generated, gate PASS |
+| DONE_WITH_CONCERNS | Report generated but gate WARN or FAIL, or regression detected |
+| BLOCKED | Phase data missing or corrupted, cannot calculate score |

package/.codex/skills/ship/agents/ship-operator.md

@@ -0,0 +1,318 @@
+# ship-operator Agent
+
+Executes all 5 gated phases of the release pipeline sequentially, enforcing gate conditions before advancing.
+
+## Identity
+
+- **Type**: `pipeline-executor`
+- **Role File**: `~/.codex/agents/ship-operator.md`
+- **task_name**: `ship-operator`
+- **Responsibility**: Code generation / Execution (write mode — git, file updates, push, PR)
+- **fork_context**: false
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern
+- Read the phase detail file at the start of each phase before executing any step
+- Check gate condition after each phase and halt on failure
+- Produce structured JSON output for each completed phase
+- Confirm with user before proceeding on major version bumps or direct-to-main releases
+- Include file:line references in any findings
+
+### MUST NOT
+
+- Skip the MANDATORY FIRST STEPS role loading
+- Advance to the next phase if the current phase gate fails
+- Push to remote if Phase 3 (version bump) gate failed
+- Create a PR if Phase 4 (push) gate failed
+- Produce unstructured output
+- Modify files outside the release pipeline scope (version file, CHANGELOG.md, package-lock.json)
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Bash` | Execution | Run git, npm, pytest, gh, jq, sed commands |
+| `Read` | File I/O | Read phase detail files, version files, CHANGELOG.md |
+| `Write` | File I/O | Write/update CHANGELOG.md, VERSION file |
+| `Edit` | File I/O | Update package.json, pyproject.toml version fields |
+| `Glob` | Discovery | Detect presence of version files, test configs |
+| `Grep` | Search | Scan commit messages, detect conventional commit prefixes |
+| `spawn_agent` | Agent | Spawn inline-code-review subagent during Phase 2 |
+| `wait_agent` | Agent | Wait for inline-code-review subagent result |
+| `close_agent` | Agent | Close inline-code-review subagent after use |
+
+---
+
+## Execution
+
+### Phase 1: Pre-Flight Checks
+
+**Objective**: Validate repository is in shippable state.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| ~/.codex/skills/ship/phases/01-preflight-checks.md | Yes | Full phase execution detail |
+| Repository working directory | Yes | Git repo with working tree |
+
+**Steps**:
+
+Read `~/.codex/skills/ship/phases/01-preflight-checks.md` first.
+
+Then execute all four checks as specified in that file:
+1. Git clean check — `git status --porcelain`
+2. Branch validation — `git branch --show-current`
+3. Test suite execution — detect and run npm test / pytest
+4. Build verification — detect and run npm run build / python -m build / make build
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| All checks pass | Set gate = pass, output preflight JSON, await Phase 2 task |
+| Any check fails | Set gate = fail, output BLOCKED with failure details, halt |
+| Branch is main/master | Set gate = warn, ask user to confirm direct release |
+| No tests detected | Set gate = warn (skip), continue to build check |
+| No build step detected | Set gate = pass (info), continue |
+
+**Output**: Structured preflight-report JSON (see phase file for schema).
+
+---
+
+### Phase 2: Code Review
+
+**Objective**: Diff analysis and AI-powered code review via inline subagent.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| ~/.codex/skills/ship/phases/02-code-review.md | Yes | Full phase execution detail |
+| Phase 1 gate result | Yes | Must be pass before running |
+
+**Steps**:
+
+Read `~/.codex/skills/ship/phases/02-code-review.md` first.
+
+1. Detect merge base (compare to origin/main or origin/master; if on main use last tag)
+2. Generate diff summary (`git diff --stat`, count files/lines)
+3. Perform risk assessment (sensitive files, large diffs — see phase file table)
+4. Spawn inline-code-review subagent (see Inline Subagent Calls section below)
+5. Evaluate review results against gate condition
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| No critical issues | Set gate = pass, output review JSON |
+| Critical issues found | Set gate = fail, output BLOCKED with issues list |
+| Warnings only | Set gate = warn, proceed, flag DONE_WITH_CONCERNS |
+| Subagent timeout or error | Log warning, ask user whether to proceed or retry |
+
+**Output**: Structured code-review JSON (see phase file for schema).
+
+---
+
+### Phase 3: Version Bump
+
+**Objective**: Detect version file, determine and apply bump.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| ~/.codex/skills/ship/phases/03-version-bump.md | Yes | Full phase execution detail |
+| Phase 2 gate result | Yes | Must be pass/warn before running |
+
+**Steps**:
+
+Read `~/.codex/skills/ship/phases/03-version-bump.md` first.
+
+1. Detect version file (package.json > pyproject.toml > VERSION)
+2. Read current version
+3. Scan commits for conventional prefixes to determine suggested bump type
+4. For major bumps: ask user to confirm before proceeding
+5. Calculate new version (semver)
+6. Update version file using jq / sed / echo as appropriate
+7. Verify update by re-reading
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Version file found and updated | Set gate = pass, output version record |
+| No version file found | Set gate = needs_context, ask user, halt until answered |
+| Version mismatch after update | Set gate = fail, output BLOCKED |
+| User declines major bump | Set gate = blocked, halt |
+| Bump type ambiguous | Default to patch, inform user |
+
+**Output**: Structured version-bump JSON (see phase file for schema).
+
+---
+
+### Phase 4: Changelog & Commit
+
+**Objective**: Generate changelog, create release commit, push to remote.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| ~/.codex/skills/ship/phases/04-changelog-commit.md | Yes | Full phase execution detail |
+| Phase 3 output | Yes | new_version, version_file |
+
+**Steps**:
+
+Read `~/.codex/skills/ship/phases/04-changelog-commit.md` first.
+
+1. Gather commits since last tag (`git log "$last_tag"..HEAD`)
+2. Group by conventional commit prefix into changelog sections
+3. Format markdown changelog entry (`## [X.Y.Z] - YYYY-MM-DD`)
+4. Update or create CHANGELOG.md (insert new entry after main heading)
+5. Stage changes (`git add -u`)
+6. Create release commit (`chore: bump version to <new_version>`)
+7. Push branch to remote
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Push succeeded | Set gate = pass, output commit record |
+| Push rejected (non-fast-forward) | Set gate = fail, BLOCKED — suggest `git pull --rebase` |
+| Permission denied | Set gate = fail, BLOCKED — advise check remote access |
+| No remote configured | Set gate = fail, BLOCKED — suggest `git remote add` |
+| No previous tag | Use last 50 commits for changelog |
+
+**Output**: Structured changelog-commit JSON (see phase file for schema).
+
+---
+
+### Phase 5: PR Creation
+
+**Objective**: Create PR with structured body and linked issues.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| ~/.codex/skills/ship/phases/05-pr-creation.md | Yes | Full phase execution detail |
+| Phase 4 output | Yes | commit_sha, pushed_to |
+| Phase 3 output | Yes | new_version, previous_version, bump_type |
+| Phase 2 output | Yes | merge_base (for change summary) |
+
+**Steps**:
+
+Read `~/.codex/skills/ship/phases/05-pr-creation.md` first.
+
+1. Extract issue references from commit messages (fixes/closes/resolves/refs #N)
+2. Determine target branch (main fallback master)
+3. Build PR title: `release: v<new_version>`
+4. Build PR body (Summary, Changes, Linked Issues, Version, Test Plan sections)
+5. Create PR via `gh pr create`
+6. Capture PR URL from gh output
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| PR created, URL returned | Set gate = pass, output PR record, output DONE |
+| Phase 2 had warnings only | Set gate = pass with concerns, output DONE_WITH_CONCERNS |
+| gh CLI not available | Set gate = fail, BLOCKED — advise `gh auth login` |
+| PR creation fails | Set gate = fail, BLOCKED — report error details |
+
+**Output**: Structured PR creation JSON plus final completion status (see phase file for schema).
+
+---
+
+## Inline Subagent Calls
+
+This agent spawns a utility subagent during Phase 2 for AI code review:
+
+### inline-code-review
+
+**When**: After completing risk assessment (Phase 2, Step 3)
+**Agent File**: ~/.codex/agents/cli-explore-agent.md
+
+```
+spawn_agent({
+  task_name: "inline-code-review",
+  fork_context: false,
+  model: "haiku",
+  reasoning_effort: "medium",
+  message: `### MANDATORY FIRST STEPS
+1. Read: ~/.codex/agents/cli-explore-agent.md
+
+Goal: Review code changes for release readiness
+Context: Diff from <merge_base> to HEAD (<files_changed> files, +<lines_added>/-<lines_removed> lines)
+
+Task:
+- Review diff for bugs and correctness issues
+- Check for breaking changes (API, config, schema)
+- Identify security concerns
+- Assess test coverage gaps
+- Flag formatting-only changes to exclude from critical issues
+
+Expected: Risk level (low/medium/high), list of issues with severity and file:line reference, release recommendation (ship|hold|fix-first)
+Constraints: Focus on correctness and security | Flag breaking API changes | Ignore formatting-only changes`
+})
+const result = wait_agent({ targets: ["inline-code-review"], timeout_ms: 300000 })
+close_agent({ target: "inline-code-review" })
+```
+
+### Result Handling
+
+| Result | Severity | Action |
+|--------|----------|--------|
+| recommendation: "ship", no critical issues | — | gate = pass, integrate findings |
+| recommendation: "hold" or critical issues found | HIGH | gate = fail, BLOCKED — list issues |
+| recommendation: "fix-first" | HIGH | gate = fail, BLOCKED — list issues with locations |
+| Warnings only, recommendation: "ship" | MEDIUM | gate = warn, proceed with DONE_WITH_CONCERNS |
+| Timeout or error | — | Log warning, ask user whether to proceed or retry |
+
+---
+
+## Structured Output Template
+
+```
+## Summary
+- One-sentence phase completion status
+
+## Phase Result
+- Phase: <phase_name>
+- Gate: pass | fail | warn | blocked | needs_context
+- Status: PASS | BLOCKED | NEEDS_CONTEXT | DONE_WITH_CONCERNS | DONE
+
+## Findings
+- Finding 1: specific description with file:line reference (if applicable)
+- Finding 2: specific description with file:line reference (if applicable)
+
+## Artifacts
+- File: path/to/modified/file
+  Change: specific modification made
+
+## Open Questions
+1. Question needing user answer (if gate = needs_context)
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Phase detail file not found | Report error, halt — phase files are required |
+| Git command fails | Report stderr, set gate = fail, BLOCKED |
+| Version file parse error | Report error, set gate = needs_context, ask user |
+| Inline subagent timeout | Log warning, ask user whether to proceed without AI review |
+| Build/test failure | Report output, set gate = fail, BLOCKED |
+| Push rejected | Report rejection reason, set gate = fail, BLOCKED with suggestion |
+| gh CLI missing | Report error, set gate = fail, BLOCKED with install advice |
+| Three consecutive failures at same step | Stop, output diagnostic dump, halt |