@codewizard-dt/bootstrap 2.10.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 (186) hide show
  1. package/.github/workflows/build.yml +88 -0
  2. package/.github/workflows/security.yml +24 -0
  3. package/.gitleaks.toml +15 -0
  4. package/README.md +472 -0
  5. package/bin/cli.js +47 -0
  6. package/lib/README.md +27 -0
  7. package/lib/hooks/README.md +316 -0
  8. package/lib/hooks/env-file-guard.js +45 -0
  9. package/lib/hooks/git-protected-ops-block.js +77 -0
  10. package/lib/hooks/lib/serena-languages.js +158 -0
  11. package/lib/hooks/lib/serena.js +787 -0
  12. package/lib/hooks/mv-absolute-path-block.js +53 -0
  13. package/lib/hooks/serena-bash-grep-block.js +501 -0
  14. package/lib/hooks/serena-edit-guard.js +74 -0
  15. package/lib/hooks/serena-first-glob-guard.js +94 -0
  16. package/lib/hooks/serena-first-guard.js +74 -0
  17. package/lib/hooks/serena-first-read-guard.js +167 -0
  18. package/lib/hooks/serena-pre-delegation.js +117 -0
  19. package/lib/hooks/serena-session-reset.js +45 -0
  20. package/lib/hooks/serena-usage-tracker.js +186 -0
  21. package/lib/hooks/serena-write-guard.js +58 -0
  22. package/lib/prompts/README.md +16 -0
  23. package/lib/prompts/migrate-wiki.md +111 -0
  24. package/lib/prompts/setup-deployment.md +322 -0
  25. package/lib/prompts/setup-design-system.md +162 -0
  26. package/lib/prompts/setup-strict-typechecks.md +139 -0
  27. package/lib/scripts/README.md +49 -0
  28. package/lib/scripts/bootstrap-serena.sh +145 -0
  29. package/lib/scripts/build-mcp-guide.sh +108 -0
  30. package/lib/scripts/install-global.sh +78 -0
  31. package/lib/scripts/install-mcps.sh +131 -0
  32. package/lib/scripts/lib.sh +154 -0
  33. package/lib/scripts/merge-gitignore.sh +65 -0
  34. package/lib/scripts/migrate-project.sh +273 -0
  35. package/lib/scripts/setup-deployment.sh +104 -0
  36. package/lib/scripts/setup-project.sh +55 -0
  37. package/lib/scripts/setup-runner.sh +99 -0
  38. package/lib/scripts/setup-strict-typechecks.sh +29 -0
  39. package/lib/scripts/startup.sh +42 -0
  40. package/lib/scripts/sync-wiki-scaffold.sh +104 -0
  41. package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
  42. package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
  43. package/lib/scripts/templates/gitignore +136 -0
  44. package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
  45. package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
  46. package/lib/scripts/templates/guides/stubs/context7.md +26 -0
  47. package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
  48. package/lib/scripts/templates/guides/stubs/serena.md +219 -0
  49. package/lib/scripts/templates/wiki/conventions.md +100 -0
  50. package/lib/scripts/templates/wiki/dashboard.html +1733 -0
  51. package/lib/scripts/templates/wiki/hot.md +21 -0
  52. package/lib/scripts/templates/wiki/index.md +46 -0
  53. package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
  54. package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
  55. package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
  56. package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
  57. package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
  58. package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
  59. package/lib/scripts/templates/wiki/log.md +14 -0
  60. package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
  61. package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
  62. package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
  63. package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
  64. package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
  65. package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
  66. package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
  67. package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
  68. package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
  69. package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
  70. package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
  71. package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
  72. package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
  73. package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
  74. package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
  75. package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
  76. package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
  77. package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
  78. package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
  79. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
  80. package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
  81. package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
  82. package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
  83. package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
  84. package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
  85. package/lib/scripts/update-project.sh +75 -0
  86. package/lib/scripts/wiki-dashboard-server.js +146 -0
  87. package/lib/skills/README.md +146 -0
  88. package/lib/skills/anti-slop/SKILL.md +183 -0
  89. package/lib/skills/bug-close/SKILL.md +136 -0
  90. package/lib/skills/bug-file/SKILL.md +114 -0
  91. package/lib/skills/bug-triage/SKILL.md +140 -0
  92. package/lib/skills/company-align/SKILL.md +203 -0
  93. package/lib/skills/debug-logs/SKILL.md +129 -0
  94. package/lib/skills/decision-create/SKILL.md +220 -0
  95. package/lib/skills/decision-finalize/SKILL.md +181 -0
  96. package/lib/skills/decision-next/SKILL.md +129 -0
  97. package/lib/skills/decision-walkthrough/SKILL.md +169 -0
  98. package/lib/skills/demo/SKILL.md +183 -0
  99. package/lib/skills/elevator-pitch/SKILL.md +125 -0
  100. package/lib/skills/eval-create/SKILL.md +344 -0
  101. package/lib/skills/eval-gap/SKILL.md +150 -0
  102. package/lib/skills/eval-run/SKILL.md +214 -0
  103. package/lib/skills/extract-feature/SKILL.md +344 -0
  104. package/lib/skills/flashcard/SKILL.md +513 -0
  105. package/lib/skills/frontend-taste/SKILL.md +184 -0
  106. package/lib/skills/gap-assess/SKILL.md +97 -0
  107. package/lib/skills/git-commit/SKILL.md +164 -0
  108. package/lib/skills/lint/SKILL.md +99 -0
  109. package/lib/skills/marp-slideshow/SKILL.md +212 -0
  110. package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
  111. package/lib/skills/now/SKILL.md +36 -0
  112. package/lib/skills/port-feature/SKILL.md +315 -0
  113. package/lib/skills/power-mode/SKILL.md +184 -0
  114. package/lib/skills/primer/SKILL.md +84 -0
  115. package/lib/skills/project-readme/SKILL.md +166 -0
  116. package/lib/skills/req-compile/SKILL.md +131 -0
  117. package/lib/skills/req-create/SKILL.md +124 -0
  118. package/lib/skills/req-extract-decisions/SKILL.md +241 -0
  119. package/lib/skills/req-finalize/SKILL.md +251 -0
  120. package/lib/skills/req-retire/SKILL.md +185 -0
  121. package/lib/skills/req-update/SKILL.md +265 -0
  122. package/lib/skills/research/SKILL.md +250 -0
  123. package/lib/skills/research-company/SKILL.md +345 -0
  124. package/lib/skills/roadmap-add/SKILL.md +238 -0
  125. package/lib/skills/roadmap-create/SKILL.md +223 -0
  126. package/lib/skills/roadmap-next/SKILL.md +132 -0
  127. package/lib/skills/security-audit/SKILL.md +246 -0
  128. package/lib/skills/serena-config/SKILL.md +92 -0
  129. package/lib/skills/simplify/SKILL.md +227 -0
  130. package/lib/skills/tackle/SKILL.md +156 -0
  131. package/lib/skills/task-add/SKILL.md +208 -0
  132. package/lib/skills/task-audit/SKILL.md +294 -0
  133. package/lib/skills/task-trash/SKILL.md +115 -0
  134. package/lib/skills/task-update/SKILL.md +136 -0
  135. package/lib/skills/uat-auto/SKILL.md +69 -0
  136. package/lib/skills/uat-auto-plus/SKILL.md +115 -0
  137. package/lib/skills/uat-generate/SKILL.md +289 -0
  138. package/lib/skills/uat-skip/SKILL.md +169 -0
  139. package/lib/skills/uat-walk/SKILL.md +164 -0
  140. package/lib/skills/uat-walk/UAT-CORE.md +140 -0
  141. package/lib/skills/update-docs/SKILL.md +75 -0
  142. package/lib/skills/wiki-archive/SKILL.md +96 -0
  143. package/lib/skills/wiki-ingest/SKILL.md +139 -0
  144. package/lib/skills/wiki-lint/SKILL.md +131 -0
  145. package/lib/skills/wiki-query/SKILL.md +71 -0
  146. package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
  147. package/lib/skills/wiki-tidy/SKILL.md +107 -0
  148. package/package.json +32 -0
  149. package/raw/.gitkeep +0 -0
  150. package/raw/design-principles.md +65 -0
  151. package/raw/guides/command-anti-patterns.md +79 -0
  152. package/raw/guides/deployment-strategy.md +448 -0
  153. package/raw/guides/evals-framework.md +452 -0
  154. package/raw/guides/mcp-tools.md +335 -0
  155. package/raw/guides/task-spec.md +79 -0
  156. package/raw/guides/type-checking-templates/README.md +112 -0
  157. package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
  158. package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
  159. package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
  160. package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
  161. package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
  162. package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
  163. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
  164. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
  165. package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
  166. package/raw/harness-notes.md +20 -0
  167. package/raw/house-style/components/Badge.tsx +16 -0
  168. package/raw/house-style/components/Button.tsx +32 -0
  169. package/raw/house-style/components/Card.tsx +26 -0
  170. package/raw/house-style/components/Chip.tsx +57 -0
  171. package/raw/house-style/components/IconButton.tsx +67 -0
  172. package/raw/house-style/components/Modal.tsx +18 -0
  173. package/raw/house-style/components/Stepper.tsx +141 -0
  174. package/raw/house-style/components/icons.tsx +128 -0
  175. package/raw/house-style/preview/src/index.css +46 -0
  176. package/raw/house-style/tokens/tailwind.preset.ts +49 -0
  177. package/raw/house-style/tokens/tokens.json +62 -0
  178. package/raw/llm-wiki-2.md +162 -0
  179. package/raw/llm-wiki.md +75 -0
  180. package/raw/research/dark-mode-theme/index.md +85 -0
  181. package/raw/research/dark-mode-theme/sources.md +49 -0
  182. package/raw/research/serena-mcp-disconnect/index.md +81 -0
  183. package/raw/research/serena-mcp-disconnect/sources.md +87 -0
  184. package/raw/research/wiki-tooling-improvements/index.md +126 -0
  185. package/raw/research/wiki-tooling-improvements/sources.md +73 -0
  186. package/raw/software-factory-case-study.pdf +0 -0
@@ -0,0 +1,140 @@
1
+ # UAT-CORE — shared procedures for the UAT family
2
+
3
+ Steps 1–5 and the closure procedure are identical (or near-identical) across `/uat-walk`, `/uat-auto`, and `/uat-auto-plus`. They live here once. Each SKILL.md defines only what differs for its mode; where a step varies, a **Mode differences** note names the deltas.
4
+
5
+ **Pipeline:** `/task-add → /tackle → /uat-generate → {uat-walk | uat-auto | uat-auto-plus} → archive/`. Tasks stay at their stable path in `wiki/work/tasks/` until UAT passes; on all-pass this procedure flips the task to `done` and archives both files. Files never move except into `archive/`.
6
+
7
+ **Status vocabulary** (only the status line ever changes — never reformat anything else in a test block):
8
+
9
+ | Marker | Meaning |
10
+ |--------|---------|
11
+ | `- [ ] Pass` | untested (pending) |
12
+ | `- [x] Pass <!-- YYYY-MM-DD -->` | passed |
13
+ | `- [FAIL: <reason>] <!-- YYYY-MM-DD -->` | failed (blocking) |
14
+ | `- [FIXING: <note>] <!-- YYYY-MM-DD -->` | fix in progress (blocking, always temporary) |
15
+ | `- [SKIP: <reason>] <!-- YYYY-MM-DD -->` | skipped — **human verdict only** |
16
+
17
+ A UAT file is **complete** when no test has a blocking status (`[FAIL]` / `[FIXING]`). `[x] Pass` and `[SKIP]` are non-blocking; `- [ ] Pass` is non-blocking only when the active mode excludes it.
18
+
19
+ ---
20
+
21
+ ## Step 1 — Resolve & parse the UAT file
22
+
23
+ Resolve `$ARGUMENTS` to one file in `wiki/work/uat/` (files never move — no `completed/` subdir; use Serena `list_dir`/`find_file`):
24
+
25
+ | Input | Action |
26
+ |-------|--------|
27
+ | File path (`wiki/work/uat/UAT-003-user-auth.md`) | use directly |
28
+ | Number-slug (`UAT-003`, `003-user-auth`) | match in `wiki/work/uat/`; if none, STOP + report |
29
+ | Number / description (`3`, `user auth`) | search `wiki/work/uat/`; if ambiguous, resolve per mode |
30
+ | Empty / unresolved | auto-pick per mode |
31
+
32
+ **Mode differences (resolution):**
33
+ - **uat-walk** — ambiguous input: list matches, ask the user to clarify. No auto-pick; empty/unresolved → STOP and report.
34
+ - **uat-auto / uat-auto-plus** — never prompt. Ambiguous input → STOP and report in the completion summary. Empty/unresolved → enumerate `status: pending` files in `wiki/work/uat/`, pick the lowest `<NNN>` prefix, announce in one line (`No matching UAT file — running \`<filename>\``), proceed without confirmation. If none pending, STOP: "No pending UAT files found".
35
+
36
+ If the resolved file is missing, empty, or outside `wiki/work/uat/`, STOP (walk: warn + confirm; auto/plus: exit with a diagnostic summary).
37
+
38
+ **Parse** the file for: `### UAT-*` test headings (e.g. `UAT-API-001:`, `UAT-UI-002:`); `## Prerequisites` items; each test's status marker (see vocabulary). Count totals per status. If every test is already resolved (no `- [ ] Pass`, `[FAIL]`, or `[FIXING]`), skip straight to **Closure**.
39
+
40
+ ---
41
+
42
+ ## Step 2 — Prerequisites
43
+
44
+ For each unchecked prerequisite: if it is a **runnable check** (server on a port, DB migrated, file exists), verify with one deterministic command — one Bash call per prerequisite (`curl`, `pg_isready`, port probe, file test). If it is **descriptive only** ("test data loaded"), it is **unverifiable** — never assume it holds.
45
+
46
+ **Mode differences (prerequisites):**
47
+ - **uat-walk** — after auto-checking, present all prerequisites at once grouped as **auto-verified ✅** and **needs-confirmation ❓** (unverifiable or failed). If all auto-verify, note it in one line and proceed without asking. Otherwise ask the user to confirm the ❓ ones; a failed prerequisite is a warning, the user decides whether to continue.
48
+ - **uat-auto** — hard gate: any prerequisite that fails or is unverifiable aborts the run. Mark every untested test `[FAIL: auto-judge: prerequisite not satisfied — <which>]` and go to Closure.
49
+ - **uat-auto-plus** — attempt **one** autonomous repair per failing runnable prerequisite (start the dev server in a background Bash call + `Monitor` for ready; run the migrate command; run the seed command; obtain a missing env var only if `.env.test` or equivalent documents how). Re-verify. If it still fails after one repair, apply the uat-auto hard gate. Track background processes started here — Closure terminates them.
50
+
51
+ ---
52
+
53
+ ## Step 3 — Classify tests
54
+
55
+ | Type | Signal |
56
+ |------|--------|
57
+ | **API/CLI** | contains `curl`/`http`/`wget` or a shell code block in Steps/Expected, **or** has an `Endpoint:` field |
58
+ | **UI** | `UAT-UI-*` prefix, or `Page:` / `Components:` metadata |
59
+ | **Manual** | anything else (edge cases, concurrency, integration logic) |
60
+
61
+ ---
62
+
63
+ ## Step 3.5 — Stub detection (headless modes only)
64
+
65
+ **uat-auto / uat-auto-plus only.** `/uat-walk` skips this — a human evaluates each test regardless. Run this gate for every eligible test **before** executing any (classify all in Step 3, then sweep, then execute non-stubs).
66
+
67
+ A stub test **stays `- [ ] Pass`** — do not execute it, do not record `[FAIL]`, do not enter the fix loop (implementing a feature from scratch is out of scope). Surface it in the summary.
68
+
69
+ 1. **Target** — API/CLI: `Endpoint:` or URL in `**Command**:`; UI: `Page:`/`Components:`; Manual: feature name from `Description`.
70
+ 2. **Locate** the implementation via `mcp__serena__search_for_pattern` across `src/`/`app/`/`lib/`. If nothing is found, treat as **unlocatable** → run the test normally (cannot confirm stub).
71
+ 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
+ 4. **Found** → leave status untouched, record `stub-detected` (with file + indicator) in run tracking, skip execution. **Not found / unlocatable** → proceed to Step 4.
73
+
74
+ ---
75
+
76
+ ## Step 4 — Execute & judge
77
+
78
+ Work through eligible tests in document order; update the file immediately after each verdict (Step 5).
79
+
80
+ **Eligibility (headless modes):** default is **pending + previously-failed** — every `- [ ] Pass` or `[FAIL: ...]` test. Reset `[FAIL: ...]` (and, in auto-plus, `[FIXING: ...]`) to `- [ ] Pass` before running so a fresh verdict is recorded. Leave `[x] Pass` and `[SKIP: ...]` untouched. `/uat-walk` selects tests by its own mode prompt instead (see its SKILL.md).
81
+
82
+ ### Auto-judge criteria (uat-auto / uat-auto-plus)
83
+
84
+ **API/CLI** — extract the command from `**Command**:`. No extractable command → `[FAIL: auto-judge: no machine-executable command in test body]`. Pass requires **ALL**:
85
+ 1. Command exited cleanly (response returned; no connection error).
86
+ 2. HTTP status matches the Expected section's explicit status; if none specified, any 2xx is pass-eligible on status alone.
87
+ 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
+ 4. If the test references `$UAT_AUTH_TOKEN`, the token must be present in the environment.
89
+
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]`.
91
+
92
+ **UI** → always `[FAIL: auto-judge: UI test requires human verification — use /uat-walk]`. No navigation, screenshot, or browser interaction.
93
+
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.
95
+
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).
97
+
98
+ ### Bash hygiene — API/CLI tests (all modes)
99
+
100
+ **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
+
102
+ 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
+
104
+ ---
105
+
106
+ ## Step 5 — Update the file per verdict
107
+
108
+ Use the **`Edit`** tool — **one `Edit` call per status line**, even when many flip in a row. **Never** `sed`, `awk`, `perl -i`, or `echo` to flip a marker (each triggers an approval prompt; see `.docs/guides/mcp-tools.md` "Common anti-patterns"). Replace only the status line with the appropriate marker + `<!-- YYYY-MM-DD -->`. Do not modify any other part of the test block — preserve all metadata, headings, and whitespace exactly.
109
+
110
+ ---
111
+
112
+ ## Closure — completion & file movement
113
+
114
+ Runs once no test has a blocking status. Two outcomes.
115
+
116
+ ### All pass (no `[FAIL]` / `[FIXING]` remain)
117
+
118
+ 1. **UAT status** — Edit `status:` → `passed`; bump `updated:` in the UAT frontmatter.
119
+ 2. **Task status** — read `task:` from the UAT frontmatter → open `wiki/work/tasks/TASK-NNN-slug.md`, Edit `status:` → `done`; bump `updated:`. (Expected prior status is `pending-uat`, set by `/tackle` when it finished implementation — but flip to `done` regardless of what's there now.)
120
+ 3. **Remove index rows** — delete the UAT row from `wiki/work/uat/index.md` and the task row from `wiki/work/tasks/index.md` (one `Edit` per file).
121
+ 4. **Archive both** (`git mv` via Bash; index appends via `Edit`):
122
+ - `git mv wiki/work/uat/<UAT>.md wiki/work/uat/archive/` → append `| [[UAT-NNN]] | Title | passed | YYYY-MM-DD |` to `wiki/work/uat/archive/index.md`
123
+ - `git mv wiki/work/tasks/<TASK>.md wiki/work/tasks/archive/` → append `| [[TASK-NNN]] | Title | done | YYYY-MM-DD |` to `wiki/work/tasks/archive/index.md`
124
+ 5. **Roadmap auto-checkoff** — scan `wiki/work/roadmaps/` for `status: active` files. For each: Edit `- [ ] [[TASK-NNN` → `- [x] [[TASK-NNN`; then sweep remaining `- [ ]` free-text lines, checking the ones the completing task clearly accomplished (leave uncertain ones). If all items are now `[x]`: flip roadmap `status: done`, bump `updated:`, remove its row from `wiki/work/roadmaps/index.md`, `git mv` it to `archive/`, and append `| [[ROADMAP-NNN]] | Title | done | YYYY-MM-DD |` to `wiki/work/roadmaps/archive/index.md`. Silent no-op if no roadmap references the task. `Edit` only (except `git mv`).
125
+ 6. **Decision annotation** — check the task body for `implements::[[DEC-NNNN#DM]]`. If found: open `wiki/work/decisions/NNNN-slug.md`, append `— implemented YYYY-MM-DD` to this task's `Source task(s):` line. Then check `wiki/work/tasks/` **and** `tasks/archive/` for other `todo|in-progress` tasks with the same `implements::[[DEC-NNNN#DM]]`; if none remain, append `— decision fully implemented YYYY-MM-DD` on a new line in the `## DM.` block. Sweep remaining `- [ ]` items in that block, checking the ones this task accomplished. `Read` then `Edit` only — never `sed`.
126
+ 7. **Log entry** — append to `wiki/log.md`:
127
+ ```
128
+ ## [YYYY-MM-DD] uat | UAT-NNN passed<MODE-TAG> · TASK-NNN done
129
+ Archived UAT-NNN → uat/archive/ and TASK-NNN → tasks/archive/. [one sentence on what was verified]
130
+ ```
131
+ `<MODE-TAG>`: walk → none · auto → ` (auto)` · auto-plus → ` (auto-plus)`.
132
+ 8. Emit the completion summary (task + UAT IDs, new `done`/`passed` statuses, archive paths).
133
+
134
+ **Mode differences (all-pass closure):**
135
+ - **uat-auto-plus** additionally: delete this task's screenshots (`mcp__serena__list_dir` `wiki/work/uat/screenshots/` for `<task-number>-*`, then `git rm` / `rm`); **terminate every background process** it started (prerequisites + fix attempts — KillShell as needed; verify none remain). Its decision-annotation step supports multi-task WIP tracking: with other WIP tasks remaining, set only this task's sub-line to `**done** YYYY-MM-DD`; when none remain, flip `**WIP**` → `**done** YYYY-MM-DD` and append `- **Decision fully implemented** YYYY-MM-DD`.
136
+ - **uat-auto** keeps screenshots (diagnostic evidence).
137
+
138
+ ### Any fail (`[FAIL]` markers remain)
139
+
140
+ Leave the UAT file in `wiki/work/uat/` (status stays `pending`/`in-progress`). Keep screenshots — diagnostic evidence for the next walkthrough. Emit the summary. **Headless modes exit 0** — an orchestrator treats the skill exiting as its task done; the pipeline decides what to do with the fail markers. **uat-auto-plus** also terminates all background processes before exit.
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: update-docs
3
+ description: Update task, UAT, and project documentation files to reflect implementation work just completed
4
+ category: executing
5
+ model: claude-sonnet-4-6
6
+ disable-model-invocation: false
7
+ user-invocable: true
8
+ ---
9
+ **Prereqs:** obey `.docs/guides/mcp-tools.md` + `wiki/work/tasks/lifecycle.md`.
10
+
11
+ # Update Documentation
12
+
13
+ Reflect the **most recent implementation work** in the project's markdown files. Scoped to the current session's changes — do not audit the entire docs tree.
14
+
15
+ ---
16
+
17
+ ## Scope
18
+
19
+ In scope:
20
+ - Task files in `wiki/work/tasks/` — checkbox state
21
+ - UAT files in `wiki/work/uat/` — folder moves only when triggered by `/uat-walk`, not here
22
+ - `PROJECT_STATUS.md` — progress + next steps (only if it exists)
23
+ - `CLAUDE.md` — only when slash commands, MCP requirements, or key files genuinely changed
24
+ - `README.md` — only when setup steps, tech stack, or project structure genuinely changed
25
+
26
+ Out of scope (do NOT touch):
27
+ - **Serena memories — NEVER call `mcp__serena__write_memory` or `mcp__serena__edit_memory` here, for any reason.**
28
+ - ADR or PRD files
29
+ - `.docs/guides/` files
30
+ - Any doc unrelated to the changes in this session
31
+
32
+ ---
33
+
34
+ ## Instructions
35
+
36
+ ### Step 1: Identify the Changes
37
+
38
+ In one pass, determine what shipped this session. Prefer `git status` / `git diff --stat` reasoning over re-exploring the codebase. If the session context already names the task and files touched, use that directly — do not re-discover.
39
+
40
+ ### Step 2: Update Task Files
41
+
42
+ For each `wiki/work/tasks/NNN-slug.md` whose steps were implemented:
43
+ - Flip `- [ ]` → `- [x]` for each completed step using **`Edit`** (one call per checkbox).
44
+ - Never `sed` / `awk` / `perl -i` / `echo >>`.
45
+ - Do **not** move the file. Task files stay in `wiki/work/tasks/` until `/uat-walk` archives them to `archive/`.
46
+
47
+ ### Step 3: Update `PROJECT_STATUS.md` (if it exists)
48
+
49
+ Skip this step entirely if the file is not present. Otherwise:
50
+ - Mark completed items.
51
+ - Update the "Next steps" section to reflect what's actually next.
52
+ - Keep edits surgical — no rewrites.
53
+
54
+ ### Step 4: Update `CLAUDE.md` and `README.md` Only If Warranted
55
+
56
+ Apply the "genuinely changed" gate:
57
+ - **`CLAUDE.md`** — edit only if a slash command, MCP requirement, or Key Files entry was added/renamed/removed.
58
+ - **`README.md`** — edit only if setup, tech stack, or top-level structure changed.
59
+
60
+ If neither qualifies, skip both. Do not edit just to bump dates or reword.
61
+
62
+ ### Step 5: Spot-Check Consistency
63
+
64
+ Quick scan only:
65
+ - Updated checkboxes match the work that landed.
66
+ - New file paths referenced in docs actually exist.
67
+ - No cross-references to deleted files.
68
+
69
+ No exhaustive audit — flag drift you happen to notice, do not search for it.
70
+
71
+ ---
72
+
73
+ ## Finish
74
+
75
+ Report what was edited (file paths, one line each).
@@ -0,0 +1,96 @@
1
+ ---
2
+ name: wiki-archive
3
+ description: Cleanup tool — sweep for work items with terminal status that were not auto-archived by their originating skill, and move them to archive/
4
+ category: wiki
5
+ model: claude-sonnet-4-6
6
+ ---
7
+
8
+ # Wiki Archive
9
+
10
+ > **Recovery sweep.** Skills that set terminal statuses (`uat-auto`, `uat-skip`, `bug-close`, etc.) now automatically move files to `archive/` at the time of completion. This skill finds any items that were missed — for example, items from before the auto-archive update, or edge cases where the originating skill didn't complete the move. In a healthy wiki, this skill finds nothing to do.
11
+
12
+ Move terminal work items from a family directory into `archive/` to reduce directory clutter. **Terminal items only** — items with active statuses are never moved. Safe because links use stable IDs, not paths.
13
+
14
+ ---
15
+
16
+ ## Usage
17
+
18
+ ```
19
+ /wiki-archive [family]
20
+ ```
21
+
22
+ `family` — one of `tasks`, `uat`, `bugs`, `requirements`, `decisions`, `roadmaps`. Omit to show a count summary across all families without moving anything.
23
+
24
+ ---
25
+
26
+ ## Step 1: Determine scope
27
+
28
+ If a family was specified, process only that family. Otherwise, scan all 6 families and report terminal item counts, then ask the user which families to archive.
29
+
30
+ For each family to process, read its `lifecycle.md` to confirm the **terminal statuses** for that family:
31
+ - **tasks**: `done`, `trashed`
32
+ - **uat**: `passed`, `skipped`, `trashed`
33
+ - **bugs**: `closed`, `wontfix`, `duplicate`, `cannot-reproduce`
34
+ - **requirements**: `retired`
35
+ - **decisions**: all decisions in the group are `accepted` or `superseded`
36
+ - **roadmaps**: `done`
37
+
38
+ Do NOT hardcode these — read `lifecycle.md` to confirm them before moving anything.
39
+
40
+ ## Step 2: Identify terminal items
41
+
42
+ Use `mcp__serena__list_dir` on the family directory. For each file (excluding `lifecycle.md`, `index.md`, `.gitkeep`, and everything under `archive/`):
43
+ 1. Read the file's `status:` frontmatter field (or per-decision block statuses for decisions).
44
+ 2. If the status is terminal → add to the move list.
45
+ 3. If the status is active → skip; never touch it.
46
+
47
+ If the move list is empty, report "No terminal items found in `<family>/`" and stop.
48
+
49
+ ## Step 3: Confirm with the user
50
+
51
+ Show the move list:
52
+ ```
53
+ Ready to archive N items from wiki/work/<family>/:
54
+ - TASK-023-some-slug.md (status: done)
55
+ - TASK-031-other.md (status: trashed)
56
+
57
+ This moves them to wiki/work/<family>/archive/. Links using [[TASK-023]] remain valid.
58
+ Proceed? (yes / skip)
59
+ ```
60
+
61
+ Wait for confirmation before moving.
62
+
63
+ ## Step 4: Move files and update archive/index.md
64
+
65
+ For each confirmed file:
66
+ 1. Use `Bash` with `mv` to move the file: `mv wiki/work/<family>/<file> wiki/work/<family>/archive/<file>`
67
+ 2. Read the file's `id`, `title`, `status`, and `updated` frontmatter fields.
68
+ 3. Append a row to `wiki/work/<family>/archive/index.md`:
69
+ ```
70
+ | [[ID]] | Title | final-status | YYYY-MM-DD |
71
+ ```
72
+ where the date is today's date.
73
+
74
+ Do NOT edit the moved file itself — its frontmatter and content are preserved exactly.
75
+
76
+ ## Step 5: Update wiki/log.md
77
+
78
+ Append one entry:
79
+ ```
80
+ ## [YYYY-MM-DD] archive | <family> — N items archived
81
+ Moved N terminal items from wiki/work/<family>/ to wiki/work/<family>/archive/. IDs: TASK-023, TASK-031, …
82
+ ```
83
+
84
+ ## Step 6: Report
85
+
86
+ Print a summary of what was moved. If any files were skipped (e.g., active status found unexpectedly), list them explicitly.
87
+
88
+ ---
89
+
90
+ ## CRITICAL rules
91
+
92
+ - **Never move an active item.** If a file's status is not in the terminal set for its family, skip it and warn.
93
+ - **Never edit content** of moved files — only the location changes.
94
+ - **Never delete** — archiving is moving, not deleting.
95
+ - **`archive/index.md` is append-only** — only add rows, never remove or edit existing rows.
96
+ - The `archive/` directory already exists in every family — do not create it.
@@ -0,0 +1,139 @@
1
+ ---
2
+ name: wiki-ingest
3
+ description: Process a source from raw/ into the wiki — write a summary page, update affected entity and concept pages, record the ingest in the index and log, and refresh the hot cache
4
+ category: researching
5
+ model: claude-sonnet-4-6
6
+ argument-hint: <raw-file-path>
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`.
11
+
12
+ # Wiki Ingest
13
+
14
+ Integrate a raw source document into the persistent wiki. The source is read once, distilled, and woven into the existing page network — summary page, entity pages, concept pages, index, and log — so the wiki compounds rather than the source sitting unprocessed. See `raw/llm-wiki.md` for the underlying pattern.
15
+
16
+ ---
17
+
18
+ **Source to ingest**: $ARGUMENTS
19
+
20
+ ---
21
+
22
+ ## Step 1: Read the Source Fully
23
+
24
+ 1. Resolve `$ARGUMENTS` to a file under `raw/`. If the path is ambiguous or missing, use `mcp__serena__find_file` against `raw/` to locate candidates and confirm with the user.
25
+ 2. Read the source **in full** with `Read` — never summarize from a partial read. For long files, read in sequential chunks until complete.
26
+ 3. Note the source type (article, spec, notes, data) and its date if discernible — recency matters when claims conflict.
27
+
28
+ ## Step 2: Discuss Key Takeaways
29
+
30
+ Before writing anything, present a brief summary to the user:
31
+
32
+ - 3–7 bullet key takeaways from the source
33
+ - Which existing wiki pages this source will touch (read `wiki/index.md` to determine this)
34
+ - Any apparent **contradictions** with existing wiki pages (see Rules below)
35
+
36
+ Keep this short — it is a checkpoint, not a report. Incorporate any emphasis or corrections the user offers.
37
+
38
+ ## Step 3: Write or Update the Summary Page
39
+
40
+ 1. Use `mcp__serena__list_dir` on `wiki/knowledge/sources/` to check whether a summary page for this source already exists.
41
+ 2. Write (or update) a summary page in `wiki/knowledge/sources/` with a **kebab-case filename** derived from the source title (e.g. `raw/Some Article.md` → `wiki/knowledge/sources/some-article.md`). Create the directory if it does not exist.
42
+ 3. Frontmatter:
43
+ ```yaml
44
+ ---
45
+ id: some-article
46
+ title: Some Article
47
+ updated: YYYY-MM-DD
48
+ sources:
49
+ - ../../raw/some-article.md
50
+ confidence: extracted
51
+ tags: []
52
+ ---
53
+ ```
54
+ Set `confidence` per the confidence decision rule (see CRITICAL RULES) — choose `extracted`, `inferred`, or `ambiguous` based on how the page's claims relate to the source; do not leave it hard-coded at `extracted`.
55
+
56
+ **Choosing `confidence`:** this field applies to `knowledge/` pages only (`sources/`, `concepts/`, `entities/`) — `work/` artifacts track state with `status` instead. Pick one value per page based on the page's dominant claims (aligned with `wiki/conventions.md` §4):
57
+ - **`extracted`** (default) — the page restates what a `raw/` source directly says.
58
+ - **`inferred`** — the page's claims are LLM synthesis or reasoning that goes beyond what any source states directly.
59
+ - **`ambiguous`** — sources disagree, or the claim is genuinely uncertain.
60
+
61
+ Omitting `confidence` means `extracted`; set it explicitly only for `inferred` or `ambiguous` pages. Steps 4 and 5 use this same note.
62
+ 4. Body: 2–4 paragraph distillation. Bold key claims. Add typed links to entities and concepts mentioned: `rel::[[Entity Name]]` (e.g. `derived_from::`, `uses::`, `relates_to::`).
63
+
64
+ ## Step 4: Update or Create Entity Pages
65
+
66
+ For each person, organisation, tool, or component mentioned significantly in the source:
67
+
68
+ 1. Determine the entity sub-type: `people`, `organisations`, `tools`, or `components` (components = this project's own modules/skills/scripts).
69
+ 2. Check `wiki/knowledge/entities/<sub-type>/` for an existing page.
70
+ 3. **Existing page**: add a new section or bullet noting what this source says. Never remove existing content. Use a `> **Contradiction:**` callout if the new claim conflicts.
71
+ 4. **New page**: create `wiki/knowledge/entities/<sub-type>/<entity-slug>.md` with frontmatter:
72
+ ```yaml
73
+ ---
74
+ id: entity-slug
75
+ title: Entity Name
76
+ aliases: [Alternative Name]
77
+ updated: YYYY-MM-DD
78
+ sources:
79
+ - ../../../raw/some-article.md
80
+ confidence: extracted
81
+ tags: []
82
+ ---
83
+ ```
84
+ Body: 1–2 paragraphs with key facts. Add typed links.
85
+
86
+ ## Step 5: Update or Create Concept Pages
87
+
88
+ For each pattern, idea, convention, or recurring theme the source illuminates:
89
+
90
+ 1. Check `wiki/knowledge/concepts/` for an existing page.
91
+ 2. **Existing**: extend or cross-link; add contradiction callout if needed.
92
+ 3. **New**: create `wiki/knowledge/concepts/<concept-slug>.md` with frontmatter (`id`, `title`, `updated`, `sources`, `confidence`, `tags`) and a focused distillation.
93
+
94
+ ## Step 6: Update the Home Index
95
+
96
+ In `wiki/index.md`:
97
+ - Under **Sources**: add `- [Source Title](knowledge/sources/source-slug.md) — one-line summary` (knowledge pages are listed in the home index; work items are not).
98
+ - Under the relevant entity sub-type: add or update the entity listing.
99
+ - Under **Concepts**: add any new concept pages.
100
+
101
+ Use a single `Edit` call per section.
102
+
103
+ ## Step 7: Append to the Log
104
+
105
+ Append to `wiki/log.md`:
106
+ ```
107
+ ## [YYYY-MM-DD] ingest | <source title>
108
+ Ingested from raw/<filename>. Key claims: [2–3 bullet summary]. [N] entity pages touched, [M] concept pages touched.
109
+ ```
110
+
111
+ ## Step 8: Refresh the Hot Cache
112
+
113
+ This is the canonical **Hot Cache Refresh** procedure — other wiki-writing skills reference it by name rather than restating it.
114
+
115
+ `wiki/hot.md` is a small, always-read-first session-handoff summary of "what changed most recently" (see `wiki/knowledge/concepts/llm-wiki-hot-cache.md`). It is a **regenerated summary, never an append log** — you rewrite it in full each time. Overwrite the whole file with `Write`; do not `Edit` in new lines.
116
+
117
+ 1. **Read for continuity** — if `wiki/hot.md` exists, `Read` it (chiefly for its `## Active Threads` section, which carries forward in-flight work the current operation may not touch). If it does not exist, start from the template at `lib/scripts/templates/wiki/hot.md`.
118
+ 2. **Read recent context** — read the last ~5–10 entries of `wiki/log.md` (the tail) plus the pages this operation just created or updated. These are the raw material for "what changed."
119
+ 3. **Regenerate all four sections**, keeping the whole file **under ~500 words**:
120
+ - Frontmatter: `title: Hot Cache`, `updated: <today>`.
121
+ - `# Hot Cache` heading, the intro sentence, and `_Last updated: <today>_`.
122
+ - `## Key Recent Facts` — the handful of things a fresh session most needs to know right now (include what this operation just did).
123
+ - `## Recent Changes` — `Created:` / `Updated:` / `Flagged:` sub-bullets naming the pages/files this operation (and other very recent ones still worth surfacing) touched.
124
+ - `## Active Threads` — in-flight work (roadmaps mid-execution, tasks in progress, waves pending), carried forward from the prior `hot.md` and adjusted for what just changed.
125
+ 4. **Drop stale items** — if a fact is no longer "recent," remove it; its durable form already lives in a knowledge or work page.
126
+ 5. **Overwrite** `wiki/hot.md` with `Write`.
127
+
128
+ ---
129
+
130
+ ## CRITICAL RULES
131
+
132
+ 1. `raw/` is **immutable** — never create, modify, move, or delete files under `raw/`.
133
+ 2. The **two-domain rule** — timeless synthesis belongs under `wiki/knowledge/`; never file a source summary or concept page under `wiki/work/`.
134
+ 3. **Flag contradictions explicitly** — add a `> **Contradiction:**` callout citing both the new source and the conflicting page; never silently overwrite.
135
+ 4. Use **relative links** from the file's location: a page at `wiki/knowledge/sources/` reaches `raw/` as `../../raw/`, reaches concepts as `../concepts/`, reaches entities as `../entities/`.
136
+ 5. Add `id:` and `aliases:` frontmatter to every page you create or touch.
137
+ 6. Use typed links (`derived_from::`, `uses::`, `relates_to::`, `contradicts::`) wherever a link has a meaning — see `wiki/conventions.md` for the full vocabulary.
138
+ 7. **Work artifacts** (requirements, decisions, tasks, bugs) are never modified by this skill — only knowledge pages and the home index.
139
+ 8. **Set `confidence` on every knowledge page** you create or update, chosen per the "Choosing `confidence`" note in Step 3 (omission defaults to `extracted`, but set it explicitly for `inferred`/`ambiguous` pages). When rule 3 makes you flag a `> **Contradiction:**` callout, the affected page carries `confidence: ambiguous` (or otherwise lower confidence) — a flagged contradiction and an `ambiguous` value travel together.
@@ -0,0 +1,131 @@
1
+ ---
2
+ name: wiki-lint
3
+ description: Health-check the wiki — find contradictions, stale claims, orphan pages, missing concept pages, missing cross-references, and never-ingested raw sources; fix only with approval
4
+ category: researching
5
+ model: claude-sonnet-4-6
6
+ disable-model-invocation: false
7
+ user-invocable: true
8
+ ---
9
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`.
10
+
11
+ # Wiki Lint
12
+
13
+ Audit the wiki for structural and semantic problems. Report findings ranked by severity. **Never fix anything without explicit user approval.**
14
+
15
+ ---
16
+
17
+ ## Step 1: Inventory the wiki tree
18
+
19
+ Use `mcp__serena__list_dir` on:
20
+ - `wiki/` (top-level)
21
+ - `wiki/knowledge/` (recursive)
22
+ - `wiki/work/` (recursive)
23
+ - `raw/` (to find never-ingested sources)
24
+
25
+ Build a complete file list.
26
+
27
+ ## Step 2: Run all checks
28
+
29
+ ### 2.0 Stranded terminal files (HIGH)
30
+
31
+ For each work family, scan the active directory (excluding `lifecycle.md`, `index.md`, `.gitkeep`, and anything under `archive/`). For each file, read its `status:` frontmatter. If the status is in the terminal set for that family (read each family's `lifecycle.md` — do NOT hardcode), report it as a stranded file.
32
+
33
+ Report format:
34
+ ```
35
+ [HIGH] stranded terminal file — wiki/work/tasks/TASK-014-some-slug.md has status: done but is not in archive/
36
+ ```
37
+
38
+ Proposed fix for each: `git mv wiki/work/<family>/<file>.md wiki/work/<family>/archive/<file>.md`
39
+
40
+ These should have been auto-archived by the skill that set the terminal status.
41
+
42
+ ### 2.1 Family-index drift (HIGH)
43
+
44
+ For each work family (`requirements`, `decisions`, `roadmaps`, `tasks`, `uat`, `bugs`):
45
+ 1. Read the family's `index.md`.
46
+ 2. For each row in the index: verify the linked file exists in the family directory; verify the file's `status:` frontmatter matches an **active** status for that family (read each family's `lifecycle.md` for the valid active statuses — do NOT hardcode them).
47
+ 3. For each file in the family directory (excluding `lifecycle.md`, `index.md`, `.gitkeep`, and anything under `archive/`): read its `status:` frontmatter; if the status is **not** in the active set, verify its row is absent from the active index. Files in `archive/` are terminal by definition — they should not appear in the active `index.md` but their presence in `archive/` is correct.
48
+
49
+ Report:
50
+ - Active item missing from index
51
+ - Non-active item still listed in index
52
+ - Index row pointing at a missing file
53
+
54
+ ### 2.2 Two-domain violations (HIGH)
55
+
56
+ - Any file under `wiki/knowledge/` that has a `status:` frontmatter key (stateful artifacts don't belong in knowledge)
57
+ - Any file under `wiki/work/` that lacks a `status:` frontmatter key (work artifacts must be status-driven)
58
+ - Any file under `wiki/knowledge/` whose name matches a work-family ID pattern (REQ-NNN, TASK-NNN, BUG-NNNN, etc.)
59
+
60
+ ### 2.3 ID / filename mismatch (MEDIUM)
61
+
62
+ For each file in `wiki/work/`: verify that the `id:` frontmatter value matches the filename prefix (e.g. `id: TASK-014` → filename must start with `TASK-014`). Report mismatches.
63
+
64
+ ### 2.4 UAT ↔ Task cross-link integrity (MEDIUM)
65
+
66
+ For each UAT file in `wiki/work/uat/`:
67
+ - The `task:` frontmatter must point to an existing task file in `wiki/work/tasks/`.
68
+ - The referenced task file must have a `uat:` frontmatter link back to this UAT.
69
+
70
+ Report broken or asymmetric links.
71
+
72
+ ### 2.5 Typed-link vocabulary (LOW)
73
+
74
+ Scan all wiki pages for `::[[` patterns. Verify the relationship keyword (the part before `::`) is in the vocabulary defined in `wiki/conventions.md`. Report unknown keywords.
75
+
76
+ ### 2.6 Orphan pages (LOW)
77
+
78
+ Pages that appear in the file tree but are not linked from any other wiki page (including `wiki/index.md`).
79
+
80
+ ### 2.7 Never-ingested raw sources (LOW)
81
+
82
+ List files in `raw/` (excluding `.gitkeep`) that have no matching summary page in `wiki/knowledge/sources/`.
83
+
84
+ ### 2.8 Contradictions (MEDIUM)
85
+
86
+ Scan all pages for `> **Contradiction:**` callouts; list them so the user can resolve or confirm they are intentional.
87
+
88
+ ### 2.9 Stale frontmatter (LOW)
89
+
90
+ Pages where `updated:` is more than 90 days old — these may contain outdated claims.
91
+
92
+ ### 2.10 Provenance / confidence (LOW)
93
+
94
+ **Knowledge pages only.** Scan every page under `wiki/knowledge/sources/`, `wiki/knowledge/concepts/`, and `wiki/knowledge/entities/` (recursive, excluding `index.md` and `.gitkeep`). Skip `wiki/work/` entirely — work artifacts track state with `status`, not `confidence`.
95
+
96
+ Read each page's `confidence:` frontmatter value (defined in `wiki/conventions.md` §4: `extracted` (default, source-backed), `inferred` (LLM synthesis beyond the source), `ambiguous` (sources disagree / uncertain)) and classify:
97
+
98
+ - **Weak provenance** — `confidence: inferred` or `confidence: ambiguous`. The page's claims are not source-backed; surface so the user can weigh or re-ground them. This is the primary signal.
99
+ - **Untagged provenance** — no `confidence` key at all. Per the convention this defaults to `extracted`, so it is **not** a defect — report it only as an informational nudge to add an explicit tag on the page's next revision (`/wiki-ingest` populates the field on pages it writes going forward).
100
+ - **`confidence: extracted`** (or the default) — no finding.
101
+
102
+ Report format:
103
+ ```
104
+ [LOW] weak provenance — wiki/knowledge/concepts/foo.md is confidence: inferred (not source-backed)
105
+ [LOW] untagged provenance — wiki/knowledge/entities/tools/bar.md has no confidence key (defaults to extracted; add an explicit tag on next revision)
106
+ ```
107
+
108
+ Report-only — provenance is a human judgment (whether a page is genuinely `inferred`), so these are never auto-fixed (see Step 4).
109
+
110
+ ## Step 3: Report findings
111
+
112
+ Group by severity (HIGH / MEDIUM / LOW). For each finding:
113
+ ```
114
+ [HIGH] family-index drift — tasks/index.md row for TASK-014 but file status is: done
115
+ ```
116
+
117
+ Summarize total counts per severity.
118
+
119
+ ## Step 4: Propose fixes
120
+
121
+ For each HIGH finding, propose the exact `Edit` operation that would fix it. Do not apply without approval.
122
+
123
+ Ask: **"Which findings should I fix?"** — wait for the user's reply before making any edits.
124
+
125
+ ## Step 5: Apply approved fixes only
126
+
127
+ For each approved fix, apply it with a single `Edit` call. After all fixes, append one log entry to `wiki/log.md`:
128
+ ```
129
+ ## [YYYY-MM-DD] lint | <N> issues found, <M> fixed
130
+ Summary of findings and fixes applied.
131
+ ```
@@ -0,0 +1,71 @@
1
+ ---
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
4
+ category: researching
5
+ model: claude-sonnet-4-6
6
+ argument-hint: <question>
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`.
11
+
12
+ # Wiki Query
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.**
15
+
16
+ ---
17
+
18
+ **Question**: $ARGUMENTS
19
+
20
+ ---
21
+
22
+ ## Step 1: Orient via the Index
23
+
24
+ 1. Read `wiki/index.md` in full — it is the home Map of Content.
25
+ 2. Identify the most relevant sections (Sources, Concepts, Entities, and the Work family indexes if the question is about in-flight work).
26
+ 3. Read the linked pages. For work items, the family `index.md` files (`wiki/work/<family>/index.md`) list only active items — read those first, then read the individual files needed.
27
+
28
+ ## Step 2: Gather Evidence
29
+
30
+ Read each relevant page completely before synthesizing. Do not summarize from the first paragraph — check for contradictions, confidence caveats, and supersession markers throughout the page.
31
+
32
+ If a page cites a `sources:` raw file, read the raw source only if the page's distillation is insufficient.
33
+
34
+ ## Step 3: Synthesize and Cite
35
+
36
+ Answer the question in 2–5 paragraphs. For each claim, cite the wiki page: `([page title](relative/path/to/page.md))`.
37
+
38
+ If you found contradictions between pages, surface them explicitly with a `> **Contradiction:**` callout and note which source is more recent.
39
+
40
+ If the wiki has no coverage at all: say so clearly and suggest:
41
+ ```
42
+ This question isn't covered in the wiki yet.
43
+ To add coverage: /wiki-ingest raw/<relevant-source>
44
+ ```
45
+
46
+ ## Step 4: Offer to File the Answer Back
47
+
48
+ 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
+
50
+ ```
51
+ Worth filing this answer as a new wiki page?
52
+ Target: wiki/knowledge/concepts/<concept-slug>.md
53
+ ```
54
+
55
+ **Never file stateful work artifacts here** — requirements, decisions, tasks, bugs belong in `wiki/work/` and are created by their own skills (`/req-create`, `/decision-create`, etc.).
56
+
57
+ If the user says yes:
58
+ 1. Create `wiki/knowledge/concepts/<concept-slug>.md` with proper frontmatter (`id`, `title`, `updated`, `tags`, `sources` if derived from a raw source).
59
+ 2. Add a typed link `derived_from::[[source-slug]]` if the answer came from an ingested source.
60
+ 3. Add the new page to the **Concepts** section of `wiki/index.md`.
61
+ 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.
63
+
64
+ ---
65
+
66
+ ## CRITICAL RULES
67
+
68
+ 1. **Answer from the wiki, not general knowledge** — if the wiki lacks coverage, say so.
69
+ 2. **The two-domain rule** — filed answers (durable synthesis) go to `wiki/knowledge/`; never file under `wiki/work/`.
70
+ 3. All citations use relative markdown links to the wiki page, not raw file paths.
71
+ 4. Do not modify any `wiki/work/` files — this skill is read-only for work artifacts.