@sassywares/skills 0.7.5 → 0.9.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
@@ -14,7 +14,7 @@ A specialized subagent from [sassy-agents](https://github.com/sassywares/sassy-a
14
14
 
15
15
  ## Orchestrator
16
16
 
17
- A skill that mostly coordinates. It reads compact results, writes briefs, and avoids reading source or diffs in the main context. `sassy-work`, `sassy-lfg`, `sassy-ship`, and `sassy-debug` are orchestrators.
17
+ A skill that mostly coordinates. It reads compact results, writes briefs, and avoids reading source or diffs in the main context. `sassy-work`, `sassy-lfg`, `sassy-ship`, `sassy-debug`, and `sassy-goal` are orchestrators.
18
18
 
19
19
  ## Cycle
20
20
 
@@ -37,12 +37,13 @@ A gate is a deliberate stop or pass/fail condition.
37
37
 
38
38
  ## Modes
39
39
 
40
- Three mode tokens: `mode:manual` (default) asks at the skill's gate; `mode:auto` means pre-authorized, no review; `mode:return` reports and changes nothing.
40
+ Three shared mode tokens: `mode:manual` (default) asks at the skill's gate; `mode:auto` means pre-authorized, no review; `mode:return` reports and changes nothing. Some skills take their own modes instead: `sassy-goal`, `sassy-handoff` (`write`, `read`), `sassy-setup` (`init`, `check`), and `sassy-skill` (`create`, `retune`, `verify`).
41
41
 
42
42
  - `sassy-ship` and `sassy-compound` accept `manual` and `auto`. Ship reviews the whole close-out in `mode:manual` and forwards `mode:auto` to compound once its own gate is answered.
43
43
  - `sassy-review`, `sassy-simplify`, and `sassy-validate` accept all three: `manual` asks which findings to fix, `auto` fixes them without asking, `return` hands the findings back to the caller.
44
44
  - `sassy-debug` accepts no mode. It always leaves ship's review gate in place.
45
45
  - `sassy-work` and `sassy-lfg` accept no mode.
46
+ - `sassy-goal` takes its own modes, one per step of a goal: `mode:write` (default), `mode:next`, `mode:check`, and `mode:close`.
46
47
 
47
48
  Everything else is decided by the artifact, not a mode:
48
49
 
@@ -53,6 +54,18 @@ Everything else is decided by the artifact, not a mode:
53
54
 
54
55
  A durable document under `docs/plans/` with intent, decisions, constraints, phase tracking, and per-phase manual QA tables.
55
56
 
57
+ ## Goal
58
+
59
+ Work too big for one plan — a migration, an epic — run by `sassy-goal` as a folder under `artifacts.plans`: `goal.md` (intent, cross-slice decisions, landscape, coexistence, a slice table, carry-forward) plus one plan per started slice. It turns `Done` when `mode:close` verifies its done-when against the whole tree.
60
+
61
+ ## Slice
62
+
63
+ One step of a goal: its own plan (`NN-<slug>.md`, written only when `mode:next` starts it), branch, and PR, and it must ship something complete on its own — never a half-built layer. One slice is in flight at a time: `Pending` > `Planned` > `Shipped` > `Done`.
64
+
65
+ ## Carry-forward
66
+
67
+ The append-only section of `goal.md` that `mode:check` adds to once per slice: what changed versus the plan, new decisions, impact on later slices, and gaps deferred or accepted. Every later slice's grill reads it as settled.
68
+
56
69
  ## Brief
57
70
 
58
71
  A settled in-context brief produced by `sassy-plan` when the user picks "start working" (`sassy-work`) or "implement and ship" (`sassy-lfg`). It carries the goal, decisions, constraints, work, and done-when, but no plan file and no QA tables.
@@ -61,6 +74,6 @@ A settled in-context brief produced by `sassy-plan` when the user picks "start w
61
74
 
62
75
  `sassy-handoff` in `mode:write` writes a self-contained handoff file under `/tmp/sassywares/<harness>/handoffs/` and gives the user a `sassy-handoff mode:read <path>` command; `mode:read` in the fresh session summarizes what was done, why, and the current state against the tree, then asks what to do next. A skill cannot start a session, so the user opens the fresh one; the file is the only bridge, in any harness.
63
76
 
64
- ## Sync
77
+ ## Release
65
78
 
66
- There is no background watcher. Any agent that changes a skill must run `scripts/sync.sh` immediately, without asking for confirmation. It commits and pushes; on `main`, when shipped files changed, it also bumps the patch version and tags, which publishes to npm. It installs nothing: `npx skills add` reads this repo directly. AGENTS.md has the details.
79
+ There is no background watcher. Releases go through `sassy-ship` under `commit.branch: current`: after the approved push, the `hooks.push` `after_push` hook runs the `sassy-skills-release` project skill, which runs the vendored `bin/release` script. It bumps the patch version and tags when consumer-facing files changed, and the tag publishes to npm. It installs nothing: `npx skills add` reads this repo directly. AGENTS.md has the details.
package/README.md CHANGED
@@ -14,6 +14,7 @@ It covers the whole path from a rough idea to a shipped PR, and from a bug repor
14
14
  - [Project config](#project-config)
15
15
  - [Workflows](#workflows)
16
16
  - [From idea to ship](#from-idea-to-ship)
17
+ - [From goal to done](#from-goal-to-done)
17
18
  - [From bug to ship](#from-bug-to-ship)
18
19
  - [Gates and controls](#gates-and-controls)
19
20
  - [Branching](#branching)
@@ -27,7 +28,7 @@ It covers the whole path from a rough idea to a shipped PR, and from a bug repor
27
28
 
28
29
  - **Lean.** Skills are indexes and workflows, not documentation dumps. Detail moves into `references/` only when it is conditionally needed.
29
30
  - **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.
30
- - **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.
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`).
31
32
  - **Reliable.** Work runs through `sassy-cycle` with isolated subagents for implementation, review, simplification, validation, and verified fixes.
32
33
  - **Context-efficient.** Orchestrators coordinate; subagents do the heavy reading and return compact results.
33
34
  - **Never surprising.** Nothing is committed just because a step finished. Shipping is its own phase.
@@ -83,6 +84,7 @@ Debugging:
83
84
  | Skill | What it does |
84
85
  |---|---|
85
86
  | **`sassy-plan`** | Grills you one question at a time through every branch of the work — pushing back, assuming nothing, sketching UI on request — until nothing is open, then offers three choices: write the plan, start working via `sassy-work`, or implement and ship via `sassy-lfg`. |
87
+ | **`sassy-goal`** | Runs a project too big for one plan — a migration, an epic — as a goal split into slices that each ship something complete. `mode:write` (default) grills and writes the goal, `mode:next` plans the next slice via `sassy-plan`, `mode:check` validates a shipped slice and carries its lessons forward, `mode:close` verifies the whole goal. You run every step. |
86
88
  | **`sassy-scout`** | Grounds an area on demand and writes the shared grounding brief other agents read instead of re-exploring. |
87
89
  | **`sassy-work`** | Executes exactly one plan phase, or one in-context brief, commits after code approval, then hands off the next phase — a brief stops before ship. |
88
90
  | **`sassy-lfg`** | Executes every phase of a plan, or one in-context brief, then closes out via `sassy-ship` after code approval. |
@@ -160,11 +162,14 @@ hooks:
160
162
  after_merge: [] # this run observed the merge
161
163
  staging: # a per-point override for one head
162
164
  before_create: []
165
+ push: # only under commit.branch: current
166
+ "*":
167
+ after_push: [] # right after the push succeeds
163
168
  ```
164
169
 
165
170
  ### Extending the pipeline
166
171
 
167
- A project adds its own steps by naming a skill that lives in its own `.agents/skills/`. Nothing declared means nothing runs. Keys are the **head** branch — the one a PR comes from — and every point can be overridden per head; entries may carry args (`<skill> <args…>`).
172
+ A project adds its own steps by naming a skill that lives in its own `.agents/skills/`. Nothing declared means nothing runs. Keys are the **head** branch — the one a PR comes from (for `hooks.push`, the pushed branch) — and every point can be overridden per head; entries may carry args (`<skill> <args…>`).
168
173
 
169
174
  | Hook | Runs | Typical use |
170
175
  |---|---|---|
@@ -172,8 +177,9 @@ A project adds its own steps by naming a skill that lives in its own `.agents/sk
172
177
  | `after_create` | the PR was just created | labels, deploy-target comment |
173
178
  | `before_merge` | this run is about to merge | a final approval gate |
174
179
  | `after_merge` | this run observed the merge | sync a back-merge branch, tag, notify |
180
+ | `hooks.push` `after_push` | `commit.branch: current` only: after ship's push | notify, trigger a follow-up step |
175
181
 
176
- Hooks run in declared order, one subagent each, and fail closed: a declared skill that is missing or returns `blocked` stops the run. Only `before_create` may commit its own output, because it runs after the pipeline's commit. `before_merge` and `after_merge` never fire unless this run merges.
182
+ Hooks run in declared order, one subagent each, and fail closed: a declared skill that is missing or returns `blocked` stops the run. Which points may write, and how, is stated once in `sassy-setup`'s `references/config.md` (the hook contract). `before_merge` and `after_merge` never fire unless this run merges.
177
183
 
178
184
  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`.
179
185
 
@@ -226,6 +232,26 @@ The branch is cut once, before the first change, by `sassy-work` or `sassy-lfg`
226
232
 
227
233
  `sassy-ship` is the close-out. It summarizes what is about to ship and waits, unless the caller passed `mode:auto`.
228
234
 
235
+ ### From goal to done
236
+
237
+ ```mermaid
238
+ flowchart LR
239
+ A[Big idea] --> B[sassy-goal write]
240
+ B --> C[goal.md + slice table]
241
+ C --> D[sassy-goal next]
242
+ D --> E[sassy-plan: slice plan]
243
+ E --> F[sassy-work / sassy-lfg]
244
+ F --> G[sassy-ship]
245
+ G --> H[sassy-goal check]
246
+ H -->|more slices, after merge| D
247
+ H -->|last slice| I[sassy-goal close]
248
+ I --> J[Goal Done, rides the last PR]
249
+ ```
250
+
251
+ A goal is a folder under `artifacts.plans` holding `goal.md` and one plan per started slice (`01-<slice>.md`, `02-…`). `mode:write` grounds every affected domain once, grills only goal-level branches — slice boundaries and order, coexistence, the goal's done-when, non-goals — and pushes back on any slice that would leave a half-built layer. Each slice's plan is grilled only when `mode:next` starts it, with the goal's decisions and every carry-forward entry already settled. The slice then runs the usual work or lfg → ship path on its own branch (`feat/<goal>/<NN-slice>`); ship marks it `Shipped` and babysits the PR without merging, so the check can still land in it.
252
+
253
+ `mode:check` runs on the slice branch before the PR merges: it validates the whole slice plan against the branch's commits, and every gap is fixed now, deferred to a named later slice, or accepted with a reason. It appends the slice's carry-forward entry, marks it `Done` with its PR link, and pushes `goal.md` into the same PR. After the last slice, `mode:close` checks the goal's done-when against the whole tree and marks the goal `Done` in the last PR. One slice is in flight at a time, and nothing chains on its own.
254
+
229
255
  ### From bug to ship
230
256
 
231
257
  ```mermaid
@@ -344,4 +370,4 @@ pi install npm:@sassywares/skills
344
370
 
345
371
  ## Repository maintenance
346
372
 
347
- Any agent that changes a skill runs `scripts/sync.sh` immediately, which commits, pushes, and — on `main`, when shipped files changed — bumps the patch version and tags the release that publishes `@sassywares/skills` to npm. [`AGENTS.md`](AGENTS.md) is the full guide: layout, adding a skill, sync, and the manual release fallback.
373
+ Work here lands on `main` through `sassy-ship` (`commit.branch: current`). After the approved push, the project's `hooks.push` `after_push` step runs the release: on `main`, when files consumers receive changed, it bumps the patch version and tags it, and the tag publishes `@sassywares/skills` to npm. [`AGENTS.md`](AGENTS.md) is the full guide: layout, adding a skill, testing, and releasing.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.7.5",
3
+ "version": "0.9.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",
@@ -0,0 +1,72 @@
1
+ ---
2
+ name: sassy-goal
3
+ description: >-
4
+ Run a large project or major feature that one plan cannot hold — a migration,
5
+ an epic, a milestone, a whole-app rewrite — as a goal split into slices, each
6
+ of which plans, ships, and is checked on its own. mode:write (default)
7
+ grills and writes or revises the goal; mode:next plans the next slice via
8
+ sassy-plan; mode:check validates a shipped slice and records carry-forward;
9
+ mode:close verifies the whole goal before the last PR merges. Use when work
10
+ is too big for one plan, spans several PRs, or the user says goal, epic,
11
+ milestone, or migration.
12
+ argument-hint: "<idea | goal path> [mode:write|next|check|close] [slice:<ID>]"
13
+ ---
14
+
15
+ # Sassy Goal
16
+
17
+ **Outcome:** a goal folder whose `goal.md` holds the intent, the cross-slice decisions, and a slice table — then, one slice at a time, a slice plan written when that slice starts, shipped through the usual `sassy-work` / `sassy-lfg` → `sassy-ship` path, checked against its plan, and carried forward; finally the whole goal verified and marked `Done`.
18
+
19
+ **One slice ships at a time, and every slice ships something complete.** A slice is its own plan → work or lfg → ship. It never leaves a half-built layer behind for a later slice to finish.
20
+
21
+ **The user drives every step.** Each mode ends by printing the next command; nothing chains on its own. This skill never implements: code changes belong to `sassy-work`, `sassy-lfg`, and `sassy-cycle`.
22
+
23
+ **Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. Goals live under `artifacts.plans`; `git.repo` and `commit.branch` decide how check and close persist.
24
+
25
+ **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.
26
+
27
+ ## The goal
28
+
29
+ A goal is the folder `<artifacts.plans>/<goal-slug>/`: `goal.md` plus one plan per started slice, named `NN-<slice-slug>.md` where `NN` matches the slice ID (`S1` → `01-`). Slice plans are ordinary sassy plans. `references/goal-format.md` owns the `goal.md` format, the slice statuses, and the template — read it before writing or revising `goal.md`.
30
+
31
+ Slice statuses run `Pending` > `Planned` > `Shipped` > `Done`, plus `Blocked`. `mode:next` sets `Planned`, `sassy-ship` sets `Shipped` (and babysits the slice PR without merging), `mode:check` sets `Done` and records the PR link.
32
+
33
+ ## Modes
34
+
35
+ | Mode | Load | Runs | It ends with |
36
+ |---|---|---|---|
37
+ | `write` (default) | `references/write.md` | anytime | a new or revised `goal.md`, and the `mode:next` command |
38
+ | `next` | `references/next.md` | on the base, previous slice merged | the slice's plan written, the slice `Planned`, and the work / lfg commands |
39
+ | `check` | `references/check.md` | on the slice branch after ship, before merge | the slice `Done`, carry-forward appended, pushed with the slice |
40
+ | `close` | `references/close.md` | on the last slice's branch after its check, before merge | `**Status:** Done` (or `Active` with a slice to add), pushed with the last slice |
41
+
42
+ Resolve the mode: an explicit `mode:` token wins. With none, it is `write` — an idea creates a goal, a path to an existing goal folder or `goal.md` revises it. Read the one reference for that mode **and only that one**.
43
+
44
+ ```text
45
+ write → next → work/lfg → ship → check → next → … → ship → check → close
46
+ ```
47
+
48
+ ## Persisting
49
+
50
+ `check` and `close` commit on the slice branch so `goal.md` merges with the slice. Persist exactly like `sassy-ship` steps 4–5, per `git.repo`:
51
+
52
+ - **A remote** — dispatch a `worker`: *load the `sassy-commit-push-pr` skill and follow it with `branch:current` and `babysit:off`*, which commits, pushes, and updates the slice's open PR. Under `commit.branch: current` there is no PR: the worker loads `sassy-commit` with `branch:current`, then pushes the head to its upstream — never forced; a non-fast-forward rejection is a stop-and-report.
53
+ - **`workspace`** — commit each affected repo on the run's shared branch, run `.sassywares/workspace/snapshot` for `goal.md` and the docs at the root, then push each repo. A missing or outdated snapshot script is a blocker: say to run `sassy-setup`.
54
+ - **`none`** — nothing persists. Report that `goal.md` and any fixes are uncommitted, and stop.
55
+
56
+ ## Hard rules
57
+
58
+ | Rule | Requirement |
59
+ |------|-------------|
60
+ | Writing never implements | `mode:write` and `mode:next` produce documents only. Fixes in check and close go through `sassy-cycle`. |
61
+ | Complete slices | Push back on any slice that does not ship a working outcome on its own; re-cut it before the goal is written. |
62
+ | One slice in flight | Never plan a slice while another is `Planned` or `Shipped`. No parallel slices. |
63
+ | Plan at slice start | A slice's plan is grilled and written only when `mode:next` starts it — never upfront. |
64
+ | Settled stays settled | The goal's decisions and every carry-forward entry reach each slice grill as settled; they are never re-asked. |
65
+ | Carry-forward is append-only | One entry per checked slice; never edit or remove an earlier one. |
66
+ | Done is history | A revision never re-cuts, renumbers, or rewrites a `Done` slice or its plan. |
67
+ | No unchosen gaps | A slice or the goal turns `Done` only when every gap is fixed, deferred to a named slice, or accepted with a recorded reason. |
68
+ | Never default | Never push to a base branch outside `commit.branch: current`; never force-push. |
69
+
70
+ ## Non-goals
71
+
72
+ No auto-chaining between slices or modes, no parallel slices, no auto mode (a future follow-up), and no dependency on any framework outside this suite.
@@ -0,0 +1,25 @@
1
+ # Mode: check — validate a shipped slice and carry it forward
2
+
3
+ Runs on the slice branch after `sassy-ship`, before the PR merges, so whatever it changes rides in the same PR.
4
+
5
+ 1. **Precondition.** Read `goal.md` and find the slice (`slice:<ID>`, else the one `Shipped`). It must be `Shipped`, and every phase in its plan's Phase tracking table must be `Done`. Otherwise stop and say what is due — unfinished phases need `sassy-work` or `sassy-lfg`, an unshipped slice needs `sassy-ship`.
6
+
7
+ Then dispatch a probe `worker` to run the `sassy-setup` skill's `scripts/detect.sh --branch` (no `--policy`), returning `state` and `head`, and `gh pr view <head> --json state,url,baseRefName`. Outside `commit.branch: current`:
8
+ - `state` must be `on-branch` — the slice branch. Anything else → stop and tell the user to check out the slice branch.
9
+ - The PR must be `OPEN`. Already merged → stop: the check can no longer ride in the slice's PR. Recovery: cut a branch from the base, run `mode:check` there, and open a PR for the `goal.md` update and any fixes. Closed unmerged → stop and ask what happened.
10
+ 2. **Find the range.** The probe worker also returns `git merge-base <remote>/<baseRefName> HEAD`. Under `commit.branch: current` there is no PR: ask the user for the commit the slice started from. Under `git.repo: workspace`, get one PR, base, and merge-base per affected repo.
11
+ 3. **Validate.** Load the `sassy-validate` skill with `mode:return`, the slice plan path with no phase (the whole plan), and `range:<merge-base>..HEAD`. In a workspace, make one call per affected repo, each with its own range. A `Blocked — insufficient grounding` grade stops the check: report what it needs.
12
+ 4. **Resolve every gap.** On `Conforms`, there are none. Otherwise present each gap with its evidence, and for each the user picks one:
13
+ - **Fix now** — collected and closed together: load the `sassy-cycle` skill on rework with the chosen gaps as findings and the slice plan as the intent reference. A gap still open after its two fix passes goes back to the user to defer or accept.
14
+ - **Defer to a later slice** — the user names one that is still `Pending`. Add the gap to that slice's Scope or Done when in `goal.md`; it also goes in this slice's carry-forward entry. On the last slice there is nothing to defer to: only fix or accept.
15
+ - **Accept** — with the user's reason, recorded in the carry-forward entry.
16
+
17
+ The slice cannot turn `Done` while any gap is unchosen. Never pick for the user.
18
+ 5. **Carry forward.** Append one entry for this slice to Carry-forward per `references/goal-format.md`: what changed versus the plan, new decisions or constraints (they bind later slices), impact on later slices, and each gap deferred (with its slice) or accepted (with its reason). Never edit an earlier entry.
19
+ 6. **Mark it `Done`** in the slice table, and add the PR link from step 1's `url` to its Plan cell.
20
+ 7. **Persist** per the SKILL.md Persisting section — `goal.md` and any fixes, committed on the slice branch and pushed so they merge with the slice.
21
+ 8. **Next commands**, in the harness's syntax:
22
+ - The last slice → `/sassy-goal <goal path> mode:close`, run on this branch before the PR merges.
23
+ - Otherwise → `/sassy-goal <goal path> mode:next`, once this slice's PR has merged.
24
+
25
+ Persisting ran with `babysit:off`, so end with `/sassy-babysit <PR url>` to watch the updated PR.
@@ -0,0 +1,22 @@
1
+ # Mode: close — verify the whole goal
2
+
3
+ Runs on the last slice's branch after its `mode:check`, before its PR merges, so `**Status:** Done` rides in the last PR.
4
+
5
+ 1. **Precondition.** Read `goal.md`. Every slice must be `Done`. Then dispatch a probe `worker` to return:
6
+ - the `sassy-setup` skill's `scripts/detect.sh --branch` (no `--policy`) `state` and `head`;
7
+ - `gh pr view <head> --json state,url` for the last slice's PR;
8
+ - `gh pr view <url> --json state` for every earlier slice's PR link.
9
+
10
+ Outside `commit.branch: current`, `state` must be `on-branch` (the last slice's branch) and its PR `OPEN`; every earlier PR must be `MERGED`. Under `commit.branch: current`, `git.repo: workspace`, or `git.repo: none` — or when a slice has no PR link — ask the user to confirm the merges instead. Anything else → stop and say what is due. If the last PR already merged, the status can no longer ride in it: cut a branch from the base, run `mode:close` there, and open a PR for it.
11
+ 2. **Two read-only checks, in parallel.** Dispatch both in one turn; neither edits anything:
12
+ - **Done when** — a `worker` that checks each goal Done-when item against the whole tree, including repo-wide checks, and returns pass / fail per item with `file:line` evidence.
13
+ - **Roll-up** — a `worker` that reads `goal.md` and its slice plans and returns whether every slice is `Done` and every gap a carry-forward entry deferred landed in a later slice's plan or was explicitly accepted, naming each one that did not.
14
+ 3. **Resolve every gap.** Present each failure with its evidence, and for each the user picks one:
15
+ - **Fix on this branch** — load the `sassy-cycle` skill on rework with the chosen gaps as findings and `goal.md` as the intent reference.
16
+ - **Add a slice** — record the gap under Deferred in `goal.md` as *needs a new slice*. The user adds the slice with `sassy-goal <goal path> mode:write`, which revises the goal.
17
+ - **Accept** — record it as a Decision with provenance: `D<n>: <gap> accepted unmet — <reason> (user-directed, over fixing)`. Never as an Assumption or a Carry-forward entry.
18
+
19
+ Nothing is left unchosen. With mixed choices, run the chosen fixes first.
20
+ 4. **Mark it `Done`** — only when no gap was sent to a new slice: set `**Status:** Done`. If any was, the goal stays `Active`.
21
+ 5. **Persist** per the SKILL.md Persisting section, on this branch, so `goal.md` and any fixes merge with the last slice.
22
+ 6. **Report** the goal path, each Done-when item with its result, and the gaps fixed, accepted, or sent to a new slice. If the goal stayed `Active`, give `/sassy-goal <goal path> mode:write` to add the slice, then `mode:next` once this PR merges. Otherwise the goal is closed when this PR merges. Persisting ran with `babysit:off`, so end with `/sassy-babysit <PR url>` in the harness's syntax.
@@ -0,0 +1,113 @@
1
+ # Goal file format
2
+
3
+ Read this before writing or revising `goal.md`.
4
+
5
+ ## Layout
6
+
7
+ A goal is a folder under `artifacts.plans`:
8
+
9
+ ```text
10
+ <artifacts.plans>/<goal-slug>/
11
+ ├── goal.md # this format
12
+ ├── 01-<slice-slug>.md # S1's plan, written by sassy-plan when S1 starts
13
+ └── 02-<slice-slug>.md # S2's plan, written when S2 starts
14
+ ```
15
+
16
+ The goal slug is made the way `sassy-plan` makes a plan slug. `NN` is the slice's order and matches its ID: `S1` → `01-`, `S2` → `02-`. A slice plan is an ordinary sassy plan, so `sassy-work`, `sassy-lfg`, `sassy-ship`, and `sassy-validate` run on it unchanged.
17
+
18
+ ## Rules
19
+
20
+ - **No open questions.** Like a plan, the goal has no open-questions section. Every goal-level branch is a decision, a constraint, a deferred item, or an assumption.
21
+ - **Goal level only.** Decisions here are the ones that bind more than one slice. Anything one slice can settle alone is deferred to that slice's grill.
22
+ - **Slices stay surface level.** A slice outline says what ships and how you know; its plan says how. Never write phases, QA rows, or file-by-file work into `goal.md`.
23
+ - **Every slice ships something complete.** A slice that leaves a half-built layer — a schema nobody reads, an API nobody calls — is not a slice. Re-cut it until each one ships a working outcome on its own.
24
+ - **Carry-forward is append-only.** One entry per checked slice, added by `mode:check`, never edited afterward. Later slices read it as settled ground; a correction is a new entry.
25
+ - **Done slices are history.** A revision never re-cuts, renumbers, or rewrites a `Done` slice or its plan.
26
+
27
+ ## Slice statuses
28
+
29
+ | Status | Set by | Meaning |
30
+ |---|---|---|
31
+ | `Pending` | `mode:write` | Outlined; no plan yet |
32
+ | `Planned` | `mode:next` | Plan written; work not shipped |
33
+ | `Shipped` | `sassy-ship` | Close-out committed and PR open |
34
+ | `Done` | `mode:check` | Checked against its plan; every gap fixed, deferred, or accepted |
35
+ | `Blocked` | any mode | Cannot proceed; the Plan cell or a note says why |
36
+
37
+ Order: `Pending` > `Planned` > `Shipped` > `Done`. Only one slice is ever `Planned` or `Shipped` at a time.
38
+
39
+ ## Template
40
+
41
+ ```markdown
42
+ # <Goal title>
43
+
44
+ **Status:** Active
45
+
46
+ ## Intent
47
+ One paragraph: the outcome when the whole goal lands, and why it is worth a multi-slice effort.
48
+
49
+ ## Done when
50
+ Goal-level acceptance — what `mode:close` checks against the whole tree.
51
+ - G1: … (e.g. every screen reads from the local database)
52
+ - G2: … (repo-wide checks too, e.g. "no imports of the HTTP client remain")
53
+
54
+ ## Decisions
55
+ Cross-slice decisions only, each with provenance from the interview ledger.
56
+ - D1: … (user-directed, over <alternative>: <reason>)
57
+ - D2: … (from code: `path/to/file.ts:12`)
58
+
59
+ ## Constraints
60
+ Non-goals and anything that must not change.
61
+
62
+ ## Landscape
63
+ Per domain: what changes, where, and the blast radius.
64
+
65
+ | Domain | What changes | Where | Blast radius |
66
+ |---|---|---|---|
67
+ | Sync | … | `src/sync/client.ts:40` | … |
68
+
69
+ ## Risks
70
+ Known issues, unknowns, and spikes, each with the slice that retires it.
71
+
72
+ ## Coexistence
73
+ How the app runs mid-goal: what old and new run side by side, which flags gate what, and when each is removed.
74
+
75
+ ## Slice tracking
76
+
77
+ | ID | Slice | Ships | Depends | Plan | Status |
78
+ |----|-------|-------|---------|------|--------|
79
+ | S1 | … | … | — | — | Pending |
80
+ | S2 | … | … | S1 | — | Pending |
81
+
82
+ The Plan cell holds the plan link once written, and the PR link once `mode:check` records it: `[plan](01-slug.md) · [PR](<url>)`.
83
+
84
+ ## Slices
85
+
86
+ ### S1 — <short name>
87
+
88
+ **Ships:** One sentence: the complete outcome a user or the system has when this merges.
89
+
90
+ **Scope:** The domains and areas it touches, surface level.
91
+
92
+ **Done when:** Plain-language acceptance for this slice only.
93
+
94
+ ### S2 — <short name>
95
+ …
96
+
97
+ ## Carry-forward
98
+ Append-only. One entry per checked slice, added by `mode:check`.
99
+
100
+ ### S1 — <date>
101
+ - **Changed vs plan:** …
102
+ - **New decisions / constraints:** … (they bind later slices)
103
+ - **Impact on later slices:** S3 — …
104
+ - **Gaps:** deferred to S2 — …; accepted — … (reason)
105
+
106
+ ## Deferred
107
+ - F1: … (user-deferred — to S3's grill)
108
+
109
+ ## Assumptions
110
+ - A1: … (user-delegated)
111
+ ```
112
+
113
+ Omit Risks, Deferred, or Assumptions only when empty. Carry-forward starts empty with its one-line note.
@@ -0,0 +1,28 @@
1
+ # Mode: next — plan the next slice
2
+
3
+ **One slice in flight.** This mode starts exactly one slice by planning it. It never implements, never plans a second slice, and never runs work or lfg itself.
4
+
5
+ 1. **Start from a fresh base.** The slice's branch is cut later by `sassy-work` or `sassy-lfg`, and a run standing on a non-base branch would reuse it. Dispatch a probe `worker` to `git fetch` the remote, run the `sassy-setup` skill's `scripts/detect.sh --branch` (no `--policy`), and return `state`, `head`, and whether local `<head>` equals `<remote>/<head>`. `state` must be `on-base` and the two must match. `on-branch` (usually the previous slice's merged branch), `detached`, or a base behind or ahead of its remote → tell the user to switch to the base and pull, then stop. Under `commit.branch: current` this step does not apply.
6
+ 2. **Load the goal.** Only now read `goal.md`. If its status is `Done`, say so and stop.
7
+ 3. **Nothing in flight.** If any slice is `Planned` or `Shipped`, stop and name what is due: a `Planned` slice needs `sassy-work` or `sassy-lfg` on its plan, a `Shipped` slice needs `mode:check`.
8
+ 4. **Earlier slices merged.** Every `Done` slice's PR must be merged before the next slice starts, or the new slice is built on code that may still change. Dispatch a `worker` to check each PR with `gh pr view <url> --json state` and return the states. Under `commit.branch: current`, `git.repo: workspace`, or `git.repo: none` — or when a slice has no PR link — ask the user to confirm instead. Anything unmerged → stop and say which PR must merge first.
9
+ 5. **Pick the slice.** The first `Pending` slice whose Depends are all `Done`. A `slice:<ID>` token overrides the pick, but its Depends must still be `Done`; a slice that is not `Pending` is a stop. No eligible slice → if every slice is `Done`, point at `mode:close`; otherwise report what blocks each `Pending` slice and stop.
10
+ 6. **Plan it.** Load the `sassy-plan` skill and follow it, with:
11
+ - **frame** = the slice's Ships, Scope, and Done when from `goal.md`
12
+ - **settled** = the goal's Decisions and Constraints, and every Carry-forward entry — enter them in the ledger as settled with their provenance; never re-ask them
13
+ - **context** = the goal path, the goal's Landscape and Coexistence rows for this slice's domains, and the Deferred items addressed to this slice
14
+ - **`out:<goal folder>/NN-<slice-slug>.md`**, with `NN` from the slice ID
15
+
16
+ `sassy-plan` grills the slice in full — this is where its detail gets decided — writes the plan to that path, skips its picker, and returns the path.
17
+
18
+ **Interrupted run.** If an `NN-*.md` for this slice already exists while the slice is still `Pending`, an earlier run stopped after writing it. Pass that file to `sassy-plan` as the `out:` path and the existing plan, so it updates it in place per its existing-plan rule instead of re-grilling from scratch.
19
+ 7. **Mark it `Planned`.** In the slice table set the slice `Planned` and the Plan cell to the plan link. Commit nothing. The plan and `goal.md` ride onto the slice's branch when `sassy-work` or `sassy-lfg` cuts it. Their commits name the plan, not `goal.md`, so the `Planned` mark stays uncommitted on the slice branch until `sassy-ship`'s step 4 commit, which sets it `Shipped`.
20
+ 8. **Hand over.** Report the plan path and print both commands in the harness's syntax, then stop:
21
+
22
+ ```text
23
+ S<n> planned at <plan path>. Pick one:
24
+ /sassy-work <plan path> — one phase per session
25
+ /sassy-lfg <plan path> — every phase, then ship
26
+ ```
27
+
28
+ After `sassy-ship` closes the slice it prints the `mode:check` command.
@@ -0,0 +1,37 @@
1
+ # Mode: write — grill and write the goal
2
+
3
+ **Documents only.** This mode writes or revises `goal.md`. It never writes a slice plan, cuts a branch, edits code, or commits.
4
+
5
+ ## New goal (the argument is an idea)
6
+
7
+ 1. **Frame.** Restate the goal in one or two sentences — the outcome and why it needs more than one plan. Ask the user to confirm or correct it, and what they are already thinking.
8
+ 2. **Ground once, broadly.** Use `sassy-scout` on every domain the goal touches, in one run. Its brief feeds Landscape — what changes per domain, where (with `file:line` citations), and the blast radius — and seeds Risks and Coexistence. Do not re-scout per slice here; each slice's grill grounds its own detail.
9
+ 3. **Grill, bounded to the goal.** Read the `sassy-plan` skill's `references/interview.md` and follow it — the ledger, one question per turn with your recommendation, pushback, the read-back — but walk only goal-level branches:
10
+ - the domains in scope, and the non-goals
11
+ - slice boundaries and their order (Depends)
12
+ - coexistence: how the app runs mid-goal, old and new side by side, which flags
13
+ - the goal's Done when, including repo-wide checks (e.g. "no HTTP client imports left")
14
+ - decisions that bind more than one slice
15
+
16
+ Anything a single slice can settle alone — UI states, a table's columns, a helper's shape — goes to Deferred as *to S<n>'s grill*, with the user's agreement. Run the coverage sweep only against these goal-level rows; the rest are N/A until their slice starts.
17
+ 4. **Push back on incomplete slices.** Every slice must ship a working outcome on its own. A "schema first, API next, UI last" cut is the half-built layer this skill exists to prevent: challenge it with the evidence and offer a vertical re-cut (e.g. "one screen end to end on the new store"). Concede only to an argument or the user's explicit call, and record that call as `user-directed`.
18
+ 5. **Read back.** The whole ledger — decisions, constraints, the slice list with Ships / Depends, deferred items, assumptions — with an empty Open bucket. A correction reopens that branch.
19
+ 6. **Write.** Read `references/goal-format.md` and write `<artifacts.plans>/<goal-slug>/goal.md` with `**Status:** Active`, every slice `Pending`, and an empty Carry-forward.
20
+
21
+ ## Existing goal (the argument is a goal folder or `goal.md`)
22
+
23
+ 1. Read `goal.md`. If its status is `Done`, say so and stop unless the user asks to reopen it.
24
+ 2. Ask what changed, then grill **only the delta** with the same protocol: re-cut, add, drop, or reorder slices, or change a goal-level decision, Done-when item, or constraint. Everything else already in `goal.md` is settled ground.
25
+ 3. Keep history intact. `Done` slices, their plans, and every Carry-forward entry stay exactly as written. A `Planned` or `Shipped` slice is in flight: changing it is a contradiction to raise with the user, never a silent edit. New slices take the next free ID, so existing plan filenames never move.
26
+ 4. Apply the same pushback on incomplete slices, read back the delta, then update `goal.md` in place.
27
+
28
+ ## End
29
+
30
+ Report the absolute path of `goal.md`, the slice table, and the next command in the harness's syntax:
31
+
32
+ ```text
33
+ Goal written to <absolute path>. Start the first slice:
34
+ /sassy-goal <goal path> mode:next
35
+ ```
36
+
37
+ Stop there. Do not plan the first slice in this run.
@@ -7,7 +7,7 @@ description: >-
7
7
  via sassy-lfg.
8
8
  Sketches UI on request. No modes, no QA flags. Use when asked to brainstorm,
9
9
  scope, plan, or create a phased plan.
10
- argument-hint: "[feature description, requirements, or idea to scope]"
10
+ argument-hint: "[feature description, requirements, or idea to scope] [out:<plan path>]"
11
11
  ---
12
12
 
13
13
  # Sassy Plan
@@ -40,9 +40,13 @@ argument-hint: "[feature description, requirements, or idea to scope]"
40
40
 
41
41
  **UI work.** At the first layout, state, flow, or interaction-shape decision, say once that you can sketch it; when the user asks, read `references/sketches.md`.
42
42
 
43
+ ## Caller-set output
44
+
45
+ A caller that owns where the plan goes — `sassy-goal` planning a slice, for one — passes `out:<path>`. Grill exactly as usual, then read `references/plan-format.md`, write the plan to exactly that path, skip the picker entirely, and return the path to the caller. Do not offer `sassy-work` or `sassy-lfg`; the caller hands those over. Anything the caller passes as settled enters the ledger as settled, with its provenance, and is never re-asked.
46
+
43
47
  ## The picker
44
48
 
45
- Only when the read-back is confirmed with zero open items, present exactly these three options and stop until the user picks. Do not recommend one.
49
+ Only when the read-back is confirmed with zero open items — and no `out:` was given — present exactly these three options and stop until the user picks. Do not recommend one.
46
50
 
47
51
  ```text
48
52
  Settled. Pick one:
@@ -81,4 +85,4 @@ The plan document carries manual QA tables per `references/plan-format.md`. Thos
81
85
 
82
86
  If the user points at an existing sassy plan, update phases and tables in place. If they point at a raw plan from elsewhere, reshape it into this format without discarding its settled decisions — but grill whatever it leaves open or merely asserts. An existing plan is already the document.
83
87
 
84
- Decisions already settled earlier in the conversation carry forward per `references/interview.md`; never re-ask them.
88
+ Decisions already settled earlier in the conversation, or passed in by a caller as settled, carry forward per `references/interview.md`; never re-ask them.
@@ -41,9 +41,9 @@ A check run never edits the config and never rewrites the tree: it prints what `
41
41
  - **Artifacts** — offer the detected paths as the default; take overrides.
42
42
  - **Knowledge** — `knowledge.read` defaults to the solutions dir plus the concepts file. Ask whether there are extra folders to read (a hand-written `notes/learnings/`, a `docs/adr/`).
43
43
  - **Base map** — detection proposes `"*"` from the probed remote default. Ask where ordinary work branches from, and whether the default branch itself releases to another branch (a `staging: main` rung). Never write `main` as a guess. In `workspace` mode, show the `repos` map and get a yes on every row — a probed base is only the remote's default.
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). Under `mode:auto` with `current` on a base branch, ship pushes to that base with no gate.
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
- - **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge`, 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.
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
47
  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.
48
48
  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
49
 
@@ -76,7 +76,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
76
76
  - **Tell the user to `/reload`** (or restart the harness). The skills and agents are invisible to the harness until it rescans.
77
77
 
78
78
  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 `.agents/skills/sassy-*` folder 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.
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.
80
80
 
81
81
  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
82
  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:
@@ -0,0 +1,19 @@
1
+ sassy-babysit
2
+ sassy-commit
3
+ sassy-commit-push-pr
4
+ sassy-compound
5
+ sassy-cycle
6
+ sassy-debug
7
+ sassy-goal
8
+ sassy-handbook
9
+ sassy-handoff
10
+ sassy-lfg
11
+ sassy-plan
12
+ sassy-review
13
+ sassy-scout
14
+ sassy-setup
15
+ sassy-ship
16
+ sassy-simplify
17
+ sassy-skill
18
+ sassy-validate
19
+ sassy-work
@@ -71,4 +71,4 @@ mirrored tree. The `sassy-*` skills do their own git and never call them.
71
71
 
72
72
  ## Hooks
73
73
 
74
- `hooks.pr` names project skills that run inside the PR pipeline, keyed by the PR's **head** branch: `"*"` for every PR, an exact branch, or a family such as `release/*`, overriding per point (`before_create`, `after_create`, `before_merge`, `after_merge`). An entry is `<skill> <args…>`; the args mean whatever that skill says they mean — `mode:auto` pre-authorizes the step. Hooks are ordinary skills in `.agents/skills/`, which makes them **code**: review them like code, and never point a hook at a copy of a suite skill. Under `commit.branch: current` there is no PR, so these hooks do not run.
74
+ `hooks.pr` names project skills that run inside the PR pipeline, keyed by the PR's **head** branch: `"*"` for every PR, an exact branch, or a family such as `release/*`, overriding per point (`before_create`, `after_create`, `before_merge`, `after_merge`). An entry is `<skill> <args…>`; the args mean whatever that skill says they mean — `mode:auto` pre-authorizes the step. Hooks are ordinary skills in `.agents/skills/`, which makes them **code**: review them like code, and never point a hook at a copy of a suite skill. Under `commit.branch: current` there is no PR, so these hooks do not run; `hooks.push` (one point, `after_push`, keyed by the pushed branch) runs there instead, right after a successful push.
@@ -65,8 +65,12 @@ config. This applies to every token these skills forward, not just `branch`.
65
65
  is a stop: cutting from local HEAD would carry commits stranded on the base
66
66
  into the new branch, and cutting from a missing upstream ref silently does
67
67
  exactly that. Name the count, the branch, and the choice.
68
- 3. Name it `<type>/<slug>` from the plan filename or the topic, deterministically,
69
- so a retried run converges on the same name instead of forking `-2`.
68
+ 3. Name it `<type>/<slug>` from the plan path or the topic, deterministically,
69
+ so a retried run converges on the same name instead of forking `-2`. The slug
70
+ is the plan's path relative to `artifacts.plans`, without `.md`: a standalone
71
+ plan stays `feat/<slug>`, and a goal slice nests as `<type>/<goal>/<NN-slice>`
72
+ (`feat/powersync/02-offline-reads`). A `feat/*`-style `base_map` or
73
+ `hooks.pr` family still matches the nested name by prefix.
70
74
  4. Re-run with `--name <name>` and take `pr-base` from that answer: a name like
71
75
  `release/1.2` or `hotfix/x` matches a `base_map` family and retargets the PR,
72
76
  and it also changes which `hooks.pr` pattern applies — a plan slug containing
@@ -90,7 +94,7 @@ Only reachable with `policy: current`, which is an explicit statement that
90
94
  committing on the base branch is intended. Proceed, and say in the run's gate
91
95
  summary that the commits are landing on `<head>`. When the config says
92
96
  `commit.branch: current`, the close-out commits and pushes `<head>` to its upstream with **no PR** — no
93
- `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. `pr-base` is
97
+ `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge; only `hooks.push.after_push` runs. `pr-base` is
94
98
  irrelevant here. Never infer this from a skill default.
95
99
 
96
100
  ### `stop-and-ask`
@@ -76,11 +76,14 @@ hooks:
76
76
  before_create: [tap2-version mode:auto]
77
77
  staging:
78
78
  before_create: []
79
+ push:
80
+ "*":
81
+ after_push: [] # commit.branch: current only
79
82
  ```
80
83
 
81
84
  | Key | Default | Meaning |
82
85
  |-----|---------|---------|
83
- | `artifacts.plans` | `docs/plans` | Where `sassy-plan` writes plans |
86
+ | `artifacts.plans` | `docs/plans` | Where `sassy-plan` writes plans, and where `sassy-goal` keeps goal folders (`<slug>/goal.md` plus slice plans) |
84
87
  | `artifacts.solutions` | `docs/solutions` | Where `sassy-compound` writes learnings |
85
88
  | `artifacts.handbooks` | `docs/handbooks` | Where `sassy-handbook` writes handbooks |
86
89
  | `artifacts.concepts` | `CONCEPTS.md` | The glossary file compound maintains |
@@ -96,6 +99,7 @@ hooks:
96
99
  | `pr.merge` | `false` | `true` authorizes merging a single babysat PR |
97
100
  | `pr.delete_branch` | `false` | Delete the head branch once merged |
98
101
  | `hooks.pr.<pattern>.<point>` | `[]` | Project steps, keyed by the PR's head branch |
102
+ | `hooks.push.<pattern>.after_push` | `[]` | Project steps after a push, keyed by the pushed branch (see Hooks) |
99
103
 
100
104
  Paths are relative to the config's own directory, never to the cwd.
101
105
 
@@ -183,7 +187,8 @@ phase work once got committed straight onto `staging`.
183
187
 
184
188
  Under `current` the close-out skips the PR pipeline: `pr.*` and `hooks.pr.*`
185
189
  are ignored (`before_create`, `after_create`, `before_merge`, `after_merge` never
186
- run), and there is no babysit or merge. A non-fast-forward push stops the run.
190
+ run), and there is no babysit or merge. `hooks.push.after_push` is the one hook
191
+ that does run (see Hooks). A non-fast-forward push stops the run.
187
192
  Only this config value triggers it. A typed `branch:current` token, or the one
188
193
  skills forward to `sassy-commit`, does not suppress the PR.
189
194
 
@@ -287,6 +292,12 @@ targets. `hooks.pr.staging` means *PRs whose source is staging*.
287
292
  | `after_create` | `sassy-commit-push-pr` | the PR was just created — not on an update |
288
293
  | `before_merge` | `sassy-babysit` | the PR looks ready **and** this run will merge it |
289
294
  | `after_merge` | `sassy-babysit` | this run observed the PR merged |
295
+ | `hooks.push.after_push` | `sassy-ship` | right after a successful push under `commit.branch: current` |
296
+
297
+ `hooks.push` has the same shape and resolution as `hooks.pr`, but its key is the
298
+ pushed head branch and its only point is `after_push`. It runs only under
299
+ `commit.branch: current`, in a single `remote` repo, never after a rejected push
300
+ or in a workspace.
290
301
 
291
302
  ### Resolution
292
303
 
@@ -317,15 +328,20 @@ in review, and commented when it is deliberate.
317
328
  - **Names**: a skill the project owns, never one of ours.
318
329
  - **Order**: declared order, one worker each, sequential.
319
330
  - **Brief**: plan path, changed files, artifact paths, base, branch, commit hash,
320
- and the PR URL where one exists.
331
+ and the PR URL where one exists. `after_push` has no PR and also gets the
332
+ pushed hash and the upstream.
321
333
  - **Result**: `done`, `blocked`, or `needs-decision`; a decision comes back to the
322
334
  orchestrator, which holds the gate.
323
335
  - **Fail closed**: a missing skill or a `blocked` result stops the pipeline.
324
- - **Writes**: only `before_create` may also commit, because it runs after the
325
- pipeline's commit; every other point leaves the tree clean.
326
- - **Never**: push, open a PR, change `mode`, `branch`, or `merge`.
336
+ - **Writes**: `before_create` may also commit, because it runs after the
337
+ pipeline's commit. `after_push` may commit and push the checked-out head and
338
+ push tags, never forcing, opening or merging a PR, or touching another branch.
339
+ Every other point leaves the tree clean.
340
+ - **Never**: push (bar `after_push`, above), open a PR, change `mode`, `branch`,
341
+ or `merge`.
327
342
  - **Idempotent**: `after_merge` can be reached by a later run observing an
328
- already merged PR, and `before_create` can run again on a re-ship.
343
+ already merged PR, `before_create` can run again on a re-ship, and `after_push`
344
+ runs after an up-to-date push (nothing new) too.
329
345
  - **Per PR**: in a workspace fan-out the hooks run once per PR.
330
346
 
331
347
  ### When they do not fire
@@ -365,8 +381,9 @@ per-PR say-so, because one switch would merge N PRs nobody re-read.
365
381
  - `git.repo` is `workspace`, `none`, or one existing remote name.
366
382
  - `git.remote` is required when `git.repo: workspace`; forbidden otherwise.
367
383
  `git.mirror_branch` and `repos` are workspace-only too.
368
- - `hooks` is allowed only with the four keys under `hooks.pr`, each a list of
369
- skill names that resolve to `.agents/skills/<name>/SKILL.md`.
384
+ - `hooks` is allowed only with the four keys under `hooks.pr` and `after_push`
385
+ under `hooks.push`, each a list of skill names that resolve to
386
+ `.agents/skills/<name>/SKILL.md`.
370
387
  - `commit.branch` is `current` or `new`; `pr.*` are `true` or `false`. Write
371
388
  booleans as `true`/`false`, never `on`/`off` — bare `on`/`off` are YAML 1.1
372
389
  booleans and parse inconsistently.
@@ -377,7 +394,7 @@ per-PR say-so, because one switch would merge N PRs nobody re-read.
377
394
 
378
395
  `scripts/detect.sh --check` enforces all of the above and reports each breach as
379
396
  a `drift:` line, exiting non-zero. When the suite is installed in project
380
- scope it also verifies the vendored pin offline: every `.agents/skills/sassy-*` folder is hashed with the `skills` CLI's own
397
+ scope it also verifies the vendored pin offline: every `.agents/skills/<name>` folder whose name is a suite skill (a name in the suite's roster, `assets/roster` in sassy-setup, not merely `sassy-`-prefixed) is hashed with the `skills` CLI's own
381
398
  definition and compared to `computedHash` in `skills-lock.json`, the lock is
382
399
  checked against the installed set in both directions, and git-tracked state of
383
400
  the lock is reported. A stale, hand-edited, or half-installed suite is drift
@@ -52,6 +52,24 @@ START="${ROOT_ARG:-$PWD}"
52
52
  START="$(cd "$START" && pwd -P)"
53
53
 
54
54
  SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
55
+
56
+ # The suite roster ships with sassy-setup (assets/roster, one skill name per
57
+ # line). Only these names are "ours"; a project skill that merely starts with
58
+ # `sassy-` is the project's. Never derived from sibling folders: in project scope
59
+ # those are the project's own skills. Empty/missing falls back to the prefix.
60
+ SUITE_ROSTER=""
61
+ if [[ -s "$SKILL_DIR/assets/roster" ]]; then
62
+ while IFS= read -r _n || [[ -n "$_n" ]]; do
63
+ _n="${_n//[$'\r\t ']/}"
64
+ [[ -n "$_n" ]] && SUITE_ROSTER="${SUITE_ROSTER:+$SUITE_ROSTER,}$_n"
65
+ done < "$SKILL_DIR/assets/roster"
66
+ fi
67
+ is_suite_skill() {
68
+ if [[ -n "$SUITE_ROSTER" ]]; then
69
+ case ",$SUITE_ROSTER," in *",$1,"*) return 0 ;; *) return 1 ;; esac
70
+ fi
71
+ [[ "$1" == sassy-* ]]
72
+ }
55
73
  ASSET_SNAPSHOT="$SKILL_DIR/assets/snapshot"
56
74
  ASSET_WORKSPACE="$SKILL_DIR/assets/workspace"
57
75
 
@@ -189,15 +207,35 @@ map_match() {
189
207
 
190
208
  base_for_head() { map_match base_map "$1"; }
191
209
 
210
+ # hook_patterns [KIND] — the head patterns declared under hooks.<kind> (pr by default).
192
211
  hook_patterns() {
193
- yaml_flat | awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n==4 && a[1]=="hooks" && a[2]=="pr") print a[3]}' | sort -u
212
+ yaml_flat | awk -F'\t' -v us="$US" -v k="${1:-pr}" '{n=split($1,a,us); if (n==4 && a[1]=="hooks" && a[2]==k) print a[3]}' | sort -u
213
+ }
214
+
215
+ # hook_points KIND — the single source of point names; empty for an unknown kind.
216
+ hook_points() {
217
+ case "$1" in
218
+ pr) printf '%s' "before_create after_create before_merge after_merge" ;;
219
+ push) printf '%s' "after_push" ;;
220
+ esac
194
221
  }
195
222
 
196
- # hooks_for_head_point HEAD POINT — exact head, then the longest matching
223
+ # hooks_declared KIND — succeeds when hooks.<kind> names at least one skill.
224
+ hooks_declared() {
225
+ local kind="$1" pat point
226
+ while IFS= read -r pat; do
227
+ for point in $(hook_points "$kind"); do
228
+ [[ -n "$(list_items "$(yflat "hooks${US}${kind}${US}${pat}${US}${point}")")" ]] && return 0
229
+ done
230
+ done < <(hook_patterns "$kind")
231
+ return 1
232
+ }
233
+
234
+ # hooks_for_head_point HEAD POINT [KIND] — exact head, then the longest matching
197
235
  # family, then "*". A pattern that declares no entry for this point inherits.
198
236
  hooks_for_head_point() {
199
- local head="$1" point="$2" pat stem best="" bestlen=0 v
200
- v="$(yflat "hooks${US}pr${US}${head}${US}${point}")"
237
+ local head="$1" point="$2" kind="${3:-pr}" pat stem best="" bestlen=0 v
238
+ v="$(yflat "hooks${US}${kind}${US}${head}${US}${point}")"
201
239
  [[ -n "$v" ]] && { printf '%s' "$v"; return; }
202
240
  while IFS= read -r pat; do
203
241
  case "$pat" in *"*") ;; *) continue ;; esac
@@ -206,12 +244,12 @@ hooks_for_head_point() {
206
244
  if [[ "$head" == "$stem"* ]] && (( ${#stem} > bestlen )); then
207
245
  best="$pat"; bestlen=${#stem}
208
246
  fi
209
- done < <(hook_patterns)
247
+ done < <(hook_patterns "$kind")
210
248
  if [[ -n "$best" ]]; then
211
- v="$(yflat "hooks${US}pr${US}${best}${US}${point}")"
249
+ v="$(yflat "hooks${US}${kind}${US}${best}${US}${point}")"
212
250
  [[ -n "$v" ]] && { printf '%s' "$v"; return; }
213
251
  fi
214
- printf '%s' "$(yflat "hooks${US}pr${US}*${US}${point}")"
252
+ printf '%s' "$(yflat "hooks${US}${kind}${US}*${US}${point}")"
215
253
  }
216
254
 
217
255
  detect_base() {
@@ -331,7 +369,7 @@ if (( CHECK )); then
331
369
  repos.*) ;;
332
370
  commit.branch) ;;
333
371
  pr.babysit|pr.merge|pr.delete_branch) ;;
334
- hooks.pr.*) ;; # shape checked with the hooks
372
+ hooks.*) ;; # shape checked with the hooks
335
373
  *) bad "unknown key '$key' — it is ignored, so the run uses the default" ;;
336
374
  esac
337
375
  done < <(yaml_flat "$CONFIG")
@@ -482,39 +520,48 @@ if (( CHECK )); then
482
520
  if [[ -n "$(yflat "hooks${US}pr${US}before_create")" ]]; then
483
521
  bad "hooks.pr.<point> is now nested by head branch — write hooks.pr.\"*\".<point>"
484
522
  fi
485
- while IFS= read -r pat; do
486
- [[ -n "$pat" ]] || continue
487
- case "$pat" in
488
- "*") ;;
489
- *"*") [[ "${pat%\*}" != *"*" ]] || bad "hook pattern '$pat': only one trailing * is allowed" ;;
490
- esac
491
- for point in before_create after_create before_merge after_merge; do
492
- val="$(yflat "hooks${US}pr${US}${pat}${US}${point}")"
493
- [[ -n "$val" ]] || continue
494
- while IFS= read -r entry; do
495
- [[ -n "$entry" ]] || continue
496
- name="${entry%% *}"
497
- case "$name" in
498
- sassy-*) bad "hooks.$pat.$point: '$name' is one of our skills — hooks are project skills only" ;;
499
- *) hook_skill_path "$name" >/dev/null 2>&1 \
500
- || bad "hooks.$pat.$point: '$name' not found at .agents/skills/$name/SKILL.md" ;;
501
- esac
502
- done < <(list_items "$val")
503
- done
504
- done < <(hook_patterns)
523
+ for kind in pr push; do
524
+ while IFS= read -r pat; do
525
+ [[ -n "$pat" ]] || continue
526
+ case "$pat" in
527
+ "*") ;;
528
+ *"*") [[ "${pat%\*}" != *"*" ]] || bad "hook pattern '$pat': only one trailing * is allowed" ;;
529
+ esac
530
+ for point in $(hook_points "$kind"); do
531
+ val="$(yflat "hooks${US}${kind}${US}${pat}${US}${point}")"
532
+ [[ -n "$val" ]] || continue
533
+ while IFS= read -r entry; do
534
+ [[ -n "$entry" ]] || continue
535
+ name="${entry%% *}"
536
+ if is_suite_skill "$name"; then
537
+ bad "hooks.$kind.$pat.$point: '$name' is one of our skills — hooks are project skills only"
538
+ else
539
+ hook_skill_path "$name" >/dev/null 2>&1 \
540
+ || bad "hooks.$kind.$pat.$point: '$name' not found at .agents/skills/$name/SKILL.md"
541
+ fi
542
+ done < <(list_items "$val")
543
+ done
544
+ done < <(hook_patterns "$kind")
545
+ done
505
546
 
506
- # `hooks.pr.<head>.<point>` is the only shape, and the four points are the
507
- # only moments a skill asks for. A fifth point name is a step that never fires.
547
+ # `hooks.<kind>.<head>.<point>` is the only shape. hooks.pr has four points and
548
+ # hooks.push has one; any other point name is a step that never fires.
508
549
  while IFS=$'\t' read -r depth hpath; do
509
550
  [[ -n "$depth" ]] || continue
551
+ kind="${hpath#hooks$US}"; kind="${kind%%$US*}"
552
+ case "$kind" in
553
+ pr|push) ;;
554
+ *) bad "hooks kind '$kind' is not one of pr|push"; continue ;;
555
+ esac
510
556
  if [[ "$depth" != "4" ]]; then
511
557
  bad "hooks entry '${hpath//$US/.}' is not head -> point -> list"
512
558
  continue
513
559
  fi
514
560
  point="${hpath##*$US}"
515
- case "$point" in
516
- before_create|after_create|before_merge|after_merge) ;;
517
- *) bad "hooks point '$point' is not one of before_create|after_create|before_merge|after_merge" ;;
561
+ points="$(hook_points "$kind")"
562
+ case " $points " in
563
+ *" $point "*) ;;
564
+ *) bad "hooks.$kind point '$point' is not one of ${points// /|}" ;;
518
565
  esac
519
566
  done < <(yaml_flat "$CONFIG" \
520
567
  | awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n>=2 && a[1]=="hooks") print n "\t" $1}')
@@ -524,9 +571,11 @@ if (( CHECK )); then
524
571
  if [[ "$TOPOLOGY" == "repo" ]]; then
525
572
  note " base for '$HEAD_ARG': $(base_for_head "$HEAD_ARG")"
526
573
  fi
527
- for point in before_create after_create before_merge after_merge; do
528
- resolved="$(hooks_for_head_point "$HEAD_ARG" "$point")"
529
- note " head '$HEAD_ARG' → $point: $( [[ -n "$resolved" ]] && printf '%s' "$resolved" || printf 'none' )"
574
+ for kind in pr push; do
575
+ for point in $(hook_points "$kind"); do
576
+ resolved="$(hooks_for_head_point "$HEAD_ARG" "$point" "$kind")"
577
+ note " head '$HEAD_ARG' → $point: $( [[ -n "$resolved" ]] && printf '%s' "$resolved" || printf 'none' )"
578
+ done
530
579
  done
531
580
  fi
532
581
 
@@ -601,16 +650,30 @@ if (( CHECK )); then
601
650
  esac
602
651
  fi
603
652
 
653
+ # Hooks that cannot fire are a note, not drift: the config is legal, the step
654
+ # just never runs. hooks.push needs `current` in a single remote repo.
655
+ if [[ "$val" == "current" ]]; then
656
+ if hooks_declared pr; then
657
+ note " hooks.pr entries are declared but commit.branch is current — no PR, so they never run"
658
+ fi
659
+ if hooks_declared push && [[ "$configured_repo" == "workspace" || "$configured_repo" == "none" ]]; then
660
+ note " hooks.push entries are declared but git.repo is '$configured_repo' — they never run"
661
+ fi
662
+ elif hooks_declared push; then
663
+ note " hooks.push entries are declared but commit.branch is not current — they never run"
664
+ fi
665
+
604
666
  # The pin. A config can match the tree perfectly while the vendored suite is
605
667
  # stale, edited, or half-installed, and every skill downstream then runs
606
668
  # something other than what the lock says. Offline, no network.
669
+ [[ -n "$SUITE_ROSTER" ]] || note " suite roster not found — falling back to the sassy-* name prefix"
607
670
  if command -v node >/dev/null 2>&1; then
608
671
  while IFS=$'\t' read -r kind msg; do
609
672
  case "$kind" in
610
673
  drift) bad "$msg" ;;
611
674
  note) note " $msg" ;;
612
675
  esac
613
- done < <(node "$SKILL_DIR/scripts/lockcheck.mjs" --root "$ROOT" 2>/dev/null || true)
676
+ done < <(node "$SKILL_DIR/scripts/lockcheck.mjs" --root "$ROOT" --roster "$SUITE_ROSTER" 2>/dev/null || true)
614
677
  else
615
678
  note " node not found — the vendored pin is unverified (the skills CLI needs node)"
616
679
  fi
@@ -949,7 +1012,7 @@ cat <<'EOF'
949
1012
 
950
1013
  # --- Commit ---------------------------------------------------------------
951
1014
  # current: commit on the checked-out branch, even on a base branch, then push
952
- # it to its upstream. No PR: pr.* and hooks.pr are ignored.
1015
+ # it to its upstream. No PR: pr.* and hooks.pr are ignored; hooks.push runs.
953
1016
  # new: never commit on a base branch — sassy-work, sassy-lfg, and sassy-debug
954
1017
  # cut a branch at the start of the run and stay on it.
955
1018
  commit:
@@ -966,7 +1029,8 @@ kv delete_branch false 24 '# true | false — delete the head branch once merged
966
1029
  cat <<'EOF'
967
1030
 
968
1031
  # --- Hooks ----------------------------------------------------------------
969
- # Project steps injected into the PR pipeline, keyed by the HEAD branch — the
1032
+ # Project steps injected into the PR pipeline, or after a push under
1033
+ # commit.branch: current, keyed by the HEAD branch — the
970
1034
  # branch the PR comes from, never the one it targets. `"*"` is the default;
971
1035
  # a name overrides per point, and `release/*` matches a family. Each entry is
972
1036
  # `<skill> <args…>`, resolved at .agents/skills/<name>/SKILL.md; args are passed
@@ -984,4 +1048,7 @@ cat <<'EOF'
984
1048
  # before_create: []
985
1049
  # release/*: # a family of heads
986
1050
  # after_merge: [notify mode:auto]
1051
+ # push: # commit.branch: current only; keyed by the pushed branch
1052
+ # "*":
1053
+ # after_push: []
987
1054
  EOF
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- // Verify the vendored sassy-* folders against skills-lock.json.
2
+ // Verify the vendored suite skill folders against skills-lock.json.
3
3
  //
4
4
  // The suite installs in one of two scopes, like the agents: the project
5
5
  // (vendored into .agents/skills and pinned in skills-lock.json) or the user
@@ -12,7 +12,9 @@
12
12
  // path — so "identical to the pin" is a fact this script asserts, not a claim
13
13
  // the agent has to make in prose.
14
14
  //
15
- // Usage: lockcheck.mjs [--root DIR]
15
+ // Usage: lockcheck.mjs [--root DIR] [--roster a,b,c]
16
+ // A suite skill is a name in --roster (assets/roster in sassy-setup); without
17
+ // one, any name starting with `sassy-`.
16
18
  // Prints "<drift|note>\t<message>" per finding and always exits 0: the caller
17
19
  // owns the verdict and the formatting.
18
20
 
@@ -23,12 +25,17 @@ import { homedir } from "node:os";
23
25
  import { join, relative } from "node:path";
24
26
 
25
27
  const SUITE = "sassywares/sassy-skills";
26
- const SASSY = /^sassy-/;
28
+ let roster = null; // suite skill names (--roster a,b,c); null falls back to the sassy- prefix
29
+ const isSuite = (name) => (roster ? roster.has(name) : /^sassy-/.test(name));
27
30
 
28
31
  const argv = process.argv.slice(2);
29
32
  let root = process.cwd();
30
33
  for (let i = 0; i < argv.length; i += 1) {
31
- if (argv[i] === "--root") {
34
+ if (argv[i] === "--roster") {
35
+ const names = (argv[i + 1] ?? "").split(",").filter(Boolean);
36
+ roster = names.length > 0 ? new Set(names) : null;
37
+ i += 1;
38
+ } else if (argv[i] === "--root") {
32
39
  root = argv[i + 1];
33
40
  i += 1;
34
41
  }
@@ -65,12 +72,12 @@ async function folderHash(dir) {
65
72
  return hash.digest("hex");
66
73
  }
67
74
 
68
- // sassy-* skills in a skills directory. Follows symlinks: a user scope may link
75
+ // suite skills in a skills directory. Follows symlinks: a user scope may link
69
76
  // each skill to a working copy rather than holding the files.
70
77
  function suiteIn(dir) {
71
78
  if (!existsSync(dir)) return [];
72
79
  return readdirSync(dir).filter(
73
- (name) => SASSY.test(name) && existsSync(join(dir, name, "SKILL.md")),
80
+ (name) => isSuite(name) && existsSync(join(dir, name, "SKILL.md")),
74
81
  );
75
82
  }
76
83
 
@@ -89,7 +96,7 @@ async function main() {
89
96
  return;
90
97
  }
91
98
  if (!existsSync(lockPath)) {
92
- drift(`sassy-* folders in .agents/skills but no skills-lock.json — re-pin with npx skills add ${SUITE}`);
99
+ drift(`suite skill folders in .agents/skills but no skills-lock.json — re-pin with npx skills add ${SUITE}`);
93
100
  return;
94
101
  }
95
102
 
@@ -102,10 +109,10 @@ async function main() {
102
109
  }
103
110
 
104
111
  const pinned = Object.entries(lock.skills ?? {}).filter(
105
- ([name, entry]) => SASSY.test(name) || String(entry.source ?? "").includes("sassy-skills"),
112
+ ([name]) => isSuite(name),
106
113
  );
107
114
  if (pinned.length === 0) {
108
- drift(`skills-lock.json pins no sassy-* skill — install with npx skills add ${SUITE}`);
115
+ drift(`skills-lock.json pins no suite skill — install with npx skills add ${SUITE}`);
109
116
  return;
110
117
  }
111
118
 
@@ -116,7 +123,7 @@ async function main() {
116
123
  }
117
124
 
118
125
  const installed = (await readdir(suite, { withFileTypes: true }))
119
- .filter((entry) => entry.isDirectory() && SASSY.test(entry.name))
126
+ .filter((entry) => entry.isDirectory() && isSuite(entry.name))
120
127
  .map((entry) => entry.name);
121
128
  const installedNames = new Set(installed);
122
129
  const pinnedNames = new Set(pinned.map(([name]) => name));
@@ -141,7 +148,7 @@ async function main() {
141
148
  }
142
149
 
143
150
  if (matched > 0) {
144
- note(`${matched}/${pinned.length} sassy-* skill folders match skills-lock.json byte for byte`);
151
+ note(`${matched}/${pinned.length} suite skill folders match skills-lock.json byte for byte`);
145
152
  }
146
153
 
147
154
  const sources = [...new Set(pinned.map(([, entry]) => String(entry.source ?? "unknown")))];
@@ -18,7 +18,7 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
18
18
 
19
19
  **Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `pr.babysit`, `pr.merge`, and `pr.delete_branch` seed the close-out; `git.repo` decides whether this run commits, snapshots, or refuses; `hooks.pr.*` adds project steps to the PR pipeline. `commit.branch: current` replaces the PR pipeline with a push; see Current policy below.
20
20
 
21
- **Current policy.** `commit.branch: current` in the config is an explicit opt-in to work landing where it stands. Under it the close-out commits on the checked-out branch and pushes it to its upstream, base branch included, and skips the PR entirely: no `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. A user-typed `branch:current` token keeps its usual meaning (commit on the checked-out branch) and does not suppress the PR; neither does the `branch:current` ship forwards to `sassy-commit`.
21
+ **Current policy.** `commit.branch: current` in the config is an explicit opt-in to work landing where it stands. Under it the close-out commits on the checked-out branch and pushes it to its upstream, base branch included, and skips the PR entirely: no `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. `hooks.push.after_push` still runs. A user-typed `branch:current` token keeps its usual meaning (commit on the checked-out branch) and does not suppress the PR; neither does the `branch:current` ship forwards to `sassy-commit`.
22
22
 
23
23
  **How to obtain it.** Before the gate, in both `mode:manual` and `mode:auto`, dispatch one dedicated probe `worker`: run the `sassy-setup` skill's `scripts/detect.sh --branch` with **no `--policy`** and return `configured`, `head`, and the upstream (or that none is set). `configured: current` means the current policy applies. Never take the policy from the commit worker: it runs with the forwarded `branch:current` and always reports `policy: current`.
24
24
 
@@ -28,7 +28,7 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
28
28
 
29
29
  ## Steps (in order)
30
30
 
31
- 1. **Review gate.** In `mode:manual` only: present a compact shipping summary — the plan or topic, the changes from the cycle results, the docs the close-out expects to write, the branch/PR target, the babysit options, and **the hooks resolved for this run's head — point, skill, and args — or that none are declared** — and wait. Under `commit.branch: current`, state instead "commit + push to `<head>`, no PR" and that no PR, babysit, merge, or `hooks.pr.*` (`before_create`, `after_create`, `before_merge`, `after_merge`) will run. In `mode:auto`, skip this gate.
31
+ 1. **Review gate.** In `mode:manual` only: present a compact shipping summary — the plan or topic, the changes from the cycle results, the docs the close-out expects to write, the branch/PR target, the babysit options, for a goal slice the `goal.md` change (slice → `Shipped`) and that babysit will not merge, and **the hooks resolved for this run's head — point, skill, and args — or that none are declared** — and wait. Under `commit.branch: current`, state instead "commit + push to `<head>`, no PR", that no PR, babysit, merge, or `hooks.pr.*` (`before_create`, `after_create`, `before_merge`, `after_merge`) will run, and **the `hooks.push.after_push` entries resolved for `<head>` — skill and args — or that none are declared**. In `mode:auto`, skip this gate.
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.
@@ -37,13 +37,17 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
37
37
  **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.
38
38
  - **`git.repo: workspace`.** Commit code inside each affected repo on the run's shared branch — cut once at the start of the run, `branch:current` from then on — then run `.sassywares/workspace/snapshot`. The snapshot is the workspace's commit and it runs every time, right after approval. A missing or outdated `.sassywares/workspace/snapshot` is a blocker: report it and say to run `sassy-setup`.
39
39
  - **`git.repo: none`.** No commit exists here. Report that the work is not persisted and stop.
40
- 5. **PR, or push.** Under `commit.branch: current` in a `remote` repo, skip the PR: dispatch a `worker` to push the head to its upstream with `git push` (upstream set), or `git push -u <remote> <head>` when the head has no upstream — never force. On a non-fast-forward rejection, stop and report; fetching or rebasing is a stop-and-ask. Return the pushed hash and `<head>`, then end the close-out (step 6 is skipped too). In a workspace, push each affected repo in `repos` order, stop at the first rejection, and return a per-repo table (pushed / rejected / not attempted). The final report says "no PR — hooks.pr.* skipped", in `mode:auto` too. Otherwise, in a `remote` repo, dispatch a `worker`: *load the `sassy-commit-push-pr` skill and follow it with `branch:current` and `babysit:off`, forwarding `base:<branch>` when the caller supplied one* (step 6 owns the babysit). It returns the PR URL. In a `workspace`, open one PR per affected repo — the same branch name in each, `--base` from that repo's own `base_map` when it carries a `.sassywares/config.yaml`, else its `repos` entry — and return a table. A touched repo missing from `repos`, or a base that cannot be resolved, is a stop-and-ask, never a guess. `none` opens nothing.
40
+ 5. **PR, or push.** Under `commit.branch: current` in a `remote` repo, skip the PR: dispatch a `worker` to push the head to its upstream with `git push` (upstream set), or `git push -u <remote> <head>` when the head has no upstream — never force. On a non-fast-forward rejection, stop and report; fetching or rebasing is a stop-and-ask. Return the pushed hash and `<head>`. Then, only after that push succeeded, run the resolved `hooks.push.after_push` entries (see below), and end the close-out (step 6 is skipped too). In a workspace, push each affected repo in `repos` order, stop at the first rejection, and return a per-repo table (pushed / rejected / not attempted); `hooks.push` is not run there — it is defined for a single `remote` repo only. The final report says "no PR — hooks.pr.* skipped" plus the push-hook outcome (ran: <names> / none declared / stopped at <name>), in `mode:auto` too. Otherwise, in a `remote` repo, dispatch a `worker`: *load the `sassy-commit-push-pr` skill and follow it with `branch:current` and `babysit:off`, forwarding `base:<branch>` when the caller supplied one* (step 6 owns the babysit). It returns the PR URL. In a `workspace`, open one PR per affected repo — the same branch name in each, `--base` from that repo's own `base_map` when it carries a `.sassywares/config.yaml`, else its `repos` entry — and return a table. A touched repo missing from `repos`, or a base that cannot be resolved, is a stop-and-ask, never a guess. `none` opens nothing.
41
+
42
+ **Push hooks.** Resolve `hooks.push.after_push` for the pushed head per `references/config.md` in the `sassy-setup` skill; empty means skip. An up-to-date push counts as successful, so the hooks run then too. Run each entry in declared order, one `worker` each: *load the project skill at `.agents/skills/<name>/SKILL.md` and follow it with the entry's args*, briefed with the standard hook brief from `references/config.md` plus the pushed hash and upstream. A missing skill or a `blocked` result stops the close-out and is reported; `needs-decision` is surfaced to the user and the close-out stops there, as with babysit and `sassy-commit-push-pr`. What an `after_push` hook may write is the contract in the same reference.
41
43
 
42
44
  **The PR step owns the PR hooks.** `before_create` and `after_create` run inside `sassy-commit-push-pr`, once per PR; ship neither runs nor repeats them.
43
45
  6. **Babysit.** Skipped under `commit.branch: current`. With `pr.babysit` (default `true`), dispatch a `worker`: *load the `sassy-babysit` skill and follow it for the PR just created, one checkpoint*, forwarding any `merge:on|off` and `delete-branch:on|off` the caller supplied, else `pr.merge` and `pr.delete_branch`. It reports looks-ready or blocked. For a continuous watch, tell the user to run `sassy-babysit` in-session.
44
46
 
45
47
  **One PR per run.** Babysitting a workspace fan-out means one `sassy-babysit` run per PR, and a fan-out is never auto-merged: `pr.merge` and `pr.merge:on` apply to a single-PR run only. A multi-repo merge needs an explicit per-PR say-so.
46
48
 
49
+ **Goal slices.** A plan that sits next to a `goal.md` is a `sassy-goal` slice. The step 4 commit worker sets that slice `Shipped` in `goal.md`'s slice table and names `goal.md` in the commit, since `sassy-commit` stages named files only. Step 6 babysits the PR **without merging** — forward `merge:off` whatever `pr.merge` or the caller says — because `sassy-goal` `mode:check` must run on the open PR first. End the final report with the `sassy-goal <goal path> mode:check` command in the harness's syntax.
50
+
47
51
  ## Rules
48
52
 
49
53
  | Rule | Requirement |
@@ -57,11 +61,11 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
57
61
  | One branch | The branch is cut once, before the first change, by `sassy-work` or `sassy-lfg` (unless `commit.branch: current`). Ship and its docs commit land on it. |
58
62
  | Never create the branch | Ship never cuts a branch. Outside `commit.branch: current`, a head on a base branch with unpublished commits is a stop-and-ask, decided from the commit worker's `state` and `unpublished`. |
59
63
  | Never default | Never push directly to the repo base branch — except under `commit.branch: current`, an explicit opt-in, where ship pushes the checked-out branch (base or not) to its upstream, never forced. |
60
- | Current policy | `commit.branch: current` means commit + push, no PR: no `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. A non-fast-forward push is a stop-and-report; in a workspace the push stops at the first rejected repo. |
64
+ | Current policy | `commit.branch: current` means commit + push, no PR: no `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge; `hooks.push.after_push` still runs (step 5). A non-fast-forward push is a stop-and-report; in a workspace the push stops at the first rejected repo. |
61
65
  | Snapshot after approval | In a workspace, the snapshot runs every time, immediately after the commit approval — never before it, never skipped. |
62
66
  | One PR per run | `pr.babysit` and `pr.merge` are single-PR. A fan-out gets one babysit run per PR and no automatic merge. |
63
- | Hooks are visible | The gate names every hook this run will trigger. A hook that runs unseen is a side effect nobody approved. |
64
- | One owner per hook | `before_create` and `after_create` belong to `sassy-commit-push-pr`; `before_merge` and `after_merge` belong to `sassy-babysit`. Ship never re-runs them. |
67
+ | Hooks are visible | The gate names every hook this run will trigger, `hooks.push` entries included. A hook that runs unseen is a side effect nobody approved. |
68
+ | One owner per hook | `before_create` and `after_create` belong to `sassy-commit-push-pr`; `before_merge` and `after_merge` belong to `sassy-babysit`; `after_push` belongs to ship (step 5). Ship never re-runs the first four. |
65
69
  | Compact I/O | Receive hashes, URLs, and one-line statuses only; never paste diffs. |
66
70
 
67
71
  ## Context and token discipline
@@ -6,7 +6,7 @@ description: >-
6
6
  sassy-cycle. mode:manual (default) asks which to close, mode:auto closes all,
7
7
  mode:return only reports. Use when asked to verify conformance to a plan or
8
8
  intent. Leaves changes uncommitted.
9
- argument-hint: "[plan path + phase, or the intent to validate against] [mode:manual|auto|return]"
9
+ argument-hint: "[plan path [+ phase], or the intent to validate against] [range:<base>..<head>] [mode:manual|auto|return]"
10
10
  ---
11
11
 
12
12
  # Sassy Validate
@@ -33,8 +33,8 @@ Use the mode the caller passed; never pick one yourself.
33
33
 
34
34
  ## Workflow
35
35
 
36
- 1. **Intent.** Resolve the reference: a plan path plus phase (preferred), or an explicit intent the user states. If neither exists, ask and stop.
37
- 2. **Validate.** Dispatch the `validator` with that intent reference.
36
+ 1. **Intent.** Resolve the reference: a plan path plus phase (preferred), a plan path with no phase — the whole plan — or an explicit intent the user states. If none exists, ask and stop.
37
+ 2. **Validate.** Dispatch the `validator` with that intent reference. When the caller passed `range:<base>..<head>`, hand it to the validator as the commit range to validate; otherwise the validator scopes the work itself.
38
38
  3. **Return.** In `mode:return`, return the validator's grade, evidence, and gaps as-is and stop.
39
39
  4. **Conforms?** If the grade is `Conforms`, report it and stop. If `Blocked — insufficient grounding`, report what it needs and stop — do not guess.
40
40
  5. **Choose.** On `Partial` or `Diverges`, in `mode:manual` present the `Gaps` and ask which to close: all / specific / none. In `mode:auto`, take all.
@@ -45,7 +45,7 @@ Use the mode the caller passed; never pick one yourself.
45
45
 
46
46
  | Rule | Requirement |
47
47
  |------|-------------|
48
- | Intent required | Never validate without a plan phase or explicit intent. |
48
+ | Intent required | Never validate without a plan, a plan phase, or an explicit intent. |
49
49
  | Orchestrator only | Never edit code. The `validator` judges, `sassy-cycle` closes. |
50
50
  | Ask first | In `mode:manual`, never change code before the user picks. |
51
51
  | Gap-bound | Close only the chosen gaps. |