End-to-end feature development lifecycle for Grimoire.

Arguments: $ARGUMENTS

This is a guided, multi-phase workflow. Each phase produces a deliverable and **pauses for user review** before proceeding. Do NOT advance to the next phase without explicit user approval.

---

## Phase 1: Brainstorm & Threat Analysis

**Goal**: Understand the feature deeply, map its security surface, and identify attack vectors *before* any design work.

1. **Understand the request**: Parse the feature description from the arguments. Ask clarifying questions if the intent is ambiguous — don't guess.

2. **Research the codebase**: Read all code and docs relevant to the feature area. Understand:
   - What exists today that this feature touches
   - What state transitions, data flows, and trust boundaries are involved
   - How similar features in the codebase were designed (study existing specs for patterns)

3. **Map the security surface**: For this feature, enumerate:
   - **New trust boundaries**: Does this introduce new inputs, outputs, IPC messages, file I/O, or network calls?
   - **Data flow**: Where do secrets or sensitive data flow? Draw the path from entry to exit.
   - **State changes**: Does this affect the service state machine? Add new states or transitions?
   - **Process model**: Does this change who can trigger what? New CLI commands? New IPC methods?

4. **Threat analysis**: Using the project's threat model (`docs/security.md`), analyze:
   - **Attack vectors**: How could an attacker abuse this feature? Consider:
     - Same-user RCE (compromised npm package, browser exploit, malicious extension)
     - Malformed input (IPC, CLI args, server responses, config)
     - Race conditions (TOCTOU on security checks, concurrent state mutations)
     - Information leaks (error messages, logs, timing, file permissions)
     - Privilege escalation (bypassing approval, accessing other users' data)
   - **Existing mitigations**: Which current protections (socket perms, scoped approval, peer UID check) apply?
   - **New mitigations needed**: What defenses does this feature require?
   - **Residual risk**: What attacks remain possible even with mitigations? Are they acceptable?

5. **Present findings** to the user as a structured brief:

Feature:

What it does

<1-2 sentences>

Touches

<crates, files, state transitions affected>

Attack Vectors

### Proposed Mitigations ### Residual Risk ### Open Questions ```

STOP. Wait for user feedback. The user may refine the scope, reject attack vectors, add constraints, or ask to explore alternatives. Iterate until they approve moving to Phase 2.

Phase 2: Spec

Goal: Produce a complete ADR spec that captures the design and security decisions from Phase 1.

Read docs/development.md for the full spec template and format conventions.
Determine the next spec number from specs/.

Write specs/NNN-<slug>.md following the ADR template:

# ADR NNN: <Title>

## Status
Proposed

## Context
Why this change is needed. Problem statement, constraints, prior art.
What exists today that this feature touches or changes.

## Decision
Concrete design — specific enough that implementation is mechanical.
Include: data structures, protocol changes, state machine changes,
code sketches for non-obvious parts, config changes, migration path.

## Consequences

### Positive
What this enables. Why the trade-offs are worth it.

### Negative
Costs, complexity added, limitations, things that get harder.

## Security Analysis

### Threat Model Impact
How this changes the threat model in docs/security.md.
New trust boundaries, attack surface, changed assumptions.

### Attack Vectors
| # | Vector | Severity | Description |
|---|--------|----------|-------------|
| 1 | ... | Critical/High/Medium/Low | ... |

### Planned Mitigations
| Vector | Mitigation | Mechanism |
|--------|-----------|-----------|
| 1 | ... | (code-level detail: where and how) |

### Residual Risk
Attacks that remain possible and why they're acceptable.

### Implementation Security Notes
_Filled during finalization (Phase 6). Leave empty._

The Security Analysis section migrates the full threat analysis from Phase 1. Every attack vector from the brainstorm must appear in the table. Every mitigation must be concrete enough to verify during the Phase 5 audit.
Cross-reference: if this spec supersedes or modifies an existing one, note it explicitly.

STOP. Wait for user review of the spec. The user may request design changes, challenge security decisions, or ask for alternatives. The spec is mutable at this stage — iterate freely. Do not proceed until the user explicitly approves.

Phase 3: Implement

Goal: Translate the approved spec into code, following the spec exactly.

Plan first: Before writing any code, present the implementation plan:
- Files to create or modify (with the specific changes for each)
- New dependencies (if any) and their security posture
- Test plan: what tests are needed and what they cover
- Order of operations
Wait for user approval of the plan.
Implement following project principles:
- Minimal surface area — only what the spec calls for
- No .unwrap() on fallible operations in non-test code
- No unsafe without spec-level justification + // SAFETY: comment
- deny_unknown_fields on new protocol/serde types
- Secrets never logged, never in error messages, never held longer than needed
- Error types via thiserror, propagated with ?
Quality gate: Run and report results:
- cargo fmt --all -- --check
- cargo clippy --workspace -- -D warnings
- cargo test --workspace