@runecraft/grimoire 1.0.0

package/skills/spec-driven/references/specify.md

@@ -0,0 +1,210 @@
+# Specify
+
+**Goal**: Capture WHAT to build with testable, traceable requirements.
+
+If the feature has ambiguous gray areas (multiple valid approaches for user-facing behavior), the agent will automatically trigger the [discuss gray areas](discuss.md) process within this phase. For clear, well-defined features, it goes straight to the next phase.
+
+## Implicit-Requirement Dimensions
+
+The canonical rubric for requirements that are easy to miss. Referenced by [discuss.md](discuss.md) — defined here, not duplicated.
+
+| Dimension | What to cover |
+| --------- | ------------- |
+| Input validation & bounds | Limits, formats, sanitization |
+| Failure / partial-failure states | Timeouts, partial saves, rollbacks |
+| Idempotency / retry / duplicate handling | Safe retries, dedup keys |
+| Auth boundaries & rate limits | Who can call what, throttle rules |
+| Concurrency / ordering | Race conditions, ordering guarantees |
+| Data lifecycle / expiry | TTL, archival, deletion |
+| Observability | Logging, metrics, tracing hooks |
+| External-dependency failure | Circuit breakers, fallbacks |
+| State-transition integrity | Valid transitions, guards |
+
+---
+
+## Process
+
+### 1. Clarify Requirements
+
+**Load confirmed lessons first:** Before clarifying, load the project's confirmed lessons so past verification failures shape this spec instead of repeating. Run `python3 scripts/lessons.py list --status confirmed` (optionally `--scope [area]` or `--query [term]` for the area this feature touches) and apply what comes back as guidance. Load only `confirmed` — never `candidate` or `quarantined`. If no store exists yet or no code tool is available, skip silently. See [lessons.md](lessons.md).
+
+**Lightweight context scan first (Knowledge Verification Chain Step 1):** Before asking questions, briefly scan existing code, patterns, and neighboring features relevant to this feature. Use what you find to ground your clarifying questions in reality — not to constrain the spec to current implementation. Keep it lightweight (stay within the <40k token budget; reuse the chain, no new machinery). The spec captures WHAT is needed, not only what exists.
+
+You are a thinking partner, not an interviewer. Start open — let the user dump their mental model. Follow the energy: whatever they emphasize, dig into that.
+
+Ask conversationally (not as a checklist):
+
+- "What problem are you solving?"
+- "Who is the user and what's their pain?"
+- "What does success look like?"
+
+If needed:
+
+- "What are the constraints (time, tech, resources)?"
+- "What is explicitly out of scope?"
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how? Make the abstract concrete: "Walk me through using this." "What does that actually look like?"
+
+**Know when to stop — then run the dimensions sweep.** When you understand what they're building, why, who it's for, and what done looks like, run a closing **implicit-requirement dimensions sweep** before offering to proceed:
+
+- **Large / Complex:** Cover every dimension above — each must resolve to a requirement OR an explicit `N/A because [reason]`. No blank entries allowed.
+- **Medium:** Cover only dimensions obviously present for this feature's domain; collapse the rest to a single `remaining dimensions N/A for this scope`.
+- **Small:** Skip the sweep entirely.
+
+The `N/A because...` escape is mandatory — it prevents inventing requirements to fill the checklist. Bound the sweep to THIS feature's scope; never add requirements outside the feature boundary.
+
+### 2. Capture User Stories with Priorities
+
+**P1 = MVP** (must ship), **P2** (should have), **P3** (nice to have)
+
+Each story MUST be **independently testable** - you can implement and demo just that story.
+
+### 3. Write Acceptance Criteria
+
+Use **WHEN/THEN/SHALL** format - it's precise and testable:
+
+- WHEN [event/action] THEN [system] SHALL [response/behavior]
+
+### 4. Requirement Closure Gate (before confirm)
+
+Before presenting the spec for confirmation, run the three checks below. The spec is not presentable for confirmation until every item is resolved or assumption-logged — this is the guarantee that no requirement leaves the spec silently unclear.
+
+**Scope-tiered:** Large/Complex = full gate; Medium = resolve obvious ambiguities, log the rest as assumptions; Small = skip entirely (consistent with skipping the sweep).
+
+1. **Unambiguity + precision (hard).** Every AC must (a) have a single interpretation and (b) define a precise, spec-defined expected outcome. Any AC that fails either check: resolve with the user, split it, or log it as an explicit assumption with the chosen interpretation and rationale. No AC proceeds readable two ways or with an undefined outcome.
+
+2. **Open-questions / assumptions closure.** Enumerate every unresolved decision that surfaced during clarification. Each must be either (a) resolved with the user OR (b) recorded as an **assumption** (chosen default + rationale) in the spec's Assumptions & Open Questions section. Nothing proceeds unmarked.
+
+3. **Declined gray areas become assumptions.** Any gray area the user declined to discuss or that went undiscussed is written to the spec's Assumptions & Open Questions section (agent's chosen default + rationale) — never silently dropped. See [discuss.md](discuss.md).
+
+Fix inline. This gate is bounded to THIS feature's stated dimensions and actual behavior — never to "anything imaginable." The Out of Scope table and anti-scope-creep rules remain the counterweights: the gate clarifies existing requirements, it never invents new ones.
+
+---
+
+## Template: `.specs/features/[feature]/spec.md`
+
+```markdown
+# [Feature Name] Specification
+
+## Problem Statement
+
+[Describe the problem in 2-3 sentences. What pain point are we solving? Why now?]
+
+## Goals
+
+- [ ] [Primary goal with measurable outcome]
+- [ ] [Secondary goal with measurable outcome]
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature     | Reason         |
+| ----------- | -------------- |
+| [Feature X] | [Why excluded] |
+| [Feature Y] | [Why excluded] |
+
+---
+
+## Assumptions & Open Questions
+
+Every ambiguity is resolved or recorded here — nothing is left silently unclear.
+
+| Assumption / decision | Chosen default  | Rationale | Confirmed? |
+| --------------------- | --------------- | --------- | ---------- |
+| [ambiguity]           | [what we'll do] | [why]     | [y/n]      |
+
+**Open questions:** none — all resolved or logged above (required before the spec is confirmed).
+
+---
+
+## User Stories
+
+### P1: [Story Title] ⭐ MVP
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P1**: [Why this is critical for MVP]
+
+**Acceptance Criteria**:
+
+1. WHEN [user action/event] THEN system SHALL [expected behavior]
+2. WHEN [user action/event] THEN system SHALL [expected behavior]
+3. WHEN [edge case] THEN system SHALL [graceful handling]
+
+**Independent Test**: [How to verify this story works alone - e.g., "Can demo by doing X and seeing Y"]
+
+---
+
+### P2: [Story Title]
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P2**: [Why this isn't MVP but important]
+
+**Acceptance Criteria**:
+
+1. WHEN [event] THEN system SHALL [behavior]
+2. WHEN [event] THEN system SHALL [behavior]
+
+**Independent Test**: [How to verify]
+
+---
+
+### P3: [Story Title]
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P3**: [Why this is nice-to-have]
+
+**Acceptance Criteria**:
+
+1. WHEN [event] THEN system SHALL [behavior]
+
+---
+
+## Edge Cases
+
+- WHEN [boundary condition] THEN system SHALL [behavior]
+- WHEN [error scenario] THEN system SHALL [graceful handling]
+- WHEN [unexpected input] THEN system SHALL [validation response]
+
+---
+
+## Requirement Traceability
+
+Each requirement gets a unique ID for tracking across design, tasks, and validation.
+
+| Requirement ID | Story       | Phase  | Status  |
+| -------------- | ----------- | ------ | ------- |
+| [FEAT]-01      | P1: [Story] | Design | Pending |
+| [FEAT]-02      | P1: [Story] | Design | Pending |
+| [FEAT]-03      | P2: [Story] | -      | Pending |
+
+**ID format:** `[CATEGORY]-[NUMBER]` (e.g., `AUTH-01`, `CART-03`, `NOTIF-02`)
+
+**Status values:** Pending → In Design → In Tasks → Implementing → Verified
+
+**Coverage:** X total, Y mapped to tasks, Z unmapped ⚠️
+
+---
+
+## Success Criteria
+
+How we know the feature is successful:
+
+- [ ] [Measurable outcome - e.g., "User can complete X in < 2 minutes"]
+- [ ] [Measurable outcome - e.g., "Zero errors in Y scenario"]
+```
+
+---
+
+## Tips
+
+- **P1 = Vertical Slice** — A complete, demo-able feature, not just backend or frontend
+- **WHEN/THEN is code** — If you can't write it as a test, rewrite it
+- **Requirement IDs are mandatory** — Every story maps to trackable IDs
+- **Edge cases matter** — What breaks? What's empty? What's huge?
+- **Out of Scope prevents creep** — If it's not here, it doesn't get built
+- **Closure gate before confirm** — Three checks: unambiguity + precision, open-questions/assumptions closure, declined gray areas logged; scope-tiered; bounded to stated dimensions; never invents requirements
+- **Confirm after the gate passes** — Present the spec for user confirmation only after the closure gate passes (no unresolved-and-unmarked items remain); user approves spec before moving to discuss phase

package/skills/spec-driven/references/sub-agents.md

@@ -0,0 +1,96 @@
+# Sub-Agent Delegation
+
+Full mechanics for phase workers and the Verifier sub-agent used during Execute.
+
+## Phase Workers
+
+**Trigger:** When the execution plan has **more than 3 phases**, offer the user per-phase sub-agents before starting Execute. For 3 or fewer phases, execute inline in the main window — no sub-agents spawned.
+
+**Offer-then-confirm (never auto-spawn):**
+
+> "This feature has [N] phases. I can run one sub-agent per phase — each worker executes its full phase in order, reports a compact summary, and the orchestrator advances. This keeps the main window lean. Want to proceed that way?"
+
+The user must explicitly accept. If they decline (or if the feature has ≤3 phases), execute inline.
+
+**Execution model — one worker per phase, sequential:**
+
+```
+Phase 1 ──→ Phase Worker 1 ──→ compact summary ──→ orchestrator updates tasks.md
+Phase 2 ──→ Phase Worker 2 ──→ compact summary ──→ orchestrator updates tasks.md
+...
+```
+
+**What a phase worker receives:**
+
+- The phase's task definitions (from `tasks.md`)
+- The Test Coverage Matrix and Gate Check Commands (from `tasks.md`)
+- `references/coding-principles.md`
+- Relevant `spec.md` and `design.md` context for the feature (not all specs)
+
+**What a phase worker does:**
+
+Executes ALL tasks in its assigned phase **in order**, following the `implement.md` cycle for each task (implement → gate → atomic commit). It does NOT spawn further sub-agents for individual tasks — `[P]` marks tasks with no inter-task dependency (order-free within the phase) and is informational only; it is not a spawn directive. After completing all tasks in the phase, the worker reports a **compact summary** to the orchestrator:
+
+```
+Phase [N] complete:
+- Tasks done: [list with commit hashes]
+- Tests: [N passed, 0 failed]
+- Deviations/blockers: [none | description]
+```
+
+No raw logs, no full test output — only the above fields keep the main context clean.
+
+**No intra-phase nesting:** Phase workers execute their tasks themselves. They never spawn sub-sub-agents. Intra-phase parallelism is explicitly dropped for simplicity.
+
+**The orchestrating agent's role during Execute:**
+
+1. Assess phase count — offer sub-agents if >3 phases and user accepts
+2. Dispatch the next phase to a worker (or execute inline if not using sub-agents)
+3. Receive the compact summary
+4. Update `tasks.md` with results
+5. If all tasks in the summary show complete: proceed to the next phase
+6. If a task failed: the worker has already stopped; decide fix/escalate before dispatching the next phase
+
+**Failure handling:** If a task in a phase fails (gate does not pass, blocker hit), the worker stops and includes the failure in its summary. The next phase does not start until the current phase's summary shows all tasks complete. The orchestrator decides: fix and re-run, or escalate to the user.
+
+**Context sizing signal:** If a single phase's task list would likely push the worker's context beyond ~40k tokens, that signals the phase should be split into smaller phases — use the granularity guidance in `references/tasks.md`.
+
+---
+
+## Verifier Sub-Agent
+
+**Always-on, never prompted — one per feature completion.** The Verifier is a separate role from the phase worker. It runs once — after the last task of the feature is committed — as an independent quality gate, dispatched automatically by the orchestrator. It is **not** gated behind the >3-phase offer; it always runs. Do NOT ask the user whether to run validation; it is mandatory.
+
+**Author ≠ verifier:** The agent (or phase worker) that wrote the code and tests is the author. The Verifier is a fresh sub-agent dispatched by the orchestrator after the final commit. It does not inherit the author's context, mental model, or assumptions. This separation is what makes the gate trustworthy.
+
+**What the Verifier receives:**
+- `spec.md` for the feature (ACs = source of truth)
+- The git diff surface for the feature (scoped to the feature branch or commit range)
+- The test files in scope
+- `references/validate.md` as its operating checklist
+
+**What the Verifier does (full process in `validate.md`):**
+1. **Spec-anchored coverage check** — re-derives coverage evidence-or-zero: every AC traced to `file:line` + assertion expression. For each covered criterion, confirms the test's asserted value matches the **spec-defined expected outcome** (not just that an assertion exists). Where the spec does not define a precise outcome, flags a **spec-precision gap** rather than passing silently.
+2. **Discrimination sensor** — injects a small behavior-level fault (flip a condition, change a return value, off-by-one, remove a required side effect) in a **scratch/throwaway state** (git stash or temp copy), runs the relevant tests, confirms they FAIL (kill the mutant), then discards the mutation. Tiered by risk: lightweight (1–3 mutations) for standard features; expanded (≥5 mutations or full mutation tooling) for P0/critical paths. Surviving mutants become fix tasks.
+3. Applies the **payload/conjunction rule**: checks payload fields are asserted on value/state, not just that the call occurred.
+4. **Writes the persisted report** to `.specs/features/[feature]/validation.md` — PASS/FAIL, per-AC evidence (`file:line` + assertion + spec outcome), sensor result (killed/survived per mutation), gate exit results, diff/commit range.
+5. **Returns a compact verdict in chat** to the orchestrator.
+6. Does **NOT** write, modify, or fix any code or tests — the real working tree is never mutated (sensor mutations run in scratch state only).
+
+**What the Verifier reports back (compact chat format):**
+```
+## Validation: [feature name] — [PASS ✅ | FAIL ❌]
+
+**Spec-anchored check**: [N/N ACs matched spec outcome | M spec-precision gaps flagged]
+**Gate**: [X passed, 0 failed]
+**Sensor**: [N mutations injected, N killed, N survived]
+**Report**: `.specs/features/[feature]/validation.md`
+
+**Ranked gaps** (if FAIL):
+1. [Gap description] — [AC or criterion] — [file:line or "no evidence"]
+2. ...
+```
+
+**Failure handling:** The orchestrator routes the ranked gaps to an implementer as fix tasks, then re-dispatches the Verifier. This fix→re-verify loop is bounded to a maximum of **3 iterations**. If gaps remain after 3 iterations, escalate to the user.
+
+**Standalone fallback:** When running without sub-agents (a single agent executing the full feature), run `validate.md` as an independent fresh-eyes pass — re-read `spec.md` and the diff from scratch, apply evidence-or-zero, run the spec-anchored check and discrimination sensor, write the report file, and report PASS/FAIL before marking the feature done.