@sassywares/skills 0.11.5 → 0.11.7

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.11.5",
3
+ "version": "0.11.7",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -38,7 +38,7 @@ recipe, and the next `run` is what proves it.
38
38
 
39
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
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.
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 — only when it refers to one — 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
42
 
43
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
44
 
@@ -53,7 +53,10 @@ recipe, and the next `run` is what proves it.
53
53
  ## Steps — `mode:discover`
54
54
 
55
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`.
56
+ 2. **Find the surfaces.** Read `**Out of scope:**` first and drop those from the
57
+ list — they were decided against, and asking again is how a decision gets
58
+ reopened every week. `**Uncovered:**` surfaces stay: they still want a path.
59
+ Then: 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
60
  3. **Classify each surface, honestly.** Three classes and no fourth:
58
61
 
59
62
  | Class | Means | Becomes |
@@ -81,7 +84,7 @@ Run the `sassy-setup` skill's `scripts/detect.sh --root <path> --check` and repo
81
84
  | Rule | Requirement |
82
85
  |------|-------------|
83
86
  | The verdict is an exit code | A section's `Prove it:` step decides. Never a judgement, a screenshot someone liked, or "looks right". |
84
- | No tooling, no installs | Never name or require a browser, driver, emulator, or MCP server; never install one to make a run possible. Missing tooling is `class: env`. |
87
+ | No tooling, no installs | Never name or require a browser, driver, emulator, or MCP server. **What the recipe names is allowed** — if *Set up once* says `bun install --frozen-lockfile` or downloads the browser its suite declares, that is the project's declared bring-up and a run executes it. Installing anything the recipe does not name is out of bounds, and so is choosing a tool the project has not committed to. A permitted command's own lifecycle hooks (a `postinstall`) come with it; the run adds none of its own. |
85
88
  | Never production | Local or staging only. A recipe step pointing at production is refused and reported, not run. |
86
89
  | The run may not edit the check | A red run never fixes itself by editing the recipe or its expectations. Propose the diff, ask, stop. |
87
90
  | Reports stay local | Never commit `reports/`. Never paste a full log to a caller, a plan, or a PR. |
@@ -93,7 +96,7 @@ Run the `sassy-setup` skill's `scripts/detect.sh --root <path> --check` and repo
93
96
  | 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
97
  | 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
98
  | 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. |
99
+ | No third-party mutation | A run never registers a user, sends mail, charges a card, or writes to a service it does not own — a public demo API is somebody else's database. **A project-owned test environment is the exception**: an E2E deployment the project built, seeded by its own provisioning script and named in `**Upstream:**`, is the project's call. Production never is. |
97
100
  | 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. |
98
101
  | 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`. |
99
102
 
@@ -5,7 +5,8 @@
5
5
  **Set up once:** <install, services to start, env files to copy; name variables,
6
6
  never values>
7
7
 
8
- **Reset:** <back to a known state>
8
+ **Reset:** <the product back to a known state — a database, a cache, a temp dir.
9
+ Never `reports/`: evidence must outlive the run that made it>`
9
10
 
10
11
  **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
12
 
@@ -68,7 +68,7 @@ because a project that "helpfully" removes it commits screenshots by accident.
68
68
  **Set up once:** `bun install`; `docker compose up -d db`;
69
69
  copy `.env.example` → `.env` and fill `DOGFOOD_USER`, `DOGFOOD_PASS`.
70
70
 
71
- **Reset:** `bun run db:reset`; `rm -rf .sassywares/dogfood/reports/*`
71
+ **Reset:** `bun run db:reset`
72
72
 
73
73
  **Preview:** open `http://localhost:${WT_PORT:-3000}`
74
74
 
@@ -119,7 +119,8 @@ answer. A section without one has no verdict.
119
119
 
120
120
  **One `**Preview:**` line**, optional: **what you look at**, not the command that
121
121
  starts it. The command belongs in the section's steps, where its `Expect` can be
122
- checked. The result — a URL, a simulator, a window — is the project's own answer
122
+ checked — and no step has to consume this line: a suite that starts its own server
123
+ never visits the address a human would. The result — a URL, a simulator, a window — is the project's own answer
123
124
  to "what is the address", and it is why the suite never has to assume a browser.
124
125
 
125
126
  `$WT_SLUG`, `$WT_NAMESPACE`, `$WT_PATH`, `$WT_PORT`, and `$WT_BASE_URL` are
@@ -140,7 +141,13 @@ keeps a recipe runnable outside a worktree.
140
141
  two dangerous facts visible without reading every step: which third-party services
141
142
  the recipe depends on, and which parts have no machine verdict at all. `Uncovered`
142
143
  may name a sub-area of a covered surface — "the web surface's auth and write
143
- flows" — which is where a no-third-party-mutation rule usually lands. A section
144
+ flows" — which is where a third-party rule usually lands.
145
+
146
+ **`**Out of scope:**` is different from `**Uncovered:**`** and the difference is the
147
+ whole point: `Uncovered` means *no path yet* — a later discovery is expected to ask
148
+ again — while `Out of scope` means *decided against*, and a later discovery must
149
+ leave it alone. Without the two words, "we have not built this" and "we do not want
150
+ this" read the same, and discovery asks about both for ever. A section
144
151
  with no verdict ends `**Prove it:** none`, so a plan keeps its rows `Manual`
145
152
  instead of inventing an Auto row for a check that does not exist.
146
153
 
@@ -256,6 +263,10 @@ one file to know where it stopped.
256
263
  note — `catalog-5 exit 1, run 20260514-093107` — which never depends on a path
257
264
  that will be deleted.
258
265
  - **Never committed.** Not the logs, the artifacts, or the traces.
266
+ - **Never deleted by a recipe.** `**Reset:**` puts the *product* back to a known
267
+ state; it never touches `reports/`. Pruning to ten is the tooling's job, and a
268
+ recipe that deletes reports destroys the record of the failure you were about to
269
+ investigate — including the one that is still open.
259
270
 
260
271
  ## Two gates: `enabled` and the recipe
261
272
 
@@ -289,6 +300,8 @@ Structural, never executed:
289
300
  once committed would be drift nobody catches later. The same check covers
290
301
  `.sassywares/session` whenever that directory exists — a committed session is a
291
302
  credential leak, not a heavy history.
303
+ - A surface named under `**Out of scope:**` has no section; one under
304
+ `**Uncovered:**` has a section ending `**Prove it:** none`.
292
305
  - The recipe has at least one `## ` section, every section has a `**Prove it:**`
293
306
  line whose value names a step (`step 3`) or is `none`, every numbered step has an
294
307
  `**Expect**`, and the file carries no secret-shaped strings. A `Prove it:` that