arreio 1.0.0-dev.1

package/skills/learn/references/dedup-rules.md

@@ -0,0 +1,129 @@
+---
+title: Dedup Rules
+description: Authoritative reference for Refine (per-entry dup/analog check) and Maintain (base-wide dedup). Defines what counts as an exact duplicate vs an analog (clearly distinct from exact), the matching signals, the resolution options (update-existing / new-slug / merge-into-canonical / keep-separate), and the lineage-preserving merge procedure — de-index the analog, keep its file with superseded-by, never delete.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Dedup Rules
+
+Authoritative reference for the **Refine** phase (per-entry duplicate+analog check) and the **Maintain** phase (base-wide dedup). Defines what counts as an **exact duplicate** vs an **analog** (a distinct category), the matching signals, the resolution options, and the **lineage-preserving merge procedure** — de-index the analog, keep its file with a `superseded-by` note, never delete. Refine and Maintain apply this reference; they do not re-encode it.
+
+## Core Principle
+
+> **Decisions don't duplicate, but analogs exist.** An exact duplicate (same `slug`) means a re-author; the user updates the existing entry or picks a new `slug`. An analog (same conclusion about the same domain, different `slug`) is a dedup candidate: merging the analog into the canonical entry **preserves lineage** — the analog is de-indexed (its index record removed, its file kept with a `superseded-by` note), never deleted. This is why dedup **merges**, never **deletes**: knowledge is rarely destroyed, it is superseded and absorbed. The `path-convention-split` gotcha is the model — a merged/migrated entry carries both the old and new knowledge, not just the new.
+
+## Matching Categories
+
+| Match      | Definition                                                                                       | Detection signals (authoritative)                                            |
+| ---------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `exact`    | An existing entry with the same `slug` (case-insensitive, hyphen-normalized), or the same canonicalized title. | Identical `slug`; or kebab-case(title) matches slug. |
+| `analog`   | An existing entry addressing the **same conclusion** on the **same domain** with overlapping `tags`, under a different `slug`. | Same `domain` + ≥2 overlapping `tags` + same `type` + semantically same Problem/Solution. |
+| `insignificant` | Loose/distant matches: same `domain` only, or one overlapping tag, or a different `type` on a related topic. | Same `domain` with ≤1 overlapping `tags`; or different `type` (a decision about caching is not an analog of a gotcha about caching). |
+
+**The matching algorithm** (run by Refine on the new draft; by Maintain on all pairs):
+
+```
+1. Canonicalize the candidate's slug and title (kebab-case, lowercase, hyphen-collapsed).
+2. For each existing entry in docs/learn/<type>/ (and cross-type — slug namespace is global):
+   - if slug matches (hyphen-normalized, case-insensitive) -> EXACT
+3. Else, for each existing entry:
+   - compute overlap: domain-strict-match + (shared-tags count) + same-type
+   - if same domain AND >=2 shared tags AND same type:
+       read both bodies' Problem/Solution; if semantically the same conclusion -> ANALOG
+   - else -> INSIGNIFICANT (ignore; not a dedup candidate)
+4. Record the matches with evidence (the shared signals + the matched slug).
+```
+
+Only `exact` and `analogs` surface for resolution; `insignificant` matches are ignored (no dedup, no pause).
+
+## Resolution Options (the user picks)
+
+### exact
+
+A re-author of the same `slug`. Two options:
+
+| Option            | Action                                                                                       |
+| ----------------- | --------------------------------------------------------------------------------------------- |
+| **update-existing** | Overwrite the existing entry file at `docs/learn/<type>/<slug>.md` with the refined content; upsert its index record (idempotent on `slug`); bump `updated_at`. The canonical way to revise a decision. |
+| **new-slug**        | Pick a different `slug` for the draft (e.g., append `-v2` or a domain qualifier); both entries coexist. Use when the new draft is a genuinely different decision that happened to share a slug by coincidence. |
+
+### analog
+
+A same-conclusion, same-domain entry under a different `slug`. Two options:
+
+| Option                    | Action                                                                                                                                                                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **merge-into-canonical**  | Fold the draft's evidence into the matched canonical entry (append/consolidate the body; add the draft's tags; bump `updated_at`). The canonical `slug` stays. The draft (or, in Maintain, the analog) keeps its **file** with `superseded-by: <canonical-slug>` added and its index record **removed** (de-indexed, not deleted). The canonical entry's `related` list records the analog's `slug`. This is the lineage-preserving merge. |
+| **keep-separate**          | Keep the draft as its own entry under the proposed `slug`. Use when the analog is genuinely a different angle (e.g., a cache-invalidation decision and a separate cache-key-naming decision that share `domain + 2 tags` but resolve different problems). |
+
+### none
+
+Proceed — a genuine new entry. No resolution.
+
+## Lineage-Preserving Merge Procedure (authoritative)
+
+On a `merge-into-canonical` resolution, Index (for a Refine-time merge) or Maintain (for a base-wide merge) executes:
+
+```
+1. Pick the canonical slug:
+   - Prefer the older entry (earlier created_at)
+   - On tie, prefer the higher-priority
+   - On tie, prefer the existing entry (keep the in-place one canonical)
+2. Fold the analog's body into the canonical:
+   - Append the analog's Problem paragraph (or merge into the canonical's Problem if clearer)
+   - Append the analog's Solution/example
+   - Append the analog's tags (union into the canonical's tags; cap at 6; if union exceeds 6, keep the top-6 by domain-relevance, log the trim)
+   - Bump the canonical's updated_at
+3. Mark the analog (de-index, keep file):
+   - In the analog's frontmatter, add `superseded-by: <canonical-slug>` and `status: obsolete`
+   - Do NOT delete the analog's file
+   - Remove the analog's record from docs/learn/index.md (YAML block + By Category / By Domain tables)
+4. Link the canonical:
+   - Add the analog's slug to the canonical's `related` list (the lineage link)
+   - The canonical's index record now reflects the merged content (richer body; same or expanded tags)
+5. Record the merge in the artifact (Refine's lineage field / Maintain's merges list):
+   merge: <analog-slug> -> <canonical-slug>
+```
+
+**Why de-index and not delete:** the analog's file may be referenced by a `related` link in another entry, or by external docs/commits. Deleting its file would orphan those links. De-indexing keeps the file reachable (the `superseded-by` note redirects readers to the canonical) and the canonical's `related` link proves the absorption. The analog's content is **not** lost — it lives in its file, superseded, plus absorbed into the canonical.
+
+## Refine vs Maintain Scope
+
+| Phase    | Scope of dedup                                                   | When                                                                 |
+| -------- | ---------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Refine   | The **one** draft against all existing entries (per-entry)       | Every authoring run (`/learn <type> <text>` or candidate curation)   |
+| Maintain | **All** pairs in the canonical store (base-wide)                 | On-demand (`/learn maintain`), after the migration step              |
+
+Refine catches duplicates at author-time (prevents creating a duplicate). Maintain catches **inter-existing** analogs across an already-built store (the store may have accumulated analogs from many separate runs). Both use the same matching algorithm and the same resolution options above.
+
+## Smart Pause Triggers
+
+Dedup operations are destructive (a merge de-indexes an analog; a slug collision forces a choice). They pause in Smart mode and **always surface in Autopilot** (per [interaction-mode-propagation.md](interaction-mode-propagation.md) — destructive ops never silent):
+
+- Refine: `dup-status: exact` (update vs new-slug) or `dup-status: analog` (merge vs keep).
+- Maintain: any analog pair found in the base-wide scan (merge vs keep, per pair).
+
+## Edge Cases
+
+| Scenario                                                                 | Resolution                                                              |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Analog pair but different `type` (e.g., a `decision` and a `gotcha` on caching) | **Not an analog** — different `type` blocks the analog match (a decision is not a gotcha). Keep separate. |
+| Two entries with the same `slug` already on disk (corrupt store)         | Maintain flags both; the user picks the canonical; the other renames. Index reconciliation detects the duplicate row. |
+| An analog referenced in another entry's `related` list                    | Still merge — but the canonical's `related` now points to the analog's old slug; readers follow the analog's `superseded-by` to the canonical. No orphan. |
+| Merge would push the canonical's `tags` over 6                          | Trim to top-6 by domain-relevance; log the trim; the analog's tags are noted in the body. |
+| The canonical entry is itself `obsolete`                                  | Do not merge into an obsolete entry; surface to user — likely the analog is the live one; reverse the canonical choice. |
+
+## Validation (Refine Step 3 / Maintain Step 2 re-checks)
+
+- A match was recorded for every same-slug / same-domain-overlapping pair (no silent matches).
+- A `merge-into-canonical` always sets `superseded-by` on the analog and adds the analog's slug to the canonical's `related` (lineage preserved both ways).
+- No analog file was deleted on a merge (only de-indexed).
+- The matched evidence is recorded (`slug` + the shared signals) so the user can confirm the match is real, not a false positive.
+
+## Notes
+
+- This reference is the single source of truth for the matching algorithm, the resolution options, and the lineage-preserving merge procedure. Refine and Maintain apply it; the modules never re-encode the matching signals inline.
+- **Decisions-not-logs** is honored: dedup operates on durable knowledge entries, never on session records. Two analogs reached the store because they were authored at different times as separate conclusions; merging absorbs them as one durable conclusion with lineage.
+- The `keep-separate` option is a first-class choice: analogs that resolve *different* problems should stay separate even when they share a domain and tags. Refine/Maintain's job is to surface the candidate, not to auto-merge.

package/skills/learn/references/entry-schema.md

@@ -0,0 +1,152 @@
+---
+title: Entry Schema
+description: Authoritative write-contract reference for Capture (drafts) and Refine (validates). Defines the canonical per-entry frontmatter (the unified schema the legacy decision+pattern entries converged to), the per-type body section templates, and the index-record shape that the read side (Plan/Work/Review's learnings-gate-logic) parses. Single source of truth for the entry's shape.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Entry Schema
+
+Authoritative **write contract** for a knowledge entry. Capture drafts the frontmatter and body from this schema; Refine validates against it; Index derives the index-record enum from it; Maintain refreshes stale entries to it. The schema unifies the two historical layouts observed in the legacy store (the newer `decision`/`gotcha` layout with `slug`+`priority`+`applicability`+`confidence`, and the older `pattern`/`workflow` layout with `title`+`category`+`severity`) into one canonical form. Capture/Refine **look this schema up**; they do not re-encode the field list.
+
+> **Write side / read side (single source of truth).** This reference owns the **write side** — the per-entry frontmatter and the `index-record` shape. The Plan skill owns the **read side** — the search algorithm in [learnings-gate-logic.md](../../plan/references/learnings-gate-logic.md). The two contracts share the **index-record shape** (`filename`, `domain`, `tags`, `applicability`, `summary`). Capturing this schema here, once, prevents the secondary-spec-contradicts-authoritative-matrix gotcha: no other reference re-encodes the entry's fields.
+
+## The Four Entry Types
+
+| Type       | Carries                                                                          | Section template (body)                                                                             |
+| ---------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `decision` | An authoritative choice with rationale                                          | Problem / Solution / Decision Rationale / Application / Related Learnings                            |
+| `pattern`  | A confirmed, reusable approach                                                  | Problem / Pattern / When to Apply / Example / Related Learnings                                      |
+| `gotcha`   | A recurring trap with prevention                                                | Problem / Trap / Solution / Prevention / Related Learnings / Source                                 |
+| `workflow` | A project convention                                                            | Convention / Why / How / Related Learnings                                                          |
+
+Each entry is **exactly one** conclusion; one entry per conclusion; never a bundle.
+
+## Per-Entry Frontmatter (canonical, unified)
+
+```yaml
+---
+slug: <kebab-case-slug>                       # REQUIRED. Globally unique. The upsert key for the entry file + index record.
+type: decision | pattern | gotcha | workflow  # REQUIRED. One of the four.
+domain: <primary-domain>                      # REQUIRED. A single primary domain.
+priority: important | normal                  # OPTIONAL (default normal).
+applicability:                                # REQUIRED. Numeric scores per side.
+  current_project: <0-10>                    # How directly the project uses this.
+  general: <0-10>                            # How broadly it generalizes.
+tags: [<related-domain-1>, ...]              # REQUIRED. 2-6 related domains.
+created_at: <ISO-8601>                        # REQUIRED. Set by Capture; Refine preserves.
+updated_at: <ISO-8601>                        # REQUIRED. Stamped on any edit (Refine/Index/Maintain).
+source:                                       # REQUIRED. Where the entry came from.
+  type: commit | candidate | user             # commit: derived from a commit; candidate: from Work/Review; user: freeform author.
+  reference: <commit-sha | report-id#finding-id | text>  # The locator.
+  extracted_at: <ISO-8601>                   # When the entry was captured.
+confidence: high | medium | low               # OPTIONAL (default medium). The author's confidence.
+# Lineage (set by Maintain / migration, optional):
+migrated-from: <docs/learnings/<type>/<file>.md>   # Only for a migrated legacy entry.
+superseded-by: <canonical-slug>              # Only for an analog merged into a canonical entry.
+status: active | obsolete                    # OPTIONAL (default active). `obsolete` de-indexes the entry.
+related: [<slug>, ...]                       # OPTIONAL. Linked entries (a canonical entry lists the analogs it absorbed).
+---
+```
+
+**Field rules (authoritative):**
+
+- `slug` — kebab-case; globally unique across all four types (one slug namespace); descriptive (date suffix allowed for time-bound decisions). Capture proposes; Refine uniqueness-checks; Index upserts on it.
+- `type` — one of the four; the body section template is determined by it (see above). Type does not change after authoring (a `decision` may not be reclassified as a `pattern` post-hoc — that's a new entry with a new `slug`, and the old one de-indexes).
+- `domain` — a single primary domain (never a list); the `tags` carry the related domains.
+- `priority` — `important` for entries that block or strongly steer a skill; `normal` otherwise. Defaults to `normal` when absent.
+- `applicability.current_project` / `general` — integers 0–10. The **write side** stores the rich numerics; the **read side** projects to the enum (see [index-format.md](index-format.md)).
+- `tags` — a list of **2–6** related domains (no more, no fewer; Refine validates the count).
+- `confidence` — `high` / `medium` / `low`; defaults to `medium` when absent.
+- `source.type` — `commit` (derived from a commit sha), `candidate` (from a Work/Review `learnings-to-capture` list), or `user` (freeform `/learn <type> <text>`).
+- `migrated-from` / `superseded-by` / `related` — lineage fields set by Maintain (or Index on a merge), not by Capture. See [dedup-rules.md](dedup-rules.md) and [migration-bootstrap.md](migration-bootstrap.md).
+
+## Per-Type Body Section Templates (authoritative)
+
+A `decision` body has exactly these sections (in order); body sections are validated by Refine:
+
+### decision
+```
+# <Title in Title Case>
+
+## Problem     [what problem this decision resolves]
+## Solution    [the decision — what was chosen]
+## Decision Rationale  [why this choice over alternatives]
+## Application [where in the project this decision lives — files, skills, phases]
+## Related Learnings  [linked slug(s) + one-line role]
+```
+
+### pattern
+```
+# <Title in Title Case>
+
+## Problem    [the recurring problem the pattern solves]
+## Pattern    [the confirmed approach]
+## When to Apply [signals that this pattern fits]
+## Example    [a concrete use of the pattern, ideally in-repo]
+## Related Learnings  [linked slug(s) + one-line role]
+```
+
+### gotcha
+```
+# <Title in Title Case>
+
+## Problem    [the surface symptom]
+## Trap       [the silent failure mode]
+## Solution   [how to fix it once hit]
+## Prevention [how to avoid it next time — the durable part]
+## Related Learnings  [linked slug(s) + one-line role]
+## Source     [file/commit/ref where this was confirmed — optional duplicate of frontmatter.source for human readability]
+```
+
+### workflow
+```
+# <Title in Title Case>
+
+## Convention [the agreed-upon practice]
+## Why        [the reason for the convention]
+## How         [the steps to apply it — concrete, repo-relative]
+## Related Learnings  [linked slug(s) + one-line role]
+```
+
+## Index-Record Shape (the read-contract projection)
+
+`docs/learn/index.md` carries one record per entry in its YAML `entries:` block (format in [index-format.md](index-format.md)). That record projects the full frontmatter to the **five fields** the read side parses:
+
+```yaml
+- filename: docs/learn/<type>/<slug>.md
+  domain: <primary-domain>
+  tags: [tag-1, tag-2]
+  applicability: DIRECT | RECOMMENDED | CONTEXTUAL | HISTORICAL | INFORMATIONAL
+  summary: <1-2 sentence summary — derived from the entry's Problem/Solution>
+```
+
+The `applicability` enum is **derived** from the frontmatter's numeric scores per [index-format.md](index-format.md)'s derivation — never stored twice. The `summary` is the frontmatter's `summary` if present, else the first 1–2 sentences of the entry's Problem/Solution paragraphs. **Field set is fixed**: `filename`, `domain`, `tags`, `applicability`, `summary` — exactly these five (the gate-logic's read contract).
+
+> Note: the canonical frontmatter above does **not** include a `summary` field. Capture/Refine derive the index `summary` from the entry's Problem/Solution body by default; a user may add a `summary` frontmatter field to override. Either way, the index-record carries the `summary`. (Adding `summary` to the frontmatter block above is a non-destructive optional extension; the body sections remain the source of truth by default.)
+
+## Validation Rules (Refine applies)
+
+1. **Frontmatter:** all REQUIRED fields present and well-typed; `type` ∈ the four; `domain` non-empty; `tags` length 2–6; `applicability` scores integers 0–10; `confidence` ∈ enum; `slug` kebab-case.
+2. **Body:** the per-type section template present (all the sections for the type); no extra top-level sections that contradict the template.
+3. **Coherence:** the body title's kebab-case matches the `slug`; the frontmatter `domain` is among the `tags`; the index-record projection (filename/domain/tags/applicability/summary) is computable from the entry.
+4. **On a missing `summary` field:** derive from the body; do not block. On a wrong type/wrong shape: block and ask (Category 2 recovery).
+
+## Migration (legacy → canonical)
+
+Legacy entries use one of two prior layouts; the migration ([migration-bootstrap.md](migration-bootstrap.md)) normalizes both to the canonical schema:
+
+| Legacy layout | Fields present | Canonical conversion |
+| ------------- | -------------- | -------------------- |
+| Newer (decision/gotcha) | `slug`, `type`, `domain`, `priority`, `applicability.{current_project,general}`, `tags`, `confidence` | Already canonical; preserve; add `migrated-from` lineage. |
+| Older (pattern/workflow) | `title`, `category`, `severity`, `domain`, `tags`, `source: commit <sha>` | Convert: `type = category` (the legacy `category` field); `slug = <kebab-case-of-title>[-<date>]`; `priority = important if severity==important else normal`; `applicability.{current_project,general}` inferred from `severity` (`important`→{9,7}, `recommended`→{6,5}, `informational`→{3,4}); `confidence = medium`; restructure `source` to `{type: commit, reference: <sha>, extracted_at: <date>}`. Add `migrated-from`. |
+
+The conversion **preserves content** — the body sections are kept, frontmatter is normalized, lineage is recorded. No legacy entry is silently dropped; no canonical field is invented where the legacy had no basis (an inferred score from `severity` is noted as inferred, never silently exact).
+
+## Notes
+
+- This reference is the single source of truth for the entry's shape. Capture drafts from it; Refine validates against it; Index projects to the index-record from it; Maintain refreshes to it. None re-encode the field list or body templates inline.
+- The schema deliberately separates the **write side** (rich numeric `applicability` + `confidence` + lineage) from the **read side** (the enum projection in the index-record). This honors the secondary-spec gotcha: the search algorithm lives once in Plan's gate-logic; the entry schema lives once here.
+- A `summary` field is **optional** in the frontmatter (overriding the body-derived default); the index-record always carries a `summary`.
+- Changing an entry's `type` post-hoc is a **new entry** (new `slug`), and the old entry de-indexes — never an in-place reclassification (a decision is a decision; a pattern is a pattern).

package/skills/learn/references/error-handling.md

@@ -0,0 +1,178 @@
+---
+title: Error Handling & Recovery
+description: Reference for all Learn Skill phases (Capture, Refine, Index, Maintain). Defines the Step 0 artifact verification procedure, per-type required fields, error categories, recovery workflow, retry limits, and cross-phase consistency checks. Applies to durable knowledge curation, not transient sessions.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Error Handling & Recovery
+
+This file documents the error handling and recovery strategies shared across all Learn Skill phases (Capture, Refine, Index, Maintain). Each phase begins with a **Step 0: Verification** that validates the incoming artifact; this reference defines the validation rules, recovery actions, and termination conditions.
+
+## Core Principle
+
+**Fail explicitly, never silently.** When an artifact is missing, malformed, or inconsistent, the phase must surface a clear error with a recovery suggestion rather than guessing or proceeding with bad data. Silent failures corrupt the canonical knowledge base — a wrong `slug` collision, a silently coerced field, or a skipped duplicate check cascades into a polluted index that Plan/Work/Review then read as source of truth. The one recognized non-block is a **missing `docs/learn/` store entirely** (the Orchestrator's Pre-Flight seeds it), and a **no-op maintain step** (e.g. migration when already migrated, or no analogs to merge) which records `no-op` and proceeds — these are deliberate non-blocks with explicit notes, not silent skips.
+
+## Step 0: Artifact Verification
+
+Every phase receives an artifact from the previous phase (or the Orchestrator, for Capture). Step 0 validates the artifact before any work begins.
+
+### Verification Procedure
+
+```
+1. Confirm the artifact exists and is non-empty
+2. Confirm the required frontmatter fields are present and well-formed
+3. Confirm the artifact type matches the expected phase input
+4. Confirm interactionMode is present and valid (default to "smart" if missing)
+5. Confirm cross-phase IDs match the upstream artifacts
+6. Confirm routing: a "maintain" shape must not reach Capture/Refine/Index; an authoring shape must not reach Maintain
+```
+
+### Required Fields by Artifact Type
+
+| Artifact Type      | Required Fields                                                                                                                                                                  | Produced By  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| `learn-input`       | `type`, `timestamp`, `source`, `status`, input shape (`explicit: {type, text}` **or** `candidate: {ref}` **or** `maintain: true`), `interactionMode`                              | Orchestrator |
+| `captured-entry`    | `capture-id`, `learn-id`, `input-shape`, `status`, `interactionMode`, `target-type` (one of the four), proposed `slug`, drafted `frontmatter`, drafted `body`, `source-candidate`   | Capture      |
+| `refined-entry`     | `refine-id`, `capture-id`, `learn-id`, `input-shape`, `status`, `interactionMode`, validated `type`, resolved `slug`, validated `frontmatter`/`body`, `dup-status`, `resolution`  | Refine       |
+| `index-update`      | `index-id`, `refine-id`, `capture-id`, `learn-id`, `input-shape`, `status`, `interactionMode`, `entry-path`, `slug`, `type`, `index-applicability`, `index-action`, `index-coherent` | Index        |
+| `maintain-log`      | `maintain-id`, `interactionMode`, `status`, `migration`, `merges`, `refresh`, `prune`, `rebuild`, `index-coherent` (no `learn-id` umbrella — Maintain authors no new entry)         | Maintain     |
+
+## Error Categories
+
+### Category 1: Missing Artifact
+
+The expected input artifact was not provided by the Orchestrator or previous phase.
+
+| Trigger                           | Recovery Action                                               | Terminate?         |
+| --------------------------------- | ------------------------------------------------------------- | ------------------ |
+| Artifact object is null/undefined | Ask Orchestrator to re-run previous phase                     | Yes, after 1 retry |
+| Artifact file path does not exist | Log warning; ask user to locate file or re-run previous phase | No                 |
+| Artifact file is empty (0 bytes)   | Re-run previous phase from its saved context                | Yes, after 1 retry |
+
+### Category 2: Malformed Artifact
+
+The artifact exists but is missing required fields or has invalid structure.
+
+| Trigger                                       | Recovery Action                                             | Terminate? |
+| --------------------------------------------- | ----------------------------------------------------------- | ---------- |
+| Missing required frontmatter field            | Re-run previous phase to regenerate artifact                | No         |
+| `interactionMode` missing or invalid          | Default to `smart`; log warning; continue                   | No         |
+| `status` field is `failed` or `pending`       | Reject; ask Orchestrator to re-run previous phase           | Yes        |
+| Artifact `type` does not match expected input | Reject; ask Orchestrator to check phase ordering            | Yes        |
+| YAML frontmatter has syntax errors            | Log error with line number; ask user to fix or re-run phase | No         |
+| Routing: `maintain` reached Capture/Refine/Index | Reject; Orchestrator routes maintain directly to Maintain | Yes        |
+| Routing: authoring shape reached Maintain      | Reject; Orchestrator should route to Capture                | Yes        |
+| Target-type not one of the four (Capture Step 1) | Ask user to pick from `decision`/`pattern`/`gotcha`/`workflow` | No      |
+
+### Category 3: Invalid Learn Input
+
+Only applies to the Capture phase (Step 0) when resolving a Learn Input Artifact.
+
+| Trigger                                              | Recovery Action                                            | Terminate? |
+| ---------------------------------------------------- | --------------------------------------------------------- | ---------- |
+| All three input shapes empty or ambiguous           | Ask: "What would you like to capture? Type + text, candidate ref, or `maintain`." | No         |
+| Explicit `<type>` not one of the four                | Ask the user to pick from the four                          | No         |
+| Explicit `<text>` is a bare ref that cannot be read (file/commit) | Ask the user to supply the decision in prose         | No         |
+| Candidate `ref` does not resolve to a report file    | Ask the user to pick a valid Work `review-id` / Review `report-id` | No         |
+| Candidate report's `learnings-to-capture` list is empty | Inform the user (no candidates to curate); stop       | No         |
+| Maintain requested but `docs/learn/` and `docs/learnings/` are both absent | Inform the user; the store must exist (or legacy) before a maintain | No |
+
+### Category 4: File System Errors
+
+Errors encountered while saving or reading entry/index files.
+
+| Trigger                                          | Recovery Action                                                   | Terminate?         |
+| ------------------------------------------------ | ----------------------------------------------------------------- | ------------------ |
+| `docs/learn/` does not exist                    | Create it (Orchestrator Pre-Flight creates; Index creates `<type>/` subdir); continue | No |
+| `docs/learn/index.md` does not exist             | Seed it from [index-format.md](index-format.md) (YAML block + tables headers); continue | No |
+| Phase save directory does not exist              | Create it; treat counter as 0; start from 001 (Pre-Flight creates) | No                 |
+| Counter directory exists but no files match date | Start counter at 001                                              | No                 |
+| File write permission denied                     | Log error; ask user to check permissions; retry once              | Yes, after 1 retry |
+| De-indexing an analog whose canonical entry is itself absent | Log; revert the merge; ask the user (the lineage link is broken) | No |
+
+### Category 5: Interaction Mode Errors
+
+Errors related to `interactionMode` propagation.
+
+| Trigger                                  | Recovery Action                                            | Terminate? |
+| ---------------------------------------- | ---------------------------------------------------------- | ---------- |
+| Mode missing from incoming artifact      | Default to "smart"; log warning; continue                  | No         |
+| Mode value is not in enum                | Reject; re-prompt Orchestrator to set valid mode            | Yes        |
+| User selects "Abort" during confirmation | Stop immediately; inform Orchestrator of abort with reason | Yes        |
+| User does not respond (timeout)          | Pause; ask user to retry or abort                          | No         |
+
+### Category 6: Curation Errors (Refine / Index / Maintain)
+
+| Trigger                                              | Recovery Action                                                    | Terminate? |
+| ---------------------------------------------------- | ------------------------------------------------------------------ | ---------- |
+| Refine: a required body section is missing            | Ask the user to add it (never auto-fill silently)                  | No         |
+| Refine: a frontmatter field has a wrong type/value    | Surface the field, suggest the fix, ask the user; never coerce      | No         |
+| Refine: exact `slug` found (a re-author)              | Smart pause: update-existing vs new-slug; never silently two       | No         |
+| Index: `index-coherent: false` after the upsert       | Reconcile (the file tree is source of truth); warn; suggest `/learn maintain` | No |
+| Maintain: a prune candidate's canonical reference is live in `related` | Do not prune; it is referenced (lineage would break) — surface to user | No |
+| Maintain: rebuild left `index-coherent: false`        | Re-run Step 5 (the rebuild); if still failing, terminate          | Yes, after 1 retry |
+
+## Recovery Workflow
+
+When a verification failure is detected in Step 0, apply this workflow:
+
+```
+1. Identify the error category (1-6) from the tables above
+2. Look up the specific trigger to find the recovery action
+3. Execute the recovery action:
+   - If recovery is "ask user": ask one question with clear options (2-4 concrete choices)
+   - If recovery is "re-run previous phase": return to Orchestrator with error context
+   - If recovery is "default and continue": apply default, log warning, proceed
+4. If terminate = Yes: stop and inform Orchestrator with:
+   - Error category and trigger
+   - Recovery action attempted
+   - Reason for termination
+5. If terminate = No: after recovery, continue to Step 1 of the phase
+```
+
+## Retry Limits
+
+- **Maximum retries per error:** 1
+- **Maximum total retries per phase:** 2
+- After exhausting phase retries, terminate with a clear error suggesting the user re-run the Learn run from the start or resume from the last complete phase.
+
+> An authoring run (`/learn <type> <text>`) is **not resume-safe**: re-running over the same content upserts on `slug` (idempotent — better than resuming). A maintain run is idempotent and self-gating (the migration is one-time, no-op thereafter).
+
+## Error Reporting Format
+
+When reporting an error to the Orchestrator or user, use this format:
+
+```yaml
+error:
+  phase: capture | refine | index | maintain
+  step: 0 | 1 | 2 | ...
+  category: 1 | 2 | 3 | 4 | 5 | 6
+  trigger: "[specific trigger description]"
+  recovery_attempted: "[action taken]"
+  outcome: recovered | terminated
+  suggestion: "[next step for the user or Orchestrator]"
+```
+
+## Cross-Phase Consistency Checks
+
+The Orchestrator should verify consistency between phases:
+
+| Check                                                                 | Action on Failure                           |
+| --------------------------------------------------------------------- | ------------------------------------------- |
+| `learn-id` in downstream artifact matches the Capture output          | Reject; re-run from Capture                |
+| `capture-id` in Refine+ matches Capture output                       | Reject; re-run from Capture                 |
+| `refine-id` in Index matches Refine output                            | Reject; re-run from Refine                  |
+| `interactionMode` is identical across all artifacts                   | Log warning; use earliest non-default value |
+| `maintain-id` standalone (no `learn-id` expected for a maintain run)  | If a `learn-id` is present on a maintain artifact, log warning; treat as orphan | 
+| Routing: authoring shape produces Capture→Refine→Index; `maintain` shape produces only Maintain | Reject; surface routing bug |
+
+## Notes
+
+- All errors and warnings should be logged with a timestamp for debugging.
+- When a phase terminates, its saved artifact (if any) should be marked `status: failed`.
+- The Orchestrator is responsible for deciding whether to retry the entire workflow or resume from the last successful phase.
+- ID assignment and re-use (including recycle-on-edit) is defined in [id-generation.md](id-generation.md); this reference covers only verification and recovery.
+- The per-entry frontmatter schema (the write contract) is defined in [entry-schema.md](entry-schema.md); the index format is defined in [index-format.md](index-format.md); the duplicate/merge logic is defined in [dedup-rules.md](dedup-rules.md); the one-time migration is defined in [migration-bootstrap.md](migration-bootstrap.md). This reference covers only verification/recovery and never re-encodes those contracts.
+- This reference is shared by all four phases; phase-specific handling is documented inline in the respective module.

package/skills/learn/references/id-generation.md

@@ -0,0 +1,114 @@
+---
+title: Artifact ID Generation
+description: Reference for Capture, Refine, Index, and Maintain phases. Defines the daily-counter algorithm for unique phase artifacts, the learn-id umbrella allocation, the maintain-id standalone allocation (no learn-id), the entry slug derivation, and the recycle-on-edit rule.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Artifact ID Generation
+
+Shared ID algorithm for the `capture`, `refine`, `index`, and `maintain` phases, plus the `learn-id` umbrella (Capture is the allocating phase), the `maintain-id` standalone allocation, and the **entry `slug`** derivation (the upsert key for the entry file and the index record). Each phase assigns exactly one ID per newly produced artifact; the ID is reused (never re-incremented) when the user picks **Edit & Retry** at the phase confirmation.
+
+## ID Format by Phase
+
+| Phase    | ID format                            | Saved to                            |
+| -------- | ----------------------------------- | ----------------------------------- |
+| Capture  | `YYYY-MM-DD-NNN-capture`            | `docs/plans/.learn/.capture/<id>.md`   |
+| Refine   | `YYYY-MM-DD-NNN-refine`             | `docs/plans/.learn/.refine/<id>.md`    |
+| Index    | `YYYY-MM-DD-NNN-index`              | `docs/plans/.learn/.index/<id>.md`     |
+| Maintain | `YYYY-MM-DD-NNN-maintain`           | `docs/plans/.learn/.maintain/<id>.md`  |
+
+`learn-id` (see below) is the umbrella shared across Capture → Refine → Index. **Maintain has no `learn-id`** — it authors no new entry; it allocates only a standalone `maintain-id`.
+
+## learn-id (umbrella — authoring runs)
+
+Allocated **only in Capture** Step 4:
+
+```
+1. Get the current date in UTC
+2. List existing files under docs/plans/.learn/.capture/ matching YYYY-MM-DD-NNN-capture.md for that date
+3. NNN = (highest existing NNN for that date), zero-padded to 3 digits
+   - if none exist for that date, start at 001
+4. learn-id = "<date>-<NNN>"  (the same NNN as the capture-id being allocated)
+5. Write the capture artifact with both learn-id and capture-id
+```
+
+Because `learn-id` reuses the capture counter's NNN, the umbrella id and the `capture-id` share the same date+counter suffix (e.g., `learn-id: 2026-08-08-001` → `capture-id: 2026-08-08-001-capture`). Refine and Index **inherit** that same NNN — they do **not** independently allocate a competing NNN. If the NNN is taken by an unrelated artifact on the same date in a later phase directory (rare), the later phase appends and notes the divergence in its artifact (the umbrella `learn-id` is still carried everywhere).
+
+## maintain-id (standalone — maintain runs)
+
+Allocated **only in Maintain** Step 6:
+
+```
+1. Get the current date in UTC
+2. List existing files under docs/plans/.learn/.maintain/ matching YYYY-MM-DD-NNN-maintain.md for that date
+3. NNN = (count + 1), zero-padded to 3 digits
+4. maintain-id = "<date>-<NNN>-maintain"
+```
+
+A maintain artifact carries only `maintain-id`, never `learn-id` (a `learn-id` on a maintain artifact is treated as an orphan and logged per [error-handling.md](error-handling.md) Cross-Phase Consistency Checks).
+
+## entry slug (upsert key — authored knowledge)
+
+The `slug` is the stable, globally-unique key for a knowledge entry — it keys the entry file path (`docs/learn/<type>/<slug>.md`) and the index record. Capture **proposes** it; Refine **validates** uniqueness; Index **upserts** on it.
+
+**Algorithm (Capture Step 4 proposes):**
+
+```
+1. Extract a concise, descriptive phrase from the entry title / problem statement
+2. Convert to kebab-case (lowercase, non-alphanumeric → hyphen, collapse repeats, trim)
+3. For time-bound decisions, a date suffix is allowed when the legacy/source used one:
+   critical-risk-tier-security-payments-2026-07-04
+4. The slug must be globally unique across docs/learn/<type>/ (all types share one slug
+   namespace — a decision's slug cannot collide with a pattern's slug)
+5. Capture proposes; Refine checks against the existing entries
+```
+
+**On a collision (Refine Step 3):** Refine runs the duplicate/analog check per [dedup-rules.md](dedup-rules.md). An exact match gives the user two choices: **update-existing** (keep the `slug`, overwrite the file + index record) or **new-slug** (append a distinguishing suffix, e.g., `<slug>-v2` or a domain qualifier). Capture does **not** pre-resolve collisions.
+
+> **Slug is the upsert key, not a timestamp id.** A re-author with the same `slug` overwrites in place (idempotent); a new `slug` creates a new entry. The slug namespace is shared across all four types — there is one global `docs/learn/` slug space, not four.
+
+## Algorithm (new phase artifact)
+
+```
+1. Get the current date in UTC (e.g., 2026-08-08)
+2. List existing files for today in the phase's save directory:
+   - capture  -> docs/plans/.learn/.capture/  matching YYYY-MM-DD-*-capture.md
+   - refine   -> docs/plans/.learn/.refine/   matching YYYY-MM-DD-*-refine.md
+   - index    -> docs/plans/.learn/.index/    matching YYYY-MM-DD-*-index.md
+   - maintain -> docs/plans/.learn/.maintain/ matching YYYY-MM-DD-*-maintain.md
+3. NNN = (count + 1), zero-padded to 3 digits (001, 002, ..., 010, ...)
+4. id = "<date>-<NNN>-<phase>"
+```
+
+Counters are independent per phase; each phase counts only its own files.
+
+## Recycle on Edit & Retry
+
+When the user picks **Edit & Retry** at a phase confirmation, **reuse the original ID** and overwrite the existing artifact file. Do **not** increment the counter. This keeps IDs stable across iterations and prevents orphaned artifacts. The Index phase's upsert on `slug` is likewise idempotent (overwrite the entry file + index record, never duplicate). Maintain's `maintain-id` reuses the same id across re-run steps within one maintain session.
+
+## Migration Note (entry slugs on legacy entries)
+
+The legacy `docs/learnings/` store uses filenames, not slugs, as the key. The migration ([migration-bootstrap.md](migration-bootstrap.md)) **derives the canonical `slug`** from each legacy filename:
+
+- `2026-07-04-critical-risk-tier-security-payments.md` → `slug: critical-risk-tier-security-payments-2026-07-04` (date kept as suffix when the file used one; the type-prefixed files already carry the date in)
+- `daily-counter-artifact-naming-2026-07-02.md` → `slug: daily-counter-artifact-naming-2026-07-02`
+- The original filename is preserved in the entry's `migrated-from` lineage field, so the old path knowledge is not lost.
+
+## Error Handling
+
+| Trigger                                         | Action                                       |
+| ----------------------------------------------- | -------------------------------------------- |
+| Phase save directory does not exist              | Create it (Pre-Flight already creates); treat count as 0; start from 001  |
+| Directory exists but no files match today's date | Start counter at 001                         |
+| `docs/learn/` missing                           | Create it; Index creates `<type>/` subdir; Maintain seeds the index (Pre-Flight helps) |
+| Write permission denied                         | Log error; ask the user; retry once          |
+| Slug collision at Capture (should not happen — Refine's job) | Capture proposes; Refine resolves — never silently two |
+
+## Notes
+
+- IDs reuse the daily-counter algorithm for cross-skill consistency with `/plan`, `/work`, and `/review`; the Learn skill's counters are independent from those skills (separate save directories under `docs/plans/.learn/`).
+- `learn-id` carries through Capture → Refine → Index; Maintain uses the standalone `maintain-id` only. Cross-phase chaining is `capture-id → refine-id → index-id`, all sharing one `learn-id` (see [error-handling.md](error-handling.md) "Cross-Phase Consistency Checks").
+- The `slug` is a **separate** key from the phase ids — it identifies the durable knowledge entry across re-authors, not the pipeline run. A single `slug` may be authored by many `learn-id` runs over time (each upsert overwrites); the `slug` is stable, the `learn-id` is per-run.
+- Counter collisions are impossible within a date because each phase writes to its own directory and recomputes the count from the directory listing.