@sassywares/skills 0.8.0 → 0.10.0

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.
@@ -76,6 +76,14 @@ hooks:
76
76
  before_create: [tap2-version mode:auto]
77
77
  staging:
78
78
  before_create: []
79
+ push:
80
+ "*":
81
+ after_push: [] # commit.branch: current only
82
+ dogfood:
83
+ enabled: false # true = sassy-plan writes Mode: Auto QA rows
84
+ recipe: .sassywares/dogfood/recipe.md # the procedure
85
+ reports: .sassywares/dogfood/reports # run output, never committed
86
+ timeout: 900 # whole procedure, seconds
79
87
  ```
80
88
 
81
89
  | Key | Default | Meaning |
@@ -96,6 +104,11 @@ hooks:
96
104
  | `pr.merge` | `false` | `true` authorizes merging a single babysat PR |
97
105
  | `pr.delete_branch` | `false` | Delete the head branch once merged |
98
106
  | `hooks.pr.<pattern>.<point>` | `[]` | Project steps, keyed by the PR's head branch |
107
+ | `hooks.push.<pattern>.after_push` | `[]` | Project steps after a push, keyed by the pushed branch (see Hooks) |
108
+ | `dogfood.enabled` | `false` | `true` lets a plan write automated QA rows. Absent means `false` — manual QA, today's behavior |
109
+ | `dogfood.recipe` | `.sassywares/dogfood/recipe.md` | The stored procedure `sassy-dogfood` executes. Its `Prove it:` step is the verdict |
110
+ | `dogfood.reports` | `.sassywares/dogfood/reports` | Where a run writes its summary, step logs, and artifacts. Must be gitignored |
111
+ | `dogfood.timeout` | `900` | Wall-clock for one run. A timeout is a failure, never a hang |
99
112
 
100
113
  Paths are relative to the config's own directory, never to the cwd.
101
114
 
@@ -183,7 +196,8 @@ phase work once got committed straight onto `staging`.
183
196
 
184
197
  Under `current` the close-out skips the PR pipeline: `pr.*` and `hooks.pr.*`
185
198
  are ignored (`before_create`, `after_create`, `before_merge`, `after_merge` never
186
- run), and there is no babysit or merge. A non-fast-forward push stops the run.
199
+ run), and there is no babysit or merge. `hooks.push.after_push` is the one hook
200
+ that does run (see Hooks). A non-fast-forward push stops the run.
187
201
  Only this config value triggers it. A typed `branch:current` token, or the one
188
202
  skills forward to `sassy-commit`, does not suppress the PR.
189
203
 
@@ -287,6 +301,12 @@ targets. `hooks.pr.staging` means *PRs whose source is staging*.
287
301
  | `after_create` | `sassy-commit-push-pr` | the PR was just created — not on an update |
288
302
  | `before_merge` | `sassy-babysit` | the PR looks ready **and** this run will merge it |
289
303
  | `after_merge` | `sassy-babysit` | this run observed the PR merged |
304
+ | `hooks.push.after_push` | `sassy-ship` | right after a successful push under `commit.branch: current` |
305
+
306
+ `hooks.push` has the same shape and resolution as `hooks.pr`, but its key is the
307
+ pushed head branch and its only point is `after_push`. It runs only under
308
+ `commit.branch: current`, in a single `remote` repo, never after a rejected push
309
+ or in a workspace.
290
310
 
291
311
  ### Resolution
292
312
 
@@ -317,15 +337,20 @@ in review, and commented when it is deliberate.
317
337
  - **Names**: a skill the project owns, never one of ours.
318
338
  - **Order**: declared order, one worker each, sequential.
319
339
  - **Brief**: plan path, changed files, artifact paths, base, branch, commit hash,
320
- and the PR URL where one exists.
340
+ and the PR URL where one exists. `after_push` has no PR and also gets the
341
+ pushed hash and the upstream.
321
342
  - **Result**: `done`, `blocked`, or `needs-decision`; a decision comes back to the
322
343
  orchestrator, which holds the gate.
323
344
  - **Fail closed**: a missing skill or a `blocked` result stops the pipeline.
324
- - **Writes**: only `before_create` may also commit, because it runs after the
325
- pipeline's commit; every other point leaves the tree clean.
326
- - **Never**: push, open a PR, change `mode`, `branch`, or `merge`.
345
+ - **Writes**: `before_create` may also commit, because it runs after the
346
+ pipeline's commit. `after_push` may commit and push the checked-out head and
347
+ push tags, never forcing, opening or merging a PR, or touching another branch.
348
+ Every other point leaves the tree clean.
349
+ - **Never**: push (bar `after_push`, above), open a PR, change `mode`, `branch`,
350
+ or `merge`.
327
351
  - **Idempotent**: `after_merge` can be reached by a later run observing an
328
- already merged PR, and `before_create` can run again on a re-ship.
352
+ already merged PR, `before_create` can run again on a re-ship, and `after_push`
353
+ runs after an up-to-date push (nothing new) too.
329
354
  - **Per PR**: in a workspace fan-out the hooks run once per PR.
330
355
 
331
356
  ### When they do not fire
@@ -351,12 +376,44 @@ partial failures explicitly. Never collapse it into one status.
351
376
  fan-out means one `sassy-babysit` run per PR; merging a fan-out needs an explicit
352
377
  per-PR say-so, because one switch would merge N PRs nobody re-read.
353
378
 
379
+ ## Dogfood
380
+
381
+ Agent QA: a stored procedure that proves a change works in the running product,
382
+ not just in the diff. The block is a **pointer and a switch**, deliberately —
383
+ four keys, no commands.
384
+
385
+ ```yaml
386
+ dogfood:
387
+ enabled: true
388
+ recipe: .sassywares/dogfood/recipe.md
389
+ reports: .sassywares/dogfood/reports
390
+ timeout: 900
391
+ ```
392
+
393
+ Commands live in the recipe, not here. A copied command duplicates
394
+ `package.json` or a `Makefile` and drifts from it silently, and a single command
395
+ cannot express what makes dogfooding project-specific anyway: which order, which
396
+ prerequisites, and what counts as success between the steps. The recipe holds
397
+ the order, an `Expect` per step, and one `Prove it:` step whose exit code is the
398
+ verdict.
399
+
400
+ **Two gates.** An `Auto` QA row needs `enabled: true` **and** a recipe section
401
+ with a `Prove it:` step. One without the other keeps the row `Manual`, which is
402
+ how an unfinished recipe degrades safely instead of producing a green gate that
403
+ proves nothing.
404
+
405
+ `enabled` is written explicitly by `sassy-setup`, never inferred: no block means
406
+ `false`, which is today's behavior — every QA row is manual. The format, the
407
+ report layout, the verdict classes, and the lint are in
408
+ [`dogfood.md`](dogfood.md).
409
+
354
410
  ## Fail closed vs soft
355
411
 
356
412
  - **Fail closed** (stop, say why): an unusable `artifacts.*` or `git.*` value.
357
413
  A typo must not silently write docs into the wrong place.
358
- - **Soft** (fall back, say so): an unusable `commit.*` or `pr.*` value, and any
359
- `knowledge.read` path that is missing.
414
+ - **Soft** (fall back, say so): an unusable `commit.*`, `pr.*`, or `dogfood.*`
415
+ value, and any `knowledge.read` path that is missing. A `dogfood` failure
416
+ never fails a run: it only means QA rows stay manual.
360
417
 
361
418
  ## Validation rules
362
419
 
@@ -365,19 +422,26 @@ per-PR say-so, because one switch would merge N PRs nobody re-read.
365
422
  - `git.repo` is `workspace`, `none`, or one existing remote name.
366
423
  - `git.remote` is required when `git.repo: workspace`; forbidden otherwise.
367
424
  `git.mirror_branch` and `repos` are workspace-only too.
368
- - `hooks` is allowed only with the four keys under `hooks.pr`, each a list of
369
- skill names that resolve to `.agents/skills/<name>/SKILL.md`.
425
+ - `hooks` is allowed only with the four keys under `hooks.pr` and `after_push`
426
+ under `hooks.push`, each a list of skill names that resolve to
427
+ `.agents/skills/<name>/SKILL.md`.
370
428
  - `commit.branch` is `current` or `new`; `pr.*` are `true` or `false`. Write
371
429
  booleans as `true`/`false`, never `on`/`off` — bare `on`/`off` are YAML 1.1
372
430
  booleans and parse inconsistently.
373
431
  - `knowledge.read` is an inline list (`read: [a, b]`). A block list is not read
374
432
  by the config reader, so it would silently scout nothing.
433
+ - `dogfood.*` is exactly four keys; `enabled` is `true` or `false`, `timeout`
434
+ is a positive integer, and both paths are repo-relative and inside the
435
+ project. `reports` must be gitignored in a `repo` topology, and the recipe is
436
+ structurally linted — a section without a `Prove it:` line, a step without an
437
+ `Expect`, or a secret-shaped string is drift. See
438
+ [`dogfood.md`](dogfood.md).
375
439
  - An unknown key is an error, not a fallback: a typo parses, is ignored, and the
376
440
  run uses a default this project never chose.
377
441
 
378
442
  `scripts/detect.sh --check` enforces all of the above and reports each breach as
379
443
  a `drift:` line, exiting non-zero. When the suite is installed in project
380
- scope it also verifies the vendored pin offline: every `.agents/skills/sassy-*` folder is hashed with the `skills` CLI's own
444
+ scope it also verifies the vendored pin offline: every `.agents/skills/<name>` folder whose name is a suite skill (a name in the suite's roster, `assets/roster` in sassy-setup, not merely `sassy-`-prefixed) is hashed with the `skills` CLI's own
381
445
  definition and compared to `computedHash` in `skills-lock.json`, the lock is
382
446
  checked against the installed set in both directions, and git-tracked state of
383
447
  the lock is reported. A stale, hand-edited, or half-installed suite is drift
@@ -0,0 +1,209 @@
1
+ # Dogfood
2
+
3
+ Agent QA: a stored procedure that proves a change actually works in the running
4
+ product, not just in the diff. `sassy-dogfood` executes it, `sassy-plan` writes
5
+ automated QA rows against it, `sassy-work` gates on it, and `sassy-ship` refuses
6
+ to open a PR with it red.
7
+
8
+ The reference is deliberately tooling-agnostic. Nothing here names a browser, a
9
+ driver, or an MCP server: a recipe is steps and expectations, and whatever the
10
+ harness has connected at run time is what satisfies them.
11
+
12
+ ## Why a procedure, and not a command
13
+
14
+ A single command cannot say "seed first, boot the simulator, wait for the health
15
+ endpoint, then re-auth if the token is stale" — and that ordering is the entire
16
+ project-specific knowledge. It is also what every fresh agent otherwise
17
+ re-derives, differently, every time.
18
+
19
+ So the config stores a **pointer and a switch**, never commands. Commands live in
20
+ the recipe because only the recipe can express their order, their prerequisites,
21
+ and what counts as success between them. A command copied into the config would
22
+ duplicate `package.json` or a `Makefile` and drift from it silently.
23
+
24
+ ## Config
25
+
26
+ ```yaml
27
+ dogfood:
28
+ enabled: false # false = every QA row is Manual
29
+ recipe: .sassywares/dogfood/recipe.md # the procedure
30
+ reports: .sassywares/dogfood/reports # run logs and artifacts; never committed
31
+ timeout: 900 # whole procedure, seconds
32
+ ```
33
+
34
+ | Key | Default | Meaning |
35
+ |-----|---------|---------|
36
+ | `dogfood.enabled` | `false` | `true` lets `sassy-plan` write `Mode: Auto` QA rows. `false` forbids them. Absent means `false`: no block is today's behavior — manual QA |
37
+ | `dogfood.recipe` | `.sassywares/dogfood/recipe.md` | The procedure. Relative to the config. Point it at an existing runbook only if that runbook is already in this format |
38
+ | `dogfood.reports` | `.sassywares/dogfood/reports` | Where a run writes its summary, step logs, and artifacts. Must be gitignored |
39
+ | `dogfood.timeout` | `900` | Wall-clock for one whole run. A timeout is a failure, never a hang |
40
+
41
+ `enabled` is written explicitly by `sassy-setup`, never left to inference, so a
42
+ teammate reads the decision instead of guessing at it. `enabled: true` is not a
43
+ promise that a check exists: an unfinished recipe degrades to Manual rows
44
+ (see *Two gates*), which is why the switch alone can never make a gate lie.
45
+
46
+ ## Files
47
+
48
+ ```text
49
+ .sassywares/
50
+ ├── config.yaml
51
+ └── dogfood/
52
+ ├── recipe.md the procedure — committed, reviewed like code
53
+ ├── .gitignore one line: /reports/
54
+ └── reports/ run output — never committed
55
+ ```
56
+
57
+ The `/reports/` line is setup-owned. `--check` reports it missing as drift,
58
+ because a project that "helpfully" removes it commits screenshots by accident.
59
+
60
+ ## Recipe format
61
+
62
+ ```markdown
63
+ # Dogfood — <project>
64
+
65
+ **Never** production. Local or staging only.
66
+
67
+ **Set up once:** `bun install`; `docker compose up -d db`;
68
+ copy `.env.example` → `.env` and fill `DOGFOOD_USER`, `DOGFOOD_PASS`.
69
+
70
+ **Reset:** `bun run db:reset`; `rm -rf .sassywares/dogfood/reports/*`
71
+
72
+ ## catalog — a search returns matching products
73
+
74
+ 1. **Do** `bun run db:seed -- --fixtures catalog-small`
75
+ **Expect** `seeded 12 products`
76
+ 2. **Do** `bun dev &`, then poll `curl -fsS localhost:3000/healthz`
77
+ **Expect** `ok` within 60s
78
+ 3. **Do** open `/catalog` and sign in as `DOGFOOD_USER`
79
+ **Expect** the header shows that email; a 401 means the token env var is stale
80
+ 4. **Do** search "wool socks", open the first result
81
+ **Expect** the detail page titles match the search term
82
+ 5. **Do** `bun run e2e -- --grep catalog`
83
+ **Expect** exit 0
84
+
85
+ **Prove it:** step 5 — its exit code is the verdict.
86
+
87
+ ## auth — an expired session re-authenticates
88
+
89
+ 1. …
90
+ **Prove it:** step 2.
91
+ ```
92
+
93
+ **A section is one testable area** — `catalog`, `auth`, `mobile`, `api`. A QA row
94
+ names a section; it never restates a step.
95
+
96
+ **Every step has `Do` and `Expect`.** Without an `Expect` it is a suggestion, not
97
+ a check, and `--check` reports it as drift. `Do` is a command *or* an
98
+ instruction ("open `/catalog`, sign in as `DOGFOOD_USER`") — the instruction is
99
+ why the recipe outlives whatever tool the agent happens to have this quarter.
100
+
101
+ **One `Prove it:` per section**, and its exit code is the verdict. Steps before
102
+ it set up state and assert along the way; the prove step is the machine-readable
103
+ answer. A section without one has no verdict.
104
+
105
+ **Rules.**
106
+
107
+ - Ordered, numbered, **append-only**: add steps at the end of their section;
108
+ never reorder or renumber. A removal carries its one-line why in the commit.
109
+ - **Env var names only.** Never a credential, a token, or a session cookie. If a
110
+ step needs one, it names the variable and the project's own gitignored env file
111
+ holds the value.
112
+ - **Local or staging only.** A recipe that names production is a bug.
113
+ - **The happy path plus its checks.** Debris ("metro holds 8081") is a learning,
114
+ not a step: it goes to `artifacts.solutions` via `sassy-compound`, which
115
+ scouting already reads. This is what keeps a busy project's recipe at forty
116
+ lines instead of becoming a wiki.
117
+ - **No tool names.** Never "use Playwright" or "use the Chrome MCP". Say what to
118
+ do and what to see, and let the run discover how.
119
+
120
+ ## Reports
121
+
122
+ ```text
123
+ .sassywares/dogfood/reports/
124
+ └── 20260514-093107/ run id: YYYYMMDD-HHMMSS, sorts chronologically
125
+ ├── summary.md the only file read whole
126
+ ├── steps/
127
+ │ ├── catalog-01.log <section>-<NN> — a file name is a citation
128
+ │ └── catalog-05.log
129
+ └── artifacts/
130
+ ├── catalog-03-header.png
131
+ └── catalog-05-trace.zip
132
+ ```
133
+
134
+ ```markdown
135
+ # Dogfood run 20260514-093107
136
+
137
+ **status:** failed
138
+ **class:** code
139
+ **section:** catalog
140
+ **recipe:** .sassywares/dogfood/recipe.md @ a91f3c2
141
+ **started:** 09:31:07 **finished:** 09:33:41
142
+
143
+ | Step | Expect | Result |
144
+ |---|---|---|
145
+ | catalog-1 | `seeded 12 products` | pass |
146
+ | catalog-5 | exit 0 | **fail, exit 1** |
147
+
148
+ **Prove it:** catalog-5 → exit 1. 3 of 41 e2e specs failed.
149
+ **Artifacts:** `artifacts/catalog-05-report.json`, `artifacts/catalog-05-trace.zip`
150
+ **Next:** re-run from catalog-4, not catalog-1.
151
+ ```
152
+
153
+ `summary.md` is created at the start with `status: running` and finalized on exit.
154
+ A killed session therefore leaves an accurate breadcrumb, and the next one reads
155
+ one file to know where it stopped.
156
+
157
+ - **`status`** — `running` | `pass` | `failed`.
158
+ - **`class`** — `code` (a finding for the rework cycle) | `env` (the toolchain is
159
+ broken: a missing dependency, exit 75 or 127 — report and park, never loop) |
160
+ `recipe` (the procedure itself is stale: a renamed script, a dead URL, a step
161
+ that cannot be followed). `recipe` is the rot signal: the run proposes a
162
+ one-line diff and never quietly improvises around it.
163
+ - **One log per executed step**, capped head-and-tail (~64 KB) with a
164
+ `[truncated N lines]` marker, so a runaway loop cannot fill the disk.
165
+ - **Redaction happens before the write.** Every value of an env var the recipe
166
+ names is masked, plus a token-shape pass. A recipe that "stores creds" must not
167
+ leave them in a log an agent will later paste into a report.
168
+ - **The agent never reads a log whole.** It reads `summary.md`, then the last
169
+ ~600 characters of the failing step. An agent that reads a 40k-line log dies of
170
+ a missing semicolon.
171
+ - **Reports are pruned to the ten most recent** at the start of each run. Nothing
172
+ is committed here, so nothing must survive. The durable record is the QA row's
173
+ note — `catalog-5 exit 1, run 20260514-093107` — which never depends on a path
174
+ that will be deleted.
175
+ - **Never committed.** Not the logs, the artifacts, or the traces.
176
+
177
+ ## Two gates: `enabled` and the recipe
178
+
179
+ An Auto QA row needs **both** `dogfood.enabled: true` **and** a section whose
180
+ recipe carries a `Prove it:` step. One without the other means the row stays
181
+ `Manual`. That is how an unfinished recipe degrades safely instead of producing a
182
+ green gate that proves nothing — there is no third state in the config and no
183
+ lying switch.
184
+
185
+ ## Who writes what
186
+
187
+ | Artifact | Owner |
188
+ |----------|-------|
189
+ | `dogfood:` block in the config | `sassy-setup` — the only skill that writes the config |
190
+ | `.sassywares/dogfood/recipe.md` | `sassy-dogfood` (`mode:discover` authors and repairs it; a `mode:run` never edits it to pass) |
191
+ | `.sassywares/dogfood/.gitignore` | `sassy-setup`, at the skeleton; never removed |
192
+ | `reports/` | `sassy-dogfood`, always gitignored, pruned to ten |
193
+ | `Mode: Auto` QA rows | `sassy-plan`, a section name per row |
194
+ | Row results | `sassy-work`, from a passing report — never from an opinion |
195
+
196
+ ## `--check` lint
197
+
198
+ Structural, never executed:
199
+
200
+ - `enabled` is `true|false`; `timeout` is a positive integer; both paths are
201
+ relative and stay inside the project.
202
+ - `recipe` exists when `enabled` is `true` — absent, it is "created by the first
203
+ `sassy-dogfood` run", a note rather than drift.
204
+ - `reports` is gitignored in a `repo` topology (`git check-ignore`), since a run
205
+ once committed would be drift nobody catches later.
206
+ - The recipe has at least one `## ` section, every section has a `**Prove it:**`
207
+ line, every numbered step has an `**Expect**`, and the file carries no
208
+ secret-shaped strings.
209
+ - `dogfood.*` is a known key block; anything else in it is an unknown key.