@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.
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 +306 -1
  20. package/lib/scripts/bootstrap-prefs.js +734 -0
  21. package/lib/scripts/install-global.sh +188 -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 +89 -6
  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 +47 -7
  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
@@ -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
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: wiki-query
3
- description: Answer a question from the wiki — locate pages via the index, synthesize a cited answer, and offer to file valuable answers back as new wiki pages
3
+ description: Answer a question from the wiki — locate pages via the index, synthesize a cited answer, auto-ingest relevant un-ingested raw sources when the wiki has no coverage, and offer to file valuable answers back as new wiki pages
4
4
  category: researching
5
5
  model: claude-sonnet-5
6
6
  argument-hint: <question>
@@ -11,7 +11,7 @@ user-invocable: true
11
11
 
12
12
  # Wiki Query
13
13
 
14
- Answer a question using the wiki as the primary source of truth. If the wiki lacks coverage, say so and suggest `/wiki-ingest` for relevant raw sources. **Never answer from general knowledge alone when a wiki page exists — cite it.**
14
+ Answer a question using the wiki as the primary source of truth. If the wiki lacks coverage, fall back to ingesting relevant un-ingested `raw/` sources (Step 4), then answer from the enlarged wiki. **Never answer from general knowledge alone when a wiki page exists — cite it.**
15
15
 
16
16
  ---
17
17
 
@@ -37,13 +37,51 @@ Answer the question in 2–5 paragraphs. For each claim, cite the wiki page: `([
37
37
 
38
38
  If you found contradictions between pages, surface them explicitly with a `> **Contradiction:**` callout and note which source is more recent.
39
39
 
40
- If the wiki has no coverage at all: say so clearly and suggest:
40
+ If the wiki has no coverage at all — no page matched, or the pages that matched do not actually contain what was asked — **do not stop here**. Go to Step 4.
41
+
42
+ ## Step 4: Fallback — Ingest Relevant Raw Sources
43
+
44
+ Run this step **only** when Step 3 produced no answer. Partial-but-sufficient coverage is not a trigger; neither is an answer you merely wish were more detailed.
45
+
46
+ ### 4.1 Find un-ingested sources
47
+
48
+ 1. `mcp__serena__list_dir` on `raw/` (recursive) for the full candidate list; skip `.gitkeep`.
49
+ 2. `mcp__serena__list_dir` on `wiki/knowledge/sources/` and read the `sources:` frontmatter of each summary page.
50
+ 3. A raw file is **un-ingested** when no summary page's `sources:` list resolves to it. The `sources:` back-link is authoritative — a matching filename slug is a hint, not proof.
51
+ 4. Treat each `raw/research/<slug>/` and `raw/companies/<slug>/` directory as a **single candidate** represented by its main report file, not as one candidate per supporting file.
52
+
53
+ ### 4.2 Rank by relevance — cheaply
54
+
55
+ Do not read candidate files in full at this stage. Triage with:
56
+
57
+ - filename and directory slugs against the question's keywords;
58
+ - `mcp__serena__search_for_pattern` for question keywords restricted to `raw/`;
59
+ - frontmatter and headings only, for the surviving few.
60
+
61
+ Keep only sources that plausibly answer *this* question. If none survive, say so and stop:
41
62
  ```
42
- This question isn't covered in the wiki yet.
43
- To add coverage: /wiki-ingest raw/<relevant-source>
63
+ This question isn't covered in the wiki, and no un-ingested raw source looks relevant.
64
+ To add coverage: add a source to raw/ then run /wiki-ingest raw/<file>
44
65
  ```
45
66
 
46
- ## Step 4: Offer to File the Answer Back
67
+ ### 4.3 Ingest the relevant sources
68
+
69
+ Announce before writing anything:
70
+ ```
71
+ No wiki coverage for this question. Un-ingested raw sources that look relevant:
72
+ 1. raw/<file> — <one line on why>
73
+ Ingesting these now, then re-answering.
74
+ ```
75
+
76
+ For each selected source, run the `/wiki-ingest` procedure (`lib/skills/wiki-ingest/SKILL.md`) in full against that path. One deviation only: its **Step 2 checkpoint becomes a non-blocking announcement** — print the takeaways and continue instead of waiting for the user. Every other step (summary page, entity pages, concept pages, index, log, hot cache) runs exactly as written there.
77
+
78
+ **Cap: at most 3 sources per invocation.** If more look relevant, ingest the 3 strongest and list the remainder for the user to run manually.
79
+
80
+ ### 4.4 Re-answer once
81
+
82
+ Redo Steps 1–3 against the now-updated wiki and cite the newly created pages like any other. **Re-enter Step 4 at most once per invocation** — if the answer is still not there, report the gap plainly and list what was ingested. Never loop.
83
+
84
+ ## Step 5: Offer to File the Answer Back
47
85
 
48
86
  If the synthesized answer represents **durable, timeless knowledge** (a pattern, a design decision rationale, an entity summary) that doesn't currently exist as its own wiki page, offer:
49
87
 
@@ -59,13 +97,15 @@ If the user says yes:
59
97
  2. Add a typed link `derived_from::[[source-slug]]` if the answer came from an ingested source.
60
98
  3. Add the new page to the **Concepts** section of `wiki/index.md`.
61
99
  4. Append to `wiki/log.md`: `## [YYYY-MM-DD] query | <question summary>\nFiled answer as wiki/knowledge/concepts/<slug>.md.`
62
- 5. **Only on this filing path** (never on the read-only answer path): run the **Hot Cache Refresh** procedure — defined in `/wiki-ingest` Step 8 (`lib/skills/wiki-ingest/SKILL.md`) — to regenerate `wiki/hot.md` in full, surfacing the newly filed page under Recent Changes. Do not restate the procedure here; follow it as written.
100
+ 5. **Only on this filing path** (never on the read-only answer path): run the **Hot Cache Refresh** procedure — defined in `/wiki-ingest` Step 8 (`lib/skills/wiki-ingest/SKILL.md`) — to regenerate `wiki/hot.md` in full, surfacing the newly filed page under Recent Changes. Do not restate the procedure here; follow it as written. Step 4's ingests refresh the hot cache on their own as part of the `/wiki-ingest` procedure — that is a write path, not the read-only answer path.
63
101
 
64
102
  ---
65
103
 
66
104
  ## CRITICAL RULES
67
105
 
68
- 1. **Answer from the wiki, not general knowledge** — if the wiki lacks coverage, say so.
106
+ 1. **Answer from the wiki, not general knowledge** — if the wiki still lacks coverage after Step 4, say so.
69
107
  2. **The two-domain rule** — filed answers (durable synthesis) go to `wiki/knowledge/`; never file under `wiki/work/`.
70
108
  3. All citations use relative markdown links to the wiki page, not raw file paths.
71
109
  4. Do not modify any `wiki/work/` files — this skill is read-only for work artifacts.
110
+ 5. `raw/` is **immutable** — Step 4 reads and ingests raw sources; it never creates, edits, moves, or deletes anything under `raw/`.
111
+ 6. **Step 4 runs at most once per invocation and ingests at most 3 sources.** A query must never trigger an ingest cascade or a re-query loop.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codewizard-dt/bootstrap",
3
- "version": "2.17.0",
3
+ "version": "2.19.0",
4
4
  "description": "Bootstrap Claude Code projects with an LLM Wiki, reusable skills, hooks, and MCP setup",
5
5
  "homepage": "https://github.com/codewizard-dt/bootstrap-wiki#readme",
6
6
  "bugs": {