@codewizard-dt/bootstrap 2.17.0 → 2.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/hooks/README.md +94 -3
- package/lib/hooks/absolute-path-guard.js +5 -0
- package/lib/hooks/claude-settings-guard.js +5 -0
- package/lib/hooks/env-content-read-guard.js +13 -3
- package/lib/hooks/env-file-guard.js +42 -0
- package/lib/hooks/interpreter-indirection-guard.js +7 -0
- package/lib/hooks/lib/command-parse.js +8 -0
- package/lib/hooks/lib/serena-languages.js +94 -1
- package/lib/hooks/lib/serena.js +228 -0
- package/lib/hooks/mv-absolute-path-block.js +84 -3
- package/lib/hooks/package-install-consent.js +11 -0
- package/lib/hooks/protected-write-guard.js +7 -0
- package/lib/hooks/serena-bash-grep-block.js +507 -44
- package/lib/hooks/serena-first-glob-guard.js +65 -20
- package/lib/hooks/serena-first-guard.js +98 -2
- package/lib/hooks/serena-first-read-guard.js +92 -2
- package/lib/hooks/serena-pre-delegation.js +123 -0
- package/lib/hooks/serena-write-guard.js +56 -3
- package/lib/scripts/README.md +306 -1
- package/lib/scripts/bootstrap-prefs.js +734 -0
- package/lib/scripts/install-global.sh +188 -18
- package/lib/scripts/install-mcps.sh +102 -14
- package/lib/scripts/lib.sh +581 -11
- package/lib/scripts/merge-gitignore.sh +201 -15
- package/lib/scripts/sync-wiki-scaffold.sh +33 -4
- package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
- package/lib/scripts/templates/bootstrap-prefs-schema.json +175 -0
- package/lib/scripts/update-project.sh +42 -9
- package/lib/skills/README.md +2 -1
- package/lib/skills/bootstrap-config/SKILL.md +154 -0
- package/lib/skills/git-commit/SKILL.md +89 -6
- package/lib/skills/research/SKILL.md +34 -3
- package/lib/skills/simplify/SKILL.md +1 -1
- package/lib/skills/uat-auto/SKILL.md +9 -4
- package/lib/skills/uat-auto-plus/SKILL.md +6 -6
- package/lib/skills/uat-generate/SKILL.md +47 -7
- package/lib/skills/uat-walk/UAT-CORE.md +41 -6
- package/lib/skills/wiki-query/SKILL.md +48 -8
- 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,41 @@ 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
|
|
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 | Manifests | Subject prefix |
|
|
76
|
+
|-------|-----------|----------------|
|
|
77
|
+
| `auto` | Today's behavior. Detect every manifest and apply the bump to all of them, no confirmation. | **written** |
|
|
78
|
+
| `confirm` — approved | Bump exactly as `auto` does. | **written** |
|
|
79
|
+
| `confirm` — declined | Edit no manifest. | **omitted** |
|
|
80
|
+
| `never` | Touch **no** version file at all. Skip straight to Step 5. | **omitted** |
|
|
81
|
+
| `unset` | Behave exactly as `auto` — that is today's behavior and an unanswered key must never change it. | **written** |
|
|
82
|
+
|
|
83
|
+
`confirm` prints the suggested bump **and the full list of manifest files that would change**, then asks once with `AskUserQuestion` before editing anything. Ask **every run** and **never persist the answer** — the standing choice is "keep asking me", so recording a reply would destroy it.
|
|
84
|
+
|
|
85
|
+
### ⛔ The prefix and the bump travel together
|
|
86
|
+
|
|
87
|
+
**Write `[patch]`/`[minor]`/`[major]` if and only if a version was actually bumped in this run.** The prefix is a claim about what the commit did, and release tooling reads it as one. A `[minor]` prefix on a commit that bumped nothing is not a harmless label — it is a false statement that tooling will act on, tagging or publishing a release that has no version change behind it. An unprefixed subject is merely uninformative; a lying prefix is actively wrong, and it is worse the more automation is downstream.
|
|
88
|
+
|
|
89
|
+
So when no bump happens, commit a **bare subject with no bracket prefix at all**. Do not substitute `[none]`, `[skip]`, `[no-bump]`, or any other placeholder — an unrecognized token is its own kind of noise, and tooling that pattern-matches the three real values will ignore a bare subject correctly.
|
|
90
|
+
|
|
91
|
+
The one case where nothing was bumped for a reason unrelated to this preference — a repo with **no manifest at all** (Detection below finds nothing) — follows the same rule: nothing was bumped, so no prefix.
|
|
92
|
+
|
|
93
|
+
Report lines, each at most once per run:
|
|
94
|
+
- `never` → `Version files untouched and no subject prefix written (gitCommit.versionBump=never). Change with /bootstrap-config.`
|
|
95
|
+
- `confirm`-declined → `Bump declined — no manifest edited and no subject prefix written.`
|
|
96
|
+
- `unset` → `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`).
|
|
97
|
+
|
|
98
|
+
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.
|
|
99
|
+
|
|
100
|
+
For `auto`, `confirm`-approved, and `unset`, continue below. For `never` and `confirm`-declined, go to Step 5.
|
|
101
|
+
|
|
58
102
|
Find and update version numbers in project files.
|
|
59
103
|
|
|
60
104
|
### Detection
|
|
@@ -100,7 +144,7 @@ Edit **every file** that contains a version using the Edit tool — do not stop
|
|
|
100
144
|
- **ALWAYS use the `git-commit` bash alias.** Never use `git add` or `git commit` directly.
|
|
101
145
|
- Always commit ALL files unless they are in `.gitignore`
|
|
102
146
|
- Consider an appropriate commit message, let's call it `$message`
|
|
103
|
-
- Prefix the subject with the bump type in brackets
|
|
147
|
+
- Prefix the subject with the bump type in brackets — `[patch]`, `[minor]`, or `[major]` — **only if Step 4 actually bumped a version**. If it did not (`never`, `confirm`-declined, or no manifest in the repo), the subject starts with the description and carries no bracket prefix
|
|
104
148
|
- Run: `git-commit "$message"`
|
|
105
149
|
|
|
106
150
|
### ⛔ No agent attribution — the user is the sole author
|
|
@@ -115,13 +159,14 @@ The commit must be attributed to the user's git identity **only**. Never add the
|
|
|
115
159
|
|
|
116
160
|
The commit message MUST be a **single-line, single-quoted-argument string**. Subject only, no body. This is a hard rule because anything else triggers a Bash approval prompt and slows you down.
|
|
117
161
|
|
|
118
|
-
**Required form
|
|
162
|
+
**Required form** — bumped, and not bumped:
|
|
119
163
|
|
|
120
164
|
```bash
|
|
121
165
|
git-commit "[patch] Single-line subject describing the change"
|
|
166
|
+
git-commit "Single-line subject describing the change"
|
|
122
167
|
```
|
|
123
168
|
|
|
124
|
-
That's it. One pair of double quotes. One line. One argument.
|
|
169
|
+
That's it. One pair of double quotes. One line. One argument. The only difference between the two forms is whether Step 4 bumped a version.
|
|
125
170
|
|
|
126
171
|
**❌ Forbidden — every one of these patterns triggers an approval prompt:**
|
|
127
172
|
|
|
@@ -150,9 +195,13 @@ git-commit "subject" "-m" "body"
|
|
|
150
195
|
|
|
151
196
|
# WRONG — piping or chaining
|
|
152
197
|
echo "subject" | git-commit -F -
|
|
198
|
+
|
|
199
|
+
# WRONG — a placeholder standing in for a bump that did not happen
|
|
200
|
+
git-commit "[none] Fix the login redirect"
|
|
201
|
+
git-commit "[no-bump] Fix the login redirect"
|
|
153
202
|
```
|
|
154
203
|
|
|
155
|
-
**✅ Correct —
|
|
204
|
+
**✅ Correct — a version was bumped:**
|
|
156
205
|
|
|
157
206
|
```bash
|
|
158
207
|
git-commit "[patch] Fix UAT verdict logic for edge-case test skips"
|
|
@@ -160,13 +209,47 @@ git-commit "[minor] Add /task-audit skill with dependency graph and wave output"
|
|
|
160
209
|
git-commit "[major] Rename all skills to noun-first convention, drop legacy verb-first aliases"
|
|
161
210
|
```
|
|
162
211
|
|
|
212
|
+
**✅ Correct — no version was bumped** (`never`, `confirm`-declined, or no manifest in the repo):
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
git-commit "Fix UAT verdict logic for edge-case test skips"
|
|
216
|
+
git-commit "Add /task-audit skill with dependency graph and wave output"
|
|
217
|
+
```
|
|
218
|
+
|
|
163
219
|
### Writing a good single-line subject
|
|
164
220
|
|
|
165
221
|
If the change feels too complex to summarize in one line, **make the subject more descriptive** — do not reach for a multi-line body. Aim for ~70–100 characters but go longer if it adds real information. Lead with the *what* and the *why* on the same line, separated by a colon when helpful:
|
|
166
222
|
|
|
167
223
|
- ✅ `[minor] Require research for every test type in /uat-generate with checkpoint gate`
|
|
168
224
|
- ✅ `[patch] Allow standard tools for markdown editing; ban bash exploration commands`
|
|
169
|
-
-
|
|
225
|
+
- ✅ `Allow standard tools for markdown editing; ban bash exploration commands` (no bump this run — the subject still carries its weight)
|
|
226
|
+
- ❌ `Update commands` (too vague — and vague is vague with or without a prefix)
|
|
170
227
|
- ❌ `[patch] Fix bug` (too vague)
|
|
228
|
+
- ❌ `[patch] Fix the login redirect` **when Step 4 bumped nothing** (the prefix is false)
|
|
171
229
|
|
|
172
230
|
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.
|
|
231
|
+
|
|
232
|
+
## Step 6: Push (gated on `gitCommit.autoPush`)
|
|
233
|
+
|
|
234
|
+
Runs only after the commit in Step 5 succeeded. A failed commit means there is nothing to push.
|
|
235
|
+
|
|
236
|
+
| Value | What to do |
|
|
237
|
+
|-------|------------|
|
|
238
|
+
| `true` | `git push` the **current** branch. Nothing else. |
|
|
239
|
+
| `false` | Do not push. Say so once in the final report: `Committed locally; not pushed (gitCommit.autoPush=false). Change with /bootstrap-config.` |
|
|
240
|
+
| `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. |
|
|
241
|
+
| `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`). |
|
|
242
|
+
|
|
243
|
+
### ⛔ The push is the plainest possible push
|
|
244
|
+
|
|
245
|
+
- **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.
|
|
246
|
+
- Never pass `--force`, `--force-with-lease`, `--set-upstream`/`-u`, `--all`, or `--tags`, and never name a different remote or refspec. Plain `git push`.
|
|
247
|
+
- 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.
|
|
248
|
+
|
|
249
|
+
## Step 7: Final report
|
|
250
|
+
|
|
251
|
+
One short report at the end. Include, in this order:
|
|
252
|
+
|
|
253
|
+
1. The commit subject that was written.
|
|
254
|
+
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.
|
|
255
|
+
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
|
-
|
|
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) **
|
|
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
|
|
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
|
|
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
|
|
66
|
-
- **
|
|
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
|
|
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 —
|
|
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,36 @@ 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 where unit test files are written** (and whether they are written at all). 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
|
+
The key answers **where** promoted tests go, not whether they exist. Its grammar is the closed enumeration `sibling | never | dedicated`.
|
|
101
|
+
|
|
102
|
+
| Value | Behaviour |
|
|
103
|
+
|-------|-----------|
|
|
104
|
+
| `dedicated` | Write promoted tests into the project's dedicated test directory, **resolved from the repo** — an existing test directory if there is one, else the language default (`test/` for JS/TS, `tests/` for Python, `spec/` where that is the local idiom). The directory is detected, never stored: `values` is a closed list of literal tokens, and a stored path would be free text. |
|
|
105
|
+
| `sibling` | Write each test **beside the file under test**, using the language's own convention — `src/parse.ts` → `src/parse.test.ts`, `src/parse.js` → `src/parse.test.js`, `parse.py` → `test_parse.py`, `parse.go` → `parse_test.go`. Never invent a suffix the language's runner does not already discover. |
|
|
106
|
+
| `never` | Create or update **nothing** under any test path. Still run the promotability *analysis* and still record it per case, as `- **Repeatable Unit Test**: Skipped by preference (uatGenerate.promoteTests=never)`. Say once in the completion report (Step 7): "No test files were written (uatGenerate.promoteTests=never). Change with /bootstrap-config." |
|
|
107
|
+
| `unset` | Behave as `dedicated` — today's behaviour. Note once: "uatGenerate.promoteTests is unanswered — /uat-generate writes promoted tests to a dedicated folder by default. Set it with: node ~/.claude/bootstrap-prefs.js --set uatGenerate.promoteTests --value <sibling\|never\|dedicated> --global" |
|
|
108
|
+
| `true` / `false` / `ask` | **Legacy values** from the key's earlier true/false grammar. Map them and carry on — do not error: `true` → `dedicated`, `false` → `never`, `ask` → ask the user once per invocation (AskUserQuestion) which of the three locations to use, honouring the answer for this run only and never writing it back. Mention once that the stored value is from an older grammar and `/bootstrap-config` can update it. |
|
|
109
|
+
|
|
110
|
+
### The project's layout outranks the stored answer
|
|
111
|
+
|
|
112
|
+
**A stored location is a default for new work, not an instruction to fight the repo.** Before writing anything, look at where tests already live:
|
|
113
|
+
|
|
114
|
+
- An existing test file that already covers the unit under test is **extended in place** under every value except `never`. That is neither "dedicated" nor "sibling" — it is the local pattern, and it always wins.
|
|
115
|
+
- If the project visibly uses one layout and the stored preference says the other (preference says `sibling`, the repo has a populated `test/` with no siblings anywhere), **follow the repo** and say so once in Step 7: "Followed the project's existing `test/` layout over uatGenerate.promoteTests=sibling. Set it per-project with /bootstrap-config." Scattering siblings through a repo that centralises its suite makes the suite worse, and this key is `scope: either` precisely so a project can hold its own answer.
|
|
116
|
+
- Only when the project has no discernible convention does the stored value decide on its own.
|
|
117
|
+
|
|
118
|
+
`never` is the one value the repo cannot overrule — "write no test files" is a directive, not a layout hint.
|
|
119
|
+
|
|
88
120
|
For every planned UAT case, decide whether any part of it can be captured as a repeatable unit test with low setup cost.
|
|
89
121
|
|
|
90
122
|
A UAT case is **unit-test promotable** when all are true:
|
|
@@ -98,13 +130,13 @@ A UAT case is **not** unit-test promotable when it primarily verifies:
|
|
|
98
130
|
- Real HTTP service wiring, authentication middleware, deployment behavior, shell environment setup, database migrations, or file permissions.
|
|
99
131
|
- Third-party service behavior or integration between multiple independently deployed systems.
|
|
100
132
|
|
|
101
|
-
Before writing the UAT file, inspect the existing test layout and runner:
|
|
102
|
-
- Find nearby test files for the changed code.
|
|
133
|
+
Before writing the UAT file, inspect the existing test layout and runner — this is also what resolves the location gate above:
|
|
134
|
+
- Find nearby test files for the changed code, and note **where** the project keeps them (a dedicated directory, siblings, or both).
|
|
103
135
|
- Identify the test framework, naming convention, fixtures, mocks, and command used by the repo.
|
|
104
|
-
- Prefer adding focused assertions to an existing nearby test file when that is the local pattern
|
|
105
|
-
- Otherwise create the smallest conventional new test file
|
|
136
|
+
- Prefer adding focused assertions to an existing nearby test file when that is the local pattern — this wins over the stored preference in every case except `never`.
|
|
137
|
+
- Otherwise create the smallest conventional new test file **at the location the gate resolved to**, following the repo's visible layout when it contradicts the stored value.
|
|
106
138
|
|
|
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.
|
|
139
|
+
If a case is promotable **and the gate resolved to a location** (anything but `never`), you **must** create or update the unit test file at that location. 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 resolved to `never`, do the analysis and record `Skipped by preference` — write no test file anywhere.
|
|
108
140
|
|
|
109
141
|
### Step 3: Generate UAT test cases
|
|
110
142
|
|
|
@@ -168,6 +200,7 @@ implements::[[TASK-NNN]]
|
|
|
168
200
|
- **Steps**: [How to trigger this scenario]
|
|
169
201
|
- **Expected Result**: [How the system should handle it]
|
|
170
202
|
- **Repeatable Unit Test**: [Created: `path/to/test-file` | Not applicable: reason | Blocked: reason]
|
|
203
|
+
- **Unit Test Command**: `node --test test/example.test.js`
|
|
171
204
|
- [ ] Pass
|
|
172
205
|
```
|
|
173
206
|
|
|
@@ -190,6 +223,13 @@ implements::[[TASK-NNN]]
|
|
|
190
223
|
- Add `- **Repeatable Unit Test**: Created: \`path/to/test-file\`` when you created or updated a unit test for the behavior.
|
|
191
224
|
- Add `- **Repeatable Unit Test**: Not applicable: <short reason>` when the case cannot reasonably become a unit test.
|
|
192
225
|
- Add `- **Repeatable Unit Test**: Blocked: <short reason>` only when it was promotable in principle but the repo lacks the needed test harness or fixtures.
|
|
226
|
+
- Add `- **Repeatable Unit Test**: Skipped by preference (uatGenerate.promoteTests=never)` when the Step 2.5 preference gate suppressed promotion for this run. Record the promotability analysis as usual; only the file write is skipped.
|
|
227
|
+
|
|
228
|
+
**Unit test command** (required whenever, and only when, the line above says `Created:`):
|
|
229
|
+
- 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/`.
|
|
230
|
+
- 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.
|
|
231
|
+
- 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.
|
|
232
|
+
- 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
233
|
|
|
194
234
|
**Auth metadata** (required for every auth-gated test):
|
|
195
235
|
```
|
|
@@ -201,7 +241,7 @@ Auth-Role: user
|
|
|
201
241
|
|
|
202
242
|
### Step 4: Write repeatable unit tests, the UAT file, and cross-reference
|
|
203
243
|
|
|
204
|
-
1.
|
|
244
|
+
1. **If the Step 2.5 gate resolved to a location**, create or update the actual unit test file for each promotable case from Step 2.5 **at that location**, before writing the UAT file. If it resolved to `never`, skip this step entirely — write no test file anywhere — and record each promotable case as `Skipped by preference` instead.
|
|
205
245
|
- Use existing test framework conventions and nearby examples.
|
|
206
246
|
- Keep the test focused on the behavior from the UAT case.
|
|
207
247
|
- Do not add broad snapshots or duplicate end-to-end checks as unit tests.
|
|
@@ -209,7 +249,7 @@ Auth-Role: user
|
|
|
209
249
|
- If editing code test files, use Serena editing tools.
|
|
210
250
|
- If creating new config/markdown/test files where Serena is unavailable, use the appropriate project-approved edit/write tool; never shell redirection.
|
|
211
251
|
|
|
212
|
-
2. Include the created test path in the corresponding UAT case's `Repeatable Unit Test` metadata.
|
|
252
|
+
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=never)` when the gate suppressed promotion.
|
|
213
253
|
|
|
214
254
|
3. Write `wiki/work/uat/UAT-NNN-slug.md` using the `Write` tool.
|
|
215
255
|
|