maestro-flow 0.5.3 → 0.5.31

package/.claude/commands/security-audit.md

@@ -1,179 +1,230 @@
----
-name: security-audit
-description: OWASP Top 10 and STRIDE security auditing with supply chain analysis
-argument-hint: "[quick|standard|deep] [--scope <path>]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Systematic security audit covering OWASP Top 10, dependency supply chain, secrets detection,
-CI/CD pipeline review, and optional STRIDE threat modeling. Three tiers control depth vs speed.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/review.md
-</required_reading>
-
-<context>
-$ARGUMENTS — Parse tier and scope:
-- Tier: `quick` (default) | `standard` | `deep`
-- `--scope <path>`: Limit scan to directory (default: project root)
-
-**Tier coverage:**
-
-| Tier | OWASP | Dependencies | Secrets | CI/CD | STRIDE | Git History |
-|------|-------|-------------|---------|-------|--------|-------------|
-| quick | ✓ | ✓ | — | — | — | — |
-| standard | ✓ | ✓ | ✓ | ✓ | — | — |
-| deep | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-</context>
-
-<execution>
-
-**Phase 1: Reconnaissance**
-
-1. Detect tech stack from package.json / go.mod / requirements.txt / Cargo.toml
-2. Identify entry points: HTTP handlers, API routes, CLI parsers, WebSocket handlers
-3. List authentication/authorization modules
-4. Map data flow: user input → processing → storage → output
-
-**Phase 2: OWASP Top 10 Scan** (all tiers)
-
-For each category, scan relevant source files:
-
-| # | Category | What to check |
-|---|----------|--------------|
-| A01 | Broken Access Control | Missing auth middleware, direct object references, path traversal |
-| A02 | Cryptographic Failures | Weak algorithms, hardcoded keys, missing TLS, plaintext storage |
-| A03 | Injection | SQL concatenation, shell exec with user input, template injection |
-| A04 | Insecure Design | Missing rate limits, no CSRF tokens, predictable tokens |
-| A05 | Security Misconfiguration | Debug mode, default credentials, verbose errors, open CORS |
-| A06 | Vulnerable Components | Known CVEs in dependencies |
-| A07 | Auth Failures | Weak password rules, missing brute-force protection, session fixation |
-| A08 | Data Integrity | Deserialization of untrusted data, unsigned updates |
-| A09 | Logging Failures | Missing audit logs, logging sensitive data |
-| A10 | SSRF | Unvalidated URLs in server-side requests |
-
-Use `Grep` for pattern matching (e.g., `eval(`, `exec(`, `innerHTML`, `dangerouslySetInnerHTML`,
-`sql.*\+.*req\.`, `process\.env` without validation).
-
-**Phase 3: Dependency Audit** (all tiers)
-
-```bash
-# Node.js
-npm audit --json 2>/dev/null || true
-# Check lockfile integrity
-test -f package-lock.json && echo "lockfile present" || echo "WARNING: no lockfile"
-```
-
-Check for:
-- Known vulnerabilities (CVE references)
-- Lockfile presence and integrity
-- Typosquatting risk on critical dependencies (manually check suspicious names)
-
-**Phase 4: Secrets Detection** (standard + deep)
-
-```bash
-# Current codebase
-grep -rn --include="*.ts" --include="*.js" --include="*.json" --include="*.env*" \
-  -E "(password|secret|api.?key|token|credential).*=.*['\"][^'\"]{8,}" . || true
-```
-
-Check `.env.example` for leaked values. Check `.gitignore` for missing `.env` patterns.
-
-**Phase 5: CI/CD Audit** (standard + deep)
-
-Scan `.github/workflows/*.yml` for:
-- Overly permissive `permissions:` (write-all, contents: write)
-- Unpinned action versions (`uses: actions/checkout@main` vs `@v4.1.0`)
-- Secrets in logs (missing `mask` or `add-mask`)
-- Pull request trigger with `pull_request_target` (code injection risk)
-
-**Phase 6: STRIDE Threat Modeling** (deep only)
-
-For each critical module identified in Phase 1:
-
-| Threat | Question |
-|--------|----------|
-| **S**poofing | Can identity be faked? Is auth per-request? |
-| **T**ampering | Can data be modified in transit/storage? Integrity checks? |
-| **R**epudiation | Are actions logged with user identity? |
-| **I**nformation Disclosure | Can unauthorized data be accessed? |
-| **D**enial of Service | Resource limits? Rate limiting? |
-| **E**levation of Privilege | Can roles be escalated? Input validation on role fields? |
-
-**Phase 7: Git History Archaeology** (deep only)
-
-```bash
-# Search for previously committed secrets
-git log --all --diff-filter=D --name-only --pretty=format: -- "*.env" "*.key" "*.pem" 2>/dev/null | head -20
-git log -p --all -S "password" --since="1 year ago" -- "*.ts" "*.js" 2>/dev/null | head -50
-```
-
-**Phase 8: Report**
-
-Output severity matrix:
-
-```
-=== Security Audit ({tier}) ===
-
-CRITICAL ({count}):
-  - [A03] SQL injection in {file}:{line} — {description}
-    Fix: {remediation}
-
-HIGH ({count}):
-  ...
-
-MEDIUM ({count}):
-  ...
-
-LOW ({count}):
-  ...
-
-Summary: {total} findings ({critical} critical, {high} high, {medium} medium, {low} low)
-```
-
-Emit completion status:
-```
---- COMPLETION STATUS ---
-STATUS: DONE|DONE_WITH_CONCERNS
-CONCERNS: {count} critical findings require immediate action
-NEXT: /quality-review
---- END STATUS ---
-```
-
-**Register artifact on completion** (so retrospective/harvest can trace this audit):
-```
-Append to state.json.artifacts[]:
-{
-  id: nextArtifactId(artifacts, "review"),  // RVW-NNN (security-audit reuses review type)
-  type: "review",
-  subtype: "security-audit",
-  milestone: current_milestone || null,
-  phase: target_phase || null,
-  scope: target_phase ? "phase" : "standalone",
-  path: "scratch/{YYYYMMDD}-security-audit-{tier}-{slug}",
-  status: critical_count == 0 ? "completed" : "completed_with_concerns",
-  tier: tier,                              // quick|standard|deep
-  harvested: false,
-  created_at: start_time,
-  completed_at: now()
-}
-```
-Write findings report to the same `path` (severity matrix, file:line refs, remediation).
-</execution>
-
-<success_criteria>
-- [ ] Tech stack identified and entry points mapped
-- [ ] OWASP Top 10 categories all checked (tier-appropriate)
-- [ ] Dependency audit completed with CVE listing
-- [ ] Severity matrix produced with file:line references
-- [ ] Each finding includes remediation suggestion
-- [ ] Completion status block emitted
-</success_criteria>
+---
+name: security-audit
+description: OWASP Top 10 and STRIDE security auditing with supply chain analysis
+argument-hint: "[quick|standard|deep] [--scope <path>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Systematic security audit covering OWASP Top 10, dependency supply chain, secrets detection,
+CI/CD pipeline review, and optional STRIDE threat modeling. Three tiers control depth vs speed.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/review.md
+</required_reading>
+
+<context>
+$ARGUMENTS — Parse tier and scope:
+- Tier: `quick` (default) | `standard` | `deep`
+- `--scope <path>`: Limit scan to directory (default: project root)
+
+**Tier coverage:**
+
+| Tier | OWASP | Dependencies | Secrets | CI/CD | STRIDE | Git History |
+|------|-------|-------------|---------|-------|--------|-------------|
+| quick | ✓ | ✓ | — | — | — | — |
+| standard | ✓ | ✓ | ✓ | ✓ | — | — |
+| deep | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+</context>
+
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Recon → Scan**
+- REQUIRED: Tech stack detected and entry points identified.
+- REQUIRED: Auth/authz modules listed and data flow mapped.
+- BLOCKED if missing: cannot scan without entry points and data flow baseline.
+
+**GATE 2: Scan → Report** (tier-gated)
+- REQUIRED: OWASP Top 10 scan completed (all tiers).
+- REQUIRED: Dependency audit completed (all tiers).
+- REQUIRED: Secrets + CI/CD scan completed (standard/deep only).
+- REQUIRED: STRIDE + git history completed (deep only).
+- BLOCKED if tier-required scans incomplete: finish all tier-applicable phases before reporting.
+
+**GATE 3: Report → Completion**
+- REQUIRED: Severity matrix produced with file:line references and remediation.
+- REQUIRED: Artifact registered in state.json.
+- BLOCKED if missing: do not emit completion status without severity matrix.
+
+**Phase 1: Reconnaissance**
+
+1. Detect tech stack from package.json / go.mod / requirements.txt / Cargo.toml
+2. Identify entry points: HTTP handlers, API routes, CLI parsers, WebSocket handlers
+3. List authentication/authorization modules
+4. Map data flow: user input → processing → storage → output
+
+**Phase 2: OWASP Top 10 Scan** (all tiers)
+
+For each category, scan relevant source files:
+
+| # | Category | What to check |
+|---|----------|--------------|
+| A01 | Broken Access Control | Missing auth middleware, direct object references, path traversal |
+| A02 | Cryptographic Failures | Weak algorithms, hardcoded keys, missing TLS, plaintext storage |
+| A03 | Injection | SQL concatenation, shell exec with user input, template injection |
+| A04 | Insecure Design | Missing rate limits, no CSRF tokens, predictable tokens |
+| A05 | Security Misconfiguration | Debug mode, default credentials, verbose errors, open CORS |
+| A06 | Vulnerable Components | Known CVEs in dependencies |
+| A07 | Auth Failures | Weak password rules, missing brute-force protection, session fixation |
+| A08 | Data Integrity | Deserialization of untrusted data, unsigned updates |
+| A09 | Logging Failures | Missing audit logs, logging sensitive data |
+| A10 | SSRF | Unvalidated URLs in server-side requests |
+
+Use `Grep` for pattern matching (e.g., `eval(`, `exec(`, `innerHTML`, `dangerouslySetInnerHTML`,
+`sql.*\+.*req\.`, `process\.env` without validation).
+
+**Phase 3: Dependency Audit** (all tiers)
+
+```bash
+# Node.js
+npm audit --json 2>/dev/null || true
+# Check lockfile integrity
+test -f package-lock.json && echo "lockfile present" || echo "WARNING: no lockfile"
+```
+
+Check for:
+- Known vulnerabilities (CVE references)
+- Lockfile presence and integrity
+- Typosquatting risk on critical dependencies (manually check suspicious names)
+
+**Phase 4: Secrets Detection** (standard + deep)
+
+```bash
+# Current codebase
+grep -rn --include="*.ts" --include="*.js" --include="*.json" --include="*.env*" \
+  -E "(password|secret|api.?key|token|credential).*=.*['\"][^'\"]{8,}" . || true
+```
+
+Check `.env.example` for leaked values. Check `.gitignore` for missing `.env` patterns.
+
+**Phase 5: CI/CD Audit** (standard + deep)
+
+Scan `.github/workflows/*.yml` for:
+- Overly permissive `permissions:` (write-all, contents: write)
+- Unpinned action versions (`uses: actions/checkout@main` vs `@v4.1.0`)
+- Secrets in logs (missing `mask` or `add-mask`)
+- Pull request trigger with `pull_request_target` (code injection risk)
+
+**Phase 6: STRIDE Threat Modeling** (deep only)
+
+For each critical module identified in Phase 1:
+
+| Threat | Question |
+|--------|----------|
+| **S**poofing | Can identity be faked? Is auth per-request? |
+| **T**ampering | Can data be modified in transit/storage? Integrity checks? |
+| **R**epudiation | Are actions logged with user identity? |
+| **I**nformation Disclosure | Can unauthorized data be accessed? |
+| **D**enial of Service | Resource limits? Rate limiting? |
+| **E**levation of Privilege | Can roles be escalated? Input validation on role fields? |
+
+**Phase 7: Git History Archaeology** (deep only)
+
+```bash
+# Search for previously committed secrets
+git log --all --diff-filter=D --name-only --pretty=format: -- "*.env" "*.key" "*.pem" 2>/dev/null | head -20
+git log -p --all -S "password" --since="1 year ago" -- "*.ts" "*.js" 2>/dev/null | head -50
+```
+
+**Phase 8: Report**
+
+Output severity matrix:
+
+```
+=== Security Audit ({tier}) ===
+
+CRITICAL ({count}):
+  - [A03] SQL injection in {file}:{line} — {description}
+    Fix: {remediation}
+
+HIGH ({count}):
+  ...
+
+MEDIUM ({count}):
+  ...
+
+LOW ({count}):
+  ...
+
+Summary: {total} findings ({critical} critical, {high} high, {medium} medium, {low} low)
+```
+
+**Register artifact on completion:**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "review"),  // RVW-NNN (security-audit reuses review type)
+  type: "review",
+  subtype: "security-audit",
+  milestone: current_milestone || null,
+  phase: target_phase || null,
+  scope: target_phase ? "phase" : "standalone",
+  path: "scratch/{YYYYMMDD}-security-audit-{tier}-{slug}",
+  status: critical_count == 0 ? "completed" : "completed_with_concerns",
+  tier: tier,                              // quick|standard|deep
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+Write findings report to the same `path` (severity matrix, file:line refs, remediation).
+</execution>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS
+CONCERNS: {count} critical findings require immediate action
+--- END STATUS ---
+```
+
+Status mapping:
+- **DONE** — No critical/high findings
+- **DONE_WITH_CONCERNS** — Critical/high findings documented with remediation
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| No critical findings | `/quality-review {phase}` |
+| Critical findings need fix | `/maestro-plan {phase} --gaps` |
+| Need deeper analysis | `/security-audit deep --scope {path}` |
+| Want dependency remediation | Fix vulnerabilities, then re-run `/security-audit` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No source files found in scope | Verify --scope path exists |
+| E002 | error | Tech stack not detected | Manually specify entry points |
+| W001 | warning | npm audit / dependency tool unavailable | Skip dependency phase, note limitation |
+| W002 | warning | Git history scan failed | Skip Phase 7, note limitation |
+| W003 | warning | Partial scan (some files inaccessible) | Report coverage gap in findings |
+</error_codes>
+
+<success_criteria>
+- [ ] Tech stack identified and entry points mapped
+- [ ] OWASP Top 10 categories all checked (tier-appropriate)
+- [ ] Dependency audit completed with CVE listing
+- [ ] Severity matrix produced with file:line references
+- [ ] Each finding includes remediation suggestion
+- [ ] Completion status block emitted
+</success_criteria>

package/.claude/commands/spec-add.md

@@ -1,70 +1,77 @@
----
-name: spec-add
-description: Add spec entry by category with role tagging
-argument-hint: "[--scope project|global|team|personal] <category> <content>"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
----
-<purpose>
-Add a knowledge entry to the specs system using `<spec-entry>` closed-tag format.
-Each category maps 1:1 to a single target file — no dual-write.
-Supports 4 scopes: project (default), global, team, personal.
-Entries use `category` attribute to declare which category they belong to.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-add.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
-
-**Options:**
-- `--description <desc>` — One-line description for search results (falls back to content[:240])
-- `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
-- `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
-
-Scope-to-directory mapping, category-to-file mapping, and entry format defined in workflow specs-add.md.
-
-**Examples:**
-```bash
-# English content → English keywords
-/spec-add coding "Named exports" "Always use named exports" --keywords "exports,naming"
-
-# With description for search results
-/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --keywords "oauth,pkce" --description "OAuth 2.0 PKCE 认证流程规范"
-
-# Chinese content → Chinese keywords
-/spec-add coding "命名导出规范" "始终使用命名导出" --keywords "导出,命名,模块"
-
-# Ref mode
-/spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.md
-```
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-add.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | Category and content are both required | parse_input |
-| E002 | fatal | Specs directory not initialized -- run `maestro spec init --scope <scope>` | validate_entry |
-| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, tools, ui | parse_input |
-| E004 | fatal | Invalid scope -- must be one of: project, global, team, personal | parse_input |
-| E005 | fatal | Personal scope requires uid -- use `--uid` or run `maestro collab join` first | parse_input |
-</error_codes>
-
-<success_criteria>
-- [ ] Scope and category parsed and validated
-- [ ] Keywords auto-extracted from content (3-5 relevant terms)
-- [ ] Entry written in `<spec-entry>` closed-tag format
-- [ ] Entry appended to correct target file for scope
-- [ ] Confirmation report displayed with scope, path, keywords
-- [ ] Next step: `maestro spec load --scope <scope> --keyword {keyword}` to verify
-</success_criteria>
+---
+name: spec-add
+description: Add spec entry by category with role tagging
+argument-hint: "[--scope project|global|team|personal] <category> <content>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Add `<spec-entry>` to specs by category. 4 scopes: project (default), global, team, personal.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-add.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
+
+**Options:**
+- `--description <desc>` — One-line description for search results (falls back to content[:240])
+- `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
+- `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
+
+Scope-to-directory mapping, category-to-file mapping, and entry format defined in workflow specs-add.md.
+
+**Examples:**
+```bash
+# English content → English keywords
+/spec-add coding "Named exports" "Always use named exports" --keywords "exports,naming"
+
+# With description for search results
+/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --keywords "oauth,pkce" --description "OAuth 2.0 PKCE 认证流程规范"
+
+# Chinese content → Chinese keywords
+/spec-add coding "命名导出规范" "始终使用命名导出" --keywords "导出,命名,模块"
+
+# Ref mode
+/spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.md
+```
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-add.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Category and content are both required | parse_input |
+| E002 | fatal | Specs directory not initialized -- run `maestro spec init --scope <scope>` | validate_entry |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, tools, ui | parse_input |
+| E004 | fatal | Invalid scope -- must be one of: project, global, team, personal | parse_input |
+| E005 | fatal | Personal scope requires uid -- use `--uid` or run `maestro collab join` first | parse_input |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope and category parsed and validated
+- [ ] Keywords auto-extracted from content (3-5 relevant terms)
+- [ ] Entry written in `<spec-entry>` closed-tag format
+- [ ] Entry appended to correct target file for scope
+- [ ] Confirmation report displayed with scope, path, keywords
+- [ ] Next step routed
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Verify entry added | `maestro spec load --scope <scope> --keyword {keyword}` |
+| Add more entries | `/spec-add <category>` |
+| View all specs | `/spec-load --category <category>` |
+</completion>