@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,156 @@
1
+ ---
2
+ name: tackle
3
+ description: Execute an outlined task file step-by-step with subagent delegation
4
+ category: executing
5
+ model: claude-sonnet-4-6
6
+ argument-hint: <path/to/task.md, number-slug, or description>
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `.docs/guides/mcp-tools.md` + `wiki/work/tasks/lifecycle.md`; run /primer if not done this session.
11
+
12
+ # Tackle Outline
13
+
14
+ Execute a pre-planned task file step-by-step. **The task file IS the plan — no re-planning.** Each `### N.` step names its agent via a `<!-- agent: TYPE -->` annotation (default `general-purpose`). This command is a pure executor: read → execute next step → update, one step per cycle.
15
+
16
+ **Outline File**: $ARGUMENTS
17
+
18
+ ---
19
+
20
+ ## Step 0: Resolve the task file
21
+
22
+ Resolve `$ARGUMENTS` (use Serena `find_file`/`list_dir`):
23
+
24
+ | Input | Action |
25
+ |-------|--------|
26
+ | File path (`wiki/work/tasks/3-user-auth.md`) | confirm exists; else fall through |
27
+ | Number-slug (`3-user-auth`) | match in `wiki/work/tasks/`; else fall through |
28
+ | Number / description (`3`, `user auth`) | search `wiki/work/tasks/`; ambiguous → list + ask; no match → fall through |
29
+ | Empty | run **Roadmap Auto-Discovery** (0a) first; only then the task survey |
30
+ | Non-empty but unresolved | task survey — recommend, never auto-pick |
31
+
32
+ Use the resolved path as the outline for all later steps.
33
+
34
+ **Mark work started:** if the resolved task's frontmatter `status` is `todo`, `Edit` it to `in-progress` now (main agent, not delegated) — this is the signal that implementation has begun, distinct from not-yet-started. Sync `wiki/work/tasks/index.md`'s `· status` suffix for this task in the same cycle (one `Edit`, skip if already `in-progress`).
35
+
36
+ ### Step 0a: Roadmap Auto-Discovery (empty `$ARGUMENTS` only)
37
+
38
+ Zero-click: find the first actionable roadmap item and tackle it, **no prompts**.
39
+
40
+ 1. `mcp__serena__list_dir("wiki/work/roadmaps/", recursive=false)` — root `.md` files only (exclude `archive/`, `README.md`). None → task survey.
41
+ 2. `Read` each roadmap (markdown). Select the one with the most `[x]` items (furthest along); tie/single → use it. No prompt.
42
+ 3. Scan top-to-bottom for the first `## Phase N` (or flat list) containing a `- [ ]` item. None unchecked → roadmap done → task survey.
43
+ 4. Take the first `- [ ]` line in that phase:
44
+ - **Task link** (markdown link into `wiki/work/tasks/`) → extract path, use as outline. Announce: `Roadmap auto-selected: <roadmap> → Phase <N>: <name> → <link text>`.
45
+ - **Inline item** (plain text) → treat text as a description, fall through to the task survey. Announce the inline item and that no task file exists.
46
+
47
+ ### Task survey (empty OR unresolved)
48
+
49
+ Recommend from the index; **do not auto-pick**.
50
+ - **Read only `wiki/work/tasks/index.md`** (canonical active list: bullet lines `- [TASK-NNN — Title](TASK-NNN-slug.md) — one-line summary · status`). Do NOT read individual task files, `grep`, `bash`, or aggregate across `wiki/work/tasks/` — the index exists to prevent exactly that. The only per-file read is the chosen task in Step 1.
51
+ - Missing `index.md` / no active-item bullets → STOP: `Task index at wiki/work/tasks/index.md is empty or missing. Add tasks with /task-add, or invoke /tackle <path-or-slug> directly.` Do not scan every file.
52
+ - `index.md` carries no progress columns — it lists title + one-line summary + `status` only, and `status` now directly distinguishes `todo` / `in-progress` / `pending-uat` (see [lifecycle](../tasks/lifecycle.md)) — no need to infer UAT-awaiting state from file existence. If a bullet points at a task file that no longer exists (moved/archived), note the drift in one sentence and skip it — don't pre-emptively fix the index.
53
+ - Empty active list → STOP: "No active tasks to tackle".
54
+ - Present the active items as a compact table (`TASK-NNN` · title · status). Below it, a **Recommendation** ranking top 1–3 by priority, using `status` alone:
55
+ 1. `status: in-progress` — finish what's started.
56
+ 2. `status: todo`, lowest-numbered first.
57
+ - Tasks at `status: pending-uat` are excluded from recommendations and listed under `**Awaiting UAT**:` — `mcp__serena__list_dir` on `wiki/work/uat/` for the matching `UAT-NNN-*` file; if found, suggest `/uat-walk wiki/work/uat/UAT-NNN-<slug>.md`; if none found (implementation finished but `/uat-generate` never ran), suggest `/uat-generate wiki/work/tasks/TASK-NNN-<slug>.md` instead.
58
+ - Progress counts, `[BLOCKED]`/`[FAILED]` flags, and per-step state are **not** in `index.md` by design — they live in the task files. This no-args survey deliberately ranks on `status` + UAT presence alone rather than re-reading every task file; use `/task-audit` when the full progress/blocker picture is needed. (Design note: the survey was simplified to `index.md`'s real bullet schema rather than expanding `index.md` with Progress/UAT/Flags columns, which would violate the "active items only, flat list" convention in `wiki/conventions.md`.)
59
+ - Use `AskUserQuestion` (top rec first, labelled `(Recommended)`; up to 2 more; `header` = number-slug). If input was unresolved, prefix one line noting it. Do NOT proceed to Step 1 until the user chooses.
60
+
61
+ ---
62
+
63
+ ## MANDATORY: Serena for all code operations
64
+
65
+ Every delegated sub-agent **MUST** use Serena, non-negotiable:
66
+
67
+ | Operation | Use | Never |
68
+ |-----------|-----|-------|
69
+ | Explore structure | `get_symbols_overview` | `Read` on code |
70
+ | Find symbol | `find_symbol` | `Grep` on code |
71
+ | Edit code | Serena symbolic / file-line tools | native `Edit` on code |
72
+ | Search code | `search_for_pattern` | `Grep` |
73
+ | Find files / dirs | `find_file`, `list_dir` | `Glob`, `find`, `ls`, `cat` |
74
+ | Library docs | Context7 | `WebSearch`/`WebFetch` |
75
+
76
+ Standard Read/Edit/Write are allowed for markdown and config (JSON, YAML, `.env`) only. **Every** sub-agent prompt must include: *"Use Serena for all code exploration/editing and all file/directory exploration. Standard Read/Edit/Write for markdown and config only. Never bash `ls`/`cat`/`find`/`grep`/`sed`. See `.docs/guides/mcp-tools.md`."*
77
+
78
+ **Verification scope: static gates only** (`bash -n`, typecheck, lint, unit tests). Runtime/E2E is the UAT phase's job — see `.docs/guides/command-anti-patterns.md#verification-belongs-to-the-right-phase`.
79
+
80
+ ---
81
+
82
+ ## Step 1: Read & parse the outline
83
+
84
+ **Delegate to an `Explore` sub-agent** (main agent does NOT read the outline directly). It reads via Serena and returns: ordered `### N.` sections, each with status and agent type. Missing/empty file → STOP + report. Status parsing: complete = `[x]`/`[DONE]`/`~~strikethrough~~`; in-progress = `[ ]`/`[WIP]`; not-started = unmarked; blocked = `[BLOCKED]`. Agent type from `<!-- agent: TYPE -->` (default `general-purpose`).
85
+
86
+ **Completion check:** all items complete → report "All tasks in outline complete!" and STOP.
87
+
88
+ ## Step 2: Execute the next incomplete step
89
+
90
+ **Delegate to the agent type named in that section's annotation.** All implementation runs in a sub-agent, never the main context. Next-step priority: (1) fix blockers, (2) continue WIP, (3) start first incomplete section.
91
+
92
+ **Delegate directly — no re-planning.** Pass the step's checkboxes and sub-details verbatim. Do not research, re-plan, or ask questions (that was `/task-add`'s job).
93
+
94
+ **CRITICAL:** max **3** sub-processes at a time; **always terminate** processes when done (dev servers, type checkers, long-running commands).
95
+
96
+ Every sub-agent prompt MUST include:
97
+ 1. The Serena mandate (above).
98
+ 2. The exact checkboxes + sub-details from the section, verbatim.
99
+ 3. **Static gates only** after the work: `bash -n` for shell scripts; the project typecheck (`pnpm typecheck`, `make types-backend`, `mypy`, …); lint and unit tests allowed. **Do NOT** run runtime/E2E: no scratch dirs, helper scripts against real paths, curl, rsync dry-runs, spawned servers, fixture seeding, or asserting on files the code just produced. If a step calls for runtime verification, mark it `[DEFERRED-TO-UAT]` and move on. **All type errors are caused by your changes — no exceptions** (the codebase is committed clean before every cycle; zero pre-existing errors). **NEVER `git stash` to "verify" if errors are pre-existing — banned.**
100
+ 4. Report completion status (success / partial / failure + reason).
101
+
102
+ ## Step 3: Update the outline
103
+
104
+ **Do this directly in the main agent — do NOT delegate** (simple text replacement).
105
+
106
+ ⛔ **HARD RULE — update immediately, never batch.** The moment a Step 2 sub-agent returns, the *next thing you do* is flip that step's checkboxes on disk. Do not dispatch the next sub-agent, continue the cycle, or defer updates. Step N's update lands before step N+1 begins.
107
+
108
+ 1. Use **`Edit`** — one call per checkbox line. **Never** `sed`/`awk`/`perl -i`/`echo` on task files, however many flip (ten `Edit`s right; one `sed` wrong + triggers approval). Markers: `[x]` done · `[WIP]` partial · `[BLOCKED: reason]` · `[FAILED: reason]`.
109
+ 2. Add `<!-- Updated: YYYY-MM-DD HH:MM -->`.
110
+ 3. Add any subtasks discovered during execution.
111
+ 4. **Keep `wiki/work/tasks/index.md` in sync** — `index.md` has no progress or flags columns, so there is nothing to recount there. The one thing to maintain is the `· status` suffix on this task's bullet line: if this cycle flips the task's frontmatter `status` (e.g. `todo` → `in-progress`), update the matching `· status` on its `index.md` line with a single `Edit` (skip if unchanged). Progress and flags live only in the task file.
112
+
113
+ ## Step 4: Repeat
114
+
115
+ Step 1 → 2 → 3 → 2 → 3 … **One step per cycle; never run Step 2 twice in a row.** The outline must visibly progress between every dispatch (so the user and any interrupting `/tackle` resumption see real-time state). Continue until all complete or interrupted.
116
+
117
+ ---
118
+
119
+ ## Important rules
120
+
121
+ - **Process management** — max 3 concurrent sub-agents; **always terminate all processes/sub-agents when done**, verify termination after each; a hung sub-agent → terminate + mark `[BLOCKED]`. The main agent NEVER runs implementation commands directly.
122
+ - **Error handling** — a failed sub-agent → `[FAILED: reason]`; do not auto-retry, continue with the next available task; all remaining blocked/failed → STOP + report.
123
+ - **Progress reporting** — each cycle: what completed, what's next, X of Y done.
124
+ - **Stopping** — all `[x]`; user interrupt; all remaining blocked/failed; outline invalid/unreadable.
125
+ - **No re-planning** — executor not planner. Don't research, re-plan, break down further, or ask questions. A step too vague to execute → `[BLOCKED: step needs more detail]` and move on. Agent annotations + step details are authoritative.
126
+ - **Mandatory delegation** — all steps except Step 3 (outline update) go to sub-agents; the main agent only orchestrates (receive → decide → delegate), never reads source, edits, or runs commands directly. Preserves the main context window.
127
+
128
+ ---
129
+
130
+ ## Completion (after all steps done)
131
+
132
+ ### Step 5: Mark implementation pending UAT
133
+
134
+ Before anything else: `Edit` the task's frontmatter `status` → `pending-uat` (main agent, not delegated) — every `## Steps` checkbox is now checked, so there's nothing left to implement, only to verify. Sync `wiki/work/tasks/index.md`'s `· status` suffix for this task in the same cycle (one `Edit`).
135
+
136
+ This is a real state, not a formality — `/roadmap-next` uses it to recommend `/uat-walk`/`/uat-auto` instead of `/tackle` for this task going forward. Do this even if you're about to immediately answer "No" to the UAT-generation gate below — a task with no UAT still needs `pending-uat` recorded (an explicit skip is `/uat-skip`'s job, not silence).
137
+
138
+ ### Step 6: UAT generation gate — ⛔ HARD STOP (never skip or reorder)
139
+ Ask via `AskUserQuestion`: **"Generate UAT tests for this task?"** — **Yes** → run `/uat-generate wiki/work/tasks/<filename>` (creates the matching UAT file); **No** → skip. **Wait** for the answer (and for `/uat-generate` to finish, if invoked) before Step 6b.
140
+
141
+ ### Step 6b: Type-check gate
142
+ Try in order, stop at the first that runs (exit 0 or type errors); skip to next only if not found / target missing: (1) `Skill(typecheck)`, (2) `make typecheck`. Suppress output from not-found/missing-target commands — surface only real type errors. None available → skip silently.
143
+ - **On type errors** → report them, mark the relevant step `[FAILED: type errors]`, and **do not** proceed to the banner. The user must resolve (or explicitly say skip) first.
144
+ - **On pass/skip** → banner.
145
+
146
+ ### Banner (output verbatim)
147
+ ```
148
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
149
+ TACKLE COMPLETED — all steps done
150
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
151
+ ```
152
+
153
+ ### Step 7: Suggest UAT
154
+ If UAT was generated, suggest `/uat-walk wiki/work/uat/<file>.uat.md`.
155
+
156
+ **Start now — read the outline and begin the first cycle.**
@@ -0,0 +1,208 @@
1
+ ---
2
+ name: task-add
3
+ description: Create a structured, execution-ready task file in wiki/work/tasks/
4
+ category: planning
5
+ model: claude-sonnet-4-6
6
+ argument-hint: <task description> [--decision DEC-NNNN#DM] [--roadmap ROADMAP-NNN]
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+
12
+ $ARGUMENTS
13
+
14
+ ---
15
+
16
+ **Instructions:**
17
+
18
+ ### Step 1: Summarize the user input
19
+
20
+ Extract the core task objective, scope, and any specific requirements from `$ARGUMENTS`.
21
+
22
+ ### Step 2: Parse and validate decision reference (only if `$ARGUMENTS` contains `--decision` or a `DEC-` token)
23
+
24
+ Detect a decision reference in any of these forms:
25
+ - `DEC-NNNN#DM` (e.g. `DEC-0007#D2`) — specific decision
26
+ - `NNNN#DM` (e.g. `0007#D2`) — specific decision
27
+ - `--decision DEC-NNNN#DM` or `--decision NNNN#DM` — flag form
28
+ - `DEC-NNNN` (no `#DM`) — **auto-detect** first accepted decision without a task
29
+
30
+ Strip the decision token and any `--decision` flag from `$ARGUMENTS` to get the clean task description.
31
+
32
+ Locate the decision file: use `mcp__serena__find_file` to find `NNNN-*.md` in `wiki/work/decisions/`.
33
+
34
+ **If no `#DM` was given (auto-detect)**: walk `## D1.`, `## D2.`, … blocks in order; find the first where `status: accepted` and the `### Links` section has no `Source task(s):` line. If every accepted decision already has a task reference, STOP and tell the user. If no accepted decisions exist, STOP and tell the user to run `/decision-finalize` first.
35
+
36
+ **Refuse if the resolved decision is not `accepted`**: STOP and tell the user to run `/decision-finalize <file>#DM` first.
37
+
38
+ Store `(decision_file_path, decision_id, decision_anchor)` for later steps.
39
+
40
+ If no decision reference: skip this step entirely.
41
+
42
+ ### Step 3: Parse and validate roadmap reference (only if `$ARGUMENTS` contains `--roadmap` or a `ROADMAP-` token)
43
+
44
+ Detect:
45
+ - `ROADMAP-NNN` — bare token
46
+ - `--roadmap ROADMAP-NNN` or `--roadmap NNN` — flag form
47
+
48
+ Strip the roadmap token from `$ARGUMENTS`.
49
+
50
+ Locate: `mcp__serena__find_file` for `NNN-*.md` in `wiki/work/roadmaps/`. If not found, STOP and report.
51
+
52
+ Confirm the file has `status: active` in its frontmatter. If `status: done`, warn the user and ask whether to proceed.
53
+
54
+ Store `(roadmap_file_path, roadmap_number)` for Step 9.
55
+
56
+ If no roadmap reference: skip this step entirely.
57
+
58
+ ### Step 4: Determine the next task number
59
+
60
+ Scan **all** task locations to find the next available number:
61
+ - `mcp__serena__list_dir` on `wiki/work/tasks/` and `wiki/work/tasks/archive/` (skip either that doesn't exist).
62
+ - Collect every `TASK-NNN` prefix from filenames across **both** directories. Take `max + 1`, zero-pad to 3 digits. The first task is `TASK-001`.
63
+ - Also scan `wiki/work/tasks/index.md` for any reserved IDs not yet on disk.
64
+ - Never re-use a number — IDs are immutable references, and archived tasks keep their original number forever (terminal tasks move to `archive/`; they don't stay in `wiki/work/tasks/`).
65
+
66
+ This number is a preview for planning; re-verify immediately before writing (Step 7a).
67
+
68
+ ### Step 5: Identify dependencies
69
+
70
+ Review active tasks by listing `wiki/work/tasks/` and reading the index at `wiki/work/tasks/index.md`. For each active task, determine whether the new task:
71
+ - **depends_on** it (requires it to complete first)
72
+ - **blocks** it (must complete before that task can start)
73
+ - **parallel_safe_with** it (can run concurrently without conflict)
74
+
75
+ Present a compact table and confirm with the user via `AskUserQuestion` before proceeding.
76
+
77
+ ### Step 6: Research and clarify approach
78
+
79
+ Investigate relevant code via Serena, consult Context7 for library docs if needed, use Brave Search for best practices. If multiple valid approaches exist, present a comparison and ask via `AskUserQuestion` before committing.
80
+
81
+ ### Step 7: Present the plan and confirm
82
+
83
+ Before writing, present:
84
+ - Core objective
85
+ - Key design decisions
86
+ - High-level step breakdown
87
+
88
+ Confirm with the user via `AskUserQuestion`.
89
+
90
+ ### Step 7a: Re-verify next task number — IMMEDIATELY before writing
91
+
92
+ Re-run the scan from Step 4. If the number planned in Step 7 is now taken, silently bump to the new next-available number. **Never call `Write` before completing this re-scan.**
93
+
94
+ ### Step 8: Create the task file
95
+
96
+ Create `wiki/work/tasks/TASK-NNN-slug.md` using the `Write` tool.
97
+
98
+ **Frontmatter** (required):
99
+ ```yaml
100
+ ---
101
+ id: TASK-NNN
102
+ title: "<task title>"
103
+ status: todo
104
+ created: YYYY-MM-DD
105
+ updated: YYYY-MM-DD
106
+ depends_on: []
107
+ blocks: []
108
+ parallel_safe_with: []
109
+ uat: ""
110
+ tags: []
111
+ ---
112
+ ```
113
+
114
+ Populate `depends_on`, `blocks`, and `parallel_safe_with` from Step 5 as lists of `TASK-NNN` IDs (empty list if none).
115
+
116
+ **Body structure**:
117
+
118
+ ```markdown
119
+ # TASK-NNN — Task Title
120
+
121
+ implements::[[DEC-NNNN#DM]] ← only when a decision reference was provided
122
+
123
+ ## Objective
124
+
125
+ <one paragraph describing what this task achieves>
126
+
127
+ ## Approach
128
+
129
+ <design decisions, trade-offs, chosen solution>
130
+
131
+ ## Steps
132
+
133
+ ### 1. Section Name <!-- agent: general-purpose -->
134
+
135
+ - [ ] Step detail
136
+ - Sub-detail: specific file paths, function names, etc.
137
+
138
+ ### 2. Next Section <!-- agent: general-purpose -->
139
+
140
+ - [ ] Step detail
141
+ ```
142
+
143
+ **The task file IS the plan.** `/tackle` executes steps verbatim. Every step must include specific file paths, function/component names, and enough implementation detail that an agent can execute without ambiguity.
144
+
145
+ Agent type annotations: valid types are `general-purpose`, `Explore`, `Plan`.
146
+
147
+ **Decision link** (only when Step 2 found an accepted decision reference): Insert `implements::[[DEC-NNNN#DM]]` as a typed link on the line immediately after the H1, before `## Objective`.
148
+
149
+ ### Step 9: Update the family index
150
+
151
+ Append to `wiki/work/tasks/index.md`:
152
+
153
+ ```
154
+ - [TASK-NNN — Title](TASK-NNN-slug.md) — one-line objective · todo
155
+ ```
156
+
157
+ If the file does not exist, create it with a `# Tasks` heading and the list entry. Insert in numeric order.
158
+
159
+ ### Step 10: Update the decision file (only when Step 2 found a decision reference)
160
+
161
+ In the decision's `### Links` section, add or append a `Source task(s):` line:
162
+
163
+ ```
164
+ - Source task(s): [[TASK-NNN]] — **WIP** (added YYYY-MM-DD)
165
+ ```
166
+
167
+ If no `### Links` section exists, create one before the closing `---` separator of that decision block. Use `Read` then `Edit` — never shell redirection.
168
+
169
+ ### Step 11: Update the roadmap file (only when Step 3 found a roadmap reference)
170
+
171
+ Read the roadmap file. Identify the last `## Phase N:` section (or any checklist section). Append a new `- [ ]` line:
172
+
173
+ ```
174
+ - [ ] [[TASK-NNN: <task title>]]
175
+ ```
176
+
177
+ Update the roadmap's `updated:` frontmatter field to today's date. Use `Read` then `Edit`.
178
+
179
+ ### Step 12: Append to wiki/log.md
180
+
181
+ Append:
182
+
183
+ ```
184
+ ## [YYYY-MM-DD] task | TASK-NNN <task title>
185
+ Created task TASK-NNN: <one sentence summarising the objective>.
186
+ ```
187
+
188
+ ### Step 13: Refresh the hot cache
189
+
190
+ The new task is durable, cross-session-relevant wiki state. 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 this task under Recent Changes (and Active Threads if it belongs to an in-flight roadmap). Do not restate the procedure here; follow it as written.
191
+
192
+ ### Step 14: Confirm completion
193
+
194
+ Report:
195
+ - Created file: `wiki/work/tasks/TASK-NNN-slug.md`
196
+ - Task ID: `TASK-NNN`
197
+ - Status: `todo`
198
+ - Next steps:
199
+
200
+ ```
201
+ To implement: /tackle wiki/work/tasks/TASK-NNN-slug.md
202
+ To generate tests: /uat-generate TASK-NNN
203
+ ```
204
+
205
+ If linked to a roadmap, mention which roadmap was updated and suggest:
206
+ ```
207
+ To see what's next: /roadmap-next wiki/work/roadmaps/NNN-slug.md
208
+ ```
@@ -0,0 +1,294 @@
1
+ ---
2
+ name: task-audit
3
+ description: Generate a dependency graph of active tasks showing which block others and which can run in parallel; also checks for unannotated implementations and auto-completes tasks
4
+ category: researching
5
+ model: claude-sonnet-4-6
6
+ argument-hint: [--json]
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `.docs/guides/mcp-tools.md` + `wiki/work/tasks/lifecycle.md`.
11
+
12
+ # Task Audit
13
+
14
+ Analyse all active tasks: verify implementation completeness, auto-check unannotated finished steps, move fully-completed tasks, parse dependency blocks, build a directed dependency graph, and surface which tasks block others and which can be safely parallelised.
15
+
16
+ ---
17
+
18
+ **Flags**: $ARGUMENTS
19
+
20
+ - `--json` — also emit a raw JSON adjacency list (useful for scripting)
21
+
22
+ ---
23
+
24
+ ## Step 1: Load the Task Index
25
+
26
+ Read `wiki/work/tasks/index.md` using the `Read` tool.
27
+
28
+ - Parse every active-item bullet line — format `- [TASK-NNN — Title](TASK-NNN-slug.md) — one-line summary · status`. Extract the `TASK-NNN` ID and the linked file path (e.g. `wiki/work/tasks/TASK-001-project-registry-push.md`) for each.
29
+ - `index.md` lists active items only and carries no progress or flags columns — those are computed from each task file in Step 2.
30
+ - If the list is empty, report "No active tasks — nothing to audit." and STOP.
31
+
32
+ Do **not** scan the directory directly. The index is authoritative for active tasks.
33
+
34
+ ---
35
+
36
+ ## Step 2: Read Each Task File — Check Completeness and Parse Dependencies
37
+
38
+ For each task file path collected in Step 1, **read the file once** using the `Read` tool (or Serena's `find_symbol`/`get_symbols_overview` for structured markdown traversal). Do all of 2a–2e in a single pass per file to avoid re-reading.
39
+
40
+ ### 2a. Extract All Steps
41
+
42
+ Scan every checklist item in the file — lines matching `- [ ] …` (incomplete) or `- [x] …` / `- [X] …` (complete). Record:
43
+
44
+ - `unchecked`: list of step descriptions without a checkmark
45
+ - `checked`: list of step descriptions already checked
46
+ - `total`: count of all steps
47
+
48
+ ### 2b. Verify Unannotated Implementations
49
+
50
+ For each unchecked step, determine whether the work it describes is **actually implemented** in the codebase:
51
+
52
+ 1. Extract the key noun/verb from the step description (e.g. "Add `foo()` helper", "Write migration for `users` table").
53
+ 2. Use Serena's `find_symbol` or `search_for_pattern` to look for the relevant symbol, file, or pattern.
54
+ 3. If evidence of a complete implementation is found (the symbol exists, the file is present, the migration exists, etc.), mark the step as **auto-completable**.
55
+
56
+ Be conservative: only mark a step auto-completable when the evidence is unambiguous. When the step is vague or the search returns nothing definitive, leave it unchecked and note it as **unverified**.
57
+
58
+ ### 2c. Apply Checkmarks
59
+
60
+ For every step confirmed as auto-completable in 2b, update the task file using `Edit` (or Serena's `replace_content`): change `- [ ]` → `- [x]` for that line.
61
+
62
+ After applying all updates, recount `checked` and `total`. Track which tasks had checkmarks added (include them in the Step 4 report as **auto-completed steps**).
63
+
64
+ ### 2d. Move Fully-Completed Tasks
65
+
66
+ If `checked == total` (all steps are now checked) after 2c:
67
+
68
+ 1. Set `status: done` in the task file's frontmatter using `Edit`, then move it from `wiki/work/tasks/` to `wiki/work/tasks/archive/` using `Bash` (`git mv` only).
69
+ 2. Delete its line from `wiki/work/tasks/index.md` and append it to `wiki/work/tasks/archive/index.md`.
70
+ 3. Scan all other active task files for references to this task's ID (e.g. in their dependency blocks). For each reference found, note it in the Step 4 report as a **now-resolved dependency** — do not auto-edit those files, but suggest `/task-update <NNN>` to clean them up.
71
+ 4. Mark the task as `completed: true` in its node record so Step 3 treats it as resolved.
72
+
73
+ ### 2e. Parse the Dependency Block
74
+
75
+ In the same file read, locate the dependency blockquote appearing **immediately after the `# NNN —` title line** and **before `## Objective`**:
76
+
77
+ ```markdown
78
+ > **Depends on**: [002-foo](002-foo.md), [003-bar](003-bar.md)
79
+ > **Blocks**: [008-baz](008-baz.md)
80
+ > **Parallel-safe with**: [005-qux](005-qux.md), [006-quux](006-quux.md)
81
+ ```
82
+
83
+ - Values may be `none` if the field is empty.
84
+ - Links follow the pattern `[NNN-slug](NNN-slug.md)` — extract the NNN-slug identifier from each link.
85
+ - A task with no dependency block at all is treated as having `Depends on: none`, `Blocks: none`, `Parallel-safe with: none`.
86
+
87
+ ### 2f. Build the Node Record
88
+
89
+ For each task (skipping any moved to completed in 2d), produce a record:
90
+
91
+ ```
92
+ {
93
+ id: "NNN-slug",
94
+ num: NNN,
95
+ depends_on: ["NNN-slug", ...], # tasks that must complete before this one
96
+ blocks: ["NNN-slug", ...], # tasks this one must complete before they can start
97
+ parallel_safe: ["NNN-slug", ...], # tasks explicitly marked safe to run alongside
98
+ progress: "X/Y", # updated count after auto-checkmarks
99
+ flags: "[WIP]" | "—" | etc,
100
+ missing_block: true/false, # true if the dependency block was absent entirely
101
+ auto_checked: ["step description", ...], # steps that were auto-completed in 2c
102
+ unverified: ["step description", ...] # unchecked steps whose implementation could not be confirmed
103
+ }
104
+ ```
105
+
106
+ Note tasks missing the dependency block — list them in the Step 4 issues report so the user knows to run `/task-update` on them.
107
+
108
+ ---
109
+
110
+ ## Step 3: Derive the Full Dependency Graph
111
+
112
+ ### 3a. Validate edges
113
+
114
+ For every `depends_on` and `blocks` edge, confirm the referenced task ID appears in the active index. If a reference points to a task not in the active index (e.g. it completed or was trashed), mark it as a **stale reference** and note it in the report — do not abort.
115
+
116
+ Cross-check symmetry: if task A says it blocks task B, but task B does not list A in its `depends_on`, flag the asymmetry (don't auto-correct).
117
+
118
+ ### 3b. Detect cycles
119
+
120
+ Walk the dependency graph using DFS. If a cycle is found (A → B → A), flag it as a **blocking cycle** — these tasks cannot proceed until the cycle is resolved. List every cycle found.
121
+
122
+ ### 3c. Compute parallelism groups
123
+
124
+ A set of tasks is **parallelisable** if no task in the set has a directed dependency on any other task in the set (directly or transitively). Use topological sort to group tasks into execution waves:
125
+
126
+ - **Wave 1**: tasks with no unresolved `depends_on` (all prerequisites already completed or none listed)
127
+ - **Wave 2**: tasks whose only blockers are Wave 1 tasks
128
+ - **Wave N**: and so on
129
+
130
+ Within a wave, all tasks are parallelisable with each other unless an explicit `parallel_safe` field contradicts it (i.e. two tasks in the same wave where neither lists the other in `parallel_safe` — treat that as unknown/untested rather than unsafe unless a flag says otherwise).
131
+
132
+ ---
133
+
134
+ ## Step 4: Output the Audit Report
135
+
136
+ Print the full report in this order:
137
+
138
+ ### 4a. Dependency Graph (Mermaid — also persisted to `wiki/work/tasks/dependency-graph.md` in Step 5)
139
+
140
+ ```
141
+ ## Dependency Graph
142
+
143
+ \`\`\`mermaid
144
+ graph TD
145
+ 001["001-project-registry-push<br/>0/18"]
146
+ 007["007-publish-npm-package<br/>0/43 [DEFERRED-TO-UAT]"]
147
+ 001 --> 007
148
+ 005["005-command-anti-patterns<br/>26/29 [DEFERRED-TO-UAT]"]
149
+ 006["006-migrate-commands-to-skills<br/>55/55"]
150
+ 009["009-audit-skills-vs-sdlc<br/>0/10"]
151
+ \`\`\`
152
+ ```
153
+
154
+ - Node label: `NNN-slug\nProgress [Flags]` — use `<br/>` for line breaks inside Mermaid labels.
155
+ - Solid arrow `-->` for `depends_on` / `blocks` edges (direction: prerequisite → dependent).
156
+ - Dashed arrow `-.->` for `parallel_safe` edges (bidirectional, draw once).
157
+ - Tasks with `[BLOCKED]` or `[FAILED]` flags use a distinct node shape: `001[["001-slug"]]` (double bracket = stadium shape).
158
+
159
+ ### 4b. Execution Waves Table
160
+
161
+ ```
162
+ ## Execution Waves (Parallelism)
163
+
164
+ | Wave | Tasks | Can run in parallel |
165
+ |------|-------|---------------------|
166
+ | 1 | 001-project-registry-push, 005-command-anti-patterns | Yes — no shared dependencies |
167
+ | 2 | 007-publish-npm-package | Waits for Wave 1 |
168
+ ```
169
+
170
+ For each wave, note any tasks within it that have an **unknown parallel-safety** (no `parallel_safe` entries exist between them) with a ⚠️ marker.
171
+
172
+ ### 4c. Blocking Summary
173
+
174
+ ```
175
+ ## Blocking Chains
176
+
177
+ - 001 → 007 (001 must complete before 007 can start)
178
+ ```
179
+
180
+ If no blocking chains exist: "No blocking dependencies found — all tasks are independent."
181
+
182
+ ### 4d. Completion Findings
183
+
184
+ Report what Step 2 discovered and changed:
185
+
186
+ ```
187
+ ## Completion Findings
188
+
189
+ ### Auto-Completed Steps
190
+ | Task | Step | Evidence |
191
+ |------|------|----------|
192
+ | 005-command-anti-patterns | "Add mcp-tools.md guide" | File found at .docs/guides/mcp-tools.md |
193
+
194
+ ### Fully-Completed Tasks Moved
195
+ | Task | Action |
196
+ |------|--------|
197
+ | 005-command-anti-patterns | Moved to wiki/work/tasks/archive/ — update references: /task-update 007 |
198
+
199
+ ### Unverified Steps (implementation unclear)
200
+ | Task | Step |
201
+ |------|------|
202
+ | 009-audit-skills-vs-sdlc | "Configure CI gate for audit output" |
203
+ ```
204
+
205
+ Omit any section whose table would be empty.
206
+
207
+ ### 4e. Issues Found
208
+
209
+ ```
210
+ ## Issues
211
+
212
+ | Task | Issue |
213
+ |------|-------|
214
+ | 006-migrate-commands-to-skills | Missing dependency block — run `/task-update 006` to add one |
215
+ | 009-audit-skills-vs-sdlc | Stale reference: depends_on "003-deleted-task" not in active index |
216
+ ```
217
+
218
+ Categories:
219
+ - **Missing dependency block** — task file has no `> **Depends on**:` block
220
+ - **Stale reference** — referenced task ID not found in active index
221
+ - **Asymmetric edge** — A blocks B but B doesn't list A in depends_on
222
+ - **Cycle** — dependency cycle detected (list all members)
223
+ - **Now-resolved dependency** — a task was moved to completed; other tasks still reference it in their dependency blocks
224
+
225
+ If no issues: "No issues found."
226
+
227
+ ### 4f. Suggested Next Actions
228
+
229
+ Based on the graph, suggest actionable next steps:
230
+
231
+ ```
232
+ ## Suggested Next Steps
233
+
234
+ Wave 1 tasks are unblocked and can start immediately:
235
+ /tackle wiki/work/tasks/001-project-registry-push.md
236
+ /tackle wiki/work/tasks/005-command-anti-patterns.md ← run in parallel
237
+
238
+ Fix missing dependency blocks:
239
+ /task-update 006
240
+ /task-update 009
241
+
242
+ Clean up now-resolved dependency references:
243
+ /task-update 007 (005 was moved to completed)
244
+ ```
245
+
246
+ ---
247
+
248
+ ## Step 5: Persist the Dependency Graph
249
+
250
+ **Always run this step** (regardless of flags).
251
+
252
+ Write the generated graph to its own file, `wiki/work/tasks/dependency-graph.md` — do **not** inline it into `index.md`. `index.md`'s contract is "active items only, as a flat bullet list" (see `wiki/conventions.md`); a large auto-generated Mermaid section would violate that. A dedicated file also lets the graph be regenerated wholesale each run without disturbing the active list.
253
+
254
+ 1. Overwrite `wiki/work/tasks/dependency-graph.md` using `Write` with this content:
255
+
256
+ ```markdown
257
+ ---
258
+ title: Task Dependency Graph
259
+ updated: YYYY-MM-DD
260
+ ---
261
+
262
+ # Task Dependency Graph
263
+
264
+ > Auto-generated by `/task-audit` on YYYY-MM-DD. Re-run to refresh. Do not edit by hand.
265
+
266
+ <paste the Mermaid block from Step 4a>
267
+
268
+ <paste the Execution Waves table from Step 4b>
269
+
270
+ <paste the Blocking Chains section from Step 4c>
271
+ ```
272
+
273
+ 2. Ensure `wiki/work/tasks/index.md` carries a one-line cross-link to the graph, directly under its `Entry format:` line: `Dependency graph: [dependency-graph.md](dependency-graph.md) — regenerated by /task-audit.` If that line is already present, leave it; if absent, add it with a single `Edit`.
274
+
275
+ There must be **exactly one** `dependency-graph.md` file after this step, and it holds the only copy of the graph. Never write the graph into `index.md` or a `README.md`.
276
+
277
+ **Only if `--json` flag is present in `$ARGUMENTS`:**
278
+
279
+ Print the raw adjacency list as a fenced JSON block:
280
+
281
+ ```json
282
+ {
283
+ "tasks": [
284
+ {
285
+ "id": "001-project-registry-push",
286
+ "depends_on": [],
287
+ "blocks": ["007-publish-npm-package"],
288
+ "parallel_safe": ["005-command-anti-patterns"],
289
+ "progress": "0/18",
290
+ "flags": "—"
291
+ }
292
+ ]
293
+ }
294
+ ```