@sassywares/skills 0.9.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.
package/CONCEPTS.md CHANGED
@@ -20,6 +20,16 @@ A skill that mostly coordinates. It reads compact results, writes briefs, and av
20
20
 
21
21
  `sassy-cycle` runs one unit of work through implement → review + simplify + validate (in parallel) → fix → verify. Simplifications are applied and verified but never block. Verify is a reviewer scoped to the fix, confirming each finding resolved and checking the fix for new ones; at most two fix passes, then anything open is `blocked`. Reviewer suggestions never block; they go to the gate. Given findings instead of a brief — requested changes, failed QA rows — it reworks existing work through the same fix → verify loop. It never commits. Work and LFG run it; debug fixes through work.
22
22
 
23
+ ## Dogfood
24
+
25
+ Agent QA: the project's own stored procedure for proving a change works in the running product, not merely in the diff. `sassy-dogfood` executes it, and the report's verdict is the only thing that settles an `Auto` QA row.
26
+
27
+ - **Recipe** — `.sassywares/dogfood/recipe.md`, committed and reviewed like code. Append-only sections of ordered steps, each with a `Do` and an `Expect`, ending in one `Prove it:` step whose exit code is the verdict. It names no tool: whatever the harness has connected at run time is what satisfies a step. The config points at it and never restates it — commands in the config would duplicate the manifest and could not express order.
28
+ - **Report** — `.sassywares/dogfood/reports/<run-id>/`, never committed and pruned to ten: `summary.md` (status, class, the per-step table, artifact paths), one log per executed step, and the artifacts. The durable record is the QA row's note — verdict and run id — never a path that will vanish.
29
+ - **Verdict classes** — `code` is a finding for the cycle, `env` means the toolchain is broken (report and park, never loop), `recipe` means the procedure itself is stale (propose a diff, never improvise around it).
30
+ - **Two gates** — an `Auto` row needs `dogfood.enabled: true` **and** a section with a `Prove it:` step. One without the other keeps the row `Manual`, which is how an unfinished recipe degrades safely instead of making a gate lie.
31
+ - **Frozen against the run** — a red run never edits the recipe or its expectations to pass. The cheapest way past a check must not be to weaken it.
32
+
23
33
  ## Gates
24
34
 
25
35
  A gate is a deliberate stop or pass/fail condition.
@@ -27,7 +37,7 @@ A gate is a deliberate stop or pass/fail condition.
27
37
  - **Fix gate** — `sassy-debug` presents the causal chain, fix, and risks before changing code.
28
38
  - **Code approval gate** — the user approves the code before committing or shipping. Always on for `sassy-work` and `sassy-lfg`.
29
39
  - **Ship review gate** — `sassy-ship` summarizes the close-out and waits in `mode:manual` (default); skipped only when the caller passed `mode:auto`.
30
- - **QA gate** — manual QA checklists, part of phase completion rather than a separate track: a phase turns `Done` only when the code is approved and every QA row passed. The user runs the rows; no agent ticks its own. It exists only when the plan document has QA tables; an in-context brief has none.
40
+ - **QA gate** — QA tables, part of phase completion rather than a separate track: a phase turns `Done` only when the code is approved and every QA row passed. A `Manual` row belongs to the user, and no agent ticks its own. An `Auto` row is settled by a passing dogfood report, never by an opinion, and ship will not persist behind one that is unproven. It exists only when the plan document has QA tables; an in-context brief has none.
31
41
 
32
42
  ## Branch and base
33
43
 
@@ -47,12 +57,12 @@ Three shared mode tokens: `mode:manual` (default) asks at the skill's gate; `mod
47
57
 
48
58
  Everything else is decided by the artifact, not a mode:
49
59
 
50
- - A plan document under `docs/plans/` drives phased execution and carries manual QA tables.
60
+ - A plan document under `docs/plans/` drives phased execution and carries QA tables whose rows are `Auto` or `Manual`.
51
61
  - An in-context brief drives one cycle and has no plan file and no QA tables.
52
62
 
53
63
  ## Plan
54
64
 
55
- A durable document under `docs/plans/` with intent, decisions, constraints, phase tracking, and per-phase manual QA tables.
65
+ A durable document under `docs/plans/` with intent, decisions, constraints, phase tracking, and per-phase QA tables.
56
66
 
57
67
  ## Goal
58
68
 
package/README.md CHANGED
@@ -12,6 +12,8 @@ It covers the whole path from a rough idea to a shipped PR, and from a bug repor
12
12
  - [Quick start](#quick-start)
13
13
  - [Skills](#skills)
14
14
  - [Project config](#project-config)
15
+ - [Dogfooding a project](#dogfooding-a-project)
16
+ - [Extending the pipeline](#extending-the-pipeline)
15
17
  - [Workflows](#workflows)
16
18
  - [From idea to ship](#from-idea-to-ship)
17
19
  - [From goal to done](#from-goal-to-done)
@@ -28,7 +30,7 @@ It covers the whole path from a rough idea to a shipped PR, and from a bug repor
28
30
 
29
31
  - **Lean.** Skills are indexes and workflows, not documentation dumps. Detail moves into `references/` only when it is conditionally needed.
30
32
  - **Explicit.** Every skill but `sassy-ship` runs only when you invoke it; ship may be started by the agent once you approve the work, and its review gate still waits. No silent background behavior.
31
- - **Controlled.** Code approval, manual QA, and ship review are visible gates that all run in sequence. Mode tokens are opt-in per skill: `mode:manual` (default) and `mode:auto` on `sassy-ship` and `sassy-compound`, plus `mode:return` on `sassy-review`, `sassy-simplify`, and `sassy-validate`; work, lfg, and debug take no mode; `sassy-goal` takes one mode per step of a goal (`write`, `next`, `check`, `close`).
33
+ - **Controlled.** Code approval, QA — manual and proved — and ship review are visible gates that all run in sequence. Mode tokens are opt-in per skill: `mode:manual` (default) and `mode:auto` on `sassy-ship` and `sassy-compound`, plus `mode:return` on `sassy-review`, `sassy-simplify`, and `sassy-validate`; work, lfg, and debug take no mode; `sassy-goal` takes one mode per step of a goal (`write`, `next`, `check`, `close`).
32
34
  - **Reliable.** Work runs through `sassy-cycle` with isolated subagents for implementation, review, simplification, validation, and verified fixes.
33
35
  - **Context-efficient.** Orchestrators coordinate; subagents do the heavy reading and return compact results.
34
36
  - **Never surprising.** Nothing is committed just because a step finished. Shipping is its own phase.
@@ -99,9 +101,12 @@ Debugging:
99
101
  | **`sassy-review`** | Reviews a diff, branch, PR, or files for bugs, security, project-rule conformance, and design-system conformance, then fixes the findings you pick. |
100
102
  | **`sassy-simplify`** | Finds behavior-preserving simplifications — reuse, quality, efficiency — then applies the ones you pick. |
101
103
  | **`sassy-validate`** | Checks whether work matches a plan or stated intent, then closes the gaps you pick. |
104
+ | **`sassy-dogfood`** | Uses the product the way a user does to prove a change actually works at runtime — runs the project's stored procedure, writes a report with a verdict, and in `mode:discover` builds or repairs that procedure from what really worked. Tooling-agnostic: it uses whatever your harness has connected and never installs a runner. |
102
105
 
103
106
  Each does one job and takes `mode:manual` (default: ask which to fix), `mode:auto` (fix without asking), or `mode:return` (report only). Fixes run through `sassy-cycle`, so they are verified. Inside work, lfg, and debug, the cycle runs all three agents in parallel itself.
104
107
 
108
+ `sassy-dogfood` takes its own modes instead: `run` (default), `discover`, and `check`.
109
+
105
110
  ### Shipping
106
111
 
107
112
  | Skill | What it does |
@@ -165,6 +170,11 @@ hooks:
165
170
  push: # only under commit.branch: current
166
171
  "*":
167
172
  after_push: [] # right after the push succeeds
173
+ dogfood: # agent QA: a stored procedure that proves a change runs
174
+ enabled: false # true lets a plan write Mode: Auto QA rows
175
+ recipe: .sassywares/dogfood/recipe.md # the procedure; never commands here
176
+ reports: .sassywares/dogfood/reports # run output; gitignored
177
+ timeout: 900 # whole procedure, seconds
168
178
  ```
169
179
 
170
180
  ### Extending the pipeline
@@ -183,6 +193,23 @@ Hooks run in declared order, one subagent each, and fail closed: a declared skil
183
193
 
184
194
  This is deliberately not a fork mechanism. A project skill that *adds* a step is a hook; one that *restates* our steps is a copy, and copies rot. Rules are not hooks either — those belong in `AGENTS.md`.
185
195
 
196
+ ### Dogfooding a project
197
+
198
+ Agent QA is opt-in and stores a **procedure**, not a command. One command can never say "seed first, boot the simulator, wait for the health endpoint, then re-auth if the token is stale" — and that ordering is the only genuinely project-specific part. So the config holds four keys and the work lives in a file:
199
+
200
+ ```text
201
+ .sassywares/
202
+ ├── config.yaml
203
+ └── dogfood/
204
+ ├── recipe.md committed — ordered steps, one `Prove it:` step per section
205
+ ├── .gitignore one line: /reports/
206
+ └── reports/ run logs and artifacts — never committed
207
+ ```
208
+
209
+ `recipe.md` is the project's, written by `sassy-dogfood mode:discover` from what actually worked, and reviewed like code: numbered steps you append to, each with a `Do` and an `Expect`, ending in a `Prove it:` step whose exit code is the verdict. It names no tool, so it outlives whichever browser driver or emulator your harness happens to have this quarter.
210
+
211
+ A QA row is `Auto` only when `dogfood.enabled` is `true` **and** the row names a recipe section with a `Prove it:` step. One without the other keeps the row `Manual`, which is how an unfinished recipe degrades safely instead of turning into a gate that proves nothing. Anything subjective, physical, irreversible, or unobservable stays a human's check — a false `Auto` pass is unrecoverable. The directory also makes a good fence: a run that trips on a step may not edit the recipe to pass, only propose the diff.
212
+
186
213
  Precedence is always explicit token > session instruction > config > skill default. `sassy-setup` writes the file from the tree it detects and keeps `pr.merge` off unless you say otherwise. The full schema, resolution chains, and the three topologies are in [`skills/sassy-setup/references/config.md`](skills/sassy-setup/references/config.md).
187
214
 
188
215
  In a `workspace` there is exactly one ignore file, and it is not at the root:
@@ -222,9 +249,9 @@ flowchart LR
222
249
  L -->|approve or mode:auto| M[Commit, PR, babysit]
223
250
  ```
224
251
 
225
- Option 1 produces a durable plan with phased slices and manual QA tables. Options 2 and 3 keep the whole job as one settled in-context brief and write no plan file.
252
+ Option 1 produces a durable plan with phased slices and QA tables. Options 2 and 3 keep the whole job as one settled in-context brief and write no plan file.
226
253
 
227
- `sassy-work` handles one phase and hands off the next. `sassy-lfg` drains the whole plan in one session. Both delegate to `sassy-cycle` and stop at one gate carrying code approval plus the manual QA checklist; nothing is `Done`, committed, or shipped until both pass. With an in-context brief there are no QA rows, so the gate is code approval alone.
254
+ `sassy-work` handles one phase and hands off the next. `sassy-lfg` drains the whole plan in one session. Both delegate to `sassy-cycle` and stop at one gate carrying code approval plus the QA checklist; nothing is `Done`, committed, or shipped until both pass. `Manual` rows are yours to run. `Auto` rows are proved before the gate by `sassy-dogfood`, and a failed one goes back through the cycle as a finding. With an in-context brief there are no QA rows, so the gate is code approval alone.
228
255
 
229
256
  Inside the cycle, every finding is fixed and then **verified**: a reviewer scoped to the fix confirms each finding resolved, and checks the fix itself for anything new. Whatever is still open gets a second fix pass; anything open after that comes back `blocked` rather than looping. Critical findings, warnings, and validator gaps are fixed automatically; the simplifier's findings are applied in the same pass but never block; the reviewer's suggestions are listed at the gate for you to pick. Changes you request at the gate and QA rows that fail go through the same loop as findings, then the gate comes back.
230
257
 
@@ -288,10 +315,11 @@ The fix gate offers four options:
288
315
  | Control | When it applies |
289
316
  |---|---|
290
317
  | Code approval | Always on for `sassy-work` and `sassy-lfg`. |
291
- | Manual QA | Part of the same gate, and only when the plan document has QA tables. The user runs the rows; a phase is `Done` only when both pass. |
318
+ | QA | Part of the same gate, and only when the plan document has QA tables. `Manual` rows are yours; `Auto` rows are settled by a `sassy-dogfood` report. A phase is `Done` only when both pass. |
319
+ | Dogfood | `Auto` rows only exist when `dogfood.enabled` is on and the row's recipe section has a `Prove it:` step. `sassy-ship` persists nothing behind an unproven row. |
292
320
  | Ship review | On in `mode:manual` (default), skipped by `mode:auto`. |
293
321
 
294
- The artifact decides QA: a plan document carries manual QA tables that gate phase completion, an in-context brief does not. Gates are deliberate stops; the only way past one is the user's approval. `mode:auto` is accepted only by `sassy-ship` and `sassy-compound`.
322
+ The artifact decides QA: a plan document carries QA tables that gate phase completion, an in-context brief does not. Gates are deliberate stops; the only way past one is the user's approval. `mode:auto` is accepted only by `sassy-ship` and `sassy-compound`.
295
323
 
296
324
  ## Branching
297
325
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -79,7 +79,7 @@ A finding is `resolved`, and a simplification `applied`, only when step 6's revi
79
79
  | Only fixes block | Simplifications are applied and verified but never make a run `blocked`; reviewer suggestions go to the caller's gate for the user to pick and are never applied automatically. |
80
80
  | Simplifier runs once | Only at step 3 (or never, on rework). Verify re-checks what was applied; it does not hunt for more. |
81
81
  | Never commit | This skill leaves everything uncommitted. Shipping is `sassy-ship`. |
82
- | Manual QA | Never mark QA rows `Done`. QA is confirmed by the user at the caller's gate; failing rows come back as findings. |
82
+ | QA stays the caller's | Never mark a QA row `Done`, `Manual` or `Auto`. A `Manual` row is confirmed by the user at the caller's gate and an `Auto` row by a passing dogfood report; failing rows come back as findings. |
83
83
 
84
84
  ## Context and token discipline
85
85
 
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: sassy-dogfood
3
+ description: >-
4
+ Use the product the way a user does, to prove a change actually works at
5
+ runtime rather than only in the diff. Runs the project's stored dogfood
6
+ procedure, writes a report with a verdict, and — in `mode:discover` — builds
7
+ or repairs that procedure from what really worked. Tooling-agnostic: it uses
8
+ whatever the harness has connected at run time and never installs a runner.
9
+ Use before a phase gate, when a plan row is `Mode: Auto`, or to set up
10
+ agent QA for a project.
11
+ argument-hint: "[section:<name>] [mode:run|discover|check]"
12
+ ---
13
+
14
+ # Sassy Dogfood
15
+
16
+ **Outcome:** a report with a verdict — `pass`, `failed` with the failing step and its output tail, or `env`/`recipe` explaining why the run could not judge the work — in `.sassywares/dogfood/reports/<run-id>/`, plus, in `mode:discover`, a `recipe.md` that a fresh agent can follow with no other context.
17
+
18
+ **A procedure is the artifact.** The project stores how to dogfood itself in `.sassywares/dogfood/recipe.md`: ordered steps, each with an observable expectation, ending in one `Prove it:` step whose exit code is the verdict. The config points at it; it never restates it. Read the `sassy-setup` skill's `references/dogfood.md` first — it owns the recipe format, the report layout, and the verdict classes, and this skill only executes them.
19
+
20
+ **Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. `dogfood.enabled`, `dogfood.recipe`, `dogfood.reports`, and `dogfood.timeout` are the only inputs. Precedence: explicit token > session instruction > config > skill default.
21
+
22
+ **No tooling.** This skill names no browser, driver, emulator, or MCP server, and it never installs one. A step says *what to do and what to see*; how the agent satisfies that is discovered at run time from what the harness already offers, and a plain command is often the better answer.
23
+
24
+ **Harness.** Loading another skill, dispatching an agent, and any command you hand the user follow the `sassy-setup` skill's `references/harness.md`. Read it once per run, before the first of those.
25
+
26
+ ## Modes
27
+
28
+ | Mode | What it does |
29
+ |------|--------------|
30
+ | `run` (default) | Preflight, execute the procedure from the recipe, write the report, classify, report back |
31
+ | `discover` | Build or repair the recipe: probe the repo, try the cheapest proof that could work, write down what actually worked |
32
+ | `check` | Lint the config and the recipe and print the last report's verdict; runs nothing, changes nothing |
33
+
34
+ `run` never edits the recipe. `discover` never gates anything: it produces a
35
+ recipe, and the next `run` is what proves it.
36
+
37
+ ## Steps — `mode:run`
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 — 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.
43
+ 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.
46
+ 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
+
48
+ ## Steps — `mode:discover`
49
+
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
+
56
+ ## Steps — `mode:check`
57
+
58
+ Run the `sassy-setup` skill's `scripts/detect.sh --root <path> --check` and report the `dogfood` and recipe lines verbatim; print the newest report's `status`, `class`, and timestamp, or that there is none. Write nothing.
59
+
60
+ ## Hard rules
61
+
62
+ | Rule | Requirement |
63
+ |------|-------------|
64
+ | The verdict is an exit code | A section's `Prove it:` step decides. Never a judgement, a screenshot someone liked, or "looks right". |
65
+ | 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`. |
66
+ | Never production | Local or staging only. A recipe step pointing at production is refused and reported, not run. |
67
+ | 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. |
68
+ | Reports stay local | Never commit `reports/`. Never paste a full log to a caller, a plan, or a PR. |
69
+ | No secrets, ever | Env var **names** only. Mask values before a log is written, and never echo one in a report. |
70
+ | 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
+ | 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
+ | 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. |
73
+ | 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
+
75
+ ## What dogfood is not
76
+
77
+ Not a test-authoring skill, and not a CI replacement: CI runs your suite on every push, dogfood runs *this* change against the running product once, and its job is to hand back a verdict the plan can trust. Not a harness either — it does not drive the agent, retry until green, or decide when work is done; `sassy-work` owns the gate and `sassy-cycle` owns the fix.
78
+
79
+ Not a reason to skip a human. Anything subjective, physical, irreversible, or unobservable stays a `Manual` QA row: a false `Auto` pass is unrecoverable, a manual row is merely slower.
@@ -9,7 +9,7 @@ argument-hint: "<plan path | brief> [branch:infer|current|new]"
9
9
 
10
10
  # Sassy LFG
11
11
 
12
- **Outcome:** every phase in the plan run through `sassy-cycle`, then one gate that carries the code approval and every phase's manual QA checklist, phases marked `Done` only when both pass, then `sassy-ship` closes it out (compound, handbook, commit, PR, babysit; under `commit.branch: current`, commit and push with no PR). A brief runs one cycle through the same gate, then ships.
12
+ **Outcome:** every phase in the plan run through `sassy-cycle`, then one gate that carries the code approval and every phase's QA checklist (`Manual` rows from the user, `Auto` rows from a `sassy-dogfood` report), phases marked `Done` only when both pass, then `sassy-ship` closes it out (compound, handbook, commit, PR, babysit; under `commit.branch: current`, commit and push with no PR). A brief runs one cycle through the same gate, then ships.
13
13
 
14
14
  **The orchestrator does not do work.** Read the plan, dispatch `sassy-cycle` per phase, then `sassy-ship`. Never edit application code. Keep the main context small — all heavy work happens in subagents.
15
15
 
@@ -28,13 +28,16 @@ If nothing is passed and no plan exists, run `sassy-plan` first and use what the
28
28
 
29
29
  ## QA gate
30
30
 
31
- Read the plan's `**QA:**` line and its per-phase QA tables. QA is manual and part of the completion gate: LFG builds every phase first, then presents one gate carrying code approval plus every phase's QA checklist. No phase turns `Done`, and nothing is committed or shipped, until both pass.
31
+ Read the plan's `**QA:**` line and its per-phase QA tables. QA is part of the completion gate: LFG builds every phase first, then presents one gate carrying code approval plus every phase's QA checklist. No phase turns `Done`, and nothing is committed or shipped, until both pass.
32
32
 
33
- - The user runs the checks. The agent never ticks a row it did not hear confirmed: a row becomes `Done` only on the user's explicit confirmation, with their note recorded.
33
+ Rows split by `Mode`:
34
+
35
+ - **`Manual` rows are the user's.** The agent never ticks one it did not hear confirmed: it becomes `Done` only on the user's explicit confirmation, with their note recorded.
36
+ - **`Auto` rows are proved, not opined.** Before the gate, run `sassy-dogfood` in `mode:run` for each row's section and take the verdict from its report; a row becomes `Done` only on a `pass`, with the run id in `Notes`.
34
37
  - A failed row is a finding. It goes through a rework cycle on its phase (step 5) and the gate is presented again; a row that fails again after its rework is `Blocked` with the reason and stops the run.
35
38
  - Rows nobody has reported on stay `Pending` and hold their phase `In progress`.
36
39
 
37
- A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA.
40
+ A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA. Never edit the dogfood recipe to make a red run green — propose the diff and ask.
38
41
 
39
42
  ## Steps
40
43
 
@@ -44,10 +47,10 @@ A brief has no QA table, so its gate is code approval alone. Never invent, enabl
44
47
  - Set the phase `In progress`, then load the `sassy-cycle` skill and follow it, with work brief = the phase's goal/work/"Done when", and intent reference = the plan path and phase.
45
48
  - On `Status: done`, leave the phase `In progress` — its QA rows are still owed, and only the gate closes them.
46
49
  - On `Status: blocked`, mark it `Blocked` and stop the run.
47
- 4. **The gate.** After the last phase, report: the plan path, each phase's status, what changed per phase, findings raised and resolved (with the fix passes each took), the simplifications applied, the validator/reviewer summaries, and the reviewers' suggestions as options the user may pick. Then give every phase's QA checklist verbatim — row ID, check, how to run it, what passing looks like — with unreported rows `Pending`. Ask for both decisions: code approval (or the changes wanted, including any suggestions picked) and the QA result per row. Wait. Do not commit.
50
+ 4. **The gate.** After the last phase, prove the `Auto` rows — run `sassy-dogfood` in `mode:run` for each row's section; a `failed` verdict is a finding for that phase's rework, and a `class: env` verdict stops the run with the toolchain named. Then report: the plan path, each phase's status, what changed per phase, findings raised and resolved (with the fix passes each took), the simplifications applied, the validator/reviewer summaries, and the reviewers' suggestions as options the user may pick. Then give every phase's QA checklist verbatim — row ID, check, `Mode`, and for `Manual` how to run it and what passing looks like, for `Auto` the dogfood verdict and run id — with unreported rows `Pending`. Ask for both decisions: code approval (or the changes wanted, including any suggestions picked) and the result per `Manual` row. Wait. Do not commit.
48
51
  5. **Resolve the gate.** Three outcomes:
49
- - **Code approved and every QA row passes** → mark the rows `Done` with the user's notes, mark the phases `Done`, then run the close-out below.
50
- - **Code approved, QA still pending** → tick nothing, mark nothing `Done`, commit nothing, ship nothing. Report which rows are outstanding and how to resume (invoke `sassy-lfg <plan>` in the harness's syntax), and stop.
52
+ - **Code approved and every QA row passes** → mark the rows `Done` (`Manual` with the user's notes, `Auto` with the verdict and run id), mark the phases `Done`, then run the close-out below.
53
+ - **Code approved, `Manual` rows still pending** → tick nothing, mark nothing `Done`, commit nothing, ship nothing. Report which rows are outstanding and how to resume (invoke `sassy-lfg <plan>` in the harness's syntax), and stop.
51
54
  - **Changes requested, or any QA row fails** → a rework cycle per affected phase: load `sassy-cycle` with that phase's requested changes and failing rows as its findings, and the plan path and phase as the intent reference. When every rework is `done`, present the gate again; a `blocked` rework marks its phase `Blocked` and stops the run. A QA row that fails again after its rework is `Blocked` with the reason and stops the run. Change requests have no cap — each one is the user's call.
52
55
  6. **Close-out.** On both gates passing, load the `sassy-ship` skill and follow it. Do only the close-out steps the user approves. Babysit options (`merge:on|off`, `delete-branch:on|off`) are forwarded through `sassy-ship` to `sassy-babysit`. The branch from step 2 already carries the work, so ship commits and opens the PR on it; ship never creates the branch. Under `commit.branch: current` ship commits and pushes the checked-out branch to its upstream and skips the PR, `hooks.pr.*`, babysit, and merge.
53
56
 
@@ -76,7 +79,7 @@ When the argument is not a plan path, the brief is the one phase:
76
79
  | Branch before code | Resolve the branch per the `sassy-setup` skill's `references/branching.md` before any phase runs, so no change lands on a base branch. |
77
80
  | Phases in plan order | Phases run one after another, in plan order. |
78
81
  | Done needs both gates | Mark a phase `Done` only when the user approves the code and every QA row for it is `Done`. |
79
- | QA rows follow the user | Tick a QA row `Done` only from the user's explicit confirmation; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
82
+ | QA rows follow the user | Tick a `Manual` QA row `Done` only from the user's explicit confirmation, and an `Auto` row only from a passing dogfood report; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
80
83
  | Send-backs are rework | Requested changes and failed QA rows go through `sassy-cycle` as findings — verified, two fix passes at most — never a direct edit. |
81
84
  | Gates before shipping | Nothing is committed or shipped until the code is approved and every QA row passes. Shipping is `sassy-ship`. |
82
85
  | No plan on the brief path | Use the in-context brief; never create or update a plan file. |
@@ -59,7 +59,7 @@ The user must pick explicitly. There is no default and no auto-selection. If no
59
59
 
60
60
  ### Option 1 — Write the plan
61
61
 
62
- Read `references/plan-format.md` and write the plan, including the per-phase manual QA tables that format defines. Then report the absolute path and offer the remaining two options, now run on the plan file:
62
+ Read `references/plan-format.md` and write the plan, including the per-phase QA tables that format defines, with each row's `Mode` decided the way that format says. Then report the absolute path and offer the remaining two options, now run on the plan file:
63
63
 
64
64
  ```text
65
65
  Plan written to <absolute path>. Pick one, or stop here:
@@ -79,7 +79,11 @@ Load the `sassy-lfg` skill the same way: the settled brief as the work brief, it
79
79
 
80
80
  ## QA
81
81
 
82
- The plan document carries manual QA tables per `references/plan-format.md`. Those rows gate phase completion: a phase is `Done` only when the code is approved and every row passed, with the user running the checks. The in-context brief has no QA table, so its gate is code approval alone. Omit QA tables only when the user explicitly asks to skip QA in plain language.
82
+ The plan document carries QA tables per `references/plan-format.md`. Those rows gate phase completion: a phase is `Done` only when the code is approved and every row passed. `Manual` rows are the user's to run; `Auto` rows are proved by `sassy-dogfood` and its report.
83
+
84
+ A row is `Auto` only when the project's `dogfood.enabled` is `true` **and** the row names a recipe section with a `Prove it:` step; otherwise it is `Manual`. That reference owns the list of checks that stay human — subjective, physical, irreversible, unobservable, unprovable — and on doubt the row is `Manual`. Never invent a section, a command, or a check to make a row look automatable: a false `Auto` pass is unrecoverable.
85
+
86
+ The in-context brief has no QA table, so its gate is code approval alone. Omit QA tables only when the user explicitly asks to skip QA in plain language.
83
87
 
84
88
  ## Resume
85
89
 
@@ -14,11 +14,29 @@ The plan has no open-questions section. Every branch the interview found is a de
14
14
  4. **Readable.** 3–8 phases for a typical feature. Merge only when a split leaves a phase with no meaningful thing to verify.
15
15
  5. **No dump sections.** Anything executable lives under a phase. No giant task list outside the phases.
16
16
 
17
- ## QA — manual, and part of the gate
17
+ ## QA — part of the gate
18
18
 
19
- Manual QA is the default: each phase gets a QA table with `Mode: Manual` fixed. Write each row so a person can run it without reading code — say what to set up, what to do, and what passing looks like. Suggest checks from the phase goal (happy path, edge, regression) but the user may edit them later.
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
- QA is a completion gate, not a separate track: a phase turns `Done` only when the code is approved and every QA row for that phase passes. The user runs the rows and the agent records them; an agent never ticks its own row.
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.
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
+
25
+ A row stays `Manual` when the answer is genuinely a human's:
26
+
27
+ | The check is… | Because |
28
+ |---|---|
29
+ | subjective | "does this look right", "does this feel intuitive", "is this the right product decision" |
30
+ | physical or sensory | audio, haptics, camera, mic, a real device, a push to a real phone |
31
+ | irreversible or third-party | payments, mail actually sent, shared or staging data touched |
32
+ | unobservable | no artifact an agent can inspect |
33
+ | unprovable | no check exists yet |
34
+
35
+ On doubt, `Manual`. A false `Auto` pass is unrecoverable; a `Manual` row is merely slower.
36
+
37
+ **An `Auto` check must have been seen failing once** — break the thing, watch the check fail, restore it — before the row is recorded. A check nobody has watched fail is not a check.
38
+
39
+ QA is a completion gate, not a separate track: a phase turns `Done` only when the code is approved and every QA row for that phase passes. `Manual` rows belong to the user, and the agent records what it hears. `Auto` rows are settled by a `sassy-dogfood` run and its report, never by an opinion.
22
40
 
23
41
  The user may ask in plain language to omit QA tables for this plan, in which case omit the tables and the `**QA:**` line entirely.
24
42
 
@@ -27,7 +45,9 @@ The user may ask in plain language to omit QA tables for this plan, in which cas
27
45
  ```markdown
28
46
  # <Plan title>
29
47
 
30
- **QA:** manual
48
+ **QA:** auto
49
+
50
+ (`auto` when at least one row in the plan is `Auto`, `manual` when none is. It is the source of truth for executors, so it never disagrees with the tables.)
31
51
 
32
52
  ## Intent
33
53
  One short paragraph: what we are building and why.
@@ -81,15 +101,15 @@ Omit empty layers. Do not put the next goal's work here.
81
101
 
82
102
  **Done when:** Plain-language acceptance for this phase only.
83
103
 
84
- #### QA — P1 (Manual)
104
+ #### QA — P1 (Auto)
85
105
 
86
106
  | ID | Check | Mode | Status | Notes |
87
107
  |----|-------|------|--------|-------|
88
- | P1-Q1 | … | Manual | Pending | |
89
- | P1-Q2 | … | Manual | Pending | |
108
+ | P1-Q1 | Searching "wool socks" returns matching products | Auto (catalog) | Pending | |
109
+ | P1-Q2 | The empty state reads well | Manual | Pending | |
90
110
 
91
111
  ### P2 — <short goal name>
92
112
  …
93
113
  ```
94
114
 
95
- Every phase has at least one QA row. Status values there are `Pending` | `Done` | `Blocked`: `Done` means the user ran that check and confirmed it passed, `Blocked` carries a note saying what failed, and anything unreported stays `Pending`. The `**QA:**` line near the title is the source of truth for executors.
115
+ Every phase has at least one QA row. Status values there are `Pending` | `Done` | `Blocked`: a `Manual` row is `Done` once the user ran that check and confirmed it passed, an `Auto` row is `Done` once a dogfood run passed and its run id is in `Notes`, `Blocked` carries a note saying what failed, and anything unreported stays `Pending`. The `**QA:**` line near the title is the source of truth for executors.
@@ -12,7 +12,7 @@ argument-hint: "[path] [mode:init|check]"
12
12
 
13
13
  # Sassy Setup
14
14
 
15
- **Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the skills installed in user or project scope and visible to the harness, the sassy-agents roster installed for the running harness, the snapshot tooling installed in `workspace` mode, and every file setup wrote committed — so the project is wired and the user is good to go in one run.
15
+ **Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the dogfood scaffold when agent QA was asked for, the skills installed in user or project scope and visible to the harness, the sassy-agents roster installed for the running harness, the snapshot tooling installed in `workspace` mode, and every file setup wrote committed — so the project is wired and the user is good to go in one run.
16
16
 
17
17
  **Read `references/config.md` first.** It is the schema and the resolution rules; this skill only decides and writes.
18
18
 
@@ -44,7 +44,10 @@ 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
+ - **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
48
  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.
49
+
50
+ **The dogfood scaffold, only when the answer was yes.** Create `.sassywares/dogfood/` holding `recipe.md` copied verbatim from `assets/dogfood-recipe.md`, and a `.gitignore` whose one line is `/reports/`. Never overwrite an existing recipe or ignore file — 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.
48
51
  5. **Wire the skills and the agents.** Both install the same way: if they are already there in either scope, report which and move on; if not, ask once where to install, recommending user scope.
49
52
 
50
53
  - **Skills.** The suite comes from upstream with the open `skills` CLI. Never copy skill files in by hand, never add the suite as a dependency.
@@ -76,21 +79,23 @@ A check run never edits the config and never rewrites the tree: it prints what `
76
79
  - **Tell the user to `/reload`** (or restart the harness). The skills and agents are invisible to the harness until it rescans.
77
80
 
78
81
  6. **Install the workspace tooling, `workspace` 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.
79
- 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`, 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.
82
+ 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 `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.
83
+
84
+ The `dogfood` half is structural and never runs the product: `enabled` and `timeout` are in range, the two paths are relative and stay inside the project, `reports` is gitignored in a `repo` topology, and the recipe has a `**Prove it:**` line per section with an `**Expect**` per step and no secret-shaped string. A recipe that does not exist yet is a note, not drift — unless `enabled` is `true`, which is the one combination that would let a planner write Auto rows against a check nobody has.
80
85
 
81
86
  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.
82
87
  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:
83
88
 
84
- `.sassywares/config.yaml`, `.sassywares/README.md`, `.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 .`.
89
+ `.sassywares/config.yaml`, `.sassywares/README.md`, `.sassywares/dogfood/recipe.md` and `.sassywares/dogfood/.gitignore` when step 4 scaffolded 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.
85
90
 
86
91
  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.
87
92
 
88
- **Nothing else** unless the user asks: a plan, a doc, a source file, or anything already dirty in the tree stays uncommitted, because setup's commit is not a place to launder work in progress. A user who says "commit my plan too" widens the list with the file they named — never with a sweep for it. On a `check` run this fires only when something setup owns is dirty: an uncommitted pin, a config edited since the last commit. Nothing dirty, nothing to commit.
93
+ **Nothing else** unless the user asks: a plan, a doc, a source file, or anything already dirty in the tree stays uncommitted, because setup's commit is not a place to launder work in progress. A user who says "commit my plan too" widens the list with the file they named — never with a sweep for it. On a `check` run this fires only when something setup owns is dirty: an uncommitted pin, a config edited since the last commit, a scaffold nobody committed. Nothing dirty, nothing to commit.
89
94
 
90
95
  - **`workspace`** — nothing to commit: the root is not a repo, and `references/workspace.md` forbids running the snapshot here. Say the root config and the pin land with the project's next snapshot.
91
96
  - **`none`** — nothing to commit, deliberately.
92
97
 
93
- 9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, where the skills are installed (scope) and where the agents are (scope and harness), or why either is not, the commit (hash and branch) or why there is none, and in `workspace` mode what was installed, with versions (`snapshot vN`, `workspace-git vN`), and the manifest the `workspace:*` aliases went into — naming it as created when there was no script surface to begin with. Remind: `/reload` so the harness rescans. Close with what is left over — at most dirt setup deliberately did not commit — and nothing else: a clean setup leaves the user good to go.
98
+ 9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, whether agent QA is on and — when it is — that the recipe is a skeleton until a `sassy-dogfood mode:discover` run writes it, where the skills are installed (scope) and where the agents are (scope and harness), or why either is not, the commit (hash and branch) or why there is none, and in `workspace` mode what was installed, with versions (`snapshot vN`, `workspace-git vN`), and the manifest the `workspace:*` aliases went into — naming it as created when there was no script surface to begin with. Remind: `/reload` so the harness rescans. Close with what is left over — at most dirt setup deliberately did not commit — and nothing else: a clean setup leaves the user good to go.
94
99
 
95
100
  ## Hard rules
96
101
 
@@ -105,10 +110,14 @@ A check run never edits the config and never rewrites the tree: it prints what `
105
110
  | Skills come from upstream | Install with `npx skills add`, `-g` for user scope; never hand-copy skill files or maintain the links yourself. |
106
111
  | Agents come from sassy-agents | Only the running harness's folder, as-is: linked by `install.sh` (user scope) or copied verbatim (project scope). Never edit, merge, or overwrite a differing agent file without asking. |
107
112
  | Never edit the manifest | No dependencies, no `postinstall`, no `skills:*` scripts. The one exception is step 6's `workspace:*` aliases in `workspace` topology: appended or corrected, never removed, and nothing else in the file touched. Setup installs the suite; the user or project decides how it updates. |
108
- | Write boundary | Only `.sassywares/`, the skills and agent files step 5 installed in the scope the user chose, `skills-lock.json` (project scope), and one `.gitignore` line — and the project-scope part of that list is step 8's commit. Never `package.json` outside step 6's `workspace:*` aliases, never a root `.gitignore` in a workspace. Workspace git helpers land in `.sassywares/workspace/`, never in a project's `bin/`. |
113
+ | Write boundary | Only `.sassywares/` (the config, the setup README, and the dogfood scaffold), the skills and agent files step 5 installed in the scope the user chose, `skills-lock.json` (project scope), and one `.gitignore` line — and the project-scope part of that list is step 8's commit. Never `package.json` outside step 6's `workspace:*` aliases, never a root `.gitignore` in a workspace. Workspace git helpers land in `.sassywares/workspace/`, never in a project's `bin/`. |
109
114
  | Detect, don't guess | An unknown base branch stays unknown and gets asked about. A probed value is reported as probed. |
110
115
  | Comments are part of the file | Every key keeps its description and allowed values. A stripped config is an incomplete config. |
111
116
  | Hooks are named, not written | Setup records hook skill names. Creating those skills is the project's work. |
117
+ | Dogfood is a pointer | The block names a recipe, a reports path, a timeout, and whether Auto rows are allowed — four keys. Never a command and never a tool: a copied command duplicates the manifest and cannot express step order. |
118
+ | The recipe is the project's | Setup scaffolds the skeleton and stops. Authoring or "fixing" a procedure is `sassy-dogfood mode:discover`'s job, and a run may never edit the recipe to make its own failure pass. |
119
+ | Reports never ship | `.sassywares/dogfood/reports/` is gitignored by one setup-owned line, `/reports/`. Never remove it, never add anything from it to the commit. |
120
+ | No secrets in setup's writes | Env var names only, in the config and in the skeleton. A credential never lands in a file setup commits. |
112
121
  | Repair is `check` | Run against an existing config, setup reports drift — it does not rewrite the file without approval. |
113
122
 
114
123
  ## What setup is not
@@ -0,0 +1,29 @@
1
+ # Dogfood — <project>
2
+
3
+ **Never** production. Local or staging only.
4
+
5
+ **Set up once:** <install, services to start, env files to copy; name variables,
6
+ never values>
7
+
8
+ **Reset:** <back to a known state>
9
+
10
+ <!--
11
+ Incomplete on purpose. sassy-setup writes this skeleton so the shape is visible;
12
+ `sassy-dogfood mode:discover` fills it by trying the product once and writing down
13
+ what actually worked. Until a section has a **Prove it:** step, every QA row stays
14
+ Manual.
15
+
16
+ Rules: steps are ordered and append-only; every step has **Do** and **Expect**;
17
+ one **Prove it:** per section and its exit code is the verdict; env var names
18
+ only; no tool names. Schema: sassy-setup/references/dogfood.md
19
+ -->
20
+
21
+ ## <section> — <one line: what this proves>
22
+
23
+ 1. **Do** <command or instruction>
24
+ **Expect** <observable, checkable result>
25
+
26
+ 2. **Do** <the proving command>
27
+ **Expect** exit 0
28
+
29
+ **Prove it:** step 2 — its exit code is the verdict.
@@ -4,6 +4,7 @@ sassy-commit-push-pr
4
4
  sassy-compound
5
5
  sassy-cycle
6
6
  sassy-debug
7
+ sassy-dogfood
7
8
  sassy-goal
8
9
  sassy-handbook
9
10
  sassy-handoff
@@ -79,6 +79,11 @@ hooks:
79
79
  push:
80
80
  "*":
81
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
82
87
  ```
83
88
 
84
89
  | Key | Default | Meaning |
@@ -100,6 +105,10 @@ hooks:
100
105
  | `pr.delete_branch` | `false` | Delete the head branch once merged |
101
106
  | `hooks.pr.<pattern>.<point>` | `[]` | Project steps, keyed by the PR's head branch |
102
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 |
103
112
 
104
113
  Paths are relative to the config's own directory, never to the cwd.
105
114
 
@@ -367,12 +376,44 @@ partial failures explicitly. Never collapse it into one status.
367
376
  fan-out means one `sassy-babysit` run per PR; merging a fan-out needs an explicit
368
377
  per-PR say-so, because one switch would merge N PRs nobody re-read.
369
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
+
370
410
  ## Fail closed vs soft
371
411
 
372
412
  - **Fail closed** (stop, say why): an unusable `artifacts.*` or `git.*` value.
373
413
  A typo must not silently write docs into the wrong place.
374
- - **Soft** (fall back, say so): an unusable `commit.*` or `pr.*` value, and any
375
- `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.
376
417
 
377
418
  ## Validation rules
378
419
 
@@ -389,6 +430,12 @@ per-PR say-so, because one switch would merge N PRs nobody re-read.
389
430
  booleans and parse inconsistently.
390
431
  - `knowledge.read` is an inline list (`read: [a, b]`). A block list is not read
391
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).
392
439
  - An unknown key is an error, not a fallback: a typo parses, is ignored, and the
393
440
  run uses a default this project never chose.
394
441
 
@@ -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.
@@ -182,6 +182,46 @@ list_items() {
182
182
  | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//; s/^"//; s/"$//' | grep -v '^$' || true
183
183
  }
184
184
 
185
+ # recipe_lint FILE — structural lint for a dogfood procedure. Prints one message
186
+ # per breach; the caller turns each into a drift line. Nothing is executed: a
187
+ # check run validates the shape of a procedure, it never runs the product.
188
+ recipe_lint() {
189
+ awk '
190
+ BEGIN { pending = 0; sec = ""; sname = ""; prove = 0; step = ""; incomment = 0 }
191
+ index($0, "<!--") { incomment = 1 }
192
+ incomment {
193
+ if (index($0, "-->")) incomment = 0
194
+ next
195
+ }
196
+ index($0, "**Prove it:**") { prove = 1; next }
197
+ /^## / {
198
+ if (sec != "" && !prove)
199
+ printf "section \"%s\" has no **Prove it:** line — it has no verdict\n", sname
200
+ if (pending)
201
+ printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
202
+ pending = 0; prove = 0
203
+ sec = $0; sub(/^## +/, "", sec)
204
+ split(sec, parts, /[ \t]+/); sname = parts[1]
205
+ next
206
+ }
207
+ /^[0-9]+\. / && index($0, "**Do**") {
208
+ if (pending)
209
+ printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
210
+ step = $0; sub(/\..*$/, "", step)
211
+ pending = 1; next
212
+ }
213
+ index($0, "**Expect**") { pending = 0; next }
214
+ END {
215
+ if (pending)
216
+ printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
217
+ if (sec != "" && !prove)
218
+ printf "section \"%s\" has no **Prove it:** line — it has no verdict\n", sname
219
+ if (sec == "")
220
+ printf "has no \"## <section>\" heading — there is nothing to prove\n"
221
+ }
222
+ ' "$1"
223
+ }
224
+
185
225
  # map_match SECTION HEAD — exact key, then the longest matching family, then "*".
186
226
  # base_map uses it, and hooks use the same rule, so "which pattern applies" has
187
227
  # exactly one answer in the whole config.
@@ -369,6 +409,7 @@ if (( CHECK )); then
369
409
  repos.*) ;;
370
410
  commit.branch) ;;
371
411
  pr.babysit|pr.merge|pr.delete_branch) ;;
412
+ dogfood.enabled|dogfood.recipe|dogfood.reports|dogfood.timeout) ;;
372
413
  hooks.*) ;; # shape checked with the hooks
373
414
  *) bad "unknown key '$key' — it is ignored, so the run uses the default" ;;
374
415
  esac
@@ -650,6 +691,73 @@ if (( CHECK )); then
650
691
  esac
651
692
  fi
652
693
 
694
+ # Dogfood is a pointer and a switch, never commands: the recipe holds the
695
+ # procedure and its `Prove it:` step is the verdict. Everything below is
696
+ # structural. A check run never runs the product — a validator that boots an
697
+ # app is a validator nobody runs.
698
+ dg_enabled="$(block_value dogfood enabled || true)"
699
+ dg_recipe="$(block_value dogfood recipe || true)"
700
+ dg_reports="$(block_value dogfood reports || true)"
701
+ dg_timeout="$(block_value dogfood timeout || true)"
702
+ case "$dg_enabled" in
703
+ "") ;;
704
+ true|false) note " dogfood.enabled: $dg_enabled" ;;
705
+ *) bad "dogfood.enabled '$dg_enabled' must be true|false" ;;
706
+ esac
707
+ for dkey in recipe reports; do
708
+ case "$dkey" in
709
+ recipe) dpath="$dg_recipe" ;;
710
+ *) dpath="$dg_reports" ;;
711
+ esac
712
+ [[ -n "$dpath" ]] || continue
713
+ case "$dpath" in
714
+ /*|~*) bad "dogfood.$dkey '$dpath' is not relative to the config" ;;
715
+ .|./) bad "dogfood.$dkey is the project root itself" ;;
716
+ *) escapes_root "$dpath" && bad "dogfood.$dkey '$dpath' walks outside the project" ;;
717
+ esac
718
+ done
719
+ if [[ -n "$dg_timeout" ]]; then
720
+ case "$dg_timeout" in
721
+ *[!0-9]*) bad "dogfood.timeout '$dg_timeout' is not a positive integer" ;;
722
+ 0) bad "dogfood.timeout is 0 — a procedure that can never finish" ;;
723
+ *) note " dogfood.timeout: ${dg_timeout}s" ;;
724
+ esac
725
+ fi
726
+
727
+ # Reports are logs and screenshots. A project that drops the ignore line
728
+ # commits them, and nobody notices until the history is heavy. Probed with a
729
+ # child path: `/reports/` names a directory, so git only matches it when the
730
+ # probe goes through the directory — and the directory may not exist yet.
731
+ if [[ "$TOPOLOGY" == "repo" && -n "$dg_reports" ]]; then
732
+ if git -C "$ROOT" check-ignore -q -- "$dg_reports/run.log" 2>/dev/null; then
733
+ note " dogfood.reports is gitignored"
734
+ else
735
+ bad "dogfood.reports '$dg_reports' is not gitignored — a run's logs and screenshots would be committed"
736
+ fi
737
+ fi
738
+
739
+ if [[ -n "$dg_recipe" ]]; then
740
+ if [[ ! -f "$ROOT/$dg_recipe" ]]; then
741
+ if [[ "$dg_enabled" == "true" ]]; then
742
+ # Enabled with no procedure is the one state that lies: a planner would
743
+ # write Auto rows against a check that does not exist.
744
+ bad "dogfood.recipe '$dg_recipe' does not exist — run sassy-dogfood mode:discover"
745
+ else
746
+ note " dogfood.recipe: $dg_recipe (written by the first sassy-dogfood run)"
747
+ fi
748
+ else
749
+ while IFS= read -r msg; do
750
+ [[ -n "$msg" ]] || continue
751
+ bad "dogfood.recipe $msg"
752
+ done < <(recipe_lint "$ROOT/$dg_recipe")
753
+ while IFS= read -r line0; do
754
+ [[ -n "$line0" ]] || continue
755
+ bad "dogfood.recipe has a secret-shaped string at line $line0 — env var names only, never a value"
756
+ done < <(grep -nE 'sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10,}' "$ROOT/$dg_recipe" 2>/dev/null | cut -d: -f1)
757
+ note " dogfood.recipe: $dg_recipe"
758
+ fi
759
+ fi
760
+
653
761
  # Hooks that cannot fire are a note, not drift: the config is legal, the step
654
762
  # just never runs. hooks.push needs `current` in a single remote repo.
655
763
  if [[ "$val" == "current" ]]; then
@@ -1052,3 +1160,18 @@ cat <<'EOF'
1052
1160
  # "*":
1053
1161
  # after_push: []
1054
1162
  EOF
1163
+ cat <<'EOF'
1164
+
1165
+ # --- Dogfood --------------------------------------------------------------
1166
+ # Agent QA: a stored procedure that proves a change works in the running
1167
+ # product. This block only points at it — commands live in the recipe, because
1168
+ # a copy here would duplicate the manifest and could not express step order.
1169
+ # The recipe ends each section in a `Prove it:` step whose exit code is the
1170
+ # verdict. enabled: true lets a plan write Mode: Auto QA rows, but only for a
1171
+ # section that actually has one.
1172
+ dogfood:
1173
+ EOF
1174
+ kv enabled false 42 '# true = plan writes Auto QA rows; false = all Manual'
1175
+ kv recipe .sassywares/dogfood/recipe.md 42 '# the procedure; sassy-dogfood writes it'
1176
+ kv reports .sassywares/dogfood/reports 42 '# run output; must stay gitignored'
1177
+ kv timeout 900 42 '# seconds for the whole procedure'
@@ -32,6 +32,8 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
32
32
  2. **Compound (conditional).** If the work produced a qualifying learning, dispatch a `worker` whose task is: *load the `sassy-compound` skill and follow it with `mode:auto`* — with a compact learnings brief (the solved problems, root causes, and solutions taken from the cycle results, not from re-reading the tree). It always gets `mode:auto` because ship's own gate already covered the approval. Skip cleanly when nothing qualifies, and skip entirely when `knowledge.write` is `false`.
33
33
  3. **Handbook (conditional).** If the feature is self-contained and independent enough that a teammate would benefit from a handover, dispatch a `worker` whose task is: *load the `sassy-handbook` skill and follow it* — with the plan path and topic. The worker reads the tree itself. Skip for small or tightly-coupled changes.
34
34
  4. **Commit or snapshot.** After the review gate — never before it — the docs and any remaining code become durable.
35
+
36
+ **Before anything is persisted, check the plan's `Auto` QA rows.** If the plan carries any and one is not `Done` from a passing `sassy-dogfood` report, stop here: report the outstanding rows, the report path, and what it would take to prove them. Ship never commits, pushes, or opens a PR behind an unproven automated row, and never runs the recipe itself — proving is `sassy-work`'s step, and re-running it here would let a red row reach a commit by being retried instead of fixed. A brief and a plan with only `Manual` rows skip this entirely.
35
37
  - **`git.repo` is a remote.** Dispatch a `worker`: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the plan, any new solutions docs, the concepts file, `AGENTS.md`, and any handbook just written — resolved from `artifacts.*`, never hardcoded. The branch already exists: `sassy-work` or `sassy-lfg` cut it before the first change, so the docs belong on it with the phase commits. It returns the hash and subject.
36
38
 
37
39
  **Ship never creates the branch.** Outside `commit.branch: current`, a head on a base branch with unpublished commits is a mis-run — `sassy-work` was supposed to cut before touching code. Ask the commit worker to return `state` and `unpublished` from the `sassy-setup` skill's `scripts/detect.sh --branch`, and stop and ask if they show a base with a non-zero count. Never relocate commits silently, never push to the base. Under `commit.branch: current` this check does not fire: unpublished commits on the head are simply pushed along with the close-out commit.
@@ -52,6 +54,7 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
52
54
 
53
55
  | Rule | Requirement |
54
56
  |------|-------------|
57
+ | Unproven rows stop the close-out | A plan's `Auto` QA row that is not `Done` from a passing dogfood report stops ship before anything is persisted. Ship never runs the recipe itself. |
55
58
  | Review gate | `mode:manual` (default) presents the summary and waits before any write, commit, push, or PR. |
56
59
  | No review | `mode:auto` runs the close-out with no approval gate. Never toggled by the skill. |
57
60
  | All-or-nothing gate | In `mode:manual`, nothing is written until the gate is answered. |
@@ -10,7 +10,7 @@ argument-hint: "<plan path | brief> [phase:<n>] [branch:infer|current|new]"
10
10
 
11
11
  # Sassy Work
12
12
 
13
- **Outcome:** one phase run through `sassy-cycle`, findings fixed, then a single gate that carries both the code approval and the phase's manual QA checklist, marked `Done` only when both pass, committed via `sassy-commit`; then a handoff that continues the **next** phase in a fresh session, or a `sassy-ship` close-out if this was the last phase.
13
+ **Outcome:** one phase run through `sassy-cycle`, findings fixed, then a single gate that carries both the code approval and the phase's QA checklist (`Manual` rows from the user, `Auto` rows from a `sassy-dogfood` report), marked `Done` only when both pass, committed via `sassy-commit`; then a handoff that continues the **next** phase in a fresh session, or a `sassy-ship` close-out if this was the last phase.
14
14
 
15
15
  **Brief input** runs one cycle, presents the code approval gate, commits, and **stops before shipping**.
16
16
 
@@ -31,13 +31,15 @@ If a plan path is given but the file does not exist, run `sassy-plan` first and
31
31
 
32
32
  ## QA gate
33
33
 
34
- Read the plan's `**QA:**` line and its per-phase QA table. QA is manual and it is part of the phase gate, not a separate track: a phase turns `Done` only when the code is approved **and** every QA row for that phase has passed.
34
+ Read the plan's `**QA:**` line and its per-phase QA table. QA is part of the phase gate, not a separate track: a phase turns `Done` only when the code is approved **and** every QA row for that phase has passed.
35
35
 
36
- - The user runs the checks. The agent never ticks a row it did not hear confirmed: a row becomes `Done` only on the user's explicit confirmation in this conversation, with their note recorded.
37
- - A row the user reports failing is a finding. It goes through a rework cycle (step 6) and the gate is presented again; a row that fails again after its rework is `Blocked` with the reason.
38
- - Rows nobody has reported on stay `Pending`, and they keep the phase `In progress`. Never infer, batch-assume, or self-certify a pass.
36
+ Rows split by `Mode`, and the split decides who can settle them:
39
37
 
40
- A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA.
38
+ - **`Manual` rows are the user's.** The agent never ticks one it did not hear confirmed: it becomes `Done` only on the user's explicit confirmation in this conversation, with their note recorded.
39
+ - **`Auto` rows are proved, not opined.** Step 4 runs `sassy-dogfood` for the phase's sections before the gate, and a row becomes `Done` only from a report whose verdict is `pass`, with the run id in `Notes`. A failed run is a finding into a rework cycle; the row never becomes `Done` because the agent judged it fine.
40
+ - A row failing again after its rework is `Blocked` with the reason. Rows nobody has reported on stay `Pending`, and they keep the phase `In progress`. Never infer, batch-assume, or self-certify a pass.
41
+
42
+ A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA. A plan's `Auto` rows exist because the project enabled them: `dogfood.enabled` and a recipe section with a `Prove it:` step, per the `sassy-setup` skill's `references/dogfood.md`. Never edit the recipe to turn a red run green — propose the diff and ask.
41
43
 
42
44
  ## Phase gate
43
45
 
@@ -53,12 +55,14 @@ Always gate before committing. The cycle has already fixed and verified its find
53
55
  - work brief = the phase's goal, work items, and "Done when" criteria
54
56
  - intent reference = the plan path and phase
55
57
  4. **Evaluate the phase.** On `Status: done`, the code is ready for the gate, but leave the phase `In progress` — both gates must pass before it closes. On `Status: blocked`, set it `Blocked` in the Phase tracking table and stop; a blocked phase is a real outcome and needs no approval.
56
- 5. **Present the phase gate.** Report the phase, what changed, findings raised and resolved (with the fix passes it took), the simplifications applied, the validator grade, the reviewer summary, and the reviewer's suggestions as options the user may pick. Then give the QA checklist verbatim: each row's ID, check, how to run it, and what passing looks like, with unreported rows `Pending`. Ask for both decisions — code approval (or the changes wanted, including any suggestions picked) and the QA result per row. Wait.
58
+
59
+ **Then prove the `Auto` rows.** If the phase has any, run the `sassy-dogfood` skill in `mode:run` with each row's section named, before the gate and never after it. Record what each report said. A `failed` verdict is a finding, so the phase goes back through step 3's cycle with the failing step and the report's log tail as its findings, and this step runs again; a `class: env` verdict is not a finding — report that the toolchain is broken, leave the phase `In progress`, and stop. An `Auto` row with no report is `Pending`, never `Done`.
60
+ 5. **Present the phase gate.** Report the phase, what changed, findings raised and resolved (with the fix passes it took), the simplifications applied, the validator grade, the reviewer summary, and the reviewer's suggestions as options the user may pick. Then give the QA checklist verbatim: each row's ID, check, `Mode`, and — for `Manual` — how to run it and what passing looks like, and for `Auto` — the dogfood verdict and run id, with unreported rows `Pending`. Ask for both decisions — code approval (or the changes wanted, including any suggestions picked) and the result per `Manual` row. Wait.
57
61
  6. **Resolve the gate.** Three outcomes, nothing in between:
58
62
  - **Code approved and every QA row passes** → go to step 7.
59
- - **Code approved, QA still pending** → record that code is approved but leave the phase `In progress`, tick nothing, commit nothing, hand off nothing, and report that the phase is waiting on manual QA plus the command that resumes it.
60
- - **Changes requested, or any QA row fails** → a rework cycle: load `sassy-cycle` with the requested changes and the failing rows as its findings, and the plan path and phase as the intent reference. On `done`, present the gate again from step 5; on `blocked`, mark the phase `Blocked` and stop. A QA row that fails again after its rework is `Blocked` with the reason and stops the phase. Change requests have no cap — each one is the user's call.
61
- 7. **Commit the phase.** On both gates passing, first mark the phase's QA rows `Done` with the user's notes and the phase `Done` in the Phase tracking table, then persist according to `git.repo`:
63
+ - **Code approved, `Manual` rows still pending** → record that code is approved but leave the phase `In progress`, tick nothing, commit nothing, hand off nothing, and report that the phase is waiting on manual QA plus the command that resumes it.
64
+ - **Changes requested, or any row fails** → a rework cycle: load `sassy-cycle` with the requested changes and the failing rows as its findings, and the plan path and phase as the intent reference. On `done`, re-prove the `Auto` rows (step 4) and present the gate again from step 5; on `blocked`, mark the phase `Blocked` and stop. A QA row that fails again after its rework is `Blocked` with the reason and stops the phase. Change requests have no cap — each one is the user's call.
65
+ 7. **Commit the phase.** On both gates passing, first mark the phase's QA rows `Done` — `Manual` rows with the user's notes, `Auto` rows with the verdict and run id from the report — and the phase `Done` in the Phase tracking table, then persist according to `git.repo`:
62
66
 
63
67
  - **A remote** — dispatch a `worker` whose task is: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the phase's code changes, the QA table results, and the now-updated Phase tracking table. It returns the hash and subject. The branch already exists: step 2 cut it, so committing on it is the point of `branch:current` here.
64
68
  - **`workspace`** — dispatch a `worker` per affected repo to commit that repo's code on the run's shared branch, then run `.sassywares/workspace/snapshot` for the plan, QA results, and docs at the root. The gate's approval is the commit approval; the snapshot runs right after it and is never skipped. A missing or outdated `.sassywares/workspace/snapshot` is a blocker — say to run `sassy-setup`.
@@ -92,7 +96,7 @@ When the argument is not a plan path, it is one settled brief:
92
96
  | Gate before commit and handoff | Do not commit, hand off, or close out until the user approves the code and the phase QA rows pass. |
93
97
  | Commit per phase | Commit the phase, its QA results, and the plan update via `sassy-commit` before handoff or close-out. |
94
98
  | Done needs both gates | Mark a phase `Done` only when the user approves the code and every QA row for that phase is `Done`, never before. |
95
- | QA rows follow the user | Tick a QA row `Done` only from the user's explicit confirmation; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
99
+ | QA rows follow their mode | Tick a `Manual` row `Done` only from the user's explicit confirmation, and an `Auto` row only from a passing dogfood report; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
96
100
  | Send-backs are rework | Requested changes and failed QA rows go through `sassy-cycle` as findings — verified, two fix passes at most — never a direct edit. |
97
101
  | No shipping on the brief path | The brief path commits and stops. Shipping is `sassy-ship` or `sassy-lfg`. |
98
102