arreio 1.0.0-dev.1

package/skills/learn/references/index-format.md

@@ -0,0 +1,140 @@
+---
+title: Index Format
+description: Authoritative reference for the Index phase (upsert) and Maintain phase (rebuild). Defines the canonical docs/learn/index.md structure: a YAML entries block (the read-contract record per entry — filename/domain/tags/applicability/summary) plus the human-readable By Category / By Domain markdown tables. Defines the applicability-enum derivation from the per-entry numeric scores and the idempotency rule.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Index Format
+
+Authoritative reference for the canonical `docs/learn/index.md` format. Defines the **hybrid structure** — a YAML `entries:` block (the read-contract record per entry) plus the human-readable **By Category** / **By Domain** markdown tables — and the **`applicability` enum derivation** from the per-entry numeric scores (the write→read projection). Index upserts one record per authoring run; Maintain rebuilds the whole index from the file tree (the source of truth). Both apply this format; neither re-encodes it.
+
+> This is the file Plan, Work, and Review all read via [learnings-gate-logic.md](../../plan/references/learnings-gate-logic.md). The YAML `entries:` block is the **read contract** — the five-field record shape the gate-logic parses. The markdown tables are the human-readable projection of the same data. Both are derived from the per-entry frontmatter ([entry-schema.md](entry-schema.md)); the index never stores a field the entry's frontmatter cannot produce. **No second formula** — the search algorithm lives in Plan's gate-logic; the format lives here.
+
+## Canonical Structure
+
+```markdown
+# Knowledge Index
+
+The project's durable knowledge base. Source of truth for decisions, patterns,
+gotchas, and workflows. Plan/Work/Review search this index via the YAML block.
+
+**Last updated:** <ISO-8601>
+
+## Entries
+
+```yaml
+entries:
+  - filename: docs/learn/decision/critical-risk-tier-security-payments-2026-07-04.md
+    domain: planning
+    tags: [risk-assessment, security]
+    applicability: DIRECT
+    summary: CRITICAL risk tier above HIGH for security/payments; always external research
+  - filename: docs/learn/gotcha/secondary-spec-contradicts-authoritative-matrix.md
+    domain: skill-design
+    tags: [single-source-of-truth, contradictions]
+    applicability: DIRECT
+    summary: Don't re-encode an authoritative matrix as a contradicting secondary formula
+  # ...one record per on-disk entry; de-indexed (obsolete/superseded) entries are EXCLUDED
+```
+
+## By Category
+
+### Decision (N)
+
+| File | Title | Domain | Applicability |
+|------|-------|--------|---------------|
+| [critical-risk-tier-security-payments-2026-07-04.md](decision/critical-risk-tier-security-payments-2026-07-04.md) | Introduce CRITICAL Risk Tier Above HIGH for Security/Payments Areas | planning | DIRECT |
+| ... | ... | ... | ... |
+
+### Pattern (N)
+... (same table shape, a row per pattern)
+
+### Gotcha (N)
+... (same table shape, a row per gotcha)
+
+### Workflow (N)
+... (same table shape, a row per workflow)
+
+## By Domain
+
+- **planning:** critical-risk-tier-security-payments-2026-07-04, plan-tier-selection-algorithm-2026-07-04, ...
+- **skill-design:** pipeline-phase-module-template-2026-07-04, quality-gates-pipeline-orchestration-2026-07-04, ...
+- **artifact-naming:** daily-counter-artifact-naming-2026-07-02, cross-phase-id-chaining-2026-07-04, ...
+- ... (one bullet per domain, listing the slugs; de-indexed entries excluded)
+```
+
+## Read-Contract Record (the YAML `entries:` block)
+
+Each record carries **exactly these five fields** — the gate-logic's read contract. No more, no fewer:
+
+```yaml
+- filename: docs/learn/<type>/<slug>.md    # REQUIRED. Repo-relative path to the entry file.
+  domain: <primary-domain>                # REQUIRED. The entry's frontmatter domain.
+  tags: [<tag>, ...]                       # REQUIRED. The entry's frontmatter tags (carried verbatim).
+  applicability: <enum>                    # REQUIRED. Derived per the table below — never stored on the entry.
+  summary: <1-2 sentence summary>         # REQUIRED. The frontmatter summary, or the body Problem/Solution derivation.
+```
+
+- `filename` — repo-relative; uses forward slashes; stable (the slug is the upsert key, so the filename is stable across re-authors).
+- `domain`, `tags` — carried verbatim from the entry's frontmatter.
+- `applicability` — **derived** (see below), never stored on the entry's frontmatter (the entry keeps the numeric scores; the index projects to the enum).
+- `summary` — the entry's frontmatter `summary` field if present; else the first 1–2 sentences of the entry's Problem/Solution body (Capture/Refine/Index derive this; Maintain re-derives on rebuild).
+
+## Applicability Enum Derivation (authoritative)
+
+The write side (the entry frontmatter per [entry-schema.md](entry-schema.md)) stores `applicability: { current_project: N, general: N }`. The index-record projects this to a single enum (the read side's vocabulary). The derivation:
+
+| Condition (write-side numerics)           | Enum          | Gate-logic handling                 |
+| ----------------------------------------- | ------------- | ----------------------------------- |
+| `current_project ≥ 8 AND general ≥ 7`    | `DIRECT`      | HIGH relevance — included           |
+| `current_project ≥ 5 AND general ≥ 5`    | `RECOMMENDED` | MEDIUM relevance — included         |
+| `general ≥ 5`                             | `CONTEXTUAL`  | MEDIUM relevance — included         |
+| `general ≥ 3`                             | `HISTORICAL`  | LOW relevance — excluded by gate    |
+| otherwise                                 | `INFORMATIONAL` | LOW relevance — excluded         |
+
+The enum is computed by Index Step 1 (for upsert) and Maintain Step 5 (for rebuild) from the entry's frontmatter. **It is never stored on the entry** — projecting from the numeric scores to the enum at index time avoids a second-source contradiction (honoring the secondary-spec gotcha: one mapping lives here, the entry keeps the rich numerics).
+
+> Gate-logic relevance: gate-logic matches keywords, then scores HIGH/MEDIUM/LOW. The enum above maps DIRECT/RECOMMENDED/CONTEXTUAL/HISTORICAL/INFORMATIONAL to that HIGH/MEDIUM/LOW banding (DIRECT/RECOMMENDED/CONTEXTUAL are potentially HIGH/MEDIUM; HISTORICAL/INFORMATIONAL are LOW). The mapping lives in the gate-logic, not here — here we only produce the enum the gate-logic expects.
+
+## By Category / By Domain Tables
+
+The human-readable projection. Both are **derived** from the same on-disk entries (the YAML block and the tables are in lockstep; Index/Maintain never allow them to drift):
+
+- **By Category** — four `### <Type> (N)` subsections (Decision/Pattern/Gotcha/Workflow), each a `| File | Title | Domain | Applicability |` markdown table, one row per entry of that type. The `(N)` is the count of that type's entries.
+- **By Domain** — one bullet per domain, listing the slugs of that domain's entries, comma-separated. Covering all on-disk domains (the union of every entry's `domain`).
+
+`Title` is the entry's body `# <Title>` heading (Title Case), carried verbatim. `Applicability` is the same derived enum as the YAML record. `De-indexed` entries (frontmatter `status: obsolete` or a `superseded-by` whose canonical is present) are **excluded** from both the YAML block and the tables.
+
+## Idempotency
+
+`docs/learn/index.md` is upserted by `slug`:
+
+- **Upsert (Index Step 3)** — the record is updated in place in the YAML `entries:` block (matched on `filename`), and the row is updated in place in the By Category table and the By Domain bullet (matched on `slug`/title). A re-author with the same `slug` overwrites the record, never appends a second.
+- **Rebuild (Maintain Step 5)** — the file tree is the source of truth: re-scan `docs/learn/<type>/*.md`, regenerate the YAML block and the tables, recompute the per-type `(N)` counts and the By Domain bullets. Idempotent (re-running rebuild over an unchanged tree produces an identical file).
+
+**Totals coherence** is the invariant: the YAML `entries:` block length must equal the count of non-de-indexed entry files on disk; each `### <Type> (N)` count must equal the number of records of that type in the YAML block; the By Domain bullets must list the same entries. If any drifts, Index reconciles in-place (non-destructive) and Maintain fully rebuilds.
+
+## Validation (Index Step 3 / Maintain Step 5 re-checks)
+
+- Every on-disk entry (non-de-indexed) has exactly one YAML record and exactly one row in By Category and one slug in By Domain.
+- Every `applicability` enum in the index matches the derivation for that entry's frontmatter numerics (no drift).
+- The `(N)` counts match the YAML records per type.
+- The `summary` is present for every record (body-derived if absent in frontmatter).
+- No two records share a `filename` (the upsert key is unique).
+
+## Failure-Condition Reference
+
+| Trigger                                                  | Outcome per this reference                              |
+| -------------------------------------------------------- | ------------------------------------------------------- |
+| An entry's frontmatter lacks numerics entirely (legacy pre-Schema entry) | Migration/Maintain infers from the legacy `severity` per [migration-bootstrap.md](migration-bootstrap.md); no inference here. |
+| Two on-disk entries have the same `slug` (corrupt store)  | Index/Maintain detect the duplicate `filename` in the YAML; flag; the user picks the canonical (dedup per [dedup-rules.md](dedup-rules.md)). |
+| An entry has a `superseded-by` but is still in the YAML block | Refine/Maintain de-index it (remove the record + row); the canonical's `related` already links its slug. |
+
+## Notes
+
+- This reference is the single source of truth for the canonical index format, the read-contract record (five fields), the applicability-enum derivation, and the idempotency rules. Index and Maintain apply it; the orchestrator and modules never re-encode the format inline.
+- The YAML block and the markdown tables are **two projections of one on-disk truth** (the entry files). Allowing them to drift would re-introduce the secondary-spec gotcha at the index level; the idempotency invariant prevents that.
+- The `index-applicability` enum is the bridge between the write side (rich numerics) and the read side (HIGH/MEDIUM/LOW banding). It is **derived**, never stored on the entry — stored once here, derived once at index time.
+- De-indexed entries (obsolete / superseded) remain on disk but are removed from the index. `docs/learn/index.md` is an index of **active** knowledge, not a registry of every file ever written.

package/skills/learn/references/interaction-mode-propagation.md

@@ -0,0 +1,89 @@
+---
+title: Interaction Mode Propagation
+description: Reference for how `interactionMode` propagates through the Learn pipeline (Capture -> Refine -> Index -> Maintain). Set at the Orchestrator; each phase reads and applies mode-specific behavior. The Learn skill has no execution mode — only interactionMode.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Interaction Mode Propagation
+
+Reference for how `interactionMode` propagates through the Learn pipeline (`Capture → Refine → Index → Maintain`). Set at the Orchestrator; each phase reads and applies mode-specific behavior.
+
+> `interactionMode` governs **when to pause for the user**. Like Review, the Learn skill has **no execution mode** — curation is a single forward pass per entry (or a reconcile pass for Maintain), not a multi-task run, so there is no `executionMode` selector. Only `interactionMode` is carried through every artifact.
+
+## Modes
+
+| Mode          | Behavior                                              | Use Case                             |
+| ------------- | ----------------------------------------------------- | ------------------------------------ |
+| **Detailed**  | Pause at each phase; present artifacts; require approval | Authoritative decisions, sensitive maintenance, unfamiliar curation |
+| **Smart**     | Auto-proceed; pause only on destructive/ambiguous operations (a likely-duplicate, a merge, a prune, a migration rewrite, a draft inferred from a short text) | Most routine curation |
+| **Autopilot** | Auto-proceed for non-destructive steps; **still pause** for destructive operations (migration, prune, merge — never silently delete or rewrite paths) | Routine, well-scoped entries |
+
+## Phase Behavior by Mode
+
+| Phase        | Detailed                                         | Smart                                                                                                       | Autopilot                         |
+| ------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| **Capture**  | Present captured entry; ask Proceed/Edit/Abort   | Auto-proceed; pause if candidate/inferred draft (inferred type, domain, tags, body), or a bare ref that could not be read | Auto-proceed (still confirms inferred content per below) |
+| **Refine**   | Present refined entry; ask Proceed/Edit/Abort    | Auto-proceed; pause on `dup-status: exact` (update vs new-slug), `dup-status: analog` (merge vs keep), a failed frontmatter field, or a missing body section | Auto-proceed (still surfaces duplicate/merge conflicts — destructive, never silent) |
+| **Index**    | Present index update; ask Finalize/Edit/Abort    | Auto-proceed; pause on `index-action: created` (overwrite of existing `slug`), `index-action: merged` (analog de-index), or an incoherent prior index that needed reconcile | Auto-proceed (still confirms overwrite + merge — destructive) |
+| **Maintain** | Present maintain log; ask Finalize/Edit/Abort     | Auto-proceed for non-destructive (refresh, rebuild); pause for migration rewrite, prune, merge, or incoherent rebuild | Auto-proceed for non-destructive; **still pauses** for migration/prune/merge (destructive — Autopilot never silently deletes or rewrites 28 paths) |
+
+**Smart mode pauses only on each phase's documented triggers above** (the canonical list lives in each module's confirmation step; this table is a summary).
+
+**Destructive operations are never silent, even in Autopilot.** This is the Learn skill's guardrail against corrupting the canonical knowledge base: a migration that rewrites 28 entry paths, a prune that deletes a file, and a merge that de-indexes an analog all surface for user confirmation regardless of the interaction mode. Non-destructive curation (drafting a new entry, refreshing frontmatter defaults, rebuilding the index from the file tree) automates freely.
+
+## Artifact Schema
+
+All phase artifacts include `interactionMode`:
+
+```yaml
+interactionMode: detailed | smart | autopilot # Passed from previous phase
+status: pending | complete | failed
+```
+
+## Implementation
+
+**Each phase must:**
+
+1. Read `interactionMode` from the incoming artifact (or context, for Capture).
+2. Apply mode-specific behavior per the table above.
+3. Include `interactionMode` in the output artifact.
+
+## Example
+
+**SMART mode on an explicit decision author:**
+
+- Capture reads user-provided prose grounded in a commit ref (not inferred) → auto-proceeds
+- Refine finds no exact/analog duplicate → auto-proceeds
+- Index creates a new entry file (no overwrite) and upserts the index → auto-proceeds (the `created` action was not an overwrite)
+- Result: a durable decision entry written with no pause; faster than Detailed, safe because the run was non-destructive
+
+**AUTOPilot mode on a `/learn maintain` after the store drifted:**
+
+- Maintain Step 1 migration: skips (`no-op, already migrated`)
+- Maintain Step 2 dedup: finds an analog pair → **pauses** (merge is destructive — Autopilot confirms)
+- User confirms the merge → Maintain de-indexes the analog with lineage
+- Maintain Step 3 refresh: auto-proceeds (non-destructive)
+- Maintain Step 4 prune: finds an obsolete entry → **pauses** (prune is destructive — Autopilot confirms; default = de-index, not delete)
+- Maintain Step 5 rebuild: auto-proceeds (non-destructive)
+
+**Result:** Paused only for the two destructive operations; the non-destructive refresh/rebuild ran automatically.
+
+## No Execution Mode (contrast with Work)
+
+Learn deliberately has **no** `executionMode`:
+
+- Work's `executionMode` (`inline`/`serial`/`parallel`) governs how multiple independent **tasks** run — Learn has no multi-task concept; curation is one entry per run (or a reconcile pass).
+- The orchestrator's quality gate #2 for Learn cross-checks **only** `interactionMode` (not `interactionMode` + `executionMode` as in Work).
+- A duplicate/migration/prune is the Learn analog of Work's HIGH-risk flag: it triggers pause behavior via `interactionMode`'s Smart triggers, not a separate mode.
+
+## Error Handling
+
+| Scenario                    | Recovery                              |
+| --------------------------- | ------------------------------------- |
+| Mode missing                | Default to "smart"; log warning       |
+| Invalid mode value          | Reject; re-prompt Orchestrator        |
+| Artifact missing mode field | Assume "smart"; log warning; continue |
+| User selects "Abort"        | Stop immediately; inform Orchestrator |
+| Timeout/connection lost     | Pause; ask user to retry or abort     |

package/skills/learn/references/migration-bootstrap.md

@@ -0,0 +1,142 @@
+---
+title: Migration Bootstrap
+description: Authoritative reference for the Maintain phase (Step 1, one-time, self-gating). Defines the procedure for migrating the legacy docs/learnings/ store into the canonical docs/learn/ store: slug derivation from legacy filenames, frontmatter normalization per entry-schema, cross-reference rewriting (entry body + related links), the migrated-from lineage note, the .migrated marker, the self-gate (no-op if already migrated), and the rule that the legacy store is never deleted.
+type: reference
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Migration Bootstrap
+
+Authoritative reference for the **Maintain** phase (Step 1, one-time, self-gating). Defines the procedure for migrating the legacy `docs/learnings/` store into the canonical `docs/learn/` store: **slug derivation** from legacy filenames, **frontmatter normalization** per [entry-schema.md](entry-schema.md), **cross-reference rewriting** (entry bodies + `related` links), the **`migrated-from` lineage note**, the **`.migrated` marker**, the **self-gate** (a no-op when already migrated), and the hard rule that **the legacy store is never deleted by the migration**. Maintain invokes this reference; it does not re-derive the procedure.
+
+## Core Principle
+
+> **One-time, self-gating, idempotent, lineage-preserving.** The migration runs once (the `.migrated` marker and slug-set parity prevent re-runs); it is idempotent (re-invoking is a no-op); it preserves lineage (each migrated entry records its `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 knowledge, never just the new). The legacy store stays on disk, read-only and superseded, until the user explicitly prunes it (a destructive, confirm-each step in Maintain, never part of the migration itself).
+
+## Trigger & Self-Gate
+
+Maintain runs the migration only when **all** are true:
+
+1. `docs/learnings/` exists and is non-empty (legacy store present).
+2. `docs/learn/` does not yet have the `.migrated` marker **and** the on-disk slug-set in `docs/learn/` does **not** match the legacy slug-set (par·ity detection — migration is already complete iff the canonical store has, for every legacy file, a matching slug).
+
+Otherwise: record `migration: no-op (already migrated)` and skip to Maintain Step 2 (base-wide dedup). A subsequent `/learn maintain` invocation is a clean no-op.
+
+## Procedure
+
+```
+1. For each file under docs/learnings/<type>/*.md (type ∈ decision/gotcha/pattern/workflow):
+   1.1 Read the legacy entry (frontmatter + body).
+   1.2 Derive the canonical slug:
+       - Slug = kebab-case(normalize(legacy filename minus extension))
+       - The introduction of a date in the filename is preserved as a date suffix:
+         2026-07-04-critical-risk-tier-security-payments.md  ->  critical-risk-tier-security-payments-2026-07-04
+         daily-counter-artifact-naming-2026-07-02.md         ->  daily-counter-artifact-naming-2026-07-02
+       - Verify global uniqueness across docs/learn/; on collision, append a qualifier
+         (e.g., -a / -b) and record the rename in the log.
+   1.3 Normalize the frontmatter per [entry-schema.md](entry-schema.md):
+       - Newer-layout (slug/type/domain/priority/applicability.{current_project,general}/tags/confidence):
+         ALREADY canonical — preserve, add migrated-from.
+       - Older-layout (title/category/severity/domain/tags/source: commit <sha>):
+         Convert:
+         * type        = category
+         * slug        = <derived above>
+         * priority    = important if severity==important else normal
+         * applicability.current_project = inferred from severity (important->9, recommended->6, informational->3)
+         * applicability.general        = inferred from severity (important->7, recommended->5, informational->4)
+         * confidence   = medium
+         * source       = { type: commit, reference: <sha>, extracted_at: <legacy created_at or date> }
+         * The legacy `title` becomes the body `# <Title>` heading.
+         * Mark inferred numerics with a comment/note: `# inferred from legacy severity:important` so
+           the inference is explicit, not silent.
+   1.4 Rewrite cross-references (the entry's body + its related links):
+       - Any `../learnings/...` or `docs/learnings/...` link -> canonical `docs/learn/...` path
+       - Any legacy filename link -> canonical slug-relative link
+       - Preserve the link target's anchor text (do not silently change the prose)
+   1.5 Add lineage: set migrated-from: docs/learnings/<type>/<original-filename>.md
+       (so a future "where did this come from?" query resolves to the legacy path).
+   1.6 Write the canonical entry to docs/learn/<type>/<slug>.md (create <type>/ subdir as needed).
+2. Write the .migrated marker at docs/learn/.migrated containing:
+   migrated-at: <ISO-8601>
+   migrated-entries: <N>
+   legacy-path: docs/learnings/
+3. After all entries are written, build docs/learn/index.md from the canonical entries
+   (per [index-format.md](index-format.md) — Index phase's format; Maintain's rebuild step
+   runs the same format). The legacy docs/learnings/INDEX.md is NOT carried over — the new
+   index is derived from the canonical entry files (single source of truth).
+4. Do NOT delete docs/learnings/ (the legacy store stays; superseded, read-only).
+   Record migration: <N> entries migrated in the maintain log.
+```
+
+## Lineage Preservation (authoritative)
+
+Every migrated entry carries:
+
+- `migrated-from: docs/learnings/<type>/<original-filename>.md` — the old path, so a reader tracking an old `docs/learnings/...` reference in a commit, a doc, or another entry's `related` link can resolve it to the canonical file.
+- The **rewritten cross-references** — any `docs/learnings/...` link in the body becomes `docs/learn/...`, but the link's old form is not erased from the project's history: it is in git, and the `migrated-from` field is the in-file breadcrumb.
+
+This is the deliberate avoid-the-gotcha move: the [path-convention-split](../../../docs/learn/gotcha/2026-08-07-path-convention-split-silently-noops.md) trap is that a convention change silently no-ops. The migration prevents the no-op by (a) recording the old path on every entry, (b) rewriting links so readers land on the new path, and (c) keeping the legacy store on disk so nothing is destroyed mid-migration. The old path knowledge and the new path knowledge **both** live in the canonical entry.
+
+## Slug Derivation Rules (authoritative)
+
+| Legacy filename pattern | Canonical slug | Notes |
+| ----------------------- | -------------- | ----- |
+| `<date>-<descriptive>.md` (date-prefixed) | `<descriptive>-<date>` | Date moved to suffix; the descriptive part stays. |
+| `<descriptive>-<date>.md` (date-suffixed) | `<descriptive>-<date>` | Already in the canonical form; preserve. |
+| `<descriptive>.md` (no date) | `<descriptive>` | Date found from the entry's `created_at`/`timestamp`; if present, optionally append as suffix for chronology. |
+| `<descriptive>.md` with non-kebab chars | kebab-case(normalize) | Spaces/underscores → hyphens; collapse repeats; trim. |
+| Collision (two legacy files normalize to the same slug) | `<slug>-a`, `<slug>-b` | Track the rename in the log; flag the duplicate for dedup in Maintain Step 2 (the collision likely indicates analogs). |
+
+## Self-Gate Mechanics
+
+The `.migrated` marker is the fast-path check. The slug-set-parity check is the robust path (covers the case where the marker was deleted but the entries migrated). Maintain runs both:
+
+```
+if docs/learn/.migrated exists OR slug-set(docs/learn/) == slug-set(docs/learnings/):
+    migration: no-op (already migrated)
+else:
+    run the migration procedure
+```
+
+Slug-set parity is computed by listing the canonical files' slugs and the legacy files' derived slugs and comparing as sets; full equality = already migrated.
+
+## Legacy Store Handling
+
+- **Never deleted by the migration.** `docs/learnings/` stays on disk; its files are untouched by the migration's writes (migration only writes to `docs/learn/`). The legacy store becomes read-only in practice (no skill writes to it after migration).
+- **Removal is a separate, explicit prune.** If the user wants to delete `docs/learnings/`, it is a prune operation in Maintain Step 4 (destructive, confirm each) — never part of the migration procedure itself. The recommended default is **keep** (knowledge is rarely deleted; the superseded store is a fallback if a `migrated-from` link needs the original).
+- **The legacy `INDEX.md` is not migrated.** The new `docs/learn/index.md` is built from the canonical entries per [index-format.md](index-format.md). The legacy markdown-table `INDEX.md` is a different format; carrying it over would re-introduce the format-mismatch the canonical hybrid format resolves.
+
+## Smart Pause Triggers
+
+The migration rewrite is destructive (it rewrites 28 entry paths + every cross-reference). It pauses in Smart mode and **always surfaces in Autopilot** (per [interaction-mode-propagation.md](interaction-mode-propagation.md) — destructive never silent):
+
+- The migration will run for the first time (rewrite 28 entries + cross-refs) — confirm before starting.
+- A slug collision was detected during derivation (decide the qualifier; likely an analog for Maintain Step 2).
+- An inferred numeric score from a legacy `severity` value is being recorded (the user may want to override the inference).
+
+## Validation (Maintain Step 1 re-checks)
+
+- Every legacy file has a corresponding canonical file at `docs/learn/<type>/<slug>.md` with:
+  - canonical frontmatter (per [entry-schema.md](entry-schema.md))
+  - `migrated-from` set
+  - cross-references rewritten to `docs/learn/...`
+- The `.migrated` marker exists with `migrated-at` and `migrated-entries: <N>` matching the count.
+- `docs/learn/index.md` was built from the canonical entries (not the legacy `INDEX.md`).
+- `docs/learnings/` is untouched by the migration writes.
+
+## Failure-Condition Reference
+
+| Trigger                                                  | Outcome per this reference                              |
+| -------------------------------------------------------- | ------------------------------------------------------- |
+| `docs/learnings/` exists but `docs/learn/` cannot be created (perms) | Category 4 recovery per [error-handling.md](error-handling.md); ask the user to fix perms |
+| A legacy entry's body has an unresolvable cross-ref (target not in the legacy store, not a slug) | Keep the link's prose; log it; the user fixes the target later |
+| Slug-set parity is partial (half-migrated state)          | Run the migration for the missing files only; do not rewrite the already-migrated ones (the idempotency invariant) |
+| A collision requires a `-a`/`-b` qualifier                 | Apply the qualifier, log the rename, flag the analog for Maintain Step 2 (dedup) |
+
+## Notes
+
+- This reference is the single source of truth for the migration procedure. Maintain invokes it; the modules and the orchestrator never re-derive the slug rules or the frontmatter normalization inline.
+- The migration is **decisions-not-logs** in action: it converts a stale `INDEX.md`-based legacy store into a canonical, schema-conformant knowledge base with lineage — not a session dump. The migration's output is durable knowledge, reorganized and normalized, never a transient record.
+- The `.migrated` marker is a soundness check, not a load-bearing file: deleting it triggers slug-set-parity verification on the next Maintain run, and the migration is a no-op if parity holds. The marker is the fast path, not the gate.
+- The legacy store's `severity` field maps to the canonical `applicability` numeric scores **only** because the canonical enum is derived from those scores ([index-format.md](index-format.md)). The migration does the inference once; the enum derivation happens at index time exactly as it does for new entries.

package/skills/learn/references/templates/artifacts/captured-entry.md

@@ -0,0 +1,172 @@
+---
+title: Captured Entry Artifact
+description: Template for the Captured Entry Artifact produced by the Capture phase. Carries the drafted entry (frontmatter + per-type body per entry-schema), the proposed slug, the learn-id umbrella, the allocate capture-id, the source-candidate trace, and the inferred-flag; consumed by Refine for validation + dedup.
+type: template
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Captured Entry Artifact
+
+The product of the **Capture** phase is a drafted entry — the per-type frontmatter and body per the authoritative [entry-schema.md](../../entry-schema.md) (which Capture looks up, never re-encodes) — plus the proposed `slug`, the allocated `learn-id` umbrella, and the `source-candidate` trace. Refine consumes it for validation + duplicate/analog check. Capture drafts; it does not validate uniqueness or write the file.
+
+## Schema
+
+```yaml
+capture-id: YYYY-MM-DD-NNN-capture
+learn-id: YYYY-MM-DD-NNN                 # umbrella id, allocated here, carried through Capture→Refine→Index
+input-shape: explicit | candidate
+interactionMode: detailed | smart | autopilot
+status: complete
+timestamp: ISO-8601 timestamp
+
+target-type: decision | pattern | gotcha | workflow   # the entry's type; matches the prepared body section template
+slug: "<proposed-kebab-case-slug>"        # global, descriptive; Refine uniqueness-checks; Index upserts
+
+frontmatter:                              # authored per entry-schema.md; Capture drafts, Refine validates
+  type: <same as target-type>
+  slug: <same as above>
+  domain: <primary-domain>
+  priority: important | normal | null
+  applicability: { current_project: <0-10>, general: <0-10> }
+  tags: [tag-1, ...]
+  created_at: ISO-8601
+  updated_at: ISO-8601
+  source: { type: commit | candidate | user, reference: <sha | report-id#finding-id | text>, extracted_at: ISO-8601 }
+  confidence: high | medium | low | null
+  # Lineage fields intentionally absent at capture (set by Maintain/Index on merge/migrate).
+
+body: |                                   # the per-type section template per entry-schema.md
+  # <Title in Title Case>
+
+  ## Problem
+  <drafted from the text/candidate>
+
+  ## Solution / Pattern / Trap / Convention (per type)
+  <drafted content>
+
+  ## ...remaining sections for the type... (Decision Rationale / When to Apply / Solution-Prevention / Why / Application / Example / Related Learnings / Source)
+
+source-candidate: | null                  # the picked Work/Review candidate (type, domain, source {finding-id}, summary),
+                                           # or null for explicit input; carried for source traceability
+inferred: true | false                     # true when drafted from a short description or candidate (a pause trigger);
+                                           # false when grounded in a concrete ref/file the user provided
+```
+
+Also save the Captured Entry Artifact to `docs/plans/.learn/.capture/<capture-id>.md`.
+
+## Validation Rules
+
+- **capture-id:** Required. Format `YYYY-MM-DD-NNN-capture` per [id-generation.md](../../id-generation.md).
+- **learn-id:** Required. Allocated by Capture (the umbrella); reuses the capture counter's NNN.
+- **input-shape:** Required. `explicit` or `candidate` (a `maintain` shape must not reach Capture — routing error per [error-handling.md](../../error-handling.md)).
+- **interactionMode:** Required, propagated from the Learn Input Artifact.
+- **status:** Required. `complete`.
+- **target-type:** Required. One of `decision` / `pattern` / `gotcha` / `workflow`.
+- **slug:** Required. Proposed kebab-case; globally unique namespace; descriptive. Refine uniqueness-checks.
+- **frontmatter:** Required. Authored per [entry-schema.md](../../entry-schema.md). Required fields: `type`, `slug`, `domain`, `applicability.current_project`, `applicability.general`, `tags` (2–6), `created_at`, `updated_at`, `source`. Optional: `priority` (default `normal`), `confidence` (default `medium`). Lineage fields (`migrated-from`/`superseded-by`/`related`/`status`) absent at capture.
+- **body:** Required. The per-type section template per [entry-schema.md](../../entry-schema.md) (e.g., a `decision` body has Problem / Solution / Decision Rationale / Application / Related Learnings). Refine validates the sections are present.
+- **source-candidate:** Required (= the picked candidate) when `input-shape: candidate`; `null` when `input-shape: explicit`. Carried so Refine/Index can set the entry's `source` field pointing back at the Work/Review report + finding id.
+- **inferred:** Required. `true` is a Capture Smart pause trigger (the draft was inferred from a short description or candidate — confirm intent).
+
+## Example (explicit decision, grounded in a commit ref)
+
+```yaml
+capture-id: 2026-08-08-001-capture
+learn-id: 2026-08-08-001
+input-shape: explicit
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T14:30:00Z
+target-type: decision
+slug: use-pnpm-when-both-lockfiles-exist
+frontmatter:
+  type: decision
+  slug: use-pnpm-when-both-lockfiles-exist
+  domain: tooling
+  priority: normal
+  applicability: { current_project: 8, general: 6 }
+  tags: [package-management, npm, pnpm, lockfiles]
+  created_at: 2026-08-08T14:30:00Z
+  updated_at: 2026-08-08T14:30:00Z
+  source: { type: commit, reference: "1ee04e2", extracted_at: 2026-08-08T14:30:00Z }
+  confidence: high
+body: |
+  # Use pnpm When Both Lockfiles Exist
+
+  ## Problem
+  When a repo has both package-lock.json and pnpm-lock.yaml, invocations must pick one; the wrong choice causes ghost deps.
+
+  ## Solution
+  Prefer the lockfile matching package.json's packageManager field; otherwise ask the user.
+
+  ## Decision Rationale
+  Reuses the Work skill's Prepare-phase npm-vs-pnpm resolution; one consistent packageManager recorded across phases.
+
+  ## Application
+  Work skill Prepare Step 1; Review skill Prepare Step 3 detects the runner + packageManager for the test-context.
+
+  ## Related Learnings
+  (none yet)
+source-candidate: null
+inferred: false
+```
+
+## Example (candidate gotcha, inferred from a Work Report)
+
+```yaml
+capture-id: 2026-08-08-002-capture
+learn-id: 2026-08-08-002
+input-shape: candidate
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T14:35:00Z
+target-type: gotcha
+slug: ttl-must-propagate-to-redis-set
+frontmatter:
+  type: gotcha
+  slug: ttl-must-propagate-to-redis-set
+  domain: data-storage
+  priority: important
+  applicability: { current_project: 8, general: 7 }
+  tags: [redis, ttl, session-store, caching]
+  created_at: 2026-08-08T14:35:00Z
+  updated_at: 2026-08-08T14:35:00Z
+  source: { type: candidate, reference: "2026-07-10-001-review#F02", extracted_at: 2026-08-08T14:35:00Z }
+  confidence: medium
+body: |
+  # Redis TTL Must Propagate to the SET Command
+
+  ## Problem
+  The session-store TTL test failed after the green gate.
+
+  ## Trap
+  Setting the TTL on the key separately rather than on SET ... EX silently loses the TTL on overwrite.
+
+  ## Solution
+  Pass the TTL on SET with EX; do not issue a separate EXPIRE.
+
+  ## Prevention
+  Assert the TTL is observable on the next get within the AC test; a separate EXPIRE path fails the test.
+
+  ## Related Learnings
+  (none yet)
+
+  ## Source
+  2026-07-10-001-review#F02 (redis TTL test blocked at Green gate)
+source-candidate:
+  title: "Redis TTL must be propagated to the SET command, not just the key"
+  domain: data-storage
+  source: { type: candidate, reference: "2026-07-10-001-review#F02" }
+  summary: "TTL test failed because SET ... EX must carry the TTL."
+  type: gotcha
+inferred: true
+```
+
+## Notes
+
+- Capture is the **allocating phase** for the `learn-id` umbrella (see [id-generation.md](../../id-generation.md)); Refine and Index inherit it unchanged.
+- The `slug` is **proposed** here, not validated — Capture never silently collides; Refine's dedup check resolves any exact/analog match per [dedup-rules.md](../../dedup-rules.md).
+- `inferred: true` (a short description or candidate sourced the draft) is the Capture Smart pause trigger; the user confirms the draft matches intent before Refine runs.
+- The frontmatter's `source.reference` for a candidate points at the Work/Review report + finding id (`<review-id>#<finding-id>`) — the traceability link from the durable entry back to where it was first surfaced.
+- Lineage fields are intentionally **absent** at capture — they are set only by Maintain (migration, base-wide merge) or Index (a Refine-time merge), per [entry-schema.md](../../entry-schema.md).