@sniper.ai/core 1.0.1 → 2.0.0

package/framework/commands/sniper-memory.md

@@ -0,0 +1,219 @@
+# /sniper-memory -- Manage Agent Memory (Conventions, Anti-Patterns, Decisions)
+
+You are executing the `/sniper-memory` command. Your job is to manage the project's accumulated knowledge — conventions, anti-patterns, and decisions that agents learn over time. Follow every step below precisely.
+
+The user's arguments are provided in: $ARGUMENTS
+
+---
+
+## Step 0: Pre-Flight Checks
+
+1. Verify `.sniper/config.yaml` exists (SNIPER is initialized)
+2. Check if `.sniper/memory/` directory exists. If not, create it with empty starter files:
+   - `.sniper/memory/conventions.yaml` with `conventions: []`
+   - `.sniper/memory/anti-patterns.yaml` with `anti_patterns: []`
+   - `.sniper/memory/decisions.yaml` with `decisions: []`
+   - `.sniper/memory/estimates.yaml` with `calibration: { velocity_factor: 1.0, common_underestimates: [], last_updated: null, sprints_analyzed: 0 }`
+   - `.sniper/memory/retros/` directory
+
+---
+
+## Step 1: Parse Arguments
+
+Parse the following flags from `$ARGUMENTS`:
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| (none) | Show memory summary | `/sniper-memory` |
+| `--conventions` | List all conventions | `/sniper-memory --conventions` |
+| `--anti-patterns` | List all anti-patterns | `/sniper-memory --anti-patterns` |
+| `--decisions` | List all decisions | `/sniper-memory --decisions` |
+| `--add convention "rule"` | Add a new convention | `/sniper-memory --add convention "Use barrel exports"` |
+| `--add anti-pattern "desc"` | Add a new anti-pattern | `/sniper-memory --add anti-pattern "Nested ternaries"` |
+| `--add decision "title" --rationale "why"` | Add a decision | `/sniper-memory --add decision "Use Zod" --rationale "Type-safe validation"` |
+| `--remove {id}` | Remove an entry by ID | `/sniper-memory --remove conv-003` |
+| `--promote {id}` | Promote candidate to confirmed | `/sniper-memory --promote ap-002` |
+| `--export` | Export memory as portable YAML | `/sniper-memory --export` |
+| `--import {file}` | Import memory from file | `/sniper-memory --import memory-pack.yaml` |
+| `--retro` | Manually trigger retrospective | `/sniper-memory --retro` |
+
+If no arguments provided, default to showing the summary.
+
+If unrecognized flags, show usage guide and STOP.
+
+---
+
+## Step 2: Read Memory State
+
+1. Read `.sniper/memory/conventions.yaml` — parse the `conventions` array
+2. Read `.sniper/memory/anti-patterns.yaml` — parse the `anti_patterns` array
+3. Read `.sniper/memory/decisions.yaml` — parse the `decisions` array
+4. Read `.sniper/memory/estimates.yaml` — parse calibration data
+5. Scan `.sniper/memory/retros/` for retro files — count them, find the latest
+
+If any file is missing or empty, treat it as an empty array/object.
+
+---
+
+## Step 3: Execute Operation
+
+### 3a: Summary (no flags)
+
+Display a formatted summary:
+
+```
+============================================
+  SNIPER Memory
+============================================
+
+  Conventions:    {N} confirmed, {M} candidates
+  Anti-Patterns:  {N} confirmed, {M} candidates
+  Decisions:      {N} active, {M} superseded
+
+  Estimation:
+    Velocity Factor:  {factor}
+    Sprints Analyzed: {count}
+
+  Retrospectives:
+    Total:     {count}
+    Latest:    Sprint {N} ({date})
+
+============================================
+```
+
+### 3b: List Operations (--conventions, --anti-patterns, --decisions)
+
+For each entry, display in a readable format:
+
+**Conventions:**
+```
+[conv-001] (confirmed) enforcement: both
+  Rule: All API routes use Zod validation middleware
+  Applies to: backend-engineer, api-designer
+  Source: review_gate (sprint-2-review, 2026-02-15)
+
+[conv-002] (candidate) enforcement: spawn_prompt
+  Rule: Use named exports for React components
+  Applies to: frontend-engineer
+  Source: retro (sprint-3-retro, 2026-02-18)
+```
+
+Similar format for anti-patterns (include severity) and decisions (include status).
+
+### 3c: Add Operations (--add)
+
+**Add convention:**
+1. Determine the next convention ID: find the highest `conv-XXX` number and increment
+2. Create the entry:
+   ```yaml
+   - id: conv-{NNN}
+     rule: "{provided rule}"
+     rationale: ""
+     source:
+       type: manual
+       ref: "user-added"
+       date: "{today ISO 8601}"
+     applies_to: []
+     enforcement: both
+     scope: project
+     status: confirmed
+     examples:
+       positive: ""
+       negative: ""
+   ```
+3. Ask the user which roles this applies to (suggest common roles: backend-engineer, frontend-engineer, architect, etc.)
+4. Append to `.sniper/memory/conventions.yaml`
+5. Confirm addition
+
+**Add anti-pattern:**
+Similar flow — next `ap-XXX` ID, ask for severity (high/medium/low), ask for fix_pattern, ask for applies_to roles.
+
+**Add decision:**
+Similar flow — next `dec-XXX` ID, require `--rationale` flag, ask for applies_to roles, set status to active.
+
+### 3d: Remove Operation (--remove {id})
+
+1. Determine which file the ID belongs to (conv- → conventions, ap- → anti-patterns, dec- → decisions)
+2. Find the entry by ID
+3. If not found, error: `Entry {id} not found in memory.`
+4. Show the entry and ask for confirmation: `Remove this entry? (y/n)`
+5. If confirmed, remove from the YAML array and rewrite the file
+6. Confirm removal
+
+### 3e: Promote Operation (--promote {id})
+
+1. Find the entry by ID (check all three files)
+2. If not found or already confirmed/active, error with appropriate message
+3. Change `status` from `candidate` to `confirmed` (for conventions/anti-patterns) or to `active` (for decisions)
+4. Rewrite the file
+5. Confirm promotion
+
+### 3f: Export Operation (--export)
+
+1. Create a combined export YAML:
+   ```yaml
+   exported_from: "{project.name}"
+   exported_at: "{today ISO 8601}"
+   version: "1.0"
+
+   conventions:
+     # Strip source.ref and project-specific fields
+     # Keep: rule, applies_to, enforcement, examples
+
+   anti_patterns:
+     # Keep: description, fix_pattern, severity, applies_to
+
+   decisions: []  # Decisions excluded by default (project-specific)
+   ```
+2. Write to `sniper-memory-export.yaml` in the project root
+3. Report: exported {N} conventions, {M} anti-patterns
+
+### 3g: Import Operation (--import {file})
+
+1. Read the specified file
+2. Validate it has the expected export format
+3. For each entry, check for duplicates by content similarity (exact rule/description match)
+4. Add non-duplicate entries with `source.type: imported`, `status: candidate`
+5. Report: imported {N} conventions, {M} anti-patterns, {K} skipped (duplicates)
+
+### 3h: Retro Operation (--retro)
+
+1. Read `.sniper/config.yaml` to get the current sprint number
+2. Read `.sniper/teams/retro.yaml` for the team definition
+3. Print instructions for running the retro:
+   ```
+   To run a sprint retrospective:
+
+   1. The retro team will analyze sprint {N} output
+   2. Findings will be written to .sniper/memory/retros/sprint-{N}-retro.yaml
+   3. High-confidence findings will be auto-added to memory
+
+   Compose the retro-analyst spawn prompt:
+     /sniper-compose --process retro-analyst --cognitive systems-thinker --name "Retro Analyst"
+
+   Then spawn the retro agent with context from:
+     - docs/stories/ (completed stories)
+     - docs/reviews/ (review gate results)
+     - .sniper/memory/ (existing memory for dedup)
+   ```
+
+---
+
+## Step 4: Display Results
+
+After executing the operation, display a final summary showing:
+- What changed (if anything)
+- Current memory counts
+- Any warnings or suggestions
+
+---
+
+## IMPORTANT RULES
+
+- Never delete memory files entirely — always preserve the YAML structure with empty arrays
+- When modifying YAML files, preserve comments and formatting where possible
+- Convention IDs use `conv-XXX`, anti-pattern IDs use `ap-XXX`, decision IDs use `dec-XXX` (zero-padded to 3 digits)
+- Always ask for confirmation before destructive operations (remove)
+- The `--retro` flag provides instructions but does not directly spawn agents (that requires team orchestration)
+- Memory files use standard YAML format — no managed section markers (those are for markdown templates)
+- If workspace memory exists (check config for `workspace.workspace_path`), mention it in the summary but don't modify it from this command

package/framework/commands/sniper-plan.md

@@ -24,19 +24,31 @@ Check that the following files exist and are non-empty:
 2. `docs/risks.md` -- Recommended but not blocking. If missing, print a warning.
 3. `docs/personas.md` -- Recommended but not blocking. If missing, print a warning.
 
-### 0c. Verify Phase State
+### 0c. Config Migration Check
 
-1. Read `state.current_phase` from config.yaml.
-2. **If `current_phase` is `discover` or artifacts exist:** Good -- discover is complete or was completed. Proceed.
-3. **If `current_phase` is `plan`:** Already in progress or was interrupted.
-   - Ask the user: "The plan phase appears to be in progress. Do you want to restart it? This will overwrite planning artifacts. (yes/no)"
-   - If no, STOP.
-4. **If `current_phase` is `solve` or `sprint`:** Project has progressed past planning.
-   - Ask the user: "The project is in the '{current_phase}' phase. Re-running plan will reset progress. Are you sure? (yes/no)"
-   - If no, STOP.
-5. **If `current_phase` is `null`:** No phase has run. Check if artifacts exist anyway (manual creation). If `docs/brief.md` exists, proceed with a warning. Otherwise STOP.
+1. Read `schema_version` from `.sniper/config.yaml`.
+2. If `schema_version` is absent or less than 2, run the v1→v2 migration as defined in the Config Reader Protocol. Write the updated config before proceeding.
 
-### 0d. Verify Framework Files
+### 0d. Verify Phase State
+
+1. Determine the current active phase: find the last entry in `state.phase_log` where `completed_at` is null.
+2. **If no active phase:** Good -- proceed. Re-running plan after sprint is normal iteration.
+3. **If active phase is `plan`:** Already in progress.
+   - Ask the user: "A plan phase is already in progress ({context}). Options: (a) Resume it (b) Start a new plan with a different context"
+4. **If active phase is something else:**
+   - Ask the user: "You have an active {phase} phase ({context}) that hasn't completed. Options: (a) Pause it and start planning (b) Complete {phase} first"
+
+### 0e. Amendment Detection
+
+1. Check if the target artifact files already exist and are non-empty:
+   - `docs/prd.md`
+   - `docs/architecture.md`
+   - `docs/ux-spec.md`
+   - `docs/security.md`
+2. **If ANY exist:** Enter **amendment mode**. Note which files exist and their current version numbers. Agents will be instructed to amend rather than create.
+3. **If NONE exist:** Normal create mode.
+
+### 0f. Verify Framework Files
 
 Check that these files exist:
 - `.sniper/teams/plan.yaml`
@@ -64,10 +76,10 @@ Report any missing files as warnings. Continue if the team YAML and key personas
 
 Edit `.sniper/config.yaml`:
 
-1. Set `state.current_phase: plan`
-2. Append to `state.phase_history`:
+1. Append to `state.phase_log`:
    ```yaml
    - phase: plan
+     context: "{from --context argument, or 'initial' for first run, or 'iteration-N' for re-runs}"
      started_at: "{current ISO timestamp}"
      completed_at: null
      approved_by: null
@@ -147,7 +159,7 @@ For each teammate, compose a spawn prompt by reading persona layer files and ass
    - **Description:** {project.description}
    - **Stack:** {summary of stack section}
 
-   ## Instructions
+   ## Instructions (Create Mode — when docs/prd.md does NOT exist)
    1. Read ALL the required reading files listed above.
    2. Read the template at `.sniper/templates/prd.md` for expected output format.
    3. Synthesize the discovery artifacts into a coherent PRD.
@@ -155,6 +167,15 @@ For each teammate, compose a spawn prompt by reading persona layer files and ass
    5. User stories must reference the personas from `docs/personas.md`.
    6. Write the complete output to `docs/prd.md`.
    7. When complete, message the team lead. Other teammates are waiting on your output.
+
+   ## Instructions (Amendment Mode — when docs/prd.md already exists)
+   1. Read the EXISTING `docs/prd.md` first. Note its current version number.
+   2. Read ALL the required reading files listed above.
+   3. AMEND the existing PRD: add new requirements, update changed sections, mark removed items as deprecated. Preserve content outside managed sections (<!-- sniper:managed --> markers).
+   4. Every P0 requirement MUST have testable acceptance criteria.
+   5. Increment the version number and add a changelog entry describing what changed.
+   6. Set Status back to "Draft".
+   7. When complete, message the team lead. Other teammates are waiting on your output.
    ```
 
 ### Teammate: architect
@@ -539,11 +560,12 @@ Update state with `approved_by: "rejected"` and STOP.
 
 Edit `.sniper/config.yaml`:
 
-1. Set `state.artifacts.prd: draft`
-2. Set `state.artifacts.architecture: draft`
-3. Set `state.artifacts.ux_spec: draft`
-4. Set `state.artifacts.security: draft` (if security doc was produced)
-5. Update the plan entry in `state.phase_history`:
+1. Update artifact tracking (increment version if amendment mode):
+   - Set `state.artifacts.prd.status: draft` and increment `state.artifacts.prd.version`
+   - Set `state.artifacts.architecture.status: draft` and increment `state.artifacts.architecture.version`
+   - Set `state.artifacts.ux_spec.status: draft` and increment `state.artifacts.ux_spec.version`
+   - Set `state.artifacts.security.status: draft` and increment `state.artifacts.security.version` (if produced)
+2. Update the plan entry in `state.phase_log`:
    - Set `completed_at: "{current ISO timestamp}"`
    - Set `approved_by: "human"` (since this is a strict gate)
 

package/framework/commands/sniper-review.md

@@ -7,16 +7,17 @@ You are executing the `/sniper-review` command. Your job is to evaluate the curr
 ## Step 0: Pre-Flight -- Determine Current Phase
 
 1. Read `.sniper/config.yaml`
-2. Extract `state.current_phase`
-3. If `current_phase` is `null`:
+2. Determine the current active phase: find the last entry in `state.phase_log` where `completed_at` is null.
+3. If no active phase (all completed or empty log):
    ```
-   ERROR: No active phase. The SNIPER lifecycle has not been started.
+   ERROR: No active phase. The SNIPER lifecycle has not been started or all phases are complete.
 
    Current state:
      Phase:   not started
      Sprint:  0
 
    To begin, run one of these phase commands:
+     /sniper-ingest    -- Ingest an existing codebase
      /sniper-discover  -- Start Phase 1: Discovery & Analysis
      /sniper-plan      -- Start Phase 2: Planning & Architecture
      /sniper-solve     -- Start Phase 3: Epic Sharding & Story Creation
@@ -24,7 +25,7 @@ You are executing the `/sniper-review` command. Your job is to evaluate the curr
    ```
    Then STOP.
 
-4. Store the current phase name. It must be one of: `discover`, `plan`, `solve`, `sprint`
+4. Store the current phase name. It must be one of: `ingest`, `discover`, `plan`, `solve`, `sprint`
 
 ---
 
@@ -34,6 +35,7 @@ Use this mapping to determine which checklist to load and what gate mode to enfo
 
 | Phase      | Checklist File                            | Config Gate Key       |
 |-----------|-------------------------------------------|-----------------------|
+| `ingest`   | `.sniper/checklists/ingest-review.md`     | `review_gates.after_ingest`  |
 | `discover` | `.sniper/checklists/discover-review.md`   | `review_gates.after_discover` |
 | `plan`     | `.sniper/checklists/plan-review.md`       | `review_gates.after_plan`     |
 | `solve`    | `.sniper/checklists/story-review.md`      | `review_gates.after_solve`    |
@@ -41,6 +43,7 @@ Use this mapping to determine which checklist to load and what gate mode to enfo
 
 1. Read the gate mode from `config.yaml` using the appropriate key
 2. Read the checklist file
+3. Check for domain pack checklists: scan `.sniper/packs/*/checklists/` for any `.md` files. If found, these will be evaluated as additional checklist items after the framework checklist (Step 3b).
 
 If the checklist file does not exist:
 ```
@@ -55,6 +58,13 @@ Then STOP.
 
 Based on the current phase, identify which artifact files need to be reviewed:
 
+### Phase: ingest
+| Artifact             | Expected Path            |
+|---------------------|-------------------------|
+| Project Brief        | `docs/brief.md`          |
+| System Architecture  | `docs/architecture.md`   |
+| Coding Conventions   | `docs/conventions.md`    |
+
 ### Phase: discover
 | Artifact             | Expected Path        |
 |---------------------|---------------------|
@@ -138,6 +148,72 @@ Be thorough but fair:
 
 ---
 
+## Step 3c: Memory Compliance Checks
+
+After evaluating the phase checklist, check project memory for compliance if memory files exist.
+
+### 3c-1: Load Memory
+
+Check if `.sniper/memory/` directory exists. If not, skip this step entirely.
+
+Read:
+- `.sniper/memory/conventions.yaml` — filter for entries with `enforcement: review_gate` or `enforcement: both`
+- `.sniper/memory/anti-patterns.yaml` — all entries
+- `.sniper/memory/decisions.yaml` — active entries only
+
+If workspace memory exists (check config), also load workspace-level files.
+
+### 3c-2: Convention Compliance
+
+For each convention with review gate enforcement:
+1. Read the convention's `rule` and `detection_hint` (if present)
+2. Examine the sprint output / artifacts being reviewed
+3. Check whether the convention was followed
+4. Report as PASS (compliant) or WARN (violation with details)
+
+### 3c-3: Anti-Pattern Scanning
+
+For each anti-pattern:
+1. Read the `detection_hint`
+2. If a detection hint is present, search the changed files for matches
+3. If matches found, report as WARN with file locations
+4. If no detection hint, skip automated detection (will be caught in manual review)
+
+### 3c-4: Decision Consistency
+
+For each active decision:
+1. Check if the sprint output contradicts the decision
+2. Example: if decision says "Use PostgreSQL" but new code imports MongoDB, flag it
+3. Report any contradictions
+
+### 3c-5: Report Memory Compliance
+
+Add a "Memory Compliance" section to the review output:
+
+```
+## Memory Compliance
+
+### Convention Checks
+PASS conv-001: Zod validation — all new routes use validation middleware
+WARN conv-003: Barrel exports — 2 new directories missing index.ts
+
+### Anti-Pattern Checks
+PASS ap-001: No direct DB queries in handlers — clean
+WARN ap-002: Silent error catch found in lib/webhook-delivery.ts:42
+
+### Decision Consistency
+PASS All decisions consistent
+
+### Summary
+{N} conventions checked, {M} violations
+{N} anti-patterns checked, {M} matches found
+{N} decisions checked, {M} contradictions
+```
+
+If there are violations, these count as review findings but do NOT block the gate by themselves (memory compliance is advisory unless the gate mode is strict AND the convention enforcement is review_gate).
+
+---
+
 ## Step 4: Present Results
 
 Print a formatted review report:
@@ -240,56 +316,44 @@ Based on the gate mode and results, take the appropriate action:
 When a phase is approved for advancement:
 
 1. Read the current `.sniper/config.yaml`
-2. Determine the next phase using this progression:
-   - `discover` -> `plan`
-   - `plan` -> `solve`
-   - `solve` -> `sprint`
-   - `sprint` -> `sprint` (remains in sprint phase, increment sprint number)
-
-3. Update the `state` section:
+2. Find the active phase_log entry (the one where `completed_at` is null) and update it:
    ```yaml
-   state:
-     current_phase: {next_phase}
-     phase_history:
-       - phase: {completed_phase}
-         started_at: {start_date_if_known_or_today}
-         completed_at: {today's date in YYYY-MM-DD format}
-         approved_by: {human or auto}
-         gate_mode: {strict|flexible|auto}
-         pass_count: {number}
-         warn_count: {number}
-         fail_count: {number}
-       # ... (preserve existing history entries)
-     current_sprint: {increment by 1 if completing a sprint, else keep}
-     artifacts:
-       # Update artifact statuses based on what was reviewed:
-       # If all items for an artifact passed -> "approved"
-       # If any items warn but no fails -> "draft"
-       # If the artifact exists but has fails -> "draft"
-       # Keep existing values for artifacts not reviewed in this phase
+   completed_at: "{current ISO timestamp}"
+   approved_by: "{human or auto-flexible or auto}"
    ```
 
-4. Write the updated config back to `.sniper/config.yaml`
+3. Update artifact statuses based on what was reviewed:
+   - If all items for an artifact passed -> set status to `approved`
+   - If any items warn but no fails -> keep status as `draft`
+   - If the artifact exists but has fails -> keep status as `draft`
+   - Keep existing values for artifacts not reviewed in this phase
+
+4. If the completed phase is `sprint`, increment `state.current_sprint` by 1.
 
-5. Print the advancement confirmation:
+5. Write the updated config back to `.sniper/config.yaml`
+
+6. Suggest the next command based on what was just completed:
+
+   | Completed Phase | Suggested Next Commands |
+   |----------------|------------------------|
+   | `ingest`        | `/sniper-feature`, `/sniper-discover`, `/sniper-audit` |
+   | `discover`      | `/sniper-plan` |
+   | `plan`          | `/sniper-solve` |
+   | `solve`         | `/sniper-sprint` |
+   | `sprint`        | `/sniper-sprint` (next sprint), `/sniper-review` |
+
+7. Print the completion confirmation:
    ```
    ============================================
-     Phase Advanced
+     Phase Review Complete
    ============================================
 
-     Completed: {phase}
-     Advanced to: {next_phase}
+     Completed: {phase} ({context})
      Artifacts updated in config.yaml
 
-     Next step: Run {next_command}
+     Suggested next: {next_command}
    ```
 
-   Where `next_command` maps to:
-   - `plan` -> `/sniper-plan`
-   - `solve` -> `/sniper-solve`
-   - `sprint` -> `/sniper-sprint`
-   - staying in `sprint` -> `/sniper-sprint` (next sprint cycle)
-
 ---
 
 ## IMPORTANT RULES

package/framework/commands/sniper-solve.md

@@ -35,16 +35,30 @@ Check that the following files exist and are non-empty. Read each file to verify
    - If no, STOP.
    - If yes, proceed with a note in the output.
 
-### 0d. Verify Phase State
+### 0d. Config Migration Check
 
-1. Read `state.current_phase`.
-2. **If `current_phase` is `plan`:** Good -- planning is done and we are advancing. Proceed.
-3. **If `current_phase` is `solve`:** Already in progress or was interrupted.
-   - Ask the user: "The solve phase appears to be in progress. Do you want to restart? This will overwrite existing epics and stories. (yes/no)"
-   - If no, STOP.
-4. **If `current_phase` is `sprint`:** Project has advanced past this phase.
-   - Ask the user: "The project is in sprint phase. Re-running solve will recreate epics and stories. Are you sure? (yes/no)"
-   - If no, STOP.
+1. Read `schema_version` from `.sniper/config.yaml`.
+2. If `schema_version` is absent or less than 2, run the v1→v2 migration. Write the updated config before proceeding.
+
+### 0e. Verify Phase State
+
+1. Determine the current active phase from `state.phase_log`.
+2. **If no active phase:** Good -- proceed.
+3. **If active phase is `solve`:** Already in progress.
+   - Ask the user: "A solve phase is already in progress ({context}). Options: (a) Resume it (b) Start a new solve with a different context"
+4. **If active phase is something else:**
+   - Ask the user: "You have an active {phase} phase ({context}). Options: (a) Pause it and start solving (b) Complete {phase} first"
+
+### 0f. Amendment Detection for Stories
+
+1. Check if `docs/epics/` and `docs/stories/` directories exist and contain files.
+2. **If story files exist:**
+   - Scan each story file for a `> **Status:** Complete (Sprint {N})` marker.
+   - **Completed stories** are NEVER overwritten. They are preserved as-is.
+   - **Draft stories** (no completion marker) can be amended: updated acceptance criteria, refreshed embedded context.
+   - **New requirements** (from amended PRD) generate new stories with the next available story number.
+   - **Removed requirements** — stories for removed PRD items are marked `> **Status:** Deprecated` rather than deleted.
+3. **If no story files exist:** Normal create mode.
 
 ---
 
@@ -52,10 +66,10 @@ Check that the following files exist and are non-empty. Read each file to verify
 
 Edit `.sniper/config.yaml`:
 
-1. Set `state.current_phase: solve`
-2. Append to `state.phase_history`:
+1. Append to `state.phase_log`:
    ```yaml
    - phase: solve
+     context: "{from --context argument, or 'initial' for first run, or 'iteration-N' for re-runs}"
      started_at: "{current ISO timestamp}"
      completed_at: null
      approved_by: null
@@ -293,9 +307,10 @@ If the self-review identified any issues:
 
 Edit `.sniper/config.yaml`:
 
-1. Set `state.artifacts.epics: draft`
-2. Set `state.artifacts.stories: draft`
-3. Update the solve entry in `state.phase_history`:
+1. Update artifact tracking:
+   - Set `state.artifacts.epics.status: draft` and increment `state.artifacts.epics.version`
+   - Set `state.artifacts.stories.status: draft` and increment `state.artifacts.stories.version`
+2. Update the solve entry in `state.phase_log`:
    - Set `completed_at: "{current ISO timestamp}"`
    - Set `approved_by: "auto-flexible"` (this is a flexible gate)
 
@@ -359,6 +374,24 @@ Print a formatted summary:
 
 ---
 
+## Feature-Scoped Mode
+
+If `$ARGUMENTS` contains `--feature SNPR-{XXXX}`:
+
+1. **Skip Steps 0b and 0c** (no need to check for main PRD or plan approval).
+2. **Step 3:** Instead of reading main PRD/architecture/UX-spec, read:
+   - `docs/features/SNPR-{XXXX}/spec.md` (replaces PRD as primary input)
+   - `docs/features/SNPR-{XXXX}/arch-delta.md` (replaces architecture for feature scope)
+   - `docs/architecture.md` (for broader system context)
+   - `docs/conventions.md` (if exists, for coding patterns)
+3. **Step 5:** Create stories in `docs/features/SNPR-{XXXX}/stories/` instead of `docs/stories/`.
+4. **Step 6:** Skip epic creation. Feature stories don't need epics (the feature IS the epic).
+5. **Step 7:** Number stories as S01, S02, etc. within the feature directory. Target 3-8 stories.
+6. **Step 7 context embedding:** Embed context from the feature spec and arch-delta, NOT the main PRD.
+7. **Step 11:** Update `state.features[].stories_total` with the count.
+
+---
+
 ## IMPORTANT RULES
 
 - This phase runs as a SINGLE AGENT. Do NOT create a team or spawn teammates.