From b31bd97e78f21a0183347df4b29b44d5838efe27 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Thu, 16 Apr 2026 21:14:14 +0100 Subject: [PATCH 01/15] feat(knowledge): add knowledge check + compact to entry-point Step 0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create shared reference knowledge-check.md that gates all workflow entry points on knowledge base readiness (check → hard stop or compact → proceed). Load it in Step 0 of all 11 entry-point skills after migrations. Add allowed-tools for knowledge.cjs. Co-Authored-By: Claude Opus 4.6 (1M context) --- .tick/tasks.jsonl | 4 +- skills/continue-bugfix/SKILL.md | 8 +- skills/continue-cross-cutting/SKILL.md | 8 +- skills/continue-epic/SKILL.md | 8 +- skills/continue-feature/SKILL.md | 8 +- skills/continue-quickfix/SKILL.md | 8 +- skills/start-bugfix/SKILL.md | 6 +- skills/start-cross-cutting/SKILL.md | 6 +- skills/start-epic/SKILL.md | 6 +- skills/start-feature/SKILL.md | 6 +- skills/start-quickfix/SKILL.md | 6 +- .../references/knowledge-check.md | 100 ++++++++++++++++++ skills/workflow-start/SKILL.md | 6 +- 13 files changed, 161 insertions(+), 19 deletions(-) create mode 100644 skills/workflow-shared/references/knowledge-check.md diff --git a/.tick/tasks.jsonl b/.tick/tasks.jsonl index ddaa20a76..8a1a27dfd 100644 --- a/.tick/tasks.jsonl +++ b/.tick/tasks.jsonl @@ -21,8 +21,8 @@ {"id":"tick-8913b7","title":"Bulk Index + Retry/Pending Queue","status":"done","priority":2,"type":"task","refs":["knowledge-base-4-4"],"description":"Problem: The knowledge base needs two operational features that work together. First, a bulk indexing mode that discovers all completed artifacts and indexes any that are missing — used by knowledge setup and for manual catch-up. Second, a retry mechanism with a pending queue so that transient failures (API timeouts, rate limits, network errors) do not permanently lose files — the system self-heals on the next successful operation.\n\nSolution: Implement the no-args form of knowledge index (bulk discovery + indexing) and a single-layer retry/pending queue mechanism that wraps both single-file indexing AND query operations.\n\nOutcome: Running knowledge index with no arguments discovers and indexes all missing completed artifacts. Failures are retried with backoff, and persistently failing files are queued for catch-up on the next successful invocation. Query failures also retry before surfacing errors.\n\nDo:\n\nBULK INDEX (extend the index command from Task 3-3):\n- Invocation: knowledge index (no arguments — the presence/absence of a file argument determines single vs bulk mode)\n- Discovery algorithm (from design doc lines 479-484):\n 1. Get all work units via the manifest CLI: list all work unit names from the project manifest.\n 2. For each work unit, get completed items across indexed phases (research, discussion, investigation, specification) via manifest CLI get commands.\n 3. For each completed item, resolve the file path via manifest resolve (Task 3-2).\n 4. Check which items are already in the store — query for chunks matching each work_unit + phase + topic combination. If chunks exist, the item is already indexed.\n 5. Index the missing ones using the single-file index logic from Task 3-3.\n- Output progress as files are indexed: Indexing {file}... {N} chunks\n- Final summary: Indexed {total_new} files ({total_chunks} chunks). {skipped} already indexed.\n- Acquire file lock for the entire bulk operation (not per-file — avoids repeated lock/unlock overhead).\n\nRETRY MECHANISM (single layer — all retry lives here):\n- Implement a general-purpose retry wrapper: withRetry(fn, { maxAttempts: 3, backoff: [1000, 2000, 4000] }) -\u003e result or throw.\n- This wraps any async operation — not specific to indexing. It is used for:\n 1. Single-file index operations (update Task 3-3 to use it)\n 2. Bulk index per-file operations\n 3. Query embed operations (update Task 3-4 query command to wrap the provider.embed call)\n- The design doc specifies retry on BOTH indexing and query failures (lines 756-776). The retry wrapper is general enough for both.\n- THIS IS THE ONLY RETRY LAYER. Task 4-1's OpenAI provider does NOT retry internally — it throws on any failure (including 429 rate limits). All retry/backoff logic lives in this wrapper. This avoids retry compounding (the previous two-layer design could have produced 3 × 3 = 9 API calls for a rate-limited request).\n- The wrapper handles all transient failures uniformly: 429 (rate limit), network errors, timeouts, etc. The backoff [1s, 2s, 4s] is appropriate for rate limit recovery and transient network issues.\n- For query failures specifically (design doc lines 769-776): after 3 retries exhausted, the CLI should exit with a non-zero code and a clear error message. The skill instructions (Phase 6) handle pausing the workflow and offering the user the choice to proceed without context. The CLI just retries and then fails clearly.\n\nPENDING QUEUE:\n- Location: the pending array in .workflows/.knowledge/metadata.json (schema established in Task 1-4, initialised on first index per Task 3-3).\n- When all 3 retries are exhausted for an INDEX operation:\n - Log it to the pending queue: { file: \u003cpath\u003e, failed_at: \u003cISO timestamp\u003e, error: \u003cerror message\u003e }\n - Output a clear message: Failed to index {file} after 3 attempts: {error}. Added to pending queue.\n - Do NOT stop the bulk index — continue with remaining files.\n- The phase itself is not blocked — the artifact file is saved, just not indexed yet.\n- Query failures do NOT go to the pending queue — they are transient operations, not files to be tracked.\n\nCATCH-UP MECHANISM:\n- After a successful single-file index (knowledge index \u003cfile\u003e), process up to 5 items from the pending queue.\n- Each pending item gets its own fresh 3-retry budget (independent of previous failures).\n- Items that fail again stay in the queue for the next cycle.\n- Items that succeed are removed from the queue.\n- This provides gradual self-healing through normal workflow use without bursty API calls after long outages.\n- knowledge index (no args — bulk mode) processes the entire pending queue alongside missing files (no 5-item limit in bulk mode).\n\nAcceptance Criteria:\n- knowledge index (no args) discovers all completed artifacts across all work units\n- Already-indexed artifacts are skipped\n- Missing artifacts are indexed\n- Progress output shows each file being indexed\n- Summary output shows totals (new, skipped)\n- Retry: transient failure on first attempt succeeds on retry (for both index and query)\n- Retry: rate limit (429) from OpenAI is retried by this wrapper (provider does not retry)\n- Retry: 3 failures on index logs file to pending queue with error message\n- Retry: 3 failures on query exits with non-zero code and clear error (no pending queue entry)\n- Pending queue: failed file appears in metadata.json pending array\n- Catch-up: next successful single-file index processes up to 5 pending items\n- Catch-up: successfully caught-up items are removed from pending queue\n- Catch-up: items that fail again remain in pending queue\n- Bulk mode processes entire pending queue (no 5-item limit)\n- Single-file index from Phase 3 (Task 3-3) now uses the retry wrapper\n- Query command from Phase 3 (Task 3-4) now uses the retry wrapper for embed calls\n- No compounding retry behaviour — exactly 3 retry attempts total per operation, not 3 × 3 = 9\n\nTests:\n- Test file: tests/scripts/test-knowledge-cli.sh (extend CLI shell tests)\n- Bulk index tests:\n - it discovers and indexes all missing completed artifacts\n - it skips already-indexed artifacts\n - it reports progress and summary\n- Retry tests (may need a mock or controlled failure mechanism):\n - it retries on transient failure and succeeds\n - it retries on 429 rate limit (provider throws, wrapper catches and retries)\n - it logs to pending queue after 3 index failures\n - it exits with error after 3 query failures (no pending queue entry)\n- Catch-up tests:\n - it processes pending items after a successful single-file index\n - it removes successfully caught-up items from pending queue\n - it leaves still-failing items in pending queue\n- Test file: tests/scripts/test-knowledge-retry.cjs (Node test for retry logic unit tests)\n - it retries up to 3 times with backoff\n - it succeeds on second attempt if first fails\n - it throws after 3 failures\n - it records correct backoff delays\n - it does not compound retry attempts (exactly 3 max per operation)\n\nEdge Cases:\n- Bulk index on a project with no completed work units — 0 files to index, clean exit\n- Bulk index on a project with no .workflows/ directory — error (knowledge check should have caught this, but handle gracefully)\n- Pending queue has items from a previous provider that no longer matches config — provider mismatch detection (from Task 3-3) will refuse these. They stay in the queue until the user runs knowledge rebuild.\n- Pending queue grows very large (many failures over time) — catch-up processes 5 at a time in single-file mode, preventing bursty API usage. Bulk mode clears the entire backlog.\n- Catch-up item file no longer exists (deleted since failure) — remove from pending queue with a warning, do not error.\n- Concurrent bulk index — file lock prevents corruption. Second invocation waits or times out.\n- Persistent rate limiting — after 3 backoff attempts (1s + 2s + 4s = 7s total), the operation fails. For indexing, it goes to the pending queue for catch-up. For query, it exits with a clear error. No further API calls until the user acts.\n\nSpec Reference: knowledge-base/design.md — knowledge index no-args description (lines 639-642), Discovery algorithm (lines 479-484), Error Handling section (lines 756-795, BOTH indexing AND query failure handling, retry mechanism, pending queue, catch-up), Catch-Up Mechanism section (pending queue schema in metadata.json, 5-item limit per single-file invocation)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-12T13:19:53Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-12T13:48:37Z","auto":false}],"parent":"tick-c52ba5","created":"2026-04-08T18:04:23Z","updated":"2026-04-12T13:48:37Z","closed":"2026-04-12T13:48:37Z"} {"id":"tick-d16e06","title":"Compact Command","status":"done","priority":2,"type":"task","refs":["knowledge-base-4-5"],"description":"Problem: The knowledge base grows over the project lifetime. Old research, discussions, and investigations become less valuable as their decisions move into specs and code. Without compaction, the index grows without bound, increasing load times and memory usage. Compaction implements the memory decay model from the design doc — removing expired non-spec chunks while preserving specs forever.\n\nSolution: Implement the knowledge compact command that applies the decay TTL to remove expired chunks from completed work units.\n\nOutcome: A compact command that keeps the active index lean by removing stale non-spec chunks, with a dry-run mode for previewing what would be removed.\n\nDo:\n- Implement the compact command handler in the CLI (invoked by Task 3-1 dispatch).\n- Invocation: knowledge compact [--dry-run]\n\nDECAY RULES (from design doc lines 833-840):\n- In-progress work units: ALL chunks kept regardless of age. No completed_at date means nothing can expire.\n- Completed work units: specification chunks kept FOREVER (never compacted). Research, discussion, and investigation chunks removed when completed_at + decay_months \u003c= now (inclusive).\n- Cancelled work units: should already be removed by the remove command during cancellation (Phase 5). But if any remain, compact should not touch them — cancellation removal is a separate lifecycle action.\n- decay_months comes from the merged config (Task 3-1). Default is 6. Set to false to disable compaction entirely (keep everything). Set to 0 for immediate expiry of non-spec chunks.\n\nMANIFEST ACCESS PATTERN:\n- The compact command reads work unit status and completed_at from the manifest. It MUST use the manifest CLI (manifest.cjs) for this — do NOT read .workflows/{work_unit}/manifest.json directly.\n- Rationale: the manifest CLI is the single source of truth for manifest state (per CLAUDE.md). Direct file reads would duplicate path conventions and bypass validation. The manifest CLI precedent is established in Task 3-2 (resolve command used by Task 4-4 bulk index) and Task 5-2 (manifest.cjs set for completed_at writes).\n- Specifically: shell out to the manifest CLI using get commands of the form: node .claude/skills/workflow-manifest/scripts/manifest.cjs get WORK_UNIT status, and similarly for completed_at. Collect both values in one manifest read where possible, or cache per-work_unit to avoid repeated shells.\n- Shelling out has a small cost per work unit; with compacted scale (500-2K chunks, 10-50 work units), this is negligible.\n\nALGORITHM:\n1. Load the store from disk.\n2. Read decay_months from config. If false, output Compaction disabled and exit.\n3. Calculate the cutoff date: now minus decay_months.\n4. For each unique work_unit in the store:\n a. Shell out to manifest.cjs to get the work unit status and completed_at fields.\n b. If status is not completed, skip (in-progress work units are exempt).\n c. If completed_at is absent, skip (cannot calculate expiry — the migration from Task 4-2 should have set this, but be defensive).\n d. If completed_at is after the cutoff date, skip (not yet expired).\n e. If expired: find all chunks for this work unit where phase is NOT specification. These are the candidates for removal. Track which phases contributed chunks for each work unit (needed for the output summary).\n5. If --dry-run: output what would be removed without removing. Exit.\n6. Otherwise: remove the candidate chunks. Save the store. Update metadata.json.\n\nOUTPUT (from design doc lines 863-869):\n- When chunks are removed:\n Compacted: removed N chunks from M work units (completed \u003e decay_months months ago)\n - work_unit: n chunks (research, discussion)\n - work_unit: n chunks (investigation)\n- The phase list in parentheses is the unique set of phases that had chunks removed for that work unit (accumulated during step 4e).\n- When nothing expires: no output (silent skip).\n- Dry-run: same format but prefixed with [dry-run] and no actual removal.\n\n- Acquire file lock during write (not during dry-run — dry-run is read-only).\n- Rebuild after implementation: npm run build.\n\nAcceptance Criteria:\n- Compact uses manifest.cjs (not direct manifest.json reads) to look up status and completed_at\n- Compact removes non-spec chunks from work units completed more than decay_months ago\n- Spec chunks are NEVER removed regardless of age\n- In-progress work unit chunks are never removed\n- Chunks from work units completed within the TTL window are kept\n- --dry-run shows what would be removed without removing\n- decay_months: false disables compaction entirely\n- decay_months: 0 expires all non-spec chunks from completed work units immediately\n- Missing completed_at on a completed work unit is handled gracefully (skip with no error)\n- Output format matches the design doc summary style with phase accumulation per work unit\n- Nothing to compact: silent exit (no output)\n- Store is saved after removal\n- File lock acquired during write, not during dry-run\n\nTests:\n- Test file: tests/scripts/test-knowledge-cli.sh (extend CLI shell tests)\n- Setup: index fixtures across multiple work units with different completion dates. Set some as completed with old completed_at values, others recent, others in-progress. Use manifest.cjs set to populate status and completed_at.\n- it removes expired non-spec chunks from old completed work units\n- it preserves spec chunks from expired work units\n- it preserves all chunks from in-progress work units\n- it preserves all chunks from recently completed work units (within TTL)\n- it shows removal plan in --dry-run without removing\n- it handles decay_months: false (compaction disabled)\n- it handles decay_months: 0 (immediate expiry)\n- it handles missing completed_at gracefully\n- it outputs summary in correct format with phase breakdown\n- it produces no output when nothing to compact\n- it uses manifest.cjs for status/completed_at lookups (can be verified by test setup using manifest.cjs set)\n\nEdge Cases:\n- Work unit completed exactly at the cutoff boundary — inclusive per design doc line 837: completed_at + decay_months \u003c= now means expired.\n- Config has no decay_months field — use default (6).\n- Store has chunks from a work unit that no longer has a manifest (work unit directory deleted manually) — manifest.cjs get will fail; catch the error and skip with no error. The status command (Task 4-6) reports these as orphans.\n- All chunks for a work unit are specs — nothing to remove, work unit not mentioned in summary.\n- Compact runs but store has no chunks at all — silent exit.\n- Multiple work units sharing the same cutoff — each is processed independently.\n\nSpec Reference: knowledge-base/design.md — Memory Decay and Compaction section (lines 808-898, decay model table, compaction rules, output format, configuration), and the compaction trigger description (lines 847-855, Step 0 sequence in skills). Manifest CLI precedent established in Task 3-2 (resolve) and Task 5-2 (set completed_at).","transitions":[{"from":"open","to":"in_progress","at":"2026-04-12T13:48:55Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-12T13:56:13Z","auto":false}],"parent":"tick-c52ba5","created":"2026-04-08T18:04:57Z","updated":"2026-04-12T13:56:13Z","closed":"2026-04-12T13:56:13Z"} {"id":"tick-097bf0","title":"Status + Rebuild + Batch Queries + Phase 4 CLI Tests","status":"done","priority":2,"type":"task","refs":["knowledge-base-4-6"],"description":"Problem: Three remaining CLI features need implementation: status (health reporting for debugging), rebuild (destructive reindex for provider changes), and batch queries (multiple search terms in one invocation). These are all Phase 4 completeness items — the knowledge base is functional without them but they round out the CLI for production use.\n\nSolution: Implement the status, rebuild, and batch query features, plus a comprehensive CLI test suite covering all Phase 4 commands.\n\nOutcome: A complete CLI with all 8 commands implemented, plus tests validating everything works against the built bundle.\n\nDo:\n\nSTATUS COMMAND (from design doc lines 680-688 + review findings 11-13):\n- Invocation: knowledge status (no arguments)\n- Full health report — not used in skill automation, intended for user/debugging.\n- Report sections:\n 1. Index summary: total chunk count, broken down by work unit, phase, and work type.\n 2. Last indexed: timestamp of most recent indexing operation (from metadata.json last_indexed).\n 3. Store health: store file size on disk, provider name + model + dimensions from metadata.json.\n 4. Pending items: count and list from metadata.json pending array. Show file path and failure reason for each.\n 5. Mode indicator: Full (hybrid search) or Keyword-only (stub mode) based on whether a provider is configured.\n 6. Provider mismatch warning: if metadata.json provider/model/dimensions differs from current config, warn: Config has changed since last index. Run knowledge rebuild to reindex.\n 7. Orphan detection (finding #11): chunks in the store whose source_file no longer exists on disk. Report count and list.\n 8. Unindexed artifacts (finding #11): completed artifacts found via manifest that are not in the store. Report count and list. Uses the same discovery logic as bulk index (Task 4-4) but only reports, does not index.\n 9. Manifest-knowledge consistency (finding #12): cross-reference manifest state against store contents. Report:\n - Superseded specs still indexed: specs whose manifest status is superseded but chunks still exist in the store (should have been removed by the supersession action in Phase 5).\n - Promoted specs not relocated: specs whose manifest status is promoted but chunks still exist under the original work unit (should have been removed and re-indexed under the new cross-cutting work unit).\n - Cancelled work units still present: chunks for work units whose manifest status is cancelled (should have been removed by the cancellation action in Phase 5).\n These are consistency warnings — the processing skills handle the operations, status catches failures.\n 10. Stub-to-full upgrade note (finding #13): if config has a provider with API key but store was built in keyword-only mode, note: Keyword-only mode but embedding provider configured. Run knowledge rebuild for full hybrid search.\n- Output is plain text, human-readable. Not JSON, not machine-parsed.\n- Read-only — no file lock needed, no store modifications.\n\nREBUILD COMMAND (from design doc lines 644-649):\n- Invocation: knowledge rebuild\n- Destructive reindex from current artifacts. Drops existing index, re-chunks and re-embeds everything.\n- HUMAN-ONLY — uses interactive confirmation prompts via process.stdin. Use a type-the-action-word pattern (like Terraform destroy or GitHub repo delete) rather than yes/no — it forces engagement with what is being done:\n Warning: This will delete the existing index and rebuild from scratch.\n This is non-deterministic — the rebuilt index will differ from the original.\n Type 'rebuild' to confirm:\n- If confirmation does not match the word exactly, abort.\n- If confirmed: delete store.msp, delete metadata.json, then run bulk index logic from Task 4-4 (knowledge index no-args internally).\n- Claude cannot handle interactive terminals — this is the natural protection against accidental invocation.\n\nBATCH QUERIES (extend the query command from Task 3-4):\n- Invocation: knowledge query \u003cterm1\u003e \u003cterm2\u003e [\u003ctermN\u003e...] [--flags]\n- Multiple positional arguments = multiple search terms.\n- Implementation (from design doc line 602-603):\n 1. Load the store once.\n 2. Run a separate search for each term (embed + search + re-rank).\n 3. Merge all result sets.\n 4. Deduplicate by chunk ID — if the same chunk appears in multiple result sets, keep the highest score.\n 5. Sort merged results by score (descending).\n 6. Apply --limit to the merged set (not per-query).\n 7. Format output as normal (same provenance format from Task 3-4).\n- This is efficient: one store load, multiple searches, one formatted output.\n\nSTUB-TO-FULL UPGRADE NOTE ON QUERY OUTPUT (finding #13, line 992):\n- When the store was built in keyword-only mode but the current config has a provider with API key configured, prepend a one-line upgrade note to the query output (before the result count header):\n [keyword-only mode but embedding provider configured — run knowledge rebuild for full hybrid search]\n- This is separate from the existing stub mode note (which appears when NO provider is configured). The stub-to-full note specifically flags the upgrade opportunity when a provider HAS been configured but the store has not been rebuilt yet.\n- Applies to both single and batch query invocations.\n- Detection: compare metadata.json (what the store was built with) against the current resolved config (what the system is configured for now). If current config has a provider + API key but metadata.json indicates keyword-only, show the note.\n- Design doc rationale: this surfaces the upgrade opportunity naturally during workflow use, not just on manual status checks.\n\nPHASE 4 CLI TESTS:\n- Test file: tests/scripts/test-knowledge-cli.sh (extend with Phase 4 command tests)\n- Status tests:\n - it reports chunk counts by work unit and phase\n - it reports store size and provider info\n - it reports pending queue items\n - it warns about provider mismatch\n - it detects orphaned chunks (source file deleted)\n - it detects unindexed completed artifacts\n - it reports superseded specs still indexed\n - it reports cancelled work units still present\n - it reports keyword-only mode when no provider\n - it reports stub-to-full upgrade note when provider available but store is keyword-only\n- Rebuild tests:\n - it prompts for confirmation (test by piping non-matching input — should abort)\n - it aborts when confirmation does not match the word rebuild\n - (full rebuild is hard to test non-interactively — test the abort path, note the confirm path for manual testing)\n- Batch query tests:\n - it returns merged results from multiple search terms\n - it deduplicates chunks appearing in multiple result sets (keeps highest score)\n - it applies --limit to the merged set\n - it handles batch where one term has results and another does not\n- Stub-to-full query note tests:\n - it shows the upgrade note on query output when config has provider but store is keyword-only\n - it does NOT show the upgrade note when store and config match\n - it does NOT show the upgrade note in pure stub mode (no provider configured)\n\nAcceptance Criteria:\n- knowledge status outputs a comprehensive health report with all 10 sections\n- Status correctly detects orphaned chunks and unindexed artifacts\n- Status correctly warns about provider mismatch\n- Status correctly reports superseded specs still indexed, cancelled work units still present (manifest-knowledge consistency)\n- knowledge rebuild prompts with type-the-word confirmation and aborts on mismatch\n- knowledge rebuild (when confirmed manually) deletes and recreates the index\n- Batch query merges and deduplicates results from multiple terms\n- Batch query applies limit to the merged result set\n- Stub-to-full upgrade note appears on knowledge query output when applicable\n- All Phase 4 CLI tests pass\n\nEdge Cases:\n- Status on empty store — reports 0 chunks, no orphans, may report unindexed artifacts\n- Status when metadata.json is missing — report what is available, note missing metadata\n- Status when no manifest exists (no .workflows/) — report error for manifest-dependent checks, still report store-only metrics\n- Rebuild when store does not exist — nothing to delete, proceed with bulk index\n- Batch query with duplicate terms (same term twice) — should work, deduplication handles it\n- Batch query with one term that matches nothing — merged results only contain results from the other term(s)\n- Rebuild in non-interactive environment (piped stdin) — read from stdin for the type-the-word confirmation. If stdin is not a TTY and no input is provided, abort (do not hang).\n- Manifest-knowledge consistency when manifest has been updated but skills have not run yet (e.g., spec manually marked superseded) — status reports the inconsistency, user runs knowledge remove manually\n- Stub-to-full note on query output during a store just transitioned — user ran setup with a new provider but has not rebuilt yet. Note appears until rebuild.\n\nSpec Reference: knowledge-base/design.md — knowledge status command (lines 680-688), knowledge rebuild command (lines 644-649), batch query description (line 602-603), Index-artifact drift detection review finding #11 (line 985), Manifest-knowledge consistency review finding #12 (line 988, superseded/promoted/cancelled checks), Stub-to-full upgrade detection review finding #13 (line 991-992, including the note on query output)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-12T13:56:31Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-12T13:59:57Z","auto":false}],"parent":"tick-c52ba5","created":"2026-04-08T18:05:40Z","updated":"2026-04-12T13:59:57Z","closed":"2026-04-12T13:59:57Z"} -{"id":"tick-77697a","title":"Phase 5: Skill Integration","status":"open","priority":2,"refs":["knowledge-base-5"],"parent":"tick-cbbd13","created":"2026-04-08T18:22:03Z","updated":"2026-04-08T18:22:03Z"} -{"id":"tick-7d74fe","title":"Hard Stop Reference + Step 0 Integration","status":"open","priority":2,"type":"task","refs":["knowledge-base-5-1"],"description":"Problem: Entry-point skills need to gate on knowledge base readiness before proceeding. Without this gate, skills would attempt to query or index against a non-existent knowledge base. The design doc makes the knowledge base required infrastructure — no graceful degradation, just a clear hard stop with setup instructions.\n\nSolution: Create a hard stop reference file and update Step 0 in all 11 entry-point skills to run knowledge check after migrations, display the hard stop if not ready, and run knowledge compact if ready.\n\nOutcome: Every workflow invocation checks knowledge base readiness before proceeding, with a clear user-facing message when setup is needed, and automatic compaction keeping the index lean.\n\nDo:\n\nHARD STOP REFERENCE FILE:\n- Create skills/workflow-shared/references/knowledge-not-ready.md (or similar shared location — check where other shared references live).\n- This file is loaded and displayed when knowledge check returns not-ready.\n- Content should follow the existing hard stop / terminal condition conventions from CLAUDE.md:\n - Phase title box explaining what happened\n - Signpost blockquote explaining why the knowledge base is needed\n - Clear instruction: run knowledge setup to initialise\n - The exact command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs setup\n - Brief explanation of what setup does (system config, project init, initial indexing)\n - Mention stub mode is available if no API key\n - Terminal stop — do not proceed\n- Follow the display conventions from CLAUDE.md: phase title (bullet-bordered box), signpost blockquote, rendering instructions.\n\nSTEP 0 CHANGES:\n- Update Step 0 in ALL 11 entry-point skills. The affected files:\n skills/start-feature/SKILL.md\n skills/start-epic/SKILL.md\n skills/start-bugfix/SKILL.md\n skills/start-quickfix/SKILL.md\n skills/start-cross-cutting/SKILL.md\n skills/continue-feature/SKILL.md\n skills/continue-epic/SKILL.md\n skills/continue-bugfix/SKILL.md\n skills/continue-quickfix/SKILL.md\n skills/continue-cross-cutting/SKILL.md\n skills/workflow-start/SKILL.md\n\n- The Step 0 sequence after this change:\n 1. Migrations (existing — preserve as-is)\n 2. Knowledge check: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs check and capture stdout.\n - If stdout is not-ready: load the hard stop reference file and follow its instructions. STOP — do not proceed.\n - If stdout is ready: proceed.\n 3. Knowledge compact: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs compact (no flags — not dry-run). This is silent when nothing to compact. Output only appears if chunks were removed.\n\n- The existing Step 0 structure varies between start-* and continue-* skills:\n - start-* skills CHECK if /workflow-migrate has been invoked (they expect it was already run)\n - continue-* and workflow-start ACTIVELY run migrations if not done\n The knowledge check + compact goes AFTER the migration handling in both cases. Read each skill's Step 0 to understand its current structure before modifying.\n\n- Each skill's Step 0 will need its own rendering instruction for the check result / compact output if applicable. Follow the existing conventions in each skill.\n\nALLOWED-TOOLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to the allowed-tools frontmatter of all 11 entry-point skills.\n- This follows the same pattern as the manifest CLI allowed-tools entries already in these files. Check one skill first to see the exact format.\n\nAcceptance Criteria:\n- Hard stop reference file exists and follows display conventions\n- All 11 entry-point skills have knowledge check in Step 0 after migrations\n- knowledge check returning not-ready loads the hard stop reference and stops\n- knowledge check returning ready proceeds normally\n- All 11 entry-point skills run knowledge compact after successful check\n- Compact output is visible when chunks are removed, silent when nothing to compact\n- allowed-tools frontmatter updated in all 11 entry-point skills\n- Existing migration handling in Step 0 is preserved and unmodified\n- The Step 0 ordering is: migrations -\u003e knowledge check -\u003e knowledge compact\n\nTests:\n- No automated tests for this task — it is a skill file editing task. Validation is manual:\n - Invoke a start-* skill with no knowledge base set up -\u003e verify hard stop appears\n - Invoke a continue-* skill with knowledge base set up -\u003e verify check passes and compact runs\n - Verify allowed-tools entries are present in all 11 files\n\nEdge Cases:\n- knowledge check fails with a genuine error (not not-ready, but a crash) — the skill should surface the error, not silently proceed. Check exit code: 0 is expected (ready or not-ready on stdout). Non-zero means something broke.\n- knowledge compact fails (e.g., store locked) — should surface the error but not hard-stop the workflow. Compaction failure is a warning, not a blocker. The knowledge base still works, just with stale chunks.\n- Existing Step 0 in start-* skills only checks if migrations were invoked — adding knowledge steps must not change this conditional structure. The check and compact are unconditional additions after the migration section.\n\nSpec Reference: knowledge-base/design.md — Knowledge Base is Required Infrastructure section (lines 304-320, setup flow, hard stop), Compaction Trigger section (lines 847-855, Step 0 sequence: migrations -\u003e check -\u003e compact), allowed-tools frontmatter changes (lines 728-733)","parent":"tick-77697a","created":"2026-04-09T08:19:17Z","updated":"2026-04-09T08:19:17Z"} +{"id":"tick-77697a","title":"Phase 5: Skill Integration","status":"in_progress","priority":2,"refs":["knowledge-base-5"],"transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:07:42Z","auto":true}],"parent":"tick-cbbd13","created":"2026-04-08T18:22:03Z","updated":"2026-04-16T20:07:42Z"} +{"id":"tick-7d74fe","title":"Hard Stop Reference + Step 0 Integration","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-1"],"description":"Problem: Entry-point skills need to gate on knowledge base readiness before proceeding. Without this gate, skills would attempt to query or index against a non-existent knowledge base. The design doc makes the knowledge base required infrastructure — no graceful degradation, just a clear hard stop with setup instructions.\n\nSolution: Create a hard stop reference file and update Step 0 in all 11 entry-point skills to run knowledge check after migrations, display the hard stop if not ready, and run knowledge compact if ready.\n\nOutcome: Every workflow invocation checks knowledge base readiness before proceeding, with a clear user-facing message when setup is needed, and automatic compaction keeping the index lean.\n\nDo:\n\nHARD STOP REFERENCE FILE:\n- Create skills/workflow-shared/references/knowledge-not-ready.md (or similar shared location — check where other shared references live).\n- This file is loaded and displayed when knowledge check returns not-ready.\n- Content should follow the existing hard stop / terminal condition conventions from CLAUDE.md:\n - Phase title box explaining what happened\n - Signpost blockquote explaining why the knowledge base is needed\n - Clear instruction: run knowledge setup to initialise\n - The exact command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs setup\n - Brief explanation of what setup does (system config, project init, initial indexing)\n - Mention stub mode is available if no API key\n - Terminal stop — do not proceed\n- Follow the display conventions from CLAUDE.md: phase title (bullet-bordered box), signpost blockquote, rendering instructions.\n\nSTEP 0 CHANGES:\n- Update Step 0 in ALL 11 entry-point skills. The affected files:\n skills/start-feature/SKILL.md\n skills/start-epic/SKILL.md\n skills/start-bugfix/SKILL.md\n skills/start-quickfix/SKILL.md\n skills/start-cross-cutting/SKILL.md\n skills/continue-feature/SKILL.md\n skills/continue-epic/SKILL.md\n skills/continue-bugfix/SKILL.md\n skills/continue-quickfix/SKILL.md\n skills/continue-cross-cutting/SKILL.md\n skills/workflow-start/SKILL.md\n\n- The Step 0 sequence after this change:\n 1. Migrations (existing — preserve as-is)\n 2. Knowledge check: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs check and capture stdout.\n - If stdout is not-ready: load the hard stop reference file and follow its instructions. STOP — do not proceed.\n - If stdout is ready: proceed.\n 3. Knowledge compact: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs compact (no flags — not dry-run). This is silent when nothing to compact. Output only appears if chunks were removed.\n\n- The existing Step 0 structure varies between start-* and continue-* skills:\n - start-* skills CHECK if /workflow-migrate has been invoked (they expect it was already run)\n - continue-* and workflow-start ACTIVELY run migrations if not done\n The knowledge check + compact goes AFTER the migration handling in both cases. Read each skill's Step 0 to understand its current structure before modifying.\n\n- Each skill's Step 0 will need its own rendering instruction for the check result / compact output if applicable. Follow the existing conventions in each skill.\n\nALLOWED-TOOLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to the allowed-tools frontmatter of all 11 entry-point skills.\n- This follows the same pattern as the manifest CLI allowed-tools entries already in these files. Check one skill first to see the exact format.\n\nAcceptance Criteria:\n- Hard stop reference file exists and follows display conventions\n- All 11 entry-point skills have knowledge check in Step 0 after migrations\n- knowledge check returning not-ready loads the hard stop reference and stops\n- knowledge check returning ready proceeds normally\n- All 11 entry-point skills run knowledge compact after successful check\n- Compact output is visible when chunks are removed, silent when nothing to compact\n- allowed-tools frontmatter updated in all 11 entry-point skills\n- Existing migration handling in Step 0 is preserved and unmodified\n- The Step 0 ordering is: migrations -\u003e knowledge check -\u003e knowledge compact\n\nTests:\n- No automated tests for this task — it is a skill file editing task. Validation is manual:\n - Invoke a start-* skill with no knowledge base set up -\u003e verify hard stop appears\n - Invoke a continue-* skill with knowledge base set up -\u003e verify check passes and compact runs\n - Verify allowed-tools entries are present in all 11 files\n\nEdge Cases:\n- knowledge check fails with a genuine error (not not-ready, but a crash) — the skill should surface the error, not silently proceed. Check exit code: 0 is expected (ready or not-ready on stdout). Non-zero means something broke.\n- knowledge compact fails (e.g., store locked) — should surface the error but not hard-stop the workflow. Compaction failure is a warning, not a blocker. The knowledge base still works, just with stale chunks.\n- Existing Step 0 in start-* skills only checks if migrations were invoked — adding knowledge steps must not change this conditional structure. The check and compact are unconditional additions after the migration section.\n\nSpec Reference: knowledge-base/design.md — Knowledge Base is Required Infrastructure section (lines 304-320, setup flow, hard stop), Compaction Trigger section (lines 847-855, Step 0 sequence: migrations -\u003e check -\u003e compact), allowed-tools frontmatter changes (lines 728-733)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:07:42Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:14:06Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T08:19:17Z","updated":"2026-04-16T20:14:06Z","closed":"2026-04-16T20:14:06Z"} {"id":"tick-055556","title":"Phase Completion Indexing","status":"open","priority":2,"type":"task","refs":["knowledge-base-5-2"],"description":"Problem: The knowledge base needs to grow automatically as workflow phases complete. Without automatic indexing at phase completion, users would need to manually run knowledge index after every discussion, research session, investigation, or specification — which would never happen consistently.\n\nSolution: Add knowledge index \u003cfile\u003e calls at the phase completion points in processing skills for all indexed phases, plus scoping (which produces a spec). Also audit the skills/ directory for every place that transitions a work unit to status: completed and add completed_at alongside each one.\n\nOutcome: Every completed workflow artifact is automatically indexed into the knowledge base, and every work unit completion path sets completed_at for the compact command's TTL calculation.\n\nDo:\n- Add knowledge index \u003cfile\u003e at the phase completion step in each of these processing skills:\n\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-specification-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n\n- For each skill, find the step where the phase artifact is finalised and committed. The index call goes AFTER the artifact is saved to disk and committed, but BEFORE any phase transition or handoff to the next phase. The artifact must exist on disk before indexing.\n\n- The index call pattern:\n Run: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index \u003cartifact_path\u003e\n Where \u003cartifact_path\u003e is the path to the completed artifact file. Each phase has a different path convention:\n - Research: .workflows/{work_unit}/research/{topic}.md (may vary — use the actual file that was just written)\n - Discussion: .workflows/{work_unit}/discussion/{topic}.md\n - Investigation: .workflows/{work_unit}/investigation/{topic}.md\n - Specification: .workflows/{work_unit}/specification/{topic}/specification.md\n - Scoping: produces a specification — index the spec file it creates, NOT a scoping artifact (scoping is not an indexed phase per design doc)\n\n- The index call should reference the actual file path variable/value used in the skill, not a hardcoded path. Read each skill to understand how it references the artifact file.\n\n- FAILURE HANDLING: indexing failure must NOT block the phase. The artifact is already saved. If knowledge index fails, output the error message (which includes retry-failed + pending queue info from Task 4-4) and continue with the phase transition. The design doc is explicit: the phase itself is not blocked — the artifact is saved. But the failure is made visible, not silently swallowed.\n\n- MULTIPLE INDEXED ARTIFACTS: some skills may complete multiple artifacts. For example, scoping produces both a specification and potentially sets up planning. Only the spec needs indexing. Each index call is independent — a failure on one does not block the other (per design doc line 707).\n\nCOMPLETED_AT AUDIT (concrete instruction, not judgement call):\n- The completed_at field (added by the migration in Task 4-2) needs to be set going forward whenever ANY code path transitions a work unit to status: completed. Missing a path means the work unit will never expire under compaction (Task 4-5 handles missing completed_at defensively, but the result is silent non-compaction).\n- AUDIT STEP: grep the skills/ directory for every place that sets status to completed. Suggested grep patterns:\n grep -rn 'status.*completed' skills/\n grep -rn 'manifest.cjs set.*status.*completed' skills/\n grep -rn 'completed' skills/ | grep -i status\n- For EACH match, add a manifest.cjs set {work_unit} completed_at {current_date_ISO} call alongside the status-setting call. Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n- Known locations (verified to exist — the grep is still the authoritative source, but these are the high-traffic files):\n - skills/workflow-bridge/references/ — 5 continuation files set status: completed (bugfix-continuation.md, feature-continuation.md, epic-continuation.md, cross-cutting-continuation.md, quickfix-continuation.md). Bridge is where most feature/bugfix/quickfix completions happen — do not miss these.\n - The 5 processing skills listed above (research, discussion, investigation, specification, scoping) — conclude-*.md references\n - skills/workflow-review-process/references/review-actions-loop.md — review is often the last phase and may mark the work unit completed\n - skills/workflow-implementation-process/references/conclude-implementation.md — implementation completion\n - skills/workflow-specification-process/references/spec-completion.md and promote-to-cross-cutting.md — specification lifecycle\n - skills/workflow-scoping-process/references/write-tasks.md and write-specification.md — scoping completion paths\n - skills/workflow-start/references/manage-work-unit.md — the manage menu done action, covered by Task 5-3\n- DO NOT rely on the list above being exhaustive. The grep is the authoritative source of truth. Add completed_at setting wherever the grep finds status: completed being set, even if the file is not in the list above.\n- Report the full list of files modified (for review) when completing this task.\n- Acceptance post-condition: after editing, grep -rn 'status.*completed' skills/ should show every match adjacent (same step or reference block) to a corresponding completed_at set. This is a mechanical check the implementer can run to self-verify coverage.\n\n- Add allowed-tools for knowledge.cjs to these 5 processing skills (if not already added by Task 5-1 or Task 5-3).\n\nAcceptance Criteria:\n- Research process skill indexes the research artifact on completion\n- Discussion process skill indexes the discussion artifact on completion\n- Investigation process skill indexes the investigation artifact on completion\n- Specification process skill indexes the specification artifact on completion\n- Scoping process skill indexes the spec it produces on completion\n- Index failure does not block the phase — error is displayed, phase continues\n- Every place in skills/ that sets status: completed also sets completed_at (verified via grep audit)\n- All 5 bridge continuation files are updated (bugfix, feature, epic, cross-cutting, quickfix)\n- The list of files modified for completed_at is documented in the task completion report\n- Post-condition grep shows every status: completed match adjacent to a completed_at set\n- allowed-tools updated in all 5 processing skills\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Complete a discussion in a test project -\u003e verify chunks appear in knowledge base (knowledge status shows them)\n - Complete a specification -\u003e verify chunks appear\n - Simulate index failure (e.g., corrupt store) -\u003e verify phase still completes, error is shown\n - Grep skills/ after task completion: every status-completed line should have a neighbouring completed_at line\n\nEdge Cases:\n- Scoping produces a spec but scoping itself is not an indexed phase — only the spec output is indexed. The index call must reference the spec file path, not a scoping artifact path.\n- Research in epics can produce multiple files — each file may need separate indexing. Check how the research process skill handles multiple outputs. If it produces one file per research topic, each gets its own index call.\n- completed_at audit finds a skill that doesn't import the manifest CLI — check the skill's allowed-tools and add if needed\n- Phase completion with no artifact file (edge case — should not happen in normal flow) — knowledge index will error on missing file, which is correct and visible.\n- A skill sets status: completed on a DIFFERENT work unit than its own (e.g., the manage menu) — this is covered by Task 5-3 for the manage menu specifically.\n- Bridge continuation files may set completed on a SOURCE work unit when transitioning (e.g., a feature completion closing out the feature before bridging to the next). Ensure completed_at is set on the same work unit whose status is being set.\n\nSpec Reference: knowledge-base/design.md — Indexing section (lines 337-341, primary trigger is phase completion, not mid-phase), Integration with Workflow Skills section (lines 707-708, indexing at phase completion, independent per artifact, failure does not block), completed_at field (line 824-829, set explicitly by skill at completion time going forward, the manage menu done action and any skill that sets status: completed must also set completed_at)","parent":"tick-77697a","created":"2026-04-09T17:54:59Z","updated":"2026-04-10T19:57:54Z"} {"id":"tick-f84af0","title":"Lifecycle Removal (Cancellation + Supersession/Promotion)","status":"open","priority":2,"type":"task","refs":["knowledge-base-5-3"],"description":"Problem: When work units are cancelled or specs are superseded/promoted, their chunks must be removed from the knowledge base. Without this, stale and contradictory information pollutes search results. Additionally, the manage menu's done action needs to set completed_at for compaction TTL calculation.\n\nSolution: Add knowledge remove calls to the manage menu reference (cancellation) and specification process (supersession/promotion) skills. Add completed_at setting to the manage menu's done action.\n\nOutcome: Work unit cancellation and spec lifecycle changes automatically clean the knowledge base, and completed work units have the timestamp needed for decay compaction.\n\nDo:\n\nCANCELLATION REMOVAL (manage menu reference):\n- The manage menu lives inside the workflow-start skill at skills/workflow-start/references/manage-work-unit.md (NOT a separate workflow-manage skill — verified).\n- Locate the cancellation action in that file (where status is set to cancelled).\n- Add inline: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit}\n- This runs INLINE as part of the cancellation action — no prompt, cancelling means done with it (design doc line 801).\n- If removal fails (store locked, CLI error): log the error visibly but do not block the cancellation. The pending queue is designed for indexing failures, not removal failures. If removal fails, output the error and note that the user can run knowledge remove manually.\n- NO frontmatter edit is needed here — skills/workflow-start is an entry-point skill that already receives allowed-tools for knowledge.cjs in Task 5-1. The reference file inherits from its parent skill.\n\nCOMPLETED_AT ON DONE ACTION (manage menu reference):\n- Locate the done/completion action in skills/workflow-start/references/manage-work-unit.md (where status is set to completed).\n- Add: manifest.cjs set {work_unit} completed_at {current_date_ISO}\n- The completed_at field is what compaction (Task 4-5) uses to calculate decay TTL. Without it, completed work units cannot expire and the index grows without bound.\n- This complements Task 5-2 which adds completed_at in processing skills and bridge continuations where completion happens automatically. The manage menu is where users manually mark work units as done — both paths must set the field.\n- Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n\nSUPERSESSION REMOVAL (specification process skill):\n- Find the specification process skill: skills/workflow-specification-process/SKILL.md\n- Locate the supersession action — where a spec's manifest status changes to superseded.\n- Add: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- This removes ONLY the superseded topic's spec chunks. Other topics in the same work unit (e.g., other specs in an epic) are unaffected. Granularity matters (design doc line 656).\n- The specification process skill already has allowed-tools for knowledge.cjs from Task 5-2 (for indexing). No additional frontmatter change needed.\n\nPROMOTION REMOVAL (specification process skill):\n- Locate the promotion action — where a spec's manifest status changes to promoted.\n- Add the same remove command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- Promotion is a RELOCATION, not a deletion (design doc line 535). The chunks are removed from the original work unit. The new cross-cutting spec will be indexed naturally when it completes in the new work unit. There is a timing gap where the content is absent from the knowledge base — this is accepted per design doc line 537.\n- Research, discussion, and investigation chunks from the original work unit are KEPT — only the spec chunks are removed (design doc line 539).\n\nALLOWED-TOOLS SUMMARY FOR PHASE 5:\n- Task 5-1 adds to 11 entry-point skills (for check + compact). workflow-start is one of them, which covers the manage-work-unit.md reference file used by this task.\n- Task 5-2 adds to 5 indexed phase processing skills (for index), and updates bridge continuation files.\n- This task adds NO new allowed-tools entries — all target files are covered by Tasks 5-1 or 5-2.\n- Total Phase 5 allowed-tools changes: 16 skills (11 from 5-1 + 5 from 5-2).\n- The 3 non-indexed processing skills (planning, implementation, review) get allowed-tools in Phase 6 Task 6-2 when autonomous querying is added — no Phase 5 reason to add them now.\n- Phase entry skills (workflow-*-entry) do NOT get allowed-tools in Phase 5. The one exception is workflow-planning-entry, which gets allowed-tools in Phase 6 Task 6-3 specifically for the cross-cutting query. No other phase entry skill needs it.\n\nAcceptance Criteria:\n- Cancelling a work unit via manage menu removes its chunks from the knowledge base\n- Cancellation removal failure does not block the cancellation action\n- Manage menu done action sets completed_at on the work unit manifest\n- Superseding a spec removes only that topic's spec chunks\n- Promoting a spec removes only that topic's spec chunks from the original work unit\n- Research/discussion/investigation chunks from the same work unit survive supersession and promotion\n- No new allowed-tools frontmatter edits in this task (covered by Task 5-1 for workflow-start, Task 5-2 for specification-process)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Cancel a work unit that has indexed chunks -\u003e verify chunks are removed (knowledge status)\n - Mark a work unit as done via manage menu -\u003e verify completed_at is set in manifest\n - Supersede a spec topic in an epic -\u003e verify only that topic's spec chunks are removed, other topics and non-spec phases survive\n\nEdge Cases:\n- Cancellation of a work unit that was never indexed — knowledge remove returns 0 removed, no error. The cancellation flow should not treat this as a failure.\n- Supersession of a spec that was never indexed — same, 0 removed, no error.\n- Promotion timing gap — between removing original spec chunks and the new cross-cutting spec completing, the content is absent from the knowledge base. This is accepted per design doc.\n- Epic with multiple spec topics — superseding one MUST NOT remove others. The --topic flag ensures granularity.\n- Done action on a work unit that already has completed_at — overwrite with current date (the user is explicitly marking it done now, regardless of previous state).\n\nSpec Reference: knowledge-base/design.md — Work Unit Lifecycle section (lines 799-801, cancelled work units auto-removed, failure handling), Staleness and Supersession section (lines 530-539, superseded removed, promoted relocated, research/discussion/investigation kept), completed_at prerequisite (line 824, manage menu done action must set it), allowed-tools frontmatter changes (lines 728-733)","parent":"tick-77697a","created":"2026-04-09T17:58:53Z","updated":"2026-04-10T19:57:48Z"} {"id":"tick-496c59","title":"Phase 6: Retrieval Integration","status":"open","priority":2,"refs":["knowledge-base-6"],"parent":"tick-cbbd13","created":"2026-04-09T18:09:56Z","updated":"2026-04-09T18:09:56Z"} diff --git a/skills/continue-bugfix/SKILL.md b/skills/continue-bugfix/SKILL.md index 6f2bdfc56..619155375 100644 --- a/skills/continue-bugfix/SKILL.md +++ b/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. @@ -40,6 +40,8 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions. #### If the `/workflow-migrate` skill has already been invoked in this conversation +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. #### Otherwise @@ -54,7 +56,9 @@ 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 the next instruction below. Do not stop after migration completes. + +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/continue-cross-cutting/SKILL.md b/skills/continue-cross-cutting/SKILL.md index a84b90e04..b65453469 100644 --- a/skills/continue-cross-cutting/SKILL.md +++ b/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. @@ -40,6 +40,8 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions. #### If the `/workflow-migrate` skill has already been invoked in this conversation +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. #### Otherwise @@ -54,7 +56,9 @@ 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 the next instruction below. Do not stop after migration completes. + +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/continue-epic/SKILL.md b/skills/continue-epic/SKILL.md index 5f6d5492e..b73a1f106 100644 --- a/skills/continue-epic/SKILL.md +++ b/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. @@ -40,6 +40,8 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions. #### If the `/workflow-migrate` skill has already been invoked in this conversation +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. #### Otherwise @@ -54,7 +56,9 @@ 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 the next instruction below. Do not stop after migration completes. + +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/continue-feature/SKILL.md b/skills/continue-feature/SKILL.md index c58fdcbe3..8438144c6 100644 --- a/skills/continue-feature/SKILL.md +++ b/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. @@ -40,6 +40,8 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions. #### If the `/workflow-migrate` skill has already been invoked in this conversation +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. #### Otherwise @@ -54,7 +56,9 @@ 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 the next instruction below. Do not stop after migration completes. + +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/continue-quickfix/SKILL.md b/skills/continue-quickfix/SKILL.md index 0377f4293..bc89a2968 100644 --- a/skills/continue-quickfix/SKILL.md +++ b/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. @@ -40,6 +40,8 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions. #### If the `/workflow-migrate` skill has already been invoked in this conversation +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. #### Otherwise @@ -54,7 +56,9 @@ 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 the next instruction below. Do not stop after migration completes. + +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. diff --git a/skills/start-bugfix/SKILL.md b/skills/start-bugfix/SKILL.md index cd3633fbf..bd95bf60e 100644 --- a/skills/start-bugfix/SKILL.md +++ b/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. @@ -47,6 +47,8 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions. > 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**. #### Otherwise @@ -79,6 +81,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**. --- diff --git a/skills/start-cross-cutting/SKILL.md b/skills/start-cross-cutting/SKILL.md index d2622bafa..2c6dc9ba9 100644 --- a/skills/start-cross-cutting/SKILL.md +++ b/skills/start-cross-cutting/SKILL.md @@ -1,6 +1,6 @@ --- name: start-cross-cutting -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 cross-cutting concern. Gather a brief description, create the work unit, and route to the first phase. @@ -49,6 +49,8 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions. > pipeline ends at specification — no planning or implementation. ``` +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. #### Otherwise @@ -83,6 +85,8 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if > pipeline ends at specification — no planning or implementation. ``` +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. --- diff --git a/skills/start-epic/SKILL.md b/skills/start-epic/SKILL.md index f3541ee26..bd9a0e9c6 100644 --- a/skills/start-epic/SKILL.md +++ b/skills/start-epic/SKILL.md @@ -1,6 +1,6 @@ --- name: start-epic -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 epic. Gather a brief description, create the work unit, and route to the first phase. @@ -48,6 +48,8 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions. > straight to discussion. ``` +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. #### Otherwise @@ -81,6 +83,8 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if > straight to discussion. ``` +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. --- diff --git a/skills/start-feature/SKILL.md b/skills/start-feature/SKILL.md index 08404639b..f2628bb69 100644 --- a/skills/start-feature/SKILL.md +++ b/skills/start-feature/SKILL.md @@ -1,6 +1,6 @@ --- name: start-feature -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 feature. Gather a brief description, create the work unit, and route to the first phase. @@ -48,6 +48,8 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions. > to discussion. ``` +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. #### Otherwise @@ -81,6 +83,8 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if > to discussion. ``` +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. --- diff --git a/skills/start-quickfix/SKILL.md b/skills/start-quickfix/SKILL.md index 7c3120a45..7bf2bc1b4 100644 --- a/skills/start-quickfix/SKILL.md +++ b/skills/start-quickfix/SKILL.md @@ -1,6 +1,6 @@ --- name: start-quickfix -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 quick-fix. Gather a brief description, create the work unit, and route to scoping. @@ -48,6 +48,8 @@ Load **[casing-conventions.md](../workflow-shared/references/casing-conventions. > and plan into a single streamlined pass. ``` +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. #### Otherwise @@ -81,6 +83,8 @@ Invoke the `/workflow-migrate` skill and follow its instructions exactly — if > and plan into a single streamlined pass. ``` +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. + → Proceed to **Step 1**. --- diff --git a/skills/workflow-shared/references/knowledge-check.md b/skills/workflow-shared/references/knowledge-check.md new file mode 100644 index 000000000..ab316c37a --- /dev/null +++ b/skills/workflow-shared/references/knowledge-check.md @@ -0,0 +1,100 @@ +# Knowledge Check + +*Shared reference for all entry-point skills.* + +--- + +Check knowledge base readiness. If not ready, display a hard stop with setup instructions. If ready, run compaction to keep the index lean. + +## A. Check Readiness + +Run the following command and capture its stdout and exit code: + +``` +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs check +``` + +#### If the command exits with a non-zero exit code + +The knowledge CLI crashed unexpectedly. Surface the error: + +> *Output the next fenced block as a code block:* + +``` +●───────────────────────────────────────────────● + Knowledge Base Error +●───────────────────────────────────────────────● + +The knowledge check command failed unexpectedly: + + {error output} + +This must be resolved before the workflow can proceed. +``` + +**STOP.** Do not proceed — terminal condition. + +#### If stdout is `not-ready` + +> *Output the next fenced block as a code block:* + +``` +●───────────────────────────────────────────────● + Knowledge Base Not Ready +●───────────────────────────────────────────────● + +``` + +> *Output the next fenced block as markdown (not a code block):* + +``` +> The knowledge base is required infrastructure for workflows. +> It must be initialised before any workflow can proceed. +``` + +> *Output the next fenced block as a code block:* + +``` +To set up the knowledge base, run: + + node .claude/skills/workflow-knowledge/scripts/knowledge.cjs setup + +Setup configures system defaults, initialises the project store, +and runs the initial indexing pass. If no API key is available, +stub mode is offered as an alternative. +``` + +**STOP.** Do not proceed — terminal condition. + +#### If stdout is `ready` + +→ Proceed to **B. Compact**. + +## B. Compact + +Run the following command: + +``` +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs compact +``` + +If the command produces output (chunks were removed), display it. If it produces no output, proceed silently. + +#### If the command exits with a non-zero exit code + +Surface the error as a warning — compaction failure is not a blocker. + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge compaction warning + {error details} + Compaction failed but the knowledge base is functional. + Proceeding normally. +``` + +→ Return to caller. + +#### Otherwise + +→ Return to caller. diff --git a/skills/workflow-start/SKILL.md b/skills/workflow-start/SKILL.md index 09f0945d8..07fa57edd 100644 --- a/skills/workflow-start/SKILL.md +++ b/skills/workflow-start/SKILL.md @@ -1,7 +1,7 @@ --- name: workflow-start disable-model-invocation: true -allowed-tools: Bash(node .claude/skills/workflow-start/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs) +allowed-tools: Bash(node .claude/skills/workflow-start/scripts/discovery.cjs), Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) --- Unified workflow entry point. Discovers state, shows all active work, and routes to start or continue skills. @@ -61,7 +61,9 @@ 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 the next instruction below. Do not stop after migration completes. + +Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. → Proceed to **Step 1**. From d559659c3df6e6334182ef81a5799cc2bdb56635 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Thu, 16 Apr 2026 21:19:41 +0100 Subject: [PATCH 02/15] feat(knowledge): add phase completion indexing + completed_at audit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add knowledge index calls at phase completion in 5 processing skills (research, discussion, investigation, specification, scoping). Index failure displays warning but does not block — artifact is already saved. Add completed_at alongside every work-unit-level status:completed set (5 bridge continuations, manage-work-unit, promote-to-cross-cutting). Add allowed-tools for knowledge.cjs to 5 processing skills. Files modified for completed_at: - skills/workflow-bridge/references/{feature,bugfix,epic,cross-cutting,quickfix}-continuation.md - skills/workflow-start/references/manage-work-unit.md - skills/workflow-specification-process/references/promote-to-cross-cutting.md Co-Authored-By: Claude Opus 4.6 (1M context) --- .tick/tasks.jsonl | 2 +- .../references/bugfix-continuation.md | 2 ++ .../references/cross-cutting-continuation.md | 1 + .../references/epic-continuation.md | 1 + .../references/feature-continuation.md | 2 ++ .../references/quickfix-continuation.md | 2 ++ skills/workflow-discussion-process/SKILL.md | 2 +- .../references/conclude-discussion.md | 13 ++++++++++++- skills/workflow-investigation-process/SKILL.md | 2 +- .../references/conclude-investigation.md | 17 ++++++++++++++--- skills/workflow-research-process/SKILL.md | 2 +- .../references/conclude-research.md | 15 +++++++++++++-- skills/workflow-scoping-process/SKILL.md | 2 +- .../references/write-specification.md | 16 ++++++++++++++++ skills/workflow-specification-process/SKILL.md | 2 +- .../references/promote-to-cross-cutting.md | 1 + .../references/spec-completion.md | 16 ++++++++++++++++ .../references/manage-work-unit.md | 1 + 18 files changed, 87 insertions(+), 12 deletions(-) diff --git a/.tick/tasks.jsonl b/.tick/tasks.jsonl index 8a1a27dfd..605a294fe 100644 --- a/.tick/tasks.jsonl +++ b/.tick/tasks.jsonl @@ -23,7 +23,7 @@ {"id":"tick-097bf0","title":"Status + Rebuild + Batch Queries + Phase 4 CLI Tests","status":"done","priority":2,"type":"task","refs":["knowledge-base-4-6"],"description":"Problem: Three remaining CLI features need implementation: status (health reporting for debugging), rebuild (destructive reindex for provider changes), and batch queries (multiple search terms in one invocation). These are all Phase 4 completeness items — the knowledge base is functional without them but they round out the CLI for production use.\n\nSolution: Implement the status, rebuild, and batch query features, plus a comprehensive CLI test suite covering all Phase 4 commands.\n\nOutcome: A complete CLI with all 8 commands implemented, plus tests validating everything works against the built bundle.\n\nDo:\n\nSTATUS COMMAND (from design doc lines 680-688 + review findings 11-13):\n- Invocation: knowledge status (no arguments)\n- Full health report — not used in skill automation, intended for user/debugging.\n- Report sections:\n 1. Index summary: total chunk count, broken down by work unit, phase, and work type.\n 2. Last indexed: timestamp of most recent indexing operation (from metadata.json last_indexed).\n 3. Store health: store file size on disk, provider name + model + dimensions from metadata.json.\n 4. Pending items: count and list from metadata.json pending array. Show file path and failure reason for each.\n 5. Mode indicator: Full (hybrid search) or Keyword-only (stub mode) based on whether a provider is configured.\n 6. Provider mismatch warning: if metadata.json provider/model/dimensions differs from current config, warn: Config has changed since last index. Run knowledge rebuild to reindex.\n 7. Orphan detection (finding #11): chunks in the store whose source_file no longer exists on disk. Report count and list.\n 8. Unindexed artifacts (finding #11): completed artifacts found via manifest that are not in the store. Report count and list. Uses the same discovery logic as bulk index (Task 4-4) but only reports, does not index.\n 9. Manifest-knowledge consistency (finding #12): cross-reference manifest state against store contents. Report:\n - Superseded specs still indexed: specs whose manifest status is superseded but chunks still exist in the store (should have been removed by the supersession action in Phase 5).\n - Promoted specs not relocated: specs whose manifest status is promoted but chunks still exist under the original work unit (should have been removed and re-indexed under the new cross-cutting work unit).\n - Cancelled work units still present: chunks for work units whose manifest status is cancelled (should have been removed by the cancellation action in Phase 5).\n These are consistency warnings — the processing skills handle the operations, status catches failures.\n 10. Stub-to-full upgrade note (finding #13): if config has a provider with API key but store was built in keyword-only mode, note: Keyword-only mode but embedding provider configured. Run knowledge rebuild for full hybrid search.\n- Output is plain text, human-readable. Not JSON, not machine-parsed.\n- Read-only — no file lock needed, no store modifications.\n\nREBUILD COMMAND (from design doc lines 644-649):\n- Invocation: knowledge rebuild\n- Destructive reindex from current artifacts. Drops existing index, re-chunks and re-embeds everything.\n- HUMAN-ONLY — uses interactive confirmation prompts via process.stdin. Use a type-the-action-word pattern (like Terraform destroy or GitHub repo delete) rather than yes/no — it forces engagement with what is being done:\n Warning: This will delete the existing index and rebuild from scratch.\n This is non-deterministic — the rebuilt index will differ from the original.\n Type 'rebuild' to confirm:\n- If confirmation does not match the word exactly, abort.\n- If confirmed: delete store.msp, delete metadata.json, then run bulk index logic from Task 4-4 (knowledge index no-args internally).\n- Claude cannot handle interactive terminals — this is the natural protection against accidental invocation.\n\nBATCH QUERIES (extend the query command from Task 3-4):\n- Invocation: knowledge query \u003cterm1\u003e \u003cterm2\u003e [\u003ctermN\u003e...] [--flags]\n- Multiple positional arguments = multiple search terms.\n- Implementation (from design doc line 602-603):\n 1. Load the store once.\n 2. Run a separate search for each term (embed + search + re-rank).\n 3. Merge all result sets.\n 4. Deduplicate by chunk ID — if the same chunk appears in multiple result sets, keep the highest score.\n 5. Sort merged results by score (descending).\n 6. Apply --limit to the merged set (not per-query).\n 7. Format output as normal (same provenance format from Task 3-4).\n- This is efficient: one store load, multiple searches, one formatted output.\n\nSTUB-TO-FULL UPGRADE NOTE ON QUERY OUTPUT (finding #13, line 992):\n- When the store was built in keyword-only mode but the current config has a provider with API key configured, prepend a one-line upgrade note to the query output (before the result count header):\n [keyword-only mode but embedding provider configured — run knowledge rebuild for full hybrid search]\n- This is separate from the existing stub mode note (which appears when NO provider is configured). The stub-to-full note specifically flags the upgrade opportunity when a provider HAS been configured but the store has not been rebuilt yet.\n- Applies to both single and batch query invocations.\n- Detection: compare metadata.json (what the store was built with) against the current resolved config (what the system is configured for now). If current config has a provider + API key but metadata.json indicates keyword-only, show the note.\n- Design doc rationale: this surfaces the upgrade opportunity naturally during workflow use, not just on manual status checks.\n\nPHASE 4 CLI TESTS:\n- Test file: tests/scripts/test-knowledge-cli.sh (extend with Phase 4 command tests)\n- Status tests:\n - it reports chunk counts by work unit and phase\n - it reports store size and provider info\n - it reports pending queue items\n - it warns about provider mismatch\n - it detects orphaned chunks (source file deleted)\n - it detects unindexed completed artifacts\n - it reports superseded specs still indexed\n - it reports cancelled work units still present\n - it reports keyword-only mode when no provider\n - it reports stub-to-full upgrade note when provider available but store is keyword-only\n- Rebuild tests:\n - it prompts for confirmation (test by piping non-matching input — should abort)\n - it aborts when confirmation does not match the word rebuild\n - (full rebuild is hard to test non-interactively — test the abort path, note the confirm path for manual testing)\n- Batch query tests:\n - it returns merged results from multiple search terms\n - it deduplicates chunks appearing in multiple result sets (keeps highest score)\n - it applies --limit to the merged set\n - it handles batch where one term has results and another does not\n- Stub-to-full query note tests:\n - it shows the upgrade note on query output when config has provider but store is keyword-only\n - it does NOT show the upgrade note when store and config match\n - it does NOT show the upgrade note in pure stub mode (no provider configured)\n\nAcceptance Criteria:\n- knowledge status outputs a comprehensive health report with all 10 sections\n- Status correctly detects orphaned chunks and unindexed artifacts\n- Status correctly warns about provider mismatch\n- Status correctly reports superseded specs still indexed, cancelled work units still present (manifest-knowledge consistency)\n- knowledge rebuild prompts with type-the-word confirmation and aborts on mismatch\n- knowledge rebuild (when confirmed manually) deletes and recreates the index\n- Batch query merges and deduplicates results from multiple terms\n- Batch query applies limit to the merged result set\n- Stub-to-full upgrade note appears on knowledge query output when applicable\n- All Phase 4 CLI tests pass\n\nEdge Cases:\n- Status on empty store — reports 0 chunks, no orphans, may report unindexed artifacts\n- Status when metadata.json is missing — report what is available, note missing metadata\n- Status when no manifest exists (no .workflows/) — report error for manifest-dependent checks, still report store-only metrics\n- Rebuild when store does not exist — nothing to delete, proceed with bulk index\n- Batch query with duplicate terms (same term twice) — should work, deduplication handles it\n- Batch query with one term that matches nothing — merged results only contain results from the other term(s)\n- Rebuild in non-interactive environment (piped stdin) — read from stdin for the type-the-word confirmation. If stdin is not a TTY and no input is provided, abort (do not hang).\n- Manifest-knowledge consistency when manifest has been updated but skills have not run yet (e.g., spec manually marked superseded) — status reports the inconsistency, user runs knowledge remove manually\n- Stub-to-full note on query output during a store just transitioned — user ran setup with a new provider but has not rebuilt yet. Note appears until rebuild.\n\nSpec Reference: knowledge-base/design.md — knowledge status command (lines 680-688), knowledge rebuild command (lines 644-649), batch query description (line 602-603), Index-artifact drift detection review finding #11 (line 985), Manifest-knowledge consistency review finding #12 (line 988, superseded/promoted/cancelled checks), Stub-to-full upgrade detection review finding #13 (line 991-992, including the note on query output)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-12T13:56:31Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-12T13:59:57Z","auto":false}],"parent":"tick-c52ba5","created":"2026-04-08T18:05:40Z","updated":"2026-04-12T13:59:57Z","closed":"2026-04-12T13:59:57Z"} {"id":"tick-77697a","title":"Phase 5: Skill Integration","status":"in_progress","priority":2,"refs":["knowledge-base-5"],"transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:07:42Z","auto":true}],"parent":"tick-cbbd13","created":"2026-04-08T18:22:03Z","updated":"2026-04-16T20:07:42Z"} {"id":"tick-7d74fe","title":"Hard Stop Reference + Step 0 Integration","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-1"],"description":"Problem: Entry-point skills need to gate on knowledge base readiness before proceeding. Without this gate, skills would attempt to query or index against a non-existent knowledge base. The design doc makes the knowledge base required infrastructure — no graceful degradation, just a clear hard stop with setup instructions.\n\nSolution: Create a hard stop reference file and update Step 0 in all 11 entry-point skills to run knowledge check after migrations, display the hard stop if not ready, and run knowledge compact if ready.\n\nOutcome: Every workflow invocation checks knowledge base readiness before proceeding, with a clear user-facing message when setup is needed, and automatic compaction keeping the index lean.\n\nDo:\n\nHARD STOP REFERENCE FILE:\n- Create skills/workflow-shared/references/knowledge-not-ready.md (or similar shared location — check where other shared references live).\n- This file is loaded and displayed when knowledge check returns not-ready.\n- Content should follow the existing hard stop / terminal condition conventions from CLAUDE.md:\n - Phase title box explaining what happened\n - Signpost blockquote explaining why the knowledge base is needed\n - Clear instruction: run knowledge setup to initialise\n - The exact command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs setup\n - Brief explanation of what setup does (system config, project init, initial indexing)\n - Mention stub mode is available if no API key\n - Terminal stop — do not proceed\n- Follow the display conventions from CLAUDE.md: phase title (bullet-bordered box), signpost blockquote, rendering instructions.\n\nSTEP 0 CHANGES:\n- Update Step 0 in ALL 11 entry-point skills. The affected files:\n skills/start-feature/SKILL.md\n skills/start-epic/SKILL.md\n skills/start-bugfix/SKILL.md\n skills/start-quickfix/SKILL.md\n skills/start-cross-cutting/SKILL.md\n skills/continue-feature/SKILL.md\n skills/continue-epic/SKILL.md\n skills/continue-bugfix/SKILL.md\n skills/continue-quickfix/SKILL.md\n skills/continue-cross-cutting/SKILL.md\n skills/workflow-start/SKILL.md\n\n- The Step 0 sequence after this change:\n 1. Migrations (existing — preserve as-is)\n 2. Knowledge check: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs check and capture stdout.\n - If stdout is not-ready: load the hard stop reference file and follow its instructions. STOP — do not proceed.\n - If stdout is ready: proceed.\n 3. Knowledge compact: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs compact (no flags — not dry-run). This is silent when nothing to compact. Output only appears if chunks were removed.\n\n- The existing Step 0 structure varies between start-* and continue-* skills:\n - start-* skills CHECK if /workflow-migrate has been invoked (they expect it was already run)\n - continue-* and workflow-start ACTIVELY run migrations if not done\n The knowledge check + compact goes AFTER the migration handling in both cases. Read each skill's Step 0 to understand its current structure before modifying.\n\n- Each skill's Step 0 will need its own rendering instruction for the check result / compact output if applicable. Follow the existing conventions in each skill.\n\nALLOWED-TOOLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to the allowed-tools frontmatter of all 11 entry-point skills.\n- This follows the same pattern as the manifest CLI allowed-tools entries already in these files. Check one skill first to see the exact format.\n\nAcceptance Criteria:\n- Hard stop reference file exists and follows display conventions\n- All 11 entry-point skills have knowledge check in Step 0 after migrations\n- knowledge check returning not-ready loads the hard stop reference and stops\n- knowledge check returning ready proceeds normally\n- All 11 entry-point skills run knowledge compact after successful check\n- Compact output is visible when chunks are removed, silent when nothing to compact\n- allowed-tools frontmatter updated in all 11 entry-point skills\n- Existing migration handling in Step 0 is preserved and unmodified\n- The Step 0 ordering is: migrations -\u003e knowledge check -\u003e knowledge compact\n\nTests:\n- No automated tests for this task — it is a skill file editing task. Validation is manual:\n - Invoke a start-* skill with no knowledge base set up -\u003e verify hard stop appears\n - Invoke a continue-* skill with knowledge base set up -\u003e verify check passes and compact runs\n - Verify allowed-tools entries are present in all 11 files\n\nEdge Cases:\n- knowledge check fails with a genuine error (not not-ready, but a crash) — the skill should surface the error, not silently proceed. Check exit code: 0 is expected (ready or not-ready on stdout). Non-zero means something broke.\n- knowledge compact fails (e.g., store locked) — should surface the error but not hard-stop the workflow. Compaction failure is a warning, not a blocker. The knowledge base still works, just with stale chunks.\n- Existing Step 0 in start-* skills only checks if migrations were invoked — adding knowledge steps must not change this conditional structure. The check and compact are unconditional additions after the migration section.\n\nSpec Reference: knowledge-base/design.md — Knowledge Base is Required Infrastructure section (lines 304-320, setup flow, hard stop), Compaction Trigger section (lines 847-855, Step 0 sequence: migrations -\u003e check -\u003e compact), allowed-tools frontmatter changes (lines 728-733)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:07:42Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:14:06Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T08:19:17Z","updated":"2026-04-16T20:14:06Z","closed":"2026-04-16T20:14:06Z"} -{"id":"tick-055556","title":"Phase Completion Indexing","status":"open","priority":2,"type":"task","refs":["knowledge-base-5-2"],"description":"Problem: The knowledge base needs to grow automatically as workflow phases complete. Without automatic indexing at phase completion, users would need to manually run knowledge index after every discussion, research session, investigation, or specification — which would never happen consistently.\n\nSolution: Add knowledge index \u003cfile\u003e calls at the phase completion points in processing skills for all indexed phases, plus scoping (which produces a spec). Also audit the skills/ directory for every place that transitions a work unit to status: completed and add completed_at alongside each one.\n\nOutcome: Every completed workflow artifact is automatically indexed into the knowledge base, and every work unit completion path sets completed_at for the compact command's TTL calculation.\n\nDo:\n- Add knowledge index \u003cfile\u003e at the phase completion step in each of these processing skills:\n\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-specification-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n\n- For each skill, find the step where the phase artifact is finalised and committed. The index call goes AFTER the artifact is saved to disk and committed, but BEFORE any phase transition or handoff to the next phase. The artifact must exist on disk before indexing.\n\n- The index call pattern:\n Run: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index \u003cartifact_path\u003e\n Where \u003cartifact_path\u003e is the path to the completed artifact file. Each phase has a different path convention:\n - Research: .workflows/{work_unit}/research/{topic}.md (may vary — use the actual file that was just written)\n - Discussion: .workflows/{work_unit}/discussion/{topic}.md\n - Investigation: .workflows/{work_unit}/investigation/{topic}.md\n - Specification: .workflows/{work_unit}/specification/{topic}/specification.md\n - Scoping: produces a specification — index the spec file it creates, NOT a scoping artifact (scoping is not an indexed phase per design doc)\n\n- The index call should reference the actual file path variable/value used in the skill, not a hardcoded path. Read each skill to understand how it references the artifact file.\n\n- FAILURE HANDLING: indexing failure must NOT block the phase. The artifact is already saved. If knowledge index fails, output the error message (which includes retry-failed + pending queue info from Task 4-4) and continue with the phase transition. The design doc is explicit: the phase itself is not blocked — the artifact is saved. But the failure is made visible, not silently swallowed.\n\n- MULTIPLE INDEXED ARTIFACTS: some skills may complete multiple artifacts. For example, scoping produces both a specification and potentially sets up planning. Only the spec needs indexing. Each index call is independent — a failure on one does not block the other (per design doc line 707).\n\nCOMPLETED_AT AUDIT (concrete instruction, not judgement call):\n- The completed_at field (added by the migration in Task 4-2) needs to be set going forward whenever ANY code path transitions a work unit to status: completed. Missing a path means the work unit will never expire under compaction (Task 4-5 handles missing completed_at defensively, but the result is silent non-compaction).\n- AUDIT STEP: grep the skills/ directory for every place that sets status to completed. Suggested grep patterns:\n grep -rn 'status.*completed' skills/\n grep -rn 'manifest.cjs set.*status.*completed' skills/\n grep -rn 'completed' skills/ | grep -i status\n- For EACH match, add a manifest.cjs set {work_unit} completed_at {current_date_ISO} call alongside the status-setting call. Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n- Known locations (verified to exist — the grep is still the authoritative source, but these are the high-traffic files):\n - skills/workflow-bridge/references/ — 5 continuation files set status: completed (bugfix-continuation.md, feature-continuation.md, epic-continuation.md, cross-cutting-continuation.md, quickfix-continuation.md). Bridge is where most feature/bugfix/quickfix completions happen — do not miss these.\n - The 5 processing skills listed above (research, discussion, investigation, specification, scoping) — conclude-*.md references\n - skills/workflow-review-process/references/review-actions-loop.md — review is often the last phase and may mark the work unit completed\n - skills/workflow-implementation-process/references/conclude-implementation.md — implementation completion\n - skills/workflow-specification-process/references/spec-completion.md and promote-to-cross-cutting.md — specification lifecycle\n - skills/workflow-scoping-process/references/write-tasks.md and write-specification.md — scoping completion paths\n - skills/workflow-start/references/manage-work-unit.md — the manage menu done action, covered by Task 5-3\n- DO NOT rely on the list above being exhaustive. The grep is the authoritative source of truth. Add completed_at setting wherever the grep finds status: completed being set, even if the file is not in the list above.\n- Report the full list of files modified (for review) when completing this task.\n- Acceptance post-condition: after editing, grep -rn 'status.*completed' skills/ should show every match adjacent (same step or reference block) to a corresponding completed_at set. This is a mechanical check the implementer can run to self-verify coverage.\n\n- Add allowed-tools for knowledge.cjs to these 5 processing skills (if not already added by Task 5-1 or Task 5-3).\n\nAcceptance Criteria:\n- Research process skill indexes the research artifact on completion\n- Discussion process skill indexes the discussion artifact on completion\n- Investigation process skill indexes the investigation artifact on completion\n- Specification process skill indexes the specification artifact on completion\n- Scoping process skill indexes the spec it produces on completion\n- Index failure does not block the phase — error is displayed, phase continues\n- Every place in skills/ that sets status: completed also sets completed_at (verified via grep audit)\n- All 5 bridge continuation files are updated (bugfix, feature, epic, cross-cutting, quickfix)\n- The list of files modified for completed_at is documented in the task completion report\n- Post-condition grep shows every status: completed match adjacent to a completed_at set\n- allowed-tools updated in all 5 processing skills\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Complete a discussion in a test project -\u003e verify chunks appear in knowledge base (knowledge status shows them)\n - Complete a specification -\u003e verify chunks appear\n - Simulate index failure (e.g., corrupt store) -\u003e verify phase still completes, error is shown\n - Grep skills/ after task completion: every status-completed line should have a neighbouring completed_at line\n\nEdge Cases:\n- Scoping produces a spec but scoping itself is not an indexed phase — only the spec output is indexed. The index call must reference the spec file path, not a scoping artifact path.\n- Research in epics can produce multiple files — each file may need separate indexing. Check how the research process skill handles multiple outputs. If it produces one file per research topic, each gets its own index call.\n- completed_at audit finds a skill that doesn't import the manifest CLI — check the skill's allowed-tools and add if needed\n- Phase completion with no artifact file (edge case — should not happen in normal flow) — knowledge index will error on missing file, which is correct and visible.\n- A skill sets status: completed on a DIFFERENT work unit than its own (e.g., the manage menu) — this is covered by Task 5-3 for the manage menu specifically.\n- Bridge continuation files may set completed on a SOURCE work unit when transitioning (e.g., a feature completion closing out the feature before bridging to the next). Ensure completed_at is set on the same work unit whose status is being set.\n\nSpec Reference: knowledge-base/design.md — Indexing section (lines 337-341, primary trigger is phase completion, not mid-phase), Integration with Workflow Skills section (lines 707-708, indexing at phase completion, independent per artifact, failure does not block), completed_at field (line 824-829, set explicitly by skill at completion time going forward, the manage menu done action and any skill that sets status: completed must also set completed_at)","parent":"tick-77697a","created":"2026-04-09T17:54:59Z","updated":"2026-04-10T19:57:54Z"} +{"id":"tick-055556","title":"Phase Completion Indexing","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-2"],"description":"Problem: The knowledge base needs to grow automatically as workflow phases complete. Without automatic indexing at phase completion, users would need to manually run knowledge index after every discussion, research session, investigation, or specification — which would never happen consistently.\n\nSolution: Add knowledge index \u003cfile\u003e calls at the phase completion points in processing skills for all indexed phases, plus scoping (which produces a spec). Also audit the skills/ directory for every place that transitions a work unit to status: completed and add completed_at alongside each one.\n\nOutcome: Every completed workflow artifact is automatically indexed into the knowledge base, and every work unit completion path sets completed_at for the compact command's TTL calculation.\n\nDo:\n- Add knowledge index \u003cfile\u003e at the phase completion step in each of these processing skills:\n\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-specification-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n\n- For each skill, find the step where the phase artifact is finalised and committed. The index call goes AFTER the artifact is saved to disk and committed, but BEFORE any phase transition or handoff to the next phase. The artifact must exist on disk before indexing.\n\n- The index call pattern:\n Run: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index \u003cartifact_path\u003e\n Where \u003cartifact_path\u003e is the path to the completed artifact file. Each phase has a different path convention:\n - Research: .workflows/{work_unit}/research/{topic}.md (may vary — use the actual file that was just written)\n - Discussion: .workflows/{work_unit}/discussion/{topic}.md\n - Investigation: .workflows/{work_unit}/investigation/{topic}.md\n - Specification: .workflows/{work_unit}/specification/{topic}/specification.md\n - Scoping: produces a specification — index the spec file it creates, NOT a scoping artifact (scoping is not an indexed phase per design doc)\n\n- The index call should reference the actual file path variable/value used in the skill, not a hardcoded path. Read each skill to understand how it references the artifact file.\n\n- FAILURE HANDLING: indexing failure must NOT block the phase. The artifact is already saved. If knowledge index fails, output the error message (which includes retry-failed + pending queue info from Task 4-4) and continue with the phase transition. The design doc is explicit: the phase itself is not blocked — the artifact is saved. But the failure is made visible, not silently swallowed.\n\n- MULTIPLE INDEXED ARTIFACTS: some skills may complete multiple artifacts. For example, scoping produces both a specification and potentially sets up planning. Only the spec needs indexing. Each index call is independent — a failure on one does not block the other (per design doc line 707).\n\nCOMPLETED_AT AUDIT (concrete instruction, not judgement call):\n- The completed_at field (added by the migration in Task 4-2) needs to be set going forward whenever ANY code path transitions a work unit to status: completed. Missing a path means the work unit will never expire under compaction (Task 4-5 handles missing completed_at defensively, but the result is silent non-compaction).\n- AUDIT STEP: grep the skills/ directory for every place that sets status to completed. Suggested grep patterns:\n grep -rn 'status.*completed' skills/\n grep -rn 'manifest.cjs set.*status.*completed' skills/\n grep -rn 'completed' skills/ | grep -i status\n- For EACH match, add a manifest.cjs set {work_unit} completed_at {current_date_ISO} call alongside the status-setting call. Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n- Known locations (verified to exist — the grep is still the authoritative source, but these are the high-traffic files):\n - skills/workflow-bridge/references/ — 5 continuation files set status: completed (bugfix-continuation.md, feature-continuation.md, epic-continuation.md, cross-cutting-continuation.md, quickfix-continuation.md). Bridge is where most feature/bugfix/quickfix completions happen — do not miss these.\n - The 5 processing skills listed above (research, discussion, investigation, specification, scoping) — conclude-*.md references\n - skills/workflow-review-process/references/review-actions-loop.md — review is often the last phase and may mark the work unit completed\n - skills/workflow-implementation-process/references/conclude-implementation.md — implementation completion\n - skills/workflow-specification-process/references/spec-completion.md and promote-to-cross-cutting.md — specification lifecycle\n - skills/workflow-scoping-process/references/write-tasks.md and write-specification.md — scoping completion paths\n - skills/workflow-start/references/manage-work-unit.md — the manage menu done action, covered by Task 5-3\n- DO NOT rely on the list above being exhaustive. The grep is the authoritative source of truth. Add completed_at setting wherever the grep finds status: completed being set, even if the file is not in the list above.\n- Report the full list of files modified (for review) when completing this task.\n- Acceptance post-condition: after editing, grep -rn 'status.*completed' skills/ should show every match adjacent (same step or reference block) to a corresponding completed_at set. This is a mechanical check the implementer can run to self-verify coverage.\n\n- Add allowed-tools for knowledge.cjs to these 5 processing skills (if not already added by Task 5-1 or Task 5-3).\n\nAcceptance Criteria:\n- Research process skill indexes the research artifact on completion\n- Discussion process skill indexes the discussion artifact on completion\n- Investigation process skill indexes the investigation artifact on completion\n- Specification process skill indexes the specification artifact on completion\n- Scoping process skill indexes the spec it produces on completion\n- Index failure does not block the phase — error is displayed, phase continues\n- Every place in skills/ that sets status: completed also sets completed_at (verified via grep audit)\n- All 5 bridge continuation files are updated (bugfix, feature, epic, cross-cutting, quickfix)\n- The list of files modified for completed_at is documented in the task completion report\n- Post-condition grep shows every status: completed match adjacent to a completed_at set\n- allowed-tools updated in all 5 processing skills\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Complete a discussion in a test project -\u003e verify chunks appear in knowledge base (knowledge status shows them)\n - Complete a specification -\u003e verify chunks appear\n - Simulate index failure (e.g., corrupt store) -\u003e verify phase still completes, error is shown\n - Grep skills/ after task completion: every status-completed line should have a neighbouring completed_at line\n\nEdge Cases:\n- Scoping produces a spec but scoping itself is not an indexed phase — only the spec output is indexed. The index call must reference the spec file path, not a scoping artifact path.\n- Research in epics can produce multiple files — each file may need separate indexing. Check how the research process skill handles multiple outputs. If it produces one file per research topic, each gets its own index call.\n- completed_at audit finds a skill that doesn't import the manifest CLI — check the skill's allowed-tools and add if needed\n- Phase completion with no artifact file (edge case — should not happen in normal flow) — knowledge index will error on missing file, which is correct and visible.\n- A skill sets status: completed on a DIFFERENT work unit than its own (e.g., the manage menu) — this is covered by Task 5-3 for the manage menu specifically.\n- Bridge continuation files may set completed on a SOURCE work unit when transitioning (e.g., a feature completion closing out the feature before bridging to the next). Ensure completed_at is set on the same work unit whose status is being set.\n\nSpec Reference: knowledge-base/design.md — Indexing section (lines 337-341, primary trigger is phase completion, not mid-phase), Integration with Workflow Skills section (lines 707-708, indexing at phase completion, independent per artifact, failure does not block), completed_at field (line 824-829, set explicitly by skill at completion time going forward, the manage menu done action and any skill that sets status: completed must also set completed_at)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:14:29Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:19:31Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T17:54:59Z","updated":"2026-04-16T20:19:31Z","closed":"2026-04-16T20:19:31Z"} {"id":"tick-f84af0","title":"Lifecycle Removal (Cancellation + Supersession/Promotion)","status":"open","priority":2,"type":"task","refs":["knowledge-base-5-3"],"description":"Problem: When work units are cancelled or specs are superseded/promoted, their chunks must be removed from the knowledge base. Without this, stale and contradictory information pollutes search results. Additionally, the manage menu's done action needs to set completed_at for compaction TTL calculation.\n\nSolution: Add knowledge remove calls to the manage menu reference (cancellation) and specification process (supersession/promotion) skills. Add completed_at setting to the manage menu's done action.\n\nOutcome: Work unit cancellation and spec lifecycle changes automatically clean the knowledge base, and completed work units have the timestamp needed for decay compaction.\n\nDo:\n\nCANCELLATION REMOVAL (manage menu reference):\n- The manage menu lives inside the workflow-start skill at skills/workflow-start/references/manage-work-unit.md (NOT a separate workflow-manage skill — verified).\n- Locate the cancellation action in that file (where status is set to cancelled).\n- Add inline: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit}\n- This runs INLINE as part of the cancellation action — no prompt, cancelling means done with it (design doc line 801).\n- If removal fails (store locked, CLI error): log the error visibly but do not block the cancellation. The pending queue is designed for indexing failures, not removal failures. If removal fails, output the error and note that the user can run knowledge remove manually.\n- NO frontmatter edit is needed here — skills/workflow-start is an entry-point skill that already receives allowed-tools for knowledge.cjs in Task 5-1. The reference file inherits from its parent skill.\n\nCOMPLETED_AT ON DONE ACTION (manage menu reference):\n- Locate the done/completion action in skills/workflow-start/references/manage-work-unit.md (where status is set to completed).\n- Add: manifest.cjs set {work_unit} completed_at {current_date_ISO}\n- The completed_at field is what compaction (Task 4-5) uses to calculate decay TTL. Without it, completed work units cannot expire and the index grows without bound.\n- This complements Task 5-2 which adds completed_at in processing skills and bridge continuations where completion happens automatically. The manage menu is where users manually mark work units as done — both paths must set the field.\n- Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n\nSUPERSESSION REMOVAL (specification process skill):\n- Find the specification process skill: skills/workflow-specification-process/SKILL.md\n- Locate the supersession action — where a spec's manifest status changes to superseded.\n- Add: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- This removes ONLY the superseded topic's spec chunks. Other topics in the same work unit (e.g., other specs in an epic) are unaffected. Granularity matters (design doc line 656).\n- The specification process skill already has allowed-tools for knowledge.cjs from Task 5-2 (for indexing). No additional frontmatter change needed.\n\nPROMOTION REMOVAL (specification process skill):\n- Locate the promotion action — where a spec's manifest status changes to promoted.\n- Add the same remove command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- Promotion is a RELOCATION, not a deletion (design doc line 535). The chunks are removed from the original work unit. The new cross-cutting spec will be indexed naturally when it completes in the new work unit. There is a timing gap where the content is absent from the knowledge base — this is accepted per design doc line 537.\n- Research, discussion, and investigation chunks from the original work unit are KEPT — only the spec chunks are removed (design doc line 539).\n\nALLOWED-TOOLS SUMMARY FOR PHASE 5:\n- Task 5-1 adds to 11 entry-point skills (for check + compact). workflow-start is one of them, which covers the manage-work-unit.md reference file used by this task.\n- Task 5-2 adds to 5 indexed phase processing skills (for index), and updates bridge continuation files.\n- This task adds NO new allowed-tools entries — all target files are covered by Tasks 5-1 or 5-2.\n- Total Phase 5 allowed-tools changes: 16 skills (11 from 5-1 + 5 from 5-2).\n- The 3 non-indexed processing skills (planning, implementation, review) get allowed-tools in Phase 6 Task 6-2 when autonomous querying is added — no Phase 5 reason to add them now.\n- Phase entry skills (workflow-*-entry) do NOT get allowed-tools in Phase 5. The one exception is workflow-planning-entry, which gets allowed-tools in Phase 6 Task 6-3 specifically for the cross-cutting query. No other phase entry skill needs it.\n\nAcceptance Criteria:\n- Cancelling a work unit via manage menu removes its chunks from the knowledge base\n- Cancellation removal failure does not block the cancellation action\n- Manage menu done action sets completed_at on the work unit manifest\n- Superseding a spec removes only that topic's spec chunks\n- Promoting a spec removes only that topic's spec chunks from the original work unit\n- Research/discussion/investigation chunks from the same work unit survive supersession and promotion\n- No new allowed-tools frontmatter edits in this task (covered by Task 5-1 for workflow-start, Task 5-2 for specification-process)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Cancel a work unit that has indexed chunks -\u003e verify chunks are removed (knowledge status)\n - Mark a work unit as done via manage menu -\u003e verify completed_at is set in manifest\n - Supersede a spec topic in an epic -\u003e verify only that topic's spec chunks are removed, other topics and non-spec phases survive\n\nEdge Cases:\n- Cancellation of a work unit that was never indexed — knowledge remove returns 0 removed, no error. The cancellation flow should not treat this as a failure.\n- Supersession of a spec that was never indexed — same, 0 removed, no error.\n- Promotion timing gap — between removing original spec chunks and the new cross-cutting spec completing, the content is absent from the knowledge base. This is accepted per design doc.\n- Epic with multiple spec topics — superseding one MUST NOT remove others. The --topic flag ensures granularity.\n- Done action on a work unit that already has completed_at — overwrite with current date (the user is explicitly marking it done now, regardless of previous state).\n\nSpec Reference: knowledge-base/design.md — Work Unit Lifecycle section (lines 799-801, cancelled work units auto-removed, failure handling), Staleness and Supersession section (lines 530-539, superseded removed, promoted relocated, research/discussion/investigation kept), completed_at prerequisite (line 824, manage menu done action must set it), allowed-tools frontmatter changes (lines 728-733)","parent":"tick-77697a","created":"2026-04-09T17:58:53Z","updated":"2026-04-10T19:57:48Z"} {"id":"tick-496c59","title":"Phase 6: Retrieval Integration","status":"open","priority":2,"refs":["knowledge-base-6"],"parent":"tick-cbbd13","created":"2026-04-09T18:09:56Z","updated":"2026-04-09T18:09:56Z"} {"id":"tick-09d9ca","title":"Knowledge SKILL.md + Two-Step Retrieval Documentation","status":"open","priority":2,"type":"task","refs":["knowledge-base-6-1"],"description":"Problem: The knowledge base CLI exists (Phases 1-4) and is wired into skills (Phase 5), but Claude has no documentation explaining what it is, how to use it, or when to query it. Without Layer 1, Layers 2 and 3 have nothing to reference for API details.\n\nSolution: Create the knowledge skill file (SKILL.md) that serves as the API documentation layer — what commands exist, how to call them, what the output looks like, and how the two-step retrieval pattern works.\n\nOutcome: A comprehensive skill file that any processing skill can reference for knowledge base API details, enabling Claude to query the knowledge base correctly.\n\nDo:\n- Create skills/workflow-knowledge/SKILL.md following the project's skill file conventions (see CLAUDE.md Skill File Structure section).\n- This is a model-invocable skill, not user-invocable. It is loaded by reference from Layer 2 usage references (Task 6-2). It is NOT directly invoked by users.\n- Content sections:\n\n PURPOSE:\n - What the knowledge base is: a RAG system storing all workflow artifacts at full fidelity for semantic search\n - Why it exists: cross-work-unit and intra-work-unit context surfacing\n - What it indexes: research, discussion, investigation, specification (not planning, implementation, review)\n\n QUERY COMMAND:\n - Single query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003csearch_term\u003e [flags]\n - Batch query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003cterm1\u003e \u003cterm2\u003e [termN...] [flags]\n Multiple positional arguments run separate searches, merge results, deduplicate by chunk ID (highest score kept), apply --limit to merged set. Efficient: one store load, multiple searches.\n - Flags: --work-type, --phase, --work-unit (re-ranking hint, not filter), --limit\n - Search modes: hybrid (default when provider configured), keyword-only (when no provider)\n - Query construction guidance: use natural language, not topic slugs. Descriptive queries produce better semantic matching. Multiple queries from different angles are encouraged.\n - Example queries showing good vs poor query construction\n\n OUTPUT FORMAT:\n - Document the exact format (from design doc lines 580-603):\n [N results]\n [phase | work_unit/topic | confidence | YYYY-MM-DD]\n chunk content verbatim\n Source: source_file_path\n - Result count header, provenance line, verbatim content, source path\n - Empty results: [0 results]\n - Stub mode note when applicable: [keyword-only mode — configure embedding provider for semantic search]\n\n CONFIDENCE TIERS:\n - Explain what confidence means and how to weigh it:\n specification (high) — validated decisions, what was decided and why\n investigation (medium) — diagnostic knowledge, tied to specific symptoms\n discussion (low-medium) — conversational, may contain corrected assumptions\n research (low) — exploratory, may contain dead ends and rejected paths\n - Low confidence is not low value — research that rejected an approach prevents re-exploring dead ends\n\n TWO-STEP RETRIEVAL PATTERN:\n - Step 1: query returns chunks with provenance (lightweight, lands in context)\n - Step 2: if a chunk looks relevant, read the actual source file (source_file in metadata) for full detail\n - This keeps context lean — surface-level awareness, deep dive on demand\n - Claude should NOT read source files for every result, only when a chunk warrants deeper investigation\n\n WHAT NOT TO DO:\n - Do not dump large result sets into context speculatively\n - Do not query using topic slugs as search terms (poor semantic signal)\n - Do not query during specification phase (explicitly excluded — spec turns decisions into a golden doc, cross-cutting concerns merge at planning time)\n - Do not prepend metadata to stored content (already in enum fields)\n\nAcceptance Criteria:\n- SKILL.md exists at skills/workflow-knowledge/SKILL.md\n- Documents both single and batch query invocation forms\n- Documents all query flags and their behaviour\n- Documents the exact output format with examples\n- Documents confidence tiers with guidance on how to weigh them\n- Documents the two-step retrieval pattern (query -\u003e read source file on demand)\n- Documents what NOT to do (spec exclusion, slug queries, speculative dumps)\n- Follows project skill file conventions from CLAUDE.md\n- Can be loaded by reference from Layer 2 files (Task 6-2)\n\nTests:\n- No automated tests — documentation task. Validation is manual:\n - Read the SKILL.md and verify it provides enough information to correctly construct and interpret knowledge queries\n - Verify it follows the project's skill file structure conventions\n\nEdge Cases:\n- The SKILL.md must describe BOTH hybrid and keyword-only modes without making keyword-only feel broken — it is a supported degraded mode\n- Must not duplicate the CLI help text verbatim — this is higher-level guidance about when and why, not just how\n- Must explain that --work-unit is a re-ranking hint, not a filter — this is a common misunderstanding that would produce wrong queries if not clear\n- Batch query section must explain deduplication and merged limit behaviour\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 1 description), Retrieved Context Format (lines 576-605, exact output format), Confidence Tiers (lines 514-525), Two-step retrieval pattern (lines 735-737), Query construction (line 737), Batch query (line 602-603, merged and deduplicated), Specification excluded from automatic retrieval (line 560)","parent":"tick-496c59","created":"2026-04-09T18:22:30Z","updated":"2026-04-09T18:30:41Z"} diff --git a/skills/workflow-bridge/references/bugfix-continuation.md b/skills/workflow-bridge/references/bugfix-continuation.md index b5f5c7c1d..8b72caa09 100644 --- a/skills/workflow-bridge/references/bugfix-continuation.md +++ b/skills/workflow-bridge/references/bugfix-continuation.md @@ -29,6 +29,7 @@ Set the work unit status to completed: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} status completed +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} completed_at $(date +%Y-%m-%d) ``` Commit: `workflow({work_unit}): complete bugfix pipeline` @@ -75,6 +76,7 @@ Set the work unit status to completed: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} status completed +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} completed_at $(date +%Y-%m-%d) ``` Commit: `workflow({work_unit}): complete bugfix pipeline (review skipped)` diff --git a/skills/workflow-bridge/references/cross-cutting-continuation.md b/skills/workflow-bridge/references/cross-cutting-continuation.md index 814dc4852..dc0d97a9f 100644 --- a/skills/workflow-bridge/references/cross-cutting-continuation.md +++ b/skills/workflow-bridge/references/cross-cutting-continuation.md @@ -27,6 +27,7 @@ Set the work unit status to completed: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} status completed +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} completed_at $(date +%Y-%m-%d) ``` Commit: `workflow({work_unit}): complete cross-cutting pipeline` diff --git a/skills/workflow-bridge/references/epic-continuation.md b/skills/workflow-bridge/references/epic-continuation.md index 25b5a24ed..39b02d232 100644 --- a/skills/workflow-bridge/references/epic-continuation.md +++ b/skills/workflow-bridge/references/epic-continuation.md @@ -46,6 +46,7 @@ Set the work unit status to completed: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} status completed +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} completed_at $(date +%Y-%m-%d) ``` Commit: `workflow({work_unit}): complete epic pipeline` diff --git a/skills/workflow-bridge/references/feature-continuation.md b/skills/workflow-bridge/references/feature-continuation.md index e3f61bb7a..074b6f8e5 100644 --- a/skills/workflow-bridge/references/feature-continuation.md +++ b/skills/workflow-bridge/references/feature-continuation.md @@ -30,6 +30,7 @@ Set the work unit status to completed: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} status completed +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} completed_at $(date +%Y-%m-%d) ``` Commit: `workflow({work_unit}): complete feature pipeline` @@ -76,6 +77,7 @@ Set the work unit status to completed: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} status completed +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} completed_at $(date +%Y-%m-%d) ``` Commit: `workflow({work_unit}): complete feature pipeline (review skipped)` diff --git a/skills/workflow-bridge/references/quickfix-continuation.md b/skills/workflow-bridge/references/quickfix-continuation.md index 1715441b2..6b7fb75c4 100644 --- a/skills/workflow-bridge/references/quickfix-continuation.md +++ b/skills/workflow-bridge/references/quickfix-continuation.md @@ -27,6 +27,7 @@ Set the work unit status to completed: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} status completed +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} completed_at $(date +%Y-%m-%d) ``` Commit: `workflow({work_unit}): complete quick-fix pipeline` @@ -73,6 +74,7 @@ Set the work unit status to completed: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} status completed +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit} completed_at $(date +%Y-%m-%d) ``` Commit: `workflow({work_unit}): complete quick-fix pipeline (review skipped)` diff --git a/skills/workflow-discussion-process/SKILL.md b/skills/workflow-discussion-process/SKILL.md index 333c7982b..d3f44cf30 100644 --- a/skills/workflow-discussion-process/SKILL.md +++ b/skills/workflow-discussion-process/SKILL.md @@ -1,7 +1,7 @@ --- name: workflow-discussion-process user-invocable: false -allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs) +allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) --- # Discussion Process diff --git a/skills/workflow-discussion-process/references/conclude-discussion.md b/skills/workflow-discussion-process/references/conclude-discussion.md index 1db8505c5..3cb6a9579 100644 --- a/skills/workflow-discussion-process/references/conclude-discussion.md +++ b/skills/workflow-discussion-process/references/conclude-discussion.md @@ -27,7 +27,18 @@ Conclude this discussion and mark as completed? node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.discussion.{topic} status completed ``` 3. Final commit -4. Invoke the bridge: +4. Index the completed artifact into the knowledge base: + ```bash + node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/discussion/{topic}.md + ``` + If the index command fails, display the error but do not block — the artifact is already saved: + > *Output the next fenced block as a code block:* + ``` + ⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. + ``` +5. Invoke the bridge: > *Output the next fenced block as markdown (not a code block):* diff --git a/skills/workflow-investigation-process/SKILL.md b/skills/workflow-investigation-process/SKILL.md index 9f754b1e3..e25f153a9 100644 --- a/skills/workflow-investigation-process/SKILL.md +++ b/skills/workflow-investigation-process/SKILL.md @@ -1,7 +1,7 @@ --- name: workflow-investigation-process user-invocable: false -allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs) +allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) --- # Investigation Process diff --git a/skills/workflow-investigation-process/references/conclude-investigation.md b/skills/workflow-investigation-process/references/conclude-investigation.md index 04c4af9d2..dbaf3c746 100644 --- a/skills/workflow-investigation-process/references/conclude-investigation.md +++ b/skills/workflow-investigation-process/references/conclude-investigation.md @@ -30,7 +30,18 @@ Investigation complete. Ready to conclude? node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.investigation.{topic} status completed ``` 2. Final commit -3. Display conclusion: +3. Index the completed artifact into the knowledge base: + ```bash + node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/investigation/{topic}.md + ``` + If the index command fails, display the error but do not block — the artifact is already saved: + > *Output the next fenced block as a code block:* + ``` + ⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. + ``` +4. Display conclusion: > *Output the next fenced block as a code block:* @@ -43,7 +54,7 @@ Fix direction: {chosen approach} The investigation is completed. Root cause and fix direction are documented. ``` -4. Closure signpost: +5. Closure signpost: > *Output the next fenced block as markdown (not a code block):* @@ -52,7 +63,7 @@ The investigation is completed. Root cause and fix direction are documented. > the fix approach into a document that drives planning. ``` -5. Invoke the bridge: +6. Invoke the bridge: ``` Pipeline bridge for: {work_unit} diff --git a/skills/workflow-research-process/SKILL.md b/skills/workflow-research-process/SKILL.md index 09bd822f4..23f60cde1 100644 --- a/skills/workflow-research-process/SKILL.md +++ b/skills/workflow-research-process/SKILL.md @@ -1,7 +1,7 @@ --- name: workflow-research-process user-invocable: false -allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs) +allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) --- # Research Process diff --git a/skills/workflow-research-process/references/conclude-research.md b/skills/workflow-research-process/references/conclude-research.md index 6a44a5c59..7127538b7 100644 --- a/skills/workflow-research-process/references/conclude-research.md +++ b/skills/workflow-research-process/references/conclude-research.md @@ -9,7 +9,18 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.research.{topic} status completed ``` 2. Final commit: `research({work_unit}): complete {topic} research` -3. Closure signpost: +3. Index the completed artifact into the knowledge base: + ```bash + node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/research/{topic}.md + ``` + If the index command fails, display the error but do not block — the artifact is already saved: + > *Output the next fenced block as a code block:* + ``` + ⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. + ``` +4. Closure signpost: > *Output the next fenced block as markdown (not a code block):* @@ -18,7 +29,7 @@ > to make decisions about architecture and approach. ``` -4. Invoke the `/workflow-bridge` skill: +5. Invoke the `/workflow-bridge` skill: ``` Pipeline bridge for: {work_unit} Completed phase: research diff --git a/skills/workflow-scoping-process/SKILL.md b/skills/workflow-scoping-process/SKILL.md index e9f8e82bb..0e41d0632 100644 --- a/skills/workflow-scoping-process/SKILL.md +++ b/skills/workflow-scoping-process/SKILL.md @@ -1,7 +1,7 @@ --- name: workflow-scoping-process user-invocable: false -allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs) +allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) --- # Scoping Process diff --git a/skills/workflow-scoping-process/references/write-specification.md b/skills/workflow-scoping-process/references/write-specification.md index bf891c6fd..7fbdeb046 100644 --- a/skills/workflow-scoping-process/references/write-specification.md +++ b/skills/workflow-scoping-process/references/write-specification.md @@ -52,4 +52,20 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.speci Commit: `spec({work_unit}): quick-fix specification` +Index the completed specification into the knowledge base: + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/specification/{topic}/specification.md +``` + +If the index command fails, display the error but do not block — the artifact is already saved: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. +``` + → Return to caller. diff --git a/skills/workflow-specification-process/SKILL.md b/skills/workflow-specification-process/SKILL.md index 1684bf49d..b7ccb3d9d 100644 --- a/skills/workflow-specification-process/SKILL.md +++ b/skills/workflow-specification-process/SKILL.md @@ -1,7 +1,7 @@ --- name: workflow-specification-process user-invocable: false -allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(mkdir -p .workflows/), Bash(mv .workflows/) +allowed-tools: Bash(node .claude/skills/workflow-manifest/scripts/manifest.cjs), Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs), Bash(mkdir -p .workflows/), Bash(mv .workflows/) --- # Specification Process diff --git a/skills/workflow-specification-process/references/promote-to-cross-cutting.md b/skills/workflow-specification-process/references/promote-to-cross-cutting.md index 297ff930b..981ea4c04 100644 --- a/skills/workflow-specification-process/references/promote-to-cross-cutting.md +++ b/skills/workflow-specification-process/references/promote-to-cross-cutting.md @@ -33,6 +33,7 @@ Create the new cross-cutting work unit and mark it as completed (the pipeline is ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs init {cc_work_unit} --work-type cross-cutting --description "{one-line summary from spec}" node .claude/skills/workflow-manifest/scripts/manifest.cjs set {cc_work_unit} status completed +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {cc_work_unit} completed_at $(date +%Y-%m-%d) ``` Set provenance to track the origin: diff --git a/skills/workflow-specification-process/references/spec-completion.md b/skills/workflow-specification-process/references/spec-completion.md index 4ee749f3d..293f82931 100644 --- a/skills/workflow-specification-process/references/spec-completion.md +++ b/skills/workflow-specification-process/references/spec-completion.md @@ -132,6 +132,22 @@ Specification is complete when: Commit: `spec({work_unit}): conclude specification` +Index the completed artifact into the knowledge base: + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/specification/{topic}/specification.md +``` + +If the index command fails, display the error but do not block — the artifact is already saved: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. +``` + → Proceed to **E. Handle Source Specifications**. --- diff --git a/skills/workflow-start/references/manage-work-unit.md b/skills/workflow-start/references/manage-work-unit.md index 223fc37fa..43561a708 100644 --- a/skills/workflow-start/references/manage-work-unit.md +++ b/skills/workflow-start/references/manage-work-unit.md @@ -184,6 +184,7 @@ Set `implementation_completed` = true. ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} status completed +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} completed_at $(date +%Y-%m-%d) ``` Commit: `workflow({selected.name}): mark as completed` From 40916e508b6ed554e7d6809afcfbe2843e8b2f2e Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Thu, 16 Apr 2026 21:21:06 +0100 Subject: [PATCH 03/15] feat(knowledge): add lifecycle removal for cancellation + supersession + promotion Add knowledge remove to manage menu cancellation (removes all work unit chunks), spec supersession (removes only superseded topic's spec chunks), and spec promotion (removes promoted topic's spec chunks from original work unit). All removals are non-blocking on failure. Co-Authored-By: Claude Opus 4.6 (1M context) --- .tick/tasks.jsonl | 4 ++-- .../references/promote-to-cross-cutting.md | 16 ++++++++++++++++ .../references/spec-completion.md | 15 +++++++++++++-- .../references/manage-work-unit.md | 16 ++++++++++++++++ 4 files changed, 47 insertions(+), 4 deletions(-) diff --git a/.tick/tasks.jsonl b/.tick/tasks.jsonl index 605a294fe..adc3bf20f 100644 --- a/.tick/tasks.jsonl +++ b/.tick/tasks.jsonl @@ -21,10 +21,10 @@ {"id":"tick-8913b7","title":"Bulk Index + Retry/Pending Queue","status":"done","priority":2,"type":"task","refs":["knowledge-base-4-4"],"description":"Problem: The knowledge base needs two operational features that work together. First, a bulk indexing mode that discovers all completed artifacts and indexes any that are missing — used by knowledge setup and for manual catch-up. Second, a retry mechanism with a pending queue so that transient failures (API timeouts, rate limits, network errors) do not permanently lose files — the system self-heals on the next successful operation.\n\nSolution: Implement the no-args form of knowledge index (bulk discovery + indexing) and a single-layer retry/pending queue mechanism that wraps both single-file indexing AND query operations.\n\nOutcome: Running knowledge index with no arguments discovers and indexes all missing completed artifacts. Failures are retried with backoff, and persistently failing files are queued for catch-up on the next successful invocation. Query failures also retry before surfacing errors.\n\nDo:\n\nBULK INDEX (extend the index command from Task 3-3):\n- Invocation: knowledge index (no arguments — the presence/absence of a file argument determines single vs bulk mode)\n- Discovery algorithm (from design doc lines 479-484):\n 1. Get all work units via the manifest CLI: list all work unit names from the project manifest.\n 2. For each work unit, get completed items across indexed phases (research, discussion, investigation, specification) via manifest CLI get commands.\n 3. For each completed item, resolve the file path via manifest resolve (Task 3-2).\n 4. Check which items are already in the store — query for chunks matching each work_unit + phase + topic combination. If chunks exist, the item is already indexed.\n 5. Index the missing ones using the single-file index logic from Task 3-3.\n- Output progress as files are indexed: Indexing {file}... {N} chunks\n- Final summary: Indexed {total_new} files ({total_chunks} chunks). {skipped} already indexed.\n- Acquire file lock for the entire bulk operation (not per-file — avoids repeated lock/unlock overhead).\n\nRETRY MECHANISM (single layer — all retry lives here):\n- Implement a general-purpose retry wrapper: withRetry(fn, { maxAttempts: 3, backoff: [1000, 2000, 4000] }) -\u003e result or throw.\n- This wraps any async operation — not specific to indexing. It is used for:\n 1. Single-file index operations (update Task 3-3 to use it)\n 2. Bulk index per-file operations\n 3. Query embed operations (update Task 3-4 query command to wrap the provider.embed call)\n- The design doc specifies retry on BOTH indexing and query failures (lines 756-776). The retry wrapper is general enough for both.\n- THIS IS THE ONLY RETRY LAYER. Task 4-1's OpenAI provider does NOT retry internally — it throws on any failure (including 429 rate limits). All retry/backoff logic lives in this wrapper. This avoids retry compounding (the previous two-layer design could have produced 3 × 3 = 9 API calls for a rate-limited request).\n- The wrapper handles all transient failures uniformly: 429 (rate limit), network errors, timeouts, etc. The backoff [1s, 2s, 4s] is appropriate for rate limit recovery and transient network issues.\n- For query failures specifically (design doc lines 769-776): after 3 retries exhausted, the CLI should exit with a non-zero code and a clear error message. The skill instructions (Phase 6) handle pausing the workflow and offering the user the choice to proceed without context. The CLI just retries and then fails clearly.\n\nPENDING QUEUE:\n- Location: the pending array in .workflows/.knowledge/metadata.json (schema established in Task 1-4, initialised on first index per Task 3-3).\n- When all 3 retries are exhausted for an INDEX operation:\n - Log it to the pending queue: { file: \u003cpath\u003e, failed_at: \u003cISO timestamp\u003e, error: \u003cerror message\u003e }\n - Output a clear message: Failed to index {file} after 3 attempts: {error}. Added to pending queue.\n - Do NOT stop the bulk index — continue with remaining files.\n- The phase itself is not blocked — the artifact file is saved, just not indexed yet.\n- Query failures do NOT go to the pending queue — they are transient operations, not files to be tracked.\n\nCATCH-UP MECHANISM:\n- After a successful single-file index (knowledge index \u003cfile\u003e), process up to 5 items from the pending queue.\n- Each pending item gets its own fresh 3-retry budget (independent of previous failures).\n- Items that fail again stay in the queue for the next cycle.\n- Items that succeed are removed from the queue.\n- This provides gradual self-healing through normal workflow use without bursty API calls after long outages.\n- knowledge index (no args — bulk mode) processes the entire pending queue alongside missing files (no 5-item limit in bulk mode).\n\nAcceptance Criteria:\n- knowledge index (no args) discovers all completed artifacts across all work units\n- Already-indexed artifacts are skipped\n- Missing artifacts are indexed\n- Progress output shows each file being indexed\n- Summary output shows totals (new, skipped)\n- Retry: transient failure on first attempt succeeds on retry (for both index and query)\n- Retry: rate limit (429) from OpenAI is retried by this wrapper (provider does not retry)\n- Retry: 3 failures on index logs file to pending queue with error message\n- Retry: 3 failures on query exits with non-zero code and clear error (no pending queue entry)\n- Pending queue: failed file appears in metadata.json pending array\n- Catch-up: next successful single-file index processes up to 5 pending items\n- Catch-up: successfully caught-up items are removed from pending queue\n- Catch-up: items that fail again remain in pending queue\n- Bulk mode processes entire pending queue (no 5-item limit)\n- Single-file index from Phase 3 (Task 3-3) now uses the retry wrapper\n- Query command from Phase 3 (Task 3-4) now uses the retry wrapper for embed calls\n- No compounding retry behaviour — exactly 3 retry attempts total per operation, not 3 × 3 = 9\n\nTests:\n- Test file: tests/scripts/test-knowledge-cli.sh (extend CLI shell tests)\n- Bulk index tests:\n - it discovers and indexes all missing completed artifacts\n - it skips already-indexed artifacts\n - it reports progress and summary\n- Retry tests (may need a mock or controlled failure mechanism):\n - it retries on transient failure and succeeds\n - it retries on 429 rate limit (provider throws, wrapper catches and retries)\n - it logs to pending queue after 3 index failures\n - it exits with error after 3 query failures (no pending queue entry)\n- Catch-up tests:\n - it processes pending items after a successful single-file index\n - it removes successfully caught-up items from pending queue\n - it leaves still-failing items in pending queue\n- Test file: tests/scripts/test-knowledge-retry.cjs (Node test for retry logic unit tests)\n - it retries up to 3 times with backoff\n - it succeeds on second attempt if first fails\n - it throws after 3 failures\n - it records correct backoff delays\n - it does not compound retry attempts (exactly 3 max per operation)\n\nEdge Cases:\n- Bulk index on a project with no completed work units — 0 files to index, clean exit\n- Bulk index on a project with no .workflows/ directory — error (knowledge check should have caught this, but handle gracefully)\n- Pending queue has items from a previous provider that no longer matches config — provider mismatch detection (from Task 3-3) will refuse these. They stay in the queue until the user runs knowledge rebuild.\n- Pending queue grows very large (many failures over time) — catch-up processes 5 at a time in single-file mode, preventing bursty API usage. Bulk mode clears the entire backlog.\n- Catch-up item file no longer exists (deleted since failure) — remove from pending queue with a warning, do not error.\n- Concurrent bulk index — file lock prevents corruption. Second invocation waits or times out.\n- Persistent rate limiting — after 3 backoff attempts (1s + 2s + 4s = 7s total), the operation fails. For indexing, it goes to the pending queue for catch-up. For query, it exits with a clear error. No further API calls until the user acts.\n\nSpec Reference: knowledge-base/design.md — knowledge index no-args description (lines 639-642), Discovery algorithm (lines 479-484), Error Handling section (lines 756-795, BOTH indexing AND query failure handling, retry mechanism, pending queue, catch-up), Catch-Up Mechanism section (pending queue schema in metadata.json, 5-item limit per single-file invocation)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-12T13:19:53Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-12T13:48:37Z","auto":false}],"parent":"tick-c52ba5","created":"2026-04-08T18:04:23Z","updated":"2026-04-12T13:48:37Z","closed":"2026-04-12T13:48:37Z"} {"id":"tick-d16e06","title":"Compact Command","status":"done","priority":2,"type":"task","refs":["knowledge-base-4-5"],"description":"Problem: The knowledge base grows over the project lifetime. Old research, discussions, and investigations become less valuable as their decisions move into specs and code. Without compaction, the index grows without bound, increasing load times and memory usage. Compaction implements the memory decay model from the design doc — removing expired non-spec chunks while preserving specs forever.\n\nSolution: Implement the knowledge compact command that applies the decay TTL to remove expired chunks from completed work units.\n\nOutcome: A compact command that keeps the active index lean by removing stale non-spec chunks, with a dry-run mode for previewing what would be removed.\n\nDo:\n- Implement the compact command handler in the CLI (invoked by Task 3-1 dispatch).\n- Invocation: knowledge compact [--dry-run]\n\nDECAY RULES (from design doc lines 833-840):\n- In-progress work units: ALL chunks kept regardless of age. No completed_at date means nothing can expire.\n- Completed work units: specification chunks kept FOREVER (never compacted). Research, discussion, and investigation chunks removed when completed_at + decay_months \u003c= now (inclusive).\n- Cancelled work units: should already be removed by the remove command during cancellation (Phase 5). But if any remain, compact should not touch them — cancellation removal is a separate lifecycle action.\n- decay_months comes from the merged config (Task 3-1). Default is 6. Set to false to disable compaction entirely (keep everything). Set to 0 for immediate expiry of non-spec chunks.\n\nMANIFEST ACCESS PATTERN:\n- The compact command reads work unit status and completed_at from the manifest. It MUST use the manifest CLI (manifest.cjs) for this — do NOT read .workflows/{work_unit}/manifest.json directly.\n- Rationale: the manifest CLI is the single source of truth for manifest state (per CLAUDE.md). Direct file reads would duplicate path conventions and bypass validation. The manifest CLI precedent is established in Task 3-2 (resolve command used by Task 4-4 bulk index) and Task 5-2 (manifest.cjs set for completed_at writes).\n- Specifically: shell out to the manifest CLI using get commands of the form: node .claude/skills/workflow-manifest/scripts/manifest.cjs get WORK_UNIT status, and similarly for completed_at. Collect both values in one manifest read where possible, or cache per-work_unit to avoid repeated shells.\n- Shelling out has a small cost per work unit; with compacted scale (500-2K chunks, 10-50 work units), this is negligible.\n\nALGORITHM:\n1. Load the store from disk.\n2. Read decay_months from config. If false, output Compaction disabled and exit.\n3. Calculate the cutoff date: now minus decay_months.\n4. For each unique work_unit in the store:\n a. Shell out to manifest.cjs to get the work unit status and completed_at fields.\n b. If status is not completed, skip (in-progress work units are exempt).\n c. If completed_at is absent, skip (cannot calculate expiry — the migration from Task 4-2 should have set this, but be defensive).\n d. If completed_at is after the cutoff date, skip (not yet expired).\n e. If expired: find all chunks for this work unit where phase is NOT specification. These are the candidates for removal. Track which phases contributed chunks for each work unit (needed for the output summary).\n5. If --dry-run: output what would be removed without removing. Exit.\n6. Otherwise: remove the candidate chunks. Save the store. Update metadata.json.\n\nOUTPUT (from design doc lines 863-869):\n- When chunks are removed:\n Compacted: removed N chunks from M work units (completed \u003e decay_months months ago)\n - work_unit: n chunks (research, discussion)\n - work_unit: n chunks (investigation)\n- The phase list in parentheses is the unique set of phases that had chunks removed for that work unit (accumulated during step 4e).\n- When nothing expires: no output (silent skip).\n- Dry-run: same format but prefixed with [dry-run] and no actual removal.\n\n- Acquire file lock during write (not during dry-run — dry-run is read-only).\n- Rebuild after implementation: npm run build.\n\nAcceptance Criteria:\n- Compact uses manifest.cjs (not direct manifest.json reads) to look up status and completed_at\n- Compact removes non-spec chunks from work units completed more than decay_months ago\n- Spec chunks are NEVER removed regardless of age\n- In-progress work unit chunks are never removed\n- Chunks from work units completed within the TTL window are kept\n- --dry-run shows what would be removed without removing\n- decay_months: false disables compaction entirely\n- decay_months: 0 expires all non-spec chunks from completed work units immediately\n- Missing completed_at on a completed work unit is handled gracefully (skip with no error)\n- Output format matches the design doc summary style with phase accumulation per work unit\n- Nothing to compact: silent exit (no output)\n- Store is saved after removal\n- File lock acquired during write, not during dry-run\n\nTests:\n- Test file: tests/scripts/test-knowledge-cli.sh (extend CLI shell tests)\n- Setup: index fixtures across multiple work units with different completion dates. Set some as completed with old completed_at values, others recent, others in-progress. Use manifest.cjs set to populate status and completed_at.\n- it removes expired non-spec chunks from old completed work units\n- it preserves spec chunks from expired work units\n- it preserves all chunks from in-progress work units\n- it preserves all chunks from recently completed work units (within TTL)\n- it shows removal plan in --dry-run without removing\n- it handles decay_months: false (compaction disabled)\n- it handles decay_months: 0 (immediate expiry)\n- it handles missing completed_at gracefully\n- it outputs summary in correct format with phase breakdown\n- it produces no output when nothing to compact\n- it uses manifest.cjs for status/completed_at lookups (can be verified by test setup using manifest.cjs set)\n\nEdge Cases:\n- Work unit completed exactly at the cutoff boundary — inclusive per design doc line 837: completed_at + decay_months \u003c= now means expired.\n- Config has no decay_months field — use default (6).\n- Store has chunks from a work unit that no longer has a manifest (work unit directory deleted manually) — manifest.cjs get will fail; catch the error and skip with no error. The status command (Task 4-6) reports these as orphans.\n- All chunks for a work unit are specs — nothing to remove, work unit not mentioned in summary.\n- Compact runs but store has no chunks at all — silent exit.\n- Multiple work units sharing the same cutoff — each is processed independently.\n\nSpec Reference: knowledge-base/design.md — Memory Decay and Compaction section (lines 808-898, decay model table, compaction rules, output format, configuration), and the compaction trigger description (lines 847-855, Step 0 sequence in skills). Manifest CLI precedent established in Task 3-2 (resolve) and Task 5-2 (set completed_at).","transitions":[{"from":"open","to":"in_progress","at":"2026-04-12T13:48:55Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-12T13:56:13Z","auto":false}],"parent":"tick-c52ba5","created":"2026-04-08T18:04:57Z","updated":"2026-04-12T13:56:13Z","closed":"2026-04-12T13:56:13Z"} {"id":"tick-097bf0","title":"Status + Rebuild + Batch Queries + Phase 4 CLI Tests","status":"done","priority":2,"type":"task","refs":["knowledge-base-4-6"],"description":"Problem: Three remaining CLI features need implementation: status (health reporting for debugging), rebuild (destructive reindex for provider changes), and batch queries (multiple search terms in one invocation). These are all Phase 4 completeness items — the knowledge base is functional without them but they round out the CLI for production use.\n\nSolution: Implement the status, rebuild, and batch query features, plus a comprehensive CLI test suite covering all Phase 4 commands.\n\nOutcome: A complete CLI with all 8 commands implemented, plus tests validating everything works against the built bundle.\n\nDo:\n\nSTATUS COMMAND (from design doc lines 680-688 + review findings 11-13):\n- Invocation: knowledge status (no arguments)\n- Full health report — not used in skill automation, intended for user/debugging.\n- Report sections:\n 1. Index summary: total chunk count, broken down by work unit, phase, and work type.\n 2. Last indexed: timestamp of most recent indexing operation (from metadata.json last_indexed).\n 3. Store health: store file size on disk, provider name + model + dimensions from metadata.json.\n 4. Pending items: count and list from metadata.json pending array. Show file path and failure reason for each.\n 5. Mode indicator: Full (hybrid search) or Keyword-only (stub mode) based on whether a provider is configured.\n 6. Provider mismatch warning: if metadata.json provider/model/dimensions differs from current config, warn: Config has changed since last index. Run knowledge rebuild to reindex.\n 7. Orphan detection (finding #11): chunks in the store whose source_file no longer exists on disk. Report count and list.\n 8. Unindexed artifacts (finding #11): completed artifacts found via manifest that are not in the store. Report count and list. Uses the same discovery logic as bulk index (Task 4-4) but only reports, does not index.\n 9. Manifest-knowledge consistency (finding #12): cross-reference manifest state against store contents. Report:\n - Superseded specs still indexed: specs whose manifest status is superseded but chunks still exist in the store (should have been removed by the supersession action in Phase 5).\n - Promoted specs not relocated: specs whose manifest status is promoted but chunks still exist under the original work unit (should have been removed and re-indexed under the new cross-cutting work unit).\n - Cancelled work units still present: chunks for work units whose manifest status is cancelled (should have been removed by the cancellation action in Phase 5).\n These are consistency warnings — the processing skills handle the operations, status catches failures.\n 10. Stub-to-full upgrade note (finding #13): if config has a provider with API key but store was built in keyword-only mode, note: Keyword-only mode but embedding provider configured. Run knowledge rebuild for full hybrid search.\n- Output is plain text, human-readable. Not JSON, not machine-parsed.\n- Read-only — no file lock needed, no store modifications.\n\nREBUILD COMMAND (from design doc lines 644-649):\n- Invocation: knowledge rebuild\n- Destructive reindex from current artifacts. Drops existing index, re-chunks and re-embeds everything.\n- HUMAN-ONLY — uses interactive confirmation prompts via process.stdin. Use a type-the-action-word pattern (like Terraform destroy or GitHub repo delete) rather than yes/no — it forces engagement with what is being done:\n Warning: This will delete the existing index and rebuild from scratch.\n This is non-deterministic — the rebuilt index will differ from the original.\n Type 'rebuild' to confirm:\n- If confirmation does not match the word exactly, abort.\n- If confirmed: delete store.msp, delete metadata.json, then run bulk index logic from Task 4-4 (knowledge index no-args internally).\n- Claude cannot handle interactive terminals — this is the natural protection against accidental invocation.\n\nBATCH QUERIES (extend the query command from Task 3-4):\n- Invocation: knowledge query \u003cterm1\u003e \u003cterm2\u003e [\u003ctermN\u003e...] [--flags]\n- Multiple positional arguments = multiple search terms.\n- Implementation (from design doc line 602-603):\n 1. Load the store once.\n 2. Run a separate search for each term (embed + search + re-rank).\n 3. Merge all result sets.\n 4. Deduplicate by chunk ID — if the same chunk appears in multiple result sets, keep the highest score.\n 5. Sort merged results by score (descending).\n 6. Apply --limit to the merged set (not per-query).\n 7. Format output as normal (same provenance format from Task 3-4).\n- This is efficient: one store load, multiple searches, one formatted output.\n\nSTUB-TO-FULL UPGRADE NOTE ON QUERY OUTPUT (finding #13, line 992):\n- When the store was built in keyword-only mode but the current config has a provider with API key configured, prepend a one-line upgrade note to the query output (before the result count header):\n [keyword-only mode but embedding provider configured — run knowledge rebuild for full hybrid search]\n- This is separate from the existing stub mode note (which appears when NO provider is configured). The stub-to-full note specifically flags the upgrade opportunity when a provider HAS been configured but the store has not been rebuilt yet.\n- Applies to both single and batch query invocations.\n- Detection: compare metadata.json (what the store was built with) against the current resolved config (what the system is configured for now). If current config has a provider + API key but metadata.json indicates keyword-only, show the note.\n- Design doc rationale: this surfaces the upgrade opportunity naturally during workflow use, not just on manual status checks.\n\nPHASE 4 CLI TESTS:\n- Test file: tests/scripts/test-knowledge-cli.sh (extend with Phase 4 command tests)\n- Status tests:\n - it reports chunk counts by work unit and phase\n - it reports store size and provider info\n - it reports pending queue items\n - it warns about provider mismatch\n - it detects orphaned chunks (source file deleted)\n - it detects unindexed completed artifacts\n - it reports superseded specs still indexed\n - it reports cancelled work units still present\n - it reports keyword-only mode when no provider\n - it reports stub-to-full upgrade note when provider available but store is keyword-only\n- Rebuild tests:\n - it prompts for confirmation (test by piping non-matching input — should abort)\n - it aborts when confirmation does not match the word rebuild\n - (full rebuild is hard to test non-interactively — test the abort path, note the confirm path for manual testing)\n- Batch query tests:\n - it returns merged results from multiple search terms\n - it deduplicates chunks appearing in multiple result sets (keeps highest score)\n - it applies --limit to the merged set\n - it handles batch where one term has results and another does not\n- Stub-to-full query note tests:\n - it shows the upgrade note on query output when config has provider but store is keyword-only\n - it does NOT show the upgrade note when store and config match\n - it does NOT show the upgrade note in pure stub mode (no provider configured)\n\nAcceptance Criteria:\n- knowledge status outputs a comprehensive health report with all 10 sections\n- Status correctly detects orphaned chunks and unindexed artifacts\n- Status correctly warns about provider mismatch\n- Status correctly reports superseded specs still indexed, cancelled work units still present (manifest-knowledge consistency)\n- knowledge rebuild prompts with type-the-word confirmation and aborts on mismatch\n- knowledge rebuild (when confirmed manually) deletes and recreates the index\n- Batch query merges and deduplicates results from multiple terms\n- Batch query applies limit to the merged result set\n- Stub-to-full upgrade note appears on knowledge query output when applicable\n- All Phase 4 CLI tests pass\n\nEdge Cases:\n- Status on empty store — reports 0 chunks, no orphans, may report unindexed artifacts\n- Status when metadata.json is missing — report what is available, note missing metadata\n- Status when no manifest exists (no .workflows/) — report error for manifest-dependent checks, still report store-only metrics\n- Rebuild when store does not exist — nothing to delete, proceed with bulk index\n- Batch query with duplicate terms (same term twice) — should work, deduplication handles it\n- Batch query with one term that matches nothing — merged results only contain results from the other term(s)\n- Rebuild in non-interactive environment (piped stdin) — read from stdin for the type-the-word confirmation. If stdin is not a TTY and no input is provided, abort (do not hang).\n- Manifest-knowledge consistency when manifest has been updated but skills have not run yet (e.g., spec manually marked superseded) — status reports the inconsistency, user runs knowledge remove manually\n- Stub-to-full note on query output during a store just transitioned — user ran setup with a new provider but has not rebuilt yet. Note appears until rebuild.\n\nSpec Reference: knowledge-base/design.md — knowledge status command (lines 680-688), knowledge rebuild command (lines 644-649), batch query description (line 602-603), Index-artifact drift detection review finding #11 (line 985), Manifest-knowledge consistency review finding #12 (line 988, superseded/promoted/cancelled checks), Stub-to-full upgrade detection review finding #13 (line 991-992, including the note on query output)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-12T13:56:31Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-12T13:59:57Z","auto":false}],"parent":"tick-c52ba5","created":"2026-04-08T18:05:40Z","updated":"2026-04-12T13:59:57Z","closed":"2026-04-12T13:59:57Z"} -{"id":"tick-77697a","title":"Phase 5: Skill Integration","status":"in_progress","priority":2,"refs":["knowledge-base-5"],"transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:07:42Z","auto":true}],"parent":"tick-cbbd13","created":"2026-04-08T18:22:03Z","updated":"2026-04-16T20:07:42Z"} +{"id":"tick-77697a","title":"Phase 5: Skill Integration","status":"done","priority":2,"refs":["knowledge-base-5"],"transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:07:42Z","auto":true},{"from":"in_progress","to":"done","at":"2026-04-16T20:20:59Z","auto":true}],"parent":"tick-cbbd13","created":"2026-04-08T18:22:03Z","updated":"2026-04-16T20:20:59Z","closed":"2026-04-16T20:20:59Z"} {"id":"tick-7d74fe","title":"Hard Stop Reference + Step 0 Integration","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-1"],"description":"Problem: Entry-point skills need to gate on knowledge base readiness before proceeding. Without this gate, skills would attempt to query or index against a non-existent knowledge base. The design doc makes the knowledge base required infrastructure — no graceful degradation, just a clear hard stop with setup instructions.\n\nSolution: Create a hard stop reference file and update Step 0 in all 11 entry-point skills to run knowledge check after migrations, display the hard stop if not ready, and run knowledge compact if ready.\n\nOutcome: Every workflow invocation checks knowledge base readiness before proceeding, with a clear user-facing message when setup is needed, and automatic compaction keeping the index lean.\n\nDo:\n\nHARD STOP REFERENCE FILE:\n- Create skills/workflow-shared/references/knowledge-not-ready.md (or similar shared location — check where other shared references live).\n- This file is loaded and displayed when knowledge check returns not-ready.\n- Content should follow the existing hard stop / terminal condition conventions from CLAUDE.md:\n - Phase title box explaining what happened\n - Signpost blockquote explaining why the knowledge base is needed\n - Clear instruction: run knowledge setup to initialise\n - The exact command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs setup\n - Brief explanation of what setup does (system config, project init, initial indexing)\n - Mention stub mode is available if no API key\n - Terminal stop — do not proceed\n- Follow the display conventions from CLAUDE.md: phase title (bullet-bordered box), signpost blockquote, rendering instructions.\n\nSTEP 0 CHANGES:\n- Update Step 0 in ALL 11 entry-point skills. The affected files:\n skills/start-feature/SKILL.md\n skills/start-epic/SKILL.md\n skills/start-bugfix/SKILL.md\n skills/start-quickfix/SKILL.md\n skills/start-cross-cutting/SKILL.md\n skills/continue-feature/SKILL.md\n skills/continue-epic/SKILL.md\n skills/continue-bugfix/SKILL.md\n skills/continue-quickfix/SKILL.md\n skills/continue-cross-cutting/SKILL.md\n skills/workflow-start/SKILL.md\n\n- The Step 0 sequence after this change:\n 1. Migrations (existing — preserve as-is)\n 2. Knowledge check: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs check and capture stdout.\n - If stdout is not-ready: load the hard stop reference file and follow its instructions. STOP — do not proceed.\n - If stdout is ready: proceed.\n 3. Knowledge compact: run node .claude/skills/workflow-knowledge/scripts/knowledge.cjs compact (no flags — not dry-run). This is silent when nothing to compact. Output only appears if chunks were removed.\n\n- The existing Step 0 structure varies between start-* and continue-* skills:\n - start-* skills CHECK if /workflow-migrate has been invoked (they expect it was already run)\n - continue-* and workflow-start ACTIVELY run migrations if not done\n The knowledge check + compact goes AFTER the migration handling in both cases. Read each skill's Step 0 to understand its current structure before modifying.\n\n- Each skill's Step 0 will need its own rendering instruction for the check result / compact output if applicable. Follow the existing conventions in each skill.\n\nALLOWED-TOOLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to the allowed-tools frontmatter of all 11 entry-point skills.\n- This follows the same pattern as the manifest CLI allowed-tools entries already in these files. Check one skill first to see the exact format.\n\nAcceptance Criteria:\n- Hard stop reference file exists and follows display conventions\n- All 11 entry-point skills have knowledge check in Step 0 after migrations\n- knowledge check returning not-ready loads the hard stop reference and stops\n- knowledge check returning ready proceeds normally\n- All 11 entry-point skills run knowledge compact after successful check\n- Compact output is visible when chunks are removed, silent when nothing to compact\n- allowed-tools frontmatter updated in all 11 entry-point skills\n- Existing migration handling in Step 0 is preserved and unmodified\n- The Step 0 ordering is: migrations -\u003e knowledge check -\u003e knowledge compact\n\nTests:\n- No automated tests for this task — it is a skill file editing task. Validation is manual:\n - Invoke a start-* skill with no knowledge base set up -\u003e verify hard stop appears\n - Invoke a continue-* skill with knowledge base set up -\u003e verify check passes and compact runs\n - Verify allowed-tools entries are present in all 11 files\n\nEdge Cases:\n- knowledge check fails with a genuine error (not not-ready, but a crash) — the skill should surface the error, not silently proceed. Check exit code: 0 is expected (ready or not-ready on stdout). Non-zero means something broke.\n- knowledge compact fails (e.g., store locked) — should surface the error but not hard-stop the workflow. Compaction failure is a warning, not a blocker. The knowledge base still works, just with stale chunks.\n- Existing Step 0 in start-* skills only checks if migrations were invoked — adding knowledge steps must not change this conditional structure. The check and compact are unconditional additions after the migration section.\n\nSpec Reference: knowledge-base/design.md — Knowledge Base is Required Infrastructure section (lines 304-320, setup flow, hard stop), Compaction Trigger section (lines 847-855, Step 0 sequence: migrations -\u003e check -\u003e compact), allowed-tools frontmatter changes (lines 728-733)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:07:42Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:14:06Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T08:19:17Z","updated":"2026-04-16T20:14:06Z","closed":"2026-04-16T20:14:06Z"} {"id":"tick-055556","title":"Phase Completion Indexing","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-2"],"description":"Problem: The knowledge base needs to grow automatically as workflow phases complete. Without automatic indexing at phase completion, users would need to manually run knowledge index after every discussion, research session, investigation, or specification — which would never happen consistently.\n\nSolution: Add knowledge index \u003cfile\u003e calls at the phase completion points in processing skills for all indexed phases, plus scoping (which produces a spec). Also audit the skills/ directory for every place that transitions a work unit to status: completed and add completed_at alongside each one.\n\nOutcome: Every completed workflow artifact is automatically indexed into the knowledge base, and every work unit completion path sets completed_at for the compact command's TTL calculation.\n\nDo:\n- Add knowledge index \u003cfile\u003e at the phase completion step in each of these processing skills:\n\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-specification-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n\n- For each skill, find the step where the phase artifact is finalised and committed. The index call goes AFTER the artifact is saved to disk and committed, but BEFORE any phase transition or handoff to the next phase. The artifact must exist on disk before indexing.\n\n- The index call pattern:\n Run: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index \u003cartifact_path\u003e\n Where \u003cartifact_path\u003e is the path to the completed artifact file. Each phase has a different path convention:\n - Research: .workflows/{work_unit}/research/{topic}.md (may vary — use the actual file that was just written)\n - Discussion: .workflows/{work_unit}/discussion/{topic}.md\n - Investigation: .workflows/{work_unit}/investigation/{topic}.md\n - Specification: .workflows/{work_unit}/specification/{topic}/specification.md\n - Scoping: produces a specification — index the spec file it creates, NOT a scoping artifact (scoping is not an indexed phase per design doc)\n\n- The index call should reference the actual file path variable/value used in the skill, not a hardcoded path. Read each skill to understand how it references the artifact file.\n\n- FAILURE HANDLING: indexing failure must NOT block the phase. The artifact is already saved. If knowledge index fails, output the error message (which includes retry-failed + pending queue info from Task 4-4) and continue with the phase transition. The design doc is explicit: the phase itself is not blocked — the artifact is saved. But the failure is made visible, not silently swallowed.\n\n- MULTIPLE INDEXED ARTIFACTS: some skills may complete multiple artifacts. For example, scoping produces both a specification and potentially sets up planning. Only the spec needs indexing. Each index call is independent — a failure on one does not block the other (per design doc line 707).\n\nCOMPLETED_AT AUDIT (concrete instruction, not judgement call):\n- The completed_at field (added by the migration in Task 4-2) needs to be set going forward whenever ANY code path transitions a work unit to status: completed. Missing a path means the work unit will never expire under compaction (Task 4-5 handles missing completed_at defensively, but the result is silent non-compaction).\n- AUDIT STEP: grep the skills/ directory for every place that sets status to completed. Suggested grep patterns:\n grep -rn 'status.*completed' skills/\n grep -rn 'manifest.cjs set.*status.*completed' skills/\n grep -rn 'completed' skills/ | grep -i status\n- For EACH match, add a manifest.cjs set {work_unit} completed_at {current_date_ISO} call alongside the status-setting call. Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n- Known locations (verified to exist — the grep is still the authoritative source, but these are the high-traffic files):\n - skills/workflow-bridge/references/ — 5 continuation files set status: completed (bugfix-continuation.md, feature-continuation.md, epic-continuation.md, cross-cutting-continuation.md, quickfix-continuation.md). Bridge is where most feature/bugfix/quickfix completions happen — do not miss these.\n - The 5 processing skills listed above (research, discussion, investigation, specification, scoping) — conclude-*.md references\n - skills/workflow-review-process/references/review-actions-loop.md — review is often the last phase and may mark the work unit completed\n - skills/workflow-implementation-process/references/conclude-implementation.md — implementation completion\n - skills/workflow-specification-process/references/spec-completion.md and promote-to-cross-cutting.md — specification lifecycle\n - skills/workflow-scoping-process/references/write-tasks.md and write-specification.md — scoping completion paths\n - skills/workflow-start/references/manage-work-unit.md — the manage menu done action, covered by Task 5-3\n- DO NOT rely on the list above being exhaustive. The grep is the authoritative source of truth. Add completed_at setting wherever the grep finds status: completed being set, even if the file is not in the list above.\n- Report the full list of files modified (for review) when completing this task.\n- Acceptance post-condition: after editing, grep -rn 'status.*completed' skills/ should show every match adjacent (same step or reference block) to a corresponding completed_at set. This is a mechanical check the implementer can run to self-verify coverage.\n\n- Add allowed-tools for knowledge.cjs to these 5 processing skills (if not already added by Task 5-1 or Task 5-3).\n\nAcceptance Criteria:\n- Research process skill indexes the research artifact on completion\n- Discussion process skill indexes the discussion artifact on completion\n- Investigation process skill indexes the investigation artifact on completion\n- Specification process skill indexes the specification artifact on completion\n- Scoping process skill indexes the spec it produces on completion\n- Index failure does not block the phase — error is displayed, phase continues\n- Every place in skills/ that sets status: completed also sets completed_at (verified via grep audit)\n- All 5 bridge continuation files are updated (bugfix, feature, epic, cross-cutting, quickfix)\n- The list of files modified for completed_at is documented in the task completion report\n- Post-condition grep shows every status: completed match adjacent to a completed_at set\n- allowed-tools updated in all 5 processing skills\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Complete a discussion in a test project -\u003e verify chunks appear in knowledge base (knowledge status shows them)\n - Complete a specification -\u003e verify chunks appear\n - Simulate index failure (e.g., corrupt store) -\u003e verify phase still completes, error is shown\n - Grep skills/ after task completion: every status-completed line should have a neighbouring completed_at line\n\nEdge Cases:\n- Scoping produces a spec but scoping itself is not an indexed phase — only the spec output is indexed. The index call must reference the spec file path, not a scoping artifact path.\n- Research in epics can produce multiple files — each file may need separate indexing. Check how the research process skill handles multiple outputs. If it produces one file per research topic, each gets its own index call.\n- completed_at audit finds a skill that doesn't import the manifest CLI — check the skill's allowed-tools and add if needed\n- Phase completion with no artifact file (edge case — should not happen in normal flow) — knowledge index will error on missing file, which is correct and visible.\n- A skill sets status: completed on a DIFFERENT work unit than its own (e.g., the manage menu) — this is covered by Task 5-3 for the manage menu specifically.\n- Bridge continuation files may set completed on a SOURCE work unit when transitioning (e.g., a feature completion closing out the feature before bridging to the next). Ensure completed_at is set on the same work unit whose status is being set.\n\nSpec Reference: knowledge-base/design.md — Indexing section (lines 337-341, primary trigger is phase completion, not mid-phase), Integration with Workflow Skills section (lines 707-708, indexing at phase completion, independent per artifact, failure does not block), completed_at field (line 824-829, set explicitly by skill at completion time going forward, the manage menu done action and any skill that sets status: completed must also set completed_at)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:14:29Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:19:31Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T17:54:59Z","updated":"2026-04-16T20:19:31Z","closed":"2026-04-16T20:19:31Z"} -{"id":"tick-f84af0","title":"Lifecycle Removal (Cancellation + Supersession/Promotion)","status":"open","priority":2,"type":"task","refs":["knowledge-base-5-3"],"description":"Problem: When work units are cancelled or specs are superseded/promoted, their chunks must be removed from the knowledge base. Without this, stale and contradictory information pollutes search results. Additionally, the manage menu's done action needs to set completed_at for compaction TTL calculation.\n\nSolution: Add knowledge remove calls to the manage menu reference (cancellation) and specification process (supersession/promotion) skills. Add completed_at setting to the manage menu's done action.\n\nOutcome: Work unit cancellation and spec lifecycle changes automatically clean the knowledge base, and completed work units have the timestamp needed for decay compaction.\n\nDo:\n\nCANCELLATION REMOVAL (manage menu reference):\n- The manage menu lives inside the workflow-start skill at skills/workflow-start/references/manage-work-unit.md (NOT a separate workflow-manage skill — verified).\n- Locate the cancellation action in that file (where status is set to cancelled).\n- Add inline: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit}\n- This runs INLINE as part of the cancellation action — no prompt, cancelling means done with it (design doc line 801).\n- If removal fails (store locked, CLI error): log the error visibly but do not block the cancellation. The pending queue is designed for indexing failures, not removal failures. If removal fails, output the error and note that the user can run knowledge remove manually.\n- NO frontmatter edit is needed here — skills/workflow-start is an entry-point skill that already receives allowed-tools for knowledge.cjs in Task 5-1. The reference file inherits from its parent skill.\n\nCOMPLETED_AT ON DONE ACTION (manage menu reference):\n- Locate the done/completion action in skills/workflow-start/references/manage-work-unit.md (where status is set to completed).\n- Add: manifest.cjs set {work_unit} completed_at {current_date_ISO}\n- The completed_at field is what compaction (Task 4-5) uses to calculate decay TTL. Without it, completed work units cannot expire and the index grows without bound.\n- This complements Task 5-2 which adds completed_at in processing skills and bridge continuations where completion happens automatically. The manage menu is where users manually mark work units as done — both paths must set the field.\n- Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n\nSUPERSESSION REMOVAL (specification process skill):\n- Find the specification process skill: skills/workflow-specification-process/SKILL.md\n- Locate the supersession action — where a spec's manifest status changes to superseded.\n- Add: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- This removes ONLY the superseded topic's spec chunks. Other topics in the same work unit (e.g., other specs in an epic) are unaffected. Granularity matters (design doc line 656).\n- The specification process skill already has allowed-tools for knowledge.cjs from Task 5-2 (for indexing). No additional frontmatter change needed.\n\nPROMOTION REMOVAL (specification process skill):\n- Locate the promotion action — where a spec's manifest status changes to promoted.\n- Add the same remove command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- Promotion is a RELOCATION, not a deletion (design doc line 535). The chunks are removed from the original work unit. The new cross-cutting spec will be indexed naturally when it completes in the new work unit. There is a timing gap where the content is absent from the knowledge base — this is accepted per design doc line 537.\n- Research, discussion, and investigation chunks from the original work unit are KEPT — only the spec chunks are removed (design doc line 539).\n\nALLOWED-TOOLS SUMMARY FOR PHASE 5:\n- Task 5-1 adds to 11 entry-point skills (for check + compact). workflow-start is one of them, which covers the manage-work-unit.md reference file used by this task.\n- Task 5-2 adds to 5 indexed phase processing skills (for index), and updates bridge continuation files.\n- This task adds NO new allowed-tools entries — all target files are covered by Tasks 5-1 or 5-2.\n- Total Phase 5 allowed-tools changes: 16 skills (11 from 5-1 + 5 from 5-2).\n- The 3 non-indexed processing skills (planning, implementation, review) get allowed-tools in Phase 6 Task 6-2 when autonomous querying is added — no Phase 5 reason to add them now.\n- Phase entry skills (workflow-*-entry) do NOT get allowed-tools in Phase 5. The one exception is workflow-planning-entry, which gets allowed-tools in Phase 6 Task 6-3 specifically for the cross-cutting query. No other phase entry skill needs it.\n\nAcceptance Criteria:\n- Cancelling a work unit via manage menu removes its chunks from the knowledge base\n- Cancellation removal failure does not block the cancellation action\n- Manage menu done action sets completed_at on the work unit manifest\n- Superseding a spec removes only that topic's spec chunks\n- Promoting a spec removes only that topic's spec chunks from the original work unit\n- Research/discussion/investigation chunks from the same work unit survive supersession and promotion\n- No new allowed-tools frontmatter edits in this task (covered by Task 5-1 for workflow-start, Task 5-2 for specification-process)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Cancel a work unit that has indexed chunks -\u003e verify chunks are removed (knowledge status)\n - Mark a work unit as done via manage menu -\u003e verify completed_at is set in manifest\n - Supersede a spec topic in an epic -\u003e verify only that topic's spec chunks are removed, other topics and non-spec phases survive\n\nEdge Cases:\n- Cancellation of a work unit that was never indexed — knowledge remove returns 0 removed, no error. The cancellation flow should not treat this as a failure.\n- Supersession of a spec that was never indexed — same, 0 removed, no error.\n- Promotion timing gap — between removing original spec chunks and the new cross-cutting spec completing, the content is absent from the knowledge base. This is accepted per design doc.\n- Epic with multiple spec topics — superseding one MUST NOT remove others. The --topic flag ensures granularity.\n- Done action on a work unit that already has completed_at — overwrite with current date (the user is explicitly marking it done now, regardless of previous state).\n\nSpec Reference: knowledge-base/design.md — Work Unit Lifecycle section (lines 799-801, cancelled work units auto-removed, failure handling), Staleness and Supersession section (lines 530-539, superseded removed, promoted relocated, research/discussion/investigation kept), completed_at prerequisite (line 824, manage menu done action must set it), allowed-tools frontmatter changes (lines 728-733)","parent":"tick-77697a","created":"2026-04-09T17:58:53Z","updated":"2026-04-10T19:57:48Z"} +{"id":"tick-f84af0","title":"Lifecycle Removal (Cancellation + Supersession/Promotion)","status":"done","priority":2,"type":"task","refs":["knowledge-base-5-3"],"description":"Problem: When work units are cancelled or specs are superseded/promoted, their chunks must be removed from the knowledge base. Without this, stale and contradictory information pollutes search results. Additionally, the manage menu's done action needs to set completed_at for compaction TTL calculation.\n\nSolution: Add knowledge remove calls to the manage menu reference (cancellation) and specification process (supersession/promotion) skills. Add completed_at setting to the manage menu's done action.\n\nOutcome: Work unit cancellation and spec lifecycle changes automatically clean the knowledge base, and completed work units have the timestamp needed for decay compaction.\n\nDo:\n\nCANCELLATION REMOVAL (manage menu reference):\n- The manage menu lives inside the workflow-start skill at skills/workflow-start/references/manage-work-unit.md (NOT a separate workflow-manage skill — verified).\n- Locate the cancellation action in that file (where status is set to cancelled).\n- Add inline: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit}\n- This runs INLINE as part of the cancellation action — no prompt, cancelling means done with it (design doc line 801).\n- If removal fails (store locked, CLI error): log the error visibly but do not block the cancellation. The pending queue is designed for indexing failures, not removal failures. If removal fails, output the error and note that the user can run knowledge remove manually.\n- NO frontmatter edit is needed here — skills/workflow-start is an entry-point skill that already receives allowed-tools for knowledge.cjs in Task 5-1. The reference file inherits from its parent skill.\n\nCOMPLETED_AT ON DONE ACTION (manage menu reference):\n- Locate the done/completion action in skills/workflow-start/references/manage-work-unit.md (where status is set to completed).\n- Add: manifest.cjs set {work_unit} completed_at {current_date_ISO}\n- The completed_at field is what compaction (Task 4-5) uses to calculate decay TTL. Without it, completed work units cannot expire and the index grows without bound.\n- This complements Task 5-2 which adds completed_at in processing skills and bridge continuations where completion happens automatically. The manage menu is where users manually mark work units as done — both paths must set the field.\n- Format: YYYY-MM-DD (ISO date, same as the migration backfill in Task 4-2).\n\nSUPERSESSION REMOVAL (specification process skill):\n- Find the specification process skill: skills/workflow-specification-process/SKILL.md\n- Locate the supersession action — where a spec's manifest status changes to superseded.\n- Add: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- This removes ONLY the superseded topic's spec chunks. Other topics in the same work unit (e.g., other specs in an epic) are unaffected. Granularity matters (design doc line 656).\n- The specification process skill already has allowed-tools for knowledge.cjs from Task 5-2 (for indexing). No additional frontmatter change needed.\n\nPROMOTION REMOVAL (specification process skill):\n- Locate the promotion action — where a spec's manifest status changes to promoted.\n- Add the same remove command: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}\n- Promotion is a RELOCATION, not a deletion (design doc line 535). The chunks are removed from the original work unit. The new cross-cutting spec will be indexed naturally when it completes in the new work unit. There is a timing gap where the content is absent from the knowledge base — this is accepted per design doc line 537.\n- Research, discussion, and investigation chunks from the original work unit are KEPT — only the spec chunks are removed (design doc line 539).\n\nALLOWED-TOOLS SUMMARY FOR PHASE 5:\n- Task 5-1 adds to 11 entry-point skills (for check + compact). workflow-start is one of them, which covers the manage-work-unit.md reference file used by this task.\n- Task 5-2 adds to 5 indexed phase processing skills (for index), and updates bridge continuation files.\n- This task adds NO new allowed-tools entries — all target files are covered by Tasks 5-1 or 5-2.\n- Total Phase 5 allowed-tools changes: 16 skills (11 from 5-1 + 5 from 5-2).\n- The 3 non-indexed processing skills (planning, implementation, review) get allowed-tools in Phase 6 Task 6-2 when autonomous querying is added — no Phase 5 reason to add them now.\n- Phase entry skills (workflow-*-entry) do NOT get allowed-tools in Phase 5. The one exception is workflow-planning-entry, which gets allowed-tools in Phase 6 Task 6-3 specifically for the cross-cutting query. No other phase entry skill needs it.\n\nAcceptance Criteria:\n- Cancelling a work unit via manage menu removes its chunks from the knowledge base\n- Cancellation removal failure does not block the cancellation action\n- Manage menu done action sets completed_at on the work unit manifest\n- Superseding a spec removes only that topic's spec chunks\n- Promoting a spec removes only that topic's spec chunks from the original work unit\n- Research/discussion/investigation chunks from the same work unit survive supersession and promotion\n- No new allowed-tools frontmatter edits in this task (covered by Task 5-1 for workflow-start, Task 5-2 for specification-process)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Cancel a work unit that has indexed chunks -\u003e verify chunks are removed (knowledge status)\n - Mark a work unit as done via manage menu -\u003e verify completed_at is set in manifest\n - Supersede a spec topic in an epic -\u003e verify only that topic's spec chunks are removed, other topics and non-spec phases survive\n\nEdge Cases:\n- Cancellation of a work unit that was never indexed — knowledge remove returns 0 removed, no error. The cancellation flow should not treat this as a failure.\n- Supersession of a spec that was never indexed — same, 0 removed, no error.\n- Promotion timing gap — between removing original spec chunks and the new cross-cutting spec completing, the content is absent from the knowledge base. This is accepted per design doc.\n- Epic with multiple spec topics — superseding one MUST NOT remove others. The --topic flag ensures granularity.\n- Done action on a work unit that already has completed_at — overwrite with current date (the user is explicitly marking it done now, regardless of previous state).\n\nSpec Reference: knowledge-base/design.md — Work Unit Lifecycle section (lines 799-801, cancelled work units auto-removed, failure handling), Staleness and Supersession section (lines 530-539, superseded removed, promoted relocated, research/discussion/investigation kept), completed_at prerequisite (line 824, manage menu done action must set it), allowed-tools frontmatter changes (lines 728-733)","transitions":[{"from":"open","to":"in_progress","at":"2026-04-16T20:19:57Z","auto":false},{"from":"in_progress","to":"done","at":"2026-04-16T20:20:59Z","auto":false}],"parent":"tick-77697a","created":"2026-04-09T17:58:53Z","updated":"2026-04-16T20:20:59Z","closed":"2026-04-16T20:20:59Z"} {"id":"tick-496c59","title":"Phase 6: Retrieval Integration","status":"open","priority":2,"refs":["knowledge-base-6"],"parent":"tick-cbbd13","created":"2026-04-09T18:09:56Z","updated":"2026-04-09T18:09:56Z"} {"id":"tick-09d9ca","title":"Knowledge SKILL.md + Two-Step Retrieval Documentation","status":"open","priority":2,"type":"task","refs":["knowledge-base-6-1"],"description":"Problem: The knowledge base CLI exists (Phases 1-4) and is wired into skills (Phase 5), but Claude has no documentation explaining what it is, how to use it, or when to query it. Without Layer 1, Layers 2 and 3 have nothing to reference for API details.\n\nSolution: Create the knowledge skill file (SKILL.md) that serves as the API documentation layer — what commands exist, how to call them, what the output looks like, and how the two-step retrieval pattern works.\n\nOutcome: A comprehensive skill file that any processing skill can reference for knowledge base API details, enabling Claude to query the knowledge base correctly.\n\nDo:\n- Create skills/workflow-knowledge/SKILL.md following the project's skill file conventions (see CLAUDE.md Skill File Structure section).\n- This is a model-invocable skill, not user-invocable. It is loaded by reference from Layer 2 usage references (Task 6-2). It is NOT directly invoked by users.\n- Content sections:\n\n PURPOSE:\n - What the knowledge base is: a RAG system storing all workflow artifacts at full fidelity for semantic search\n - Why it exists: cross-work-unit and intra-work-unit context surfacing\n - What it indexes: research, discussion, investigation, specification (not planning, implementation, review)\n\n QUERY COMMAND:\n - Single query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003csearch_term\u003e [flags]\n - Batch query: node .claude/skills/workflow-knowledge/scripts/knowledge.cjs query \u003cterm1\u003e \u003cterm2\u003e [termN...] [flags]\n Multiple positional arguments run separate searches, merge results, deduplicate by chunk ID (highest score kept), apply --limit to merged set. Efficient: one store load, multiple searches.\n - Flags: --work-type, --phase, --work-unit (re-ranking hint, not filter), --limit\n - Search modes: hybrid (default when provider configured), keyword-only (when no provider)\n - Query construction guidance: use natural language, not topic slugs. Descriptive queries produce better semantic matching. Multiple queries from different angles are encouraged.\n - Example queries showing good vs poor query construction\n\n OUTPUT FORMAT:\n - Document the exact format (from design doc lines 580-603):\n [N results]\n [phase | work_unit/topic | confidence | YYYY-MM-DD]\n chunk content verbatim\n Source: source_file_path\n - Result count header, provenance line, verbatim content, source path\n - Empty results: [0 results]\n - Stub mode note when applicable: [keyword-only mode — configure embedding provider for semantic search]\n\n CONFIDENCE TIERS:\n - Explain what confidence means and how to weigh it:\n specification (high) — validated decisions, what was decided and why\n investigation (medium) — diagnostic knowledge, tied to specific symptoms\n discussion (low-medium) — conversational, may contain corrected assumptions\n research (low) — exploratory, may contain dead ends and rejected paths\n - Low confidence is not low value — research that rejected an approach prevents re-exploring dead ends\n\n TWO-STEP RETRIEVAL PATTERN:\n - Step 1: query returns chunks with provenance (lightweight, lands in context)\n - Step 2: if a chunk looks relevant, read the actual source file (source_file in metadata) for full detail\n - This keeps context lean — surface-level awareness, deep dive on demand\n - Claude should NOT read source files for every result, only when a chunk warrants deeper investigation\n\n WHAT NOT TO DO:\n - Do not dump large result sets into context speculatively\n - Do not query using topic slugs as search terms (poor semantic signal)\n - Do not query during specification phase (explicitly excluded — spec turns decisions into a golden doc, cross-cutting concerns merge at planning time)\n - Do not prepend metadata to stored content (already in enum fields)\n\nAcceptance Criteria:\n- SKILL.md exists at skills/workflow-knowledge/SKILL.md\n- Documents both single and batch query invocation forms\n- Documents all query flags and their behaviour\n- Documents the exact output format with examples\n- Documents confidence tiers with guidance on how to weigh them\n- Documents the two-step retrieval pattern (query -\u003e read source file on demand)\n- Documents what NOT to do (spec exclusion, slug queries, speculative dumps)\n- Follows project skill file conventions from CLAUDE.md\n- Can be loaded by reference from Layer 2 files (Task 6-2)\n\nTests:\n- No automated tests — documentation task. Validation is manual:\n - Read the SKILL.md and verify it provides enough information to correctly construct and interpret knowledge queries\n - Verify it follows the project's skill file structure conventions\n\nEdge Cases:\n- The SKILL.md must describe BOTH hybrid and keyword-only modes without making keyword-only feel broken — it is a supported degraded mode\n- Must not duplicate the CLI help text verbatim — this is higher-level guidance about when and why, not just how\n- Must explain that --work-unit is a re-ranking hint, not a filter — this is a common misunderstanding that would produce wrong queries if not clear\n- Batch query section must explain deduplication and merged limit behaviour\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 1 description), Retrieved Context Format (lines 576-605, exact output format), Confidence Tiers (lines 514-525), Two-step retrieval pattern (lines 735-737), Query construction (line 737), Batch query (line 602-603, merged and deduplicated), Specification excluded from automatic retrieval (line 560)","parent":"tick-496c59","created":"2026-04-09T18:22:30Z","updated":"2026-04-09T18:30:41Z"} {"id":"tick-c5a9f0","title":"Per-Phase Usage References + Contextual Query at Phase Start","status":"open","priority":2,"type":"task","refs":["knowledge-base-6-2"],"description":"Problem: Layer 1 (SKILL.md) documents the API, but Claude needs phase-specific guidance on WHEN to query and WHY — the trigger heuristics contextualised for each phase's work. Without Layer 2, Claude has the capability but not the judgment to use it effectively. Additionally, Claude needs explicit guidance on how to handle query failures — the design doc mandates pausing the workflow, not silently proceeding.\n\nSolution: Create usage reference files loaded early in processing skills that describe when and why to query during each specific phase, how to handle failures, plus the contextual query at phase start for research, discussion, and investigation.\n\nOutcome: Every processing skill loads phase-appropriate querying guidance early in its flow, the three early phases perform a contextual query at phase start, and query failures are handled by pausing with user options rather than silently skipping.\n\nDo:\n\nUSAGE REFERENCE FILES (Layer 2):\n- Create reference files — either one shared file or per-phase files, depending on how much the guidance differs between phases. The design doc (line 720) says: may be shared if guidance is generic enough, or local per phase if each needs different emphasis.\n- Recommended approach: one shared reference at skills/workflow-shared/references/knowledge-usage.md that covers the common trigger heuristics, with phase-specific notes where needed. This avoids maintaining 8 near-identical files.\n- Content:\n - Load the knowledge SKILL.md (Layer 1, Task 6-1) by reference for API details\n - Trigger heuristics — when to query (from design doc lines 551-557):\n 1. At topic boundaries — conversation edges toward adjacent territory\n 2. Upstream/downstream dependencies — current topic may affect or be affected by other work\n 3. Unfamiliar territory — not sure whether something was explored before\n 4. User prompts — user asks to check for prior context\n - Encourage proactive querying — under-querying is the bigger risk (design doc line 1003)\n - Multiple queries from different angles are expected and encouraged\n - Query construction: use natural language derived from what is currently being discussed, not topic names\n - Two-step retrieval reminder: query first (lightweight), read source file only when a chunk warrants investigation\n\nQUERY FAILURE HANDLING (from design doc lines 767-776):\n- This is skill-level behavior, not CLI behavior. The CLI retries 3 times and then exits with a non-zero code and error message (Task 4-4). The SKILL must handle what happens next:\n 1. If knowledge query fails (non-zero exit): PAUSE the workflow. Do not silently proceed without context.\n 2. Present the error clearly: what failed, likely causes (API key expired, network down, store corrupted).\n 3. Offer the user two options: fix the issue and retry, or explicitly choose to proceed without knowledge context.\n 4. If the user chooses to proceed: continue the phase but note that knowledge retrieval was skipped. This note should be visible in the output so the user knows context may be missing.\n- The design doc is emphatic: the value of the knowledge base is too high to silently skip (line 776).\n- This failure handling guidance goes in the usage reference (Layer 2) so it applies to all phases that load it.\n\n- Phase-specific notes within the shared reference (or in separate files if warranted):\n - Research: query at start + throughout. Early phase, high chance of overlap with prior work.\n - Discussion: query at start + throughout. Decisions being made that may relate to prior decisions.\n - Investigation: query at start + throughout. Symptoms and root causes may have been seen before.\n - Specification: EXCLUDED from automatic retrieval. Explicit note: do not query during spec authoring. Cross-cutting concerns merge at planning time, not spec time (design doc line 560).\n - Scoping: query throughout. Quick-fix scoping benefits from knowing if the issue was discussed elsewhere.\n - Planning: query throughout, especially for cross-cutting context. The explicit cross-cutting query is handled separately (Task 6-3).\n - Implementation: query when hitting unfamiliar territory or when a task touches areas covered by prior work.\n - Review: query to verify decisions against prior context.\n\nCONTEXTUAL QUERY AT PHASE START:\n- Add to the processing skills for research, discussion, and investigation: at the beginning of the phase (after loading references, before the first substantive step), construct a natural language query from available context and search the knowledge base.\n- Available context for query construction (from design doc line 549): topic description, bootstrap answers, handoff context, problem statement — whatever is available at that point.\n- NOT the topic slug. The query must be descriptive: not auth-flow but user authentication flow using OAuth2 with PKCE for mobile and web clients.\n- Returns a small, focused result set. Zero cost if nothing comes back. High value when it catches prior work.\n- This is a single query, not a dump. If results come back, Claude reads them and proceeds with that context. If nothing comes back, proceed as normal.\n- Specification is EXCLUDED — no contextual query at spec phase start.\n\nLOAD DIRECTIVES IN PROCESSING SKILLS:\n- Add a load directive for the usage reference early in each processing skill (alongside where case conventions are loaded). The exact insertion point varies per skill — read each to find the right place.\n- Processing skills that need this:\n skills/workflow-research-process/SKILL.md\n skills/workflow-discussion-process/SKILL.md\n skills/workflow-investigation-process/SKILL.md\n skills/workflow-scoping-process/SKILL.md\n skills/workflow-planning-process/SKILL.md\n skills/workflow-implementation-process/SKILL.md\n skills/workflow-review-process/SKILL.md\n- Specification process does NOT load the usage reference (excluded from automatic retrieval).\n\nALLOWED-TOOLS FOR REMAINING PROCESSING SKILLS:\n- Add Bash(node .claude/skills/workflow-knowledge/scripts/knowledge.cjs) to:\n skills/workflow-planning-process/SKILL.md\n skills/workflow-implementation-process/SKILL.md\n skills/workflow-review-process/SKILL.md\n- These 3 were deferred from Phase 5 — now they need it for autonomous querying.\n- Scoping process already has it from Phase 5 Task 5-2. Research, discussion, investigation, specification process already have it from Task 5-2.\n\nAcceptance Criteria:\n- Usage reference file(s) exist with trigger heuristics and phase-specific guidance\n- Usage reference loads Layer 1 (SKILL.md) by reference for API details\n- Query failure handling documented: pause workflow, present error, offer user choice to proceed or fix\n- All 7 processing skills (except specification) load the usage reference early in their flow\n- Specification process does NOT load the usage reference\n- Research, discussion, and investigation processing skills perform a contextual query at phase start\n- Contextual query uses descriptive natural language, not topic slugs\n- allowed-tools added to planning, implementation, and review processing skills\n- Trigger heuristics match the design doc (topic boundaries, dependencies, unfamiliar territory, user prompts)\n\nTests:\n- No automated tests — skill file editing task. Validation is manual:\n - Start a discussion in a test project with existing indexed knowledge -\u003e verify contextual query runs and surfaces relevant prior work\n - Start a specification -\u003e verify no contextual query runs\n - Simulate query failure -\u003e verify workflow pauses with user options (not silent skip)\n - Verify all processing skills load the usage reference\n\nEdge Cases:\n- Contextual query with no prior knowledge indexed — returns [0 results], phase proceeds normally with no delay or noise\n- Phase start with very little context available (e.g., just a topic name) — construct the best query possible from what is available. A poor query that returns nothing is fine. The design doc accepts zero cost if nothing comes back.\n- Query failure during contextual query at phase start — same failure handling applies (pause, present, offer choice). The contextual query is not exempt from failure handling.\n- Shared vs per-phase reference: if a shared reference becomes unwieldy with too many phase-specific notes, split into per-phase files. Start shared, split if needed.\n\nSpec Reference: knowledge-base/design.md — Three-layer integration pattern (lines 716-724, Layer 2 description), Autonomous querying trigger heuristics (lines 551-557), Contextual query at phase start (line 549), Specification excluded (line 560), Query Failures section (lines 767-776, pause workflow, present error, user choice), Autonomous query guardrails review finding #16 (line 1002)","parent":"tick-496c59","created":"2026-04-09T18:23:15Z","updated":"2026-04-09T18:30:02Z"} diff --git a/skills/workflow-specification-process/references/promote-to-cross-cutting.md b/skills/workflow-specification-process/references/promote-to-cross-cutting.md index 981ea4c04..9eed9fb21 100644 --- a/skills/workflow-specification-process/references/promote-to-cross-cutting.md +++ b/skills/workflow-specification-process/references/promote-to-cross-cutting.md @@ -97,6 +97,22 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.speci node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.specification.{topic} promoted_to {cc_work_unit} ``` +Remove the promoted spec's chunks from the original work unit (the new cross-cutting spec will be indexed when it completes): + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic} +``` + +If the remove command fails, display the error but do not block — the promotion is already recorded: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge removal warning + {error details} + The spec is promoted. You can run knowledge remove manually later. +``` + → Proceed to **F. Commit and Display**. ## F. Commit and Display diff --git a/skills/workflow-specification-process/references/spec-completion.md b/skills/workflow-specification-process/references/spec-completion.md index 293f82931..c253fcbe2 100644 --- a/skills/workflow-specification-process/references/spec-completion.md +++ b/skills/workflow-specification-process/references/spec-completion.md @@ -161,8 +161,19 @@ If any of your sources were **existing specifications** (as opposed to discussio node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.specification.{source-topic} status superseded node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.specification.{source-topic} superseded_by {topic} ``` -2. Inform the user which topics were updated -3. Commit: `spec({work_unit}): mark source specifications as superseded` +2. Remove superseded spec chunks from the knowledge base (per source topic): + ```bash + node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {source-topic} + ``` + If the remove command fails, display the error but do not block — the supersession is already recorded: + > *Output the next fenced block as a code block:* + ``` + ⚑ Knowledge removal warning + {error details} + The spec is superseded. You can run knowledge remove manually later. + ``` +3. Inform the user which topics were updated +4. Commit: `spec({work_unit}): mark source specifications as superseded` → Proceed to **F. Pipeline Continuation**. diff --git a/skills/workflow-start/references/manage-work-unit.md b/skills/workflow-start/references/manage-work-unit.md index 43561a708..645aa57e7 100644 --- a/skills/workflow-start/references/manage-work-unit.md +++ b/skills/workflow-start/references/manage-work-unit.md @@ -242,6 +242,22 @@ Invoke the `/continue-epic` skill. This is terminal — do not return to the cal node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} status cancelled ``` +Remove the cancelled work unit's chunks from the knowledge base: + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {selected.name} +``` + +If the remove command fails, display the error but do not block — the cancellation itself is already recorded: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge removal warning + {error details} + The work unit is cancelled. You can run knowledge remove manually later. +``` + Commit: `workflow({selected.name}): mark as cancelled` > *Output the next fenced block as a code block:* From 9ecf8c02e94f0671b41812c0c7ee0a95aba0b937 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Thu, 16 Apr 2026 21:55:33 +0100 Subject: [PATCH 04/15] docs(knowledge): log removal retry gap as deferred issue #18 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No automatic catch-up for failed knowledge remove calls — unlike indexing which has a pending queue. Stale chunks persist until manual retry. Logged for future mitigation. Co-Authored-By: Claude Opus 4.6 (1M context) --- knowledge-base/deferred-issues.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/knowledge-base/deferred-issues.md b/knowledge-base/deferred-issues.md index a16f97b66..d07ab4d22 100644 --- a/knowledge-base/deferred-issues.md +++ b/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. From d9e2ea9d8cebd20e80edbf1a96559e3ebe5aaa26 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Fri, 17 Apr 2026 19:39:58 +0100 Subject: [PATCH 05/15] fix(knowledge): close 3 knowledge base gaps found in review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Issue 2: Promoted spec permanently lost from knowledge base — the cc work unit is born completed so no future completion event fires. Add knowledge index after spec move in promote-to-cross-cutting. Issue 3: Feature absorption orphans knowledge base chunks — moved files were never re-indexed under the epic, and the deleted feature's chunks were never removed. Add index for moved completed artifacts and remove for the old feature work unit in absorb-into-epic. Issue 4: Epic topic cancellation leaves stale chunks — add knowledge remove on cancel, knowledge index on reactivate (completed indexed phases only). Co-Authored-By: Claude Opus 4.6 (1M context) --- .../references/epic-display-and-menu.md | 38 +++++++++++++++ .../references/promote-to-cross-cutting.md | 18 ++++++- .../references/absorb-into-epic.md | 48 +++++++++++++++++++ 3 files changed, 103 insertions(+), 1 deletion(-) diff --git a/skills/continue-epic/references/epic-display-and-menu.md b/skills/continue-epic/references/epic-display-and-menu.md index dc1ef5176..80312e96e 100644 --- a/skills/continue-epic/references/epic-display-and-menu.md +++ b/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 `research`, `discussion`, `investigation`, or `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:* diff --git a/skills/workflow-specification-process/references/promote-to-cross-cutting.md b/skills/workflow-specification-process/references/promote-to-cross-cutting.md index 9eed9fb21..dff267d6b 100644 --- a/skills/workflow-specification-process/references/promote-to-cross-cutting.md +++ b/skills/workflow-specification-process/references/promote-to-cross-cutting.md @@ -86,6 +86,22 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {cc_work_unit}.sp node .claude/skills/workflow-manifest/scripts/manifest.cjs set {cc_work_unit}.specification.{cc_work_unit} date $(date +%Y-%m-%d) ``` +Index the specification at its new location in the knowledge base: + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{cc_work_unit}/specification/{cc_work_unit}/specification.md +``` + +If the index command fails, display the error but do not block — the artifact is already saved: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. +``` + → Proceed to **E. Update Epic Manifest**. ## E. Update Epic Manifest @@ -97,7 +113,7 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.speci node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.specification.{topic} promoted_to {cc_work_unit} ``` -Remove the promoted spec's chunks from the original work unit (the new cross-cutting spec will be indexed when it completes): +Remove the promoted spec's chunks from the original work unit (already re-indexed under the new cc work unit in section D): ```bash node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic} diff --git a/skills/workflow-start/references/absorb-into-epic.md b/skills/workflow-start/references/absorb-into-epic.md index 2be1b75fc..e6c069d1f 100644 --- a/skills/workflow-start/references/absorb-into-epic.md +++ b/skills/workflow-start/references/absorb-into-epic.md @@ -219,6 +219,22 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs init-phase {target_ep node .claude/skills/workflow-manifest/scripts/manifest.cjs set {target_epic}.discussion.{topic} status completed ``` +Index the discussion at its new location in the knowledge base: + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{target_epic}/discussion/{topic}.md +``` + +If the index command fails, display the error but do not block — the artifact is already saved: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. +``` + → Proceed to **G. Move Research**. #### Otherwise @@ -250,6 +266,22 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs init-phase {target_ep node .claude/skills/workflow-manifest/scripts/manifest.cjs set {target_epic}.research.{target_name} status completed ``` +Index the research at its new location in the knowledge base: + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{target_epic}/research/{target_name}.md +``` + +If the index command fails, display the error but do not block — the artifact is already saved: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. +``` + → Proceed to **H. Cleanup**. #### Otherwise @@ -260,6 +292,22 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {target_epic}.res ## H. Cleanup +Remove the absorbed feature's chunks from the knowledge base (moved files were re-indexed under the epic): + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {selected.name} +``` + +If the remove command fails, display the error but do not block — the absorption itself is already recorded: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge removal warning + {error details} + The feature is absorbed. You can run knowledge remove manually later. +``` + Remove the feature from the project manifest: ```bash From c90248ed51d9fd5854660d78ffb9ce26af3ba103 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Fri, 17 Apr 2026 20:11:41 +0100 Subject: [PATCH 06/15] fix(knowledge): handle promoted discussion chunks + work-unit reactivation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Promote-to-cross-cutting section C: index discussions at new cc location and remove old chunks from the epic. Previously only the spec move was handled — discussions were orphaned. View-completed reactivation: re-index all completed indexed-phase artifacts when reactivating a cancelled work unit. Cancellation removes all chunks, so reactivation must restore them. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../references/promote-to-cross-cutting.md | 17 +++++++++++ .../references/view-completed.md | 28 +++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/skills/workflow-specification-process/references/promote-to-cross-cutting.md b/skills/workflow-specification-process/references/promote-to-cross-cutting.md index dff267d6b..e640d2245 100644 --- a/skills/workflow-specification-process/references/promote-to-cross-cutting.md +++ b/skills/workflow-specification-process/references/promote-to-cross-cutting.md @@ -67,6 +67,23 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs init-phase {cc_work_u node .claude/skills/workflow-manifest/scripts/manifest.cjs set {cc_work_unit}.discussion.{source} status completed ``` +Index the discussion at its new location and remove old chunks (per source): + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{cc_work_unit}/discussion/{source}.md +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase discussion --topic {source} +``` + +If either command fails, display the error but do not block — the move is already recorded: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge warning + {error details} + The discussion is moved. You can run knowledge index/remove manually later. +``` + → Proceed to **D. Move Specification**. ## D. Move Specification diff --git a/skills/workflow-start/references/view-completed.md b/skills/workflow-start/references/view-completed.md index fe264f862..0644e7784 100644 --- a/skills/workflow-start/references/view-completed.md +++ b/skills/workflow-start/references/view-completed.md @@ -98,6 +98,34 @@ Store the selected item. node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} status in-progress ``` +**If `selected.status` was `cancelled`:** + +Re-index completed artifacts that were removed during cancellation. For each indexed phase (research, discussion, investigation, specification), check the manifest for completed items: + +```bash +node .claude/skills/workflow-manifest/scripts/manifest.cjs get '{selected.name}.{phase}.*' status +``` + +For each item with status `completed`, resolve the artifact path by phase: +- research: `.workflows/{selected.name}/research/{topic}.md` +- discussion: `.workflows/{selected.name}/discussion/{topic}.md` +- investigation: `.workflows/{selected.name}/investigation/{topic}.md` +- specification: `.workflows/{selected.name}/specification/{topic}/specification.md` + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index {artifact_path} +``` + +If any 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 work unit is reactivated. Indexing can be retried later. +``` + > *Output the next fenced block as a code block:* ``` From 12f7633e5181b6ee327a11122fd31236c9b2c235 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 09:31:01 +0100 Subject: [PATCH 07/15] fix(knowledge): close 3 gaps from round-3 review BUG 1: reactivation loop crashed when phases didn't exist. Extract a shared reference that guards each indexed phase with an exists check before querying for completed items. BUG 2: bulk index re-added chunks from cancelled work units because discoverArtifacts didn't filter by status. Filter out cancelled work units at discovery time. Adds CLI test 80 to prevent regression. BUG 3: feature-to-epic pivot left stale work_type in chunk metadata. Re-index all completed artifacts after pivot so chunks pick up the new work_type. The shared reference skills/workflow-shared/references/reindex-work-unit.md is reused by reactivation and pivot paths. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../workflow-knowledge/scripts/knowledge.cjs | 2 +- .../references/reindex-work-unit.md | 60 +++++++++++++++++++ .../references/manage-work-unit.md | 4 ++ .../references/view-completed.md | 26 +------- src/knowledge/index.js | 1 + tests/scripts/test-knowledge-cli.sh | 17 ++++++ 6 files changed, 85 insertions(+), 25 deletions(-) create mode 100644 skills/workflow-shared/references/reindex-work-unit.md diff --git a/skills/workflow-knowledge/scripts/knowledge.cjs b/skills/workflow-knowledge/scripts/knowledge.cjs index 6e44b5b79..87d8ec8ca 100644 --- a/skills/workflow-knowledge/scripts/knowledge.cjs +++ b/skills/workflow-knowledge/scripts/knowledge.cjs @@ -51,7 +51,7 @@ Expected: .workflows/{work_unit}/research/{filename}.md`);o=c[1]}if(o==="."||o== Store was indexed with: provider=${r}, model=${s} Current config has no provider configured.`)}async function Gd(t,e,n,r){if(t.length===0)return ko(e,n,r);let s=t[0],i=C.resolve(s);v.existsSync(i)||(process.stderr.write(`File not found: ${i} `),process.exit(1));let o=Er(s),c=await nt(()=>Ar(s,o,n,r),{maxAttempts:3,backoff:tt});process.stdout.write(`Indexed ${c} chunks from ${s} -`),await No(n,r,Wd)}async function Ar(t,e,n,r){let s=Kd(e.workUnit),i=C.join(__dirname,"..","chunking",e.phase+".json");if(!v.existsSync(i))throw new Error(`Chunking config not found: ${i}`);let o=JSON.parse(v.readFileSync(i,"utf8")),c=C.resolve(t),u=v.readFileSync(c,"utf8"),a=vo.chunk(u,o);if(a.length===0)throw new Error(`No chunks produced from ${t}. Refusing to index an empty file \u2014 this would silently wipe any existing indexed chunks for this topic. Use \`knowledge remove\` explicitly if that is what you want.`);let d=ie(),l=oe(),f=me(),p=xe();v.existsSync(d)||v.mkdirSync(d,{recursive:!0});let g,y,h=v.existsSync(l),m=v.existsSync(f);h&&(g=await E.loadStore(l)),m&&(y=E.readMetadata(f),Array.isArray(y.pending)||(y.pending=[]));let w,S;if(y){let A=Oo(y,n,r);w=A.mode,S=A.provider}else r?(w="full",S=r):(w="keyword-only",S=null);if(!g){let A=S?S.dimensions():n.dimensions||xr;g=await E.createStore(A)}let _=null;if(w==="full"&&S&&a.length>0){let A=a.map(k=>k.content);_=await S.embedBatch(A)}let I=Date.now(),T=o.confidence||"medium",D=a.map((A,k)=>{let Ee=String(k+1).padStart(3,"0"),Y={id:`${e.workUnit}-${e.phase}-${e.topic}-${Ee}`,content:A.content,work_unit:e.workUnit,work_type:s,phase:e.phase,topic:e.topic,confidence:T,source_file:t,timestamp:I};return _&&(Y.embedding=_[k]),Y});return await E.withLock(p,async()=>{h?g=await E.loadStore(l):v.existsSync(l)&&(g=await E.loadStore(l)),await E.removeByIdentity(g,{work_unit:e.workUnit,phase:e.phase,topic:e.topic});for(let k of D)await E.insertDocument(g,k);await E.saveStore(g,l);let A=v.existsSync(f)?E.readMetadata(f):null;if(A)A.last_indexed=new Date().toISOString(),Array.isArray(A.pending)||(A.pending=[]),E.writeMetadata(f,A);else{let k={provider:S?n.provider:null,model:S?S.model():null,dimensions:S?S.dimensions():null,last_indexed:new Date().toISOString(),pending:[]};E.writeMetadata(f,k)}}),D.length}function et(t){let{execFileSync:e}=require("child_process");return e("node",[Vd,...t],{cwd:process.cwd(),encoding:"utf8",stdio:["pipe","pipe","pipe"]})}async function Po(t,e,n,r){return(await E.searchFulltext(t,{term:"",where:{work_unit:{eq:e},phase:{eq:n},topic:{eq:r}},limit:1})).length>0}function Tr(){let t=[],e;try{let n=et(["list"]);e=JSON.parse(n)}catch{return t}if(!Array.isArray(e)||e.length===0)return t;for(let n of e){let r=n.name;if(r)for(let s of Ir){let i=n.phases&&n.phases[s];if(!(!i||!i.items)){for(let[o,c]of Object.entries(i.items))if(!(!c||c.status!=="completed"))try{let a=et(["resolve",`${r}.${s}.${o}`]).trim();a&&v.existsSync(C.resolve(a))&&t.push({file:a,workUnit:r,phase:s,topic:o})}catch{}}}}return t}async function ko(t,e,n){let r=Tr(),s=ie(),i=oe();v.existsSync(s)||v.mkdirSync(s,{recursive:!0});let o=null;v.existsSync(i)&&(o=await E.loadStore(i));let c=0,u=0,a=0;for(let d of r){if(o&&await Po(o,d.workUnit,d.phase,d.topic)){a++;continue}try{let l={workUnit:d.workUnit,phase:d.phase,topic:d.topic},f=await nt(()=>Ar(d.file,l,e,n),{maxAttempts:3,backoff:tt});process.stdout.write(`Indexing ${d.file}... ${f} chunks +`),await No(n,r,Wd)}async function Ar(t,e,n,r){let s=Kd(e.workUnit),i=C.join(__dirname,"..","chunking",e.phase+".json");if(!v.existsSync(i))throw new Error(`Chunking config not found: ${i}`);let o=JSON.parse(v.readFileSync(i,"utf8")),c=C.resolve(t),u=v.readFileSync(c,"utf8"),a=vo.chunk(u,o);if(a.length===0)throw new Error(`No chunks produced from ${t}. Refusing to index an empty file \u2014 this would silently wipe any existing indexed chunks for this topic. Use \`knowledge remove\` explicitly if that is what you want.`);let d=ie(),l=oe(),f=me(),p=xe();v.existsSync(d)||v.mkdirSync(d,{recursive:!0});let g,y,h=v.existsSync(l),m=v.existsSync(f);h&&(g=await E.loadStore(l)),m&&(y=E.readMetadata(f),Array.isArray(y.pending)||(y.pending=[]));let w,S;if(y){let A=Oo(y,n,r);w=A.mode,S=A.provider}else r?(w="full",S=r):(w="keyword-only",S=null);if(!g){let A=S?S.dimensions():n.dimensions||xr;g=await E.createStore(A)}let _=null;if(w==="full"&&S&&a.length>0){let A=a.map(k=>k.content);_=await S.embedBatch(A)}let I=Date.now(),T=o.confidence||"medium",D=a.map((A,k)=>{let Ee=String(k+1).padStart(3,"0"),Y={id:`${e.workUnit}-${e.phase}-${e.topic}-${Ee}`,content:A.content,work_unit:e.workUnit,work_type:s,phase:e.phase,topic:e.topic,confidence:T,source_file:t,timestamp:I};return _&&(Y.embedding=_[k]),Y});return await E.withLock(p,async()=>{h?g=await E.loadStore(l):v.existsSync(l)&&(g=await E.loadStore(l)),await E.removeByIdentity(g,{work_unit:e.workUnit,phase:e.phase,topic:e.topic});for(let k of D)await E.insertDocument(g,k);await E.saveStore(g,l);let A=v.existsSync(f)?E.readMetadata(f):null;if(A)A.last_indexed=new Date().toISOString(),Array.isArray(A.pending)||(A.pending=[]),E.writeMetadata(f,A);else{let k={provider:S?n.provider:null,model:S?S.model():null,dimensions:S?S.dimensions():null,last_indexed:new Date().toISOString(),pending:[]};E.writeMetadata(f,k)}}),D.length}function et(t){let{execFileSync:e}=require("child_process");return e("node",[Vd,...t],{cwd:process.cwd(),encoding:"utf8",stdio:["pipe","pipe","pipe"]})}async function Po(t,e,n,r){return(await E.searchFulltext(t,{term:"",where:{work_unit:{eq:e},phase:{eq:n},topic:{eq:r}},limit:1})).length>0}function Tr(){let t=[],e;try{let n=et(["list"]);e=JSON.parse(n)}catch{return t}if(!Array.isArray(e)||e.length===0)return t;for(let n of e){let r=n.name;if(r&&n.status!=="cancelled")for(let s of Ir){let i=n.phases&&n.phases[s];if(!(!i||!i.items)){for(let[o,c]of Object.entries(i.items))if(!(!c||c.status!=="completed"))try{let a=et(["resolve",`${r}.${s}.${o}`]).trim();a&&v.existsSync(C.resolve(a))&&t.push({file:a,workUnit:r,phase:s,topic:o})}catch{}}}}return t}async function ko(t,e,n){let r=Tr(),s=ie(),i=oe();v.existsSync(s)||v.mkdirSync(s,{recursive:!0});let o=null;v.existsSync(i)&&(o=await E.loadStore(i));let c=0,u=0,a=0;for(let d of r){if(o&&await Po(o,d.workUnit,d.phase,d.topic)){a++;continue}try{let l={workUnit:d.workUnit,phase:d.phase,topic:d.topic},f=await nt(()=>Ar(d.file,l,e,n),{maxAttempts:3,backoff:tt});process.stdout.write(`Indexing ${d.file}... ${f} chunks `),c++,u+=f,v.existsSync(i)&&(o=await E.loadStore(i))}catch(l){await Yd(d.file,l.message),process.stderr.write(`Failed to index ${d.file} after 3 attempts: ${l.message}. Added to pending queue. `)}}await No(e,n,1/0),process.stdout.write(`Indexed ${c} files (${u} chunks). ${a} already indexed. `)}async function Yd(t,e){let n=me(),r=ie(),s=xe();v.existsSync(r)||v.mkdirSync(r,{recursive:!0}),await E.withLock(s,async()=>{let i;v.existsSync(n)?i=E.readMetadata(n):i={provider:null,model:null,dimensions:null,last_indexed:null,pending:[]},Array.isArray(i.pending)||(i.pending=[]);let o=i.pending.findIndex(u=>u.file===t),c={file:t,failed_at:new Date().toISOString(),error:e};o>=0?i.pending[o]=c:i.pending.push(c),E.writeMetadata(n,i)})}async function br(t){let e=me(),n=xe();v.existsSync(e)&&await E.withLock(n,async()=>{if(!v.existsSync(e))return;let r=E.readMetadata(e);Array.isArray(r.pending)&&(r.pending=r.pending.filter(s=>s.file!==t),E.writeMetadata(e,r))})}async function No(t,e,n){let r=me();if(!v.existsSync(r))return;let s=E.readMetadata(r);if(!Array.isArray(s.pending)||s.pending.length===0)return;let i=s.pending.slice(0,n);for(let o of i){let c=C.resolve(o.file);if(!v.existsSync(c)){process.stderr.write(`Pending item ${o.file} no longer exists. Removing from queue. diff --git a/skills/workflow-shared/references/reindex-work-unit.md b/skills/workflow-shared/references/reindex-work-unit.md new file mode 100644 index 000000000..a74d116fa --- /dev/null +++ b/skills/workflow-shared/references/reindex-work-unit.md @@ -0,0 +1,60 @@ +# Re-Index Work Unit + +*Shared reference for skills that need to re-index all completed artifacts of a work unit (e.g., reactivation after cancellation, feature-to-epic pivot).* + +--- + +Re-index every completed artifact in an indexed phase so that chunk metadata stays in sync with the manifest. Caller passes `work_unit`. + +## A. Loop Over Indexed Phases + +For each phase in `research`, `discussion`, `investigation`, `specification`: + +Check whether the work unit has that phase: + +```bash +node .claude/skills/workflow-manifest/scripts/manifest.cjs exists {work_unit}.{phase} +``` + +#### If `false` + +Skip this phase. → Continue to the next phase. + +#### If `true` + +Read all items in this phase with their statuses: + +```bash +node .claude/skills/workflow-manifest/scripts/manifest.cjs get '{work_unit}.{phase}.*' status +``` + +For each item whose status is `completed`, 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` + +Then run: + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index {artifact_path} +``` + +If any index command fails, display the error but do not block — the caller's operation is already recorded: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge indexing warning + {error details} + Indexing can be retried later. +``` + +→ Continue to the next item, then the next phase. + +## B. Complete + +Once every indexed phase has been processed, return to the caller. + +→ Return to caller. diff --git a/skills/workflow-start/references/manage-work-unit.md b/skills/workflow-start/references/manage-work-unit.md index 645aa57e7..729b89d41 100644 --- a/skills/workflow-start/references/manage-work-unit.md +++ b/skills/workflow-start/references/manage-work-unit.md @@ -203,6 +203,10 @@ Commit: `workflow({selected.name}): mark as completed` node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} work_type epic ``` +Re-index all completed artifacts so their chunks carry the new `work_type: epic`: + +Load **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. + > *Output the next fenced block as markdown (not a code block):* ``` diff --git a/skills/workflow-start/references/view-completed.md b/skills/workflow-start/references/view-completed.md index 0644e7784..2119e9264 100644 --- a/skills/workflow-start/references/view-completed.md +++ b/skills/workflow-start/references/view-completed.md @@ -100,31 +100,9 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} s **If `selected.status` was `cancelled`:** -Re-index completed artifacts that were removed during cancellation. For each indexed phase (research, discussion, investigation, specification), check the manifest for completed items: +Re-index completed artifacts that were removed during cancellation. -```bash -node .claude/skills/workflow-manifest/scripts/manifest.cjs get '{selected.name}.{phase}.*' status -``` - -For each item with status `completed`, resolve the artifact path by phase: -- research: `.workflows/{selected.name}/research/{topic}.md` -- discussion: `.workflows/{selected.name}/discussion/{topic}.md` -- investigation: `.workflows/{selected.name}/investigation/{topic}.md` -- specification: `.workflows/{selected.name}/specification/{topic}/specification.md` - -```bash -node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index {artifact_path} -``` - -If any 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 work unit is reactivated. Indexing can be retried later. -``` +Load **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. > *Output the next fenced block as a code block:* diff --git a/src/knowledge/index.js b/src/knowledge/index.js index 49d1aa561..a22001256 100644 --- a/src/knowledge/index.js +++ b/src/knowledge/index.js @@ -544,6 +544,7 @@ function discoverArtifacts() { for (const wu of workUnits) { const wuName = wu.name; if (!wuName) continue; + if (wu.status === 'cancelled') continue; for (const phase of INDEXED_PHASES) { const phaseData = wu.phases && wu.phases[phase]; diff --git a/tests/scripts/test-knowledge-cli.sh b/tests/scripts/test-knowledge-cli.sh index e4c0c9fb3..e3ffd4a59 100644 --- a/tests/scripts/test-knowledge-cli.sh +++ b/tests/scripts/test-knowledge-cli.sh @@ -1360,6 +1360,23 @@ assert_eq "partial input aborts" "true" "$([ "$exit_code" -ne 0 ] && echo true | assert_eq "shows aborted" "true" "$(echo "$output" | grep -q 'Aborted' && echo true || echo false)" teardown_project +# --- Test 80: Bulk index skips cancelled work units --- +echo "Test 80: Bulk index skips cancelled work units" +setup_project +create_work_unit "cancelled-wu" "feature" "Cancelled" +write_stub_config +create_discussion_file "cancelled-wu" "cancelled-wu" +cd "$TEST_ROOT" && node "$MANIFEST_JS" init-phase cancelled-wu.discussion.cancelled-wu >/dev/null 2>&1 +cd "$TEST_ROOT" && node "$MANIFEST_JS" set cancelled-wu.discussion.cancelled-wu status completed >/dev/null 2>&1 +run_kb index .workflows/cancelled-wu/discussion/cancelled-wu.md >/dev/null 2>&1 +cd "$TEST_ROOT" && node "$MANIFEST_JS" set cancelled-wu status cancelled >/dev/null 2>&1 +run_kb remove --work-unit cancelled-wu >/dev/null 2>&1 +# After cancel + remove, bulk index must NOT re-add the chunks. +output=$(run_kb index 2>&1) +status_output=$(run_kb status 2>&1) +assert_eq "bulk index skipped cancelled wu" "true" "$(echo "$status_output" | grep -q 'cancelled-wu' && echo false || echo true)" +teardown_project + # --- Summary --- echo "" echo "Results: $PASS passed, $FAIL failed" From fcc258b2bdd6af24bc27c0a438c453d1cc43db45 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 12:50:02 +0100 Subject: [PATCH 08/15] chore(knowledge): polish round-3 conditional scope + parameter docs Tighten the reactivation conditional in view-completed.md with an explicit Otherwise branch so the closure/return scope is unambiguous. Add a standard ## Parameters section to reindex-work-unit.md to match the convention in convergence-analysis.md. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/workflow-shared/references/reindex-work-unit.md | 8 +++++++- skills/workflow-start/references/view-completed.md | 8 ++++++-- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/skills/workflow-shared/references/reindex-work-unit.md b/skills/workflow-shared/references/reindex-work-unit.md index a74d116fa..02af1889c 100644 --- a/skills/workflow-shared/references/reindex-work-unit.md +++ b/skills/workflow-shared/references/reindex-work-unit.md @@ -4,7 +4,13 @@ --- -Re-index every completed artifact in an indexed phase so that chunk metadata stays in sync with the manifest. Caller passes `work_unit`. +Re-index every completed artifact in an indexed phase so that chunk metadata stays in sync with the manifest. + +## Parameters + +The caller provides these via context before loading: + +- `work_unit` — the work unit name whose completed artifacts should be re-indexed ## A. Loop Over Indexed Phases diff --git a/skills/workflow-start/references/view-completed.md b/skills/workflow-start/references/view-completed.md index 2119e9264..d4f924fed 100644 --- a/skills/workflow-start/references/view-completed.md +++ b/skills/workflow-start/references/view-completed.md @@ -100,9 +100,13 @@ node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} s **If `selected.status` was `cancelled`:** -Re-index completed artifacts that were removed during cancellation. +Re-index completed artifacts that were removed during cancellation. Load **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. -Load **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. +**Otherwise:** + +No re-indexing needed — completed work units keep their chunks. + +Display the confirmation: > *Output the next fenced block as a code block:* From caf61d7f41a8b4866825351ba0c9ee9be8398b1f Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 13:18:11 +0100 Subject: [PATCH 09/15] chore(knowledge): enforce CLAUDE.md conventions across Phase 5 additions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hard violations: - reindex-work-unit.md used the forbidden '→ Continue to' verb for loop iteration. Restructure to prose iteration with a single '→ Return to caller' exit. - view-completed.md bold conditional branches left shared closure code un-routed. Collapse to an inline prose conditional so the single exit arrow covers the whole block. Advisories: - epic-display-and-menu.md conditional listed phases with commas; rephrase as 'one of the indexed phases (...)'. - 5 conclusion files embedded rendering-instruction blockquotes inside numbered-list continuations. Break the failure-handling blocks out of the list (matching the existing 'Closure signpost:' pattern) so renderers don't mis-handle the blockquote inside a list item. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../references/epic-display-and-menu.md | 2 +- .../references/conclude-discussion.md | 25 +++++++++++-------- .../references/conclude-investigation.md | 25 +++++++++++-------- .../references/conclude-research.md | 25 +++++++++++-------- .../references/reindex-work-unit.md | 22 ++++++---------- .../references/spec-completion.md | 25 +++++++++++-------- .../references/view-completed.md | 10 +------- 7 files changed, 69 insertions(+), 65 deletions(-) diff --git a/skills/continue-epic/references/epic-display-and-menu.md b/skills/continue-epic/references/epic-display-and-menu.md index 80312e96e..ef4bb6542 100644 --- a/skills/continue-epic/references/epic-display-and-menu.md +++ b/skills/continue-epic/references/epic-display-and-menu.md @@ -673,7 +673,7 @@ 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 `research`, `discussion`, `investigation`, or `specification`:** +**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` diff --git a/skills/workflow-discussion-process/references/conclude-discussion.md b/skills/workflow-discussion-process/references/conclude-discussion.md index 3cb6a9579..18f55bc3b 100644 --- a/skills/workflow-discussion-process/references/conclude-discussion.md +++ b/skills/workflow-discussion-process/references/conclude-discussion.md @@ -28,16 +28,21 @@ Conclude this discussion and mark as completed? ``` 3. Final commit 4. Index the completed artifact into the knowledge base: - ```bash - node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/discussion/{topic}.md - ``` - If the index command fails, display the error but do not block — the artifact is already saved: - > *Output the next fenced block as a code block:* - ``` - ⚑ Knowledge indexing warning - {error details} - The artifact is saved. Indexing can be retried later. - ``` + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/discussion/{topic}.md +``` + +If the index command fails, display the error but do not block — the artifact is already saved: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. +``` + 5. Invoke the bridge: > *Output the next fenced block as markdown (not a code block):* diff --git a/skills/workflow-investigation-process/references/conclude-investigation.md b/skills/workflow-investigation-process/references/conclude-investigation.md index dbaf3c746..353d50a09 100644 --- a/skills/workflow-investigation-process/references/conclude-investigation.md +++ b/skills/workflow-investigation-process/references/conclude-investigation.md @@ -31,16 +31,21 @@ Investigation complete. Ready to conclude? ``` 2. Final commit 3. Index the completed artifact into the knowledge base: - ```bash - node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/investigation/{topic}.md - ``` - If the index command fails, display the error but do not block — the artifact is already saved: - > *Output the next fenced block as a code block:* - ``` - ⚑ Knowledge indexing warning - {error details} - The artifact is saved. Indexing can be retried later. - ``` + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/investigation/{topic}.md +``` + +If the index command fails, display the error but do not block — the artifact is already saved: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. +``` + 4. Display conclusion: > *Output the next fenced block as a code block:* diff --git a/skills/workflow-research-process/references/conclude-research.md b/skills/workflow-research-process/references/conclude-research.md index 7127538b7..eb026c7d9 100644 --- a/skills/workflow-research-process/references/conclude-research.md +++ b/skills/workflow-research-process/references/conclude-research.md @@ -10,16 +10,21 @@ ``` 2. Final commit: `research({work_unit}): complete {topic} research` 3. Index the completed artifact into the knowledge base: - ```bash - node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/research/{topic}.md - ``` - If the index command fails, display the error but do not block — the artifact is already saved: - > *Output the next fenced block as a code block:* - ``` - ⚑ Knowledge indexing warning - {error details} - The artifact is saved. Indexing can be retried later. - ``` + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs index .workflows/{work_unit}/research/{topic}.md +``` + +If the index command fails, display the error but do not block — the artifact is already saved: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge indexing warning + {error details} + The artifact is saved. Indexing can be retried later. +``` + 4. Closure signpost: > *Output the next fenced block as markdown (not a code block):* diff --git a/skills/workflow-shared/references/reindex-work-unit.md b/skills/workflow-shared/references/reindex-work-unit.md index 02af1889c..9484a896f 100644 --- a/skills/workflow-shared/references/reindex-work-unit.md +++ b/skills/workflow-shared/references/reindex-work-unit.md @@ -12,23 +12,19 @@ The caller provides these via context before loading: - `work_unit` — the work unit name whose completed artifacts should be re-indexed -## A. Loop Over Indexed Phases +## A. Re-Index Each Indexed Phase -For each phase in `research`, `discussion`, `investigation`, `specification`: +Process each phase in turn: `research`, `discussion`, `investigation`, `specification`. -Check whether the work unit has that phase: +For each phase, check whether the work unit has that phase: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs exists {work_unit}.{phase} ``` -#### If `false` +If the phase does not exist on this work unit, move on to the next phase in the list. -Skip this phase. → Continue to the next phase. - -#### If `true` - -Read all items in this phase with their statuses: +If the phase exists, read all items in it with their statuses: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs get '{work_unit}.{phase}.*' status @@ -57,10 +53,6 @@ If any index command fails, display the error but do not block — the caller's Indexing can be retried later. ``` -→ Continue to the next item, then the next phase. - -## B. Complete - -Once every indexed phase has been processed, return to the caller. +Process the remaining items in this phase, then move on to the next phase in the list. -→ Return to caller. +→ Return to caller once every indexed phase has been processed. diff --git a/skills/workflow-specification-process/references/spec-completion.md b/skills/workflow-specification-process/references/spec-completion.md index c253fcbe2..1de5d59b3 100644 --- a/skills/workflow-specification-process/references/spec-completion.md +++ b/skills/workflow-specification-process/references/spec-completion.md @@ -162,16 +162,21 @@ If any of your sources were **existing specifications** (as opposed to discussio node .claude/skills/workflow-manifest/scripts/manifest.cjs set {work_unit}.specification.{source-topic} superseded_by {topic} ``` 2. Remove superseded spec chunks from the knowledge base (per source topic): - ```bash - node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {source-topic} - ``` - If the remove command fails, display the error but do not block — the supersession is already recorded: - > *Output the next fenced block as a code block:* - ``` - ⚑ Knowledge removal warning - {error details} - The spec is superseded. You can run knowledge remove manually later. - ``` + +```bash +node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {source-topic} +``` + +If the remove command fails, display the error but do not block — the supersession is already recorded: + +> *Output the next fenced block as a code block:* + +``` +⚑ Knowledge removal warning + {error details} + The spec is superseded. You can run knowledge remove manually later. +``` + 3. Inform the user which topics were updated 4. Commit: `spec({work_unit}): mark source specifications as superseded` diff --git a/skills/workflow-start/references/view-completed.md b/skills/workflow-start/references/view-completed.md index d4f924fed..4c8e8d5dc 100644 --- a/skills/workflow-start/references/view-completed.md +++ b/skills/workflow-start/references/view-completed.md @@ -98,15 +98,7 @@ Store the selected item. node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} status in-progress ``` -**If `selected.status` was `cancelled`:** - -Re-index completed artifacts that were removed during cancellation. Load **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. - -**Otherwise:** - -No re-indexing needed — completed work units keep their chunks. - -Display the confirmation: +If `selected.status` was `cancelled`, re-index the completed artifacts that were removed during cancellation by loading **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. Completed work units keep their chunks, so no re-indexing is needed in that case. > *Output the next fenced block as a code block:* From 78fcc10ed89764f0a1f1c0e5efcb0fbd98959064 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 17:26:25 +0100 Subject: [PATCH 10/15] feat(claude-md): introduce decimal sub-step convention + restructure Step 0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document a new sub-step convention in CLAUDE.md scoped to early setup steps (typically Step 0). Sub-steps use H3 with decimal numbering ('### Step 0.1: Name') and allow conditional branches inside one sub-step to route to the next sub-step by name without duplicating shared downstream content. Later steps must continue to use reference files + progressive disclosure; sub-steps are not a general pattern. Remove the `### 6a:` example from the heading hierarchy — it was never an approved convention and was unused in the codebase. Apply the new convention to all 11 entry-point skills: Step 0 now decomposes into Step 0.1 (casing conventions), Step 0.2 (migrations), Step 0.3 (knowledge check). This removes the previous duplication where knowledge-check was loaded inside both branches of the migration conditional. For start-* skills the phase title + signpost move into Step 0.3 so they display once after migrations. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 38 +++++++++++++++++++++++++- skills/continue-bugfix/SKILL.md | 16 ++++++++--- skills/continue-cross-cutting/SKILL.md | 16 ++++++++--- skills/continue-epic/SKILL.md | 16 ++++++++--- skills/continue-feature/SKILL.md | 16 ++++++++--- skills/continue-quickfix/SKILL.md | 16 ++++++++--- skills/start-bugfix/SKILL.md | 30 ++++++++------------ skills/start-cross-cutting/SKILL.md | 32 ++++++++-------------- skills/start-epic/SKILL.md | 31 ++++++++------------- skills/start-feature/SKILL.md | 31 ++++++++------------- skills/start-quickfix/SKILL.md | 31 ++++++++------------- skills/workflow-start/SKILL.md | 12 +++++++- 12 files changed, 163 insertions(+), 122 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d2b62bfd6..bb3ed4e46 100644 --- a/CLAUDE.md +++ b/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: diff --git a/skills/continue-bugfix/SKILL.md b/skills/continue-bugfix/SKILL.md index 619155375..36fd99352 100644 --- a/skills/continue-bugfix/SKILL.md +++ b/skills/continue-bugfix/SKILL.md @@ -36,13 +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. -#### If the `/workflow-migrate` skill has already been invoked in this conversation +→ Proceed to **Step 0.2**. -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +### Step 0.2: Migrations -→ Proceed to **Step 1**. +#### If the `/workflow-migrate` skill has already been invoked in this conversation + +→ Proceed to **Step 0.3**. #### Otherwise @@ -56,7 +60,11 @@ Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** 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: Knowledge Check Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. diff --git a/skills/continue-cross-cutting/SKILL.md b/skills/continue-cross-cutting/SKILL.md index b65453469..f63a7344f 100644 --- a/skills/continue-cross-cutting/SKILL.md +++ b/skills/continue-cross-cutting/SKILL.md @@ -36,13 +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. -#### If the `/workflow-migrate` skill has already been invoked in this conversation +→ Proceed to **Step 0.2**. -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +### Step 0.2: Migrations -→ Proceed to **Step 1**. +#### If the `/workflow-migrate` skill has already been invoked in this conversation + +→ Proceed to **Step 0.3**. #### Otherwise @@ -56,7 +60,11 @@ Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** 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: Knowledge Check Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. diff --git a/skills/continue-epic/SKILL.md b/skills/continue-epic/SKILL.md index b73a1f106..69114bb0e 100644 --- a/skills/continue-epic/SKILL.md +++ b/skills/continue-epic/SKILL.md @@ -36,13 +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. -#### If the `/workflow-migrate` skill has already been invoked in this conversation +→ Proceed to **Step 0.2**. -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +### Step 0.2: Migrations -→ Proceed to **Step 1**. +#### If the `/workflow-migrate` skill has already been invoked in this conversation + +→ Proceed to **Step 0.3**. #### Otherwise @@ -56,7 +60,11 @@ Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** 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: Knowledge Check Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. diff --git a/skills/continue-feature/SKILL.md b/skills/continue-feature/SKILL.md index 8438144c6..f1d90c16f 100644 --- a/skills/continue-feature/SKILL.md +++ b/skills/continue-feature/SKILL.md @@ -36,13 +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. -#### If the `/workflow-migrate` skill has already been invoked in this conversation +→ Proceed to **Step 0.2**. -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +### Step 0.2: Migrations -→ Proceed to **Step 1**. +#### If the `/workflow-migrate` skill has already been invoked in this conversation + +→ Proceed to **Step 0.3**. #### Otherwise @@ -56,7 +60,11 @@ Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** 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: Knowledge Check Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. diff --git a/skills/continue-quickfix/SKILL.md b/skills/continue-quickfix/SKILL.md index bc89a2968..b8a1e8c9b 100644 --- a/skills/continue-quickfix/SKILL.md +++ b/skills/continue-quickfix/SKILL.md @@ -36,13 +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. -#### If the `/workflow-migrate` skill has already been invoked in this conversation +→ Proceed to **Step 0.2**. -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +### Step 0.2: Migrations -→ Proceed to **Step 1**. +#### If the `/workflow-migrate` skill has already been invoked in this conversation + +→ Proceed to **Step 0.3**. #### Otherwise @@ -56,7 +60,11 @@ Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** 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: Knowledge Check Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. diff --git a/skills/start-bugfix/SKILL.md b/skills/start-bugfix/SKILL.md index bd95bf60e..f253440de 100644 --- a/skills/start-bugfix/SKILL.md +++ b/skills/start-bugfix/SKILL.md @@ -27,29 +27,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. ── Initialisation ─────────────────────────────── ``` -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 +### Step 0.1: Casing Conventions -> *Output the next fenced block as a code block:* - -``` -●───────────────────────────────────────────────● - New Bugfix -●───────────────────────────────────────────────● - -``` +Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written. -> *Output the next fenced block as markdown (not a code block):* +→ Proceed to **Step 0.2**. -``` -> Starting a new bugfix. I'll ask what's broken, suggest a name, -> then hand off to investigation to diagnose the root cause. -``` +### Step 0.2: Migrations -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +#### If the `/workflow-migrate` skill has already been invoked in this conversation -→ Proceed to **Step 1**. +→ Proceed to **Step 0.3**. #### Otherwise @@ -63,7 +51,11 @@ Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** 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:* diff --git a/skills/start-cross-cutting/SKILL.md b/skills/start-cross-cutting/SKILL.md index 2c6dc9ba9..36be54e15 100644 --- a/skills/start-cross-cutting/SKILL.md +++ b/skills/start-cross-cutting/SKILL.md @@ -27,31 +27,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. ── Initialisation ─────────────────────────────── ``` -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 - -> *Output the next fenced block as a code block:* - -``` -●───────────────────────────────────────────────● - New Cross-Cutting Concern -●───────────────────────────────────────────────● +### Step 0.1: Casing Conventions -``` +Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written. -> *Output the next fenced block as markdown (not a code block):* +→ Proceed to **Step 0.2**. -``` -> Starting a new cross-cutting concern. I'll ask what pattern -> or policy you're defining, suggest a name, then you'll choose -> whether to research first or go straight to discussion. The -> pipeline ends at specification — no planning or implementation. -``` +### Step 0.2: Migrations -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +#### If the `/workflow-migrate` skill has already been invoked in this conversation -→ Proceed to **Step 1**. +→ Proceed to **Step 0.3**. #### Otherwise @@ -65,7 +51,11 @@ Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** 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:* diff --git a/skills/start-epic/SKILL.md b/skills/start-epic/SKILL.md index bd9a0e9c6..d1dda6e4b 100644 --- a/skills/start-epic/SKILL.md +++ b/skills/start-epic/SKILL.md @@ -27,30 +27,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. ── Initialisation ─────────────────────────────── ``` -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 +### Step 0.1: Casing Conventions -> *Output the next fenced block as a code block:* - -``` -●───────────────────────────────────────────────● - New Epic -●───────────────────────────────────────────────● +Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written. -``` +→ Proceed to **Step 0.2**. -> *Output the next fenced block as markdown (not a code block):* +### Step 0.2: Migrations -``` -> Starting a new epic. I'll ask what you're building, suggest -> a name, then you'll choose whether to research first or go -> straight to discussion. -``` - -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +#### If the `/workflow-migrate` skill has already been invoked in this conversation -→ Proceed to **Step 1**. +→ Proceed to **Step 0.3**. #### Otherwise @@ -64,7 +51,11 @@ Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** 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:* diff --git a/skills/start-feature/SKILL.md b/skills/start-feature/SKILL.md index f2628bb69..55a58f1ac 100644 --- a/skills/start-feature/SKILL.md +++ b/skills/start-feature/SKILL.md @@ -27,30 +27,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. ── Initialisation ─────────────────────────────── ``` -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 +### Step 0.1: Casing Conventions -> *Output the next fenced block as a code block:* - -``` -●───────────────────────────────────────────────● - New Feature -●───────────────────────────────────────────────● +Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written. -``` +→ Proceed to **Step 0.2**. -> *Output the next fenced block as markdown (not a code block):* +### Step 0.2: Migrations -``` -> Starting a new feature. I'll ask what you're building, suggest -> a name, then you'll choose whether to research first or go straight -> to discussion. -``` - -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +#### If the `/workflow-migrate` skill has already been invoked in this conversation -→ Proceed to **Step 1**. +→ Proceed to **Step 0.3**. #### Otherwise @@ -64,7 +51,11 @@ Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** 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:* diff --git a/skills/start-quickfix/SKILL.md b/skills/start-quickfix/SKILL.md index 7bf2bc1b4..af7dc59a5 100644 --- a/skills/start-quickfix/SKILL.md +++ b/skills/start-quickfix/SKILL.md @@ -27,30 +27,17 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. ── Initialisation ─────────────────────────────── ``` -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 +### Step 0.1: Casing Conventions -> *Output the next fenced block as a code block:* - -``` -●───────────────────────────────────────────────● - New Quick-Fix -●───────────────────────────────────────────────● +Load **[casing-conventions.md](../workflow-shared/references/casing-conventions.md)** and follow its instructions as written. -``` +→ Proceed to **Step 0.2**. -> *Output the next fenced block as markdown (not a code block):* +### Step 0.2: Migrations -``` -> Starting a new quick-fix. I'll ask what needs changing, suggest -> a name, then hand off to scoping — which combines context, spec, -> and plan into a single streamlined pass. -``` - -Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. +#### If the `/workflow-migrate` skill has already been invoked in this conversation -→ Proceed to **Step 1**. +→ Proceed to **Step 0.3**. #### Otherwise @@ -64,7 +51,11 @@ Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** 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:* diff --git a/skills/workflow-start/SKILL.md b/skills/workflow-start/SKILL.md index 07fa57edd..9da2450a7 100644 --- a/skills/workflow-start/SKILL.md +++ b/skills/workflow-start/SKILL.md @@ -48,8 +48,14 @@ 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 + > *Output the next fenced block as markdown (not a code block):* ``` @@ -61,7 +67,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: Knowledge Check Load **[knowledge-check.md](../workflow-shared/references/knowledge-check.md)** and follow its instructions as written. From 502fb622172b285ef6a7babd1207ee8459972b79 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 17:35:27 +0100 Subject: [PATCH 11/15] docs(knowledge): clarify knowledge-check.md summary sentence The previous wording implied compaction is contingent on readiness when it's actually a routine maintenance step that simply requires the store to exist. Reframe as a gate + maintenance pair. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/workflow-shared/references/knowledge-check.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/workflow-shared/references/knowledge-check.md b/skills/workflow-shared/references/knowledge-check.md index ab316c37a..2726d4464 100644 --- a/skills/workflow-shared/references/knowledge-check.md +++ b/skills/workflow-shared/references/knowledge-check.md @@ -4,7 +4,7 @@ --- -Check knowledge base readiness. If not ready, display a hard stop with setup instructions. If ready, run compaction to keep the index lean. +Gate the workflow on knowledge base readiness, then run routine compaction. If the store isn't set up, hard stop with setup instructions. Otherwise, trim any expired chunks so the index stays lean. ## A. Check Readiness From 0b15ed5931b781cc714011b289b798518e993d47 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 17:35:59 +0100 Subject: [PATCH 12/15] docs(knowledge): drop redundant pre-description from knowledge-check.md The summary sentence just restated what the A/B section headings already convey. Structure is self-documenting. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/workflow-shared/references/knowledge-check.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/skills/workflow-shared/references/knowledge-check.md b/skills/workflow-shared/references/knowledge-check.md index 2726d4464..9351ded2f 100644 --- a/skills/workflow-shared/references/knowledge-check.md +++ b/skills/workflow-shared/references/knowledge-check.md @@ -4,8 +4,6 @@ --- -Gate the workflow on knowledge base readiness, then run routine compaction. If the store isn't set up, hard stop with setup instructions. Otherwise, trim any expired chunks so the index stays lean. - ## A. Check Readiness Run the following command and capture its stdout and exit code: From 03036288ac587ea4d568a49c805d40b10250a04c Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 17:41:14 +0100 Subject: [PATCH 13/15] chore(knowledge): replace inline prose conditional with H4 branches in view-completed The previous wording 'If selected.status was cancelled, ...' was inline-prose conditional, which isn't a CLAUDE.md convention. Split into two H4 branches ('reactivate and cancelled' / 'reactivate and completed'), each self-contained with its own body and routing. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../references/view-completed.md | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/skills/workflow-start/references/view-completed.md b/skills/workflow-start/references/view-completed.md index 4c8e8d5dc..0ca332717 100644 --- a/skills/workflow-start/references/view-completed.md +++ b/skills/workflow-start/references/view-completed.md @@ -92,13 +92,29 @@ Store the selected item. **STOP.** Wait for user response. -#### If user chose `r`/`reactivate` +#### If user chose `r`/`reactivate` and `selected.status` is `cancelled` ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} status in-progress ``` -If `selected.status` was `cancelled`, re-index the completed artifacts that were removed during cancellation by loading **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. Completed work units keep their chunks, so no re-indexing is needed in that case. +Cancellation removed the work unit's chunks from the knowledge base. Restore them by loading **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. + +> *Output the next fenced block as a code block:* + +``` +"{selected.name:(titlecase)}" reactivated. +``` + +→ Return to caller. + +#### If user chose `r`/`reactivate` and `selected.status` is `completed` + +```bash +node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} status in-progress +``` + +Completed work units retain their chunks — no re-indexing needed. > *Output the next fenced block as a code block:* From 4e2e8b1bb82d1600273a5d5462eded9cbefe0ab3 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 17:44:22 +0100 Subject: [PATCH 14/15] chore(knowledge): use nested bold conditionals for reactivate status check Previous commit promoted both branches to H4, but the status-based decision is nested inside the reactivate action. CLAUDE.md's nested conditional example uses bold **If X:** for this case. Restore the H4 'If user chose reactivate' as the top level, put the shared status-setting command after it, then branch on previous status via bold conditionals with each branch self-contained. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/workflow-start/references/view-completed.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/skills/workflow-start/references/view-completed.md b/skills/workflow-start/references/view-completed.md index 0ca332717..37471ad16 100644 --- a/skills/workflow-start/references/view-completed.md +++ b/skills/workflow-start/references/view-completed.md @@ -92,12 +92,16 @@ Store the selected item. **STOP.** Wait for user response. -#### If user chose `r`/`reactivate` and `selected.status` is `cancelled` +#### If user chose `r`/`reactivate` + +Set status back to in-progress: ```bash node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} status in-progress ``` +**If `selected.status` was `cancelled`:** + Cancellation removed the work unit's chunks from the knowledge base. Restore them by loading **[reindex-work-unit.md](../workflow-shared/references/reindex-work-unit.md)** with work_unit = `{selected.name}`. > *Output the next fenced block as a code block:* @@ -108,11 +112,7 @@ Cancellation removed the work unit's chunks from the knowledge base. Restore the → Return to caller. -#### If user chose `r`/`reactivate` and `selected.status` is `completed` - -```bash -node .claude/skills/workflow-manifest/scripts/manifest.cjs set {selected.name} status in-progress -``` +**If `selected.status` was `completed`:** Completed work units retain their chunks — no re-indexing needed. From 1f0f08df18020160d40a7e2082f6182859702638 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sat, 18 Apr 2026 18:29:42 +0100 Subject: [PATCH 15/15] feat(knowledge): add migration 037 to close completed_at phasing gap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Migration 036 landed in Phase 4 and ran once. Phase 5 is what adds the skill-code that sets completed_at at completion time. Between the two PRs, any work unit that reached status=completed on main will have no completed_at — invisible to compaction (silent non-compaction). Migration 037 re-runs the same idempotent backfill logic under a new migration ID so it fires once after Phase 5 lands, catching any work units that slipped through the gap. Identical logic to 036; separated only to give the migration orchestrator a reason to run it again. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../migrations/037-completed-at-gap.sh | 94 +++++ tests/scripts/test-migration-037.sh | 320 ++++++++++++++++++ 2 files changed, 414 insertions(+) create mode 100644 skills/workflow-migrate/scripts/migrations/037-completed-at-gap.sh create mode 100644 tests/scripts/test-migration-037.sh diff --git a/skills/workflow-migrate/scripts/migrations/037-completed-at-gap.sh b/skills/workflow-migrate/scripts/migrations/037-completed-at-gap.sh new file mode 100644 index 000000000..8a5e114e8 --- /dev/null +++ b/skills/workflow-migrate/scripts/migrations/037-completed-at-gap.sh @@ -0,0 +1,94 @@ +#!/bin/bash +# +# Migration 037: Close the completed_at gap between Phase 4 and Phase 5 +# +# Migration 036 added completed_at backfill via file mtime. It ran once and +# was logged. Phase 4 shipped that migration but NOT the skill-code changes +# that set completed_at at completion time. Those skill changes shipped in +# Phase 5. +# +# Any work unit that reached status=completed on main after migration 036 +# had already run, but before Phase 5's skill changes landed, will have +# status=completed with no completed_at. Those work units are invisible +# to compaction (silent non-compaction) — their chunks never expire. +# +# This migration re-runs the same idempotent backfill logic under a new +# migration ID to catch any such work units. The logic is intentionally +# identical to 036: skip if completed_at is already set; otherwise derive +# from latest artifact mtime. +# +# Bash 3.2 compatible (no mapfile, declare -A, local -n). +# + +WORKFLOWS_DIR="${PROJECT_DIR:-.}/.workflows" + +[ -d "$WORKFLOWS_DIR" ] || return 0 + +node -e " +const fs = require('fs'); +const path = require('path'); + +const wfDir = process.argv[1]; +const entries = fs.readdirSync(wfDir, { withFileTypes: true }); + +function latestMtime(dir) { + let latest = 0; + function walk(d) { + let items; + try { items = fs.readdirSync(d, { withFileTypes: true }); } catch { return; } + for (const item of items) { + if (item.name === 'manifest.json' || item.name.startsWith('.')) continue; + const full = path.join(d, item.name); + if (item.isDirectory()) { + walk(full); + } else if (item.isFile()) { + try { + const st = fs.statSync(full); + if (st.mtimeMs > latest) latest = st.mtimeMs; + } catch { /* skip unreadable files */ } + } + } + } + walk(dir); + return latest; +} + +function toISODate(ms) { + const d = new Date(ms); + const yyyy = d.getFullYear(); + const mm = String(d.getMonth() + 1).padStart(2, '0'); + const dd = String(d.getDate()).padStart(2, '0'); + return yyyy + '-' + mm + '-' + dd; +} + +for (const entry of entries) { + if (!entry.isDirectory() || entry.name.startsWith('.')) continue; + + const mPath = path.join(wfDir, entry.name, 'manifest.json'); + if (!fs.existsSync(mPath)) continue; + + let m; + try { m = JSON.parse(fs.readFileSync(mPath, 'utf8')); } catch { continue; } + + if (m.status !== 'completed') continue; + if (m.completed_at !== undefined && m.completed_at !== null) continue; + + // Find latest mtime across all artifact files in this work unit dir. + const wuDir = path.join(wfDir, entry.name); + const latest = latestMtime(wuDir); + + if (latest === 0) { + // No files found — skip (do not set a bogus date). + continue; + } + + m.completed_at = toISODate(latest); + fs.writeFileSync(mPath, JSON.stringify(m, null, 2) + '\n'); +} +" "$WORKFLOWS_DIR" 2>/dev/null + +if [ $? -eq 0 ]; then + report_update +else + report_skip +fi diff --git a/tests/scripts/test-migration-037.sh b/tests/scripts/test-migration-037.sh new file mode 100644 index 000000000..900cb7634 --- /dev/null +++ b/tests/scripts/test-migration-037.sh @@ -0,0 +1,320 @@ +#!/bin/bash +# +# Tests for migration 037: Close the completed_at gap between Phase 4 and Phase 5 +# +# Run: bash tests/scripts/test-migration-037.sh +# + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" +MIGRATION="$REPO_DIR/skills/workflow-migrate/scripts/migrations/037-completed-at-gap.sh" + +PASS=0 +FAIL=0 + +report_update() { : ; } +report_skip() { : ; } + +assert_eq() { + local label="$1" expected="$2" actual="$3" + if [ "$expected" = "$actual" ]; then + PASS=$((PASS + 1)) + else + FAIL=$((FAIL + 1)) + echo "FAIL: $label" + echo " expected: $expected" + echo " actual: $actual" + fi +} + +setup() { + TEST_DIR=$(mktemp -d /tmp/migration-037-test.XXXXXX) + export PROJECT_DIR="$TEST_DIR" + mkdir -p "$TEST_DIR/.workflows" +} + +teardown() { + rm -rf "$TEST_DIR" +} + +# --- Test 1: Happy path — completed work unit without completed_at gets backfilled --- +test_happy_path() { + setup + + mkdir -p "$TEST_DIR/.workflows/alpha/discussion" + cat > "$TEST_DIR/.workflows/alpha/manifest.json" <<'JSON' +{ + "name": "alpha", + "work_type": "feature", + "status": "completed", + "phases": {} +} +JSON + + echo "content" > "$TEST_DIR/.workflows/alpha/discussion/alpha.md" + touch -t 202501150930 "$TEST_DIR/.workflows/alpha/discussion/alpha.md" + + source "$MIGRATION" + + local has_field + has_field=$(node -e "const m=JSON.parse(require('fs').readFileSync('$TEST_DIR/.workflows/alpha/manifest.json','utf8')); console.log(m.completed_at !== undefined && m.completed_at !== null)") + assert_eq "completed_at set" "true" "$has_field" + + local value + value=$(node -e "const m=JSON.parse(require('fs').readFileSync('$TEST_DIR/.workflows/alpha/manifest.json','utf8')); console.log(m.completed_at)") + assert_eq "completed_at is ISO date" "2025-01-15" "$value" + + teardown +} + +# --- Test 2: Skip — already has completed_at (036 already set it) --- +test_skip_existing() { + setup + + mkdir -p "$TEST_DIR/.workflows/beta/discussion" + cat > "$TEST_DIR/.workflows/beta/manifest.json" <<'JSON' +{ + "name": "beta", + "work_type": "feature", + "status": "completed", + "completed_at": "2025-03-01", + "phases": {} +} +JSON + echo "content" > "$TEST_DIR/.workflows/beta/discussion/beta.md" + + local before + before=$(cat "$TEST_DIR/.workflows/beta/manifest.json") + + source "$MIGRATION" + + local after + after=$(cat "$TEST_DIR/.workflows/beta/manifest.json") + assert_eq "manifest unchanged" "$before" "$after" + + teardown +} + +# --- Test 3: Skip — in-progress work unit --- +test_skip_in_progress() { + setup + + mkdir -p "$TEST_DIR/.workflows/gamma/discussion" + cat > "$TEST_DIR/.workflows/gamma/manifest.json" <<'JSON' +{ + "name": "gamma", + "work_type": "feature", + "status": "in-progress", + "phases": {} +} +JSON + echo "content" > "$TEST_DIR/.workflows/gamma/discussion/gamma.md" + + local before + before=$(cat "$TEST_DIR/.workflows/gamma/manifest.json") + + source "$MIGRATION" + + local after + after=$(cat "$TEST_DIR/.workflows/gamma/manifest.json") + assert_eq "in-progress not modified" "$before" "$after" + + teardown +} + +# --- Test 4: Skip — cancelled work unit --- +test_skip_cancelled() { + setup + + mkdir -p "$TEST_DIR/.workflows/delta/discussion" + cat > "$TEST_DIR/.workflows/delta/manifest.json" <<'JSON' +{ + "name": "delta", + "work_type": "feature", + "status": "cancelled", + "phases": {} +} +JSON + echo "content" > "$TEST_DIR/.workflows/delta/discussion/delta.md" + + local before + before=$(cat "$TEST_DIR/.workflows/delta/manifest.json") + + source "$MIGRATION" + + local after + after=$(cat "$TEST_DIR/.workflows/delta/manifest.json") + assert_eq "cancelled not modified" "$before" "$after" + + teardown +} + +# --- Test 5: Idempotent — running twice produces same result --- +test_idempotent() { + setup + + mkdir -p "$TEST_DIR/.workflows/echo/specification/echo" + cat > "$TEST_DIR/.workflows/echo/manifest.json" <<'JSON' +{ + "name": "echo", + "work_type": "feature", + "status": "completed", + "phases": {} +} +JSON + echo "spec" > "$TEST_DIR/.workflows/echo/specification/echo/specification.md" + touch -t 202502200800 "$TEST_DIR/.workflows/echo/specification/echo/specification.md" + + source "$MIGRATION" + + local after_first + after_first=$(cat "$TEST_DIR/.workflows/echo/manifest.json") + + source "$MIGRATION" + + local after_second + after_second=$(cat "$TEST_DIR/.workflows/echo/manifest.json") + assert_eq "idempotent" "$after_first" "$after_second" + + teardown +} + +# --- Test 6: Multiple work units — only completed without completed_at --- +test_multiple() { + setup + + mkdir -p "$TEST_DIR/.workflows/one/discussion" + cat > "$TEST_DIR/.workflows/one/manifest.json" <<'JSON' +{ + "name": "one", + "work_type": "feature", + "status": "completed", + "phases": {} +} +JSON + echo "content" > "$TEST_DIR/.workflows/one/discussion/one.md" + touch -t 202503100000 "$TEST_DIR/.workflows/one/discussion/one.md" + + mkdir -p "$TEST_DIR/.workflows/two/discussion" + cat > "$TEST_DIR/.workflows/two/manifest.json" <<'JSON' +{ + "name": "two", + "work_type": "feature", + "status": "in-progress", + "phases": {} +} +JSON + echo "content" > "$TEST_DIR/.workflows/two/discussion/two.md" + + local two_before + two_before=$(cat "$TEST_DIR/.workflows/two/manifest.json") + + source "$MIGRATION" + + local one_has + one_has=$(node -e "const m=JSON.parse(require('fs').readFileSync('$TEST_DIR/.workflows/one/manifest.json','utf8')); console.log(m.completed_at)") + assert_eq "one backfilled" "2025-03-10" "$one_has" + + local two_after + two_after=$(cat "$TEST_DIR/.workflows/two/manifest.json") + assert_eq "two unchanged" "$two_before" "$two_after" + + teardown +} + +# --- Test 7: Content preservation — other fields intact --- +test_content_preservation() { + setup + + mkdir -p "$TEST_DIR/.workflows/foxtrot/research" + cat > "$TEST_DIR/.workflows/foxtrot/manifest.json" <<'JSON' +{ + "name": "foxtrot", + "work_type": "epic", + "status": "completed", + "description": "Important project", + "custom_field": 42, + "phases": { + "research": { + "items": { "topic-a": { "status": "completed" } } + } + } +} +JSON + echo "research" > "$TEST_DIR/.workflows/foxtrot/research/topic-a.md" + touch -t 202504010000 "$TEST_DIR/.workflows/foxtrot/research/topic-a.md" + + source "$MIGRATION" + + local desc + desc=$(node -e "const m=JSON.parse(require('fs').readFileSync('$TEST_DIR/.workflows/foxtrot/manifest.json','utf8')); console.log(m.description)") + assert_eq "description preserved" "Important project" "$desc" + + local custom + custom=$(node -e "const m=JSON.parse(require('fs').readFileSync('$TEST_DIR/.workflows/foxtrot/manifest.json','utf8')); console.log(m.custom_field)") + assert_eq "custom_field preserved" "42" "$custom" + + local topic_status + topic_status=$(node -e "const m=JSON.parse(require('fs').readFileSync('$TEST_DIR/.workflows/foxtrot/manifest.json','utf8')); console.log(m.phases.research.items['topic-a'].status)") + assert_eq "topic status preserved" "completed" "$topic_status" + + teardown +} + +# --- Test 8: No workflows dir --- +test_no_workflows() { + TEST_DIR=$(mktemp -d /tmp/migration-037-test.XXXXXX) + export PROJECT_DIR="$TEST_DIR" + + source "$MIGRATION" + + assert_eq "no crash" "true" "true" + + teardown +} + +# --- Test 9: Empty work unit (no artifact files) — skip --- +test_empty_work_unit() { + setup + + mkdir -p "$TEST_DIR/.workflows/ghost" + cat > "$TEST_DIR/.workflows/ghost/manifest.json" <<'JSON' +{ + "name": "ghost", + "work_type": "feature", + "status": "completed", + "phases": {} +} +JSON + + local before + before=$(cat "$TEST_DIR/.workflows/ghost/manifest.json") + + source "$MIGRATION" + + local after + after=$(cat "$TEST_DIR/.workflows/ghost/manifest.json") + assert_eq "empty work unit unchanged" "$before" "$after" + + teardown +} + +# --- Run all tests --- +echo "Running migration 037 tests..." +echo "" + +test_happy_path +test_skip_existing +test_skip_in_progress +test_skip_cancelled +test_idempotent +test_multiple +test_content_preservation +test_no_workflows +test_empty_work_unit + +echo "" +echo "Results: $PASS passed, $FAIL failed" +[ "$FAIL" -eq 0 ] || exit 1