@sassywares/skills 0.9.0 → 0.11.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.
Files changed (32) hide show
  1. package/CONCEPTS.md +39 -4
  2. package/README.md +86 -6
  3. package/package.json +1 -1
  4. package/skills/sassy-commit/SKILL.md +1 -1
  5. package/skills/sassy-commit-push-pr/SKILL.md +1 -1
  6. package/skills/sassy-cycle/SKILL.md +1 -1
  7. package/skills/sassy-dogfood/SKILL.md +79 -0
  8. package/skills/sassy-handoff/SKILL.md +2 -1
  9. package/skills/sassy-handoff/references/read.md +1 -1
  10. package/skills/sassy-handoff/references/write.md +1 -1
  11. package/skills/sassy-lfg/SKILL.md +11 -8
  12. package/skills/sassy-plan/SKILL.md +6 -2
  13. package/skills/sassy-plan/references/plan-format.md +28 -8
  14. package/skills/sassy-scout/SKILL.md +4 -3
  15. package/skills/sassy-setup/SKILL.md +26 -9
  16. package/skills/sassy-setup/assets/dogfood-recipe.md +31 -0
  17. package/skills/sassy-setup/assets/roster +2 -0
  18. package/skills/sassy-setup/assets/worktree/_lib.sh +269 -0
  19. package/skills/sassy-setup/assets/worktree/create +104 -0
  20. package/skills/sassy-setup/assets/worktree/list +78 -0
  21. package/skills/sassy-setup/assets/worktree/prune +84 -0
  22. package/skills/sassy-setup/assets/worktree/remove +85 -0
  23. package/skills/sassy-setup/assets/worktree/stop +61 -0
  24. package/skills/sassy-setup/references/branching.md +19 -5
  25. package/skills/sassy-setup/references/config.md +104 -5
  26. package/skills/sassy-setup/references/dogfood.md +245 -0
  27. package/skills/sassy-setup/references/harness.md +14 -5
  28. package/skills/sassy-setup/references/worktree.md +151 -0
  29. package/skills/sassy-setup/scripts/detect.sh +261 -4
  30. package/skills/sassy-ship/SKILL.md +3 -0
  31. package/skills/sassy-work/SKILL.md +15 -11
  32. package/skills/sassy-worktree/SKILL.md +87 -0
@@ -30,13 +30,12 @@ For any other harness, give the skill name and its arguments and let the user in
30
30
 
31
31
  ## Temp files
32
32
 
33
- Every file a skill or agent writes outside the repo goes under **`/tmp/sassywares/<harness>/<purpose>/`** — never loose in `/tmp`, never inside the working tree. Each harness gets its own folder; the harness is detected from its environment (`CLAUDECODE` → `claude`, `PI_CODING_AGENT` → `pi`, else `other`), and `SASSY_HARNESS` overrides it. Directories are `0700`; a symlinked directory, or a `/tmp/sassywares` owned by someone else, aborts rather than being followed.
33
+ Every file a skill or agent writes outside the repo goes under **`/tmp/sassywares/<purpose>/`** — never loose in `/tmp`, never inside the working tree. One folder per purpose, shared by every harness: a handoff written in one harness has to be findable from another, which is the whole point of the file.
34
34
 
35
35
  ```bash
36
36
  SW=/tmp/sassywares
37
- HARNESS="${SASSY_HARNESS:-$(if [ -n "${CLAUDECODE:-}" ]; then echo claude; elif [ -n "${PI_CODING_AGENT:-}" ]; then echo pi; else echo other; fi)}"
38
- DIR="$SW/$HARNESS/<purpose>"
39
- for d in "$SW" "$SW/$HARNESS" "$DIR"; do [ -L "$d" ] && { echo "unsafe symlink: $d" >&2; exit 1; }; done
37
+ DIR="$SW/<purpose>"
38
+ [ -L "$SW" ] && { echo "unsafe symlink: $SW" >&2; exit 1; }
40
39
  (umask 077; mkdir -p "$DIR")
41
40
  [ -O "$SW" ] || { echo "not owned by you: $SW" >&2; exit 1; }
42
41
  ```
@@ -49,4 +48,14 @@ for d in "$SW" "$SW/$HARNESS" "$DIR"; do [ -L "$d" ] && { echo "unsafe symlink:
49
48
  | PR bodies | `prs/` | `sassy-commit-push-pr` |
50
49
  | Anything else — clones, captured output, drafts | `scratch/` | any skill or agent |
51
50
 
52
- Name files so a run can find its own: a UTC timestamp plus a short slug (`20261027T101500Z-fix-checkout.txt`). Delete scratch you no longer need; `/tmp` clearing on reboot covers the rest. A new purpose gets a new row here, not a new top-level folder.
51
+ Name files so a run can find its own: a UTC timestamp, a short slug, and a short random suffix (`20261027T101500Z-fix-checkout-4f2a.txt`). The suffix keeps two harnesses writing in the same second apart, now that they share a folder. A clone or any temporary tree gets its own `mktemp -d` under `scratch/` for the same reason. Delete scratch you no longer need; `/tmp` clearing on reboot covers the rest. A new purpose gets a new row here, not a new top-level folder.
52
+
53
+ **Harness is not a path segment.** It is recorded inside the file where it still matters — a handoff carries `**Harness:**` so a reader knows which agent wrote it — and the resume command is generated for whoever is reading, not for the writer. When a file needs it:
54
+
55
+ ```bash
56
+ HARNESS="${SASSY_HARNESS:-$(if [ -n "${CLAUDECODE:-}" ]; then echo claude; elif [ -n "${PI_CODING_AGENT:-}" ]; then echo pi; else echo other; fi)}"
57
+ ```
58
+
59
+ ## Durable state
60
+
61
+ `/tmp` is for files a run produces and forgets. Anything that must survive a reboot lives under **`~/.sassywares/<purpose>/`**: today that is `worktrees/`, whose checkouts carry uncommitted work (see `worktree.md`). Never put working state under `/tmp`, and never bury durable state inside a checkout — `/tmp` clearing is harmless for a handoff and fatal for a worktree.
@@ -0,0 +1,151 @@
1
+ # Worktrees
2
+
3
+ Parallel work in one repo: each run gets its own checkout, its own branch, and
4
+ its own port, without a second clone and without fighting the checkout somebody
5
+ else is using.
6
+
7
+ Read this when the project has `worktrees.enabled: true`, or when the user asks
8
+ to run two agents in one project.
9
+
10
+ ## Install
11
+
12
+ Setup copies `assets/worktree/*` flat into `.sassywares/worktree/`, makes the
13
+ scripts executable, and wires one `worktree:<script>` alias per script into the
14
+ project's manifest — the same exception `workspace:*` uses. They are tracked: a
15
+ worktree is a checkout of the repo, so every worktree carries the tooling.
16
+
17
+ ```text
18
+ .sassywares/worktree/
19
+ ├── _lib.sh shared helpers; reads `worktrees:`; carries worktree-version
20
+ ├── create add a worktree, claim a port, print the namespace
21
+ ├── list the table; --address / --path for scripting
22
+ ├── stop kill whatever is on that worktree's port
23
+ ├── remove refuse unsafe removals, then delete
24
+ └── prune merged-or-gone candidates; removes only what you approve
25
+ ```
26
+
27
+ Nothing else lives there. No state, no registry, no pid file.
28
+
29
+ `_lib.sh` carries `# worktree-version: N`. Bump `N` when an asset changes;
30
+ `--check` compares the installed copy and reports a stale one. Ask before
31
+ overwriting an existing copy — from the first install it is the project's file.
32
+
33
+ ## Where things live
34
+
35
+ ```text
36
+ ~/.sassywares/worktrees/
37
+ └── <repo>/ <- the worktree home; .repo records which checkout owns it
38
+ ├── .repo absolute path of the main checkout
39
+ ├── ports/ claim directories, one per claimed port
40
+ └── <slug>/ a checkout
41
+ ```
42
+
43
+ `worktrees.dir` sets the parent (default `~/.sassywares/worktrees`). It is the
44
+ one path in the config that may be absolute or start with `~/` — it names
45
+ machine-local state, not something a teammate clones.
46
+
47
+ **Never put checkouts inside `.git` or inside the working tree.** Inside `.git`
48
+ is undocumented and breaks where `.git` is a file (linked worktrees, submodules,
49
+ `--separate-git-dir`). Inside the working tree is destroyed by `git clean -xdf`
50
+ and crawled by every scanner that does not read `.gitignore` (`tsc`, Docker).
51
+
52
+ **Never `rm -rf` the worktree home.** It is full of checkouts with uncommitted
53
+ work; `remove` and `prune` are the only safe exits.
54
+
55
+ ## The namespace
56
+
57
+ `create` derives and prints, for the caller and the hook:
58
+
59
+ | Variable | Example | Use |
60
+ |---|---|---|
61
+ | `WT_PATH` | `~/.sassywares/worktrees/shop/feat-catalog` | where the checkout is |
62
+ | `WT_BRANCH` | `feat/catalog` | the branch, as git names it |
63
+ | `WT_SLUG` | `feat-catalog` | the directory name, port key, registry key |
64
+ | `WT_NAMESPACE` | `shop-feat-catalog` | database schema, compose project, simulator name |
65
+ | `WT_PORT` | `3041` | the private port this checkout owns |
66
+ | `WT_BASE_URL` | `http://localhost:3041` | what to open |
67
+
68
+ Derived, never invented downstream: a hook that needs a database name uses
69
+ `$WT_NAMESPACE` rather than building its own, so two worktrees cannot collide by
70
+ accident.
71
+
72
+ **Ports.** The slug hashes into `worktrees.ports`, then the claim is taken with
73
+ an atomic `mkdir` and probed forward one port at a time on a collision. A claim
74
+ belongs to a slug, so a restarted app returns to the same port, and two slugs
75
+ that hash alike do not fight. `list` probes for liveness and never trusts a
76
+ recorded pid: a killed process leaves nothing to believe.
77
+
78
+ ## Hooks
79
+
80
+ Two points, keyed by head branch like every other hook:
81
+
82
+ ```yaml
83
+ hooks:
84
+ worktree:
85
+ "*":
86
+ after_create: [shop-worktree]
87
+ before_remove: [shop-worktree]
88
+ ```
89
+
90
+ `after_create` runs **after** the checkout exists — that is when a project
91
+ installs dependencies, derives `.env` from `$WT_NAMESPACE`, seeds a database or
92
+ creates a simulator, and copies the session. `before_remove` runs **before** the
93
+ files go, and is where the derived database or device is dropped.
94
+
95
+ A shell script cannot dispatch a skill, so `remove` fails closed: with a hook
96
+ declared and `--hook-ok` missing, it prints `require-hook <name>` and exits `3`.
97
+
98
+ **Never write a hook skill yourself** — the same rule as every other hook. Setup
99
+ records the name; the project writes the body.
100
+
101
+ ## Previewing a worktree
102
+
103
+ `sassy-worktree mode:preview` brings the product up in a checkout and prints
104
+ `how_to_see`, using the dogfood recipe's bring-up steps — everything up to, but
105
+ not including, that section's `Prove it:` step. It leaves the app running, and
106
+ `stop` (or `remove`) reaps it by port.
107
+
108
+ There is no separate preview configuration. How the app comes up is the recipe's
109
+ job, because it is the only place that knowledge is allowed to live.
110
+
111
+ **Sessions and third-party origins.** A worktree gets a fresh, empty
112
+ `.sassywares/session/`. Most providers register one callback URL, so a worktree
113
+ usually cannot log in on its own; the recipe's *Working in a second checkout*
114
+ section says how this project solves that, and the `after_create` hook does it —
115
+ copying or linking the main checkout's session is the common answer. A cookie is
116
+ host-scoped and crosses ports freely; a `localStorage` session is origin-scoped,
117
+ port included, and has to be injected per origin. That difference is worth
118
+ writing down once in the recipe rather than rediscovering it.
119
+
120
+ ## Refusals
121
+
122
+ `remove` refuses, and `prune` skips rows it cannot prove safe:
123
+
124
+ | Condition | Why |
125
+ |---|---|
126
+ | It is the main checkout | the repo itself |
127
+ | Dirty tree | uncommitted work |
128
+ | Commits on no remote | nothing to recover from |
129
+ | Something listening on its port | stop the app first |
130
+ | A `before_remove` hook not yet run | the project has cleanup to do |
131
+
132
+ `--force` skips the dirty and unpushed checks and nothing else. It is never
133
+ implied.
134
+
135
+ ## Concurrency rules
136
+
137
+ - **One worktree per run.** `references/branching.md` decides; a run already on
138
+ a non-base branch reuses it, so a second `sassy-work` in the same checkout does
139
+ not nest another worktree.
140
+ - **Never operate on another worktree.** A delegation brief carries the absolute
141
+ path of the checkout it may touch; `MAIN` is for reading config and listing.
142
+ - **Never `git stash`.** It is repository-global: a stash taken in one worktree
143
+ appears in all of them. A worktree already gives you what stash was for.
144
+ - **Never `git checkout` a branch in two places.** Git refuses it — that refusal
145
+ is a feature, and `create` reports it as such.
146
+ - **Do not copy `node_modules`.** Hardlink copies share inodes, so a rewrite
147
+ through one checkout corrupts the other. Let the package manager's store do
148
+ the deduplicating.
149
+ - **`worktrees.enabled` needs `commit.branch: new`.** Under `current` a run
150
+ commits where it stands and never cuts a branch, so no run would ever create a
151
+ worktree; `--check` notes the combination.
@@ -72,6 +72,7 @@ is_suite_skill() {
72
72
  }
73
73
  ASSET_SNAPSHOT="$SKILL_DIR/assets/snapshot"
74
74
  ASSET_WORKSPACE="$SKILL_DIR/assets/workspace"
75
+ ASSET_WORKTREE="$SKILL_DIR/assets/worktree"
75
76
 
76
77
  # The nearest config wins, walking up. Report where it is if one exists.
77
78
  CONFIG=""
@@ -182,6 +183,46 @@ list_items() {
182
183
  | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//; s/^"//; s/"$//' | grep -v '^$' || true
183
184
  }
184
185
 
186
+ # recipe_lint FILE — structural lint for a dogfood procedure. Prints one message
187
+ # per breach; the caller turns each into a drift line. Nothing is executed: a
188
+ # check run validates the shape of a procedure, it never runs the product.
189
+ recipe_lint() {
190
+ awk '
191
+ BEGIN { pending = 0; sec = ""; sname = ""; prove = 0; step = ""; incomment = 0 }
192
+ index($0, "<!--") { incomment = 1 }
193
+ incomment {
194
+ if (index($0, "-->")) incomment = 0
195
+ next
196
+ }
197
+ index($0, "**Prove it:**") { prove = 1; next }
198
+ /^## / {
199
+ if (sec != "" && !prove)
200
+ printf "section \"%s\" has no **Prove it:** line — it has no verdict\n", sname
201
+ if (pending)
202
+ printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
203
+ pending = 0; prove = 0
204
+ sec = $0; sub(/^## +/, "", sec)
205
+ split(sec, parts, /[ \t]+/); sname = parts[1]
206
+ next
207
+ }
208
+ /^[0-9]+\. / && index($0, "**Do**") {
209
+ if (pending)
210
+ printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
211
+ step = $0; sub(/\..*$/, "", step)
212
+ pending = 1; next
213
+ }
214
+ index($0, "**Expect**") { pending = 0; next }
215
+ END {
216
+ if (pending)
217
+ printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
218
+ if (sec != "" && !prove)
219
+ printf "section \"%s\" has no **Prove it:** line — it has no verdict\n", sname
220
+ if (sec == "")
221
+ printf "has no \"## <section>\" heading — there is nothing to prove\n"
222
+ }
223
+ ' "$1"
224
+ }
225
+
185
226
  # map_match SECTION HEAD — exact key, then the longest matching family, then "*".
186
227
  # base_map uses it, and hooks use the same rule, so "which pattern applies" has
187
228
  # exactly one answer in the whole config.
@@ -217,6 +258,7 @@ hook_points() {
217
258
  case "$1" in
218
259
  pr) printf '%s' "before_create after_create before_merge after_merge" ;;
219
260
  push) printf '%s' "after_push" ;;
261
+ worktree) printf '%s' "after_create before_remove" ;;
220
262
  esac
221
263
  }
222
264
 
@@ -369,6 +411,8 @@ if (( CHECK )); then
369
411
  repos.*) ;;
370
412
  commit.branch) ;;
371
413
  pr.babysit|pr.merge|pr.delete_branch) ;;
414
+ dogfood.enabled|dogfood.recipe|dogfood.reports|dogfood.timeout) ;;
415
+ worktrees.enabled|worktrees.dir|worktrees.ports) ;;
372
416
  hooks.*) ;; # shape checked with the hooks
373
417
  *) bad "unknown key '$key' — it is ignored, so the run uses the default" ;;
374
418
  esac
@@ -520,7 +564,7 @@ if (( CHECK )); then
520
564
  if [[ -n "$(yflat "hooks${US}pr${US}before_create")" ]]; then
521
565
  bad "hooks.pr.<point> is now nested by head branch — write hooks.pr.\"*\".<point>"
522
566
  fi
523
- for kind in pr push; do
567
+ for kind in pr push worktree; do
524
568
  while IFS= read -r pat; do
525
569
  [[ -n "$pat" ]] || continue
526
570
  case "$pat" in
@@ -550,8 +594,8 @@ if (( CHECK )); then
550
594
  [[ -n "$depth" ]] || continue
551
595
  kind="${hpath#hooks$US}"; kind="${kind%%$US*}"
552
596
  case "$kind" in
553
- pr|push) ;;
554
- *) bad "hooks kind '$kind' is not one of pr|push"; continue ;;
597
+ pr|push|worktree) ;;
598
+ *) bad "hooks kind '$kind' is not one of pr|push|worktree"; continue ;;
555
599
  esac
556
600
  if [[ "$depth" != "4" ]]; then
557
601
  bad "hooks entry '${hpath//$US/.}' is not head -> point -> list"
@@ -571,7 +615,7 @@ if (( CHECK )); then
571
615
  if [[ "$TOPOLOGY" == "repo" ]]; then
572
616
  note " base for '$HEAD_ARG': $(base_for_head "$HEAD_ARG")"
573
617
  fi
574
- for kind in pr push; do
618
+ for kind in pr push worktree; do
575
619
  for point in $(hook_points "$kind"); do
576
620
  resolved="$(hooks_for_head_point "$HEAD_ARG" "$point" "$kind")"
577
621
  note " head '$HEAD_ARG' → $point: $( [[ -n "$resolved" ]] && printf '%s' "$resolved" || printf 'none' )"
@@ -650,6 +694,191 @@ if (( CHECK )); then
650
694
  esac
651
695
  fi
652
696
 
697
+ # Worktrees: a switch and three mechanical settings. Creating, claiming, and
698
+ # refusing all belong to the scripts, so this validates only what a run reads.
699
+ wt_on="$(block_value worktrees enabled || true)"
700
+ wt_dir="$(block_value worktrees dir || true)"
701
+ wt_ports="$(block_value worktrees ports || true)"
702
+ case "$wt_on" in
703
+ "") ;;
704
+ true|false) note " worktrees.enabled: $wt_on" ;;
705
+ *) bad "worktrees.enabled '$wt_on' must be true|false" ;;
706
+ esac
707
+ if [[ -n "$wt_ports" ]]; then
708
+ case "$wt_ports" in
709
+ *-*) wt_lo="${wt_ports%%-*}"; wt_hi="${wt_ports##*-}" ;;
710
+ *) wt_lo=""; wt_hi=""; bad "worktrees.ports '$wt_ports' is not <from>-<to>" ;;
711
+ esac
712
+ if [[ -n "$wt_lo" ]]; then
713
+ case "$wt_lo$wt_hi" in
714
+ *[!0-9]*) bad "worktrees.ports '$wt_ports' is not numeric" ;;
715
+ *) if (( wt_lo < 1 || wt_hi > 65535 || wt_lo > wt_hi )); then
716
+ bad "worktrees.ports '$wt_ports' is not a usable port range"
717
+ else
718
+ note " worktrees.ports: $wt_ports"
719
+ fi ;;
720
+ esac
721
+ fi
722
+ fi
723
+
724
+ if [[ "$wt_on" == "true" ]]; then
725
+ if [[ "$TOPOLOGY" != "repo" ]]; then
726
+ bad "worktrees.enabled needs a repo — this folder is '$TOPOLOGY', and a checkout needs git"
727
+ else
728
+ if [[ "$(yflat "commit${US}branch" 2>/dev/null || true)" == "current" ]]; then
729
+ note " worktrees.enabled with commit.branch: current — a run never cuts a branch, so no run creates one"
730
+ fi
731
+
732
+ wt_lib="$ROOT/.sassywares/worktree/_lib.sh"
733
+ if [[ -f "$wt_lib" ]]; then
734
+ installed_wt="$(sed -n 's/^# worktree-version: //p' "$wt_lib" | head -n 1)"
735
+ asset_wt="$(sed -n 's/^# worktree-version: //p' "$ASSET_WORKTREE/_lib.sh" | head -n 1)"
736
+ if [[ -z "$installed_wt" ]]; then
737
+ bad "installed .sassywares/worktree/_lib.sh has no worktree-version line"
738
+ elif [[ -n "$asset_wt" && "$installed_wt" != "$asset_wt" ]]; then
739
+ bad "installed worktree tooling is v${installed_wt}, this skill ships v${asset_wt} — re-run setup"
740
+ else
741
+ note " worktree tooling v${installed_wt}"
742
+ fi
743
+ for helper in create list stop remove prune; do
744
+ [[ -x "$ROOT/.sassywares/worktree/$helper" ]] \
745
+ || bad "missing or not executable: .sassywares/worktree/$helper"
746
+ done
747
+ else
748
+ bad "worktrees.enabled but .sassywares/worktree/_lib.sh is missing — re-run setup"
749
+ fi
750
+
751
+ # A checkout must live outside the working tree — inside it, `git clean
752
+ # -xdf` deletes uncommitted work and every scanner that ignores .gitignore
753
+ # crawls a second copy of the source. And a worktree parked on a configured
754
+ # base is a run that will commit onto a shared branch unobserved.
755
+ root_real="$(cd "$ROOT" && pwd -P)"
756
+ BASE_VALUES="$(yaml_flat "$CONFIG" \
757
+ | awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n==3 && a[1]=="git" && a[2]=="base_map") print $2}' \
758
+ | tr '\n' ' ')"
759
+ wt_paths=()
760
+ while IFS=$'\t' read -r wpath wbranch; do
761
+ [[ -n "$wpath" ]] || continue
762
+ wt_paths+=("$wpath")
763
+ [[ "$wpath" == "$root_real" ]] && continue # the main checkout
764
+ case "$wpath" in
765
+ "$root_real"/*) bad "worktree '$wpath' is inside the working tree — move worktrees.dir outside it" ;;
766
+ esac
767
+ case " $BASE_VALUES " in
768
+ *" $wbranch "*) bad "a worktree holds '$wbranch', which base_map names as a base" ;;
769
+ esac
770
+ done < <(git -C "$ROOT" worktree list --porcelain 2>/dev/null \
771
+ | awk '/^worktree /{p=$2} /^branch /{b=$2; sub(/^refs\/heads\//,"",b); print p "\t" b; p=""} /^detached/{print p "\t(detached)"; p=""}')
772
+
773
+ # Orphan port claims: the worktree is gone but its port is still taken, so
774
+ # a later checkout is pushed off it for no reason.
775
+ wt_homef=""
776
+ d="${wt_dir:-$HOME/.sassywares/worktrees}"
777
+ case "$d" in
778
+ "~") d="$HOME" ;;
779
+ "~/"*) d="$HOME/${d#\~/}" ;;
780
+ /*) ;;
781
+ *) d="$ROOT/$d" ;;
782
+ esac
783
+ cand="$d/$(basename "$ROOT")"
784
+ if [[ -f "$cand/.repo" && "$(cat "$cand/.repo" 2>/dev/null)" != "$root_real" ]]; then
785
+ cand="$d/$(basename "$ROOT")-$(printf '%s' "$root_real" | shasum -a 256 | cut -c1-6)"
786
+ fi
787
+ [[ -d "$cand" ]] && wt_homef="$cand"
788
+ if [[ -n "$wt_homef" && -d "$wt_homef/ports" ]]; then
789
+ for claim in "$wt_homef"/ports/*; do
790
+ [[ -d "$claim" ]] || continue
791
+ owner="$(cat "$claim/owner" 2>/dev/null || true)"
792
+ [[ -n "$owner" ]] || continue
793
+ found=0
794
+ if (( ${#wt_paths[@]} )); then
795
+ for p in "${wt_paths[@]}"; do
796
+ [[ "$p" == *"/$owner" ]] && found=1
797
+ done
798
+ fi
799
+ (( found )) || bad "port $(basename "$claim") is claimed by '$owner', which has no worktree"
800
+ done
801
+ fi
802
+ fi
803
+ fi
804
+
805
+ # Dogfood is a pointer and a switch, never commands: the recipe holds the
806
+ # procedure and its `Prove it:` step is the verdict. Everything below is
807
+ # structural. A check run never runs the product — a validator that boots an
808
+ # app is a validator nobody runs.
809
+ dg_enabled="$(block_value dogfood enabled || true)"
810
+ dg_recipe="$(block_value dogfood recipe || true)"
811
+ dg_reports="$(block_value dogfood reports || true)"
812
+ dg_timeout="$(block_value dogfood timeout || true)"
813
+ case "$dg_enabled" in
814
+ "") ;;
815
+ true|false) note " dogfood.enabled: $dg_enabled" ;;
816
+ *) bad "dogfood.enabled '$dg_enabled' must be true|false" ;;
817
+ esac
818
+ for dkey in recipe reports; do
819
+ case "$dkey" in
820
+ recipe) dpath="$dg_recipe" ;;
821
+ *) dpath="$dg_reports" ;;
822
+ esac
823
+ [[ -n "$dpath" ]] || continue
824
+ case "$dpath" in
825
+ /*|~*) bad "dogfood.$dkey '$dpath' is not relative to the config" ;;
826
+ .|./) bad "dogfood.$dkey is the project root itself" ;;
827
+ *) escapes_root "$dpath" && bad "dogfood.$dkey '$dpath' walks outside the project" ;;
828
+ esac
829
+ done
830
+ if [[ -n "$dg_timeout" ]]; then
831
+ case "$dg_timeout" in
832
+ *[!0-9]*) bad "dogfood.timeout '$dg_timeout' is not a positive integer" ;;
833
+ 0) bad "dogfood.timeout is 0 — a procedure that can never finish" ;;
834
+ *) note " dogfood.timeout: ${dg_timeout}s" ;;
835
+ esac
836
+ fi
837
+
838
+ # Reports are logs and screenshots. A project that drops the ignore line
839
+ # commits them, and nobody notices until the history is heavy. Probed with a
840
+ # child path: `/reports/` names a directory, so git only matches it when the
841
+ # probe goes through the directory — and the directory may not exist yet.
842
+ if [[ "$TOPOLOGY" == "repo" && -n "$dg_reports" ]]; then
843
+ if git -C "$ROOT" check-ignore -q -- "$dg_reports/run.log" 2>/dev/null; then
844
+ note " dogfood.reports is gitignored"
845
+ else
846
+ bad "dogfood.reports '$dg_reports' is not gitignored — a run's logs and screenshots would be committed"
847
+ fi
848
+ fi
849
+
850
+ # A committed session is a credential leak, not merely a heavy history. Only
851
+ # checked once the folder exists, so a project that never uses one is silent.
852
+ if [[ "$TOPOLOGY" == "repo" && -d "$ROOT/.sassywares/session" ]]; then
853
+ if git -C "$ROOT" check-ignore -q -- ".sassywares/session/probe" 2>/dev/null; then
854
+ note " .sassywares/session is gitignored"
855
+ else
856
+ bad ".sassywares/session is not gitignored — a session artifact must never be committed"
857
+ fi
858
+ fi
859
+
860
+ if [[ -n "$dg_recipe" ]]; then
861
+ if [[ ! -f "$ROOT/$dg_recipe" ]]; then
862
+ if [[ "$dg_enabled" == "true" ]]; then
863
+ # Enabled with no procedure is the one state that lies: a planner would
864
+ # write Auto rows against a check that does not exist.
865
+ bad "dogfood.recipe '$dg_recipe' does not exist — run sassy-dogfood mode:discover"
866
+ else
867
+ note " dogfood.recipe: $dg_recipe (written by the first sassy-dogfood run)"
868
+ fi
869
+ else
870
+ while IFS= read -r msg; do
871
+ [[ -n "$msg" ]] || continue
872
+ bad "dogfood.recipe $msg"
873
+ done < <(recipe_lint "$ROOT/$dg_recipe")
874
+ while IFS= read -r line0; do
875
+ [[ -n "$line0" ]] || continue
876
+ bad "dogfood.recipe has a secret-shaped string at line $line0 — env var names only, never a value"
877
+ 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)
878
+ note " dogfood.recipe: $dg_recipe"
879
+ fi
880
+ fi
881
+
653
882
  # Hooks that cannot fire are a note, not drift: the config is legal, the step
654
883
  # just never runs. hooks.push needs `current` in a single remote repo.
655
884
  if [[ "$val" == "current" ]]; then
@@ -1052,3 +1281,31 @@ cat <<'EOF'
1052
1281
  # "*":
1053
1282
  # after_push: []
1054
1283
  EOF
1284
+ cat <<'EOF'
1285
+
1286
+ # --- Worktrees ------------------------------------------------------------
1287
+ # Parallel work in one repo: a checkout per branch, each with its own derived
1288
+ # namespace and port, so two runs never fight over one working tree. enabled:
1289
+ # true lets a run create one instead of working here — and needs
1290
+ # commit.branch: new, because `current` never cuts a branch. The scripts in
1291
+ # .sassywares/worktree/ own the mechanics; nothing else reads these values.
1292
+ worktrees:
1293
+ EOF
1294
+ kv enabled false 34 '# true = a run may work in its own checkout'
1295
+ kv dir '~/.sassywares/worktrees' 34 '# parent of the per-repo folder; ~ is allowed'
1296
+ kv ports 3000-3099 34 '# the range a checkout claims a port from'
1297
+ cat <<'EOF'
1298
+
1299
+ # --- Dogfood --------------------------------------------------------------
1300
+ # Agent QA: a stored procedure that proves a change works in the running
1301
+ # product. This block only points at it — commands live in the recipe, because
1302
+ # a copy here would duplicate the manifest and could not express step order.
1303
+ # The recipe ends each section in a `Prove it:` step whose exit code is the
1304
+ # verdict. enabled: true lets a plan write Mode: Auto QA rows, but only for a
1305
+ # section that actually has one.
1306
+ dogfood:
1307
+ EOF
1308
+ kv enabled false 42 '# true = plan writes Auto QA rows; false = all Manual'
1309
+ kv recipe .sassywares/dogfood/recipe.md 42 '# the procedure; sassy-dogfood writes it'
1310
+ kv reports .sassywares/dogfood/reports 42 '# run output; must stay gitignored'
1311
+ kv timeout 900 42 '# seconds for the whole procedure'
@@ -32,6 +32,8 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
32
32
  2. **Compound (conditional).** If the work produced a qualifying learning, dispatch a `worker` whose task is: *load the `sassy-compound` skill and follow it with `mode:auto`* — with a compact learnings brief (the solved problems, root causes, and solutions taken from the cycle results, not from re-reading the tree). It always gets `mode:auto` because ship's own gate already covered the approval. Skip cleanly when nothing qualifies, and skip entirely when `knowledge.write` is `false`.
33
33
  3. **Handbook (conditional).** If the feature is self-contained and independent enough that a teammate would benefit from a handover, dispatch a `worker` whose task is: *load the `sassy-handbook` skill and follow it* — with the plan path and topic. The worker reads the tree itself. Skip for small or tightly-coupled changes.
34
34
  4. **Commit or snapshot.** After the review gate — never before it — the docs and any remaining code become durable.
35
+
36
+ **Before anything is persisted, check the plan's `Auto` QA rows.** If the plan carries any and one is not `Done` from a passing `sassy-dogfood` report, stop here: report the outstanding rows, the report path, and what it would take to prove them. Ship never commits, pushes, or opens a PR behind an unproven automated row, and never runs the recipe itself — proving is `sassy-work`'s step, and re-running it here would let a red row reach a commit by being retried instead of fixed. A brief and a plan with only `Manual` rows skip this entirely.
35
37
  - **`git.repo` is a remote.** Dispatch a `worker`: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the plan, any new solutions docs, the concepts file, `AGENTS.md`, and any handbook just written — resolved from `artifacts.*`, never hardcoded. The branch already exists: `sassy-work` or `sassy-lfg` cut it before the first change, so the docs belong on it with the phase commits. It returns the hash and subject.
36
38
 
37
39
  **Ship never creates the branch.** Outside `commit.branch: current`, a head on a base branch with unpublished commits is a mis-run — `sassy-work` was supposed to cut before touching code. Ask the commit worker to return `state` and `unpublished` from the `sassy-setup` skill's `scripts/detect.sh --branch`, and stop and ask if they show a base with a non-zero count. Never relocate commits silently, never push to the base. Under `commit.branch: current` this check does not fire: unpublished commits on the head are simply pushed along with the close-out commit.
@@ -52,6 +54,7 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
52
54
 
53
55
  | Rule | Requirement |
54
56
  |------|-------------|
57
+ | Unproven rows stop the close-out | A plan's `Auto` QA row that is not `Done` from a passing dogfood report stops ship before anything is persisted. Ship never runs the recipe itself. |
55
58
  | Review gate | `mode:manual` (default) presents the summary and waits before any write, commit, push, or PR. |
56
59
  | No review | `mode:auto` runs the close-out with no approval gate. Never toggled by the skill. |
57
60
  | All-or-nothing gate | In `mode:manual`, nothing is written until the gate is answered. |
@@ -10,7 +10,7 @@ argument-hint: "<plan path | brief> [phase:<n>] [branch:infer|current|new]"
10
10
 
11
11
  # Sassy Work
12
12
 
13
- **Outcome:** one phase run through `sassy-cycle`, findings fixed, then a single gate that carries both the code approval and the phase's manual QA checklist, marked `Done` only when both pass, committed via `sassy-commit`; then a handoff that continues the **next** phase in a fresh session, or a `sassy-ship` close-out if this was the last phase.
13
+ **Outcome:** one phase run through `sassy-cycle`, findings fixed, then a single gate that carries both the code approval and the phase's QA checklist (`Manual` rows from the user, `Auto` rows from a `sassy-dogfood` report), marked `Done` only when both pass, committed via `sassy-commit`; then a handoff that continues the **next** phase in a fresh session, or a `sassy-ship` close-out if this was the last phase.
14
14
 
15
15
  **Brief input** runs one cycle, presents the code approval gate, commits, and **stops before shipping**.
16
16
 
@@ -31,13 +31,15 @@ If a plan path is given but the file does not exist, run `sassy-plan` first and
31
31
 
32
32
  ## QA gate
33
33
 
34
- Read the plan's `**QA:**` line and its per-phase QA table. QA is manual and it is part of the phase gate, not a separate track: a phase turns `Done` only when the code is approved **and** every QA row for that phase has passed.
34
+ Read the plan's `**QA:**` line and its per-phase QA table. QA is part of the phase gate, not a separate track: a phase turns `Done` only when the code is approved **and** every QA row for that phase has passed.
35
35
 
36
- - The user runs the checks. The agent never ticks a row it did not hear confirmed: a row becomes `Done` only on the user's explicit confirmation in this conversation, with their note recorded.
37
- - A row the user reports failing is a finding. It goes through a rework cycle (step 6) and the gate is presented again; a row that fails again after its rework is `Blocked` with the reason.
38
- - Rows nobody has reported on stay `Pending`, and they keep the phase `In progress`. Never infer, batch-assume, or self-certify a pass.
36
+ Rows split by `Mode`, and the split decides who can settle them:
39
37
 
40
- A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA.
38
+ - **`Manual` rows are the user's.** The agent never ticks one it did not hear confirmed: it becomes `Done` only on the user's explicit confirmation in this conversation, with their note recorded.
39
+ - **`Auto` rows are proved, not opined.** Step 4 runs `sassy-dogfood` for the phase's sections before the gate, and a row becomes `Done` only from a report whose verdict is `pass`, with the run id in `Notes`. A failed run is a finding into a rework cycle; the row never becomes `Done` because the agent judged it fine.
40
+ - A row failing again after its rework is `Blocked` with the reason. Rows nobody has reported on stay `Pending`, and they keep the phase `In progress`. Never infer, batch-assume, or self-certify a pass.
41
+
42
+ A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA. A plan's `Auto` rows exist because the project enabled them: `dogfood.enabled` and a recipe section with a `Prove it:` step, per the `sassy-setup` skill's `references/dogfood.md`. Never edit the recipe to turn a red run green — propose the diff and ask.
41
43
 
42
44
  ## Phase gate
43
45
 
@@ -53,12 +55,14 @@ Always gate before committing. The cycle has already fixed and verified its find
53
55
  - work brief = the phase's goal, work items, and "Done when" criteria
54
56
  - intent reference = the plan path and phase
55
57
  4. **Evaluate the phase.** On `Status: done`, the code is ready for the gate, but leave the phase `In progress` — both gates must pass before it closes. On `Status: blocked`, set it `Blocked` in the Phase tracking table and stop; a blocked phase is a real outcome and needs no approval.
56
- 5. **Present the phase gate.** Report the phase, what changed, findings raised and resolved (with the fix passes it took), the simplifications applied, the validator grade, the reviewer summary, and the reviewer's suggestions as options the user may pick. Then give the QA checklist verbatim: each row's ID, check, how to run it, and what passing looks like, with unreported rows `Pending`. Ask for both decisions — code approval (or the changes wanted, including any suggestions picked) and the QA result per row. Wait.
58
+
59
+ **Then prove the `Auto` rows.** If the phase has any, run the `sassy-dogfood` skill in `mode:run` with each row's section named, before the gate and never after it. Record what each report said. A `failed` verdict is a finding, so the phase goes back through step 3's cycle with the failing step and the report's log tail as its findings, and this step runs again; a `class: env` verdict is not a finding — report that the toolchain is broken, leave the phase `In progress`, and stop. An `Auto` row with no report is `Pending`, never `Done`.
60
+ 5. **Present the phase gate.** Report the phase, what changed, findings raised and resolved (with the fix passes it took), the simplifications applied, the validator grade, the reviewer summary, and the reviewer's suggestions as options the user may pick. Then give the QA checklist verbatim: each row's ID, check, `Mode`, and — for `Manual` — how to run it and what passing looks like, and for `Auto` — the dogfood verdict and run id, with unreported rows `Pending`. Ask for both decisions — code approval (or the changes wanted, including any suggestions picked) and the result per `Manual` row. Wait.
57
61
  6. **Resolve the gate.** Three outcomes, nothing in between:
58
62
  - **Code approved and every QA row passes** → go to step 7.
59
- - **Code approved, QA still pending** → record that code is approved but leave the phase `In progress`, tick nothing, commit nothing, hand off nothing, and report that the phase is waiting on manual QA plus the command that resumes it.
60
- - **Changes requested, or any QA row fails** → a rework cycle: load `sassy-cycle` with the requested changes and the failing rows as its findings, and the plan path and phase as the intent reference. On `done`, present the gate again from step 5; on `blocked`, mark the phase `Blocked` and stop. A QA row that fails again after its rework is `Blocked` with the reason and stops the phase. Change requests have no cap — each one is the user's call.
61
- 7. **Commit the phase.** On both gates passing, first mark the phase's QA rows `Done` with the user's notes and the phase `Done` in the Phase tracking table, then persist according to `git.repo`:
63
+ - **Code approved, `Manual` rows still pending** → record that code is approved but leave the phase `In progress`, tick nothing, commit nothing, hand off nothing, and report that the phase is waiting on manual QA plus the command that resumes it.
64
+ - **Changes requested, or any row fails** → a rework cycle: load `sassy-cycle` with the requested changes and the failing rows as its findings, and the plan path and phase as the intent reference. On `done`, re-prove the `Auto` rows (step 4) and present the gate again from step 5; on `blocked`, mark the phase `Blocked` and stop. A QA row that fails again after its rework is `Blocked` with the reason and stops the phase. Change requests have no cap — each one is the user's call.
65
+ 7. **Commit the phase.** On both gates passing, first mark the phase's QA rows `Done` — `Manual` rows with the user's notes, `Auto` rows with the verdict and run id from the report — and the phase `Done` in the Phase tracking table, then persist according to `git.repo`:
62
66
 
63
67
  - **A remote** — dispatch a `worker` whose task is: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the phase's code changes, the QA table results, and the now-updated Phase tracking table. It returns the hash and subject. The branch already exists: step 2 cut it, so committing on it is the point of `branch:current` here.
64
68
  - **`workspace`** — dispatch a `worker` per affected repo to commit that repo's code on the run's shared branch, then run `.sassywares/workspace/snapshot` for the plan, QA results, and docs at the root. The gate's approval is the commit approval; the snapshot runs right after it and is never skipped. A missing or outdated `.sassywares/workspace/snapshot` is a blocker — say to run `sassy-setup`.
@@ -92,7 +96,7 @@ When the argument is not a plan path, it is one settled brief:
92
96
  | Gate before commit and handoff | Do not commit, hand off, or close out until the user approves the code and the phase QA rows pass. |
93
97
  | Commit per phase | Commit the phase, its QA results, and the plan update via `sassy-commit` before handoff or close-out. |
94
98
  | Done needs both gates | Mark a phase `Done` only when the user approves the code and every QA row for that phase is `Done`, never before. |
95
- | QA rows follow the user | Tick a QA row `Done` only from the user's explicit confirmation; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
99
+ | QA rows follow their mode | Tick a `Manual` row `Done` only from the user's explicit confirmation, and an `Auto` row only from a passing dogfood report; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
96
100
  | Send-backs are rework | Requested changes and failed QA rows go through `sassy-cycle` as findings — verified, two fix passes at most — never a direct edit. |
97
101
  | No shipping on the brief path | The brief path commits and stops. Shipping is `sassy-ship` or `sassy-lfg`. |
98
102