maestro-flow 0.5.42 → 0.5.44

package/.codex/skills/team-lifecycle-v4/SKILL.md

@@ -130,10 +130,10 @@ id,title,description,role,pipeline_phase,deps,context_from,wave
 | Column | Initial Value | Description |
 |--------|--------------|-------------|
 | `status` | `pending` | Task lifecycle: pending → completed/failed/blocked/skipped |
-| `findings` | `""` | Populated from output_schema merge |
-| `files_modified` | `""` | Populated from output_schema merge |
-| `quality_score` | `""` | Populated from output_schema merge |
-| `error` | `""` | Populated from output_schema merge |
+| `findings` | `""` | Populated from output_schema `result_findings` during merge |
+| `files_modified` | `""` | Populated from output_schema `result_files_modified` during merge |
+| `quality_score` | `""` | Populated from output_schema `result_quality_score` during merge |
+| `error` | `""` | Populated from output_schema `result_error` during merge |
 
 **Dynamic column** (added to wave-N.csv only, not in initial tasks.csv):
 
@@ -146,12 +146,12 @@ id,title,description,role,pipeline_phase,deps,context_from,wave
 | Column | Description |
 |--------|-------------|
 | `result_status` | completed / failed / blocked (maps to master `status`) |
-| `findings` | Key findings (max 500 chars) |
-| `files_modified` | Semicolon-separated paths |
-| `quality_score` | Numeric quality score (0-100) |
-| `error` | Error message if failed |
+| `result_findings` | Key findings (max 500 chars) → maps to master `findings` |
+| `result_files_modified` | Semicolon-separated paths → maps to master `files_modified` |
+| `result_quality_score` | Numeric quality score (0-100) → maps to master `quality_score` |
+| `result_error` | Error message if failed → maps to master `error` |
 
-**Column separation rule**: Input/lifecycle columns and output_schema MUST NOT share names. `result_status` → master `status` during merge.
+**Column separation rule**: Input/lifecycle columns and output_schema MUST NOT share names. Merge mapping: `result_status` → `status`, `result_findings` → `findings`, `result_files_modified` → `files_modified`, `result_quality_score` → `quality_score`, `result_error` → `error`.
 
 ### Pipeline Wave Assignments
 
@@ -201,7 +201,7 @@ spec-only waves 1-8 + user approval checkpoint + impl-only waves shifted.
 6. **Discovery Board is Append-Only**: Never clear/modify discoveries.ndjson
 7. **Cascading Skip on Failure**: Failed tasks cascade to dependents
 8. **Cleanup Temp Files**: Delete wave-N.csv and wave-N-results.csv after merge
-9. **Checkpoint Pause**: After CHECKPOINT waves, pause for user approval (skip if -y)
+9. **Checkpoint Pause**: After CHECKPOINT waves, pause for user approval (skip if -y). Record approval decision in master tasks.csv (`status=approved|revision_requested|aborted`) and persist gate state to `{sessionFolder}/gate-{checkpoint_id}.json`
 10. **DO NOT STOP**: Continuous execution between checkpoints
 11. **Role Files are Authoritative**: Agents read roles/{role}/role.md for domain logic
 </invariants>
@@ -227,9 +227,9 @@ S_WAVE_{N} → S_CHECKPOINT     WHEN: wave N was a CHECKPOINT task
 S_WAVE_{N} → S_WAVE_{N+1}     WHEN: wave N not checkpoint, more waves
 S_WAVE_{N} → S_AGGREGATE      WHEN: last wave complete
 
-S_CHECKPOINT → S_WAVE_{N+1}   WHEN: user approves or -y
-S_CHECKPOINT → S_WAVE_{N}     WHEN: user requests revision (re-run checkpoint)
-S_CHECKPOINT → S_AGGREGATE    WHEN: user aborts
+S_CHECKPOINT → S_WAVE_{N+1}   WHEN: user approves or -y (persist: set CHECKPOINT task status=approved in tasks.csv, write gate-{id}.json)
+S_CHECKPOINT → S_WAVE_{N}     WHEN: user requests revision (persist: set CHECKPOINT task status=revision_requested in tasks.csv, write gate-{id}.json with feedback)
+S_CHECKPOINT → S_AGGREGATE    WHEN: user aborts (persist: set CHECKPOINT task status=aborted in tasks.csv, write gate-{id}.json)
 </transitions>
 
 <actions>
@@ -311,30 +311,37 @@ spawn_agents_on_csv({
   output_schema: {
     type: "object",
     properties: {
-      id:             { type: "string" },
-      result_status:  { type: "string", enum: ["completed", "failed", "blocked"] },
-      findings:       { type: "string", maxLength: 500 },
-      files_modified: { type: "string", description: "Semicolon-separated paths" },
-      quality_score:  { type: "string", description: "0-100" },
-      error:          { type: "string" }
+      id:                    { type: "string" },
+      result_status:         { type: "string", enum: ["completed", "failed", "blocked"] },
+      result_findings:       { type: "string", maxLength: 500 },
+      result_files_modified: { type: "string", description: "Semicolon-separated paths" },
+      result_quality_score:  { type: "string", description: "0-100" },
+      result_error:          { type: "string" }
     },
-    required: ["id", "result_status", "findings"]
+    required: ["id", "result_status", "result_findings"]
   }
 })
 ```
 
 #### Step 5: Merge + Cleanup
 1. Map `result_status` → master `status`
-2. Copy `findings`, `files_modified`, `quality_score`, `error`
+2. Map `result_findings` → master `findings`, `result_files_modified` → master `files_modified`, `result_quality_score` → master `quality_score`, `result_error` → master `error`
 3. Delete `wave-{N}.csv` AND `wave-{N}-results.csv`
 4. Cascade skip failed task dependents
 
 #### Step 6: Checkpoint handling
 If wave N was a CHECKPOINT task:
-- Read supervisor's `findings` and `quality_score`
+- Read supervisor's `result_findings` and `result_quality_score`
 - If quality_score >= 80 (pass) → continue
 - If 60-79 (review) → display warnings, continue (or pause if not -y)
 - If < 60 (fail) → pause for user: Revise / Override / Abort
+- **Persist approval decision**:
+  1. Update CHECKPOINT task `status` in master tasks.csv to `approved` / `revision_requested` / `aborted`
+  2. Write `{sessionFolder}/gate-{checkpoint_id}.json`:
+     ```json
+     {"checkpoint_id":"<id>","decision":"approved|revision_requested|aborted","quality_score":<N>,"feedback":"<user feedback if any>","timestamp":"<ISO>"}
+     ```
+  3. On `--continue` resume, read gate files to restore checkpoint state
 
 ### Instruction Builder
 
@@ -393,10 +400,10 @@ Append to {sessionFolder}/discoveries.ndjson:
 ## Output
 Return via output_schema:
 - result_status: completed | failed | blocked
-- findings: key findings (max 500 chars)
-- files_modified: semicolon-separated paths
-- quality_score: 0-100 per quality-gates.md
-- error: error message if not completed
+- result_findings: key findings (max 500 chars)
+- result_files_modified: semicolon-separated paths
+- result_quality_score: 0-100 per quality-gates.md
+- result_error: error message if not completed
 ```
 
 ### Results Aggregation (S_AGGREGATE)

package/.codex/skills/team-quality-assurance/SKILL.md

@@ -156,6 +156,49 @@ S_WAVE_{N} → S_AGGREGATE     WHEN: last wave
 
 <actions>
 
+### Session Initialization (S_PARSE)
+
+```
+Parse from $ARGUMENTS:
+  AUTO_YES       ← --yes | -y
+  continueMode   ← --continue
+  maxConcurrency ← --concurrency | -c N  (default: 3)
+  modeFlag       ← --mode discovery|testing|full
+  scopeTarget    ← remaining text (file/module path)
+
+Derive:
+  dateStr       ← UTC+8 YYYYMMDD
+  slug          ← first 3 meaningful words, kebab-case
+  sessionId     ← "{dateStr}-qa-{slug}"
+  sessionFolder ← ".workflow/.csv-wave/{sessionId}"
+  skillRoot     ← resolve path to this skill directory
+
+mkdir -p {sessionFolder}
+```
+
+When `--continue`: scan `.workflow/.csv-wave/*-qa-*/tasks.csv` for sessions with pending tasks. Single match → resume. Multiple → `request_user_input`. Read master tasks.csv → find first pending wave → jump to S_WAVE_{N}.
+
+### CSV Generation (S_CSV_GEN)
+
+1. Select mode: `--mode` flag, or detect from scope (single module → discovery, test files exist → testing, else → full)
+2. Load pipeline wave assignments from csv_schema section above
+3. For each task, build CSV row with PURPOSE/TASK/EXPECTED/CONSTRAINTS in description
+4. Initialize lifecycle columns: `status=pending`, empty `findings`/`files_modified`/`coverage_score`/`error`
+5. Write `tasks.csv` and empty `discoveries.ndjson`
+6. User validation (skip if `-y`): display mode, task count, wave structure
+
+### Wave Execution (S_WAVE_{N})
+
+1. Skip check: if all tasks in wave N completed/skipped → next wave
+2. Cascading skip: if any dep is failed/blocked → skip dependents
+3. Build `prev_context` from upstream findings
+4. Write `wave-{N}.csv` with qualifying rows + `prev_context` column
+5. `spawn_agents_on_csv` with output_schema (see below)
+6. Merge results: `result_status` → master `status`
+7. Cascade skip failed task dependents
+8. Delete `wave-{N}.csv` and `wave-{N}-results.csv`
+9. If wave was QARUN → transition to S_GC_CHECK
+
 ### GC Loop
 
 After each QARUN wave:

package/.codex/skills/team-review/SKILL.md

@@ -117,7 +117,7 @@ id,title,description,role,review_dimension,deps,context_from,wave
 1. **Wave Order Sacred**
 2. **CSV Source of Truth**
 3. **Column Separation Rule**
-4. **User Checkpoint Before Fix**: In full mode, pause after REV for user approval (skip if -y)
+4. **User Checkpoint Before Fix**: In full mode, pause after REV for user approval (skip if -y; when `-y` is set, default fix scope is `critical+high` severity only)
 5. **0 Findings Shortcut**: If scanner finds 0 issues → skip REV and FIX
 6. **Discovery Board Append-Only**
 7. **Cleanup Temp Files**
@@ -141,21 +141,65 @@ S_CSV_GEN → S_WAVE_1
 S_WAVE_{N} → S_FIX_GATE       WHEN: mode=full, REV wave complete, FIX pending
 S_WAVE_{N} → S_WAVE_{N+1}     WHEN: more waves
 S_WAVE_{N} → S_AGGREGATE      WHEN: last wave or 0 findings shortcut
-S_FIX_GATE → S_WAVE_{N+1}     WHEN: user selects fix scope (all/critical+high)
+S_FIX_GATE → S_WAVE_{N+1}     WHEN: user selects fix scope (all/critical+high), or -y (default: critical+high)
 S_FIX_GATE → S_AGGREGATE      WHEN: user selects skip
 </transitions>
 
 <actions>
 
+### Session Initialization (S_PARSE)
+
+```
+Parse from $ARGUMENTS:
+  AUTO_YES       ← --yes | -y
+  continueMode   ← --continue
+  maxConcurrency ← --concurrency | -c N  (default: 3)
+  modeFlag       ← --mode default|full|fix-only|quick
+  scopeTarget    ← remaining text (file/module path)
+
+Derive:
+  dateStr       ← UTC+8 YYYYMMDD
+  slug          ← first 3 meaningful words, kebab-case
+  sessionId     ← "{dateStr}-rv-{slug}"
+  sessionFolder ← ".workflow/.csv-wave/{sessionId}"
+  skillRoot     ← resolve path to this skill directory
+
+mkdir -p {sessionFolder}
+```
+
+When `--continue`: scan `.workflow/.csv-wave/*-rv-*/tasks.csv` for sessions with pending tasks. Single match → resume. Multiple → `request_user_input`. Read master tasks.csv → find first pending wave → jump to S_WAVE_{N}.
+
+### Mode Selection + CSV Generation (S_CSV_GEN)
+
+1. Select mode: `--mode` flag, or default to `default`
+2. Load pipeline wave assignments from csv_schema section above
+3. For each task, build CSV row with PURPOSE/TASK/EXPECTED/CONSTRAINTS in description
+4. Initialize lifecycle columns: `status=pending`, empty `findings`/`files_modified`/`finding_count`/`verdict`/`error`
+5. Write `tasks.csv` and empty `discoveries.ndjson`
+6. User validation (skip if `-y`): display mode, task count, scope
+
+### Wave Execution (S_WAVE_{N})
+
+1. Skip check: if all tasks in wave N completed/skipped → next wave
+2. Cascading skip: if any dep is failed/blocked → skip dependents
+3. Build `prev_context` from upstream findings
+4. Write `wave-{N}.csv` with qualifying rows + `prev_context` column
+5. `spawn_agents_on_csv` with output_schema (see below)
+6. Merge results: `result_status` → master `status`
+7. Cascade skip failed task dependents
+8. Delete `wave-{N}.csv` and `wave-{N}-results.csv`
+9. If mode=full and REV wave complete → transition to S_FIX_GATE
+
 ### Fix Gate Logic
 
 After REV wave in full mode:
 1. Read reviewer's `findings` and `verdict`
 2. If `finding_count` = 0 or verdict = APPROVE → skip fix, aggregate
-3. Display findings summary to user
-4. `request_user_input`: Fix all / Fix critical+high only / Skip fixes
-5. Update FIX-001 description with approved scope
-6. Continue to FIX wave
+3. If `-y` → auto-select fix scope = `critical+high` (default), update FIX-001 description, continue to FIX wave
+4. Otherwise display findings summary to user
+5. `request_user_input`: Fix all / Fix critical+high only / Skip fixes
+6. Update FIX-001 description with approved scope
+7. Continue to FIX wave
 
 ### Instruction Builder
 

package/.codex/skills/team-tech-debt/SKILL.md

@@ -78,7 +78,7 @@ id,title,description,role,scan_dimension,deps,context_from,wave
 | `result_status` | completed / failed / blocked |
 | `findings` | Key findings (max 500 chars) |
 | `files_modified` | Semicolon-separated paths |
-| `debt_count` | Number of debt items found/fixed |
+| `debt_count` | Number of debt items found/fixed (string type, e.g. "5") |
 | `regression_detected` | true/false (for TDVAL tasks) |
 | `error` | Error message |
 
@@ -136,6 +136,7 @@ S_CSV_GEN     — Generate tasks.csv
 S_WAVE_{N}    — Execute wave N
 S_PLAN_GATE   — User approval of remediation plan
 S_GC_CHECK    — Regression check after TDVAL
+S_DEGRADED_AGGREGATE — Aggregate partial results after GC exhaustion (regression persists)
 S_AGGREGATE   — Generate report
 </states>
 
@@ -149,12 +150,57 @@ S_WAVE_{N} → S_AGGREGATE       WHEN: last wave
 S_PLAN_GATE → S_WAVE_{N+1}     WHEN: user approves
 S_PLAN_GATE → S_WAVE_{N}       WHEN: user requests revision (re-run TDPLAN with feedback)
 S_PLAN_GATE → S_AGGREGATE      WHEN: user aborts
-S_GC_CHECK → S_AGGREGATE       WHEN: no regression or gc_rounds >= 3
-S_GC_CHECK → S_WAVE_{N+1}      WHEN: regression, add TDFIX+TDVAL rows
+S_GC_CHECK → S_AGGREGATE           WHEN: no regression (clean pass)
+S_GC_CHECK → S_WAVE_{N+1}          WHEN: regression AND gc_rounds < 3 (add TDFIX+TDVAL rows)
+S_GC_CHECK → S_DEGRADED_AGGREGATE  WHEN: regression AND gc_rounds >= 3 (aggregate partial results with regression warning)
 </transitions>
 
 <actions>
 
+### Session Initialization (S_PARSE)
+
+```
+Parse from $ARGUMENTS:
+  AUTO_YES       ← --yes | -y
+  continueMode   ← --continue
+  maxConcurrency ← --concurrency | -c N  (default: 3)
+  modeFlag       ← --mode scan|remediate|targeted
+  scopeTarget    ← remaining text (file/module path)
+
+Derive:
+  dateStr       ← UTC+8 YYYYMMDD
+  slug          ← first 3 meaningful words, kebab-case
+  sessionId     ← "{dateStr}-td-{slug}"
+  sessionFolder ← ".workflow/.csv-wave/{sessionId}"
+  skillRoot     ← resolve path to this skill directory
+
+mkdir -p {sessionFolder}
+```
+
+When `--continue`: scan `.workflow/.csv-wave/*-td-*/tasks.csv` for sessions with pending tasks. Single match → resume. Multiple → `request_user_input`. Read master tasks.csv → find first pending wave → jump to S_WAVE_{N}.
+
+### Mode Selection + CSV Generation (S_CSV_GEN)
+
+1. Select mode: `--mode` flag, or detect from scope (no existing scan → scan, existing scan results → remediate, specific debt items → targeted)
+2. Load pipeline wave assignments from csv_schema section above
+3. For each task, build CSV row with PURPOSE/TASK/EXPECTED/CONSTRAINTS in description
+4. Initialize lifecycle columns: `status=pending`, empty `findings`/`files_modified`/`debt_count`/`regression_detected`/`error`
+5. Write `tasks.csv` and empty `discoveries.ndjson`
+6. User validation (skip if `-y`): display mode, task count, wave structure
+
+### Wave Execution (S_WAVE_{N})
+
+1. Skip check: if all tasks in wave N completed/skipped → next wave
+2. Cascading skip: if any dep is failed/blocked → skip dependents
+3. Build `prev_context` from upstream findings
+4. Write `wave-{N}.csv` with qualifying rows + `prev_context` column
+5. `spawn_agents_on_csv` with output_schema (see below)
+6. Merge results: `result_status` → master `status`
+7. Cascade skip failed task dependents
+8. Delete `wave-{N}.csv` and `wave-{N}-results.csv`
+9. If TDPLAN wave complete → transition to S_PLAN_GATE
+10. If TDVAL wave complete → transition to S_GC_CHECK
+
 ### Plan Gate
 
 After TDPLAN wave:
@@ -169,9 +215,9 @@ After TDPLAN wave:
 
 After TDVAL wave:
 1. Read `regression_detected` from results
-2. No regression → complete
-3. Regression AND gc_rounds < 3 → add TDFIX+TDVAL rows, iterate
-4. gc_rounds >= 3 → escalate to user
+2. No regression → S_AGGREGATE (clean pass)
+3. Regression AND gc_rounds < 3 → add TDFIX+TDVAL rows to tasks.csv, increment wave, iterate
+4. Regression AND gc_rounds >= 3 → S_DEGRADED_AGGREGATE (aggregate partial results with regression warning, escalate to user)
 
 ### Instruction Builder
 
@@ -202,7 +248,7 @@ Return JSON:
   "result_status": "completed" | "failed" | "blocked",
   "findings": "<key findings, max 500 chars>",
   "files_modified": "<semicolon-separated paths or empty>",
-  "debt_count": <integer or empty>,
+  "debt_count": "<integer as string or empty>",
   "regression_detected": "true" | "false" | "" (TDVAL only),
   "error": "<message if not completed>"
 }

package/.codex/skills/team-testing/SKILL.md

@@ -161,6 +161,54 @@ S_WAVE_{N} → S_AGGREGATE     WHEN: last wave
 
 <actions>
 
+### Session Initialization (S_PARSE)
+
+```
+Parse from $ARGUMENTS:
+  AUTO_YES       ← --yes | -y
+  continueMode   ← --continue
+  maxConcurrency ← --concurrency | -c N  (default: 3)
+  pipelineFlag   ← --pipeline targeted|standard|comprehensive
+  scopeTarget    ← remaining text (file/module path)
+
+Derive:
+  dateStr       ← UTC+8 YYYYMMDD
+  slug          ← first 3 meaningful words, kebab-case
+  sessionId     ← "{dateStr}-tst-{slug}"
+  sessionFolder ← ".workflow/.csv-wave/{sessionId}"
+  skillRoot     ← resolve path to this skill directory
+
+mkdir -p {sessionFolder}
+```
+
+When `--continue`: scan `.workflow/.csv-wave/*-tst-*/tasks.csv` for sessions with pending tasks. Single match → resume. Multiple → `request_user_input`. Read master tasks.csv → find first pending wave → jump to S_WAVE_{N}.
+
+### Scope Detection + Pipeline Selection (S_CSV_GEN)
+
+1. If `--pipeline` flag → use specified pipeline
+2. Else detect from scope:
+   - Count files and modules in scopeTarget
+   - ≤3 files, ≤1 module → `targeted`
+   - ≤10 files, ≤3 modules → `standard`
+   - >10 files or >3 modules → `comprehensive`
+3. Load pipeline wave assignments from csv_schema section above
+4. For each task, build CSV row with PURPOSE/TASK/EXPECTED/CONSTRAINTS in description
+5. Initialize lifecycle columns: `status=pending`, empty `findings`/`files_modified`/`pass_rate`/`coverage_score`/`error`
+6. Write `tasks.csv` and empty `discoveries.ndjson`
+7. User validation (skip if `-y`): display pipeline, task count, layer coverage targets
+
+### Wave Execution (S_WAVE_{N})
+
+1. Skip check: if all tasks in wave N completed/skipped → next wave
+2. Cascading skip: if any dep is failed/blocked → skip dependents
+3. Build `prev_context` from upstream findings
+4. Write `wave-{N}.csv` with qualifying rows + `prev_context` column
+5. `spawn_agents_on_csv` with output_schema (see below)
+6. Merge results: `result_status` → master `status`
+7. Cascade skip failed task dependents
+8. Delete `wave-{N}.csv` and `wave-{N}-results.csv`
+9. If wave was TESTRUN → transition to S_GC_CHECK
+
 ### GC Loop
 
 After each TESTRUN wave:
@@ -197,7 +245,7 @@ You MUST call report_agent_job_result EXACTLY ONCE before exiting. NO exceptions
   "result_status": "completed" | "failed" | "blocked",
   "findings": "<key findings, max 500 chars>",
   "files_modified": "<semicolon-separated paths or empty>",
-  "pass_rate": "<0-100 or empty>" (TESTRUN only),
+  "pass_rate": "<0.0-1.0 or empty>" (TESTRUN only),
   "coverage_score": "<0-100 or empty>" (TESTRUN only),
   "error": "<message if not completed>"
 }
@@ -217,7 +265,7 @@ You MUST call report_agent_job_result EXACTLY ONCE before exiting. NO exceptions
     "result_status":  { "type": "string", "enum": ["completed", "failed", "blocked"] },
     "findings":       { "type": "string", "maxLength": 500 },
     "files_modified": { "type": "string" },
-    "pass_rate":      { "type": "string" },
+    "pass_rate":      { "type": "string", "description": "0.0-1.0 ratio, e.g. 0.95" },
     "coverage_score": { "type": "string" },
     "error":          { "type": "string" }
   },

package/.codex/skills/wiki-connect/SKILL.md

@@ -43,7 +43,9 @@ Display ranked suggestions with scores, reasons, projected health delta.
 If not `--fix`: display and exit.
 
 ### Stage 5: Apply (--fix only)
-For each suggestion: get entry → append target to `related` → update via `maestro wiki update`.
+**Confirmation gate**: Before applying, present the list of link changes to user via `request_user_input` for confirmation. Only proceed with user-approved changes. Skip confirmation only if `-y` flag is also set.
+
+For each approved suggestion: get entry → append target to `related` → update via `maestro wiki update`.
 Re-run `maestro wiki health` for delta.
 
 ### Stage 6: Persist

package/.codex/skills/wiki-digest/SKILL.md

@@ -26,7 +26,7 @@ $ARGUMENTS — scope and optional flags.
 - `--format full` — Detailed with per-entry summaries
 - `--create-issues` — Auto-create knowledge-gap issues in issues.jsonl
 
-**Output**: `.workflow/knowhow/KNW-digest-{slug}-{date}.md`
+**Output**: `.workflow/knowhow/digest-{slug}-{date}.md`
 </context>
 
 <execution>
@@ -54,10 +54,12 @@ knowhow       █░░░░      ██░░░      ████░
 Empty cells = knowledge gaps.
 
 ### Stage 6: Write Digest
-Produce `digest-{slug}-{date}.md` with themes, heatmap, gaps, unlinked insights, recommended actions.
+Produce `.workflow/knowhow/digest-{slug}-{date}.md` with themes, heatmap, gaps, unlinked insights, recommended actions.
 
 ### Stage 7: Gap → Issue (if --create-issues)
-For each gap: dedup against issues.jsonl, append with `type: "knowledge-gap"`, `source: "wiki-digest"`.
+**Confirmation gate**: Before creating issues, present the list of proposed gap issues to user via `request_user_input` for confirmation. Only create user-approved issues. Skip confirmation only if `-y` flag is also set.
+
+For each approved gap: dedup against issues.jsonl, append with `type: "knowledge-gap"`, `source: "wiki-digest"`.
 
 ### Stage 8: Persist
 Append meta-insights to `specs/learnings.md` (source: "wiki-digest"). Display summary.
@@ -82,6 +84,6 @@ Append meta-insights to `specs/learnings.md` (source: "wiki-digest"). Display su
 - [ ] Cross-reference with specs/learnings.md completed
 - [ ] Coverage heatmap generated
 - [ ] If --create-issues: gap issues created (deduped)
-- [ ] Digest written to `KNW-digest-{slug}-{date}.md`
+- [ ] Digest written to `.workflow/knowhow/digest-{slug}-{date}.md`
 - [ ] Meta-insights appended to specs/learnings.md
 </success_criteria>

package/dashboard/dist-server/dashboard/src/server/wiki/embedding.d.ts

@@ -13,6 +13,7 @@ export interface EmbeddingIndex {
     docIds: string[];
     vectors: Float32Array[];
     contentHashes?: string[];
+    chunkDocIds?: string[];
     builtAt: number;
     deviceUsed?: string;
     buildTimeMs?: number;
@@ -89,6 +90,11 @@ export declare function getUnavailableReason(): string | null;
 export declare function embedTexts(texts: string[]): Promise<Float32Array[]>;
 export declare function embedQuery(query: string): Promise<Float32Array>;
 export declare function vectorSearch(queryVector: Float32Array, index: EmbeddingIndex, limit: number): VectorSearchResult[];
+/**
+ * Async vector search using zvec collection.
+ * Falls back to flat cosine scan when zvec is unavailable or feature flag is set.
+ */
+export declare function vectorSearchZvec(queryVector: Float32Array, dir: string, limit: number): Promise<VectorSearchResult[]>;
 export declare function saveEmbeddingIndex(index: EmbeddingIndex, dir: string): void;
 export declare function loadEmbeddingIndex(dir: string): EmbeddingIndex | null;
 export interface DocForEmbedding {
@@ -99,5 +105,15 @@ export interface DocForEmbedding {
     body?: string;
 }
 export declare function hashDocContent(d: DocForEmbedding): string;
+/**
+ * Split a document into multiple chunks for embedding.
+ * Short docs (<500 chars body) produce a single chunk.
+ * Long docs are split by markdown heading regex /^#{1,3}\s/m, max 5 chunks.
+ * Each chunk inherits title+summary as context prefix.
+ */
+export declare function splitDocToChunks(d: DocForEmbedding): Array<{
+    chunkId: string;
+    text: string;
+}>;
 export declare function buildEmbeddingIndex(docs: DocForEmbedding[], existingIndex?: EmbeddingIndex | null, precomputedHashes?: string[]): Promise<EmbeddingIndex>;
 export {};