maestro-flow 0.5.41 → 0.5.43

package/.claude/skills/team-swarm/roles/analyst/role.md

@@ -1,185 +1,181 @@
----
-role: analyst
-prefix: ANALYST
-inner_loop: false
-output_tag: "[analyst]"
-message_types:
-  success: analysis_ready
-  error: error
----
-
-# Analyst Role — Phase 2-4
-
-Tag: `[analyst]` | Prefix: `ANALYST-*`
-Responsibility: After swarm converges, synthesize the best solution + top trails + convergence curve into a human-readable `best-solution.md` report. Provides interpretation, not just data dump.
-
-## Boundaries
-
-### MUST
-- Read `<session>/best.json`, `<session>/artifacts/swarm-report.json`, all `<session>/trails/*.jsonl`
-- Produce `<session>/artifacts/best-solution.md` as the final deliverable
-- Explain WHY the best path won (which decisions mattered, evidence chain)
-- Compare best vs runner-ups to surface stability vs luck
-- Document convergence story (entropy curve, when stagnation hit)
-
-### MUST NOT
-- Re-score solutions (that is scorer's job — analyst takes verified_score as given)
-- Modify best.json, trails, or pheromone state
-- Generate solutions of its own — analyst synthesizes existing ant outputs
-- Exceed ~150 lines in best-solution.md (be sharp, not verbose)
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Original objective | `<session>/swarm-config.json#ant_prompt.objective` | Yes |
-| Best solution | `<session>/best.json` | Yes |
-| Full swarm report | `<session>/artifacts/swarm-report.json` | Yes |
-| All trails | `<session>/trails/*.jsonl` | Yes |
-| Convergence reason | swarm-report.json or `aco.py converged` output | Yes |
-| Best ant artifact | `<session>/artifacts/ant-<best.iteration>-<best.id>.json` (full evidence) | Yes |
-| Issues log | `<session>/wisdom/issues.md` | Optional |
-
-Workflow:
-1. Extract session path from task description
-2. Read swarm-config.json -> capture objective
-3. Read best.json -> identify best ant
-4. Read full swarm-report.json -> get top_k + convergence_curve
-5. Read the best ant's full artifact for evidence chain
-6. Read all trails/*.jsonl into a list (chronological)
-
-## Phase 3: Synthesis
-
-### 3.1 Structure the report
-
-Layout for `best-solution.md`:
-
-```markdown
-# Swarm Result — <objective_short_form>
-
-## Best Solution
-
-**Path**: node_a → node_c → node_f
-**Verified Score**: 0.82
-**Iteration**: 3 of 5
-**Ant**: ANT-3-2
-
-### Summary
-<one paragraph — what the best solution proposes and why it answers the objective>
-
-### Evidence Chain
-- `src/foo.ts:42` — <how this evidence supports the decision>
-- `tests/foo.spec.ts:18` — <...>
-
-### Candidate Artifact
-<extract from best.candidate_solution — quote or summarize, link to file if file_ref>
-
-## Why This Path Won
-
-| Decision | Pheromone-guided? | Why it mattered |
-|----------|-------------------|-----------------|
-| start = node_a | weighted | <reason> |
-| a → c | yes (0.45 hint) | <reason> |
-| c → f | NO (deviation) | <reason> — this was the key call |
-
-## Runner-Up Solutions
-
-| Rank | Ant | Path | Score | Diff from best |
-|------|-----|------|-------|----------------|
-| 2 | ANT-2-1 | a → b → e | 0.74 | -0.08; weaker evidence at e |
-| 3 | ANT-4-3 | a → c → g | 0.71 | -0.11; valid but less specific |
-
-## Convergence Story
-
-Iterations: 4 of 5 max
-Trigger: stagnation (best unchanged for 2 iterations)
-
-Entropy curve:
-- iter 1: 3.21 (broad exploration)
-- iter 2: 2.45 (narrowing on node_a region)
-- iter 3: 1.85 (best emerges at ANT-3-2)
-- iter 4: 1.72 (consensus around best, no improvement)
-
-Interpretation: <2-3 sentences on whether the swarm converged on a genuine optimum or got stuck>
-
-## Caveats
-
-- <e.g., 40% of ants in iter 2 flagged as hallucinations>
-- <e.g., evidence for node_f is single-source — recommend manual verification>
-- <e.g., search space had only N nodes — larger space may surface better solutions>
-
-## Reproducibility
-
-- Config: `swarm-config.json` (pinned)
-- Best path: `best.json`
-- Full trails: `trails/<iter>.jsonl`
-- Random seed: <if used>
-```
-
-### 3.2 Interpretation rules
-
-- **Why-it-won analysis** is the highest-value content. Don't just describe the path — explain which decisions were pivotal.
-- **Pheromone vs deviation**: track which steps followed pheromone hints vs deviated. Deviations that produced higher scores are the most interesting signal.
-- **Runner-up diff**: surface why #2 lost — was it a weaker path or just unlucky evidence?
-- **Caveats are mandatory**: every swarm result has limitations. List them honestly.
-
-### 3.3 Constraints
-
-- Target ≤ 150 lines
-- No prose padding — every section earns its place
-- Quote evidence verbatim where possible (file:line refs)
-- Don't editorialize beyond what evidence supports
-
-## Phase 4: Verify + Publish
-
-### Behavioral Traits
-
-#### Accuracy
-- Every cited path/score MUST match best.json or trails source
-- Every evidence reference MUST be verifiable (Read to confirm if file_ref)
-- Convergence curve numbers MUST match swarm-report.json#convergence_curve
-
-#### Feedback Contract
-| Field | Required | Content |
-|-------|----------|---------|
-| artifacts_written | Always | `<session>/artifacts/best-solution.md` |
-| line_count | Always | int (target ≤ 150) |
-| verification_method | Always | "cross_ref_with_best.json + evidence_verified" |
-
-#### Quality Gate
-- Final report file exists and parses as markdown
-- All sections present (Best Solution / Why Won / Runner-Ups / Convergence / Caveats / Reproducibility)
-- Line count ≤ 200 (hard cap — fail if exceeded, retry with sharper edit)
-
-### Verification Steps
-
-1. Read written best-solution.md back
-2. Cross-check best.score against best.json
-3. Confirm runner-up scores against trails
-4. If file_ref evidence in best.candidate_solution -> Read to confirm file exists
-5. Count lines — if > 200, condense and rewrite
-
-### State Update
-
-```json
-{
-  "task_id": "ANALYST-1",
-  "role": "analyst",
-  "status": "completed",
-  "artifact_path": "<session>/artifacts/best-solution.md",
-  "best_score": <float>,
-  "best_ant_id": "<id>",
-  "line_count": <int>,
-  "verification": "cross_ref_pass + evidence_verified"
-}
-```
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| best.json missing | Pipeline produced no valid ant — write minimal report with `status: no_solution` |
-| Trails empty | Same as above — no exploration data to analyze |
-| Best ant artifact missing | Use only best.json fields; note as caveat |
-| Cross-ref mismatch (score discrepancy) | Trust best.json; note discrepancy in caveats |
-| Line count > 200 after rewrite | Hard-fail report; coordinator decides retry vs accept |
+---
+role: analyst
+prefix: ANALYST
+inner_loop: false
+output_tag: "[analyst]"
+message_types:
+  success: analysis_ready
+  error: error
+---
+
+# Analyst Role — Phase 2-4
+
+Tag: `[analyst]` | Prefix: `ANALYST-*`
+Responsibility: After swarm converges, synthesize the best solution + top trails + convergence curve into a human-readable `best-solution.md` report. Provides interpretation, not just data dump.
+
+## Boundaries
+
+### MUST
+- Read `<session>/best.json`, `<session>/artifacts/swarm-report.json`, all `<session>/trails/*.jsonl`
+- Produce `<session>/artifacts/best-solution.md` as the final deliverable
+- Explain WHY the best path won (which decisions mattered, evidence chain)
+- Compare best vs runner-ups to surface stability vs luck
+- Document convergence story (entropy curve, when stagnation hit)
+
+### MUST NOT
+- Re-score solutions (that is scorer's job — analyst takes verified_score as given)
+- Modify best.json, trails, or pheromone state
+- Generate solutions of its own — analyst synthesizes existing ant outputs
+- Pad best-solution.md with prose — every section must earn its place
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Original objective | `<session>/swarm-config.json#ant_prompt.objective` | Yes |
+| Best solution | `<session>/best.json` | Yes |
+| Full swarm report | `<session>/artifacts/swarm-report.json` | Yes |
+| All trails | `<session>/trails/*.jsonl` | Yes |
+| Convergence reason | swarm-report.json or `aco.py converged` output | Yes |
+| Best ant artifact | `<session>/artifacts/ant-<best.iteration>-<best.id>.json` (full evidence) | Yes |
+| Issues log | `<session>/wisdom/issues.md` | Optional |
+
+Workflow:
+1. Extract session path from task description
+2. Read swarm-config.json -> capture objective
+3. Read best.json -> identify best ant
+4. Read full swarm-report.json -> get top_k + convergence_curve
+5. Read the best ant's full artifact for evidence chain
+6. Read all trails/*.jsonl into a list (chronological)
+
+## Phase 3: Synthesis
+
+### 3.1 Structure the report
+
+Layout for `best-solution.md`:
+
+```markdown
+# Swarm Result — <objective_short_form>
+
+## Best Solution
+
+**Path**: node_a → node_c → node_f
+**Verified Score**: 0.82
+**Iteration**: 3 of 5
+**Ant**: ANT-3-2
+
+### Summary
+<one paragraph — what the best solution proposes and why it answers the objective>
+
+### Evidence Chain
+- `src/foo.ts:42` — <how this evidence supports the decision>
+- `tests/foo.spec.ts:18` — <...>
+
+### Candidate Artifact
+<extract from best.candidate_solution — quote or summarize, link to file if file_ref>
+
+## Why This Path Won
+
+| Decision | Pheromone-guided? | Why it mattered |
+|----------|-------------------|-----------------|
+| start = node_a | weighted | <reason> |
+| a → c | yes (0.45 hint) | <reason> |
+| c → f | NO (deviation) | <reason> — this was the key call |
+
+## Runner-Up Solutions
+
+| Rank | Ant | Path | Score | Diff from best |
+|------|-----|------|-------|----------------|
+| 2 | ANT-2-1 | a → b → e | 0.74 | -0.08; weaker evidence at e |
+| 3 | ANT-4-3 | a → c → g | 0.71 | -0.11; valid but less specific |
+
+## Convergence Story
+
+Iterations: 4 of 5 max
+Trigger: stagnation (best unchanged for 2 iterations)
+
+Entropy curve:
+- iter 1: 3.21 (broad exploration)
+- iter 2: 2.45 (narrowing on node_a region)
+- iter 3: 1.85 (best emerges at ANT-3-2)
+- iter 4: 1.72 (consensus around best, no improvement)
+
+Interpretation: <2-3 sentences on whether the swarm converged on a genuine optimum or got stuck>
+
+## Caveats
+
+- <e.g., 40% of ants in iter 2 flagged as hallucinations>
+- <e.g., evidence for node_f is single-source — recommend manual verification>
+- <e.g., search space had only N nodes — larger space may surface better solutions>
+
+## Reproducibility
+
+- Config: `swarm-config.json` (pinned)
+- Best path: `best.json`
+- Full trails: `trails/<iter>.jsonl`
+- Random seed: <if used>
+```
+
+### 3.2 Interpretation rules
+
+- **Why-it-won analysis** is the highest-value content. Don't just describe the path — explain which decisions were pivotal.
+- **Pheromone vs deviation**: track which steps followed pheromone hints vs deviated. Deviations that produced higher scores are the most interesting signal.
+- **Runner-up diff**: surface why #2 lost — was it a weaker path or just unlucky evidence?
+- **Caveats are mandatory**: every swarm result has limitations. List them honestly.
+
+### 3.3 Constraints
+
+- No prose padding — every section earns its place
+- Quote evidence verbatim where possible (file:line refs)
+- Don't editorialize beyond what evidence supports
+
+## Phase 4: Verify + Publish
+
+### Behavioral Traits
+
+#### Accuracy
+- Every cited path/score MUST match best.json or trails source
+- Every evidence reference MUST be verifiable (Read to confirm if file_ref)
+- Convergence curve numbers MUST match swarm-report.json#convergence_curve
+
+#### Feedback Contract
+| Field | Required | Content |
+|-------|----------|---------|
+| artifacts_written | Always | `<session>/artifacts/best-solution.md` |
+| line_count | Always | int (informational) |
+| verification_method | Always | "cross_ref_with_best.json + evidence_verified" |
+
+#### Quality Gate
+- Final report file exists and parses as markdown
+- All sections present (Best Solution / Why Won / Runner-Ups / Convergence / Caveats / Reproducibility)
+
+### Verification Steps
+
+1. Read written best-solution.md back
+2. Cross-check best.score against best.json
+3. Confirm runner-up scores against trails
+4. If file_ref evidence in best.candidate_solution -> Read to confirm file exists
+
+### State Update
+
+```json
+{
+  "task_id": "ANALYST-1",
+  "role": "analyst",
+  "status": "completed",
+  "artifact_path": "<session>/artifacts/best-solution.md",
+  "best_score": <float>,
+  "best_ant_id": "<id>",
+  "line_count": <int>,
+  "verification": "cross_ref_pass + evidence_verified"
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| best.json missing | Pipeline produced no valid ant — write minimal report with `status: no_solution` |
+| Trails empty | Same as above — no exploration data to analyze |
+| Best ant artifact missing | Use only best.json fields; note as caveat |
+| Cross-ref mismatch (score discrepancy) | Trust best.json; note discrepancy in caveats |

package/.codex/skills/codify-to-knowhow/SKILL.md

@@ -145,22 +145,24 @@ $codify-to-knowhow ".workflow/reference_style/my-style-v1"
 2. **Idempotent Writes**: Same-slug file exists = skip, never overwrite
 3. **Closed Tags**: All entries use `<spec-entry>` / `<knowhow-entry>` closed-tag format
 4. **Upstream Generates Manifest**: This skill only writes, never extracts knowledge
-5. **CLI First, File Fallback**: Prefer `maestro spec add` CLI; fall back to direct file append on failure
-6. **Ref Bridge**: Spec entries reference knowhow files via `ref` attribute
+5. **CLI First, File Fallback**: Prefer `maestro spec add` CLI with `--ref` param; fall back to direct file append on failure (with confirmation log)
+6. **Ref Bridge**: Spec entries reference knowhow files via `ref` attribute — both CLI path (`--ref` flag) and fallback path (`ref` attr in `<spec-entry>`) carry the ref
 </invariants>
 
 <execution>
 
 ### Step 1: Parse Package Path
 
-**Parse from `$ARGUMENTS`**:
+**Parse first positional from `$ARGUMENTS` and assign to `package_path`**:
 
 | Variable | Source | Default |
 |----------|--------|---------|
-| `package_path` | positional (required) | ERROR if missing |
+| `package_path` | first positional from $ARGUMENTS (required) | ERROR if missing |
 
 ```bash
-package_path="${PACKAGE_PATH}"
+# Parse first positional argument from $ARGUMENTS
+package_path="$(echo "$ARGUMENTS" | awk '{print $1}')"
+test -n "$package_path" || { echo "ERROR: package_path is required as first positional argument"; exit 1; }
 
 # Validate directory exists
 test -d "$package_path" || { echo "ERROR: Package path not found: $package_path"; exit 1; }
@@ -313,10 +315,12 @@ ${spec.body}
 
   // Prefer CLI, fallback to direct append
   const descFlag = spec.description ? ` --description "${spec.description}"` : '';
-  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}"${descFlag} 2>/dev/null`);
+  const refFlag = spec.ref ? ` --ref "${spec.ref}"` : '';
+  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}"${descFlag}${refFlag} 2>/dev/null`);
 
   if (cliResult.exitCode !== 0) {
-    // Fallback: direct file append
+    // Fallback: direct file append — confirm before writing
+    REPORT(`CLI failed for "${spec.title}", falling back to direct append to ${targetFile}`);
     Edit(targetFile, { append: entryBlock });
   }
 
@@ -348,22 +352,30 @@ for file in ${knowhowPaths}; do
 done
 ```
 
-**6b: Verify spec entries**:
+**6b: Verify spec entries** (verify by actual targetFile set from manifest, not hardcoded categories):
+
+```javascript
+// Collect unique target files from manifest specs
+const verifiedFiles = new Set();
+for (const spec of manifest.specs) {
+  const targetFile = `.workflow/specs/${categoryFileMap[spec.category]}`;
+  verifiedFiles.add(targetFile);
+}
+```
 
 ```bash
 echo "=== Spec Entry Verification ==="
-grep -c "${slug}" .workflow/specs/coding-conventions.md 2>/dev/null && \
-  echo "  OK: coding-conventions.md" || echo "  MISSING: No entries in coding-conventions.md"
-
-grep -c "${slug}" .workflow/specs/architecture-constraints.md 2>/dev/null && \
-  echo "  OK: architecture-constraints.md" || echo "  MISSING: No entries in architecture-constraints.md"
+for target_file in ${verifiedFiles}; do
+  grep -c "${slug}" "${target_file}" 2>/dev/null && \
+    echo "  OK: ${target_file}" || echo "  MISSING: No entries in ${target_file}"
+done
 ```
 
-**6c: Verify ref links**:
+**6c: Verify ref links** (scan only the target files derived from the manifest):
 
 ```bash
 echo "=== Ref Link Verification ==="
-refs=$(grep -oP 'ref="knowhow/[^"]*"' .workflow/specs/coding-conventions.md .workflow/specs/architecture-constraints.md 2>/dev/null | grep "${slug}" || true)
+refs=$(grep -oP 'ref="knowhow/[^"]*"' ${verifiedFiles} 2>/dev/null | grep "${slug}" || true)
 
 if [ -n "$refs" ]; then
   echo "$refs" | while IFS= read -r ref; do

package/.codex/skills/domain-add/SKILL.md

@@ -34,7 +34,7 @@ Extract canonical (first token, kebab-case) and definition (remainder) from argu
 
 ### Step 2: Validate Domain Directory
 
-Verify `.workflow/domain/glossary.yaml` exists (E002). If not, run `maestro domain init`.
+Verify `.workflow/domain/glossary.yaml` exists. If missing, ask user to confirm auto-initialization (`maestro domain init`). Proceed on confirmation; abort with E002 if declined. Skip confirmation when `--yes` flag is set.
 
 ### Step 3: Check Duplicates
 
@@ -42,7 +42,7 @@ Read existing glossary and check for:
 - Exact duplicate (same canonical name) → report existing entry, exit
 - Near match (Levenshtein ≤ 2 or alias overlap) → warn, ask to confirm or merge
 
-### Step 4: Extract Metadata
+### Step 4: Extract & Confirm Metadata
 
 Auto-derive from the definition and codebase context:
 - **aliases** (1-3): common abbreviations, Chinese translations, alternate forms
@@ -50,6 +50,8 @@ Auto-derive from the definition and codebase context:
 - **tier**: `core` | `extended` | `peripheral`
 - **relationships**: scan existing glossary for related terms
 
+Display a preview of all derived metadata and ask user to confirm or edit before proceeding. When `--yes` / `-y` flag is set, skip confirmation and write directly.
+
 ### Step 5: Register Term
 
 ```bash
@@ -66,7 +68,7 @@ Display: canonical name, definition, aliases, tier, relationships, and verify co
 | Code | Severity | Description |
 |------|----------|-------------|
 | E001 | fatal | Canonical name and definition are both required |
-| E002 | fatal | `.workflow/domain/` not initialized — run `maestro domain init` first |
+| E002 | fatal | `.workflow/domain/` not initialized and user declined auto-init |
 | E003 | fatal | Term already registered with same canonical name |
 </error_codes>
 

package/.codex/skills/learn-decompose/SKILL.md

@@ -77,7 +77,9 @@ Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2).
     "findings":      { "type": "string", "maxLength": 500 },
     "error":         { "type": "string" }
   },
-  "required": ["id", "result_status", "findings"]
+  "required": ["id", "result_status", "findings"],
+  "if":   { "properties": { "result_status": { "const": "completed" } } },
+  "then": { "required": ["id", "result_status", "findings", "patterns", "dimension"] }
 }
 ```
 
@@ -110,14 +112,29 @@ Each dimension agent populates `patterns` as a JSON array string of:
 
 ### Phase 3: Wave 2 — Cross-Reference + Catalog
 
-Single agent receives all wave 1 findings via `prev_context`. Uses same `output_schema` + termination contract above. Tasks:
+Single agent receives all wave 1 findings via `prev_context`. Uses same `output_schema` + termination contract above.
+
+**prev_context filtering**: Only rows with `result_status=="completed"` are forwarded. For each wave 1 row that `failed`, append a `gap_note` line to the cross-ref instruction: `"[GAP] {dimension} scan failed — catalog may be incomplete for this dimension."` The cross-ref agent must not fabricate patterns for missing dimensions.
+
+Tasks:
 - Match against dedup set → mark as `documented`, `known`, or `new`
 - Merge duplicates across dimensions (same pattern found by multiple agents)
 - Flag contradictions with documented conventions
-- Build pattern catalog grouped by dimension
+- Build pattern catalog grouped by dimension; note any gap dimensions
 
 ### Phase 4: Persist
 
+**Preview gate** (unless `-y`/`--yes`):
+1. Build a summary table of all writes that will be performed:
+   - Knowhow file path + pattern count
+   - New patterns to append to `learnings.md` (list names + INS-ids)
+   - If `--save-spec`: spec entries to create
+   - If `--save-wiki`: wiki notes to create
+2. Display the summary to the user via `request_user_input` asking for confirmation (`y` to proceed, `n` to abort, `e` to edit selection).
+3. If user selects `e`, re-display with checkboxes and apply only checked items.
+4. If `-y`/`--yes` flag is set, skip the preview gate and write all items automatically.
+
+**Writes:**
 1. Write `KNW-decompose-{slug}-{date}.md` with full catalog
 2. Append each **new** pattern to `.workflow/specs/learnings.md` (source: "decompose", category: "pattern")
 3. If `--save-spec`: invoke `spec-add` per new pattern
@@ -129,7 +146,7 @@ Single agent receives all wave 1 findings via `prev_context`. Uses same `output_
 |------|----------|-----------|----------|
 | E001 | error | Target path not found | Check path or use module name |
 | E002 | error | No source files in target | Check target has .ts/.js files |
-| W001 | warning | Dimension agent failed — partial results | Proceed with available dimensions |
+| W001 | warning | Dimension agent failed — partial results | Exclude from prev_context, add gap_note, proceed |
 | W002 | warning | coding-conventions.md not found | All patterns marked "new" |
 </error_codes>
 
@@ -138,6 +155,7 @@ Single agent receives all wave 1 findings via `prev_context`. Uses same `output_
 - [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
 - [ ] Each finding has: name, dimension, confidence, anchors, description
 - [ ] Cross-reference performed (documented / known / new)
+- [ ] Preview summary shown and user confirmed (or `-y` flag bypassed)
 - [ ] Pattern catalog written to `KNW-decompose-{slug}-{date}.md`
 - [ ] New patterns appended to `.workflow/specs/learnings.md` with stable INS-ids
 - [ ] If --save-spec / --save-wiki: entries created

package/.codex/skills/learn-follow/SKILL.md

@@ -52,10 +52,15 @@ From forcing question answers, extract: design patterns (with file:line anchors)
 
 Cross-reference against `coding-conventions.md`: documented vs undocumented patterns.
 
-### Stage 5: Persist
-1. Write `KNW-follow-{slug}-{date}.md` with understanding map
-2. Append new patterns to `.workflow/specs/learnings.md` (source: "follow", stable INS-ids)
-3. If `--save-wiki`: create wiki note entry
+### Stage 5: Persist (confirmation-gated)
+1. Display understanding map summary to user
+2. **Confirmation gate**: prompt user via `request_user_input` — "Save knowhow and specs? (y/n/edit)"
+   - `y` → proceed to write
+   - `n` → skip persistence, display summary only
+   - `edit` → let user modify findings before writing
+3. On confirmation: write `KNW-follow-{slug}-{date}.md` with understanding map
+4. On confirmation: append new patterns to `.workflow/specs/learnings.md` (source: "follow", stable INS-ids)
+5. If `--save-wiki`: create wiki note entry (also gated by step 2 confirmation)
 
 **Next steps:** `$learn-decompose <path>`, `$spec-add coding ...`, `$learn-second-opinion <file>`
 </execution>
@@ -75,6 +80,7 @@ Cross-reference against `coding-conventions.md`: documented vs undocumented patt
 - [ ] All 4 forcing questions applied per section
 - [ ] Patterns extracted with file:line anchors
 - [ ] Understanding map produced with concepts, patterns, assumptions, questions
-- [ ] `KNW-follow-{slug}-{date}.md` written
-- [ ] `.workflow/specs/learnings.md` appended with stable INS-ids
+- [ ] User confirmation obtained before persistence
+- [ ] `KNW-follow-{slug}-{date}.md` written (if confirmed)
+- [ ] `.workflow/specs/learnings.md` appended with stable INS-ids (if confirmed)
 </success_criteria>

package/.codex/skills/learn-investigate/SKILL.md

@@ -17,6 +17,7 @@ $ARGUMENTS — question text and optional flags.
 **Flags:**
 - `--scope <path>` — Restrict to files under this directory (default: entire project)
 - `--max-hypotheses N` — Max hypotheses before escalating (default: 3)
+- `--no-persist` — Skip writing to learnings.md (report.md still written locally)
 
 **Output**: `.workflow/knowhow/KNW-investigate-{slug}/` (evidence.ndjson, understanding.md, report.md)
 </context>
@@ -50,12 +51,15 @@ Generate ranked hypotheses from evidence. For each (in rank order):
 ### Stage 4: 3-Strike Escalation
 If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark INCONCLUSIVE.
 
-### Stage 5: Synthesize + Persist
+### Stage 5: Synthesize + Persist (confirmation-gated)
 1. Write `report.md` with answer, evidence trail, hypothesis results
-2. Append to `.workflow/specs/learnings.md`:
-   - Confirmed → category: "technique" / "pattern"
-   - Disproved → category: "gotcha"
-3. Display summary with next-step routing
+2. If `--no-persist`: skip learnings append, display summary only
+3. Otherwise: **Confirmation gate** — prompt user via `request_user_input`: "Persist findings to learnings.md? (y/n)"
+   - `y` → append to `.workflow/specs/learnings.md`:
+     - Confirmed → category: "technique" / "pattern"
+     - Disproved → category: "gotcha"
+   - `n` → skip learnings append
+4. Display summary with next-step routing
 
 **Next steps:** `$spec-add debug <finding>`, `$learn-follow <path>`, `$learn-decompose <module>`
 </execution>
@@ -76,6 +80,7 @@ If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark IN
 - [ ] At least 1 hypothesis formed and tested
 - [ ] understanding.md tracks evolving understanding
 - [ ] report.md written with answer and evidence trail
-- [ ] Findings appended to .workflow/specs/learnings.md with stable INS-ids
+- [ ] User confirmation obtained before learnings append (unless --no-persist)
+- [ ] Findings appended to .workflow/specs/learnings.md with stable INS-ids (if confirmed)
 - [ ] 3-strike escalation triggered if all hypotheses fail
 </success_criteria>