arreio 1.0.0-dev.1

package/skills/learn/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: learn
+description: "Curate the project's durable knowledge base — decisions, patterns, gotchas, workflows — as the source of truth that Plan/Work/Review search via docs/learn/index.md. Orchestrates Capture -> Refine -> Index for authoring one entry, plus an on-demand Maintain pass (dedup/refresh/prune) and a one-time legacy-to-canonical migration. Stores decisions, not logs; knowledge, not sessions; durable entries, not session memory. Local-only; no agent dependency; no fallback paths."
+disable-model-invocation: true
+---
+
+# Learn
+
+Orchestrates the project's durable knowledge base. Authors durable **knowledge entries** — `decision` / `pattern` / `gotcha` / `workflow` — through `Capture -> Refine -> Index`, and maintains them through an on-demand `Maintain` pass (dedup / refresh / prune) plus a one-time legacy-to-canonical migration. The knowledge base lives at `docs/learn/` and is the **source of truth** that Plan, Work, and Review search via `docs/learn/index.md`. No agent dependency, no fallback paths.
+
+> **Store decisions, not logs; knowledge, not sessions.** This skill authors durable, decision-shaped entries — it does **not** extract transient session transcripts or event logs. An entry is a conclusion a future skill needs; it is never a "what we did this session" record.
+
+## Skill Invocation
+
+This skill is invoked by prompting:
+
+- `/learn <type> <text>` — **explicit author.** `<type>` is one of `decision` / `pattern` / `gotcha` / `workflow`; `<text>` is the content (prose, a reference to a file/commit, or a short description to expand). Runs the Capture → Refine → Index pipeline and writes one durable entry to `docs/learn/<type>/`.
+- `/learn <candidate-ref>` — **curate a candidate.** `<candidate-ref>` points at a Work `review-id` (the Work Report's `learnings-to-capture` list) or a Review `report-id` (the Review Report's `learnings-to-capture` list). Capture refines each candidate into a durable entry; the user confirms which to author.
+- `/learn maintain` — **on-demand maintenance.** Runs the Maintain phase standalone: dedup, refresh, prune stale entries, and (once) migrate the legacy `docs/learnings/` store into the canonical `docs/learn/` store. Does not author new entries.
+- `/learn` (no args) — ask: "What would you like to capture? Provide a type (decision/pattern/gotcha/workflow) and text, a candidate ref, or `maintain`."
+
+This skill runs the learn pipeline, authoring/maintaining knowledge entries, acting as the Orchestrator.
+
+## Interaction Method
+
+- Ask the user one structured question at a time (2–4 concrete options) using the agent's interactive question capability; never hardcode a specific tool name.
+- If input is empty, ask: "What would you like to capture? Provide a type and text, a candidate ref, or `maintain`."
+
+Before starting the workflow, ask the user to choose an interaction mode:
+
+- **Detailed** — Confirm at each phase transition and before each destructive write (entry creation, index rewrite, prune). Maximum control. Best for authoritative decisions or sensitive maintenance.
+- **Autopilot** — All phases run automatically; only the final outcome is reported. Fastest. Best for routine, well-scoped entries.
+- **Smart** — Phases run automatically; pause only on destructive or ambiguous operations (a likely-duplicate detected at Refine; a prune that would delete an entry at Maintain; a migration that would rewrite 28 legacy paths).
+
+Store in the context object:
+
+```yaml
+interactionMode: detailed | smart | autopilot
+```
+
+**Propagation:** `interactionMode` flows into the `capture`, `refine`, `index`, and `maintain` artifacts; each downstream phase reads it to adjust confirmation behaviour (detailed = pause every transition + before destructive writes; autopilot = run all; smart = pause only on duplicates, prunes, and migrations).
+
+## Orchestration Implementation
+
+Each phase runs sequentially: the orchestrator calls the phase module, receives the output artifact, validates it with a quality gate, and passes the artifact to the next phase.
+
+### INPUT
+
+- Receives a context object from the user, a saved prompt, a document, or a combination.
+- **Three input shapes:**
+  1. **Explicit** — `/learn <type> <text>`. Capture drafts an entry of the named type from the text. The canonical path for authoring a decision/pattern/gotcha/workflow.
+  2. **Candidate** — `/learn <candidate-ref>`. The ref resolves to a Work `review-id` (`docs/plans/.work/.review/<id>.md`) or a Review `report-id` (`docs/plans/.review/.report/<id>.md`); Capture reads its `learnings-to-capture` list and, for each candidate, drafts the corresponding entry. The user confirms which candidates become durable entries.
+  3. **Maintain** — `/learn maintain`. Runs only the Maintain phase (dedup / refresh / prune); bypasses Capture → Refine → Index (no new entry is authored).
+- **If no context is provided**, ask: "What would you like to capture? Provide a type and text, a candidate ref, or `maintain`."
+- **Unified key:** downstream phases key off a `learn-id` umbrella (`YYYY-MM-DD-NNN`), allocated by Capture. For Maintain-only runs, Maintain allocates its own `maintain-id` (no `learn-id` umbrella — there is no newly authored entry).
+- Output: [Learn Input Artifact](references/templates/artifacts/learn-input.md)
+
+### Pre-Flight Check
+
+Before starting the learn pipeline, the orchestrator verifies that required folders exist:
+
+- `docs/learn/` — must exist for writing entries and the index; the seed `docs/learn/index.md` must exist (empty `entries:` block is valid — the legacy migration populates 28 entries)
+- `docs/plans/.learn/.capture/`, `docs/plans/.learn/.refine/`, `docs/plans/.learn/.index/`, `docs/plans/.learn/.maintain/` — must exist for saving the phase artifacts
+
+**Self-Healing:** If any are missing, the orchestrator automatically creates them (`mkdir -p`), and seeds `docs/learn/index.md` from the [index-format.md](references/index-format.md) template. This allows the Learn skill to run even if `arreio-init` wasn't explicitly run.
+
+For **explicit** input, verify `<type>` is one of the four; if not, ask to pick from the four. For **candidate** input, verify the ref resolves to a non-empty `learnings-to-capture` list; if the list is empty, inform the user (no candidates to curate). For **maintain** input, verify `docs/learn/` exists; if only the legacy `docs/learnings/` exists, the migration runs first as part of Maintain.
+
+### Phases
+
+| Phase | Phase Module                          | Output Artifact                                                              | Saved to                               |
+| ----- | ------------------------------------ | ---------------------------------------------------------------------------- | -------------------------------------- |
+| 1     | [Capture](modules/capture.md)        | [Captured entry](references/templates/artifacts/captured-entry.md)           | `docs/plans/.learn/.capture/<id>.md`   |
+| 2     | [Refine](modules/refine.md)          | [Refined entry](references/templates/artifacts/refined-entry.md)             | `docs/plans/.learn/.refine/<id>.md`    |
+| 3     | [Index](modules/index.md)            | [Index update](references/templates/artifacts/index-update.md)               | `docs/plans/.learn/.index/<id>.md`     |
+| 4     | [Maintain](modules/maintain.md) _(on demand)_ | [Maintain log](references/templates/artifacts/maintain-log.md)   | `docs/plans/.learn/.maintain/<id>.md`  |
+
+**Phase 4 is on-demand.** A normal `/learn <type> <text>` run executes Phases 1–3 and writes one entry; Maintain runs only via `/learn maintain`. The migration procedure (legacy → canonical) is a Maintain operation, run once.
+
+### Quality Gates
+
+Between phases, the orchestrator validates the output artifact before passing it to the next phase:
+
+1. **Schema validation** — required fields present and well-formed (see [error-handling.md](references/error-handling.md) for the per-type field list).
+2. **Cross-phase consistency** — IDs (`learn-id`, `capture-id`, `refine-id`, `index-id`, `maintain-id`) match the upstream artifacts; `interactionMode` is identical across artifacts.
+3. **Status check** — the artifact's `status` is `complete` (not `pending` or `failed`).
+4. **Entry coherence (after Refine)** — the candidate entry has a valid `type` (one of the four), a unique `slug`, and all required frontmatter fields (`domain`, `tags`, `applicability`, `summary`); the per-entry frontmatter and the index-record shape agree with [entry-schema.md](references/entry-schema.md); no exact duplicate was detected per [dedup-rules.md](references/dedup-rules.md).
+5. **Index idempotency (after Index)** — `docs/learn/index.md` was updated by upserting on the entry's `slug` (YAML block entry + By Category / By Domain rows); the YAML `entries:` length matches the on-disk entry-file count; no duplicate index rows; totals (Decision/Pattern/Gotcha/Workflow counts) are consistent.
+
+If a gate fails, the orchestrator returns to the producing phase with the error context (per the recovery workflow in [error-handling.md](references/error-handling.md)).
+
+### Index Registration
+
+The **Index phase** is the skill's only index writer for authored entries; the **Maintain phase** is the only index rebuilder:
+
+| Phase    | Registers To                       | Update                                                                                                       |
+| -------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Index    | `docs/learn/<type>/<slug>.md` + `docs/learn/index.md` | Write the entry file; upsert the YAML `entries:` block record **and** the By Category / By Domain markdown rows, keyed on `slug`. Idempotent on `slug`. |
+| Maintain | `docs/learn/index.md`              | Rebuild the index from the on-disk file tree (full reconcile): re-scan `docs/learn/<type>/*.md`, regenerate the YAML block + tables, and (once) migrate legacy `docs/learnings/` entries. Idempotent. |
+
+**Idempotency rule:** re-authoring the same decision upserts on `slug` (overwrites the entry file and its index record, never duplicates). Refine rejects an exact duplicate (same `slug`) and asks to either update the existing entry or pick a new slug — never silently two entries (per [dedup-rules.md](references/dedup-rules.md)).
+
+### FINAL OUTPUT
+
+- **Entry file:** Saved to `docs/learn/<type>/<slug>.md` with the [entry-schema.md](references/entry-schema.md) frontmatter (`type`, `domain`, `tags`, `applicability`, `summary`, plus `created_at`/`updated_at`, `source`, `confidence`, and `related`).
+- **Index:** `docs/learn/index.md` updated — a YAML `entries:` block (the `filename` / `domain` / `tags` / `applicability` / `summary` record per entry — the **read contract** that Plan/Work/Review's [learnings-gate-logic.md](../plan/references/learnings-gate-logic.md) parses) plus the human-readable By Category / By Domain tables.
+- **Maintain Log (if `/learn maintain`):** Saved to `docs/plans/.learn/.maintain/<maintain-id>.md`, recording the dedup/refresh/prune operations performed and any migration applied.
+- **Not produced:** This skill produces **no session log, no event transcript, no "what we did."** Only durable entries and the index.
+
+## References
+
+The orchestrator and phase modules share these reference files:
+
+| Reference                                                                       | Used By                                  |
+| ------------------------------------------------------------------------------- | ---------------------------------------- |
+| [error-handling.md](references/error-handling.md)                               | All phases (Step 0 verification)         |
+| [id-generation.md](references/id-generation.md)                                 | Capture, Index, Maintain (entry-id + slug allocation) |
+| [interaction-mode-propagation.md](references/interaction-mode-propagation.md)   | All phases (Step N confirmation)        |
+| [entry-schema.md](references/entry-schema.md)                                   | Capture + Refine (the per-entry frontmatter + the index-record shape — the write contract) |
+| [dedup-rules.md](references/dedup-rules.md)                                     | Refine + Maintain (duplicate detection, merge, lineage preservation) |
+| [index-format.md](references/index-format.md)                                   | Index (the canonical `docs/learn/index.md` format — YAML block + tables) |
+| [migration-bootstrap.md](references/migration-bootstrap.md)                     | Maintain (one-time `docs/learnings/` → `docs/learn/` migration) |
+
+Artifact templates live in [references/templates/artifacts/](references/templates/artifacts/):
+
+| Template                                                                       | Produced By |
+| ----------------------------------------------------------------------------- | ----------- |
+| [learn-input.md](references/templates/artifacts/learn-input.md)               | Orchestrator |
+| [captured-entry.md](references/templates/artifacts/captured-entry.md)         | Capture   |
+| [refined-entry.md](references/templates/artifacts/refined-entry.md)           | Refine    |
+| [index-update.md](references/templates/artifacts/index-update.md)             | Index     |
+| [maintain-log.md](references/templates/artifacts/maintain-log.md)             | Maintain  |
+
+### Write side vs read side (single source of truth)
+
+> The Learn skill **owns the write side** — the per-entry frontmatter schema ([entry-schema.md](references/entry-schema.md)) and the `docs/learn/index.md` format ([index-format.md](references/index-format.md)). The Plan skill **owns the read side** — the keyword/relevance search in [learnings-gate-logic.md](../plan/references/learnings-gate-logic.md), reused cross-skill by Work and Review. The two contracts share the **index-record shape** (`filename`, `domain`, `tags`, `applicability`, `summary` + the `applicability` enum). Learn **guarantees** its index satisfies that shape; it does **not** re-encode the search algorithm (honoring the secondary-spec-contradicts-authoritative-matrix gotcha — one algorithm lives in Plan's gate-logic, one schema lives here; see `docs/learn/gotcha/2026-08-07-secondary-spec-contradicts-authoritative-matrix.md` post-migration).
+
+## Core Principles
+
+- **Source of Truth, Not Memory:** `docs/learn/` is the project's durable, authoritative knowledge base. Plan/Work/Review search it; this skill authors and maintains it. Not a session memory, not an event log.
+- **Store Decisions, Not Logs; Knowledge, Not Sessions:** Every entry is a conclusion a future skill needs — a decision, a confirmed pattern, a recurring gotcha, or a workflow convention. Never an ephemeral "what we did this session."
+- **One Entry per Conclusion; Four Types:** `decision` (authoritative choices), `pattern` (confirmed, reusable), `gotcha` (recurring traps + prevention), `workflow` (conventions). One entry carries one conclusion.
+- **Idempotent Writes:** Authoring a known `slug` upserts the entry file and its index record — never duplicates. Maintain rebuilds the index from the file tree and is idempotent. Re-running a normal `/learn` over the same content merges, it does not pile up.
+- **Dedup Welcomed, Lineage Preserved:** Decisions don't duplicate, but analogs exist; dedup merges an analog into the canonical entry and records the merge (the path-convention-split entry is the model — a migrated entry carries both the old and new path knowledge, not just the new; see `docs/learn/gotcha/2026-08-07-path-convention-split-silently-noops.md` post-migration).
+- **Write Side / Read Side Split:** Learn owns the entry schema and the index format; Plan owns the search algorithm. Both agree on the index-record shape. Never re-encode the other side's logic inline.
+- **Transparent Artifacts:** Each phase produces an explicit output artifact for the next phase.
+- **Behavior-Described, Tool-Agnostic:** Steps describe required capabilities ("write the entry file", "rebuild the index", "ask the user to confirm"), not specific tool names.
+- **Stay Portable:** Use repository-relative paths only — `docs/learn/<type>/<slug>.md`, never absolute.
+- **Error Handling:** Fail explicitly, not silently; each phase has clear error handling with recovery suggestions.
+- **Single Source of Truth:** This skill defines all its own write-side rules; it does not depend on any external agent rule file.
+- **Local-Only:** No GitHub sync, no outbound posting; entries live on disk under `docs/learn/`.

package/skills/learn/modules/capture.md

@@ -0,0 +1,108 @@
+---
+title: Capture
+description: Entry point to the Learn workflow. Resolves an explicit (type + text) or candidate (Work/Review learnings-to-capture ref) input, selects the entry to draft, drafts the per-type body and frontmatter per the authoritative write contract (entry-schema), allocates the learn-id umbrella and the slug, and returns a Captured Entry for the Refine phase.
+type: module
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Phase 1 - Capture
+
+**Purpose:** Entry point to the Learn workflow. Resolves the incoming input (an explicit `<type> <text>` author request **or** a candidate ref to a Work/Review `learnings-to-capture` list), selects **one** entry to draft, drafts its per-type body and frontmatter per the authoritative [entry-schema.md](../references/entry-schema.md), allocates the `learn-id` umbrella and proposes the `slug`, and returns a [Captured Entry](../references/templates/artifacts/captured-entry.md) for the Refine phase. Capture drafts; it does **not** validate against existing entries (that is Refine's job) and it never writes the entry file or the index (that is Index's job). Maintain-only input (`/learn maintain`) does not reach Capture — the Orchestrator routes it straight to Maintain.
+
+## Workflow
+
+This is the Phase 1 pipeline for the Learn Skill. It orchestrates the following steps:
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: a valid **Learn Input Artifact** (see [learn-input.md](../references/templates/artifacts/learn-input.md)) from the Orchestrator. Specifically verify:
+
+1. The Learn Input Artifact carries exactly one of: an `explicit` request (`type` + `text`), a `candidate` ref, **or** a `maintain` flag.
+2. If the shape is `maintain`, **do not run Capture** — the Orchestrator should have routed directly to Maintain (Phase 4). Surface a routing error to the Orchestrator (Category 2).
+3. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+4. The required folders already exist (the Orchestrator's Pre-Flight Check is responsible for creation); do not re-create them here.
+
+If the input is empty or ambiguous, ask the user one question: "What would you like to capture? Provide a type (decision/pattern/gotcha/workflow) and text, a candidate ref, or `maintain`."
+
+### Step 1: Resolve Input Shape
+
+Determine which of the two authoring shapes applies (maintain is rejected in Step 0):
+
+1. **Explicit** — the input carries a `<type>` (one of `decision` / `pattern` / `gotcha` / `workflow`) and `<text>` (prose, a file/commit ref, or a short description to expand).
+2. **Candidate** — the input carries a ref to a Work `review-id` (`docs/plans/.work/.review/<id>.md`) or a Review `report-id` (`docs/plans/.review/.report/<id>.md`).
+
+Record `input-shape: explicit | candidate`. If `<type>` is provided but is not one of the four, ask the user to pick from the four (Step 2 confirms intent either way).
+
+### Step 2: Select the Entry to Draft
+
+Capture produces **one** Captured Entry per run (single-shape artifact). The shape determines the selection:
+
+#### 2a. Explicit
+
+1. Validate `<type>` is one of the four; record it as `capture.target-type`.
+2. The `<text>` is the sole source; if it is a short description, this is a Smart pause trigger (Step 6) — the drafted entry will be inferred, not user-authored, so confirm it matches intent.
+3. The entry to draft is fixed: one entry of `<type>` from `<text>`.
+
+#### 2b. Candidate
+
+1. Resolve the ref to the artifact file:
+   - Work `review-id` → `docs/plans/.work/.review/<review-id>.md` → read its `learnings-to-capture` list.
+   - Review `report-id` → `docs/plans/.review/.report/<report-id>.md` → read its `learnings-to-capture` list.
+2. If the list is empty, inform the user (no candidates to curate) and stop — do not fabricate an entry.
+3. Present the candidate list to the user (each has a `title`, `domain`, `source` {finding-id or task-id+gate}, `summary`, `type`) and ask which to author **first** (one entry per Captured Entry). If the candidate's recorded `type` is one of the four, use it; otherwise map: `confirmed-pattern` → `pattern`, `refuted-assumption` → `gotcha`, `gotcha` → `gotcha`, `forced-decision` → `decision`. The user may override the inferred type.
+4. Record the selected candidate as `capture.source-candidate` (carried for traceability into the entry's `source` frontmatter).
+
+> If the user wants to author **multiple** candidates, the Orchestrator loops Capture → Refine → Index once per picked candidate. Capture handles one entry per run.
+
+### Step 3: Draft the Entry
+
+Draft the entry's frontmatter and body per the authoritative write contract **[entry-schema.md](../references/entry-schema.md)** — Capture looks it up; it does not re-encode the field list or the body section template:
+
+1. **Frontmatter** — populate from the text/candidate:
+   - `type` (one of the four), `slug` (proposed in Step 4), `domain`, `tags`, `priority`, `applicability: { current_project: N, general: N }` (numeric scores 0–10), `confidence` (`high` / `medium` / `low`), `source` (`type: commit|candidate|user`, `reference`, `extracted_at`), `created_at`/`updated_at`.
+   - For a candidate input, `source.type: candidate` and `source.reference: <review-id|report-id>#<finding-id>`.
+2. **Body** — draft the per-type section template (entry-schema.md defines the canonical sections per type): `decision` (Problem / Solution / Decision Rationale / Application / Related Learnings), `pattern` (Problem / Pattern / When to Apply / Example / Related Learnings), `gotcha` (Problem / Trap / Solution / Prevention / Related Learnings / Source), `workflow` (Convention / Why / How / Related Learnings).
+3. **Extract domain and tags** from the text/candidate — name the primary `domain` and 2–6 `tags` (related domains).
+4. **Score applicability** — assign `current_project` (how directly the project uses this) and `general` (how broadly it generalizes) as 0–10, plus `confidence`. Capture proposes these; Refine validates them.
+5. If the `<text>` is a file/commit ref, **read** that file/commit and ground the draft in the actual content (Capture does not invent content from a bare ref — it reads and summarizes the decision the ref embodies).
+
+### Step 4: Propose slug and Allocate the learn-id Umbrella
+
+1. **Propose a `slug`** — a kebab-case, globally-unique stable key for the entry. Derive from the title (concise, descriptive); for time-bound decisions a date suffix is allowed (`critical-risk-tier-security-payments-2026-07-04`). The slug is the upsert key for the entry file and its index record. Refine checks uniqueness; Capture only **proposes**.
+2. **Allocate a `learn-id`** umbrella of the form `YYYY-MM-DD-NNN` per [id-generation.md](../references/id-generation.md), counting existing `docs/plans/.learn/.capture/YYYY-MM-DD-NNN-capture.md` files for today. The `learn-id` is the pipeline umbrella carried through Capture → Refine → Index (Maintain-only runs allocate their own `maintain-id` and have no `learn-id`).
+3. **Assign a `capture-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-capture`, saved to `docs/plans/.learn/.capture/`). Reuse it if the user later picks **Edit & Retry**.
+
+### Step 5: Generate the Captured Entry Artifact
+
+Produce a **Captured Entry** block (as markdown) following the schema in [captured-entry.md](../references/templates/artifacts/captured-entry.md). Include:
+
+- `capture-id`, `learn-id`, `input-shape`, `interactionMode`
+- `target-type` (the entry's type), the proposed `slug`
+- the drafted `frontmatter` (per [entry-schema.md](../references/entry-schema.md)) and the drafted `body` (per-type sections)
+- `source-candidate` (the picked candidate, or `null` for explicit input)
+- `inferred: true | false` — `true` when the draft was inferred from a short description or a candidate (a Step 6 pause trigger); `false` when grounded in a concrete ref/file the user provided
+
+### Step 6: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these capture-specific **Smart pause triggers**:
+
+- `input-shape: candidate` (the draft was inferred from a candidate — confirm the inferred `type`, `domain`, `tags`, and body match intent), or
+- `inferred: true` (the explicit `<text>` was a short description expanded to a full draft — confirm it matches intent), or
+- The `<text>` was a file/commit ref that could not be grounded (could not read the content) — ask the user to supply the decision in prose instead.
+
+- **Detailed:** present the Captured Entry and ask one question with options *(1) Proceed to Refine, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–5 reusing the `capture-id` and `learn-id` (re-propose `slug` only if the `target-type` changed). On **Abort**, stop and inform the Orchestrator.
+- **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
+- **Autopilot:** auto-proceed (no confirmation).
+
+Then save the artifact to `docs/plans/.learn/.capture/<capture-id>.md` (ensure `interactionMode` and `target-type` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Refine).
+
+## Output: Captured Entry Artifact
+
+- Verify that the Captured Entry is complete and valid: `capture-id`, `learn-id`, `input-shape`, `interactionMode`, `target-type`, the proposed `slug`, the drafted `frontmatter`, and the drafted `body`.
+- Verify that `target-type` is one of `decision` / `pattern` / `gotcha` / `workflow`.
+- Verify that the frontmatter and body conform to [entry-schema.md](../references/entry-schema.md) (the per-type section template), without re-encoding the schema inline.
+- Verify that the `learn-id` umbrella was allocated (Capture is the allocating phase) and the `slug` is kebab-case and descriptive.
+- Verify that the artifact is saved to `docs/plans/.learn/.capture/<capture-id>.md`.
+
+> Pass the Captured Entry to `refine` (Phase 2) for type/frontmatter validation and the duplicate + analog check against existing entries.

package/skills/learn/modules/index.md

@@ -0,0 +1,94 @@
+---
+title: Index
+description: Third step in the Learn workflow. Reads the Refined Entry, derives the index-record applicability enum from the per-entry numeric scores, writes the entry file to docs/learn/<type>/<slug>.md (upsert on slug), and upserts docs/learn/index.md (the canonical YAML-entries block + By Category / By Domain tables, per the authoritative index-format). Returns an Index Update for the Orchestrator's final output.
+type: module
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Phase 3 - Index
+
+**Purpose:** Third step in the Learn workflow. Reads the [Refined Entry](../references/templates/artifacts/refined-entry.md) from Refine, derives the index-record `applicability` enum from the per-entry numeric scores (the read-side contract Plan/Work/Review's [learnings-gate-logic.md](../../plan/references/learnings-gate-logic.md) parses), **writes** the entry file to `docs/learn/<type>/<slug>.md` (upsert on `slug`), and **upserts** `docs/learn/index.md` — the canonical YAML `entries:` block + the By Category / By Domain markdown tables — per the authoritative [index-format.md](../references/index-format.md). Returns an [Index Update](../references/templates/artifacts/index-update.md) as the Orchestrator's final output for the run. Index is the only authoring-phase writer of the entry file and the index.
+
+## Workflow
+
+This is the Phase 3 pipeline for the Learn Skill. It orchestrates the following steps:
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: a valid **Refined Entry** from Refine. Specifically verify:
+
+1. The Refined Entry carries `refine-id`, `capture-id`, `learn-id`, `input-shape`, `interactionMode`, the validated `type`, the resolved `slug`, the validated `frontmatter` and `body`, and the `dup-status` + `resolution`.
+2. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+3. Cross-phase consistency: `learn-id`, `capture-id`, `refine-id` match the upstream artifacts; `interactionMode` is identical.
+
+If Refine recorded a `resolution: merge-into-canonical`, Index additionally de-indexes the analog (Step 3) — it does **not** delete the analog's file (lineage preserved per [dedup-rules.md](../references/dedup-rules.md)).
+
+### Step 1: Derive the Index-Record Applicability Enum
+
+The per-entry frontmatter carries numeric `applicability: { current_project: N, general: N }` (the write side). The index-record (in `docs/learn/index.md`) carries the enum `applicability: DIRECT | RECOMMENDED | CONTEXTUAL | HISTORICAL | INFORMATIONAL` — the read-side contract the gate-logic parses. The derivation rule is authoritative in **[index-format.md](../references/index-format.md)** — Index looks it up, it does not re-encode the mapping:
+
+- `current_project ≥ 8 AND general ≥ 7` → `DIRECT`
+- `current_project ≥ 5 AND general ≥ 5` → `RECOMMENDED`
+- `general ≥ 5` → `CONTEXTUAL`
+- `general ≥ 3` → `HISTORICAL`
+- otherwise → `INFORMATIONAL`
+
+Record the derived enum as `index-applicability` for the index-record. The per-entry frontmatter keeps its numeric scores (the write side stays richer; the enum is a derived projection for readers).
+
+### Step 2: Write the Entry File (upsert on slug)
+
+1. Resolve the path `docs/learn/<type>/<slug>.md`. Create `docs/learn/<type>/` if missing.
+2. **Upsert** — if the file exists (re-author / update-existing), overwrite it in place; if not, create it. Both operations key on `slug` (idempotent — never a duplicate file).
+3. Write the entry as markdown: the frontmatter block, then the per-type body from the Refined Entry.
+4. For a merge resolution: **do not** delete the analog file. Instead, write the analog's `superseded-by: <canonical-slug>` note into the analog's frontmatter (a non-destructive lineage record); the analog's index record is removed in Step 3.
+
+### Step 3: Upsert docs/learn/index.md (canonical format)
+
+Update `docs/learn/index.md` per the authoritative **[index-format.md](../references/index-format.md)** — the canonical hybrid format (YAML `entries:` block + By Category / By Domain markdown tables). Index applies the format; it does not re-encode it:
+
+1. **YAML `entries:` block** — upsert (by `filename`) the one record for this entry: `filename: docs/learn/<type>/<slug>.md`, `domain`, `tags`, `applicability: <derived enum>`, `summary`. If the entry already exists in the block (update-existing), overwrite that record in place; never append a second.
+2. **By Category table** — upsert (by `slug`) the row under the entry's `<type>` section (`### Decision` / `### Pattern` / `### Gotcha` / `### Workflow`). Update the per-type count heading (`### Gotcha (N)`).
+3. **By Domain table** — upsert (by `slug`) the entry under its primary `domain` bullet.
+4. **Merge** — on a `merge-into-canonical` resolution: **remove** the analog's record from the YAML block and both tables (it is de-indexed, not deleted), and ensure the canonical entry's record now reflects the merged content.
+5. **Totals coherence** — the per-type count headings must match the `entries:` block length per type, and the YAML `entries:` block length must match the on-disk entry-file count in `docs/learn/`. If a prior index drifted, Index **reconciles** it (the file tree is the source of truth) — this is a non-destructive reconcile, not a rebuild (rebuild is Maintain).
+
+### Step 4: Allocate the index-id
+
+Assign an `index-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-index`, saved to `docs/plans/.learn/.index/`). Reuse it if the user later picks **Edit & Retry**. The `learn-id` umbrella is inherited unchanged.
+
+### Step 5: Generate the Index Update Artifact
+
+Produce an **Index Update** block (as markdown) following the schema in [index-update.md](../references/templates/artifacts/index-update.md). Include:
+
+- `index-id`, inherited `refine-id`, `capture-id`, `learn-id`, `input-shape`, `interactionMode`
+- `entry-path` (`docs/learn/<type>/<slug>.md`), `slug`, `type`, the derived `index-applicability`
+- `index-action` (`created` / `updated` / `merged`), and (for a merge) the analog's `slug` + the de-index action taken
+- `index-coherent: true` — the YAML length matches the on-disk count, totals are consistent (the orchestrator's quality gate #5)
+- `source-candidate` carried through
+
+### Step 6: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these index-specific **Smart pause triggers**:
+
+- `index-action: created` on a destructive first write (overwriting an existing `slug` the user may not expect — confirm before overwriting), or
+- `index-action: merged` (a merge de-indexed an analog — confirm the lineage note and de-index before finalizing), or
+- Totals were incoherent prior to Index and Index had to reconcile (warn the index drifted; suggest `/learn maintain` for a full rebuild).
+
+- **Detailed:** present the Index Update and ask one question with options *(1) Finalize, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–5 reusing the `index-id`. On **Abort**, stop and inform the Orchestrator.
+- **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
+- **Autopilot:** auto-proceed (no confirmation).
+
+Then save the artifact to `docs/plans/.learn/.index/<index-id>.md` (ensure `interactionMode` included) and return it to the Orchestrator. The Orchestrator marks the authoring run complete — the durable entry now lives at `docs/learn/<type>/<slug>.md` and `docs/learn/index.md` reflects it.
+
+## Output: Index Update Artifact
+
+- Verify that the Index Update is complete and valid: `index-id`, `refine-id`, `capture-id`, `learn-id`, `input-shape`, `interactionMode`, `entry-path`, `slug`, `type`, `index-applicability`, and `index-action`.
+- Verify that the entry file was written to `docs/learn/<type>/<slug>.md` and the upsert keyed on `slug` (no duplicate file).
+- Verify that `docs/learn/index.md` was upserted in **both** the YAML `entries:` block and the By Category / By Domain tables, per [index-format.md](../references/index-format.md).
+- Verify **index coherence** (orchestrator gate #5): the YAML block length matches the on-disk entry-file count; the per-type count headings match; no duplicate index rows.
+- Verify that a merge **de-indexed** (not deleted) the analog and recorded the `superseded-by` lineage in the analog's file — lineage preserved per [dedup-rules.md](../references/dedup-rules.md).
+- Verify that the derived `index-applicability` enum was **read from** [index-format.md](../references/index-format.md) (the derivation rule) rather than re-encoded inline.
+- Verify that the artifact is saved to `docs/plans/.learn/.index/<index-id>.md`.
+
+> The Index Update is the authoring run's final artifact. The Orchestrator marks the workflow complete; the durable knowledge entry lives at `docs/learn/<type>/<slug>.md` and is discoverable via `docs/learn/index.md` (the source-of-truth index Plan/Work/Review search).

package/skills/learn/modules/maintain.md

@@ -0,0 +1,116 @@
+---
+title: Maintain
+description: On-demand fourth step of the Learn workflow. Reconciles the canonical knowledge base from the file tree: runs the one-time legacy-to-canonical migration (migration-bootstrap), dedups analogs across the whole base with lineage preserved (dedup-rules), refreshes stale frontmatter against the current entry-schema, prunes obsolete entries (confirm each, never silent), and rebuilds docs/learn/index.md as a full reconcile. Maintain allocates its own maintain-id (no learn-id umbrella) and produces a Maintain Log.
+type: module
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Phase 4 - Maintain
+
+**Purpose:** On-demand fourth step of the Learn workflow. Reconciles the canonical knowledge base (`docs/learn/`) from the on-disk file tree. Runs the one-time legacy `docs/learnings/` → `docs/learn/` migration (via [migration-bootstrap.md](../references/migration-bootstrap.md)), dedups analogs **across the whole base** with lineage preserved (per [dedup-rules.md](../references/dedup-rules.md)), refreshes stale entry frontmatter against the current [entry-schema.md](../references/entry-schema.md), prunes obsolete entries (each confirmed — never silent), and **rebuilds** `docs/learn/index.md` as a full reconcile (the file tree is the source of truth). Produces a [Maintain Log](../references/templates/artifacts/maintain-log.md) recording every operation. Maintain allocates its own `maintain-id` — there is no `learn-id` umbrella (Maintain does not author one new entry).
+
+## Workflow
+
+This is the Phase 4 pipeline for the Learn Skill. It orchestrates the following steps. **Control flow:** a `/learn maintain` run executes Steps 1→5 (each step is idempotent and self-gating — a step with nothing to do records `no-op` and proceeds). Steps run in order; the user confirms destructive operations (prune; migration rewrite) per the interaction mode.
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: a valid **Learn Input Artifact** from the Orchestrator with the `maintain` flag set. Specifically verify:
+
+1. The Learn Input Artifact carries `shape: maintain` (not explicit or candidate). If it carries an authoring shape, the Orchestrator routed incorrectly — surface a routing error (Category 2).
+2. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+3. `docs/learn/` exists (the Orchestrator's Pre-Flight Check ensures this); if only the legacy `docs/learnings/` exists and `docs/learn/` is empty/absent, the migration in Step 1 creates `docs/learn/`.
+
+### Step 1: Migrate the Legacy Store (one-time, self-gating)
+
+Run the one-time migration defined canonically in **[migration-bootstrap.md](../references/migration-bootstrap.md)** — Maintain invokes it; it does not re-derive the procedure:
+
+1. **Self-gate:** if `docs/learnings/` does not exist, or `docs/learn/` already contains the migrated entries (detected by a `docs/learn/.migrated` marker or by slug-set parity), record `migration: no-op (already migrated)` and skip to Step 2.
+2. Otherwise: copy each `docs/learnings/<type>/<file>.md` to `docs/learn/<type>/<slug>.md` (slug = normalized from the legacy filename: kebab-case, date kept as suffix when the legacy file used it), rewrite any legacy `docs/learnings/...` cross-references in the entry **and its `related` links** to the canonical `docs/learn/...` paths, then write the `docs/learn/.migrated` marker.
+3. **Lineage preserved:** each migrated entry's frontmatter records `migrated-from: docs/learnings/<type>/<file>.md` so the old path knowledge is not lost (the `path-convention-split` gotcha is the model — a migrated entry carries both the old and new path).
+4. Record `migration: <N> entries migrated` in the log.
+
+> Maintain does **not** delete `docs/learnings/` after migration. The legacy store stays on disk (read-only, superseded) until the user explicitly removes it — a destructive prune (Step 4) the user confirms. The canonical `docs/learn/` is the source of truth going forward; `docs/learnings/` is vestigial.
+
+### Step 2: Dedup Across the Whole Base
+
+Apply the analog detection from **[dedup-rules.md](../references/dedup-rules.md)** across **all** entries in `docs/learn/` — not just one (Refine applied it per-entry; Maintain applies it base-wide):
+
+1. Scan all `docs/learn/<type>/*.md`; for each pair of entries with the same `domain` + overlapping `tags` + the same decision/pattern/gotcha/workflow conclusion, flag an analog pair.
+2. For each analog pair, propose a **merge into canonical** (pick the canonical `slug` — prefer the older/higher-priority entry; the analog carries `superseded-by`).
+3. Confirm each merge with the user (a destructive dedup Smart pause trigger — Step 7); on confirmation, fold the analog's evidence into the canonical entry, write `superseded-by: <canonical-slug>` into the analog file (de-index, keep file), and record the lineage link in the canonical entry's `related`.
+4. Record each merge in the log (`merge: <analog-slug> → <canonical-slug>`).
+
+### Step 3: Refresh (non-destructive)
+
+Re-validate every entry's frontmatter against the current **[entry-schema.md](../references/entry-schema.md)** — the schema may have evolved since the entry was written:
+
+1. For each entry: check every required field is present and well-typed; check the per-type body sections are present.
+2. **Non-destructive fixes** allowed without confirmation: add a missing default (`priority: normal`, `confidence: medium`), normalize casing (`applicability` enum), stamp `updated_at` if any field was normalized.
+3. **Destructive changes** (rewriting a field's value, deleting a section) require confirmation — these are flagged, not auto-applied. The user decides.
+4. Record `refresh: <N> entries normalized, <M> entries flagged for review`.
+
+### Step 4: Prune (destructive, confirm each)
+
+Remove obsolete entries. **Obsolescence is explicit, never inferred silently:**
+
+1. An entry is **obsolete** iff: the user marks it obsolete, **or** it is `superseded-by` another entry **and** no other entry references it in `related` (a fully-absorbed analog).
+2. For each prune candidate, ask the user one question: keep (de-index only — the recommended default) **or** delete the file (truly destructive). Never delete without explicit confirmation.
+3. On **delete**: remove the file. On **de-index**: remove the index record, keep the file with `status: obsolete` in frontmatter. Both remove the entry from `docs/learn/index.md`.
+4. Record `prune: <slug> (deleted | de-indexed)` in the log.
+
+> Prune is the only step that can delete a file. Every deletion is confirmed. A de-index (keep the file, mark obsolete) is the recommended default — knowledge is rarely deleted, it is superseded.
+
+### Step 5: Rebuild the Index (full reconcile)
+
+Rebuild `docs/learn/index.md` from the on-disk file tree — the file tree is the source of truth, never the existing index:
+
+1. Re-scan `docs/learn/<type>/*.md` (all four types); parse each entry's frontmatter.
+2. Regenerate the YAML `entries:` block per [index-format.md](../references/index-format.md) — re-derive each record's `index-applicability` enum from the per-entry numeric scores (the same derivation Index Step 1 uses).
+3. Regenerate the By Category / By Domain markdown tables; recompute the per-type count headings.
+4. **Exclude** de-indexed entries (those with `status: obsolete` or a `superseded-by` note whose canonical entry is present) from the YAML block and tables.
+5. Write `docs/learn/index.md`. Record `rebuild: <N> entries indexed` and any coherence fixes applied.
+
+### Step 6: Allocate the maintain-id
+
+Assign a `maintain-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-maintain`, saved to `docs/plans/.learn/.maintain/`). Maintain has **no `learn-id` umbrella** (it authors no new entry). Reuse the `maintain-id` if the user picks **Edit & Retry**.
+
+### Step 7: Generate the Maintain Log Artifact
+
+Produce a **Maintain Log** block (as markdown) following the schema in [maintain-log.md](../references/templates/artifacts/maintain-log.md). Include:
+
+- `maintain-id`, `interactionMode`, `status`
+- `migration` (`no-op` | `<N> entries migrated`)
+- `merges` — the list of `analog-slug → canonical-slug` merges performed
+- `refresh` — entries normalized vs flagged-for-review counts + the flagged list
+- `prune` — each `slug (deleted | de-indexed)`
+- `rebuild` — `<N> entries indexed`, coherence fixes applied
+- `index-coherent: true` — the rebuilt YAML length matches the on-disk count
+
+### Step 8: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these maintain-specific **Smart pause triggers**:
+
+- The migration would rewrite legacy paths (Step 1) — confirm before running (it rewrites 28 entry paths + cross-refs), or
+- A prune would delete or de-index an entry (Step 4) — confirm each prune candidate, or
+- A merge would absorb an entry (Step 2) — confirm each analog merge, or
+- `index-coherent: false` after rebuild (a bug — the rebuild did not reconcile; re-run Step 5).
+
+- **Detailed:** present the Maintain Log and ask one question with options *(1) Finalize, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–7 reusing the `maintain-id`. On **Abort**, stop and inform the Orchestrator.
+- **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed (but destructive operations — migration, prune, merge — always surface for confirmation even in Smart, per the principle that destructive writes are never silent).
+- **Autopilot:** auto-proceed for non-destructive steps (refresh, rebuild); **still pause** for destructive operations (migration, prune) — Autopilot never silently deletes or rewrites paths.
+
+Then save the artifact to `docs/plans/.learn/.maintain/<maintain-id>.md` (ensure `interactionMode` included) and return it to the Orchestrator. The Orchestrator marks the Maintain run complete — the canonical knowledge base is reconciled.
+
+## Output: Maintain Log Artifact
+
+- Verify that the Maintain Log is complete and valid: `maintain-id`, `interactionMode`, `status`, and the `migration` / `merges` / `refresh` / `prune` / `rebuild` sections.
+- Verify that the migration (if it ran) preserved lineage (`migrated-from` per entry) and did not delete the legacy store.
+- Verify that every merge recorded lineage (`superseded-by` in the analog; `related` link in the canonical) — de-indexed, not deleted — per [dedup-rules.md](../references/dedup-rules.md).
+- Verify that every prune was explicitly confirmed (no silent deletion); a delete leaves no file; a de-index keeps the file with `status: obsolete`.
+- Verify **index coherence** (orchestrator gate #5): the rebuilt `docs/learn/index.md` YAML length matches the on-disk entry-file count; per-type totals consistent; no duplicate rows.
+- Verify that the rebuild was **applied from** [index-format.md](../references/index-format.md) (and the applicability-enum derivation) rather than re-encoded inline.
+- Verify that the artifact is saved to `docs/plans/.learn/.maintain/<maintain-id>.md`.
+
+> The Maintain Log is the Maintain run's deliverable. The Orchestrator marks the workflow complete; the canonical knowledge base at `docs/learn/` is reconciled and `docs/learn/index.md` reflects the on-disk truth.

package/skills/learn/modules/refine.md

@@ -0,0 +1,104 @@
+---
+title: Refine
+description: Second step in the Learn workflow. Reads the Captured Entry, validates its type and frontmatter per the authoritative write contract (entry-schema), runs the duplicate + analog check against existing entries per dedup-rules, resolves any conflict (update-existing / new-slug / merge-into-canonical with lineage), and returns a Refined Entry for the Index phase.
+type: module
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Phase 2 - Refine
+
+**Purpose:** Second step in the Learn workflow. Reads the [Captured Entry](../references/templates/artifacts/captured-entry.md) from Capture, validates its `type` and frontmatter per the authoritative [entry-schema.md](../references/entry-schema.md), runs the **duplicate + analog check** against existing entries per [dedup-rules.md](../references/dedup-rules.md), and resolves any conflict (update-existing / new-slug / merge-into-canonical with lineage). Returns a [Refined Entry](../references/templates/artifacts/refined-entry.md) for the Index phase. Refine validates and reconciles; it never writes the entry file or the index.
+
+## Workflow
+
+This is the Phase 2 pipeline for the Learn Skill. It orchestrates the following steps:
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: a valid **Captured Entry** from Capture. Specifically verify:
+
+1. The Captured Entry carries `capture-id`, `learn-id`, `input-shape`, `interactionMode`, `target-type`, the proposed `slug`, the drafted `frontmatter`, and the drafted `body`.
+2. `target-type` is one of the four (Capture validated this; Refine re-confirms).
+3. `interactionMode` is present and valid (default to `smart` if missing; log warning).
+4. Cross-phase consistency: `learn-id` matches the Capture output; `interactionMode` is identical.
+
+### Step 1: Validate the Type
+
+1. Confirm `target-type` ∈ {`decision`, `pattern`, `gotcha`, `workflow`}. If invalid, apply Category 2 recovery (re-run Capture).
+2. Confirm the drafted `body` uses the per-type section template (entry-schema.md defines the canonical sections). A `decision` must carry Problem / Solution / Decision Rationale / Application; a `gotcha` must carry Problem / Trap / Solution / Prevention; etc. Missing sections are a Refine Smart pause trigger (Step 6) — ask the user to add them, not auto-fill silently.
+
+### Step 2: Validate the Frontmatter
+
+Validate every frontmatter field against the authoritative **[entry-schema.md](../references/entry-schema.md)** — Refine looks it up; it does not re-encode the field list:
+
+1. `domain` — a single primary domain (non-empty).
+2. `tags` — a list of 2–6 related domains.
+3. `applicability.current_project` and `applicability.general` — integers 0–10.
+4. `confidence` — one of `high` / `medium` / `low`.
+5. `priority` — one of `important` / `normal` (or absent → default `normal`).
+6. `summary` — a 1–2 sentence summary (non-empty).
+7. `source` — `{ type, reference, extracted_at }`; for a candidate input, `source.type: candidate` and `reference` points at the Work/Review report + finding id.
+8. `created_at` / `updated_at` — ISO-8601; Refine leaves `created_at` as Capture set it and stamps `updated_at` to now.
+
+On any validation failure: surface the specific field, suggest the fix, and ask the user — never silently coerce a wrong value (Category 2 recovery).
+
+### Step 3: Duplicate + Analog Check
+
+Run the duplicate and analog detection defined canonically in **[dedup-rules.md](../references/dedup-rules.md)** — Refine applies it; it does not re-derive the matching algorithm:
+
+1. **Exact duplicate** — an existing entry with the same `slug` (or the same canonicalized title). This is a **re-author** case, not a new entry.
+2. **Analog** — an existing entry that addresses the same conclusion (same domain + overlapping tags + the same decision/pattern/gotcha/workflow), under a different `slug`. Analogs are dedup candidates.
+3. **Insignificant** — distant/loose matches; ignore (no action).
+
+Record the matches (`dup-status: exact | analog | none`, the matched `slug`/file, and the match evidence).
+
+#### Resolve the conflict (per dedup-rules.md):
+
+| Match      | Resolution options the user picks from (Smart pause trigger Step 6)                                                               |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `exact`    | (a) **Update existing** — overwrite the existing entry file + index record with the refined content (idempotent on `slug`); (b) **New slug** — keep both, author under a new `slug`. |
+| `analog`   | (a) **Merge into canonical** — fold this draft into the matched entry (append/consolidate the new evidence, record a lineage link to the analog's `slug`, bump `updated_at`); (b) **Keep separate** — keep this as its own entry under the proposed `slug` (the user judges the analog too distant to merge). |
+| `none`     | Proceed — a genuine new entry; no resolution needed.                                                                            |
+
+> **Lineage is preserved** on a merge: the merged entry records the analog as a `related` / lineage link, and the analog's content is not deleted — it is de-indexed (its index record removed) but its **file is kept** with a `superseded-by: <canonical-slug>` note (per [dedup-rules.md](../references/dedup-rules.md)). The `path-convention-split` gotcha is the model: a migrated/merged entry carries both the old and new knowledge, never just the new. This is why dedup **merges**, never **deletes**.
+
+### Step 4: Allocate the refine-id
+
+Assign a `refine-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-refine`, saved to `docs/plans/.learn/.refine/`). Reuse it if the user later picks **Edit & Retry**. The `learn-id` umbrella is inherited unchanged.
+
+### Step 5: Generate the Refined Entry Artifact
+
+Produce a **Refined Entry** block (as markdown) following the schema in [refined-entry.md](../references/templates/artifacts/refined-entry.md). Include:
+
+- `refine-id`, inherited `capture-id` and `learn-id`, `input-shape`, `interactionMode`
+- the validated `type`, the resolved `slug` (may differ from Capture's proposal after a conflict resolution)
+- the validated `frontmatter` and `body`
+- `dup-status` (`exact` / `analog` / `none`), the matched `slug`/file + evidence, and the chosen `resolution` (`update-existing` / `new-slug` / `merge-into-canonical` / `keep-separate` / `none`)
+- `lineage` — the analog `slug` + `superseded-by` note when a merge occured (else empty)
+- `source-candidate` carried through from Capture
+
+### Step 6: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these refine-specific **Smart pause triggers**:
+
+- `dup-status: exact` (decide update-existing vs new-slug before Index writes), or
+- `dup-status: analog` (decide merge-into-canonical vs keep-separate before Index writes), or
+- A frontmatter field failed validation and required the user's fix (Step 2), or
+- A required body section is missing (Step 1) and the user must add it.
+
+- **Detailed:** present the Refined Entry and ask one question with options *(1) Proceed to Index, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–5 reusing the `refine-id`. On **Abort**, stop and inform the Orchestrator.
+- **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
+- **Autopilot:** auto-proceed (no confirmation).
+
+Then save the artifact to `docs/plans/.learn/.refine/<refine-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 3 (Index).
+
+## Output: Refined Entry Artifact
+
+- Verify that the Refined Entry is complete and valid: `refine-id`, `capture-id`, `learn-id`, `input-shape`, `interactionMode`, the validated `type`, the resolved `slug`, the validated `frontmatter` and `body`, and the `dup-status` + `resolution`.
+- Verify that the frontmatter conforms to [entry-schema.md](../references/entry-schema.md) (every required field valid; the per-type body template present) without re-encoding the schema inline.
+- Verify that the duplicate/analog check ran per [dedup-rules.md](../references/dedup-rules.md) and that any conflict was resolved with a recorded `resolution` (never silently two entries).
+- Verify that a merge recorded `lineage` (the analog `slug` + `superseded-by` note) — lineage preserved, never deleted.
+- Verify that the artifact is saved to `docs/plans/.learn/.refine/<refine-id>.md`.
+
+> Pass the Refined Entry to `index` (Phase 3) to write the entry file and upsert the canonical index.