fix(aidd-context): make 10-learn's recommendation step consistent

plugins/aidd-context/CATALOG.md

@@ -180,6 +180,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `actions` | [05-sync.md](skills/10-learn/actions/05-sync.md) | - |
 | `assets` | [adr-template.md](skills/10-learn/assets/adr-template.md) | - |
 | `assets` | [learning-packet.md](skills/10-learn/assets/learning-packet.md) | - |
+| `assets` | [recommendation-table.md](skills/10-learn/assets/recommendation-table.md) | - |
+| `assets` | [write-report.md](skills/10-learn/assets/write-report.md) | - |
 | `references` | [assessment.md](skills/10-learn/references/assessment.md) | - |
 | `references` | [destinations.md](skills/10-learn/references/destinations.md) | - |
 | `references` | [gather-protocol.md](skills/10-learn/references/gather-protocol.md) | - |

plugins/aidd-context/skills/10-learn/SKILL.md

@@ -8,8 +8,12 @@ argument-hint: conversation | file | diff | review
 ```mermaid
 flowchart LR
   source --> gather --> assess --> write
+  source -->|"missing, empty, or ambiguous"| sourceStop([stop])
+  gather -->|"no candidates"| gatherEnd([end])
+  assess -->|"all covered"| assessEnd([end])
   write -->|"memory or ADR"| sync
   write -->|"rule or skill"| handoff([handoff])
+  sync -->|"failure"| syncStop([stop])
 ```
 
 ## Actions
@@ -20,12 +24,12 @@ Run the flow above. Read only the next action file.
 | ------ | ---- |
 | source | identify and challenge the origin |
 | gather | read the origin and extract candidates |
-| assess | score, reconcile, and confirm |
+| assess | score, reconcile, show, and confirm |
 | write | write or hand off approved lessons |
 | sync | refresh memory references |
 
 ## Transversal rules
 
 - Write only the user-approved plan.
 - Preserve user edits and touch affected files only.
-- Write project files only, never personal or global memory, never scaffold `aidd_docs/memory/` yourself.
+- Write project files only, never personal or global memory.

plugins/aidd-context/skills/10-learn/actions/01-source.md

@@ -16,11 +16,11 @@ One or more source descriptions that name where to look and how narrowly to read
 2. **Select.** Select the smallest readable source set that fits the current context.
 3. **Ask.** Ask only when the source choice would change what gets learned.
 4. **Stop.** Stop on a missing, empty, or ambiguous source.
-5. **Emit.** Emit the selected source descriptions.
+5. **Emit.** Emit each source's kind, label, and scope.
 
 ## Test
 
 | Case | Pass |
 | --- | --- |
-| A source is readable | one or more source descriptions are emitted |
+| A source is readable | one or more sources are emitted, each with kind, label, and scope |
 | A source cannot be read | the run stops and names it |

plugins/aidd-context/skills/10-learn/actions/03-assess.md

@@ -12,9 +12,10 @@ A learning plan approved by the user and ready to write.
 
 ## Process
 
-1. **Frame.** Apply [assessment](../references/assessment.md), then use [destinations](../references/destinations.md) to propose where each candidate should land.
-2. **Score.** Score each candidate and reconcile existing coverage.
-3. **Confirm.** Show the scored recommendation and ask which packets to approve, edit, redirect, or skip.
+1. **Score.** Apply [assessment](../references/assessment.md) and [destinations](../references/destinations.md): reason internally to a 0-10 score, reconcile existing coverage, and propose where it lands.
+2. **Show.** State the source in one line, then fill and show the [recommendation table](../assets/recommendation-table.md).
+3. **Confirm.** Ask, per packet: approve, modify, or skip.
+   - When every packet is covered, skip the question.
 4. **Fill.** Fill [learning packet](../assets/learning-packet.md) for approved items only.
 
 ## Test
@@ -23,3 +24,6 @@ A learning plan approved by the user and ready to write.
 | --- | --- |
 | A packet is approved | it carries score, approved destination, reconciliation, and user approval |
 | An item is skipped or already covered | it is not written |
+| The confirm step runs | only the source line and the table appear before it |
+| The confirm question is asked | it names approve, modify, and skip |
+| Every candidate is covered | the run ends, nothing is asked |

plugins/aidd-context/skills/10-learn/actions/04-write.md

@@ -12,11 +12,12 @@ The created or updated files, and a summary table.
 
 ## Process
 
-1. **Start.** Start from the approved learning packet.
-2. **Route.** Apply only the destination path in [destinations](../references/destinations.md).
-3. **Fill.** Load the destination asset when one is required, fill it from the packet, and strip its guidance comment.
+1. **Start.** Start from each approved learning packet.
+2. **Route.** Apply the destination and reconciliation rules in [destinations](../references/destinations.md).
+3. **Fill.** Load the destination asset when one is required and follow its instructions.
+   - For a retraction, remove the entry instead of filling one.
 4. **Review.** Apply [review protocol](../references/review-protocol.md) to every touched file or handoff.
-5. **Report.** Report packet, destination, action, file or handoff, and review verdict.
+5. **Report.** Fill [write report](../assets/write-report.md) grouped by destination.
 
 ## Test
 
@@ -25,3 +26,4 @@ The created or updated files, and a summary table.
 | A lesson is approved | it appears in the table, at the destination the user chose |
 | A packet has no user approval | it is neither written nor handed off |
 | The report is delivered | it carries a review verdict for every touched file and handoff |
+| A candidate retracts existing content | the entry is removed, not left in place with a note |

plugins/aidd-context/skills/10-learn/actions/05-sync.md

@@ -4,7 +4,7 @@ Refresh context references after memory or ADR writes.
 
 ## Input
 
-The write summary, confirming at least one memory or ADR file changed. Skip this action when write only handed off rules or skills.
+The write summary, confirming at least one memory or ADR file changed.
 
 ## Output
 

plugins/aidd-context/skills/10-learn/assets/learning-packet.md

@@ -6,8 +6,8 @@
 - Source: <kind + label>
 - Evidence: <short quote or paraphrase>
 - Score: <0-10 + reason>
-- Destination: <approved memory | ADR | rule | skill>
-- Reconciliation: <new | covered | updates | supersedes>
-- User approval: <approved | edited | destination changed>
-- Scope: <files, workflow, or team context>
+- Destination: <approved memory | ADR | contract | rule | skill>
+- Reconciliation: <new | covered | updates | supersedes | retracts>
+- User approval: <approved | modified>
+- Applies to: <files, workflow, or team context>
 - Request: <one sentence when handing off to a generator>

plugins/aidd-context/skills/10-learn/assets/recommendation-table.md

@@ -0,0 +1,5 @@
+<!-- Reproduce this markdown table (pipe syntax), never a list or cards. One row per scored candidate. Score: plain 0-10 integer, never a label. Destination: one listed value, never invented text; for contract, name the file's basename as `contract: <file>`, not its full path. Reconciliation: one listed value with its emoji. Table stands alone, nothing before or after it. Strip this comment. -->
+
+| Packet | Score | Destination | Reconciliation |
+| --- | --- | --- | --- |
+| <title> | <0-10> | <memory \| ADR \| contract: \<file\> \| rule \| skill> | <✅ new \| covered \| ✏️ updates \| ✏️ supersedes \| ❌ retracts> |

plugins/aidd-context/skills/10-learn/assets/write-report.md

@@ -0,0 +1,7 @@
+<!-- Group rows by destination, one row per touched file or handoff, then strip this comment. -->
+
+### <memory | ADR | contract | rule | skill>
+
+| Action | File | Lesson | Review |
+| --- | --- | --- | --- |
+| <✅ add \| ✏️ modify \| ❌ remove> | <path, "new" when created> | <the lesson written> | <verdict> |

plugins/aidd-context/skills/10-learn/references/assessment.md

@@ -21,4 +21,5 @@ Reconcile before approval:
 - `new`: no equivalent content exists.
 - `covered`: existing content already carries it.
 - `updates`: refine an existing memory, rule, ADR, or skill.
-- `supersedes`: reverses an earlier decision or rule; require an explicit link.
+- `supersedes`: reverses an earlier decision or rule.
+- `retracts`: existing content no longer holds and nothing replaces it.

plugins/aidd-context/skills/10-learn/references/destinations.md

@@ -6,15 +6,22 @@ Every destination starts from the approved learning packet.
 | ----------- | -------- | ----- |
 | memory | durable project fact, convention, or gotcha | write the packet into the matching memory entry |
 | ADR | explicit choice with context and consequences | write the packet to `aidd_docs/memory/internal/decisions/<slug>.md` through [ADR template](../assets/adr-template.md) |
-| rule | enforceable coding or agent behavior | send the packet to rule-generate |
+| contract | enforceable behavior already owned by an existing project contract file | write the packet by amending that file |
+| rule | enforceable coding or agent behavior with no existing owner | send the packet to rule-generate |
 | skill | reusable workflow worth a dedicated skill | send the packet to skill-generate |
 
+Reconciliation:
+
+| Value | Apply |
+| --- | --- |
+| updates | replace the existing entry; do not add contradictions |
+| supersedes | replace the entry; link both decision records for an ADR |
+| retracts | remove the entry; delete the file only when nothing remains |
+
 Rules:
 
 - If the project memory bank is missing, say what is missing and ask before handing off to project-memory.
 - If the destination structure is unclear, ask. Do not invent a new taxonomy.
-- Replace superseded entries. Do not add contradictions.
-- For ADR supersession, link both decision records.
 - Prefer the narrowest destination that can own the lesson.
 - The user may choose another destination after seeing the recommendation.
-- Learn writes memory and ADRs. Learn hands off rules and skills.
+- Write memory, ADRs, and contract amendments directly. Hand off rules and skills.

plugins/aidd-context/skills/10-learn/references/gather-protocol.md

@@ -2,21 +2,20 @@
 
 Extract only durable project learning.
 
-Keep:
-
-- Decision, tradeoff, or consequence.
-- Convention or recurring project rule.
-- Pitfall, failed path, or costly pivot.
-- Reusable workflow worth documenting or automating.
-- Missing context that should prevent the same confusion later.
-
-Drop:
-
-- Personal preferences.
-- AI behavior preferences.
-- Routine implementation details.
-- One-off facts with no reuse.
-- Items already obviously covered by the source itself.
+| Signal | Verdict |
+| --- | --- |
+| Decision, tradeoff, or consequence | Keep |
+| Convention or recurring project rule | Keep |
+| Pitfall, failed path, or costly pivot | Keep |
+| Reusable workflow worth documenting or automating | Keep |
+| Missing context that should prevent the same confusion later | Keep |
+| Personal preference | Drop |
+| AI behavior preference | Drop |
+| Routine implementation detail | Drop |
+| One-off fact with no reuse | Drop |
+| Item already obviously covered by the source itself | Drop |
+| Signal outside the selected source's scope, even when noticed while reading | Drop |
+| Bug already fixed as part of the current change, unless the user explicitly asked to remember it as a decision | Drop |
 
 For each candidate, include:
 

plugins/aidd-context/skills/10-learn/references/review-protocol.md

@@ -7,7 +7,7 @@ Check:
 - The approved packet is represented.
 - No duplicate or contradictory entry was added.
 - Superseded ADRs or rules point to the newer decision.
+- A retracted entry is gone, not just marked.
+- A contract amendment lands in the file the packet names.
 - Memory and ADR references are synced when those destinations changed.
 - Rule and skill handoffs carry the approved packet and name the target generator.
-
-Do not expand scope into unrelated project cleanup.

plugins/aidd-context/skills/10-learn/references/sources.md

@@ -18,9 +18,8 @@ Kind meaning:
 Selection:
 
 - Explicit hint narrows the source kind.
-- No hint defaults to the current conversation, same as before this skill could take an explicit pointer.
+- No hint defaults to the current conversation.
 - Multiple specs are allowed when one source cannot explain the learning alone.
-- Ask before continuing when several source sets are plausible.
 
 Limits: