feat(knowledge): Phase 5 — skill integration

CLAUDE.md

@@ -543,7 +543,7 @@ Never use `Stop here.`, `Command ends.`, `Wait for user to acknowledge before en
 
 - **H1** (`#`): File title only — one per file, at the top
 - **H2** (`##`): Steps and major sections (`## Step N: {Name}`, `## Notes`, `## Instructions`)
-- **H3** (`###`): Subsections within steps (`### 6a: Warn about in-progress specs`)
+- **H3** (`###`): Sub-steps within early setup steps only (`### Step 0.1: Casing Conventions`)
 - **H4** (`####`): Conditional routing only (`#### If {condition}`, `#### Otherwise`)
 
 ### Step Numbering
@@ -555,6 +555,42 @@ Sequential: `## Step 0`, `## Step 1`, `## Step 2`, etc.
 - Each step completes fully before the next begins
 - User-facing step markers (see Display & Output Conventions → Step Markers) use names only — no numbers. They are embedded at each step boundary, including steps with no explicit output (Claude's visible processing labels the activity for the user)
 
+### Sub-Steps (Early Setup Steps Only)
+
+Early setup steps — Step 0 in particular — bundle multiple discrete pre-disclosure actions that all run unconditionally: loading shared conventions, running migrations, gating on prerequisites. These actions must execute inline (they are not progressive-disclosure work), but each needs its own routing target so conditional branches inside one action can route to the next action by name without duplicating shared content downstream.
+
+Decompose these steps into **sub-steps** using H3 decimal numbering:
+
+```
+## Step 0: Initialisation
+
+### Step 0.1: Casing Conventions
+Load **[casing-conventions.md](...)** and follow its instructions as written.
+→ Proceed to **Step 0.2**.
+
+### Step 0.2: Migrations
+
+#### If the `/workflow-migrate` skill has already been invoked in this conversation
+→ Proceed to **Step 0.3**.
+
+#### Otherwise
+[run migrations + CRITICAL note]
+→ Proceed to **Step 0.3**.
+
+### Step 0.3: Knowledge Check
+Load **[knowledge-check.md](...)** and follow its instructions as written.
+→ Proceed to **Step 1**.
+```
+
+Rules:
+
+- Heading format: `### Step {parent}.{sub}: {Name}` (e.g., `### Step 0.1: Casing Conventions`)
+- Sub-steps are **unconditional, sequential** units — they always run when the parent step runs. Use H4 `#### If` *inside* a sub-step for branching; the branches route to the next sub-step by name
+- Each sub-step is a valid routing target: `→ Proceed to **Step 0.3**`
+- The final sub-step routes to the parent's next top-level step: `→ Proceed to **Step 1**`
+- **Sub-steps are reserved for early setup steps** (typically Step 0) where content must run inline before progressive disclosure begins — migrations must complete before anything else, knowledge check gates the entire pipeline
+- **Later steps must use reference files and progressive disclosure instead.** `Load **[reference.md](...)**` is the mechanism for decomposing later-step content, not sub-steps
+
 ### Conditional Routing
 
 Use H4 headings for if/else branches within a step:

knowledge-base/deferred-issues.md

@@ -115,6 +115,17 @@ Each entry records: where, what, why it was deferred, and a mitigation idea. Cir
 
 ---
 
+## Phase 5 (Skill Integration) — Deferred
+
+### 18. Knowledge removal has no automatic retry on failure — Medium
+
+**Location:** `skills/workflow-start/references/manage-work-unit.md` (cancellation), `skills/workflow-specification-process/references/spec-completion.md` (supersession), `skills/workflow-specification-process/references/promote-to-cross-cutting.md` (promotion).
+**Description:** When `knowledge remove` fails (store locked, CLI error), the skill displays a warning and tells the user to retry manually. Unlike indexing failures — which have a pending queue for automatic catch-up on the next `index` call — removal failures have no retry mechanism. Stale chunks from cancelled/superseded/promoted work persist in the knowledge base until the user manually runs `knowledge remove`.
+**Why deferred:** Removal failures are rare (store lock is the main scenario), and stale chunks cause noise but not corruption. The pending queue design (Phase 4) was scoped to indexing only.
+**Mitigation:** Add a pending-removal queue analogous to the pending-index queue. On each `knowledge remove` or `knowledge compact` invocation, process queued removals first.
+
+---
+
 ## How to use this file
 
 - Add new entries as you review code across any phase.

skills/continue-bugfix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: continue-bugfix
-allowed-tools: Bash(node .claude/skills/continue-bugfix/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs)
+allowed-tools: Bash(node .claude/skills/continue-bugfix/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs)
 ---
 
 Continue an in-progress bugfix. Determines current phase and routes to the appropriate phase skill.
@@ -36,11 +36,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them.
 ── Initialisation ───────────────────────────────
 ```
 
+### Step 0.1: Casing Conventions
+
 Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written.
 
+→ Proceed to **Step 0.2**.
+
+### Step 0.2: Migrations
+
 #### If the `/workflow-migrate` skill has already been invoked in this conversation
 
-→ Proceed to **Step 1**.
+→ Proceed to **Step 0.3**.
 
 #### Otherwise
 
@@ -54,7 +60,13 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.
 
 Invoke the `/workflow-migrate` skill and follow its instructions exactly — if it issues a STOP gate, you must stop.
 
-**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to Step 1 below. Do not stop after migration completes.
+**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to **Step 0.3**. Do not stop after migration completes.
+
+→ Proceed to **Step 0.3**.
+
+### Step 0.3: Knowledge Check
+
+Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written.
 
 → Proceed to **Step 1**.
 

skills/continue-cross-cutting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: continue-cross-cutting
-allowed-tools: Bash(node .claude/skills/continue-cross-cutting/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs)
+allowed-tools: Bash(node .claude/skills/continue-cross-cutting/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs)
 ---
 
 Continue an in-progress cross-cutting concern. Determines current phase and routes to the appropriate phase skill.
@@ -36,11 +36,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them.
 ── Initialisation ───────────────────────────────
 ```
 
+### Step 0.1: Casing Conventions
+
 Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written.
 
+→ Proceed to **Step 0.2**.
+
+### Step 0.2: Migrations
+
 #### If the `/workflow-migrate` skill has already been invoked in this conversation
 
-→ Proceed to **Step 1**.
+→ Proceed to **Step 0.3**.
 
 #### Otherwise
 
@@ -54,7 +60,13 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.
 
 Invoke the `/workflow-migrate` skill and follow its instructions exactly — if it issues a STOP gate, you must stop.
 
-**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to Step 1 below. Do not stop after migration completes.
+**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to **Step 0.3**. Do not stop after migration completes.
+
+→ Proceed to **Step 0.3**.
+
+### Step 0.3: Knowledge Check
+
+Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written.
 
 → Proceed to **Step 1**.
 

skills/continue-epic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: continue-epic
-allowed-tools: Bash(node .claude/skills/continue-epic/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs)
+allowed-tools: Bash(node .claude/skills/continue-epic/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs)
 ---
 
 Continue an in-progress epic. Shows full phase-by-phase state and routes to the appropriate phase skill.
@@ -36,11 +36,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them.
 ── Initialisation ───────────────────────────────
 ```
 
+### Step 0.1: Casing Conventions
+
 Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written.
 
+→ Proceed to **Step 0.2**.
+
+### Step 0.2: Migrations
+
 #### If the `/workflow-migrate` skill has already been invoked in this conversation
 
-→ Proceed to **Step 1**.
+→ Proceed to **Step 0.3**.
 
 #### Otherwise
 
@@ -54,7 +60,13 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.
 
 Invoke the `/workflow-migrate` skill and follow its instructions exactly — if it issues a STOP gate, you must stop.
 
-**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to Step 1 below. Do not stop after migration completes.
+**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to **Step 0.3**. Do not stop after migration completes.
+
+→ Proceed to **Step 0.3**.
+
+### Step 0.3: Knowledge Check
+
+Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written.
 
 → Proceed to **Step 1**.
 

skills/continue-epic/references/epic-display-and-menu.md

@@ -586,6 +586,22 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.{phas
 node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.{phase}.{topic} status cancelled
 ```
 
+Remove the cancelled topic's chunks from the knowledge base:
+
+```bash
+node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase {phase} --topic {topic}
+```
+
+If the remove command fails, display the error but do not block — the cancellation is already recorded:
+
+> *Output the next fenced block as a code block:*
+
+```
+⚑ Knowledge removal warning
+  {error details}
+  The topic is cancelled. You can run knowledge remove manually later.
+```
+
 Commit the change.
 
 > *Output the next fenced block as a code block:*
@@ -657,6 +673,28 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.{phas
 node .claude/skills/workflow-manifest/scripts/manifest.cjs delete {work_unit}.{phase}.{topic} previous_status
 ```
 
+**If `previous_status` is `completed` and `phase` is one of the indexed phases (research / discussion / investigation / specification):**
+
+Re-index the reactivated topic's artifact into the knowledge base. Resolve the artifact path by phase:
+- research: `.workflows/{work_unit}/research/{topic}.md`
+- discussion: `.workflows/{work_unit}/discussion/{topic}.md`
+- investigation: `.workflows/{work_unit}/investigation/{topic}.md`
+- specification: `.workflows/{work_unit}/specification/{topic}/specification.md`
+
+```bash
+node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index {artifact_path}
+```
+
+If the index command fails, display the error but do not block — the reactivation is already recorded:
+
+> *Output the next fenced block as a code block:*
+
+```
+⚑ Knowledge indexing warning
+  {error details}
+  The artifact is saved. Indexing can be retried later.
+```
+
 Commit the change.
 
 > *Output the next fenced block as a code block:*

skills/continue-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: continue-feature
-allowed-tools: Bash(node .claude/skills/continue-feature/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs)
+allowed-tools: Bash(node .claude/skills/continue-feature/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs)
 ---
 
 Continue an in-progress feature. Determines current phase and routes to the appropriate phase skill.
@@ -36,11 +36,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them.
 ── Initialisation ───────────────────────────────
 ```
 
+### Step 0.1: Casing Conventions
+
 Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written.
 
+→ Proceed to **Step 0.2**.
+
+### Step 0.2: Migrations
+
 #### If the `/workflow-migrate` skill has already been invoked in this conversation
 
-→ Proceed to **Step 1**.
+→ Proceed to **Step 0.3**.
 
 #### Otherwise
 
@@ -54,7 +60,13 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.
 
 Invoke the `/workflow-migrate` skill and follow its instructions exactly — if it issues a STOP gate, you must stop.
 
-**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to Step 1 below. Do not stop after migration completes.
+**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to **Step 0.3**. Do not stop after migration completes.
+
+→ Proceed to **Step 0.3**.
+
+### Step 0.3: Knowledge Check
+
+Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written.
 
 → Proceed to **Step 1**.
 

skills/continue-quickfix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: continue-quickfix
-allowed-tools: Bash(node .claude/skills/continue-quickfix/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs)
+allowed-tools: Bash(node .claude/skills/continue-quickfix/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs)
 ---
 
 Continue an in-progress quick-fix. Determines current phase and routes to the appropriate phase skill.
@@ -36,11 +36,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them.
 ── Initialisation ───────────────────────────────
 ```
 
+### Step 0.1: Casing Conventions
+
 Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written.
 
+→ Proceed to **Step 0.2**.
+
+### Step 0.2: Migrations
+
 #### If the `/workflow-migrate` skill has already been invoked in this conversation
 
-→ Proceed to **Step 1**.
+→ Proceed to **Step 0.3**.
 
 #### Otherwise
 
@@ -54,7 +60,13 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.
 
 Invoke the `/workflow-migrate` skill and follow its instructions exactly — if it issues a STOP gate, you must stop.
 
-**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to Step 1 below. Do not stop after migration completes.
+**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to **Step 0.3**. Do not stop after migration completes.
+
+→ Proceed to **Step 0.3**.
+
+### Step 0.3: Knowledge Check
+
+Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written.
 
 → Proceed to **Step 1**.
 

skills/start-bugfix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: start-bugfix
-allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(ls .workflows/), Bash(mkdir -p .workflows/.inbox/.archived/), Bash(mv .workflows/.inbox/)
+allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs), Bash(ls .workflows/), Bash(mkdir -p .workflows/.inbox/.archived/), Bash(mv .workflows/.inbox/)
 ---
 
 Start a new bugfix. Gather a brief description, create the work unit, and route to investigation.
@@ -27,27 +27,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them.
 ── Initialisation ───────────────────────────────
 ```
 
+### Step 0.1: Casing Conventions
+
 Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written.
 
-#### If the `/workflow-migrate` skill has already been invoked in this conversation
+→ Proceed to **Step 0.2**.
 
-> *Output the next fenced block as a code block:*
+### Step 0.2: Migrations
 
-```
-●───────────────────────────────────────────────●
-  New Bugfix
-●───────────────────────────────────────────────●
-
-```
-
-> *Output the next fenced block as markdown (not a code block):*
-
-```
-> Starting a new bugfix. I'll ask what's broken, suggest a name,
-> then hand off to investigation to diagnose the root cause.
-```
+#### If the `/workflow-migrate` skill has already been invoked in this conversation
 
-→ Proceed to **Step 1**.
+→ Proceed to **Step 0.3**.
 
 #### Otherwise
 
@@ -61,7 +51,11 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.
 
 Invoke the `/workflow-migrate` skill and follow its instructions exactly — if it issues a STOP gate, you must stop.
 
-**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to the next instruction below. Do not stop after migration completes.
+**CRITICAL**: When the migrate skill returns (either after committing changes or reporting no changes needed), you MUST continue to **Step 0.3**. Do not stop after migration completes.
+
+→ Proceed to **Step 0.3**.
+
+### Step 0.3: Intro and Knowledge Check
 
 > *Output the next fenced block as a code block:*
 
@@ -79,6 +73,8 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if
 > then hand off to investigation to diagnose the root cause.
 ```
 
+Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written.
+
 → Proceed to **Step 1**.
 
 ---