@sassywares/skills 0.11.0 → 0.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CONCEPTS.md CHANGED
@@ -59,12 +59,19 @@ owns the lifecycle; the scripts in `.sassywares/worktree/` own the git.
59
59
  - **Namespace** — the slug prefixed with the repo (`shop-feat-catalog`), and the
60
60
  only name a hook should use for a database, a compose project, or a simulator.
61
61
  Derived once by `create`; never rebuilt by hand.
62
- - **Port claim** — the private port a checkout owns: hashed from the slug into the
63
- configured range, claimed with an atomic `mkdir`, and probed forward on a
64
- collision. Liveness is *probed*, never read from a pid file.
62
+ - **Port claim** — the private port a checkout owns, *when the project configured
63
+ `worktrees.ports`*: hashed from the slug into the range, claimed with an atomic
64
+ `mkdir`, and probed forward on a collision. Liveness is *probed*, never read
65
+ from a pid file. Without a range there is no port and nothing to claim — a port
66
+ is one resource, not the definition of a preview.
65
67
  - **Preview** — bringing that checkout up so a human can look at it. It runs the
66
68
  dogfood recipe's steps up to the section's `Prove it:` and never judges the
67
- work; proving is dogfood's job.
69
+ work; proving is dogfood's job. **How to see it** is the recipe's `**Preview:**`
70
+ line with `WT_*` substituted — a URL, a simulator, a window, never the command
71
+ that started it — so the suite never assumes a browser.
72
+ - **Managed checkout** — one under `worktrees.dir` that also carries
73
+ `.sassywares/config.yaml`. The tooling lists, prunes, stops, and removes only
74
+ those; anything else belongs to another tool or predates the wiring.
68
75
 
69
76
  `create` and `remove` need an agent because their hooks are project skills, and a
70
77
  script cannot dispatch one. That is why the lifecycle is a skill and the git is a
package/README.md CHANGED
@@ -179,7 +179,7 @@ hooks:
179
179
  worktrees: # parallel checkouts of this repo
180
180
  enabled: false # true = a run may work in its own checkout
181
181
  dir: ~/.sassywares/worktrees # parent of the per-repo folder
182
- ports: 3000-3099 # the range a checkout claims a port from
182
+ ports: 3000-3099 # optional; delete for a non-port preview
183
183
  dogfood: # agent QA: a stored procedure that proves a change runs
184
184
  enabled: false # true lets a plan write Mode: Auto QA rows
185
185
  recipe: .sassywares/dogfood/recipe.md # the procedure; never commands here
@@ -199,12 +199,22 @@ directory, a port, a database. `worktrees:` turns that on:
199
199
  └── feat-catalog-search/
200
200
  ```
201
201
 
202
- `create` derives the whole namespace from the branch and prints it — `WT_PATH`,
203
- `WT_SLUG`, `WT_NAMESPACE`, `WT_PORT`, `WT_BASE_URL` — so a project's hook derives
204
- `.env`, a database name, or a simulator from one source instead of inventing its
205
- own. Ports hash into the configured range and are claimed atomically, so a
206
- restarted app comes back on the same port and two slugs that hash alike do not
207
- fight.
202
+ Only checkouts this tooling manages are listed or pruned: one under `worktrees.dir`
203
+ that also carries `.sassywares/config.yaml`. Anything else — another tool's
204
+ worktree, or one cut from a ref that predates the wiring — is counted in a footer
205
+ and left alone.
206
+
207
+ `create` derives the identity from the branch and prints it — `WT_PATH`,
208
+ `WT_SLUG`, `WT_NAMESPACE` — so a project's hook derives `.env`, a database name,
209
+ or a simulator from one source instead of inventing its own.
210
+
211
+ A **port is a resource, not the model**. With `ports:` configured, a checkout
212
+ also gets `WT_PORT` and `WT_BASE_URL`, hashed into the range and claimed
213
+ atomically so a restarted app returns to the same port. Delete `ports:` and there
214
+ is no port at all: the checkout is addressed by the recipe's `**Preview:**` line
215
+ instead — a simulator named `$WT_NAMESPACE`, a desktop window, or nothing at all
216
+ for a CLI. The `list` table's column is `HOW TO SEE`, not "address", for exactly
217
+ that reason.
208
218
 
209
219
  It needs `commit.branch: new`: under `current` a run commits where it stands and
210
220
  never cuts a branch, so nothing would create a checkout. `--check` says so rather
@@ -212,7 +222,7 @@ than leaving a switch that cannot fire.
212
222
 
213
223
  **Previewing.** `sassy-worktree mode:preview` runs the dogfood recipe's bring-up
214
224
  steps — everything up to the section's `Prove it:` — leaves the app running, and
215
- prints the address. A worktree gets a fresh, empty `.sassywares/session/`, and
225
+ prints the preview line — the result, not the command that booted it. A worktree gets a fresh, empty `.sassywares/session/`, and
216
226
  most providers register one callback URL, so the usual answer is to copy or link
217
227
  the main checkout's session in the `after_create` hook: a cookie is host-scoped
218
228
  and crosses ports freely, while a `localStorage` session is origin-scoped and has
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.11.0",
3
+ "version": "0.11.2",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -36,22 +36,41 @@ recipe, and the next `run` is what proves it.
36
36
 
37
37
  ## Steps — `mode:run`
38
38
 
39
- 1. **Resolve the target.** Read the `dogfood:` block. If `enabled` is not `true`, stop with one line: reporting is not enabled, and enabling it is `sassy-setup mode:init`. Load the recipe; a section the caller names (`section:<name>`) is the target, otherwise every section. A missing recipe, or one whose section has no `Prove it:` step, stops the run and names `mode:discover` — never guess a verdict from a procedure that has none.
40
- 2. **Preflight, and do not run blind.** The recipe's *Set up once* lists what must exist. Check that each env var it **names** is present — presence only, never print a value — that a session the recipe refers to is actually in `.sassywares/session/`, and that the commands' entry points exist. A missing dependency, a tool not on `PATH`, or an absent env var is `class: env`: write the report, report it, and stop. Never install, never `docker pull`, never mutate the environment to get past preflight.
41
- 3. **Open the report.** Create `<reports>/<YYYYMMDD-HHMMSS>/` with `steps/` and `artifacts/`, and write `summary.md` with `status: running`, the class blank, the recipe path with the current commit, and the start time. Prune older run directories down to ten.
42
- 4. **Execute in order, stopping at the first broken expectation.** Per step: write `steps/<section>-<NN>.log`, capped head-and-tail, with the command and its output, values of every env var the recipe names masked, and the exit code. `Do` is a command *or* an instruction — satisfy it with whatever is available, and judge it only against its `Expect`. A step whose expectation fails ends that section: record it, keep everything already written, and skip to the report. Resume at the failed step on the next run, never from the top: the summary's `Next:` line says which.
39
+ 1. **Resolve the target.** Read the `dogfood:` block. If `enabled` is not `true`, stop with one line: reporting is not enabled, and enabling it is `sassy-setup mode:init`. Load the recipe; a section the caller names (`section:<name>`) is the target, otherwise every section. A missing recipe, or one whose section has no `Prove it:` step, stops the run and names `mode:discover`. A section whose `**Prove it:**` says `none` is refused with one line — it has no machine verdict by design, so its QA rows are `Manual`, and running it would only manufacture an opinion. Never guess a verdict from a procedure that has none.
40
+ 2. **Open the report.** Create `<reports>/<YYYYMMDD-HHMMSS>/` with `steps/` and `artifacts/`, and write `summary.md` with `status: running`, the class blank, the recipe path with the current commit, and the start time. Prune older run directories down to ten.
41
+ 3. **Preflight, then the bring-up.** Preflight checks presence only: each env var the recipe **names** (never print a value), a session it refers to actually sitting in `.sassywares/session/`, and the commands' entry points existing. A missing entry point, a tool not on `PATH`, or an absent env var is `class: env` — write the report, report it, and stop.
42
+
43
+ Then **run the recipe's *Set up once*.** It is the bring-up, not a checklist: install frozen where the project has a lockfile, and continue. That is the only installing a run does — never install something the recipe does not name, never `docker pull`, never mutate the environment to make a step pass.
44
+
45
+ 4. **Execute in order, stopping at the first broken expectation.** Per step: write `steps/<section>-<NN>.log`, capped head-and-tail, with the command and its output, values of every env var the recipe names masked, and the exit code. `Do` is a command *or* an instruction — satisfy it with whatever is available, and judge it only against its `Expect`. The step's own shell mechanics are part of the step: backgrounding a server, redirecting its output, creating the directory a log path lives in. Improvisation is what the recipe does **not** name. A step whose expectation fails ends that section: record it, keep everything already written, and skip to the report. Resume at the failed step on the next run, never from the top: the summary's `Next:` line says which.
43
46
  5. **Take the verdict from the prove step.** The section's `Prove it:` step decides: exit 0 is `pass`, non-zero is `failed`. A failure earlier in the section is `failed` regardless. This skill holds no opinion about the work — a check it judged by reading instead of running is not a verdict.
44
- 6. **Classify.** `env` when the toolchain is broken (exit 75 or 127, a missing dependency, an unreachable service that is not part of the change); `recipe` when a step cannot be followed at all (a script renamed, a URL that no longer exists, a UI that no longer matches) — that is the procedure being stale, not the code being wrong; `code` otherwise. When in doubt between `recipe` and `code`, ask: could a person follow this step as written and still be testing the app? If not, it is `recipe`.
45
- 7. **Finalize and report.** Write the final `summary.md` (`status`, `class`, the per-step table, artifacts, `Next:`), then return compactly: verdict, class, section, failing step id, the last ~600 characters of that step's log, the report path, and — for `recipe` — the one-line diff you propose. Never paste a whole log to the caller.
47
+ **The deadline is yours to hold.** Track wall-clock from the start and stop at `dogfood.timeout`, filing the run as `failed` with `class: env` and the step it stopped in. A step that can hang states its own bound in its `Expect`; the recipe-wide deadline is the backstop, not a substitute.
48
+
49
+ 6. **Classify.** `env` when the environment cannot produce a verdict: exit 75 or 127, a missing dependency, or **a service nobody in this run controls** being down (a third-party API, a shared backend). That last one is neither `code` nor `recipe` — report it, name the dependency, and stop. The line between the two is whose text is wrong: the named toolchain is right but absent → `env`; the recipe names the wrong version, script, or URL → `recipe`, because the procedure itself is what failed; `recipe` when a step cannot be followed at all (a script renamed, a URL that no longer exists, a UI that no longer matches) — that is the procedure being stale, not the code being wrong; `code` otherwise. When in doubt between `recipe` and `code`, ask: could a person follow this step as written and still be testing the app? If not, it is `recipe`.
50
+ 7. **Finalize and report.** A preflight or bring-up failure has no step id, so it logs to `steps/00-setup.log` and the summary's table row reads `setup`. Write the final `summary.md` (`status`, `class`, the per-step table, artifacts, `Next:`), then return compactly: verdict, class, section, failing step id, the last ~600 characters of that step's log, the report path, and — for `recipe` — the one-line diff you propose. Never paste a whole log to the caller.
46
51
  8. **On `recipe`, propose and stop.** Show the diff that would make the procedure followable and ask before writing it. Never edit the recipe to turn a red run green: the cheapest way to pass a check must not be to weaken it.
47
52
 
48
53
  ## Steps — `mode:discover`
49
54
 
50
- 1. **Read what the project already says.** The existing recipe, the config, and the manifest's scripts (`package.json`, `Makefile`, `pyproject.toml`, `deno.json`, a CI workflow) — what is already wired is the answer more often than a new harness is. Discover, do not impose.
51
- 2. **Find the surfaces.** What is this product? A web app, an API, a CLI, a library, a desktop app, a mobile app in a simulator, several of them. Each surface that a change can break gets a section.
52
- 3. **Find the cheapest proof per surface.** Prefer, in order: an existing test suite or e2e target, a single narrow command that exercises the change, an instruction the agent can carry out against the running product. Whatever the harness has connected right now is fair game; nothing is installed to make this work.
53
- 4. **Try it, then write down what worked.** Bring the product up, run the proof, watch it fail at least once if you can arrange it — a check nobody has seen fail is not a check — then write the steps exactly as they succeeded, with the `Expect` each one actually produced. Write instructions, not recipes for one tool.
54
- 5. **Report.** The sections written, which proof each uses, what is still unknown, and whether a `Mode: Auto` row is now justified. Say plainly that `sassy-setup mode:init` flips `dogfood.enabled` and that the switch alone changes nothing.
55
+ 1. **Read what the project already says.** The existing recipe, the config, and the manifest's scripts (`package.json`, `Makefile`, `pyproject.toml`, `deno.json`, a CI workflow). **Reading is not deciding** — what exists is the starting point, never the target.
56
+ 2. **Find the surfaces.** What is this product? A web app, an API, a CLI, a library, a desktop app, a mobile app in a simulator, several of them. Each surface that a change can break gets its own answer — in a monorepo especially, one app having a suite says nothing about its siblings. **A surface is something this repository serves**; a backend it calls is not a surface — record it as `**Upstream:**` and let its outages be `env`.
57
+ 3. **Classify each surface, honestly.** Three classes and no fourth:
58
+
59
+ | Class | Means | Becomes |
60
+ |---|---|---|
61
+ | `runtime` | something already drives the running product — e2e, integration, a smoke script | a section that wraps it |
62
+ | `unit-only` | tests exist, but they never start the product | an **uncovered** section |
63
+ | `none` | nothing | an **uncovered** section |
64
+
65
+ **A unit test is not a dogfood path**, and neither is `lint`, `tsc`, or `build`: they never start the product. Recording one as coverage is the failure this step exists to prevent — it makes an untested app look tested, and nobody can tell afterwards that the gap was never closed.
66
+ 4. **Ask, one surface at a time — and stop until answered.** With what you found: *"`web`, `api`, and `admin` have no runtime path — `web` has Playwright, the other two only unit tests. Set up a runtime check for `api` and `admin`?"* The options are wrap an existing suite, add a small runtime check, or leave it uncovered and say so. **This step blocks steps 5–8**: the answer decides what gets written, so with no user to ask, stop and report the question verbatim — never write a recipe on a guessed answer. Never leave a surface uncovered silently, and never fill the gap with what happens to exist.
67
+
68
+ A **small runtime check is in scope**: a boot plus one assertion, a `curl`, a screenshot diff — written into the recipe as steps. That is not a test framework, and it is the only check this skill authors. Installing a driver or a runner to make one possible is out of bounds; without one already present, the surface is uncovered.
69
+ 5. **Write the draft, gaps included.** An uncovered section ends with `**Prove it:** none` — explicitly, so a plan keeps its rows `Manual`. Name the uncovered surfaces in the header too (`**Uncovered:** api (unit tests only), admin (nothing)`), so the gap is visible without reading every section.
70
+ 6. **Run it, and log every deviation.** Bring the product up and run the draft. Anything you do that is **not a step in the recipe** — an install, an export, a patch, a workaround, a second terminal — is a *deviation*, written down as you go. This is the only step where improvising is allowed, and it is never silent.
71
+ 7. **Reconcile.** Every deviation becomes exactly one of two things: a step in the recipe, or the reason this surface is unprovable (`**Prove it:** none`). A recipe whose check passed only with help the recipe does not contain is wrong. If you cannot capture a deviation as a step, the surface is uncovered — say so rather than shipping a procedure nobody else can follow.
72
+ 8. **Prove the procedure, not the day — with a fresh agent.** Hand the recipe to a run that has **nothing but the recipe and the config**: a new session, or a dispatched agent, but never this one. It is run once from a clean checkout, allowing no deviation. If you cannot get one, say the recipe is **unverified** rather than claiming it. That second run is the artifact. If it needs improvising, the recipe is wrong: fix it and repeat once; still failing means uncovered and visible.
73
+ 9. **Report.** Per surface: its class, its proof, whether it was asked about, the deviations you reconciled, and what is still unknown. Mark a check you wrote as **unproven** if you never watched it fail — breaking the thing once is the way to earn that. Say plainly that `sassy-setup` flips `dogfood.enabled` and that the switch alone changes nothing.
55
74
 
56
75
  ## Steps — `mode:check`
57
76
 
@@ -70,6 +89,12 @@ Run the `sassy-setup` skill's `scripts/detect.sh --root <path> --check` and repo
70
89
  | Env is not code | Exit 75/127, a missing dependency, or an unreachable service is `env`: report and park. Looping on a broken toolchain burns a run for nothing. |
71
90
  | Resume, don't restart | Re-run from the failed step; the summary says where. Starting over hides the state that made the failure happen. |
72
91
  | Reports are disposable | Pruned to ten. The durable record is the QA row's note, which names the verdict and the run id, never a path that will vanish. |
92
+ | Never promote what exists | A unit test, `lint`, or `build` is not a dogfood path. Discovery records what the product needs, and says so when that is nothing yet. |
93
+ | Improvise out loud, or not at all | Discovery may improvise, never silently: every action that is not a step is a deviation, and every deviation is promoted into a step or kills the surface. A run never improvises — it classifies and stops. |
94
+ | The second run is the artifact | A recipe is proven by a clean checkout that has nothing but the recipe. If it only works with the discoverer's context, it does not work. |
95
+ | Ask about every gap | Each uncovered surface gets one question: wrap a suite, add a runtime check, or leave it uncovered and visible. Silence is how a gap becomes a false green. |
96
+ | No third-party mutation | A run never registers a user, sends mail, charges a card, or writes to a shared service it does not own. A public demo API is somebody else's database. |
97
+ | No dependency churn | A bring-up never changes a lockfile. Install frozen where the project has one; a broken lockfile is `env`, not something to repair mid-run. |
73
98
  | Not a test framework | If the project has a suite, the recipe wraps it. This skill never grows assertions of its own beyond a step's `Expect`. |
74
99
 
75
100
  ## What dogfood is not
@@ -19,7 +19,7 @@ The plan has no open-questions section. Every branch the interview found is a de
19
19
  Every phase gets a QA table. Each row's `Mode` is `Auto` or `Manual`, and the choice is not a preference:
20
20
 
21
21
  - **`Manual` is the default.** Write each row so a person can run it without reading code — what to set up, what to do, and what passing looks like.
22
- - **`Auto` needs two things**: the project's `dogfood.enabled` is `true` (per the `sassy-setup` skill's `references/dogfood.md`) **and** the row names a recipe section that carries a `Prove it:` step. One without the other stays `Manual`. An `Auto` row with no check behind it is a gate that proves nothing.
22
+ - **`Auto` needs two things**: the project's `dogfood.enabled` is `true` (per the `sassy-setup` skill's `references/dogfood.md`) **and** the row names a recipe section whose `**Prove it:**` names a step. One without the other stays `Manual`. A section whose `**Prove it:**` says `none` has no machine verdict by design — its rows are `Manual`, and writing `Auto` against it is a gate that proves nothing.
23
23
  - An `Auto` row names the recipe **section**, never a command. Commands belong in the recipe; copied into a row they rot one row at a time.
24
24
 
25
25
  A row stays `Manual` when the answer is genuinely a human's:
@@ -44,8 +44,8 @@ A check run never edits the config and never rewrites the tree: it prints what `
44
44
  - **`commit.branch`** — default `new`: the run cuts a branch before the first change and never commits on a base branch. Offer `current` for a repo that genuinely wants work committed where it stands, and say plainly that `current` lets a run commit onto its base branch and push it, with no PR (`pr.*` and `hooks.pr` are ignored; `hooks.push` runs). Under `mode:auto` with `current` on a base branch, ship pushes to that base with no gate.
45
45
  - **`pr.*`** — default `babysit: true`, `merge: false`, `delete_branch: false`. Say plainly that `merge: true` authorizes merging every babysat PR in this project without asking.
46
46
  - **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge` (or `hooks.push` `after_push`, for `commit.branch: current` only), and under which head branch (`"*"` for all). Entries may carry args (`<skill> <args…>`); a hook skill's args are its own vocabulary. Leave them `[]` when there is nothing to add. **Never write a hook skill yourself** — hooks are project skills, and copying one of ours into that role is the fork this mechanism exists to prevent.
47
- - **Worktrees** — ask whether the project wants parallel work in this repo: a checkout per branch, each with its own derived namespace and port, so two runs never fight over one working tree. Say plainly what it costs and what it needs. `false` — the run works here, which is today's behaviour. `true` — a run may create a checkout, and `sassy-worktree` gains `create`, `list`, `preview`, `remove`, and `prune`. It needs `commit.branch: new`: under `current` nothing ever cuts a branch, so the switch would do nothing — say so and leave it `false` rather than writing a setting that cannot fire. In `workspace` or `none` topology, say it is not available and write `false`. Read `references/worktree.md`; **never write a hook yourself** for the project's checkout prep.
48
- - **Dogfood** — ask whether the project wants agent QA: a stored procedure that proves a change works in the running product, which then lets `sassy-plan` write `Mode: Auto` QA rows instead of manual ones. Say plainly what each answer means. `false` — every QA row stays a human's, which is today's behavior. `true` — a plan may write Auto rows, but only for a recipe section that carries a `Prove it:` step, so the switch alone never makes a gate prove something. Write the answer explicitly either way; never leave it to inference. On yes, scaffold per step 4. Read `references/dogfood.md` and **never** write a command into the block or author the procedure: the recipe is the project's, and its first real content comes from a `sassy-dogfood mode:discover` run.
47
+ - **Worktrees** — ask whether the project wants parallel work in this repo: a checkout per branch, each with its own derived namespace and port, so two runs never fight over one working tree. Say plainly what it costs and what it needs. `false` — the run works here, which is today's behaviour. `true` — a run may create a checkout, and `sassy-worktree` gains `create`, `list`, `preview`, `remove`, and `prune`. It needs `commit.branch: new`: under `current` nothing ever cuts a branch, so the switch would do nothing — say so and leave it `false` rather than writing a setting that cannot fire. In `workspace` or `none` topology, say it is not available and write `false`. Read `references/worktree.md`. **Say what a checkout will need for this project** — install, `.env` derivation, a per-namespace database, a simulator, the session — and offer to create the hook with `sassy-skill`; **never write its body yourself**. With no hook, say plainly that every new checkout starts empty and the first preview will show it.
48
+ - **Dogfood** — ask whether the project wants agent QA: a stored procedure that proves a change works in the running product, which then lets `sassy-plan` write `Mode: Auto` QA rows instead of manual ones. Say plainly what each answer means. `false` — every QA row stays a human's, which is today's behavior. `true` — a plan may write Auto rows, but only for a recipe section that carries a `Prove it:` step, so the switch alone never makes a gate prove something. Write the answer explicitly either way; never leave it to inference. On yes, scaffold per step 4 and offer to run the first `sassy-dogfood mode:discover` before this run ends: yes means do it now (it is the only step that knows how to bring this app up), no means hand over the command and say the recipe stays a skeleton until it runs. Read `references/dogfood.md` and **never** write a command into the block or author the procedure: the recipe is the project's, and its first real content comes from a `sassy-dogfood mode:discover` run.
49
49
  4. **Write the config.** Build the file from the proposal plus the answers. It is written **fully commented**: every key keeps a description and its allowed values, exactly as the detector emits them. Never strip those comments to save lines — for a teammate opening the file, the comments are the documentation. If a config already exists, show what changes and ask before writing — never silently overwrite. Keep every key; an unset key falls back to its documented default, so a short file is legal when nothing deviates.
50
50
 
51
51
  **The dogfood scaffold, only when the answer was yes.** Create `.sassywares/dogfood/` holding `recipe.md` copied verbatim from `assets/dogfood-recipe.md`, and `.sassywares/.gitignore` with two lines — `/session/` and `/dogfood/reports/` — adding them to a `.gitignore` that already exists rather than replacing it. Never overwrite an existing recipe — show it and ask. The skeleton is deliberately incomplete: it carries the shape and the rules and fills in nothing, because `sassy-dogfood mode:discover` writes the procedure from what actually worked. Say so in the report — `enabled: true` is a permission, not a promise that a check exists.
@@ -81,7 +81,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
81
81
 
82
82
  6. **Install the git tooling.** Two independent sets, each only when its answer was yes.
83
83
 
84
- - **Worktrees, `repo` topology and `worktrees.enabled: true`.** Copy every file in `assets/worktree/` flat into `.sassywares/worktree/` and make the five scripts executable, then add one `worktree:<script>` alias per script to the project's manifest, append-only, exactly as the workspace aliases are. Report the `worktree-version` you installed. **Ask before overwriting any of them when they already exist** — from the first install they are the project's files. Read `references/worktree.md`. Do not create a worktree, and do not run a script: installing is the whole job, and the first `create` belongs to a run or to the user.
84
+ - **Worktrees, `repo` topology and `worktrees.enabled: true`.** Copy every file in `assets/worktree/` flat into `.sassywares/worktree/` and make the five scripts executable, then add one `worktree:<script>` alias per script to the project's manifest, append-only, exactly as the workspace aliases are. **Prove the merge**: the file must still parse (`node -p "require('./package.json')"`, or the manifest's own syntax check) and `git diff` must show only added lines plus at most one trailing comma — anything else is a rewrite, so restore the file from `HEAD` and insert again. Report the `worktree-version` you installed. **Ask before overwriting any of them when they already exist** — from the first install they are the project's files. Read `references/worktree.md`. Do not create a worktree, and do not run a script: installing is the whole job, and the first `create` belongs to a run or to the user.
85
85
  - **Workspace, `workspace` topology only.** The snapshot plus the `branches` / `pull` / `checkout-bases` git helpers, and one `workspace:<script>` alias per script in the project's own manifest. Read `references/workspace.md` and follow it.
86
86
  7. **Verify.** Run `scripts/detect.sh --root <path> --check`. It validates the config against the tree — topology and remotes, `base_map` shape and cycles, `repos` against each nested repo, hooks, artifacts paths, `knowledge`, `pr.*` booleans, `commit.branch`, the `worktrees` block, the `dogfood` block, any unknown key, and in `workspace` mode the installed snapshot's version — plus, for a project-scope install, the pin: every suite-skill folder in `.agents/skills` (a name in the suite's roster, `assets/roster` in sassy-setup, not any `sassy-` prefix) hashed against `skills-lock.json`, the lock's coverage both ways, and whether git carries the lock. A user-scope install has no pin here; the check notes the scope it found. Report every `drift:` line verbatim, or that the config matches the tree. Drift blocks step 8.
87
87
 
@@ -92,7 +92,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
92
92
  Then check the skills and the agents exactly as step 5's **Installed** rules say, and report the scope each was found in or what is missing. A check run never installs them; a missing suite or roster is reported with the fix (`mode:init`), and it does not block step 8.
93
93
  8. **Commit what setup owns.** `repo` topology only, and only when step 7 is clean. The file list is exactly what setup wrote or found unwritten:
94
94
 
95
- `.sassywares/config.yaml`, `.sassywares/README.md`, `.sassywares/dogfood/recipe.md` and `.sassywares/.gitignore` when step 4 created them, `.sassywares/worktree/*` when step 6 installed them, `.agents/skills/sassy-*` and `skills-lock.json` when the suite is in project scope, the project-scope agent files when step 5 copied them, and `.gitignore` when step 5 created it. Named files only — never `git add -A`, never `git add .`. The reports directory is never in this list: it is gitignored, and nothing setup writes lives there.
95
+ `.sassywares/config.yaml`, `.sassywares/README.md`, `.sassywares/dogfood/recipe.md` and `.sassywares/.gitignore` when step 4 created them, `.sassywares/worktree/*` and `package.json` when step 6 installed the tooling and added its aliases, `.agents/skills/sassy-*` and `skills-lock.json` when the suite is in project scope, the project-scope agent files when step 5 copied them, and `.gitignore` when step 5 created it. Named files only — never `git add -A`, never `git add .`. The reports directory is never in this list: it is gitignored, and nothing setup writes lives there.
96
96
 
97
97
  Dispatch `sassy-commit` with that list and `branch:current`. The token is explicit, not this skill's default: wiring is a one-time bootstrap commit, and cutting a branch would leave the project configured but uncommitted until someone ships it. Name the branch it landed on, base branch included.
98
98
 
@@ -7,7 +7,7 @@ never values>
7
7
 
8
8
  **Reset:** <back to a known state>
9
9
 
10
- **Preview:** <the one command a human runs to look at it — `bun dev --port $PORT` — and what to open>
10
+ **Preview:** <what you look at once it is up — `http://localhost:$WT_PORT`, a simulator name, a window. Not the command; that is a step below.>
11
11
 
12
12
  <!--
13
13
  Incomplete on purpose. sassy-setup writes this skeleton so the shape is visible;
@@ -100,7 +100,7 @@ wt_namespace() {
100
100
  # under a home that survives a reboot. A second clone of the same project gets a
101
101
  # suffixed folder instead of sharing this one.
102
102
  wt_home() {
103
- local dir base cand parent
103
+ local dir base cand parent owner
104
104
  dir="$(wt_cfg dir "$HOME/.sassywares/worktrees")"
105
105
  case "$dir" in
106
106
  "~") dir="$HOME" ;;
@@ -114,18 +114,29 @@ wt_home() {
114
114
  [ -d "$parent" ] && dir="$(cd "$parent" && pwd -P)/$(basename "$dir")"
115
115
  base="$(basename "$MAIN")"
116
116
  cand="$dir/$base"
117
- if [ -f "$cand/.repo" ] && [ "$(cat "$cand/.repo" 2>/dev/null)" != "$MAIN" ]; then
118
- cand="$dir/$base-$(printf '%s' "$MAIN" | shasum -a 256 | cut -c1-6)"
117
+ if [ -f "$cand/.repo" ]; then
118
+ owner="$(cat "$cand/.repo" 2>/dev/null || true)"
119
+ # Only a live checkout squats the plain name; a deleted one is reclaimed, so a
120
+ # finished project does not leave a hash-suffixed home behind forever.
121
+ if [ "$owner" != "$MAIN" ] && [ -n "$owner" ] && [ -d "$owner" ]; then
122
+ cand="$dir/$base-$(printf '%s' "$MAIN" | shasum -a 256 | cut -c1-6)"
123
+ fi
119
124
  fi
120
125
  printf '%s' "$cand"
121
126
  }
122
127
 
123
128
  wt_path() { printf '%s/%s' "$(wt_home)" "$1"; }
124
129
 
125
- # --- ports ----------------------------------------------------------------
130
+ # --- resources ------------------------------------------------------------
131
+ # A port is one resource a checkout may need, not the definition of a preview. A
132
+ # mobile app claims a simulator, a desktop app nothing, and both are legitimate:
133
+ # when `worktrees.ports` is absent nothing is derived and nothing is claimed.
134
+ wt_has_ports() { [ -n "$(wt_cfg ports '')" ]; }
135
+
126
136
  wt_range() {
127
137
  local r lo hi
128
- r="$(wt_cfg ports 3000-3099)"
138
+ r="$(wt_cfg ports '')"
139
+ [ -n "$r" ] || return 0
129
140
  case "$r" in
130
141
  *-*) lo="${r%%-*}"; hi="${r##*-}" ;;
131
142
  *) lo="$r"; hi="$r" ;;
@@ -159,6 +170,7 @@ wt_owner() {
159
170
  # one probed forward past claims held by others. Read-only, so `list` may call it.
160
171
  wt_port_for() {
161
172
  local slug="$1" lo hi span i port owner hex d
173
+ wt_has_ports || return 0
162
174
  read -r lo hi <<<"$(wt_range)"
163
175
  for d in "$(wt_home)/ports"/*; do
164
176
  [ -d "$d" ] || continue
@@ -221,6 +233,24 @@ wt_find() { # $1 slug or branch -> path<TAB>branch, or nothing
221
233
  done < <(wt_all)
222
234
  }
223
235
 
236
+ # A checkout is ours when it lives under this repo's worktree home AND carries
237
+ # the wiring. Anything else — another tool's worktree, or one cut before setup
238
+ # was committed — is not managed here: we do not list it, prune it, or delete it.
239
+ wt_managed() { # $1 path
240
+ case "$1" in
241
+ "$(wt_home)"/*) [ -f "$1/.sassywares/config.yaml" ] ;;
242
+ *) return 1 ;;
243
+ esac
244
+ }
245
+
246
+ wt_require_managed() { # $1 slug or branch -> path<TAB>branch, or die
247
+ local rec
248
+ rec="$(wt_require "$1")"
249
+ wt_managed "${rec%%$'\t'*}" \
250
+ || die "'$1' is not managed here — it is outside the worktree home, or it was cut before the wiring"
251
+ printf '%s' "$rec"
252
+ }
253
+
224
254
  wt_require() { # $1 slug or branch -> path<TAB>branch, or die
225
255
  local rec
226
256
  rec="$(wt_find "$1")"
@@ -257,6 +287,42 @@ wt_upstream_state() { # merged | gone | unmerged
257
287
  fi
258
288
  }
259
289
 
290
+ # wt_subst LINE NAME VALUE — expand `$NAME`, `${NAME}` and `${NAME:-default}` for
291
+ # one variable. No name here is a prefix of another, so a plain replace is exact.
292
+ wt_subst() {
293
+ local line="$1" name="$2" val="$3"
294
+ if [ -n "$val" ]; then
295
+ printf '%s' "$line" \
296
+ | sed -e "s|\${$name:-[^}]*}|$val|g" -e "s|\${$name}|$val|g" -e "s|\$$name|$val|g"
297
+ else
298
+ printf '%s' "$line" \
299
+ | sed -e "s|\${$name:-\([^}]*\)}|\1|g" -e "s|\${$name}||g" -e "s|\$$name||g"
300
+ fi
301
+ }
302
+
303
+ # wt_preview SLUG — the recipe's `**Preview:**` line with WT_* substituted.
304
+ # Empty when the project has no recipe or no preview line.
305
+ wt_preview() {
306
+ local slug="$1" recipe line port base
307
+ recipe="$(wt_flat | awk -F'\t' -v p="dogfood${WLIB_US}recipe" '$1 == p { print $2; exit }')"
308
+ recipe="${recipe:-.sassywares/dogfood/recipe.md}"
309
+ case "$recipe" in /*) ;; *) recipe="$MAIN/$recipe" ;; esac
310
+ [ -f "$recipe" ] || return 0
311
+ line="$(sed -n 's/^\*\*Preview:\*\*[[:space:]]*//p' "$recipe" 2>/dev/null | head -n 1)"
312
+ [ -n "$line" ] || return 0
313
+ port=""
314
+ if wt_has_ports; then
315
+ port="$(wt_port_for "$slug")"
316
+ base="http://localhost:$port"
317
+ fi
318
+ line="$(wt_subst "$line" WT_SLUG "$slug")"
319
+ line="$(wt_subst "$line" WT_NAMESPACE "$(wt_namespace "$slug")")"
320
+ line="$(wt_subst "$line" WT_PATH "$(wt_path "$slug")")"
321
+ line="$(wt_subst "$line" WT_PORT "$port")"
322
+ line="$(wt_subst "$line" WT_BASE_URL "$base")"
323
+ printf '%s' "$line"
324
+ }
325
+
260
326
  # Newest dogfood verdict for a checkout, as `status class` — or empty.
261
327
  wt_verdict() {
262
328
  local dir="$1/.sassywares/dogfood/reports" newest s c
@@ -50,20 +50,34 @@ slug="$(wt_slug "$branch")"
50
50
  path="$(wt_path "$slug")"
51
51
 
52
52
  report() { # $1 path, $2 branch
53
- local port addr ns
53
+ local port="" addr="" ns
54
54
  ns="$(wt_namespace "$slug")"
55
- port="$(wt_claim "$slug")"
56
- addr="http://localhost:$port"
55
+ # A port is a resource this project asked for, not a property of a checkout.
56
+ if wt_has_ports; then
57
+ port="$(wt_claim "$slug")"
58
+ addr="http://localhost:$port"
59
+ fi
57
60
  if [ "$env_only" -eq 1 ]; then
58
- printf 'WT_PATH=%s\nWT_BRANCH=%s\nWT_SLUG=%s\nWT_NAMESPACE=%s\nWT_PORT=%s\nWT_BASE_URL=%s\n' \
59
- "$1" "$2" "$slug" "$ns" "$port" "$addr"
61
+ printf 'WT_PATH=%s\nWT_BRANCH=%s\nWT_SLUG=%s\nWT_NAMESPACE=%s\n' "$1" "$2" "$slug" "$ns"
62
+ [ -n "$port" ] && printf 'WT_PORT=%s\nWT_BASE_URL=%s\n' "$port" "$addr"
60
63
  return 0
61
64
  fi
62
65
  ok worktree "$1"
63
66
  ok branch "$2"
64
67
  ok namespace "$ns"
65
- ok port "$port"
66
- ok address "$addr"
68
+ if [ -n "$port" ]; then
69
+ ok port "$port"
70
+ ok address "$addr"
71
+ else
72
+ ok port "none — worktrees.ports is unset, so this checkout holds no port"
73
+ fi
74
+ local preview
75
+ preview="$(wt_preview "$slug")"
76
+ [ -n "$preview" ] && ok preview "$preview"
77
+ # A branch cut from a ref that predates setup has no config and no tooling, so
78
+ # this checkout is not managed here: `list` skips it, `prune` leaves it alone.
79
+ [ -f "$1/.sassywares/config.yaml" ] \
80
+ || ok unmanaged "this branch has no .sassywares/config.yaml — cut from a ref that predates setup; list and prune will skip it"
67
81
  local hooks n
68
82
  hooks="$(wt_hook after_create "$2")"
69
83
  if [ -z "$hooks" ]; then
@@ -28,7 +28,7 @@ while [ $# -gt 0 ]; do
28
28
  case "$1" in
29
29
  -h|--help) usage; exit 0 ;;
30
30
  --version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
31
- --address|--path) kind="${1#--}"; shift; want="${1:-}"; [ -n "$want" ] || die "$kind needs a slug" ;;
31
+ --address|--path|--preview) kind="${1#--}"; shift; want="${1:-}"; [ -n "$want" ] || die "$kind needs a slug" ;;
32
32
  -*) die "unknown flag: $1 (try --help)" ;;
33
33
  *) die "unexpected argument: $1 (try --help)" ;;
34
34
  esac
@@ -38,7 +38,7 @@ done
38
38
  need_git
39
39
 
40
40
  one() { # $1 path, $2 branch
41
- local p="$1" b="$2" slug port
41
+ local p="$1" b="$2" slug port line
42
42
  slug="$(wt_slug "$b")"
43
43
  if wt_is_main "$p"; then
44
44
  die "the main checkout has no derived port — it uses whatever the app defaults to"
@@ -46,33 +46,56 @@ one() { # $1 path, $2 branch
46
46
  case "$kind" in
47
47
  path) printf '%s\n' "$p" ;;
48
48
  address)
49
+ wt_has_ports || die "no port resource here — worktrees.ports is unset; try --preview"
49
50
  port="$(wt_port_for "$slug")"
50
51
  printf 'http://localhost:%s\n' "$port"
51
52
  ;;
53
+ preview)
54
+ line="$(wt_preview "$slug")"
55
+ [ -n "$line" ] || die "no preview line for '$slug' — add one to dogfood.recipe"
56
+ printf '%s\n' "$line"
57
+ ;;
52
58
  esac
53
59
  }
54
60
 
55
61
  if [ -n "$kind" ]; then
56
- rec="$(wt_require "$want")"
62
+ rec="$(wt_require_managed "$want")"
57
63
  one "${rec%%$'\t'*}" "${rec##*$'\t'}"
58
64
  exit 0
59
65
  fi
60
66
 
61
- printf ' %-34s %-50s %-22s %-5s %s\n' "BRANCH" "WORKTREE" "ADDRESS" "LIVE" "LAST RUN"
67
+ printf ' %-34s %-50s %-40s %-5s %s\n' "BRANCH" "WORKTREE" "HOW TO SEE" "LIVE" "LAST RUN"
62
68
  count=0
69
+ unmanaged=0
63
70
  while IFS=$'\t' read -r p b; do
64
71
  [ -n "$p" ] || continue
65
72
  count=$(( count + 1 ))
66
73
  slug="$(wt_slug "$b")"
67
74
  shown="${p/#$HOME/~}"
68
75
  if wt_is_main "$p"; then
69
- printf ' %-34s %-50s %-22s %-5s %s\n' "$b (main checkout)" "$shown" "—" "—" "—"
76
+ printf ' %-34s %-50s %-40s %-5s %s\n' "$b (main checkout)" "$shown" "—" "—" "—"
77
+ continue
78
+ fi
79
+ if ! wt_managed "$p"; then
80
+ unmanaged=$(( unmanaged + 1 ))
70
81
  continue
71
82
  fi
72
- port="$(wt_port_for "$slug")"
73
- if tcp_up "$port"; then live="up"; else live="down"; fi
83
+ # The address is whatever the project says it is: a URL, a simulator, a window.
84
+ line="$(wt_preview "$slug")"
85
+ port=""
86
+ if wt_has_ports; then
87
+ port="$(wt_port_for "$slug")"
88
+ [ -n "$line" ] || line="http://localhost:$port"
89
+ fi
90
+ if [ -n "$port" ]; then
91
+ if tcp_up "$port"; then live="up"; else live="down"; fi
92
+ else
93
+ live="—"
94
+ fi
74
95
  last="$(wt_verdict "$p")"
75
- printf ' %-34s %-50s %-22s %-5s %s\n' "$b" "$shown" "http://localhost:$port" "$live" "${last:-—}"
96
+ printf ' %-34s %-50s %-40s %-5s %s\n' "$b" "$shown" "${line:-—}" "$live" "${last:-—}"
76
97
  done < <(wt_all)
77
98
 
78
99
  [ "$count" -gt 0 ] || log " no checkouts found — is this a git repository?"
100
+ [ "$unmanaged" -gt 0 ] && hint "$unmanaged worktree(s) not managed here — outside $(wt_home | sed "s|$HOME|~|"), or cut before the wiring"
101
+ true
@@ -39,15 +39,21 @@ need_git
39
39
  printf ' %-32s %-9s %-6s %-9s %s\n' "BRANCH" "UPSTREAM" "DIRTY" "UNPUSHED" "ACTION"
40
40
  n_candidates=0
41
41
  n_removed=0
42
+ unmanaged=0
42
43
  while IFS=$'\t' read -r p b; do
43
44
  [ -n "$p" ] || continue
44
45
  wt_is_main "$p" && continue
46
+ wt_managed "$p" || { unmanaged=$(( unmanaged + 1 )); continue; }
45
47
  slug="$(wt_slug "$b")"
46
48
  state="$(wt_upstream_state "$p")"
47
49
  if wt_dirty "$p"; then dirty="yes"; else dirty="no"; fi
48
50
  unpushed="$(wt_unpushed "$p")"
49
- port="$(wt_port_for "$slug")"
50
- if tcp_up "$port"; then live="yes"; else live="no"; fi
51
+ port=""
52
+ live="no"
53
+ if wt_has_ports; then
54
+ port="$(wt_port_for "$slug")"
55
+ tcp_up "$port" && live="yes"
56
+ fi
51
57
 
52
58
  action=""
53
59
  if [ "$state" = "unmerged" ]; then
@@ -57,7 +63,7 @@ while IFS=$'\t' read -r p b; do
57
63
  elif [ "$unpushed" != "0" ]; then
58
64
  action="skipped — $unpushed unpushed"
59
65
  elif [ "$live" = "yes" ]; then
60
- action="skipped — running on :$port"
66
+ action="skipped — running${port:+ on :$port}"
61
67
  else
62
68
  action="removable"
63
69
  n_candidates=$(( n_candidates + 1 ))
@@ -71,7 +77,9 @@ while IFS=$'\t' read -r p b; do
71
77
  warn skipped "$b has a before_remove hook — run remove <$slug> so it runs"
72
78
  continue
73
79
  fi
74
- git worktree remove "$p" && wt_release "$port" "$slug" && n_removed=$(( n_removed + 1 ))
80
+ git worktree remove "$p" || continue
81
+ [ -n "$port" ] && wt_release "$port" "$slug"
82
+ n_removed=$(( n_removed + 1 ))
75
83
  fi
76
84
  done < <(wt_all)
77
85
 
@@ -79,6 +87,6 @@ if [ "$yes" -eq 1 ]; then
79
87
  ok pruned "$n_removed removed, $(( n_candidates - n_removed )) left"
80
88
  elif [ "$n_candidates" -gt 0 ]; then
81
89
  hint "re-run with --yes to remove the $n_candidates removable worktree(s)"
82
- else
83
- ok pruned "nothing to remove"
90
+ [ "$unmanaged" -gt 0 ] && hint "$unmanaged worktree(s) not managed here — left alone"
91
+ [ "$n_candidates" -eq 0 ] && [ "$unmanaged" -eq 0 ] && ok pruned "nothing to remove"
84
92
  fi
@@ -42,7 +42,7 @@ done
42
42
  [ -n "$target" ] || { usage >&2; exit 2; }
43
43
 
44
44
  need_git
45
- rec="$(wt_require "$target")"
45
+ rec="$(wt_require_managed "$target")"
46
46
  path="${rec%%$'\t'*}"
47
47
  branch="${rec##*$'\t'}"
48
48
  slug="$(wt_slug "$branch")"
@@ -59,9 +59,12 @@ if [ -n "$hooks" ] && [ "$hook_ok" -eq 0 ]; then
59
59
  exit 3
60
60
  fi
61
61
 
62
- port="$(wt_port_for "$slug")"
63
- if tcp_up "$port"; then
64
- die "something is still listening on :$port — stop <$slug> first"
62
+ port=""
63
+ if wt_has_ports; then
64
+ port="$(wt_port_for "$slug")"
65
+ if tcp_up "$port"; then
66
+ die "something is still listening on :$port — stop <$slug> first"
67
+ fi
65
68
  fi
66
69
 
67
70
  if [ "$force" -eq 0 ]; then
@@ -79,7 +82,7 @@ if [ "$force" -eq 1 ]; then
79
82
  else
80
83
  git worktree remove "$path"
81
84
  fi
82
- wt_release "$port" "$slug"
85
+ [ -n "$port" ] && wt_release "$port" "$slug"
83
86
 
84
- ok released ":$port"
87
+ [ -n "$port" ] && ok released ":$port"
85
88
  ok removed "$path"
@@ -16,7 +16,9 @@ usage() {
16
16
  Usage: .sassywares/worktree/stop <slug|branch>
17
17
 
18
18
  Kill the processes listening on that worktree's port. Nothing listening is a
19
- success with a note, so stopping twice is safe.
19
+ success with a note, so stopping twice is safe. Only a project that configured
20
+ `worktrees.ports` has something here to stop — for a simulator or a desktop app,
21
+ stopping belongs to the project.
20
22
  EOF
21
23
  }
22
24
 
@@ -27,12 +29,13 @@ case "${1:-}" in
27
29
  esac
28
30
 
29
31
  need_git
30
- rec="$(wt_require "$1")"
32
+ rec="$(wt_require_managed "$1")"
31
33
  path="${rec%%$'\t'*}"
32
34
  branch="${rec##*$'\t'}"
33
35
  slug="$(wt_slug "$branch")"
34
36
 
35
- wt_is_main "$path" && die "the main checkout has no derived port to stop"
37
+ wt_is_main "$path" && die "the main checkout is not a worktree — nothing to stop"
38
+ wt_has_ports || die "no port resource here — stopping this preview is the project's job (its before_remove hook or the recipe)"
36
39
  port="$(wt_port_for "$slug")"
37
40
 
38
41
  if ! tcp_up "$port"; then