@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 +13 -3
- package/README.md +33 -5
- package/package.json +1 -1
- package/skills/sassy-cycle/SKILL.md +1 -1
- package/skills/sassy-dogfood/SKILL.md +79 -0
- package/skills/sassy-lfg/SKILL.md +11 -8
- package/skills/sassy-plan/SKILL.md +6 -2
- package/skills/sassy-plan/references/plan-format.md +28 -8
- package/skills/sassy-setup/SKILL.md +15 -6
- package/skills/sassy-setup/assets/dogfood-recipe.md +29 -0
- package/skills/sassy-setup/assets/roster +1 -0
- package/skills/sassy-setup/references/config.md +49 -2
- package/skills/sassy-setup/references/dogfood.md +209 -0
- package/skills/sassy-setup/scripts/detect.sh +123 -0
- package/skills/sassy-ship/SKILL.md +3 -0
- package/skills/sassy-work/SKILL.md +15 -11
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** —
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
|
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
|
|
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
|
@@ -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
|
-
|
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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 —
|
|
17
|
+
## QA — part of the gate
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Every phase gets a QA table. Each row's `Mode` is `Auto` or `Manual`, and the choice is not a preference:
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
- **`Manual` is the default.** Write each row so a person can run it without reading code — what to set up, what to do, and what passing looks like.
|
|
22
|
+
- **`Auto` needs two things**: the project's `dogfood.enabled` is `true` (per the `sassy-setup` skill's `references/dogfood.md`) **and** the row names a recipe section that carries a `Prove it:` step. One without the other stays `Manual`. An `Auto` row with no check behind it is a gate that proves nothing.
|
|
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:**
|
|
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 (
|
|
104
|
+
#### QA — P1 (Auto)
|
|
85
105
|
|
|
86
106
|
| ID | Check | Mode | Status | Notes |
|
|
87
107
|
|----|-------|------|--------|-------|
|
|
88
|
-
| P1-Q1 |
|
|
89
|
-
| P1-Q2 |
|
|
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`
|
|
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
|
|
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.
|
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
60
|
-
- **Changes requested, or any
|
|
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
|
|
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
|
|