@sniper.ai/core 3.1.2 → 3.3.0

package/agents/memory-curator.md

@@ -0,0 +1,112 @@
+---
+write_scope:
+  - ".sniper/memory/"
+---
+
+# Memory Curator
+
+You are a SNIPER memory curator agent. You manage the lifecycle of project learnings — consolidating, validating, and pruning the learning store.
+
+## Responsibilities
+
+1. **Consolidation** — Merge duplicate or overlapping learnings
+2. **Contradiction Detection** — Find conflicting learnings and flag for resolution
+3. **Staleness Check** — Flag learnings that haven't been applied or reinforced recently
+4. **Spec Drift Detection** — Check if learnings still apply after spec/architecture changes
+5. **Signal Migration** — Convert legacy signals to learning records
+6. **Pruning** — Archive old deprecated learnings
+
+## Invocation
+
+You are spawned:
+- As the optional `curate` phase in protocols (after retro)
+- On-demand via `/sniper-learn --review`
+- Automatically when active learning count exceeds 30
+
+## Curation Process
+
+### 1. Consolidation
+
+1. Read all learnings from `.sniper/memory/learnings/` with `status: active` or `status: validated`
+2. Group learnings by overlapping `scope` (same agents, phases, or file patterns)
+3. Within each group, compare `learning` text for semantic similarity
+4. If two or more learnings describe the same pattern:
+   - Merge into the learning with the highest confidence
+   - Combine `reinforced_by` and `applied_in` arrays
+   - Set confidence to the max of the merged learnings
+   - Add history entry: `event: merged`, listing merged learning IDs
+   - Set merged learnings to `status: deprecated`, `superseded_by: <winner_id>`
+
+### 2. Contradiction Detection
+
+1. For each pair of active learnings, check if:
+   - The `anti_pattern` of one matches the `correction` of another
+   - The `learning` text directly contradicts another learning
+2. If a contradiction is found:
+   - Add each learning's ID to the other's `contradicted_by` array
+   - Reduce confidence by 0.1 on the older learning
+   - Add history entry: `event: contradicted`
+   - If both learnings have confidence >= 0.7, present the conflict to the user for resolution
+
+### 3. Staleness Check
+
+1. Determine the last 5 protocol IDs from `.sniper/retros/` (sorted by date)
+2. For each active learning:
+   - If the learning's `applied_in` does not include any of the last 5 protocol IDs AND the learning has not been reinforced in the last 90 days:
+     - Flag as stale
+     - Read current `docs/spec.md` and `docs/architecture.md`
+     - Assess whether the learning still applies to the current project state
+     - If clearly outdated, set `status: deprecated` with history entry
+     - If uncertain, reduce confidence by 0.05 and add history entry: `event: confidence_adjusted`
+
+### 4. Spec Drift Detection
+
+1. For each active learning with `scope.files` defined:
+   - Run `git log --since=<learning.updated_at> --name-only -- docs/spec.md docs/architecture.md` to check for changes
+   - If spec/architecture has changed since the learning was last updated:
+     - Read the current spec/architecture
+     - Assess if the learning still applies
+     - If clearly invalidated: set `status: deprecated` with history entry
+     - If unclear: flag for human review, add history note
+
+### 5. Signal Migration
+
+1. Read all files from `.sniper/memory/signals/`
+2. For each signal file:
+   - Create a learning record:
+     - `source.type`: map from signal type (`ci_failure` → `ci_failure`, `pr_review_comment` → `pr_review`, `production_error` → `ci_failure`, `manual` → `human`)
+     - `confidence`: 0.4 for CI/PR signals, 0.9 for manual
+     - `learning`: signal's `learning` field, or `summary` if no learning
+     - `scope.files`: signal's `affected_files`
+   - Write to `.sniper/memory/learnings/L-{date}-{hash}.yaml`
+   - Delete the original signal file
+3. Log: "Migrated N signals to learnings"
+
+### 6. Pruning
+
+1. Find deprecated learnings where `updated_at` is more than 180 days ago
+2. Move these files to `.sniper/memory/archive/`
+3. Log: "Archived N deprecated learnings"
+
+## Output
+
+After curation, write a summary to stdout:
+```
+Curation complete:
+- Consolidated: N learnings merged into M
+- Contradictions: N pairs flagged
+- Stale: N learnings flagged
+- Spec drift: N learnings reviewed
+- Migrated: N signals → learnings
+- Archived: N deprecated learnings
+- Active learnings: N (confidence avg: X.XX)
+```
+
+## Rules
+
+- NEVER delete a learning without archiving it first
+- NEVER auto-deprecate human-sourced learnings (confidence >= 0.9) — flag for review instead
+- ALWAYS write history entries for every status or confidence change
+- Write scope is `.sniper/memory/` only — never modify project code or other SNIPER directories
+- Cap consolidation at 10 merges per run to avoid over-aggressive pruning
+- When uncertain about staleness or spec drift, err on the side of keeping the learning

package/agents/retro-analyst.md

@@ -18,7 +18,7 @@ You are a SNIPER retro analyst agent. You run automated retrospectives after pro
 
 ## Invocation
 
-You are automatically spawned by `/sniper-flow` at protocol completion when `auto_retro: true`.
+You are spawned as part of the `retro` phase in protocols (full, feature, refactor).
 The orchestrator provides you with the `protocol_id` (e.g., `SNPR-20260307-a3f2`) and protocol type.
 
 ## Analysis Process
@@ -61,23 +61,75 @@ findings:
 - Keep the report concise — under 1000 tokens
 - Compare against previous retros if they exist to track trends
 
+## Learning Extraction
+
+After generating the retro report, extract learnings into the unified learning store:
+
+1. For each `action_item` in the retro findings, create a learning record:
+   - `id`: `L-{YYYYMMDD}-{4-char-hex}`
+   - `status: active`
+   - `confidence: 0.5`
+   - `source.type: retro`
+   - `source.protocol_id: {protocol_id}`
+   - `source.detail`: context from the retro finding
+   - `learning`: the action item text
+   - `scope`: infer from context — which phase failed (→ `scope.phases`), which agents were involved (→ `scope.agents`), which files were touched (→ `scope.files`)
+   - Write to `.sniper/memory/learnings/L-{date}-{hash}.yaml`
+
+2. For each `needs_improvement` item that is **specific and actionable** (not vague like "better communication"):
+   - Create a learning at `confidence: 0.4`
+   - Same format as above
+
+3. **Cap at 5 learnings per retro** to avoid noise. Prioritize by specificity and actionability.
+
+4. Record the created learning IDs in the retro report under `findings.learning_ids`.
+
+## Learning Effectiveness Check
+
+After extracting new learnings, check effectiveness of previously applied learnings:
+
+1. Read all active learnings from `.sniper/memory/learnings/` where `applied_in` contains any recent protocol ID (including the current one)
+2. For each such learning, check if the related problem recurred:
+   - Gate failures in the learning's scoped phase?
+   - CI failures in the learning's scoped files?
+   - Human rejection feedback mentioning the same pattern?
+3. **No recurrence** → increase confidence by +0.05, add history entry:
+   ```yaml
+   - timestamp: <ISO 8601>
+     event: validated_by_absence
+     detail: "No recurrence in {protocol_id}"
+     confidence_delta: +0.05
+   ```
+4. **Recurrence despite the learning** → decrease confidence by -0.2, add history entry:
+   ```yaml
+   - timestamp: <ISO 8601>
+     event: recurrence_detected
+     detail: "Problem recurred in {protocol_id} despite learning"
+     confidence_delta: -0.2
+   ```
+   Flag for human review by adding to findings.
+5. If confidence drops below 0.2 after adjustment, set `status: deprecated`.
+
 ## Signal Analysis
 
-During the retrospective, analyze external signals:
+During the retrospective, analyze external signals from both legacy and new stores:
 
-1. Read `.sniper/memory/signals/` for signal records captured during this protocol execution
-2. Correlate signals with protocol phases: which CI failures occurred during which phase?
-3. Identify recurring patterns: are the same files or tests failing repeatedly?
-4. Promote high-confidence learnings: if a signal's learning applies broadly, note it in the retro findings
-5. Include signal summary in the retro report under a `signals_analyzed` section:
+1. Read `.sniper/memory/signals/` for legacy signal records (if any exist)
+2. Read `.sniper/memory/learnings/` for existing learnings
+3. Correlate signals with protocol phases: which CI failures occurred during which phase?
+4. Identify recurring patterns: are the same files or tests failing repeatedly?
+5. If legacy signals exist, note in the retro report: "Legacy signals detected. Run `/sniper-learn --review` to migrate to learnings."
+6. Include signal summary in the retro report under a `signals_analyzed` section:
    ```yaml
    signals_analyzed:
      total: <count>
      by_type:
        ci_failure: <count>
        pr_review_comment: <count>
-     promoted_learnings:
-       - <learning that should be applied going forward>
+     learnings_checked: <count>
+     effectiveness:
+       validated: <count>
+       recurrence: <count>
    ```
 
 ## Velocity Tracking

package/checklists/plan.yaml

@@ -20,11 +20,6 @@ checks:
     blocking: true
     description: Architecture plan includes Data Model section
 
-  - id: ears_criteria
-    description: All stories have EARS acceptance criteria
-    check: grep:.sniper/artifacts/{protocol_id}/stories/:"shall"
-    blocking: true
-
   - id: open_questions
     description: No unresolved open questions remain
     check: "!grep:.sniper/artifacts/{protocol_id}/:\\*\\*TBD\\*\\*|\\*\\*TODO\\*\\*|\\*\\*OPEN\\*\\*"

package/checklists/retro.yaml

@@ -0,0 +1,15 @@
+name: retro
+description: Gate checks for the retrospective phase
+
+checks:
+  - id: retro_report_exists
+    description: Retro report file exists
+    type: file_exists
+    path: ".sniper/retros/{protocol_id}.yaml"
+    blocking: true
+
+  - id: velocity_updated
+    description: Velocity data updated
+    type: file_exists
+    path: ".sniper/memory/velocity.yaml"
+    blocking: true

package/checklists/solve.yaml

@@ -0,0 +1,29 @@
+name: solve
+description: Story sharding quality gate
+# Note: {protocol_id} is resolved at gate-review time from the active checkpoint
+
+checks:
+  - id: stories_exist
+    description: At least one story file exists
+    check: glob:.sniper/artifacts/{protocol_id}/stories/:*.md
+    blocking: true
+
+  - id: ears_criteria
+    description: All stories have EARS acceptance criteria
+    check: grep:.sniper/artifacts/{protocol_id}/stories/:"shall"
+    blocking: true
+
+  - id: stories_have_status
+    description: All stories have a status field in frontmatter
+    check: grep:.sniper/artifacts/{protocol_id}/stories/:"status:"
+    blocking: true
+
+  - id: stories_reference_architecture
+    description: Stories reference the architecture plan
+    check: grep:.sniper/artifacts/{protocol_id}/stories/:"plan.md"
+    blocking: false
+
+  - id: open_questions
+    description: No unresolved open questions in stories
+    check: "!grep:.sniper/artifacts/{protocol_id}/stories/:\\*\\*TBD\\*\\*|\\*\\*TODO\\*\\*|\\*\\*OPEN\\*\\*"
+    blocking: false

package/config.template.yaml

@@ -24,6 +24,7 @@ agents:
     - code-reviewer
     - gate-reviewer
     - retro-analyst
+    - memory-curator
 
   # Cognitive mixins applied to agents during scaffolding
   # Format: agent-name: [mixin1, mixin2]
@@ -148,9 +149,17 @@ plugins: []
 # workspace:
 #   ref: "../.sniper-workspace"
 
+# Learning store configuration
+learning:
+  max_per_retro: 5              # Cap learnings created per retro
+  min_confidence: 0.4           # Threshold for composition into agent prompts
+  composition_limit: 10         # Max learnings composed per agent
+  staleness_threshold: 5        # Protocols without application before flagging
+  archive_after_days: 180       # Days after deprecation before archiving
+
 # Visibility settings
 visibility:
   live_status: true          # Maintain .sniper/live-status.yaml
   checkpoints: true          # Write phase checkpoints
   cost_tracking: true        # Track token usage
-  auto_retro: true           # Run retro after protocol completion
+  # auto_retro: true         # DEPRECATED — use retro phase in protocols instead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sniper.ai/core",
-  "version": "3.1.2",
+  "version": "3.3.0",
   "description": "SNIPER framework core — agents, skills, protocols, checklists, templates, and hooks",
   "type": "module",
   "exports": {

package/protocols/feature.yaml

@@ -4,18 +4,28 @@ budget: 800000  # 800K tokens
 
 phases:
   - name: plan
-    description: Feature design and story creation
+    description: Feature design and architecture
     agents:
       - architect
       - product-manager
-    spawn_strategy: sequential  # Architect designs first, PM writes stories from that
-    interactive_review: true  # Present plan to user for review/feedback before proceeding
+    spawn_strategy: sequential  # Architect designs first, PM refines PRD from that
+    interactive_review: true  # User reviews architecture before story sharding
     gate:
       checklist: plan
       human_approval: true
     outputs:
       - .sniper/artifacts/{protocol_id}/plan.md
       - .sniper/artifacts/{protocol_id}/prd.md
+
+  - name: solve
+    description: Story creation from approved architecture
+    agents:
+      - product-manager
+    spawn_strategy: single
+    gate:
+      checklist: solve
+      human_approval: false
+    outputs:
       - .sniper/artifacts/{protocol_id}/stories/
 
   - name: implement
@@ -44,4 +54,15 @@ phases:
     outputs:
       - .sniper/artifacts/{protocol_id}/review-report.md
 
-auto_retro: true
+  - name: retro
+    description: Retrospective — extract learnings, update velocity, check learning effectiveness
+    agents:
+      - retro-analyst
+    spawn_strategy: single
+    gate:
+      checklist: retro
+      human_approval: false
+    outputs:
+      - .sniper/retros/{protocol_id}.yaml
+      - .sniper/memory/velocity.yaml
+      - .sniper/memory/learnings/

package/protocols/full.yaml

@@ -4,33 +4,44 @@ budget: 2000000  # 2M tokens
 
 phases:
   - name: discover
-    description: Research, analyze codebase, produce discovery spec
+    description: Research, analyze codebase, produce discovery spec and PRD
     agents:
       - analyst
     spawn_strategy: single  # One agent, no team needed
+    interactive_review: true  # User reviews spec/PRD before architecture begins
     gate:
       checklist: discover
-      human_approval: false
+      human_approval: true
     outputs:
       - .sniper/artifacts/spec.md  # Living master doc
       - .sniper/artifacts/codebase-overview.md  # Living master doc
 
   - name: plan
-    description: Architecture design, PRD creation, story breakdown
+    description: Architecture design and PRD refinement
     agents:
       - architect
       - product-manager
     spawn_strategy: team  # Multiple agents, use TeamCreate
-    interactive_review: true  # Present plan to user for review/feedback before proceeding
+    interactive_review: true  # User reviews architecture before story sharding
     coordination:
       - between: [architect, product-manager]
-        topic: Architecture must be approved before stories reference it
+        topic: Architecture must be finalized before PRD is updated
     gate:
       checklist: plan
-      human_approval: true  # Human reviews the plan before implementation
+      human_approval: true  # Human reviews architecture before stories are created
     outputs:
       - .sniper/artifacts/{protocol_id}/plan.md
       - .sniper/artifacts/{protocol_id}/prd.md
+
+  - name: solve
+    description: Epic sharding and story creation from approved architecture
+    agents:
+      - product-manager
+    spawn_strategy: single
+    gate:
+      checklist: solve
+      human_approval: false
+    outputs:
       - .sniper/artifacts/{protocol_id}/stories/
 
   - name: implement
@@ -62,4 +73,25 @@ phases:
     outputs:
       - .sniper/artifacts/{protocol_id}/review-report.md
 
-auto_retro: true  # Trigger retro-analyst after completion
+  - name: retro
+    description: Retrospective — extract learnings, update velocity, check learning effectiveness
+    agents:
+      - retro-analyst
+    spawn_strategy: single
+    gate:
+      checklist: retro
+      human_approval: false
+    outputs:
+      - .sniper/retros/{protocol_id}.yaml
+      - .sniper/memory/velocity.yaml
+      - .sniper/memory/learnings/
+
+  - name: curate
+    description: Review and consolidate learnings (skipped if not needed)
+    agents:
+      - memory-curator
+    spawn_strategy: single
+    skip_if: learning_count < 30 AND last_curation_within_5_protocols
+    gate:
+      checklist: none
+      human_approval: false

package/protocols/refactor.yaml

@@ -40,4 +40,15 @@ phases:
     outputs:
       - .sniper/artifacts/{protocol_id}/review-report.md
 
-auto_retro: true
+  - name: retro
+    description: Retrospective — extract learnings, update velocity, check learning effectiveness
+    agents:
+      - retro-analyst
+    spawn_strategy: single
+    gate:
+      checklist: retro
+      human_approval: false
+    outputs:
+      - .sniper/retros/{protocol_id}.yaml
+      - .sniper/memory/velocity.yaml
+      - .sniper/memory/learnings/

package/schemas/learning.schema.yaml

@@ -0,0 +1,128 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/learning"
+title: Learning Record
+description: Schema for SNIPER learning records — unified store for project-specific learnings captured from retros, human feedback, CI failures, PR reviews, and gate failures.
+type: object
+required:
+  - id
+  - status
+  - confidence
+  - created_at
+  - source
+  - learning
+properties:
+  id:
+    type: string
+    pattern: "^L-\\d{8}-[a-f0-9]{4}$"
+    description: "Unique learning ID in format L-YYYYMMDD-XXXX (4-char hex suffix)."
+  status:
+    type: string
+    enum: [draft, active, validated, deprecated]
+    description: Lifecycle status of the learning.
+  confidence:
+    type: number
+    minimum: 0.0
+    maximum: 1.0
+    description: "Confidence score (0.0–1.0). Changes over time based on reinforcement, contradictions, and decay."
+  created_at:
+    type: string
+    format: date-time
+    description: When the learning was first created.
+  updated_at:
+    type: string
+    format: date-time
+    description: When the learning was last modified.
+  expires_at:
+    type: string
+    format: date-time
+    description: "Optional expiration date. Null means never expires."
+
+  # Origin
+  source:
+    type: object
+    required:
+      - type
+    properties:
+      type:
+        type: string
+        enum: [retro, human, ci_failure, pr_review, gate_failure]
+        description: How this learning entered the system.
+      protocol_id:
+        type: string
+        description: "Protocol ID that generated this learning (null for human-submitted)."
+      detail:
+        type: string
+        description: Context about how the learning was discovered.
+    additionalProperties: false
+
+  # The learning itself
+  learning:
+    type: string
+    description: The core insight or lesson learned.
+  anti_pattern:
+    type: string
+    description: What to avoid — the behavior that caused the problem.
+  correction:
+    type: string
+    description: What to do instead — the recommended approach.
+
+  # Scoping
+  scope:
+    type: object
+    properties:
+      agents:
+        type: array
+        items: { type: string }
+        description: "Agent personas this learning applies to. Null = all agents."
+      phases:
+        type: array
+        items: { type: string }
+        description: "Protocol phases this learning applies to. Null = all phases."
+      files:
+        type: array
+        items: { type: string }
+        description: "Glob patterns for relevant files. Null = all files."
+    additionalProperties: false
+
+  # Effectiveness tracking
+  applied_in:
+    type: array
+    items: { type: string }
+    description: Protocol IDs where this learning was composed into agent prompts.
+  reinforced_by:
+    type: array
+    items: { type: string }
+    description: Event or learning IDs that confirm this learning.
+  contradicted_by:
+    type: array
+    items: { type: string }
+    description: Learning IDs that contradict this learning.
+  superseded_by:
+    type: string
+    description: "If deprecated, the learning ID that replaced this one."
+
+  # Audit trail
+  history:
+    type: array
+    items:
+      type: object
+      required:
+        - timestamp
+        - event
+      properties:
+        timestamp:
+          type: string
+          format: date-time
+        event:
+          type: string
+          enum: [created, reinforced, contradicted, deprecated, validated_by_absence, recurrence_detected, confidence_adjusted, merged, human_confirmed, human_invalidated]
+        actor:
+          type: string
+          description: "Who triggered this event (agent name or 'human')."
+        detail:
+          type: string
+        confidence_delta:
+          type: number
+          description: "Change in confidence from this event (e.g., +0.1, -0.2)."
+      additionalProperties: false
+additionalProperties: false

package/schemas/live-status.schema.yaml

@@ -76,6 +76,33 @@ properties:
           minimum: 0
           maximum: 100
           description: Phase completion percentage.
+  stories:
+    type: array
+    description: Per-story status tracking for the current protocol run.
+    items:
+      type: object
+      required:
+        - id
+        - title
+        - status
+      properties:
+        id:
+          type: string
+          description: Story identifier (e.g., "001", "002").
+        title:
+          type: string
+          description: Story title.
+        status:
+          type: string
+          enum:
+            - pending
+            - in_progress
+            - completed
+            - skipped
+          description: Current status of the story.
+        assigned_agent:
+          type: string
+          description: Agent assigned to implement this story.
   gate_results:
     type: array
     description: Results from completed gate reviews.

package/schemas/protocol.schema.yaml

@@ -54,7 +54,9 @@ properties:
           properties:
             checklist:
               type: string
-              description: Name of the checklist to evaluate at the gate.
+              description: >
+                Name of the checklist to evaluate at the gate.
+                Use "none" to skip checklist evaluation (phase still completes normally).
             human_approval:
               type: boolean
               description: Whether a human must approve the gate before proceeding.
@@ -93,8 +95,19 @@ properties:
                 type: string
                 description: Description of the coordination requirement.
             additionalProperties: false
+        skip_if:
+          type: string
+          description: >
+            Predicate expression that, when true, causes this phase to be skipped.
+            Available variables: learning_count (active learnings),
+            last_curation_within_N_protocols (boolean).
+            Example: "learning_count < 30 AND last_curation_within_5_protocols"
       additionalProperties: false
   auto_retro:
     type: boolean
-    description: Whether to trigger the retro-analyst after protocol completion.
+    deprecated: true
+    description: >
+      DEPRECATED — Use a 'retro' phase in the phases list instead.
+      When true, spawns retro-analyst after protocol completion. Retained for
+      backward compatibility with custom protocols that don't define a retro phase.
 additionalProperties: false

package/schemas/retro.schema.yaml

@@ -78,6 +78,10 @@ properties:
         description: Concrete action items for future runs.
         items:
           type: string
+      learning_ids:
+        type: array
+        items: { type: string }
+        description: IDs of learnings created from this retro's findings.
   velocity:
     type: object
     description: Velocity metrics for this execution, used for budget calibration.

package/schemas/signal.schema.yaml

@@ -1,7 +1,15 @@
 $schema: "https://json-schema.org/draft/2020-12/schema"
 $id: "https://sniper.ai/schemas/signal"
 title: External Signal Record
-description: Schema for SNIPER signal records that capture learnings from CI failures, PR reviews, and production errors.
+deprecated: true
+superseded_by: learning.schema.yaml
+description: >
+  DEPRECATED — Superseded by learning.schema.yaml.
+  This schema is retained for backward compatibility. Existing signal files in
+  .sniper/memory/signals/ will be migrated to learnings by the memory-curator
+  agent on first run. Use /sniper-learn --review to trigger migration.
+  Original description: Schema for SNIPER signal records that capture learnings
+  from CI failures, PR reviews, and production errors.
 type: object
 required:
   - type

package/skills/sniper-flow/SKILL.md

@@ -84,6 +84,8 @@ commits: [git SHAs produced]
 
 Update `.sniper/live-status.yaml` with current phase, agent statuses, and cost percentage.
 
+After the `solve` phase completes, populate the `stories` array in `.sniper/live-status.yaml` by reading story files from `.sniper/artifacts/{protocol_id}/stories/`. During `implement`, update each story's status (`in_progress` → `completed`) as agents finish work on it.
+
 ### Gate
 
 1. Write `.sniper/pending-gate.yaml` with phase name and checklist reference
@@ -106,8 +108,8 @@ Update `.sniper/live-status.yaml` with current phase, agent statuses, and cost p
 2. Update `.sniper/live-status.yaml` with `status: completed`
 3. Update `.sniper/artifacts/{protocol_id}/meta.yaml` with final status, token usage, commits, agents used
 4. Update `.sniper/artifacts/registry.md` entry from `in_progress` to `completed`
-5. Present summary: phases completed, gate results, token usage
-6. If `auto_retro: true` in protocol: spawn `retro-analyst` as background task (see [Reference: Retrospective](#reference-retrospective))
+5. Present summary: phases completed, gate results, token usage, learnings created
+6. **Backward compatibility:** If the protocol has `auto_retro: true` but no `retro` phase in its phases list (custom protocols), spawn retro-analyst as a single-agent phase before completing
 
 ## Cost Tracking
 
@@ -141,9 +143,26 @@ For each agent in the phase, build the full prompt by layering these sources. Ea
 | 2. Mixins | `.claude/personas/cognitive/<mixin>.md` (from `config.agents.mixins.<agent>`) | WARN — skip mixin, continue |
 | 3. Domain knowledge | `.sniper/knowledge/manifest.yaml` → referenced files (from agent's `knowledge_sources` frontmatter) | SKIP — no knowledge section |
 | 4. Workspace conventions | `.sniper-workspace/config.yaml` → `shared.conventions` and `shared.anti_patterns` | SKIP — no workspace section |
-| 5. Signals | `.sniper/memory/signals/` → top 10 most relevant by `affected_files` and `relevance_tags` | SKIP — no signals section |
+| 5. Learnings | `.sniper/memory/learnings/` → scoped, confidence-ranked, top 10 | SKIP — no learnings |
+
+**Learning Composition (Layer 5):**
+
+```
+Filter: status IN (active, validated), confidence >= 0.4
+Match:  scope.agents includes <current_agent> OR scope.agents is null
+Match:  scope.phases includes <current_phase> OR scope.phases is null
+Match:  scope.files overlaps with <agent_ownership_paths> OR scope.files is null
+Rank:   confidence DESC, updated_at DESC
+Limit:  10
+```
+
+Confidence bands: `>= 0.7` = HIGH, `0.4–0.7` = MEDIUM.
 
-The composed prompt = base definition + concatenated mixin content + `## Domain Knowledge` section + `## Workspace Conventions` section + `## Anti-Patterns (Workspace)` section + `## Recent Learnings` section (formatted as `- [<type>] <summary> (<affected_files>)`).
+After composing learnings into the prompt, record the current protocol ID in each learning's `applied_in` array (write the updated learning file back).
+
+**Backward compatibility:** If `.sniper/memory/signals/` contains files but `.sniper/memory/learnings/` is empty or doesn't exist, fall back to the old Layer 5 behavior (read signals, top 10 by `affected_files` and `relevance_tags`). Log a warning: "Legacy signals detected. Run `/sniper-learn --review` to migrate."
+
+The composed prompt = base definition + concatenated mixin content + `## Domain Knowledge` section + `## Workspace Conventions` section + `## Anti-Patterns (Workspace)` section + `## Learnings` section (formatted as `- [HIGH] {learning}. Anti-pattern: {anti_pattern}. Instead: {correction}.` or `- [MEDIUM] {learning}.`).
 
 Replace all `{protocol_id}` placeholders in the composed prompt with the actual protocol ID.
 
@@ -180,17 +199,33 @@ For agents working in worktrees (after all implementation agents complete):
 
 When a phase has `interactive_review: true`:
 
-1. Read produced artifacts from `.sniper/artifacts/{protocol_id}/` (e.g., `plan.md`, `prd.md`, `stories/`)
-2. Present a structured summary: key architectural decisions, component overview, story count, open questions
+1. Read produced artifacts from `.sniper/artifacts/{protocol_id}/` (e.g., `spec.md`, `plan.md`, `prd.md`)
+2. Present a structured summary appropriate to the phase:
+   - **discover:** scope, requirements, key findings, open questions
+   - **plan:** key architectural decisions, component overview, data model, trade-offs
 3. Offer options:
    - **Approve** — continue to next phase
    - **Request changes** — describe changes (architect/PM will revise, then re-present)
    - **Edit directly** — user modifies plan files, says "done", re-validate via gate
 4. Only advance after explicit user approval
 
-## Reference: Retrospective
+## Reference: Retrospective (Legacy)
+
+> **Note:** The retro is now a first-class phase in protocols (full, feature, refactor). This reference is retained for backward compatibility with custom protocols using `auto_retro: true`.
+
+When `auto_retro: true` and no `retro` phase exists in the protocol:
+1. Spawn `retro-analyst` as a single-agent phase with: protocol ID, checkpoint history, gate results, cost data
+2. The retro-analyst writes a report to `.sniper/retros/{protocol_id}.yaml`, extracts learnings to `.sniper/memory/learnings/`, updates `.sniper/memory/velocity.yaml`, and checks effectiveness of previously applied learnings
+3. Run the retro gate checklist (retro report exists + velocity updated)
+
+## Reference: Review Gate Feedback Capture
+
+When a user selects "Request changes" during an interactive review:
 
-When `auto_retro: true`, after protocol completion:
-1. Spawn `retro-analyst` as a background Task with: protocol ID, checkpoint history, gate results, cost data
-2. The retro-analyst writes a report to `.sniper/retros/{protocol_id}.yaml`, updates `.sniper/memory/velocity.yaml` with execution metrics, and calculates calibrated budgets if 5+ data points exist
-3. Runs in background — user doesn't wait for it
+1. Ask: "What should be changed and why?"
+2. Parse the response for actionable learnings — patterns and rules, not one-off fixes
+3. If the feedback describes a generalizable pattern (not just "fix line 42"):
+   - Create a learning with `source.type: human`, `confidence: 0.9`
+   - Scope to the current phase and relevant agents
+   - Write to `.sniper/memory/learnings/`
+4. Include the learning in the agent prompt when the phase reruns

package/skills/sniper-init/SKILL.md

@@ -73,6 +73,11 @@ Create the following directory structure:
   retros/
   self-reviews/
   checklists/              ← Copied from @sniper.ai/core/checklists/
+  memory/
+    learnings/             ← Unified learning store (replaces signals/)
+    signals/               ← Legacy — kept for backward compat, migrated by memory-curator
+    velocity.yaml
+    archive/               ← Deprecated learnings archived here
 .claude/
   agents/                  ← Copied from @sniper.ai/core/agents/
   settings.json            ← Merge hooks from @sniper.ai/core/hooks/

package/skills/sniper-learn/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: sniper-learn
+description: Submit, review, or deprecate project learnings
+arguments:
+  - name: learning
+    description: "The learning to submit (e.g., \"Always validate JWT expiry before checking permissions\")"
+    required: false
+  - name: review
+    description: Review and curate existing learnings
+    required: false
+    type: boolean
+  - name: deprecate
+    description: "Learning ID to deprecate (e.g., L-20260307-a3f2)"
+    required: false
+---
+
+# /sniper-learn
+
+Manage the SNIPER learning store. Submit new learnings from experience, review existing learnings, or deprecate outdated ones.
+
+## Mode Selection
+
+```
+--review given?             → Review mode
+--deprecate <id> given?     → Deprecate mode
+learning text given?        → Submit mode
+Nothing given?              → Submit mode (prompt for learning text)
+```
+
+## Submit Mode
+
+Submit a new learning from human experience or observation.
+
+### Process
+
+1. **Capture the learning text** from the argument or prompt the user:
+   - "What did you learn? Describe the pattern, rule, or insight."
+
+2. **Ask clarifying questions** (present as multi-select, all optional):
+   - **Agents:** Which agents should see this learning? (default: all)
+     - Options: analyst, architect, product-manager, fullstack-dev, backend-dev, frontend-dev, qa-engineer, code-reviewer
+   - **Phases:** Which protocol phases does this apply to? (default: all)
+     - Options: discover, plan, solve, implement, review
+   - **Files:** Any specific file patterns? (default: all)
+     - Accept glob patterns like `src/api/**`, `*.test.ts`
+
+3. **Ask for anti-pattern and correction** (optional):
+   - "Is there a specific anti-pattern to avoid?"
+   - "What should be done instead?"
+
+4. **Create the learning record:**
+   ```yaml
+   id: L-{YYYYMMDD}-{4-char-hex}
+   status: active
+   confidence: 0.9
+   created_at: {ISO 8601}
+   updated_at: {ISO 8601}
+   source:
+     type: human
+     detail: "Submitted via /sniper-learn"
+   learning: {learning text}
+   anti_pattern: {if provided}
+   correction: {if provided}
+   scope:
+     agents: {selected or null}
+     phases: {selected or null}
+     files: {selected or null}
+   applied_in: []
+   reinforced_by: []
+   contradicted_by: []
+   history:
+     - timestamp: {ISO 8601}
+       event: created
+       actor: human
+   ```
+
+5. **Write** to `.sniper/memory/learnings/{id}.yaml`
+
+6. **Confirm:** "Learning `{id}` created with confidence 0.9. It will be composed into agent prompts for matching phases/agents."
+
+## Review Mode
+
+Review, curate, and manage existing learnings.
+
+### Process
+
+1. **Spawn the memory-curator agent** from `.claude/agents/memory-curator.md`
+   - Pass it the task: "Run full curation — consolidation, contradiction detection, staleness check, spec drift detection, signal migration, and pruning."
+
+2. **Present curator summary** to the user
+
+3. **Show flagged items** requiring human decision:
+   - Contradictions between high-confidence learnings
+   - Stale learnings that might still apply
+   - Spec drift detections
+
+4. **For each flagged item**, ask the user:
+   - **Keep** — maintain current status
+   - **Deprecate** — set status to deprecated
+   - **Edit** — modify the learning text/scope
+
+5. **Show final state:**
+   ```
+   Active learnings: N
+   Validated: N
+   Deprecated: N
+   Archived: N
+   Average confidence: X.XX
+   ```
+
+## Deprecate Mode
+
+Deprecate a specific learning by ID.
+
+### Process
+
+1. **Read** `.sniper/memory/learnings/{id}.yaml`
+2. If not found, report error: "Learning `{id}` not found."
+3. **Show the learning** to the user for confirmation:
+   - Learning text, current confidence, source, created date
+4. **Confirm:** "Deprecate this learning?"
+5. **Update the learning:**
+   - `status: deprecated`
+   - `confidence: 0.0`
+   - Add history entry:
+     ```yaml
+     - timestamp: {ISO 8601}
+       event: human_invalidated
+       actor: human
+       detail: "Deprecated via /sniper-learn --deprecate"
+     ```
+6. **Confirm:** "Learning `{id}` deprecated. It will no longer be composed into agent prompts."
+
+## Rules
+
+- Human-submitted learnings ALWAYS start at confidence 0.9
+- ALWAYS write to `.sniper/memory/learnings/` — never to signals
+- ALWAYS include a history entry for every change
+- If `.sniper/memory/learnings/` doesn't exist, create it
+- If `.sniper/memory/signals/` contains files, suggest running `--review` to migrate them

package/skills/sniper-review/SKILL.md

@@ -42,6 +42,17 @@ Display the gate result:
 
 Save the gate result to `.sniper/gates/<phase>-<timestamp>.yaml`.
 
+### 6. Capture Feedback
+
+If the gate fails and the user provides feedback on what should change:
+
+1. Parse the feedback for actionable, generalizable patterns
+2. If the feedback describes a pattern (not a one-off fix):
+   - Create a learning with `source.type: human`, `confidence: 0.9`
+   - Scope to the reviewed phase and relevant agents
+   - Write to `.sniper/memory/learnings/`
+3. Note: "Learning `{id}` captured from review feedback."
+
 ## Rules
 
 - This is a manual trigger — it does NOT advance the protocol phase

package/templates/custom-protocol.yaml

@@ -93,6 +93,36 @@ phases:
     outputs:
       - .sniper/artifacts/{protocol_id}/review-report.md
 
-# auto_retro (optional, default: false): Whether to run the retro-analyst
-# after protocol completion to record velocity metrics.
-auto_retro: true
+  # ── Phase 4: Retro (recommended) ──────────────────────────
+  # Runs the retro-analyst to extract learnings, update velocity, and check
+  # learning effectiveness. Replaces the old auto_retro flag.
+  - name: retro
+    description: Retrospective — extract learnings and update velocity
+    agents:
+      - retro-analyst
+    spawn_strategy: single
+    gate:
+      checklist: retro
+      human_approval: false
+    outputs:
+      - .sniper/retros/{protocol_id}.yaml
+      - .sniper/memory/velocity.yaml
+      - .sniper/memory/learnings/
+
+  # ── Phase 5: Curate (optional) ────────────────────────────
+  # Consolidate, prune, and review learnings. Only runs when learning count
+  # exceeds 30 or last curation was more than 5 protocols ago.
+  # - name: curate
+  #   description: Review and consolidate learnings
+  #   agents:
+  #     - memory-curator
+  #   spawn_strategy: single
+  #   skip_if: learning_count < 30 AND last_curation_within_5_protocols
+  #   gate:
+  #     checklist: none
+  #     human_approval: false
+
+# auto_retro (DEPRECATED — use a retro phase instead):
+# Retained for backward compatibility. If set to true and no retro phase
+# exists, the retro-analyst is spawned as a single-agent phase at completion.
+# auto_retro: true

package/templates/live-status.yaml

@@ -13,6 +13,12 @@ phases:
     #   status: active | completed | failed
     progress: 0  # percentage
 
+stories: []
+# - id: "001"
+#   title: ""
+#   status: pending  # pending | in_progress | completed | skipped
+#   assigned_agent: ""
+
 gate_results: []
 # - phase: discover
 #   result: pass

package/templates/story.md

@@ -1,3 +1,10 @@
+---
+status: pending  # pending | in_progress | completed | skipped
+assigned_agent:
+started_at:
+completed_at:
+---
+
 # Story: [TITLE]
 <!-- Budget: 1500 tokens max -->