slash-do 2.11.0 → 2.13.0

package/README.md

@@ -63,6 +63,7 @@ All commands live under the `do:` namespace:
 | `/do:review` | Deep code review against best practices |
 | `/do:better` | Full DevSecOps audit with 8-agent scan and remediation |
 | `/do:better-swift` | SwiftUI DevSecOps audit with multi-platform coverage |
+| `/do:scan` | Read-only safety audit of an unfamiliar directory — flags malware patterns, network calls, and vulnerable deps without executing code |
 | `/do:depfree` | Audit dependencies, remove unnecessary ones, write replacement code |
 | `/do:goals` | Generate GOALS.md from codebase analysis |
 | `/do:replan` | Review and clean up PLAN.md |

package/commands/do/depfree.md

@@ -67,6 +67,7 @@ Key behavioral changes when `HEAVY_MODE` is `true`:
 
 When compacting during this workflow, always preserve:
 - The `DEPENDENCY_MAP` (complete classification of all dependencies)
+- The `PRIOR_DECISIONS` map loaded from `./docs/DEPS.md`
 - All REMOVABLE findings with package names and usage details
 - The current phase number and what phases remain
 - All PR numbers and URLs created so far
@@ -111,6 +112,26 @@ Record as `BUILD_CMD` and `TEST_CMD`.
 - Record `DEFAULT_BRANCH` via `gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'` (or `glab` equivalent)
 - Record `IS_DIRTY` via `git status --porcelain`
 
+### 0e: Load Prior Decisions
+
+Read `{REPO_DIR}/docs/DEPS.md` if it exists. This file records decisions from prior `/do:depfree` runs and is used to skip re-evaluation of dependencies that have already been audited.
+
+Parse the file into `PRIOR_DECISIONS` — a map keyed by package name, with values:
+- `decision`: one of `KEPT_TIER1`, `KEPT_AUDITED`, `KEPT_TRANSITIVE`, `REMOVED`, `REVERTED`, `SKIPPED_INFEASIBLE`
+- `major_version`: the major version that was evaluated (e.g., `18` for react@18.x)
+- `mode`: the mode the decision was made under (`default`, `heavy`, or `both`)
+- `reason`: the rationale recorded
+- `decision_date`: ISO date the decision was made
+
+If the file does not exist, set `PRIOR_DECISIONS` to an empty map. The file will be created in Phase 4c only when remediation runs proceed past the scan-only phases (i.e., `--scan-only` was not passed).
+
+A prior decision is **valid for skipping re-evaluation** when ALL of these are true:
+1. The package is still in the manifest at the same major version
+2. The recorded mode matches the current run mode (a `default` decision does NOT skip a `heavy` run; `both` skips either; `heavy` skips a `default` run)
+3. The decision is not `REMOVED` or `REVERTED` (those packages should not be in the manifest; if they are, treat as new)
+
+Otherwise, the dependency is re-evaluated in Phase 1 normally.
+
 
 ## Phase 1: Dependency Inventory
 
@@ -138,7 +159,15 @@ Based on `PROJECT_TYPE`, extract the full dependency list:
 
 ### 1b: Classify Dependencies
 
-For each dependency, classify it into one of three tiers:
+For each dependency, first check `PRIOR_DECISIONS` (from Phase 0e). If a valid prior decision exists for the package + major version + mode, carry it forward:
+- `KEPT_TIER1` → classify as **Tier 1** (skip further audit)
+- `KEPT_AUDITED` → classify as **Tier 2** with recommendation **KEEP** (skip Phase 1c usage analysis)
+- `KEPT_TRANSITIVE` → classify as **Tier 2** with recommendation **KEEP (transitive)** (skip Phase 1c usage analysis and Phase 1d transitive check; the prior `Kept Via` chain is recorded)
+- `SKIPPED_INFEASIBLE` → classify as **Tier 2** with recommendation **KEEP** (skip Phase 1c usage analysis)
+
+Record carried-forward decisions in `DEPENDENCY_MAP` with a `from_prior: true` flag. Print one line per skipped dependency: `↻ {package}@{major} — carrying forward prior {decision} ({decision_date})`.
+
+For all other dependencies (no prior decision, major version bump, or mode escalation from default → heavy), classify it into one of three tiers:
 
 **Tier 1 — ACCEPTABLE (keep without question):**
 Large, widely-audited, foundational libraries. Examples by ecosystem:
@@ -217,7 +246,7 @@ Record the full classification as `DEPENDENCY_MAP`.
 
 ### 1c: Usage Analysis (Tier 2 & 3 only)
 
-For each Tier 2 and Tier 3 dependency, launch parallel Explore agents (using `AUDIT_MODEL`) to determine actual usage:
+Skip any dependency with `from_prior: true` (carried forward from Phase 1b). For all remaining Tier 2 and Tier 3 dependencies, launch parallel Explore agents (using `AUDIT_MODEL`) to determine actual usage:
 
 Each agent should:
 1. Search all source files for imports/requires of the package
@@ -455,7 +484,75 @@ After all replacement agents complete:
    - Correct error handling at system boundaries
 3. Fix any issues found, commit each fix separately
 
-### 4c: Verify No Phantom Dependencies
+### 4c: Update DEPS.md
+
+Write the consolidated decision record to `{WORKTREE_DIR}/docs/DEPS.md`. Create the `docs/` directory if it does not exist.
+
+Build the new file from:
+1. **All carried-forward entries** from `PRIOR_DECISIONS` whose packages are still in the manifest at the same major version (preserve `decision_date` and `mode`)
+2. **New decisions** from this run:
+   - Each Tier 1 package → `KEPT_TIER1`
+   - Each Tier 2 package with KEEP recommendation → `KEPT_AUDITED`
+   - Each Tier 2/3 package downgraded to KEEP (transitive) in Phase 1d → `KEPT_TRANSITIVE`
+   - Each successfully removed package → `REMOVED`
+   - Each reverted package (replacement failed in 4a) → `REVERTED`
+   - Each skipped package (replacement infeasible / >2x estimate / >300 lines in heavy) → `SKIPPED_INFEASIBLE`
+3. **Mode merging**: if a prior decision was `default` and this run is `heavy` (or vice versa) and both runs reached the same conclusion for the same package + major version, set `mode` to `both`. Otherwise the new run's mode overwrites.
+
+Use this layout:
+
+```markdown
+# Dependency Audit Decisions
+
+Auto-maintained by `/do:depfree`. Records prior audit decisions so repeat runs
+skip re-evaluation. Re-audit triggers: major version bump, heavy-mode run after
+default-mode decision, or manual deletion of an entry.
+
+Last updated: {YYYY-MM-DD}
+
+## Kept — Tier 1 (foundational)
+
+| Package | Major | Mode | Reviewed | Reason |
+|---------|-------|------|----------|--------|
+| ...     | ...   | ...  | ...      | ...    |
+
+## Kept — Tier 2 (audited)
+
+| Package | Major | Mode | Reviewed | Reason |
+|---------|-------|------|----------|--------|
+
+## Kept — Transitive
+
+| Package | Major | Mode | Reviewed | Kept Via |
+|---------|-------|------|----------|----------|
+
+## Removed
+
+| Package | Major | Mode | Removed | Replacement |
+|---------|-------|------|---------|-------------|
+
+## Reverted (replacement failed, kept in manifest)
+
+| Package | Major | Mode | Reviewed | Reason |
+|---------|-------|------|----------|--------|
+
+## Skipped (replacement infeasible)
+
+| Package | Major | Mode | Reviewed | Reason |
+|---------|-------|------|----------|--------|
+```
+
+Sort each section alphabetically by package name.
+
+Commit the change (only if the file actually changed):
+```bash
+git -C {WORKTREE_DIR} add -- docs/DEPS.md
+if ! git -C {WORKTREE_DIR} diff --cached --quiet -- docs/DEPS.md; then
+  git -C {WORKTREE_DIR} commit -m "docs: update DEPS.md with audit decisions"
+fi
+```
+
+### 4d: Verify No Phantom Dependencies
 
 Confirm no source file still references a removed package:
 ```bash
@@ -518,7 +615,9 @@ Estimated supply chain attack surface reduction: {N} packages ({transitive count
 - [ ] Build passes
 - [ ] All tests pass
 - [ ] No phantom references to removed packages
-- [ ] Lock file updated"
+- [ ] Lock file updated
+- [ ] \`docs/DEPS.md\` updated with audit decisions
+"
 
 gh pr create --head depfree/{DATE} --base {DEFAULT_BRANCH} \
   --title "$PR_TITLE" \
@@ -622,6 +721,7 @@ Transitive deps eliminated: ~{count} (estimated)
 
 - This command complements `/do:better` — run `depfree` for dependency hygiene, `better` for code quality
 - All remediation happens in an isolated worktree — the user's working directory is never modified
+- `docs/DEPS.md` is the persistent decision log. It is read at the start of every run (Phase 0e) to skip re-evaluation of unchanged dependencies, and rewritten at the end of Phase 4c with the merged set of prior + current decisions. Major version bumps and heavy-mode escalations bypass the cache. Manually delete an entry to force re-audit on the next run
 - **Default mode**: the threshold for "acceptable" libraries is deliberately generous — the goal is to remove obvious attack surface, not to rewrite everything
 - **Heavy mode**: the threshold narrows to foundational frameworks only — the goal is to own as much code as feasibly possible, eliminating supply chain risk from individual maintainers and small projects
 - Replacement code should be minimal and focused — don't over-engineer utilities that replace single-purpose packages

package/commands/do/help.md

@@ -26,6 +26,7 @@ List all available `/do:*` commands with their descriptions.
 | `/do:replan` | Review and clean up PLAN.md, extract docs from completed work |
 | `/do:review` | Deep code review of changed files against best practices |
 | `/do:rpr` | Resolve PR review feedback with parallel agents |
+| `/do:scan` | Read-only safety audit of an unfamiliar directory — flags malware patterns, network calls, and vulnerable deps without executing code |
 | `/do:update` | Update slashdo commands to the latest version |
 
 2. **Check for updates**: Run `npm view slash-do version` and compare to the installed version in `~/.claude/.slashdo-version`. If an update is available, mention it.

package/commands/do/review.md

@@ -32,21 +32,31 @@ Before dispatching agents, understand what this change set claims to do:
 
 ## Dispatch Review Agents
 
-Read the three agent instruction files, then spawn **all three in parallel** using the Agent tool with `model: "opus"`. Each agent reviews ALL changed files independently. Opus-class reasoning catches issues that require drawing on broad software engineering principles, not just pattern-matching against checklists.
+Read the five agent instruction files, then spawn **all five in parallel** using the Agent tool with `model: "opus"`. Each agent reviews ALL changed files independently. Opus-class reasoning catches issues that require drawing on broad software engineering principles, not just pattern-matching against checklists.
 
 <surface_scan_agent>
 
-### 1. Surface Scan Agent
+### 1. Surface Scan Agent (Runtime)
 
-Catches per-file bugs: runtime crashes, hygiene, domain-specific issues, quality, and convention violations.
+Catches per-file RUNTIME bugs: crashes, type/coercion errors, async/state, error handling, streaming, plus domain-specific runtime patterns (SQL, shell, wire protocols, accessibility).
 
 !`cat ~/.claude/lib/review-surface-scan.md`
 
 </surface_scan_agent>
 
+<surface_quality_agent>
+
+### 2. Surface Quality Agent
+
+Catches per-file QUALITY issues: intent-vs-implementation drift, AI-generated code patterns, dead config, missing tests, supply chain hygiene, style.
+
+!`cat ~/.claude/lib/review-surface-quality.md`
+
+</surface_quality_agent>
+
 <security_agent>
 
-### 2. Security Audit Agent
+### 3. Security Audit Agent
 
 Catches trust boundary violations, injection, SSRF, data exposure, and access control gaps.
 
@@ -54,15 +64,25 @@ Catches trust boundary violations, injection, SSRF, data exposure, and access co
 
 </security_agent>
 
-<cross_file_agent>
+<cross_file_tracing_agent>
 
-### 3. Cross-File Tracing Agent
+### 4. Cross-File Tracing Agent (State/Lifecycle)
 
-Catches contract mismatches, broken call chains, stale state propagation, lifecycle gaps, and architectural violations.
+Catches STATE/LIFECYCLE issues across files: stale state propagation, lifecycle gaps (mount/unmount, init/cleanup, started/completed), resource leaks, lock/flag exit paths, concurrent-mutation races.
 
 !`cat ~/.claude/lib/review-cross-file-tracing.md`
 
-</cross_file_agent>
+</cross_file_tracing_agent>
+
+<cross_file_contract_agent>
+
+### 5. Cross-File Contract Agent
+
+Catches CONTRACT issues across files: schema/shape agreements, validation parity, error classification, field-set enumerations, intent-vs-implementation claims spanning files, architectural-pattern adherence.
+
+!`cat ~/.claude/lib/review-cross-file-contract.md`
+
+</cross_file_contract_agent>
 
 ### How to dispatch
 
@@ -72,7 +92,7 @@ For each agent, construct its prompt by combining:
 3. The list of changed files from the diff stat
 4. Instruction: "Read each changed file in full (not just diff hunks). Apply your checklist. Return structured findings."
 
-Spawn all three agents simultaneously. Each returns its findings independently.
+Spawn all five agents simultaneously. Each returns its findings independently.
 
 ### Large PR handling
 
@@ -80,10 +100,10 @@ If the diff touches more than 20 files, tell each agent to batch files by direct
 
 ## Collect & Deduplicate
 
-After all three agents return:
+After all five agents return:
 
 1. **Merge** all findings into a single list, tagged by source agent
-2. **Deduplicate**: if two agents flagged the same `file:line` with overlapping descriptions, keep the most detailed version and note both agents found it
+2. **Deduplicate**: if two agents flagged the same `file:line` with overlapping descriptions, keep the most detailed version and note all agents that found it (overlap between Surface Scan and Surface Quality, or between Cross-File Tracing and Cross-File Contract, is expected for borderline issues — that's signal a finding is real, not noise)
 3. **PR coherence**: verify commits deliver what they claim — flag discrepancies as IMPROVEMENT findings
 4. **CLAUDE.md filter**: remove findings that conflict with explicit project conventions
 
@@ -116,13 +136,15 @@ Print a summary table of what was reviewed and found:
 
 | Agent | Files Checked | Issues Found | Fixed |
 |-------|--------------|-------------|-------|
-| Surface Scan | N | N | N |
+| Surface Scan (Runtime) | N | N | N |
+| Surface Quality | N | N | N |
 | Security Audit | N | N | N |
-| Cross-File Tracing | N | N | N |
+| Cross-File Tracing (State) | N | N | N |
+| Cross-File Contract | N | N | N |
 | **Total** | **N** | **N** | **N** |
 
 ### Issues Fixed
-- file:line — description of fix (agent: Surface/Security/Cross-File)
+- file:line — description of fix (agent: Surface-Scan / Surface-Quality / Security / Cross-File-Tracing / Cross-File-Contract)
 
 ### Accepted As-Is (with rationale)
 - file:line — description and why it's acceptable

package/commands/do/rpr.md

@@ -87,12 +87,12 @@ Verify the request was accepted by checking that `Copilot` appears in the respon
 
 ### Poll for review completion
 
-Poll using GraphQL to check for a new review with a `submittedAt` timestamp after the request:
+Poll using GraphQL to check for a new review with a `submittedAt` timestamp after the request. Use stdin JSON piping (per the GraphQL escaping guidance) to avoid shell-quoting fragility:
 ```bash
-gh api graphql -f query='{ repository(owner: "OWNER", name: "REPO") { pullRequest(number: PR_NUM) { reviews(last: 3) { nodes { state body author { login } submittedAt } } reviewThreads(first: 100) { nodes { id isResolved comments(first: 3) { nodes { body path line author { login } } } } } } } }'
+echo '{"query":"{ repository(owner: \"OWNER\", name: \"REPO\") { pullRequest(number: PR_NUM) { reviews(last: 3) { nodes { state body author { login } submittedAt } } reviewThreads(first: 100) { nodes { id isResolved comments(first: 3) { nodes { body path line author { login } } } } } } } }"}' | gh api graphql --input -
 ```
 
-**Dynamic poll timing**: Before your first poll, check how long the most recent Copilot review on this PR took by comparing consecutive Copilot review `submittedAt` timestamps (or PR creation time for the first review). Use that duration as your expected wait. If no prior review exists, default to 2 minutes. Use **progressive poll intervals**: 10s, 10s, 15s, 15s, then 30s thereafter — small diffs often complete in under a minute, so early frequent checks avoid wasting time. Set max wait to **2x the expected duration** (minimum 2 minutes, maximum 10 minutes). Copilot reviews typically complete in **2-5 minutes**; large diffs may take longer — do NOT give up early.
+**Dynamic poll timing**: Before your first poll, check how long the most recent Copilot review on this PR took by comparing consecutive Copilot review `submittedAt` timestamps (or PR creation time for the first review). Use that duration as your expected wait. If no prior review exists, default to **60 seconds**. Use **progressive poll intervals**: 5s, 5s, 10s, 10s, then 15s thereafter — Copilot reviews on small diffs typically land in **30–90 seconds**, so an early first check avoids burning a full minute on a review that's already sitting in the API. Set max wait to **3x the expected duration** (minimum 90 seconds, maximum 5 minutes); only large diffs (200+ changed lines) should ever approach the max. If the review hasn't arrived by then, treat it as stuck rather than slow.
 
 The review is complete when a new `copilot-pull-request-reviewer` review node appears. If no review appears after max wait: **Default mode**: auto-skip and continue. **Interactive mode (`--interactive`)**: ask the user whether to continue waiting, re-request, or skip.