@ericrisco/rsc 3.7.0 → 3.7.2

package/README.md

@@ -8,7 +8,7 @@
 
 [![npm](https://img.shields.io/npm/v/@ericrisco/rsc?color=63d68a&labelColor=12161c&label=npm)](https://www.npmjs.com/package/@ericrisco/rsc)
 [![downloads](https://img.shields.io/npm/dm/@ericrisco/rsc?color=63d68a&labelColor=12161c&label=downloads)](https://www.npmjs.com/package/@ericrisco/rsc)
-[![skills](https://img.shields.io/badge/skills-273-63d68a?labelColor=12161c)](#the-catalog)
+[![skills](https://img.shields.io/badge/skills-274-63d68a?labelColor=12161c)](#the-catalog)
 [![license](https://img.shields.io/badge/license-MIT-63d68a?labelColor=12161c)](LICENSE)
 [![stars](https://img.shields.io/github/stars/ericrisco/rsc-harness?color=63d68a&labelColor=12161c)](https://github.com/ericrisco/rsc-harness/stargazers)
 
@@ -71,7 +71,7 @@ The decisions your agent needs should have a place to live outside the chat.
 | --- | --- |
 | **Knowledge** | A local `02-DOCS/` wiki for project context, decisions and evidence. |
 | **Tools** | A `01-TOOLS/` convention for documenting real connections and their checks. |
-| **Skills** | A selection from 273 available skills, loaded progressively when relevant. |
+| **Skills** | A selection from 274 available skills, loaded progressively when relevant. |
 | **Controls** | Working rules and provider-specific hooks, with explicit support limits. |
 
 The mechanism is practical: keep the decision, make it discoverable, and have the next task consult it.
@@ -501,7 +501,7 @@ price, customer testimonial, deadline or guarantee is needed to explain a useful
 
 ## The catalog
 
-273 skills, grouped by what you are trying to do. Click any skill to read its `SKILL.md`. It fires on
+274 skills, grouped by what you are trying to do. Click any skill to read its `SKILL.md`. It fires on
 its own when a task matches.
 
 ### 🧭 Core & control plane
@@ -513,7 +513,7 @@ its own when a task matches.
 Two lanes for change: `ftd` for ordinary work, and the ten-phase chain when durable artifacts would
 settle a real ambiguity. `idea-refinement` runs inside `specify`; `decision-challenge` is on demand.
 
-[ftd](skills/ftd/) · [sdd](skills/sdd/) · [constitution](skills/constitution/) · [idea-refinement](skills/idea-refinement/) · [specify](skills/specify/) · [clarify](skills/clarify/) · [plan](skills/plan/) · [tasks](skills/tasks/) · [analyze](skills/analyze/) · [decision-challenge](skills/decision-challenge/) · [implement](skills/implement/) · [source-grounded-development](skills/source-grounded-development/) · [verify](skills/verify/) · [review](skills/review/) · [simplify-code](skills/simplify-code/) · [ship](skills/ship/) · [debug](skills/debug/) · [worktrees](skills/worktrees/) · [parallel](skills/parallel/)
+[ftd](skills/ftd/) · [sdd](skills/sdd/) · [constitution](skills/constitution/) · [idea-refinement](skills/idea-refinement/) · [specify](skills/specify/) · [clarify](skills/clarify/) · [plan](skills/plan/) · [tasks](skills/tasks/) · [analyze](skills/analyze/) · [decision-challenge](skills/decision-challenge/) · [implement](skills/implement/) · [source-grounded-development](skills/source-grounded-development/) · [verify](skills/verify/) · [review](skills/review/) · [simplify-code](skills/simplify-code/) · [ship](skills/ship/) · [debug](skills/debug/) · [worktrees](skills/worktrees/) · [parallel](skills/parallel/) · [tidy](skills/tidy/)
 
 ### 💼 Run a business
 

package/manifest.json

@@ -1,7 +1,7 @@
 {
-  "version": "3.7.0",
+  "version": "3.7.2",
   "counts": {
-    "skills": 273,
+    "skills": 274,
     "agents": 34,
     "commands": 53,
     "fixedCommands": 20
@@ -5056,6 +5056,29 @@
       ],
       "profiles": []
     },
+    {
+      "id": "tidy",
+      "description": "Use when every repository in the workspace must end synced and clean: each one on its default branch, everything pushed, everything pulled, no leftover branches or worktrees. Covers the root repo and every nested repo (child projects). Fires on 'limpia el harness', 'actualiza todo', 'sincroniza todo', 'déjalo todo en main', 'sube y baja todo', 'tidy up the repos', 'sync everything'. NOT upgrading the rsc version (that is `npx @ericrisco/rsc upgrade`), NOT opening isolation for new work (that is `worktrees`), NOT landing one finished branch (that is `ship`).",
+      "tags": [
+        "git",
+        "sync",
+        "cleanup",
+        "branches",
+        "worktrees",
+        "limpieza",
+        "sincronizar",
+        "main"
+      ],
+      "recommends": [
+        "worktrees",
+        "ship"
+      ],
+      "profiles": [
+        "minimal",
+        "core",
+        "full"
+      ]
+    },
     {
       "id": "tiktok-api",
       "description": "Use when connecting a real TikTok account to code via the Content Posting, Display and Business Account APIs — OAuth, chunked video publish with status polling, and pulling views, watch time and impression sources, then logging that performance into the wiki as a dated feedback record. Covers short-lived tokens breaking a cron, unverified pull-from-URL ownership, and rate limits. NOT what to post or how to package it (that is `shortform-strategy` and `shortform-packaging`).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "3.7.0",
+  "version": "3.7.2",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {

package/scripts/lib/default-skill-floor.js

@@ -22,7 +22,11 @@
 // `ux` joined in 3.4.0: `design` decides how a screen looks, `ux` decides whether people can use it —
 // the whole flow, every state, the browser walk. It replaced `ui-engineering`, which was core-only.
 // Only its description is paid for on other turns; the upstream references load on demand.
-export const DEFAULT_SKILL_FLOOR = Object.freeze(['orient', 'suggest', 'unslop', 'ftd', 'connect-tool', 'design', 'ux']);
+//
+// `tidy` joined in 3.8.0: "limpia el harness" / "actualiza todo" — every repo on its default branch,
+// pushed, pulled, no landed branch or worktree left. Leftovers pile up in every workspace, not only in
+// the ones that picked a profile with git skills, and the person asks for it in their own words.
+export const DEFAULT_SKILL_FLOOR = Object.freeze(['orient', 'suggest', 'unslop', 'ftd', 'connect-tool', 'design', 'ux', 'tidy']);
 
 export function withDefaultSkillFloor(skillIds = []) {
   return [...new Set([...DEFAULT_SKILL_FLOOR, ...skillIds])];

package/scripts/lib/domains.js

@@ -5,7 +5,7 @@
 
 export const DOMAINS = [
   { title: 'Core & control plane', ids: ['init', 'harness', 'orient', 'suggest', 'unslop', 'author-skill', 'sdd-init'] },
-  { title: 'Spec-Driven Development', ids: ['ftd', 'sdd', 'constitution', 'idea-refinement', 'specify', 'clarify', 'plan', 'tasks', 'analyze', 'decision-challenge', 'implement', 'source-grounded-development', 'verify', 'review', 'simplify-code', 'ship', 'debug', 'worktrees', 'parallel'] },
+  { title: 'Spec-Driven Development', ids: ['ftd', 'sdd', 'constitution', 'idea-refinement', 'specify', 'clarify', 'plan', 'tasks', 'analyze', 'decision-challenge', 'implement', 'source-grounded-development', 'verify', 'review', 'simplify-code', 'ship', 'debug', 'worktrees', 'parallel', 'tidy'] },
   { title: 'Run a business', ids: ['finance-ops', 'invoicing', 'bookkeeping', 'pricing', 'sales-pipeline', 'lead-gen', 'cold-outreach', 'proposals', 'contracts', 'customer-support', 'client-onboarding', 'retention', 'hiring', 'people-ops', 'inventory', 'logistics-ops', 'procurement', 'meeting-notes', 'sop-builder', 'project-ops'] },
   { title: 'Raise & model money', ids: ['pitch-deck', 'investor-materials', 'financial-model', 'fundraising', 'unit-economics', 'grants'] },
   { title: 'Legal, privacy & compliance', ids: ['gdpr-privacy', 'terms-conditions', 'compliance', 'data-policy', 'ip-trademark'] },

package/scripts/lib/onboarding.js

@@ -18,11 +18,13 @@ export const ONBOARDING_VALUES = Object.freeze({
 });
 
 const ignored = new Set([
-  '.git', '.rsc', 'node_modules', '.venv', '.next', 'dist', 'build', 'coverage', '__pycache__', '.dart_tool',
+  // `vendor` is Composer's (and Go's/Bundler's) `node_modules`: third-party code, not the project. A
+  // Laravel app was read as Python because one vendored package shipped a `docs/requirements.txt` (#325).
+  '.git', '.rsc', 'node_modules', 'vendor', '.venv', '.next', 'dist', 'build', 'coverage', '__pycache__', '.dart_tool',
   '.claude', '.codex', '.cursor', '.opencode', '.amp', '.jules', '.zed', '.gemini', '.antigravity',
   '.windsurf', '.clinerules', '.roo', '.continue', '.junie', '.kiro', '.aider',
 ]);
-const manifests = new Set(['package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml', 'pubspec.yaml', 'requirements.txt']);
+const manifests = new Set(['package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml', 'pubspec.yaml', 'requirements.txt', 'composer.json']);
 const sourceExt = new Set(['.js', '.jsx', '.ts', '.tsx', '.py', '.go', '.rs', '.dart', '.java', '.kt', '.swift', '.php', '.rb']);
 
 const clean = (value) => String(value ?? '').trim();
@@ -152,6 +154,14 @@ export function scanProject(root = process.cwd()) {
         } catch { stacks.add('node'); }
       }
       if (entry.name === 'pyproject.toml' || entry.name === 'requirements.txt') stacks.add('python');
+      if (entry.name === 'composer.json') {
+        stacks.add('php');
+        try {
+          const composer = JSON.parse(readFileSync(path, 'utf8'));
+          const deps = { ...(composer.require || {}), ...(composer['require-dev'] || {}) };
+          if (deps['laravel/framework']) stacks.add('laravel');
+        } catch { /* an unreadable composer.json is still PHP */ }
+      }
       if (entry.name === 'go.mod') stacks.add('go');
       if (entry.name === 'Cargo.toml') stacks.add('rust');
       if (entry.name === 'pubspec.yaml') stacks.add('flutter');

package/skills/tidy/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: tidy
+description: "Use when every repository in the workspace must end synced and clean: each one on its default branch, everything pushed, everything pulled, no leftover branches or worktrees. Covers the root repo and every nested repo (child projects). Fires on 'limpia el harness', 'actualiza todo', 'sincroniza todo', 'déjalo todo en main', 'sube y baja todo', 'tidy up the repos', 'sync everything'. NOT upgrading the rsc version (that is `npx @ericrisco/rsc upgrade`), NOT opening isolation for new work (that is `worktrees`), NOT landing one finished branch (that is `ship`)."
+tags: [git, sync, cleanup, branches, worktrees, limpieza, sincronizar, main]
+recommends: [worktrees, ship]
+profiles: [minimal, core, full]
+origin: risco
+---
+
+# tidy — every repo on main, pushed, pulled, nothing left over
+
+One request, every repository in the workspace. When it ends, each repo shows the same picture:
+
+- the main checkout is on the **default branch**, up to date with the remote;
+- **nothing local is missing from the remote** — no unpushed commit, on any branch;
+- **no worktree and no branch whose work has already landed**, locally or on the remote.
+
+The job is cleanup, and cleanup is where work gets lost. So the rule under every step: **delete only
+what is proven to be in the default branch already.** Anything else is pushed, kept and reported —
+never thrown away to make the picture look clean.
+
+## 1. Find the repositories
+
+The workspace root, plus every nested git repository below it (child projects keep their own git):
+
+```bash
+git rev-parse --show-toplevel                          # the root repo, if any
+find . -name .git -maxdepth 4 -not -path '*/node_modules/*' -not -path '*/.worktrees/*'
+```
+
+A `.git` that is a *file* is a linked worktree or a submodule, not a repo of its own: skip it here,
+it is handled from its parent in step 4. Name the list in one line before touching anything.
+
+**Never change the working directory into a child repo.** Use `git -C <repo>` and absolute paths.
+Session hooks take the cwd as the project, and a `cd` plants state inside the child.
+
+## 2. Read everything before changing anything
+
+Per repo, one pass, no writes except the fetch:
+
+```bash
+git -C <repo> fetch --all --prune --quiet
+git -C <repo> symbolic-ref --short refs/remotes/origin/HEAD     # the default branch (origin/main)
+git -C <repo> status --short --branch                           # current branch, ahead/behind, dirty
+git -C <repo> for-each-ref --format='%(refname:short) %(upstream:short) %(upstream:track)' refs/heads
+git -C <repo> worktree list --porcelain
+git -C <repo> stash list
+gh pr list --state open --json number,headRefName 2>/dev/null   # open PRs, when gh is there
+```
+
+No remote at all → the repo cannot be "pushed"; report it and only tidy what is local.
+
+## 3. Classify every item
+
+Each branch, worktree and remote branch lands in exactly one row. Decide by the commands, not by
+reading names.
+
+| Item | Proof | Action |
+| --- | --- | --- |
+| Worktree whose work landed | `npx @ericrisco/rsc worktrees` calls it safe | `npx @ericrisco/rsc worktrees reap` |
+| Worktree whose directory is gone | `prunable` in the porcelain list | `git -C <repo> worktree prune` |
+| Worktree with live or unsaved work | anything the reaper refuses | keep; report the reaper's reason |
+| Local branch merged into the default | `merge-base --is-ancestor <b> origin/<default>` | `git branch -d <b>` |
+| Local branch squash-merged | its content is in the default (below) | `git branch -D <b>`, tip SHA in the report |
+| Local branch with unlanded commits | neither of the two above | push it (`git push -u origin <b>`), keep it |
+| Remote branch whose content landed | same content check, against `origin/<b>` | delete it, after one confirmation (step 6) |
+| Remote branch with an open PR | `gh pr list` | keep; it is live |
+| Remote branch unlanded, no PR | not in the default, no PR | keep; report it as an open question |
+| Stash | any | keep; report it. Never `stash drop` without a yes |
+
+**The content check** (what makes a squash merge count as landed): merge the branch into the default
+in memory and see whether anything changes.
+
+```bash
+git -C <repo> merge-tree --write-tree origin/<default> <branch> | head -1   # resulting tree
+git -C <repo> rev-parse origin/<default>^{tree}                             # default's tree
+```
+
+Same tree → the branch adds nothing; it has landed. A conflict, a different tree, or a git older
+than 2.38 (no `--write-tree`) → **not proven**, so it is kept. A branch that never carried a commit
+of its own is a live workspace someone just opened, not leftovers: keep it.
+
+Never delete the default branch, the current branch of another checkout, or `rsc/knowledge`.
+
+## 4. Act, in this order
+
+1. **Uncommitted changes stop that repo.** Show the files and ask once: commit them, stash them, or
+   leave the repo as is. Never commit or discard someone's work in progress on your own. Another
+   session working in that checkout (the isolation notice says so) → do not touch its branch or its
+   files at all; report it.
+2. **Push what is only local.** Every branch with unlanded commits goes to the remote. The default
+   branch ahead of `origin`: push it if the default branch is open here; if it is protected
+   (branches and PRs), move those commits to a branch and open a PR — ask first.
+3. **Retire what landed.** `npx @ericrisco/rsc worktrees reap` for worktrees (it refuses anything
+   that would lose a file, and its refusal stands), `worktree prune`, then the branches from step 3.
+   Without rsc in that repo, follow the manual path in `../worktrees/SKILL.md`.
+4. **Back to the default and pull.** Clean checkout on another branch whose work is pushed →
+   `git -C <repo> switch <default>`. Then `git -C <repo> pull --ff-only`. A pull that cannot
+   fast-forward means the local default diverged: stop and report, never `reset --hard`.
+
+## 5. What is never done
+
+- `reset --hard`, `clean -fdx`, `push --force`, `worktree remove --force`, `stash drop` or `clear` —
+  not to make the picture tidy, not on a "probably fine".
+- Deleting a branch or worktree because its name looks old. Only the proofs in step 3 count.
+- Committing straight to a protected default branch.
+
+## 6. Remote branches: one confirmation, for all of them
+
+Deleting a remote branch reaches everyone who clones the repo. Collect every remote branch whose
+content landed, across all repos, and ask **once** with the full list:
+
+> Remote branches already in main, to delete: `rsc-harness: feat/x, fix/y` · `rsc-brain: feat/z`.
+> ¿Las borro? (sí/no)
+
+On yes: `git -C <repo> push origin --delete <b> ...`. On no: keep them and say so in the report.
+
+## 7. The report
+
+One table, one row per repo, then the open questions. Only facts you observed in this run.
+
+| Repo | Branch | ↑ / ↓ | Worktrees | Local branches | Remote branches | Pending |
+| --- | --- | --- | --- | --- | --- | --- |
+| rsc-harness | main | 0 / 0 | 0 | 0 | 2 deleted | — |
+| rsc-brain | main | 0 / 0 | 1 kept | 1 pushed | — | `feat/z`: live, no PR |
+
+Under it: every deleted squash-merged branch with its tip SHA (it can be brought back with
+`git branch <name> <sha>`), and every item kept with the one action that would close it. A repo that
+is not fully clean is reported as not clean, with the reason; a tidy-looking summary that hides one
+kept item is the failure this skill exists to prevent.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "It's an old branch, nobody uses it" | Age proves nothing. Ancestor or same tree, or it stays. |
+| "Squash-merged, so `-D` is fine without checking" | Check the tree first. A branch with one extra commit after the PR looks identical by name. |
+| "The tree is dirty, I'll stash it to switch to main" | That is someone's work. Ask first; a stash is easy to forget for ever. |
+| "Pull failed, I'll `reset --hard origin/main`" | That throws away local commits. Report the divergence instead. |
+| "I'll `cd` into each child to run git" | `git -C <repo>`. A `cd` plants session state inside the child. |
+| "I'll delete the remote branches as I go" | One list, one confirmation, at the end. |
+| "Report says clean; the kept worktree is a detail" | Say what was kept and why. The report is the deliverable. |
+
+**Next:** after a clean report there is nothing to hand over. Neighbours: `../worktrees/SKILL.md`
+opens isolation for new work; `../ship/SKILL.md` lands one finished branch; `npx @ericrisco/rsc
+upgrade` updates the harness itself, which is a different "actualiza".
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/tidy/evals/README.md

@@ -0,0 +1,23 @@
+# Evals — tidy
+
+The claim under test is the boundary with three neighbours that also say "update" or "clean":
+`rsc upgrade` (the harness version), `worktrees` (opening isolation) and `ship` (landing one
+branch). The negatives prove the split.
+
+## Triggering
+
+Load only `tidy` and run every prompt in 3–5 fresh sessions. A positive passes when `tidy` loads in
+a majority of trials; a negative passes when it stays quiet. Require at least 90% accuracy, and treat
+a trigger on "actualiza rsc a la última versión" as blocking: that one is the same verb, a
+different job.
+
+## Capability
+
+Fixture: a workspace with a root repo and two child repos holding, between them, a merge-landed
+branch, a squash-landed branch whose remote is gone, a branch with one unpushed commit, a landed
+worktree, a worktree with an untracked `.env`, and a child checkout left on a feature branch.
+
+Pass when, after the run: both landed branches are gone (the squash one with its SHA reported); the
+unpushed branch exists on the remote and locally; the landed worktree is gone; the `.env` worktree is
+still there and reported; every checkout is on `main`, 0 ahead and 0 behind; and no remote branch was
+deleted before the single confirmation. Any lost commit or file fails the run outright.

package/skills/tidy/evals/cases.yaml

@@ -0,0 +1,53 @@
+skill: tidy
+
+# `tidy` owns the end-of-day sweep across every repo in the workspace: each on its default
+# branch, pushed, pulled, no landed branch or worktree left. Upgrading rsc itself, opening
+# isolation for new work and landing one branch belong to neighbours.
+should_trigger:
+  - prompt: "Limpia el harness."
+    why: "The owner's own phrase for the whole sweep."
+
+  - prompt: "Actualiza todo a main en estos proyectos, que esté todo subido y sin ramas."
+    why: "Default branch, pushed, no branches: the contract in one sentence."
+
+  - prompt: "Sube y baja todo y quita los worktrees que sobren."
+    why: "Push, pull and retire leftovers across the workspace."
+
+  - prompt: "Tidy up the repos, I have branches and worktrees everywhere."
+    why: "Leftover branches and worktrees across repos, in English."
+
+  - prompt: "Déjalo todo en main y limpio antes de irme."
+    why: "End-of-session state for every repo."
+
+  - prompt: "Sync everything with GitHub and delete the merged branches."
+    why: "Push/pull plus landed-branch cleanup is this skill's whole job."
+
+should_not_trigger:
+  - prompt: "Actualiza rsc a la última versión."
+    route_to: "suggest"
+    why: "Upgrading the harness itself is `rsc upgrade`, not a git sweep."
+
+  - prompt: "Abre un worktree para empezar la feature de pagos."
+    route_to: "worktrees"
+    why: "Opening isolation for new work is the opposite move."
+
+  - prompt: "Esta rama ya pasó review, fusiónala."
+    route_to: "ship"
+    why: "Landing one verified branch is ship."
+
+  - prompt: "Borra los ficheros temporales y el node_modules del proyecto."
+    route_to: "bash-scripting"
+    why: "Disk cleanup inside a project is not branch and remote hygiene."
+
+capability:
+  - scenario: "User says: 'Limpia el harness.' The workspace has a root repo and two child repos. Between them: a branch merged into main, a squash-merged branch whose remote is gone, a branch with one unpushed commit, a worktree whose work landed, a worktree holding an untracked `.env`, and one child checkout left on a clean, pushed feature branch. Another child has an uncommitted edit to README.md."
+    must_include:
+      - "Lists the repos it found (root plus every nested repo) before changing anything, and runs git with `git -C <repo>` instead of changing directory into a child"
+      - "Fetches with prune and reads branches, worktrees, stashes and status for every repo before the first write"
+      - "Deletes the merged branch with `git branch -d`, and the squash-merged one only after the content check (merge-tree tree equals the default's tree), reporting its tip SHA"
+      - "Pushes the branch with the unpushed commit and keeps it, instead of deleting it"
+      - "Retires the landed worktree through `npx @ericrisco/rsc worktrees reap` and keeps the `.env` worktree, reporting the reaper's reason"
+      - "Stops on the uncommitted README.md edit and asks (commit, stash or leave) instead of stashing or discarding it on its own"
+      - "Switches the clean child checkout back to main and pulls with `--ff-only`"
+      - "Asks once, with the full list, before deleting any remote branch"
+      - "Ends with one table per repo plus the kept items and the action that would close each, and never uses reset --hard, push --force, clean -fdx or stash drop"