@codewizard-dt/bootstrap 2.17.0 → 2.18.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 (39) hide show
  1. package/lib/hooks/README.md +94 -3
  2. package/lib/hooks/absolute-path-guard.js +5 -0
  3. package/lib/hooks/claude-settings-guard.js +5 -0
  4. package/lib/hooks/env-content-read-guard.js +13 -3
  5. package/lib/hooks/env-file-guard.js +42 -0
  6. package/lib/hooks/interpreter-indirection-guard.js +7 -0
  7. package/lib/hooks/lib/command-parse.js +8 -0
  8. package/lib/hooks/lib/serena-languages.js +94 -1
  9. package/lib/hooks/lib/serena.js +228 -0
  10. package/lib/hooks/mv-absolute-path-block.js +84 -3
  11. package/lib/hooks/package-install-consent.js +11 -0
  12. package/lib/hooks/protected-write-guard.js +7 -0
  13. package/lib/hooks/serena-bash-grep-block.js +507 -44
  14. package/lib/hooks/serena-first-glob-guard.js +65 -20
  15. package/lib/hooks/serena-first-guard.js +98 -2
  16. package/lib/hooks/serena-first-read-guard.js +92 -2
  17. package/lib/hooks/serena-pre-delegation.js +123 -0
  18. package/lib/hooks/serena-write-guard.js +56 -3
  19. package/lib/scripts/README.md +296 -1
  20. package/lib/scripts/bootstrap-prefs.js +734 -0
  21. package/lib/scripts/install-global.sh +147 -18
  22. package/lib/scripts/install-mcps.sh +102 -14
  23. package/lib/scripts/lib.sh +581 -11
  24. package/lib/scripts/merge-gitignore.sh +201 -15
  25. package/lib/scripts/sync-wiki-scaffold.sh +33 -4
  26. package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
  27. package/lib/scripts/templates/bootstrap-prefs-schema.json +175 -0
  28. package/lib/scripts/update-project.sh +42 -9
  29. package/lib/skills/README.md +2 -1
  30. package/lib/skills/bootstrap-config/SKILL.md +154 -0
  31. package/lib/skills/git-commit/SKILL.md +54 -1
  32. package/lib/skills/research/SKILL.md +34 -3
  33. package/lib/skills/simplify/SKILL.md +1 -1
  34. package/lib/skills/uat-auto/SKILL.md +9 -4
  35. package/lib/skills/uat-auto-plus/SKILL.md +6 -6
  36. package/lib/skills/uat-generate/SKILL.md +30 -3
  37. package/lib/skills/uat-walk/UAT-CORE.md +41 -6
  38. package/lib/skills/wiki-query/SKILL.md +48 -8
  39. package/package.json +1 -1
@@ -0,0 +1,154 @@
1
+ ---
2
+ name: bootstrap-config
3
+ description: View, edit, and reset the stored bootstrap preferences that decide which installer prompts are asked and how consent-gated skills behave
4
+ category: executing
5
+ model: claude-haiku-4-5-20251001
6
+ argument-hint: [view | edit | reset] [--global | --project]
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`.
11
+
12
+ # /bootstrap-config — View, edit, and reset stored preferences
13
+
14
+ Bootstrap remembers your answers to installer and skill prompts in two flat JSON files — the global `~/.claude/bootstrap-prefs.json` and the per-project `<project>/.claude/bootstrap-prefs.json` — and every read and write of them goes through the helper `lib/scripts/bootstrap-prefs.js`. This command is the front end to that store: it reads current state with the helper, explains each key from the registry at `lib/scripts/templates/bootstrap-prefs-schema.json`, and changes exactly what you confirm.
15
+
16
+ **CRITICAL ORDERING RULE**: Steps A and B (locate + read current state) MUST complete, and the Step B2 state summary MUST be printed, before any `AskUserQuestion` call. Never prompt against an unread store — the whole point of this command is that the user decides against real current state, not a guess.
17
+
18
+ **Writes go through the helper.** Never write `bootstrap-prefs.json` with `Write` or `Edit`; every change is a `--set` or `--unset` invocation, which is where value validation, `true`/`false` JSON coercion, and atomic writes already live. Never edit `bootstrap-prefs.README.md` at all — that companion is generated output, rewritten on every successful `--set`/`--unset`, and hand edits are overwritten without warning. If this skill ever has to change some *other* file in place, it uses `Edit`, never `Write`.
19
+
20
+ ## Arguments
21
+
22
+ `argument-hint: [view | edit | reset] [--global | --project]`
23
+
24
+ - A mode word (`view` / `edit` / `reset`) preselects the mode and skips the Step C question. Steps A and B still run, and the Step B2 summary is still printed first — a mode word skips a question, never the state read.
25
+ - `--global` / `--project` preselects the layer for reads and pins the write layer, subject to the per-key `scope` check in Step E. A pinned layer that the chosen key's `scope` forbids is refused, not silently redirected.
26
+ - No arguments = the full interactive flow.
27
+
28
+ ---
29
+
30
+ ## Step A — Locate the helper, the schema, and the layers
31
+
32
+ 1. Resolve the helper path. Prefer `lib/scripts/bootstrap-prefs.js` relative to the current project root; if the current project is not this repo, fall back to the installed copy that ships with the bootstrap package. If neither exists, abort with this exact message and stop:
33
+ > No bootstrap preference helper found. Run `npx @codewizard-dt/bootstrap update` (or `./lib/scripts/install-global.sh --skip-mcps`) to install it, then re-run `/bootstrap-config`.
34
+ 2. Resolve the schema path: `lib/scripts/templates/bootstrap-prefs-schema.json`, sitting next to the helper. The helper already defaults to exactly that path, so pass `--schema <path>` **only** when a non-default schema was located.
35
+ 3. Determine `PROJECT_DIR` — the current working directory when inside a git repo / project, otherwise none. Record whether each layer's file exists:
36
+ - project layer: `<PROJECT_DIR>/.claude/bootstrap-prefs.json`
37
+ - global layer: `~/.claude/bootstrap-prefs.json`
38
+
39
+ **Neither file existing is a normal state, not an error.** It means nothing has been answered yet and every key is `unset`. Report it as such and continue — there is still a useful summary to print and still keys that can be set.
40
+
41
+ ## Step B — Read current state before prompting
42
+
43
+ 1. Run the helper exactly once via `Bash`:
44
+ - Inside a project: `node <helper> --list --project "$PROJECT_DIR"`
45
+ - Outside a project, or when `--global` was passed: `node <helper> --list`
46
+
47
+ **`--list` without `--project` consults the global layer only.** Omitting it silently hides every project-layer answer, which is precisely the confusion this command exists to remove — a user staring at a summary that says `unset` while a project file says otherwise. Always pass `--project` when a project directory was resolved. The helper says so itself in its closing line (`No --project given: the project layer was not consulted; showing the global layer only.`); pass that line through if it appears.
48
+ 2. `Read` the schema JSON to obtain `detail`, `values`, `scope`, and `consumer` per key. `--list` prints only the one-line `summary`; the longer `detail` paragraph is what makes an unfamiliar key legible, and the entry's `values` string is the **only** legal source for the options offered in Step E.
49
+ 3. `--list` annotates every row with the layer that supplied it, in brackets — `[project]`, `[global]`, `[default]`, `[unset]`, or `[target]`. Carry that annotation through to the printed summary verbatim. "Which layer supplied this" is half the answer: a value shown without its layer cannot tell the user whether editing global will change anything.
50
+
51
+ ## Step B2 — Print the grouped state summary
52
+
53
+ Print a plain-text summary grouped exactly the way the helper groups it, in this order:
54
+
55
+ 1. **Installer preferences** (`consumer: installer` — read by the setup/update scripts)
56
+ 2. **Skill preferences** (`consumer: skill` — read by slash commands at run time; changing these changes what a command does)
57
+ 3. **Unrecognized keys** (present in a values file, absent from the schema; the helper keeps them untouched) — omit this group when empty
58
+
59
+ Per key show the key name, its current value, the supplying layer in brackets, and the schema `summary`. **Never print a key without its summary** — a bare key name is the exact failure this command exists to fix.
60
+
61
+ ### Render all four states distinguishably, and label them
62
+
63
+ | State | What it means |
64
+ |---|---|
65
+ | `unset` | Absent from every consulted file, and the entry has no `default`. The next run will ask this question. |
66
+ | a settled value | A real stored answer (e.g. `shared`, `auto`, `user`, `true`). |
67
+ | `false` | A **remembered decline** — say so explicitly. This is *not* the same as `unset`; it is stored, it is why the prompt stopped coming back, and only a reset re-opens it. |
68
+ | `ask` | Stored, and means "keep prompting me, do not persist an answer". |
69
+
70
+ Also mark rows whose layer is `[default]`: nothing is stored for that key, the schema default is what is in effect, and the question can still be answered.
71
+
72
+ ### The two dynamic families
73
+
74
+ `guides.*` and `gitignore.section.*` are `dynamic: true` **patterns, not keys**. When the consulted files hold concrete keys under a pattern, `--list` lists those concrete keys and the summary should show them individually. When none exist, `--list` shows the pattern row instead — print it and explain the family rather than showing a literal `.*` with no context:
75
+
76
+ - `guides.*` — one key per optional guide that `sync-wiki-scaffold.sh` can deliver into `wiki/guides/`.
77
+ - `gitignore.section.*` — one key per titled section of the `.gitignore` template, slugified from the section's banner title. Ask the helper for a slug rather than deriving one by hand: `node <helper> --section-key "<banner title>"`.
78
+
79
+ For `gitignore.section.*`, state the one-value grammar plainly: the schema's `values` is `false` **only**. An accepted section is deliberately never recorded (a remembered yes would let a later template version append lines to a project's `.gitignore` without asking), so the only storable answer is a decline, and `--unset` is the only way to make a declined section be offered again.
80
+
81
+ ### View mode ends here
82
+
83
+ In view mode, stop after the summary and print the two follow-ups:
84
+
85
+ ```
86
+ /bootstrap-config edit
87
+ /bootstrap-config reset
88
+ ```
89
+
90
+ ## Step C — The mode question (first `AskUserQuestion`)
91
+
92
+ Issue **one** `AskUserQuestion` (`multiSelect: false`) — only after Step B2 has printed. Options:
93
+
94
+ - `Edit a preference` — change a stored value.
95
+ - `Reset a preference` — remove a key so the installer or skill asks that question again.
96
+ - `No changes` — exit without writing anything. This option is **mandatory and always offered**.
97
+
98
+ Skip this question entirely when a mode word was supplied as an argument — but never skip Step B2's printed summary.
99
+
100
+ ## Step D — Choose the key
101
+
102
+ 1. Issue one `AskUserQuestion` listing the candidate keys, grouped so `consumer: skill` keys are **visibly separate** from `consumer: installer` keys. Include an `Other` free-text affordance for typing a key name directly — the dynamic families can hold more concrete keys than fit in an option list.
103
+ 2. Label each option `<key> — <summary>`, and include its current value and supplying layer. Include a `Back / No changes` option.
104
+ 3. **Reset mode only offers keys that are actually stored in a writable layer.** A key showing `[unset]` or `[default]` has nothing to remove; say so rather than running a no-op `--unset`.
105
+ 4. Once a key is chosen, print its schema `detail` paragraph **in full** before going any further. This is the entire point of the registry: the user decides against the real explanation, including its grammar quirks, not against a key name.
106
+ 5. When the chosen key has `consumer: skill`, print this heavier banner:
107
+ > This is a **skill preference**. Changing it changes what a slash command actually does the next time it runs — not merely whether the installer asks you a question.
108
+
109
+ Name the affected command from the entry's `askedBy` / `summary` — e.g. `gitCommit.versionBump` changes what `/git-commit` does on every commit. The `consumer: skill` population is `gitCommit.versionBump`, `gitCommit.autoPush`, `research.persistToRaw`, `uatGenerate.promoteTests`, and `gitignore.offerSectionUpdates`. Every other key is `consumer: installer` and gets the lighter framing: it only affects whether a setup/update script prompts you.
110
+
111
+ ## Step E — Choose the value and the layer (edit mode)
112
+
113
+ 1. **Offer values parsed from the entry's `values` string** — split on `|`, trim each token. Never a hardcoded list, and never a value the grammar omits. The helper validates against this same string, so an option that is not in it is guaranteed to fail. Two grammars trip people up and must be handled as written:
114
+ - `gitCommit.versionBump` — `values` is `auto | confirm | never`. **`confirm` IS this key's ask state.** Do not offer a separate `ask`; there is none, and offering one produces a hard failure.
115
+ - `gitignore.section.*` — `values` is `false` only. There is intentionally no `true`. Widening it would break `merge-gitignore.sh`'s invariant that nothing is ever added to a project's `.gitignore` without asking.
116
+ 2. **Offer the layer subject to the entry's `scope`:**
117
+ - `scope: project` → the project layer only.
118
+ - `scope: global` → the global layer only.
119
+ - `scope: either` → ask which, explaining that **project wins over global, per key**.
120
+
121
+ Never offer a layer the key's `scope` makes inert. The helper's `--set` does not enforce scope — it will happily write a `global`-scope key into a project file, where nothing ever reads it and the generated companion files it under "Unrecognized keys" with the reason that this layer never consults it. This step is the guard against creating that situation.
122
+ 3. If `scope` requires the project layer but no project directory was resolved in Step A, abort that edit with an explanation. Do not fall back to the global layer.
123
+ 4. Confirm with one final `AskUserQuestion` (`Yes, apply` / `No, cancel`) showing the exact command about to run:
124
+ ```
125
+ node <helper> --set <key> --value <v> --global
126
+ node <helper> --set <key> --value <v> --project "$PROJECT_DIR"
127
+ ```
128
+ `--set` takes **exactly one** layer selector — `--global` or `--project <dir>` (or `--target <path>`, the explicit single-file escape hatch). Zero selectors and two selectors are both usage errors; the helper will not guess which file to write.
129
+ 5. Run it with `Bash` only after confirmation. Two failure modes are loud and correct — surface the helper's message verbatim rather than retrying or working around it:
130
+ - An illegal value exits 1 with the legal list. That is the grammar rejecting a typo, not a bug to route around.
131
+ - The literal values `unset` and `null` are refused outright, with a pointer to `--unset`. Absence is how a key is unset; there is no value that spells it.
132
+
133
+ ## Step F — Reset a key (reset mode)
134
+
135
+ 1. Reset means `--unset`: the key is **deleted** from the values file. Absence is the entire representation of `unset` — `null` and the string `"unset"` are never stored — so the next installer run or skill invocation asks that question again.
136
+ 2. Pick the layer the key is actually stored in, using the `[layer]` annotation captured in Step B. If the same key is stored in **both** layers, say so and ask which to clear: clearing the project layer alone re-exposes the global answer rather than re-opening the question.
137
+ 3. Confirm with one `AskUserQuestion` showing the exact command:
138
+ ```
139
+ node <helper> --unset <key> --global
140
+ node <helper> --unset <key> --project "$PROJECT_DIR"
141
+ ```
142
+ Like `--set`, `--unset` requires exactly one layer selector.
143
+ 4. Run it with `Bash` only after confirmation.
144
+
145
+ ## Step G — Report and re-verify
146
+
147
+ 1. After **any** successful write, re-run the Step B `--list` command and print the changed rows, so the user sees the new value *and its layer* rather than a bare success line. A write that landed in a layer the user did not expect is invisible otherwise.
148
+ 2. Mention that the helper regenerated `bootstrap-prefs.README.md` next to the values file, and that this companion is generated output — read it, never hand-edit it.
149
+ 3. Print the closing pointers:
150
+ ```
151
+ View again: /bootstrap-config view
152
+ Re-open a question: /bootstrap-config reset
153
+ ```
154
+ 4. Close with the same warning the generated companion carries: **a preference file never holds a secret.** No API key, token, or password belongs in it — not in the values file, not in the companion, not in a new schema key.
@@ -10,6 +10,19 @@ user-invocable: true
10
10
 
11
11
  # git-commit
12
12
 
13
+ ## Step 0: Read the two preferences that govern this skill
14
+
15
+ Two stored preferences change what this command does. Read **both, once, before Step 1** — never mid-run, and never once per file:
16
+
17
+ ```bash
18
+ node ~/.claude/bootstrap-prefs.js --get gitCommit.versionBump --project . 2>/dev/null || echo unset
19
+ node ~/.claude/bootstrap-prefs.js --get gitCommit.autoPush --project . 2>/dev/null || echo unset
20
+ ```
21
+
22
+ `--project .` is required. Both keys are `scope: either`, so the answer resolves **project file → global file → schema default**; dropping the flag would read the machine-wide answer even in a repo that overrides it. If either command fails — bootstrap was never installed globally, or `node` is not on PATH — treat that answer as `unset`.
23
+
24
+ `unset` means *nobody has ever been asked*. It always keeps today's behavior; it never invents one. Mention an `unset` key **once**, in the final report, never as a mid-run interruption.
25
+
13
26
  ## Step 1: Run Lint Fix Cycles
14
27
 
15
28
  Before committing, run the `/lint` workflow to catch and fix any diagnostics:
@@ -51,10 +64,25 @@ Use these semver rules to determine the bump:
51
64
  | **minor** | New features or capabilities that are backward-compatible; new commands, skills, config options, or APIs added without breaking existing ones |
52
65
  | **major** | Breaking changes — removed or renamed commands/APIs/config keys, changed behavior that callers must update for, deleted files that others depend on |
53
66
 
54
- Print the summary, then **proceed immediately** with the suggested bump — no user confirmation needed.
67
+ Print the summary. What happens next is decided by `gitCommit.versionBump` from Step 0 — see the table in Step 4. **Do not ask for confirmation here**; the only value that asks is `confirm`, and it asks in Step 4 where the manifest list is known.
55
68
 
56
69
  ## Step 4: Bump Version in Project Files
57
70
 
71
+ ### Gate: `gitCommit.versionBump`
72
+
73
+ Its grammar is `auto | confirm | never` — there is deliberately **no `ask` value**, because `confirm` *is* this key's ask state. Do not look for one.
74
+
75
+ | Value | What to do |
76
+ |-------|------------|
77
+ | `auto` | Today's behavior. Detect every manifest and apply the bump to all of them, no confirmation. |
78
+ | `confirm` | Print the suggested bump **and the full list of manifest files that would change**, then ask once with `AskUserQuestion` before editing anything. Approved → bump exactly as `auto` does. Declined → edit no manifest, and still commit with the subject prefix. Ask **every run** and **never persist the answer** — the standing choice is "keep asking me", so recording a reply would destroy it. |
79
+ | `never` | Touch **no** version file at all. Skip straight to Step 5. The `[patch]`/`[minor]`/`[major]` subject prefix is still written, because downstream release tooling reads that prefix — dropping it would break releases, not just skip a bump. Say so once in the final report: `Version files untouched (gitCommit.versionBump=never); the subject prefix is still set. Change with /bootstrap-config.` |
80
+ | `unset` | Behave exactly as `auto` — that is today's behavior and an unanswered key must never change it. Note once in the final report: `gitCommit.versionBump is unanswered — /git-commit bumps every manifest by default. Set it with: node ~/.claude/bootstrap-prefs.js --set gitCommit.versionBump --value auto --global` (or `confirm` / `never`). |
81
+
82
+ Anything else stored under this key is a value from a newer bootstrap that this skill has no branch for: treat it as `unset`, and say which value you did not recognize.
83
+
84
+ For `auto`, `confirm`-approved, and `unset`, continue below. For `never` and `confirm`-declined, go to Step 5.
85
+
58
86
  Find and update version numbers in project files.
59
87
 
60
88
  ### Detection
@@ -170,3 +198,28 @@ If the change feels too complex to summarize in one line, **make the subject mor
170
198
  - ❌ `[patch] Fix bug` (too vague)
171
199
 
172
200
  Detailed reasoning, before/after examples, and rationale belong in **PR descriptions**, not in commit message bodies. The commit subject is the index entry; the PR is the encyclopedia.
201
+
202
+ ## Step 6: Push (gated on `gitCommit.autoPush`)
203
+
204
+ Runs only after the commit in Step 5 succeeded. A failed commit means there is nothing to push.
205
+
206
+ | Value | What to do |
207
+ |-------|------------|
208
+ | `true` | `git push` the **current** branch. Nothing else. |
209
+ | `false` | Do not push. Say so once in the final report: `Committed locally; not pushed (gitCommit.autoPush=false). Change with /bootstrap-config.` |
210
+ | `ask` | Ask once with `AskUserQuestion` whether to push this commit. Honor the answer for **this run only** and **never persist it** — `ask` is a settled answer whose content is "keep asking me", and writing a reply would overwrite it. |
211
+ | `unset` | **Do not push.** This is the one key whose `unset` is not the schema-friendliest reading but the compatibility-correct one: today's behavior is that this skill never pushes, and defaulting an unanswered key to an outward-facing action that publishes code would break the guarantee that an absent preferences file changes nothing. Note once in the final report: `gitCommit.autoPush is unanswered — /git-commit does not push. Set it with: node ~/.claude/bootstrap-prefs.js --set gitCommit.autoPush --value true --global` (or `false` / `ask`). |
212
+
213
+ ### ⛔ The push is the plainest possible push
214
+
215
+ - **The Step 5 branch rule is unchanged and still absolute.** Never run `git branch`, `git checkout -b`, or `git switch -c`. Pushing an existing branch is all this step ever does.
216
+ - Never pass `--force`, `--force-with-lease`, `--set-upstream`/`-u`, `--all`, or `--tags`, and never name a different remote or refspec. Plain `git push`.
217
+ - If the push fails for any reason — no upstream configured, no remote, rejected non-fast-forward, no credentials — **stop and report it**. The commit already succeeded and is safe; do not retry with extra flags, do not set an upstream, and do not attempt to reconcile with a pull or rebase.
218
+
219
+ ## Step 7: Final report
220
+
221
+ One short report at the end. Include, in this order:
222
+
223
+ 1. The commit subject that was written.
224
+ 2. Any of the once-only preference notes from Steps 4 and 6 that apply. Each appears **at most once per run**, here — not inline, and not repeated per file.
225
+ 3. The push outcome (pushed / not pushed and why / push failed and how).
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: research
3
- description: Deep research on a topic using codebase analysis, library docs, and web search — writes the report plus its primary sources to raw/research/<slug>/
3
+ description: Deep research on a topic using codebase analysis, library docs, and web search — by default also writes the report plus its primary sources to raw/research/<slug>/ (preference-gated by research.persistToRaw; findings are always delivered in the reply)
4
4
  category: researching
5
5
  model: claude-sonnet-5
6
6
  effort: high
@@ -145,6 +145,31 @@ Suggest concrete next steps:
145
145
 
146
146
  ## Phase 5: Write Output Files
147
147
 
148
+ ### Phase 5 preference gate
149
+
150
+ This gate governs **only the file write** under `raw/research/`. The research, synthesis, and report from Phases 1–4 are never gated — findings always go in the reply.
151
+
152
+ Read the preference once, before writing anything:
153
+
154
+ ```bash
155
+ node ~/.claude/bootstrap-prefs.js --get research.persistToRaw --project . 2>/dev/null || echo unset
156
+ ```
157
+
158
+ | Value | Behaviour |
159
+ |-------|-----------|
160
+ | `true` | Write both files, as described below. |
161
+ | `false` | Write **nothing** under `raw/research/`. Deliver the full report and the source register in the reply instead, and state once: "Not saved to raw/research/ (research.persistToRaw=false). Change with /bootstrap-config, or re-run with --save to persist just this one." |
162
+ | `ask` | Before writing, ask the user (AskUserQuestion) whether to save this report. Honour the answer for **this run only** — never write it back to the store. |
163
+ | `unset` | Write both files (today's behaviour) and add one line: "research.persistToRaw is unanswered — /research saves by default. Set it with: node ~/.claude/bootstrap-prefs.js --set research.persistToRaw --value <true\|false\|ask> --global" |
164
+
165
+ **Per-run override** (independent of the stored value, and never written to the store):
166
+
167
+ - An explicit per-run instruction in the invocation — `--no-save` / `--no-persist`, or plain language such as "don't save this one" — suppresses the Phase 5 write for that run **even when the stored value is `true`**.
168
+ - The mirror `--save` / "save this one" forces the write **even when the stored value is `false`**.
169
+ - `ask` and the per-run override are different mechanisms serving the same need from opposite directions (`ask` prompts every time by standing choice; the override is a one-off escape from a standing value). Both must keep working.
170
+
171
+ When the write is suppressed, the run is still complete: deliver the report and the register inline, and follow the Phase 6 not-persisted branch.
172
+
148
173
  The synthesis from Phase 4 is the **report**; the register from the Phase 1 callout is the **primary sources**. Persist both under `raw/research/<slug>/` using the **Write tool** (do not rely only on the chat transcript). Create the directory if it does not exist. Write two files — and honor the Phase 1 no-overwrite rule: if `index.md` or `sources.md` already exists, write `index-2.md` / `sources-2.md` (then `-3`, …) carrying only non-redundant new/changed content with a cross-reference back to the prior file.
149
174
 
150
175
  ### `index.md` — the research report
@@ -219,12 +244,18 @@ Rules for this phase:
219
244
 
220
245
  ## Phase 6: Confirm & Suggest Next Steps
221
246
 
222
- After writing the files, tell the user:
247
+ **If the files were written**, tell the user:
223
248
  - The paths written (`raw/research/<slug>/index.md` and `raw/research/<slug>/sources.md`)
224
249
  - A 2–4 bullet summary of the recommendation
225
250
  - That the report is now a `raw/` ground-truth source: **"Run `/wiki-ingest raw/research/<slug>/index.md` to synthesize this research into the knowledge base."**
226
251
  - Any follow-on `/task-add` or `/decision-create` suggested by the findings
227
252
 
253
+ **If nothing was persisted** (stored `false`, a per-run `--no-save`/`--no-persist` override, or a declined `ask`), tell the user:
254
+ - That no files were written, and which of the three reasons applies
255
+ - The same 2–4 bullet summary of the recommendation
256
+ - Skip the `/wiki-ingest` suggestion entirely — there is no `raw/` file to ingest
257
+ - Any follow-on `/task-add` or `/decision-create` suggested by the findings
258
+
228
259
  ---
229
260
 
230
261
  ## Research Quality Standards
@@ -244,7 +275,7 @@ After writing the files, tell the user:
244
275
  3) **Use Serena for code**: Do NOT use Read, Grep, or Glob on code files
245
276
  4) **Maximum 3 sub-processes at a time** if delegating research steps
246
277
  5) **ALWAYS terminate processes when done**
247
- 6) **Always write the output files** to `raw/research/<slug>/` (`index.md` + `sources.md`) with the **Write tool** — the report is not done until it is persisted as a ground-truth source
278
+ 6) **Write the output files whenever the Phase 5 gate allows it** — `raw/research/<slug>/` (`index.md` + `sources.md`) with the **Write tool**, which is the default. When the gate suppresses the write (`research.persistToRaw=false`, or a per-run `--no-save`/`--no-persist`, or a declined `ask`), the findings go in the reply and that is a complete run — never write the files anyway
248
279
  7) **Never overwrite `raw/` files**: if a target already exists, write `<name>-2.md` / `-3.md` instead, carrying only non-redundant new/changed data with a cross-reference to the prior file
249
280
  8) **No fabricated sources**: every row in `sources.md` is a source you actually consulted; mark unsupported claims as inferences rather than inventing citations
250
281
  9) **`raw/research/` is the only `raw/` path this skill may write to** — never modify or delete anything elsewhere under `raw/`
@@ -77,7 +77,7 @@ With user approval:
77
77
 
78
78
  After changes:
79
79
  - For code files:
80
- - Run appropriate quality gates (mypy, typecheck) from `.docs/agent/quality-gates.md`
80
+ - Run the project's quality gates — detect and run its type checkers and tests (`/typecheck` covers detection: tsc/mypy/pyright/go vet/cargo check, etc.)
81
81
  - Ensure no functionality broken
82
82
  - For documentation:
83
83
  - Verify all critical information retained
@@ -25,6 +25,8 @@ Headless variant of `/uat-walk`: run every eligible test, auto-judge from determ
25
25
 
26
26
  **Never auto-pass a test you cannot verify with hard evidence.** Pass requires a machine-checkable match (UAT-CORE Step 4 "Auto-judge criteria"). On any doubt, uncertainty, or missing evidence → `[FAIL: auto-judge: <reason>]`. **Never** `[SKIP: ...]` (a human verdict). **Never** `[x] Pass` unless the criteria are met exactly. A false pass ships a broken feature; a false fail merely gets re-triaged in the next `/uat-walk` — so this is the single most important rule.
27
27
 
28
+ Fail-closed means *no oracle*, not *no curl*. A **unit-backed** test (UAT-CORE Step 3 — carries `Repeatable Unit Test: Created: <path>`) has a real machine-checkable oracle even with no `Endpoint:`/`Command:` field, so run it and judge it rather than sending it to a human. What stays human is the genuinely unverifiable: bare Manual cases with no test file, and every UI case.
29
+
28
30
  ---
29
31
 
30
32
  ## Procedure
@@ -34,7 +36,7 @@ Run UAT-CORE as written, headless throughout:
34
36
  1. **Step 1** — resolve/parse (auto/plus resolution rules: never prompt; auto-pick lowest-numbered pending on empty/unresolved).
35
37
  2. **Step 2** — prerequisites as a **hard gate**: any failed or unverifiable prerequisite aborts → `[FAIL: auto-judge: prerequisite not satisfied — <which>]` on every untested test, then Closure. No repair attempt (that's `/uat-auto-plus`).
36
38
  3. **Step 3 + 3.5** — classify all eligible tests, then stub-detect (leave stubs `- [ ] Pass`, do not execute).
37
- 4. **Step 4** — auto-judge each non-stub test in document order: API/CLI by the machine-checkable criteria; UI and Manual always `[FAIL: auto-judge: ... requires human verification]` (no browser automation, no heuristics). Eligibility = pending + previously-failed.
39
+ 4. **Step 4** — auto-judge each non-stub test in document order by its strongest evidence channel: **live command** (API/CLI with an extractable `**Command**:`) → **unit-backed** (run the recorded `Repeatable Unit Test` file, all 7 criteria) → **human** (`[FAIL: auto-judge: ... requires human verification]` for bare Manual cases and every UI case — no browser automation, no heuristics). Channel 1 is never overridden by channel 2: a failing live command is a `[FAIL]` regardless of a green unit test. Eligibility = pending + previously-failed.
38
40
  5. **Step 5** — write each verdict **immediately** via `Edit` (no buffering/batching).
39
41
  6. **Closure** — archive on all-pass; on any fail leave the file in place and **exit 0** (the orchestrator treats exit as its task done; the pipeline decides what to do with fail markers). This mode keeps screenshots and uses log tag ` (auto)`.
40
42
 
@@ -47,8 +49,10 @@ There is **no fix workflow** — record evidence and exit; re-run `/uat-walk` (o
47
49
  ```
48
50
  ━━━ UAT AUTO COMPLETE ━━━
49
51
  File: wiki/work/uat/UAT-005-positions.md · Source: wiki/work/tasks/TASK-005-positions.md · Mode: headless
50
- ✅ Passed 6 · ⚠️ Skipped 1 (pre-existing, untouched) · ❌ Failed 2 (auto-judge-uncertain: 1)
52
+ ✅ Passed 6 (live command 4 · unit-backed 2) · ⚠️ Skipped 1 (pre-existing, untouched) · ❌ Failed 2 (auto-judge-uncertain: 1)
51
53
  ❔ Pending 0 · 🔲 Stub-detected 0 (left untouched — implement first) · Total 9
54
+ Unit-backed:
55
+ • UAT-EDGE-002: Rate Limit Window — `node --test test/rate-limit.test.js` (7 tests, 0 fail)
52
56
  Failed:
53
57
  • UAT-API-003: Delete Position — "auto-judge: HTTP 500 expected 204"
54
58
  • UAT-EDGE-001: Empty Positions — "auto-judge: manual test requires human verification"
@@ -62,8 +66,9 @@ On all-pass, replace `Next action` with the task/UAT IDs and their new `done`/`p
62
66
  ## Rules
63
67
 
64
68
  - **No user interaction, ever** — no `AskUserQuestion`, no inline prompts, no clarifying questions. Ambiguity → record fail / exit with a diagnostic summary.
65
- - **Verdict discipline** — `[x] Pass` only on concrete machine-verified evidence; `[FAIL: auto-judge: <reason>]` for everything else (uncertainty, missing command, non-verifiable Expected, UI, manual); **never** `[SKIP]`.
66
- - **No browser automation** — UI tests always fail-closed to human verification.
69
+ - **Verdict discipline** — `[x] Pass` only on concrete machine-verified evidence: a matching live command, or a unit-backed run meeting all 7 criteria. `[FAIL: auto-judge: <reason>]` for everything else (uncertainty, missing command with no unit test, non-verifiable Expected, UI, bare manual); **never** `[SKIP]`.
70
+ - **A green exit code is not a pass** — for unit-backed tests, always confirm the run actually executed tests from the recorded file (UAT-CORE Step 4 criterion 3). Exit 0 with 0 tests collected is the one failure mode that looks exactly like success.
71
+ - **No browser automation** — UI tests always fail-closed to human verification, unit test or not.
67
72
  - **File integrity + Bash hygiene + MCP compliance** — per UAT-CORE Step 5 and "Bash hygiene". Serena for all listing/search; `Edit` for every status flip; no `sed`/`awk`/`ls`/`find`/`grep`/`cat`; never emit literal secrets (only `"$UAT_AUTH_TOKEN"` / `"$UAT_TEST_PASSWORD"`).
68
73
 
69
74
  **Start now — read UAT-CORE.md, resolve the UAT file, and begin.**
@@ -31,7 +31,7 @@ Autonomous variant of `/uat-auto`: run every eligible test, auto-judge from dete
31
31
 
32
32
  ## Prime Directive: truthful pass
33
33
 
34
- **Never mark `[x] Pass` unless the test currently passes against unmodified test logic.** Fixes go into application code, build/config, infrastructure, or test-environment setup — **never** into the UAT file's Expected/Steps/Command, and never by weakening assertions. If a failure can't be fixed without changing what is being tested, record `[FAIL: auto-fix-declined: <reason>]` and leave the code unchanged. Related: **never delete or `[SKIP: ...]` a test to avoid fixing it** — skip is a human verdict. A false pass is the worst outcome — it ships a broken feature *and* erodes trust in every later run.
34
+ **Never mark `[x] Pass` unless the test currently passes against unmodified test logic.** Fixes go into application code, build/config, infrastructure, or test-environment setup — **never** into the UAT file's Expected/Steps/Command, **never** into the unit test file backing a unit-backed case, and never by weakening assertions. Editing the oracle you are about to be judged by is the one move that turns this mode from useful into dangerous. If a failure can't be fixed without changing what is being tested, record `[FAIL: auto-fix-declined: <reason>]` and leave the code unchanged. Related: **never delete or `[SKIP: ...]` a test to avoid fixing it** — skip is a human verdict. A false pass is the worst outcome — it ships a broken feature *and* erodes trust in every later run.
35
35
 
36
36
  ---
37
37
 
@@ -42,7 +42,7 @@ Run UAT-CORE headless throughout, adding the fix loop:
42
42
  1. **Step 1** — resolve/parse (auto/plus resolution: never prompt; auto-pick lowest-numbered pending on empty/unresolved).
43
43
  2. **Step 2** — prerequisites with **one autonomous repair attempt** each (start dev server in background + `Monitor` for ready; run migrate; run seed; obtain a documented env var), then re-verify. Still failing after one repair → hard gate (`[FAIL: auto-judge: prerequisite not satisfied — <which>]` on every untested test → Closure). Track every background process started — Closure terminates them.
44
44
  3. **Step 3 + 3.5** — classify, then stub-detect (leave stubs `- [ ] Pass`; **do not enter the fix loop** for them — implementing a feature from scratch is out of scope; surface in the summary).
45
- 4. **Step 4** — auto-judge in document order: API/CLI by machine-checkable criteria → on `[FAIL]`, **enter the fix loop (below)**. UI and Manual are always `[FAIL: auto-judge: ... requires human verification]` and **never** enter the fix loop (no machine-checkable signal that a fix worked). Eligibility = pending + previously-failed; also reset `[FIXING: ...]` → `- [ ] Pass` before running.
45
+ 4. **Step 4** — auto-judge in document order by evidence channel: **live command** (API/CLI) and **unit-backed** (the recorded `Repeatable Unit Test` file) are both machine-checkable → on `[FAIL]`, **enter the fix loop (below)**. Bare Manual cases and every UI case are `[FAIL: auto-judge: ... requires human verification]` and **never** enter the fix loop (no machine-checkable signal that a fix worked). Eligibility = pending + previously-failed; also reset `[FIXING: ...]` → `- [ ] Pass` before running.
46
46
  5. **Step 5** — write each verdict/`[FIXING: ...]` transition **immediately** via `Edit` (no buffering).
47
47
  6. **Closure** — archive on all-pass; on any fail leave in place and **exit 0**. This mode additionally deletes this task's screenshots, **terminates every background process** it started, and supports multi-task WIP tracking in decision annotation (all per UAT-CORE Closure "Mode differences: uat-auto-plus"). Log tag ` (auto-plus)`.
48
48
 
@@ -67,9 +67,9 @@ The defining feature. On an API/CLI `[FAIL]` in Step 4, do not move on — diagn
67
67
  **Loop (per failing test, attempts 1–3):**
68
68
  1. Mark `[FIXING: attempt N/3 — <short reason>]` via `Edit`.
69
69
  2. **Diagnose** — read the test, the relevant app code, recent logs. Navigate with Serena (`find_symbol`, `find_referencing_symbols`, `get_symbols_overview`) — not Grep/Glob. For runtime failures, consider the `debug-logs` skill for a ranked hypothesis list.
70
- 3. **Decide the smallest correct fix** that makes the test pass without weakening it. Acceptable targets: application code, build/config (missing env default, misrouted path, wrong port), test fixtures/seed data. **Never** the UAT file's Steps/Expected/Command; **never** test assertions in code.
70
+ 3. **Decide the smallest correct fix** that makes the test pass without weakening it. Acceptable targets: application code, build/config (missing env default, misrouted path, wrong port), test fixtures/seed data. **Never** the UAT file's Steps/Expected/Command; **never** test assertions in code — including the unit test file named in a unit-backed case's `Repeatable Unit Test` metadata, which is off-limits for the whole loop.
71
71
  4. **Delegate to a sub-agent** (`Agent` tool, `subagent_type: general-purpose`, or `Plan` for design-heavy fixes). Prompt must include: the test ID + full body; the actual-vs-expected evidence from Step 4; the constraint "do not modify the UAT file or test assertions; fix only application code, build, config, or fixtures"; a request for a short report of files changed + rationale.
72
- 5. **Re-run** the test with the same Step 4 procedure and the same Bash call — do not relax assertions.
72
+ 5. **Re-run** the test with the same Step 4 procedure and the same Bash call — same curl, or the same unit-test command over an unmodified test file (verify it is unchanged before trusting the result). Do not relax assertions or narrow the run.
73
73
  6. **Evaluate:** Pass → `[x] Pass`, delete this test's fail screenshots, exit loop, next test. Fail & attempt < 3 → next attempt with diagnosis refined by the prior report. Fail & attempt = 3 → `[FAIL: auto-fix-exhausted: <last reason>]`, exit loop.
74
74
 
75
75
  **Fix-decline cases** — mark `[FAIL: auto-fix-declined: <why>]` immediately (declining is correct judgment, not failure) when:
@@ -88,7 +88,7 @@ The defining feature. On an API/CLI `[FAIL]` in Step 4, do not move on — diagn
88
88
  ━━━ UAT AUTO-PLUS COMPLETE ━━━
89
89
  File: wiki/work/uat/5-positions.uat.md · Source: wiki/work/tasks/5-positions.md · Mode: autonomous-fix
90
90
  Budget: attempts 7/N · wall 12m22s/30m
91
- ✅ Passed 7 (fixed during run: 4) · ⚠️ Skipped 1 (pre-existing) · ❌ Failed 1 (auto-fix-exhausted 1 · declined 0 · auto-judge-uncertain 0)
91
+ ✅ Passed 7 (live command 5 · unit-backed 2 · fixed during run: 4) · ⚠️ Skipped 1 (pre-existing) · ❌ Failed 1 (auto-fix-exhausted 1 · declined 0 · auto-judge-uncertain 0)
92
92
  ❔ Pending 0 · 🔲 Stub-detected 0 (left untouched — implement first) · Total 9
93
93
  Fixes Applied:
94
94
  • UAT-API-001: added missing 422 handler in src/api/positions.ts
@@ -104,7 +104,7 @@ On all-pass, replace `Next action` with `Archived to archive/` and the new paths
104
104
 
105
105
  ## Rules
106
106
 
107
- **Autonomy boundaries** — the agent **may** modify application code, build/config, fixtures, and seed data. It **may not**: modify any UAT file's Steps/Expected/Command; modify test assertions in code (`expect(...)`); disable, comment out, `xfail`, or `[SKIP: ...]` a failing test; weaken type signatures, lower error-throwing branches, or remove validation to force a pass. When in doubt, decline and surface for review.
107
+ **Autonomy boundaries** — the agent **may** modify application code, build/config, fixtures, and seed data. It **may not**: modify any UAT file's Steps/Expected/Command; modify test assertions in code (`expect(...)`), including any unit test file backing a unit-backed case; disable, comment out, `xfail`, or `[SKIP: ...]` a failing test; narrow a test filter so fewer cases run; weaken type signatures, lower error-throwing branches, or remove validation to force a pass. When in doubt, decline and surface for review.
108
108
 
109
109
  **Verdict discipline** — `[x] Pass` only on machine-verified evidence against unmodified logic; `[FAIL: auto-fix-exhausted: ...]` after 3 attempts; `[FAIL: auto-fix-declined: ...]` when out of scope/unsafe; `[FAIL: auto-judge: ...]` when unverifiable (UI/manual); **never** `[SKIP]`.
110
110
 
@@ -17,6 +17,8 @@ UAT owns **runtime and end-to-end verification**. `/tackle` only runs static gat
17
17
 
18
18
  When a UAT case also contains behavior that can easily be preserved as a deterministic repeatable unit test, create that unit test immediately. UAT should not be the only place a cheap, automatable assertion lives.
19
19
 
20
+ Promoting a case pays off twice: the assertion becomes repeatable, **and** the case becomes headlessly judgeable. `/uat-auto` treats a recorded unit test as a first-class evidence channel, so a Manual or edge case with one auto-passes on a green run instead of fail-closing to human verification. Every case you promote is one fewer case a human has to walk.
21
+
20
22
  ---
21
23
 
22
24
  **Target**: $ARGUMENTS
@@ -85,6 +87,23 @@ Do not proceed to Step 3 until you can answer yes to all:
85
87
 
86
88
  #### Step 2.5: Unit-test promotion checkpoint (mandatory)
87
89
 
90
+ ##### Preference gate
91
+
92
+ This gate governs **only whether files are written under `test/`**. It never affects the UAT file itself or how UAT verdicts are judged.
93
+
94
+ Read the preference **once per invocation** (not per case), before Step 2.5 does any other work:
95
+
96
+ ```bash
97
+ node ~/.claude/bootstrap-prefs.js --get uatGenerate.promoteTests --project . 2>/dev/null || echo unset
98
+ ```
99
+
100
+ | Value | Behaviour |
101
+ |-------|-----------|
102
+ | `true` | Today's behaviour — run the promotion checkpoint and create/update the unit test files. |
103
+ | `false` | Do **not** create or update anything under `test/`. Still run the promotability *analysis* and still record it per case, as `- **Repeatable Unit Test**: Skipped by preference (uatGenerate.promoteTests=false)`. Say once in the completion report (Step 7): "No test/ files were written (uatGenerate.promoteTests=false). Change with /bootstrap-config." |
104
+ | `ask` | Ask the user **once per invocation** (AskUserQuestion), before Step 2.5 does any work, whether to promote tests this run. Honour the answer for this run only — never write it back to the store. |
105
+ | `unset` | Promote (today's behaviour) and note once: "uatGenerate.promoteTests is unanswered — /uat-generate promotes tests by default. Set it with: node ~/.claude/bootstrap-prefs.js --set uatGenerate.promoteTests --value <true\|false\|ask> --global" |
106
+
88
107
  For every planned UAT case, decide whether any part of it can be captured as a repeatable unit test with low setup cost.
89
108
 
90
109
  A UAT case is **unit-test promotable** when all are true:
@@ -104,7 +123,7 @@ Before writing the UAT file, inspect the existing test layout and runner:
104
123
  - Prefer adding focused assertions to an existing nearby test file when that is the local pattern.
105
124
  - Otherwise create the smallest conventional new test file beside the unit under test.
106
125
 
107
- If a case is promotable, you **must** create or update the unit test file. Do not merely list it as a recommendation. If you cannot create it because the test framework is absent or the harness would require new infrastructure, record that as a gap with the concrete blocker.
126
+ If a case is promotable **and the preference gate allows promotion**, you **must** create or update the unit test file. Do not merely list it as a recommendation. If you cannot create it because the test framework is absent or the harness would require new infrastructure, record that as a gap with the concrete blocker. When the gate suppresses promotion, do the analysis and record `Skipped by preference` — write nothing under `test/`.
108
127
 
109
128
  ### Step 3: Generate UAT test cases
110
129
 
@@ -168,6 +187,7 @@ implements::[[TASK-NNN]]
168
187
  - **Steps**: [How to trigger this scenario]
169
188
  - **Expected Result**: [How the system should handle it]
170
189
  - **Repeatable Unit Test**: [Created: `path/to/test-file` | Not applicable: reason | Blocked: reason]
190
+ - **Unit Test Command**: `node --test test/example.test.js`
171
191
  - [ ] Pass
172
192
  ```
173
193
 
@@ -190,6 +210,13 @@ implements::[[TASK-NNN]]
190
210
  - Add `- **Repeatable Unit Test**: Created: \`path/to/test-file\`` when you created or updated a unit test for the behavior.
191
211
  - Add `- **Repeatable Unit Test**: Not applicable: <short reason>` when the case cannot reasonably become a unit test.
192
212
  - Add `- **Repeatable Unit Test**: Blocked: <short reason>` only when it was promotable in principle but the repo lacks the needed test harness or fixtures.
213
+ - Add `- **Repeatable Unit Test**: Skipped by preference (uatGenerate.promoteTests=false)` when the Step 2.5 preference gate suppressed promotion for this run. Record the promotability analysis as usual; only the file write is skipped.
214
+
215
+ **Unit test command** (required whenever, and only when, the line above says `Created:`):
216
+ - Add `- **Unit Test Command**: \`<cmd>\`` on the next line, holding the **file-scoped** command that runs exactly that test file — e.g. `node --test test/foo.test.js`, `npx vitest run test/foo.test.ts`, `pytest tests/test_foo.py`, `go test ./pkg/foo/`.
217
+ - Verify it by running it once before writing the UAT file. A command that has never been run is a guess, and a wrong one costs a false failure later.
218
+ - This is what makes a Manual or edge-case test **auto-judgeable**: `/uat-auto` and `/uat-auto-plus` run it as their evidence channel instead of fail-closing the case to human verification (UAT-CORE Step 4, "Unit-backed"). Omitting it forces them to derive a command from the repo's conventions, and a case they cannot resolve one for fails closed. It costs one line here to save a human triage pass later.
219
+ - Do not point it at the whole suite (`npm test`) when a file-scoped form exists — a green suite is weak evidence about one case, and slow to re-run inside the auto-plus fix loop.
193
220
 
194
221
  **Auth metadata** (required for every auth-gated test):
195
222
  ```
@@ -201,7 +228,7 @@ Auth-Role: user
201
228
 
202
229
  ### Step 4: Write repeatable unit tests, the UAT file, and cross-reference
203
230
 
204
- 1. For each promotable case from Step 2.5, create or update the actual unit test file before writing the UAT file:
231
+ 1. **If the Step 2.5 preference gate allows promotion**, create or update the actual unit test file for each promotable case from Step 2.5, before writing the UAT file. If the gate suppressed promotion, skip this step entirely — write nothing under `test/` — and record each promotable case as `Skipped by preference` instead.
205
232
  - Use existing test framework conventions and nearby examples.
206
233
  - Keep the test focused on the behavior from the UAT case.
207
234
  - Do not add broad snapshots or duplicate end-to-end checks as unit tests.
@@ -209,7 +236,7 @@ Auth-Role: user
209
236
  - If editing code test files, use Serena editing tools.
210
237
  - If creating new config/markdown/test files where Serena is unavailable, use the appropriate project-approved edit/write tool; never shell redirection.
211
238
 
212
- 2. Include the created test path in the corresponding UAT case's `Repeatable Unit Test` metadata.
239
+ 2. Include the created test path in the corresponding UAT case's `Repeatable Unit Test` metadata, plus the verified file-scoped `Unit Test Command` — or `Skipped by preference (uatGenerate.promoteTests=false)` when the gate suppressed promotion.
213
240
 
214
241
  3. Write `wiki/work/uat/UAT-NNN-slug.md` using the `Write` tool.
215
242
 
@@ -58,6 +58,8 @@ For each unchecked prerequisite: if it is a **runnable check** (server on a port
58
58
  | **UI** | `UAT-UI-*` prefix, or `Page:` / `Components:` metadata |
59
59
  | **Manual** | anything else (edge cases, concurrency, integration logic) |
60
60
 
61
+ **Unit-backed** is an *attribute*, not a type — it cuts across all three. A test is unit-backed when it records `- **Repeatable Unit Test**: Created: \`<path>\`` (written by `/uat-generate` Step 2.5 when it promoted the case to a repeatable unit test). Note the path, and the `- **Unit Test Command**: \`<cmd>\`` line if present; Step 4 uses them as a machine-checkable evidence channel. The other three values of that field — `Not applicable:`, `Blocked:`, `Skipped by preference` — are **not** unit-backed: no test file exists to run.
62
+
61
63
  ---
62
64
 
63
65
  ## Step 3.5 — Stub detection (headless modes only)
@@ -71,6 +73,8 @@ A stub test **stays `- [ ] Pass`** — do not execute it, do not record `[FAIL]`
71
73
  3. **Stub indicators** (via `find_symbol` / `search_for_pattern`): `TODO`/`FIXME`/`HACK` inside a body; `throw new Error('not implemented')`, `raise NotImplementedError`, `notImplemented()`, `unimplemented!()`; a bare `pass` / `pass # TODO|stub`; empty body (`{}`, `return`, `return null|undefined|None`); placeholder comments (`// stub`, `# TODO: implement`, etc.).
72
74
  4. **Found** → leave status untouched, record `stub-detected` (with file + indicator) in run tracking, skip execution. **Not found / unlocatable** → proceed to Step 4.
73
75
 
76
+ Stub detection outranks unit-backing: a stub-detected test stays `- [ ] Pass` and its unit test is not run. If you have already run one and it passed against a body carrying stub indicators, that is a contradiction, not a pass — record `[FAIL: auto-judge: unit test passes but implementation appears stubbed — <file>: <indicator>]`.
77
+
74
78
  ---
75
79
 
76
80
  ## Step 4 — Execute & judge
@@ -81,26 +85,57 @@ Work through eligible tests in document order; update the file immediately after
81
85
 
82
86
  ### Auto-judge criteria (uat-auto / uat-auto-plus)
83
87
 
84
- **API/CLI** — extract the command from `**Command**:`. No extractable command → `[FAIL: auto-judge: no machine-executable command in test body]`. Pass requires **ALL**:
88
+ Judge each test on the **strongest evidence channel available to it**:
89
+
90
+ | # | Channel | Applies when | Verdict source |
91
+ |---|---------|--------------|----------------|
92
+ | 1 | **Live command** | API/CLI test with an extractable `**Command**:` | run the command (below) |
93
+ | 2 | **Unit-backed** | channel 1 unavailable **and** the test is unit-backed (Step 3) | run that unit test file (below) |
94
+ | 3 | **Human** | neither — no machine-checkable oracle | fail-closed `[FAIL: auto-judge: ...]` |
95
+
96
+ **Channel 1 outranks channel 2 and is never overridden by it.** A live command that fails is `[FAIL]` even when the test is unit-backed and its unit test passes — a green unit test beside a red live call means the live path is broken, and the narrower oracle does not get a vote. Channel 2 is reached only when channel 1 returns no verdict at all: a Manual/Edge case, or an API/CLI case whose body carries no extractable command or no machine-checkable Expected.
97
+
98
+ **API/CLI** — extract the command from `**Command**:`. No extractable command → fall through to channel 2 if the test is unit-backed, else `[FAIL: auto-judge: no machine-executable command in test body]`. Pass requires **ALL**:
85
99
  1. Command exited cleanly (response returned; no connection error).
86
100
  2. HTTP status matches the Expected section's explicit status; if none specified, any 2xx is pass-eligible on status alone.
87
101
  3. Response body satisfies **every** machine-checkable assertion in Expected (literal substring, JSON key presence, JSON value equality, array length, type-of) — via `jq` or substring match.
88
102
  4. If the test references `$UAT_AUTH_TOKEN`, the token must be present in the environment.
89
103
 
90
- Any criterion fails → `[FAIL: auto-judge: <criterion, actual vs expected>]`. Expected section with no machine-checkable assertion → `[FAIL: auto-judge: expected section not machine-verifiable]`.
104
+ Any criterion fails → `[FAIL: auto-judge: <criterion, actual vs expected>]` — a run that produced a verdict is final, and no unit test overrides it. Expected section with no machine-checkable assertion → channel 1 yielded no verdict at all, so fall through to channel 2 if the test is unit-backed, else `[FAIL: auto-judge: expected section not machine-verifiable]`.
91
105
 
92
- **UI** → always `[FAIL: auto-judge: UI test requires human verification — use /uat-walk]`. No navigation, screenshot, or browser interaction.
106
+ **Unit-backed (channel 2)** — a recorded, passing unit test *is* hard evidence, so a unit-backed test **does not fail-closed to human verification**. Resolve a run command, run it in one Bash call, and judge the result.
93
107
 
94
- **Manual** → always `[FAIL: auto-judge: manual test requires human verification]`. No heuristic evaluation. Intentional fail-closed: `/uat-generate` produced a manual test because it expected a human.
108
+ Resolve the command:
109
+ - Use the test's `- **Unit Test Command**: \`<cmd>\`` verbatim when present.
110
+ - Otherwise derive a **file-scoped** invocation for the project's runner — e.g. `node --test test/foo.test.js` · `npx vitest run test/foo.test.ts` · `npx jest test/foo.test.js` · `pytest tests/test_foo.py` · `go test ./pkg/foo/` · `cargo test --test foo`. Match the repo's existing convention (`package.json` `scripts.test`, CI config, nearby tests).
111
+ - A whole-suite run (`npm test`) is acceptable **only** when its output names this file's own cases and shows them passing — otherwise a green suite says nothing about this file.
112
+ - Cannot resolve either form → `[FAIL: auto-judge: no runnable unit-test command for <path>]`.
95
113
 
96
- `/uat-walk` does not auto-judge — the user issues every verdict. `/uat-auto-plus` enters its fix loop after an API/CLI `[FAIL]` (never for UI/Manual — no machine-checkable signal that a fix worked).
114
+ Pass requires **ALL**:
115
+ 1. The recorded path resolves to a file that exists (`mcp__serena__find_file`). Missing → `[FAIL: auto-judge: unit test file not found — <path>]`; stale metadata pointing at a moved or deleted test is not evidence.
116
+ 2. The runner exited 0.
117
+ 3. The run **executed ≥1 test from that file**, and the output states the count. `0 tests` / `no tests ran` / `0 matched` / an empty pass line → `[FAIL: auto-judge: unit-test run matched 0 tests in <path>]`. **This is the load-bearing check** — a filter typo, a renamed file, or a wrong path produces exit 0 with nothing executed, which is indistinguishable from a real pass on exit code alone.
118
+ 4. Zero failing, errored, or timed-out tests in the run.
119
+ 5. The file's cases covering this UAT case actually ran — all `skip`/`todo`/`xfail`/`.only`-excluded → `[FAIL: auto-judge: unit test coverage skipped, not executed]`.
120
+ 6. The unit test file is unmodified by this run (auto-plus: its fix loop may never touch it — see that skill's Autonomy boundaries).
121
+ 7. The Expected Result contains no observable the unit test demonstrably cannot assert (live HTTP round-trip, rendering, deploy/filesystem state). Partial coverage → `[FAIL: auto-judge: unit test covers only part of Expected — <what is uncovered>]`. Apply this narrowly: a unit test that asserts the case's stated outcome by construction is complete evidence, not partial.
97
122
 
98
- ### Bash hygiene — API/CLI tests (all modes)
123
+ On pass: `- [x] Pass <!-- YYYY-MM-DD -->`; record `via unit test <path>` in run tracking so the summary can count it.
124
+
125
+ **UI** → always `[FAIL: auto-judge: UI test requires human verification — use /uat-walk]`, **even when unit-backed**. No navigation, screenshot, or browser interaction. A unit test cannot cover what a UI case exists to check (rendering, layout, flow timing) — `/uat-generate` Step 2.5 classifies exactly those as non-promotable, so a `Created:` on a UI case covers a fragment at best.
126
+
127
+ **Manual** → unit-backed goes to channel 2. Otherwise always `[FAIL: auto-judge: manual test requires human verification]`, with no heuristic evaluation — intentional fail-closed: `/uat-generate` produced a bare manual test because it expected a human.
128
+
129
+ `/uat-walk` does not auto-judge — the user issues every verdict. `/uat-auto-plus` enters its fix loop after a channel 1 or channel 2 `[FAIL]` (both have a machine-checkable signal that a fix worked); never after a channel 3 `[FAIL]`.
130
+
131
+ ### Bash hygiene — API/CLI and unit-backed tests (all modes)
99
132
 
100
133
  **One program invocation per Bash call: one `curl` (as-is), optionally one `\| jq` stage. Nothing else.** If a generated `**Command**:` block violates this, rewrite it to the clean form before running (canonical style: `lib/skills/uat-generate/SKILL.md` "Curl command standards"). Never emit literal password/token values — only `"$UAT_AUTH_TOKEN"` / `"$UAT_TEST_PASSWORD"` references.
101
134
 
102
135
  Forbidden (each triggers an approval prompt and obscures output): multiple `curl`s in one call · `&&` / `;` / `\|\|` chaining · `echo` banners · `-w` format strings · `-o /tmp/...` then re-read · defensive flags (`--max-time`) · pre-assigned `TOKEN=...` vars · `\` line-continuations · piping to `head`/`tee`/redirection. Capture per test: HTTP status, response body (truncate display to ~50 lines; never write a temp file to read it back), connection errors.
103
136
 
137
+ Unit-backed runs follow the same rule: **one test-runner invocation per Bash call**, unchained and unredirected, so the runner's own pass/fail/count lines reach you intact. Capture per test: exit code, tests-run count, failing test names.
138
+
104
139
  ---
105
140
 
106
141
  ## Step 5 — Update the file per verdict