arreio 1.0.0-dev.1

package/skills/learn/references/templates/artifacts/index-update.md

@@ -0,0 +1,135 @@
+---
+title: Index Update Artifact
+description: Template for the Index Update Artifact produced by the Index phase. Carries the entry-path, the resolved slug, the derived index-applicability enum, the index-action (created/updated/merged), the index-coherence flag, and any merge de-index performed. The authoring run's final artifact; the entry is now durable at docs/learn/<type>/<slug>.md and indexed in docs/learn/index.md.
+type: template
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Index Update Artifact
+
+The product of the **Index** phase is the authoring run's final artifact. Index **writes** the entry file at `docs/learn/<type>/<slug>.md` (upsert on `slug`), derives the index-record `applicability` enum from the per-entry numeric scores per [index-format.md](../../index-format.md), and **upserts** `docs/learn/index.md` (YAML `entries:` block record plus By Category / By Domain markdown rows). On a merge resolution, Index de-indexes the analog (removes its index record), writes `superseded-by` into the analog's file, and adds the analog's `slug` to the canonical's `related` — keeping the analog's file (lineage preserved, never deleted). Index is the only authoring-phase writer of the entry file and the index.
+
+## Schema
+
+```yaml
+index-id: YYYY-MM-DD-NNN-index
+refine-id: YYYY-MM-DD-NNN-refine
+capture-id: YYYY-MM-DD-NNN-capture
+learn-id: YYYY-MM-DD-NNN
+input-shape: explicit | candidate
+interactionMode: detailed | smart | autopilot
+status: complete
+timestamp: ISO-8601 timestamp
+
+entry-path: "docs/learn/<type>/<slug>.md"      # where the entry file was written
+slug: "<resolved-slug>"                       # the upsert key (matches the entry's frontmatter slug)
+type: decision | pattern | gotcha | workflow  # the entry's type
+
+index-applicability: DIRECT | RECOMMENDED | CONTEXTUAL | HISTORICAL | INFORMATIONAL
+                                              # DERIVED per index-format.md from the frontmatter's numeric scores
+
+index-action: created | updated | merged      # what Index did
+                                              # created: new slug written
+                                              # updated: existing slug overwritten (update-existing resolution)
+                                              # merged: merge-into-canonical — analog de-indexed + canonical updated
+
+merge:                                        # present ONLY when index-action == merged
+  analog-slug: <the analog being de-indexed>
+  analog-file: "docs/learn/<type>/<analog-slug>.md"
+  analog-deindexed: true                       # its index record + rows removed; file KEPT
+  analog-superseded-note-written: true         # superseded-by + status:obsolete written into the analog's frontmatter
+  canonical-related-updated: true             # analog-slug added to canonical's related list
+
+index-coherent: true                          # the YAML entries: length == on-disk entry-file count;
+                                              # per-type (N) counts consistent; no duplicate rows; the orchestrator's gate #5
+
+source-candidate: <carried through> | null
+
+entry-written: true                           # the entry file was written (false only on a failed-write recovery; would be status: failed)
+index-updated: true                           # docs/learn/index.md was upserted
+```
+
+Also save the Index Update Artifact to `docs/plans/.learn/.index/<index-id>.md`.
+
+## Validation Rules
+
+- **index-id:** Required. Format `YYYY-MM-DD-NNN-index` per [id-generation.md](../../id-generation.md).
+- **refine-id, capture-id, learn-id, input-shape:** Required, inherited (cross-phase consistency).
+- **interactionMode:** Required, identical across the authoring chain.
+- **status:** Required. `complete`.
+- **entry-path:** Required. Repo-relative, of the form `docs/learn/<type>/<slug>.md`; the directory `docs/learn/<type>/` created if missing.
+- **slug:** Required. The resolved slug (matches the entry's frontmatter).
+- **type:** Required. One of the four.
+- **index-applicability:** Required. The **derived** enum, per [index-format.md](../../index-format.md) (not re-encoded inline here; the artifact records the result of applying the derivation rule to the frontmatter's numeric scores).
+- **index-action:** Required. `created` (new slug), `updated` (existing slug overwritten via `update-existing`), or `merged` (`merge-into-canonical` executed).
+- **merge:** Required when `index-action: merged`; absent otherwise. On a merge:
+  - `analog-deindexed: true` — the analog's record was removed from the YAML block + By Category / By Domain tables.
+  - `analog-superseded-note-written: true` — `superseded-by: <canonical-slug>` and `status: obsolete` written into the analog file's frontmatter.
+  - `canonical-related-updated: true` — the analog's `slug` added to the canonical's `related` list.
+  - The analog **file is never deleted** (lineage preservation per [dedup-rules.md](../../dedup-rules.md)).
+- **index-coherent:** Required. `true` — the post-upsert invariants hold (YAML length == on-disk count; per-type counts consistent; no duplicate rows). If `false`, Index reconciled in-place (non-destructive) and flagged it; the orchestrator's quality gate #5 requires `true` to finalize the run.
+- **entry-written, index-updated:** Required. `true` on success; `status: failed` would cover a write failure.
+
+## Example (created — new decision entry)
+
+```yaml
+index-id: 2026-08-08-001-index
+refine-id: 2026-08-08-001-refine
+capture-id: 2026-08-08-001-capture
+learn-id: 2026-08-08-001
+input-shape: explicit
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T14:34:00Z
+entry-path: docs/learn/decision/use-pnpm-when-both-lockfiles-exist.md
+slug: use-pnpm-when-both-lockfiles-exist
+type: decision
+index-applicability: DIRECT                  # current_project=8, general=6 → RECOMMENDED; refine higher if any
+index-action: created
+index-coherent: true
+source-candidate: null
+entry-written: true
+index-updated: true
+```
+
+## Example (merged — analog de-indexed, canonical updated, lineage preserved)
+
+```yaml
+index-id: 2026-08-08-002-index
+refine-id: 2026-08-08-002-refine
+capture-id: 2026-08-08-002-capture
+learn-id: 2026-08-08-002
+input-shape: candidate
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T14:42:00Z
+entry-path: docs/learn/gotcha/ttl-must-propagate-to-redis-set.md
+slug: ttl-must-propagate-to-redis-set
+type: gotcha
+index-applicability: DIRECT                  # current_project=8, general=7 → DIRECT
+index-action: merged
+merge:
+  analog-slug: redis-ttl-set-vs-expire
+  analog-file: docs/learn/gotcha/redis-ttl-set-vs-expire.md
+  analog-deindexed: true
+  analog-superseded-note-written: true
+  canonical-related-updated: true
+index-coherent: true
+source-candidate:
+  title: "Redis TTL must be propagated to the SET command"
+  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
+entry-written: true
+index-updated: true
+```
+
+## Notes
+
+- Index is the **sole authoring-phase writer** of the entry file and the index; the upsert on `slug` is idempotent (a re-author overwrites, never duplicates).
+- The `index-applicability` enum is **derived** from the frontmatter's numeric scores per [index-format.md](../../index-format.md); the artifact records the **result** of that derivation — it does not re-encode the derivation rule (no second formula).
+- A `merged` action de-indexes the analog **without deleting its file** — the analog carries `superseded-by` + `status: obsolete`, and the canonical's `related` list links the analog's `slug`. The reader can walk either direction. This honors the [dedup-rules.md](../../dedup-rules.md) lineage-preservation rule (the `path-convention-split` gotcha is the model: a merged entry carries both the old and new knowledge, never just the new).
+- `index-coherent: true` is the orchestrator's quality gate #5; the Index phase is responsible for leaving the index coherent (the YAML block, the per-type `(N)` counts, and the By Domain bullets are all in lockstep with the on-disk file tree).
+- This artifact is the authoring run's **final** output. The Orchestrator marks the run complete; the durable knowledge entry now lives at `entry-path` and is discoverable via `docs/learn/index.md` (the source-of-truth index Plan/Work/Review search).

package/skills/learn/references/templates/artifacts/learn-input.md

@@ -0,0 +1,100 @@
+---
+title: Learn Input Artifact
+description: Template for the Learn Input Artifact produced by the Orchestrator. Carries the input shape (explicit type+text, candidate ref, or maintain flag) and interactionMode; consumed by Capture (authoring shapes) or routed directly to Maintain (maintain shape).
+type: template
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Learn Input Artifact
+
+The Orchestrator produces a Learn Input Artifact as the entry point to the Learn workflow. It carries the input shape (one of explicit `<type> <text>`, a candidate ref, or a `maintain` flag) and the user-selected `interactionMode`. The Orchestrator routes an authoring shape to Capture; a `maintain` shape bypasses Capture/Refine/Index and routes directly to Maintain.
+
+## Schema
+
+```yaml
+type: learn-input
+timestamp: ISO-8601 timestamp (e.g., 2026-08-08T14:30:00Z)
+source: user | saved-prompt | document | combination
+status: complete
+interactionMode: detailed | smart | autopilot
+shape: explicit | candidate | maintain   # REQUIRED. Determines the route.
+
+# Input cargo — exactly one shape's fields:
+explicit:
+  type: decision | pattern | gotcha | workflow   # REQUIRED when shape == explicit
+  text: "<prose | file ref | commit ref | short description>"   # REQUIRED when shape == explicit
+candidate:
+  ref: "work-review-id | review-report-id"        # REQUIRED when shape == candidate
+  # e.g. "2026-07-10-001-review" (Work) or "2026-08-08-001-report" (Review)
+maintain:
+  run: true                                       # REQUIRED when shape == maintain
+
+# Optional context carried (explicit/candidate):
+goals: [ ... ]
+constraints: [ ... ]
+references: [ ... ]
+```
+
+## Validation Rules
+
+- **type:** Required. Must be `learn-input`.
+- **timestamp:** Required. ISO-8601.
+- **source:** Required. One of `user`, `saved-prompt`, `document`, `combination`.
+- **status:** Required. `complete` (the Orchestrator marks it complete once it has the input and the interaction mode).
+- **interactionMode:** Required. One of `detailed`, `smart`, `autopilot`. (If missing, default to `smart`; see [error-handling.md](../../error-handling.md) Category 5.)
+- **shape:** Required. One of `explicit`, `candidate`, `maintain`.
+- **Exactly one shape's cargo is present** (the others null/absent):
+  - `explicit` requires `explicit.type` ∈ the four types **and** non-empty `explicit.text`.
+  - `candidate` requires a non-empty `candidate.ref` resolving to a Work `review-id` or Review `report-id`.
+  - `maintain` requires `maintain.run: true`.
+- **Routing:** the Orchestrator routes `shape: maintain` directly to the Maintain phase (Phase 4); `shape: explicit` and `shape: candidate` route to Capture (Phase 1). A routing mismatch (e.g., a `maintain` shape reaching Capture) is a Category 2 error ([error-handling.md](../../error-handling.md)).
+
+## Example (explicit author)
+
+```yaml
+type: learn-input
+timestamp: 2026-08-08T09:00:00Z
+source: user
+status: complete
+interactionMode: smart
+shape: explicit
+explicit:
+  type: decision
+  text: "Use pnpm over npm when both lockfiles exist; prefer the packageManager field lock for invocations"
+goals: null
+constraints: null
+references: null
+```
+
+## Example (candidate curation)
+
+```yaml
+type: learn-input
+timestamp: 2026-08-08T09:05:00Z
+source: user
+status: complete
+interactionMode: detailed
+shape: candidate
+candidate:
+  ref: "2026-07-10-001-review"      # a Work review-id with a learnings-to-capture list
+```
+
+## Example (maintain)
+
+```yaml
+type: learn-input
+timestamp: 2026-08-08T09:10:00Z
+source: user
+status: complete
+interactionMode: smart
+shape: maintain
+maintain:
+  run: true
+```
+
+## Notes
+
+- The Orchestrator's Pre-Flight Check ensures `docs/learn/`, `docs/plans/.learn/.{capture,refine,index,maintain}/` exist, and seeds `docs/learn/index.md` if missing (self-healing via `mkdir -p`), before routing the artifact.
+- `interactionMode` flows from this artifact into every downstream artifact (Capture → Refine → Index for authoring; straight to Maintain otherwise); the orchestrator quality gate #2 cross-checks it is identical across the authoring chain (Maintain carries it standalone).
+- The shape **determines the route**, not just the allocation: a `maintain` shape never reaches Capture, Refine, or Index. The phase ids reflect this — `maintain-id` is standalone (no `learn-id` umbrella) per [id-generation.md](../../id-generation.md).

package/skills/learn/references/templates/artifacts/maintain-log.md

@@ -0,0 +1,142 @@
+---
+title: Maintain Log Artifact
+description: Template for the Maintain Log Artifact produced by the Maintain phase. Carries the one-time migration result (no-op or N entries migrated), the base-wide dedup merges performed, the refresh normalization/flag counts, the explicit prune decisions, the rebuilt index state, and the index-coherence flag. Maintain's only deliverable; the canonical knowledge base is reconciled.
+type: template
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Maintain Log Artifact
+
+The product of the **Maintain** phase is the Maintain Log — the Maintain run's only deliverable. It records the one-time **migration** result (a self-gating no-op when already migrated, or `<N> entries migrated`), the **base-wide dedup** merges performed, the **refresh** (frontmatter normalization + flagged-for-review entries), the explicit **prune** decisions (deletes and de-indexes, each confirmed), and the rebuilt **index** state. The canonical knowledge base at `docs/learn/` is reconciled; `docs/learn/index.md` is rebuilt from the on-disk file tree (the source of truth). Maintain allocates its own `maintain-id` — there is no `learn-id` umbrella (Maintain authors no new entry).
+
+## Schema
+
+```yaml
+maintain-id: YYYY-MM-DD-NNN-maintain       # standalone; no learn-id umbrella (Maintain authors no new entry)
+interactionMode: detailed | smart | autopilot
+status: complete
+timestamp: ISO-8601 timestamp
+
+migration:
+  ran: true | false                         # false when self-gated (no-op)
+  result: "no-op (already migrated)" | "<N> entries migrated"
+  marker-written: true | false             # the .migrated marker at docs/learn/.migrated
+  legacy-store-deleted: false               # ALWAYS false — migration never deletes docs/learnings/; removal is a separate prune
+
+merges:                                     # base-wide dedup performed (Step 2)
+  - analog-slug: <the analog folded>
+    canonical-slug: <the canonical entry>
+    analog-file: "docs/learn/<type>/<analog-slug>.md"
+    analog-kept: true                       # the analog file is KEPT (de-indexed, not deleted)
+    analog-superseded-note-written: true    # superseded-by + status:obsolete into the analog's frontmatter
+    canonical-related-updated: true         # analog-slug added to the canonical's related list
+  []
+
+refresh:
+  normalized-count: <N>                     # entries with non-destructive fixes applied (priority default, casing, updated_at)
+  flagged-for-review-count: <N>             # entries with destructive changes needed (field-rewrite, missing sections) — NOT auto-applied
+  flagged-entries: [ "<slug>", ... ]
+
+prune:                                      # each prune was explicitly confirmed (destructive never silent, even in Autopilot)
+  - slug: <slug>
+    action: deleted | de-indexed            # deleted: file removed; de-indexed: file kept, status:obsolete, index record removed (recommended default)
+    reason: "<user-confirmed rationale>"
+  []
+
+rebuild:
+  ran: true
+  entries-indexed: <N>                      # the count of on-disk non-de-indexed entries in the rebuilt index
+  coherence-fixes-applied: <N>              # any (YAML length vs file count) drift reconciled (should be 0 on a clean store)
+
+index-coherent: true                        # the rebuilt YAML entries: length == on-disk entry-file count;
+                                           # per-type (N) counts consistent; no duplicate rows; the orchestrator's gate #5
+
+summary:                                    # a one-line human-readable summary
+  "<N> entries migrated; <M> merged; <R> normalized, <F> flagged; <P> pruned; <I> indexed"
+```
+
+Also save the Maintain Log Artifact to `docs/plans/.learn/.maintain/<maintain-id>.md`.
+
+## Validation Rules
+
+- **maintain-id:** Required. Format `YYYY-MM-DD-NNN-maintain` per [id-generation.md](../../id-generation.md). A maintain artifact **never** carries a `learn-id` (a `learn-id` here is treated as an orphan and logged per [error-handling.md](../../error-handling.md) Cross-Phase Consistency Checks).
+- **interactionMode:** Required, propagated from the Learn Input Artifact.
+- **status:** Required. `complete` (a partial maintain is `failed`; the user re-runs `/learn maintain` — runs are idempotent).
+- **migration:** Required. `ran: false` with `result: "no-op (already migrated)"` (self-gated; the fast path is the `.migrated` marker, the robust path is slug-set parity per [migration-bootstrap.md](../../migration-bootstrap.md)). When `ran: true`: `result: "<N> entries migrated"`, `marker-written: true`. `legacy-store-deleted` is **always false** — the migration never deletes `docs/learnings/` (its removal is a separate prune the user explicitly runs if desired).
+- **merges:** Required (may be `[]`). Each merge has `analog-slug`, `canonical-slug`, `analog-file`, `analog-kept: true`, `analog-superseded-note-written: true`, `canonical-related-updated: true`. **The analog file is never deleted** (lineage preserved per [dedup-rules.md](../../dedup-rules.md)).
+- **refresh:** Required. `normalized-count` (non-destructive fixes; counted), `flagged-for-review-count`, `flagged-entries` (the slug list needing destructive changes — these are **not** auto-applied; the user decides).
+- **prune:** Required (may be `[]`). Each prune has `slug`, `action` (`deleted` or `de-indexed`), and a `reason`. Each prune was **explicitly confirmed** by the user (destructive never silent, even in Autopilot). A deleted entry's file is gone; a de-indexed entry's file is kept with `status: obsolete`.
+- **rebuild:** Required. `ran: true`, `entries-indexed: <N>` (the count of non-de-indexed on-disk entries), `coherence-fixes-applied: <N>` (should be 0 on a clean store; the rebuild reconciles any prior drift).
+- **index-coherent:** Required. `true` — the orchestrator's quality gate #5; the rebuilt `docs/learn/index.md` YAML block length matches the on-disk entry-file count, per-type `(N)` counts are consistent, and no duplicate rows.
+- **summary:** Required. A one-line human-readable record of what Maintain did.
+
+## Example (first-run maintain after the legacy store exists — migration + a merge + a prune)
+
+```yaml
+maintain-id: 2026-08-08-001-maintain
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T16:00:00Z
+migration:
+  ran: true
+  result: "28 entries migrated"
+  marker-written: true
+  legacy-store-deleted: false
+merges:
+  - analog-slug: redis-ttl-set-vs-expire
+    canonical-slug: ttl-must-propagate-to-redis-set
+    analog-file: docs/learn/gotcha/redis-ttl-set-vs-expire.md
+    analog-kept: true
+    analog-superseded-note-written: true
+    canonical-related-updated: true
+refresh:
+  normalized-count: 14                       # the older-layout pattern/workflow entries normalized to the canonical schema
+  flagged-for-review-count: 2
+  flagged-entries: [ cross-phase-id-chaining-2026-07-04, capability-described-not-tool-named-2026-08-07 ]
+prune:
+  - slug: deprecated-skill-format-2026-06-01
+    action: de-indexed                       # the recommended default — file kept, status:obsolete, index record removed
+    reason: "Superseded by the canonical skill-format convention; user confirmed de-index."
+rebuild:
+  ran: true
+  entries-indexed: 27
+  coherence-fixes-applied: 0
+index-coherent: true
+summary: "28 entries migrated; 1 merged; 14 normalized, 2 flagged; 1 pruned; 27 indexed"
+```
+
+## Example (steady-state maintain — no migration, just a refresh + rebuild)
+
+```yaml
+maintain-id: 2026-08-25-003-maintain
+interactionMode: autopilot
+status: complete
+timestamp: 2026-08-25T10:00:00Z
+migration:
+  ran: false
+  result: "no-op (already migrated)"
+  marker-written: false
+  legacy-store-deleted: false
+merges: []
+refresh:
+  normalized-count: 0
+  flagged-for-review-count: 0
+  flagged-entries: []
+prune: []
+rebuild:
+  ran: true
+  entries-indexed: 31
+  coherence-fixes-applied: 0
+index-coherent: true
+summary: "0 entries migrated; 0 merged; 0 normalized, 0 flagged; 0 pruned; 31 indexed"
+```
+
+## Notes
+
+- Maintain is **on-demand** (`/learn maintain`); it authors no new entry, hence the standalone `maintain-id` (no `learn-id` umbrella).
+- The **migration is one-time and self-gating** — the `.migrated` marker is the fast path; slug-set parity is the robust path. A steady-state maintain records `migration.ran: false` with `result: "no-op (already migrated)"`.
+- **Destructive operations are never silent**, even in Autopilot (per [interaction-mode-propagation.md](../../interaction-mode-propagation.md)): the migration rewrite, each merge, and each prune surface for user confirmation. Non-destructive refresh and the rebuild auto-proceed.
+- **Lineage is preserved everywhere**: a merge keeps the analog's file with `superseded-by` + `status: obsolete`; the recommended prune action is `de-indexed` (keep the file, mark obsolete), not `deleted`. The legacy store is **never deleted by the migration** — removal is a separate, explicit prune the user runs.
+- **`index-coherent: true`** is the orchestrator's quality gate #5; Maintain is responsible for leaving the rebuilt index coherent (the file tree is the source of truth, the YAML block and the markdown tables are two projections in lockstep).
+- This artifact is Maintain's only **deliverable** — it describes what was reconciled, never a session transcript. The canonical knowledge base at `docs/learn/` is the durable source-of-truth outcome.

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

@@ -0,0 +1,168 @@
+---
+title: Refined Entry Artifact
+description: Template for the Refined Entry Artifact produced by the Refine phase. Carries the validated entry (frontmatter + body conforming to entry-schema), the resolved slug (may differ from Capture's proposal after a conflict), the dup-status (exact/analog/none) + the chosen resolution, and a lineage block when a merge occurred; consumed by Index.
+type: template
+version: 1.0
+timestamp: "2026-08-08"
+---
+
+# Refined Entry Artifact
+
+The product of the **Refine** phase is a validated, conflict-resolved entry: frontmatter and body conforming to the authoritative [entry-schema.md](../../entry-schema.md) (which Refine validates against, never re-encodes), the **resolved** `slug` (may differ from Capture's proposal after a duplicate/analog conflict), the `dup-status` + `resolution` chosen by the user, and a `lineage` block when a merge occurred. Index consumes it to write the entry file and upsert the index. Refine validates and reconciles; it does not write.
+
+## Schema
+
+```yaml
+refine-id: YYYY-MM-DD-NNN-refine
+capture-id: YYYY-MM-DD-NNN-capture
+learn-id: YYYY-MM-DD-NNN
+input-shape: explicit | candidate
+interactionMode: detailed | smart | autopilot
+status: complete
+timestamp: ISO-8601 timestamp
+
+type: decision | pattern | gotcha | workflow    # validated
+slug: "<resolved-kebab-case-slug>"             # validated; may differ from Capture's proposal (new-slug case)
+
+frontmatter:                                   # validated per entry-schema.md; Refine does not coerce silently
+  type: <same as type>
+  slug: <same as slug>
+  domain: <primary-domain>
+  priority: important | normal
+  applicability: { current_project: <0-10>, general: <0-10> }
+  tags: [tag-1, ..., tag-6]                     # 2-6 tags validated
+  created_at: ISO-8601                          # preserved from Capture
+  updated_at: ISO-8601                          # stamp of Refine's validation
+  source: { type, reference, extracted_at }
+  confidence: high | medium | low
+
+body: |                                         # per-type section template validated present (Refine does not auto-fill)
+  # <Title>
+
+  ## Problem
+  ...
+  ## ... remaining sections for the type ...
+
+dup-status: exact | analog | none               # the ref result of Refine Step 3 against existing entries
+matched-slug: <existing-slug> | null            # the entry Refine matched (exact or analog); null when none
+match-evidence: | null                          # the shared signals (slug match, or domain+tags+type+conclusion)
+resolution: update-existing | new-slug | merge-into-canonical | keep-separate | none
+                                               # chosen by the user per dedup-rules.md; none when dup-status==none
+
+lineage:                                        # set ONLY when resolution == merge-into-canonical
+  analog-slug: <the entry being merged-away>   # the entry Refine matched (matched-slug) when merging
+  canonical-slug: <slug>                        # the canonical slug; same as the entry's slug above
+  analog-kept: true                             # the analog file is KEPT (de-indexed, not deleted) per dedup-rules.md
+  rationale: "<why merge, in one line>"
+
+source-candidate: <carried from Capture> | null
+```
+
+Also save the Refined Entry Artifact to `docs/plans/.learn/.refine/<refine-id>.md`.
+
+## Validation Rules
+
+- **refine-id:** Required. Format `YYYY-MM-DD-NNN-refine` per [id-generation.md](../../id-generation.md).
+- **capture-id, learn-id, input-shape:** Required, inherited from Capture (cross-phase consistency).
+- **interactionMode:** Required, identical to the Capture artifact.
+- **status:** Required. `complete`.
+- **type:** Required. One of the four (re-confirmed by Refine Step 1).
+- **slug:** Required. The **resolved** slug; kebab-case; globally unique (Refine confirmed no exact collision unless `resolution: new-slug`/`update-existing`).
+- **frontmatter:** Required. Every required field validated per [entry-schema.md](../../entry-schema.md); `tags` length 2–6; numeric scores 0–10; `confidence`/`priority` in enums; `created_at` preserved, `updated_at` stamped.
+- **body:** Required. The per-type section template present in full (Refine flagged any missing section as a pause trigger; auto-fill is forbidden).
+- **dup-status:** Required. `exact`, `analogs`, or `none`.
+- **matched-slug:** Required (= the existing slug) when `dup-status` is `exact` or `analog`; `null` when `none`.
+- **match-evidence:** Required when `dup-status` is `exact` or `analog`; the shared signals (slug match, or domain+tags+type+conclusion overlap) so the user can confirm the match is real.
+- **resolution:** Required. Must be one of `update-existing`, `new-slug`, `merge-into-canonical`, `keep-separate`, `none`; `none` only when `dup-status: none`.
+- **lineage:** Required when `resolution: merge-into-canonical` (`analog-slug`, `canonical-slug`, `analogs-kept: true`, `rationale`); absent otherwise. `analogs-kept: true` is mandatory — Refine may not authorize deletion (the analog is de-indexed, not deleted, per [dedup-rules.md](../../dedup-rules.md)).
+- **source-candidate:** Carried through from Capture (setter of the entry's `source.reference` traceability).
+
+## Example (explicit decision, no duplicate)
+
+```yaml
+refine-id: 2026-08-08-001-refine
+capture-id: 2026-08-08-001-capture
+learn-id: 2026-08-08-001
+input-shape: explicit
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T14:32:00Z
+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:32:00Z
+  source: { type: commit, reference: "1ee04e2", extracted_at: 2026-08-08T14:30:00Z }
+  confidence: high
+body: |
+  # Use pnpm When Both Lockfiles Exist
+  ## Problem
+  ...
+  ## Solution
+  ...
+dup-status: none
+matched-slug: null
+match-evidence: null
+resolution: none
+source-candidate: null
+```
+
+## Example (analog → merge-into-canonical, lineage preserved)
+
+```yaml
+refine-id: 2026-08-08-002-refine
+capture-id: 2026-08-08-002-capture
+learn-id: 2026-08-08-002
+input-shape: candidate
+interactionMode: smart
+status: complete
+timestamp: 2026-08-08T14:40:00Z
+type: gotcha
+slug: ttl-must-propagate-to-redis-set     # the canonical stays (older entry here)
+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-07-10T00:00:00Z         # preserved (older entry's created_at retained on merge)
+  updated_at: 2026-08-08T14:40: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
+  ...
+  ## Trap / Solution / Prevention / Source ...
+dup-status: analog
+matched-slug: redis-ttl-set-vs-expire       # the older lower-priority analog
+match-evidence: |
+  same domain (data-storage) + 3 shared tags (redis, ttl, session-store) + same type (gotcha)
+  + same conclusion (SET ... EX must carry the TTL); different slug.
+resolution: merge-into-canonical
+lineage:
+  analog-slug: redis-ttl-set-vs-expire
+  canonical-slug: ttl-must-propagate-to-redis-set
+  analog-kept: true
+  rationale: "Same gotcha, same prevention; redis-ttl-set-vs-expire folds into the canonical with lineage."
+source-candidate:
+  title: "Redis TTL must be propagated to the SET command"
+  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
+```
+
+## Notes
+
+- Refine is the **validator + conflict resolver**; it does not write the entry file (Index does) and does not coerce frontmatter silently (a wrong field surfaces as a pause trigger, never a silent fix).
+- The `slug` here is the **resolved** slug — it may differ from Capture's proposal only when a conflict chose `new-slug` (Capture proposed → existing collision → user renamed) or `update-existing` (Capture proposed → existing match → keep existing slug).
+- The `lineage` block is the **single** place the merge's bookkeeping lives at Refine-time; Index reads it to perform the de-index + `superseded-by` write + `related` link on the canonical. `analogs-kept: true` is mandatory — Refine may not authorize deletion (de-index only, per [dedup-rules.md](../../dedup-rules.md)).
+- `created_at` on a merge is the **older** entry's timestamp (the canonical's, often the existing entry's); `updated_at` stamps the merge. This preserves chronology across the absorption.