slash-do 2.10.0 → 2.12.0

package/README.md

@@ -24,7 +24,7 @@
 <p align="center">
   <img src="https://img.shields.io/npm/v/slash-do?style=flat-square&color=blue" alt="npm version" />
   <img src="https://img.shields.io/badge/environments-4-green?style=flat-square" alt="environments" />
-  <img src="https://img.shields.io/badge/commands-14-orange?style=flat-square" alt="commands" />
+  <img src="https://img.shields.io/badge/commands-15-orange?style=flat-square" alt="commands" />
   <img src="https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square" alt="license" />
 </p>
 
@@ -56,12 +56,14 @@ All commands live under the `do:` namespace:
 |:---|:---|
 | `/do:push` | Commit and push all work with changelog |
 | `/do:pr` | Open a PR with self-review and Copilot review loop |
+| `/do:pr-better` | Run a full do:better audit on the current branch, commit fixes directly, then open a single PR |
 | `/do:fpr` | Fork PR -- push to fork, PR against upstream |
 | `/do:rpr` | Resolve PR review feedback with parallel agents |
 | `/do:release` | Create a release PR with version bump and changelog |
 | `/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

@@ -20,11 +20,13 @@ List all available `/do:*` commands with their descriptions.
 | `/do:help` | List all available slashdo commands |
 | `/do:omd` | Audit and optimize markdown files (CLAUDE.md, README.md, etc.) against best practices |
 | `/do:pr` | Commit, push, and open a PR against the repo's default branch |
+| `/do:pr-better` | Run a full do:better audit on the current branch, commit fixes directly, then open a single PR |
 | `/do:push` | Commit and push all work with changelog |
 | `/do:release` | Create a release PR using the project's documented release workflow |
 | `/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/pr-better.md

@@ -0,0 +1,94 @@
+---
+description: Run a full do:better audit/remediation on the current branch, commit fixes directly to it, then open a single PR with do:pr
+argument-hint: "[--interactive] [path filter or focus areas]"
+---
+
+# PR-Better — Better Audit + Single PR
+
+Run the full `do:better` DevSecOps audit and remediation, but **commit all fixes directly to the current branch** instead of creating per-category PRs. Then hand off to `do:pr` so the entire result ships as one cohesive PR (with self-review and the Copilot review loop).
+
+This is the right command when:
+- You want the full `do:better` quality bar on a feature branch you're about to ship
+- You want a single PR (not 8 per-category PRs) so reviewers see one cohesive change
+- You're already on a feature branch and want all audit fixes folded into the same PR as your feature work
+
+## Argument Forwarding
+
+Pass `$ARGUMENTS` through to `do:better` verbatim, with these constraints applied automatically:
+- **`--scan-only` is incompatible** — if the user passes it, refuse and explain that pr-better must remediate
+- **`--no-merge` is incompatible** — pr-better always produces a PR, but as one combined PR via `do:pr`
+- All other flags (`--interactive`, path filter, focus areas) pass through unchanged
+
+## Pre-flight
+
+1. Run `git branch --show-current` and `gh repo view --json defaultBranchRef -q '.defaultBranchRef.name'`
+2. If the current branch is the default branch, halt and tell the user: pr-better needs a feature branch — either create one first or run `/do:better` directly to produce per-category PRs from default
+3. Run `git status --porcelain` — if dirty, the do:better Phase 3a stash will handle it, but warn the user that uncommitted changes will be stashed and restored after the audit
+
+## Phase A: Run do:better (constrained to "Commit directly")
+
+Execute the full `do:better` workflow defined in `~/.claude/commands/do/better.md` with these mandatory deviations:
+
+### Phase 0 → 4a: unchanged
+Run discovery, audit (all 8 agents), plan generation, worktree setup, foundation utilities, parallel remediation, build/test verification, and internal code review exactly as specified in `do:better`.
+
+### Phase 4b: Force the "Commit directly" path
+
+When you reach Phase 4b's decision point, **do not present the AskUserQuestion** and **do not proceed to per-category PR creation**. Instead, always take the "Commit directly" path:
+
+- Ensure all worktree changes are committed in `better/{DATE}`
+- Return to `{REPO_DIR}`, check out `{CURRENT_BRANCH}`, and merge `better/{DATE}` into it:
+  ```bash
+  cd {REPO_DIR}
+  git checkout {CURRENT_BRANCH}
+  if git merge better/{DATE}; then
+    git worktree remove {WORKTREE_DIR}
+    git branch -D better/{DATE}
+  else
+    echo "Merge conflict — resolve in {REPO_DIR}, then run:"
+    echo "  git worktree remove {WORKTREE_DIR}"
+    echo "  git branch -D better/{DATE}"
+    # halt and surface the conflict to the user
+  fi
+  ```
+- If a merge conflict surfaces, stop here and ask the user to resolve before continuing to Phase B
+- Restore the stash if Phase 3a stashed changes (`git stash pop`)
+
+### Phase 4c: Test Enhancement
+
+Run Phase 4c (test enhancement) **before** the merge-back if the worktree is still active, so the new/fixed tests ship in the same merge. The Phase 4c.3 `FILE_OWNER_MAP` update is unnecessary in pr-better (we're not building per-category branches), so skip that step.
+
+### Phases 5, 6, 7: SKIP entirely
+
+Do not create category branches. Do not bump the version (the user's PR is responsible for any version bump via the project's normal release flow). Do not run the Copilot review loop here — `do:pr` will run it once on the combined PR. Do not delete branches you didn't create.
+
+The only Phase 7-equivalent housekeeping that applies:
+- Update PLAN.md to mark completed findings as `[x]` and note any skipped findings with reasons. Stage these changes so the next phase commits them as part of the PR.
+- Print the final summary table from Phase 7 (with PR fields blank — they'll be filled by Phase B).
+
+## Phase B: Run do:pr
+
+After Phase A leaves all fixes committed on `{CURRENT_BRANCH}`, hand off to the workflow defined in `~/.claude/commands/do/pr.md`:
+
+1. **Detect branches** — already done in pre-flight, reuse those values
+2. **Commit and push** — commit any remaining staged changes (e.g., the PLAN.md update), then `git pull --rebase --autostash && git push -u origin {current_branch}`
+3. **Local Code Review (REQUIRED GATE)** — run the full review gate from `do:pr`. The do:better Phase 4b internal review covered the worktree diff against the default branch, but the do:pr review gate also covers any prior commits on the feature branch that predate this run. Do not skip it.
+4. **Open the PR** — create a single PR with a description that summarizes both:
+   - The original feature work on the branch (from prior commits)
+   - The do:better audit findings now folded in (categories, counts, severity)
+5. **Copilot review loop** — runs once on the combined PR via the standard `do:pr` flow
+
+## Final Report
+
+Print:
+- The do:better summary table (categories, findings fixed/skipped) — with the PR column populated by the single PR URL
+- Test enhancement stats (vacuous fixed, weak strengthened, new cases, new files)
+- The PR URL
+- Final review status (clean / comments addressed / left open)
+
+## Notes
+
+- This is **not** equivalent to running `/do:better --no-merge` then `/do:pr`. `--no-merge` still creates per-category branches and PRs (it just skips the Copilot/merge step). pr-better never creates per-category branches at all.
+- Conflict-avoidance machinery from do:better Phase 5 (FILE_OWNER_MAP, backward-compatible re-exports across PRs) is unnecessary here — everything lands on one branch in one merge.
+- The user's existing feature commits remain intact; do:better remediation is added as additional commits on top.
+- If do:better finds zero actionable CRITICAL/HIGH/MEDIUM findings, skip Phase A's Phase 3-4 entirely and run only Phase B (`do:pr`) — the audit served as a quality gate even when nothing needed fixing.

package/commands/do/review.md

@@ -22,7 +22,13 @@ CLAUDE.md is already loaded into your context. Use its rules (code style, error
 Before dispatching agents, understand what this change set claims to do:
 
 1. Read commit messages (`git log {base}...HEAD --oneline`)
-2. Note the claims — verify after agents return whether the code actually delivers them.
+2. Read PLAN.md, .changelog/NEXT.md (or equivalent), and the PR description for capability claims, test counts, and "deep-links to X" / "feature Y now works" assertions
+3. Note the claims — verify after agents return whether the code actually delivers them. Concrete drift to flag:
+   - Test counts in PLAN/changelog vs `find . -name '*.test.*' -exec grep -c '^\(it\|test\)(' {} +` (or project equivalent)
+   - "Deep-links to record X" claims vs whether the destination route handler actually consumes the encoded parameter
+   - "Auto-prune after N days" / "scans only the page returned" claims vs the listing implementation
+   - Comments in code claiming behavior the surrounding code doesn't perform
+   - Field names quoted in docs (request body shape, event payload shape) vs what the code actually reads/emits
 
 ## Dispatch Review Agents
 

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 5 minutes. Use **progressive poll intervals**: 15s, 15s, 30s, 30s, then 60s 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 5 minutes, maximum 20 minutes). Copilot reviews can take **10-15 minutes** for large diffs — 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.