@codename_inc/spectre 5.0.0 → 5.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codename_inc/spectre",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "type": "module",
   "bin": {
     "spectre": "./bin/spectre.js"

package/plugins/spectre/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "spectre",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "Agentic coding workflow with session memory. spectre guides you through Scope, Plan, Execute, Clean, Test, Rebase, and Extract phases."
 }

package/plugins/spectre/skills/code_review/SKILL.md

@@ -171,6 +171,8 @@ Optional user input to seed this workflow.
 - **MEDIUM**: Quality improvements, test coverage, configuration, performance (non-critical)
 - **LOW**: Documentation, polish, cleanup
 
+**Evidence rule:** Every CRITICAL or HIGH finding MUST include (1) `file:line` and (2) a reproducible failure scenario or exploit path describing observable behavior. Findings without an evidence chain are auto-downgraded one severity level. "Could potentially" is not evidence.
+
 **Perform comprehensive analysis covering all aspects:**
 
 ### 🔧 Foundation & Correctness

package/plugins/spectre/skills/create_plan/SKILL.md

@@ -29,8 +29,9 @@ Treat the current command arguments as this workflow's input. When invoked from
   - **If** found with comprehensive analysis → use existing research; skip to Step 3.
   - **Else** → proceed with new research below.
 - **Action** — AutomatedResearch: Spawn parallel research agents for comprehensive analysis.
-  - Use `codebase-locator` to find all files related to feature area.
-  - Dispatch multiple parallel `codebase-analyzer` subagents to understand current implementation patterns. Pay particular attention to how and where data is accessed that will be needed for this feature.
+  - Use `@finder` to find all files related to feature area.
+  - Dispatch multiple parallel `@analyst` subagents to understand current implementation patterns. Pay particular attention to how and where data is accessed that will be needed for this feature.
+  - Use `@patterns` to surface canonical reference implementations already in the codebase — these become "follow this file" anchors in the plan.
   - Wait for ALL agents to complete before proceeding.
   - Read ALL identified files into context.
 - **Action** — TraceCodePaths: Trace through relevant execution paths.
@@ -97,17 +98,28 @@ Dynamically generate up to 10 technical questions based on research findings. **
 
 - **Action** — DesignTechnicalApproach: Create the implementation plan.
 
-  **STANDARD** depth — Focused plan for contained changes. Include the sections that matter for THIS feature. Typical sections: Overview, Desired End State, Out of Scope, Technical Approach.
-
-  **COMPREHENSIVE** depth — Full technical design for complex/risky changes. Consider all of the following, but only include sections relevant to the feature: Overview, Current State (with file:line refs), Desired End State, Out of Scope, Technical Approach, System Architecture, Implementation Phases, Component/Data Architecture, API Design, Testing Strategy.
-
-  Use your judgment — the goal is a plan that gives a developer everything they need to implement, not a template with empty sections.
-
-- **Action** — AppendCriticalFiles: End the plan with a "Critical Files for Implementation" section.
-
-  - List 3-7 files most critical for implementing this plan.
-  - Format: `path/to/file.ts` — brief reason (e.g., "Core logic to modify", "Pattern to follow", "Interface to implement").
-  - These should be specific files discovered during research, not guesses.
+  Every plan, regardless of depth, MUST include these seven sections. They are the verification spine — without them, downstream agents cannot self-check their work.
+
+  **Required for both STANDARD and COMPREHENSIVE:**
+  1. **Overview** — 1–2 paragraphs: what problem, what shape the solution takes, why this approach.
+  2. **Technical Approach** — How the change actually lands: components touched, data flow, key decisions with rationale. Reference existing patterns from `@patterns` research by file:line (e.g., "follow the shape of `src/widgets/HotDogWidget.ts:42` for the registration step").
+  3. **Critical Files for Implementation** — 3–7 specific files from research. Format: `path/to/file.ts` — *reason* (Core logic to modify / Pattern to follow / Interface to implement / Test to extend). No guesses — only files surfaced during Step 1 research.
+  4. **External Dependencies — Verify Before Implementation** — Every third-party package required, with exact version and a one-line existence check. Format: `package@1.2.3 — verify: npm view package@1.2.3` (or pip equivalent). Required even if "no new packages" (write that explicitly). This is the slopsquatting fence: ~20% of AI-suggested packages don't exist; we catch that here, not in production.
+  5. **Verification — How We Know This Works** — For each major change in Technical Approach, 1–3 falsifiable signals: a test name, an observable behavior, or a state/file condition. Prose like "the feature works" is not acceptable — it must be checkable. Format: `<change> → verifies by: <test name | observable behavior | state condition>`. These become acceptance criteria in `create_tasks` downstream.
+  6. **Out-of-Bounds — DO NOT add** — 4–8 concrete things the implementation must NOT add, even if "best practice." Examples: rate limiting, retry/backoff, caching layer, optimistic UI, soft-delete, telemetry events, feature flags, admin UI. This is the YAGNI fence against familiar-shape bias (agents reproduce mature-system patterns unprompted). Be specific to this feature, not generic.
+  7. **Risks & Filled Assumptions** — Two short subsections:
+     - *Risks*: what could go wrong (e.g., concurrent write race, migration ordering, third-party rate limit). Each with a one-line mitigation or "accept and monitor."
+     - *Filled Assumptions*: things the plan defaulted because the spec didn't say (e.g., "Assumed Postgres; spec didn't specify DB." "Assumed retry count = 0; spec didn't mention failure modes."). Reviewer-visible by design — these are the silent decisions that bite at execution.
+
+  **COMPREHENSIVE additionally requires:**
+  8. **Current State** — How the affected code path works today, with file:line refs. Anchored to research findings.
+  9. **Implementation Phases** — Ordered phases, each with its own Verification subsection (Phase N succeeds when …). Phases must be sequenced by dependency, not by file. Migration phases come before consumer phases.
+  10. **Component / Data Architecture** — Where data is created, mutated, and read. Schema deltas if any.
+  11. **API Design** — Endpoint signatures, request/response shapes, error contracts. Required if any external or internal API surface changes.
+  12. **Migration Plan** — Required if any data-layer change. Up + down migration sketch, backfill strategy, rollback plan.
+  13. **Testing Strategy** — What test types cover what (unit / integration / e2e), where new tests live, what's deferred to the post-feature coverage task.
+
+  Use your judgment on section length, not on inclusion. If a required section is genuinely N/A for this feature, write the section header followed by *"N/A — <one-line reason>"*. Empty section headers are not acceptable; absent section headers are not acceptable.
 
 - **Action** — DocumentPlan: Save to `{OUT_DIR}/specs/plan.md` (use scoped name if exists)
 

package/plugins/spectre/skills/create_tasks/SKILL.md

@@ -129,12 +129,46 @@ Read completely (no limits):
   - This section helps the user understand how the work integrates with the product before diving into tasks
 
 ### Task Hierarchy (4 Levels)
-- **📦 Phase**: Organizational header (no checkbox) — groups related parent tasks
-- **📋 Parent Task**: Cohesive deliverable (small-medium scope) — one component/file
-- **✓ Sub-task**: Atomic work (single focused change) — single action, 2-3 acceptance criteria
-- **✓ Acceptance Criteria**: Verifiable outcomes (not implementation steps)
+- **Phase**: Organizational header (no checkbox) — groups related parent tasks
+- **Parent Task**: Cohesive deliverable (small-medium scope) — one component/file
+- **Sub-task**: Atomic work (single focused change) — single action, 2-3 acceptance criteria
+- **Acceptance Criteria**: Executable, verifiable outcomes (see Acceptance Criteria Types below)
 
-**Numbering**: Phase 1 → Parent 1.1, 1.2 → Sub-tasks 1.1.1, 1.1.2 → Criteria ✓
+**Numbering**: Phase 1 → Parent 1.1, 1.2 → Sub-tasks 1.1.1, 1.1.2 → Criteria
+
+### Right-Sized for AI Execution
+
+Published data on AI agent execution (Cognition's Devin reviews, Anthropic's Claude Code guidance) converges on a bounded sweet spot: each sub-task should be completable in roughly the time a junior would take in a 4–8 hour window — not a multi-day epic, not a 10-line tweak.
+
+**Hard size cap — split a sub-task if ANY of these is true:**
+- Touches more than 3 files
+- Has more than 5 acceptance criteria
+- Would require more than ~200 lines of diff
+- Requires a mid-execution judgment call about scope (split the judgment into its own predecessor task)
+- Spans more than one concern (e.g., schema + UI in one sub-task)
+
+When splitting, keep the integration-aware principle intact: each split task still names its Producer / Consumer / Replaces.
+
+### Acceptance Criteria Types
+
+Every acceptance criterion MUST be one of three executable types. Prose criteria like "feature works correctly" or "behavior is consistent" are forbidden — an executor cannot self-check them.
+
+1. **Test passes** — `Test \`<test_name>\` passes` (or `tests in <file_path> pass`)
+2. **Observable behavior** — A specific, checkable runtime signal: `GET /api/x returns 200 with field \`y\``, `Console logs \`event=loaded params={...}\``, `Button click triggers <handler> within 100ms`
+3. **State / file condition** — `File \`<path>\` exists and contains <pattern>`, `Migration \`<id>\` applied`, `Env var \`X\` is read at startup`
+
+Mixing types within a sub-task is fine. What's not fine: criteria the agent cannot verify without asking the user.
+
+### Test-First Task Pairing
+
+For any sub-task that changes observable behavior (not pure refactors or cleanup), pair it with a preceding RED task. Pattern:
+
+- **N.M.k RED**: Write failing test `<test_name>` asserting `<behavior>`. Acceptance: test exists and fails for the documented reason.
+- **N.M.(k+1) Build**: Implement `<change>`. Acceptance: the RED test passes; no other tests regress.
+
+This is the TDAD pattern (test-driven agentic development): the failing test is the executor's self-correction signal. Without it, the executor is guessing whether the implementation is right.
+
+Pure refactors, cleanups, and config-only tasks don't require RED pairing — but if behavior changes, the RED comes first.
 
 ### Integration-Aware Task Principle
 
@@ -153,11 +187,23 @@ Tasks without consumers are incomplete. Tasks that don't address old code paths
 - **Cleanup tasks**: Remove/redirect old code paths (MANDATORY when replacing patterns)
 
 ### 4b. Create Parent Tasks
-- **Action** — CreateParentTasks: Draft as many phases as needed to logically organize work, each with as many parent tasks (📋) as required to cover complete scope.
+- **Action** — CreateParentTasks: Draft as many phases as needed to logically organize work, each with as many parent tasks as required to cover complete scope.
   - Each parent task = single cohesive deliverable (small-medium scope)
   - Cover ALL extracted requirements with no gaps
   - Group related work into phases for clarity
   - Align with technical approach (from research or existing docs)
+  - Every parent task carries explicit sequencing in its body:
+    - **Predecessor**: parent task IDs that must complete first (or "none")
+    - **Unblocks**: parent task IDs this unblocks (or "terminal")
+  - The first phase is always **Phase 0 — Dependency Verification** (see 4a-Phase0 below). Other phases start at Phase 1.
+
+### 4a-Phase0. Phase 0 — Dependency Verification (always present)
+
+Before any implementation, generate a Phase 0 containing one sub-task per external dependency listed in `plan.md`'s "External Dependencies — Verify Before Implementation" section. Each sub-task verifies the package exists at the named version and exposes the API the plan assumed.
+
+- Acceptance type: state condition (`npm view <pkg>@<ver>` returns valid metadata) and/or test passes (a minimal import-and-call smoke test).
+- If `plan.md` declared "no new packages," Phase 0 is a single sub-task that confirms no new dependencies were silently introduced during implementation (cross-check `package.json` diff at end).
+- Phase 0 unblocks Phase 1; it cannot be skipped or run in parallel with Phase 1.
 
 ### 4c. Break Down Sub-tasks
 - **Action** — BreakdownSubTasks: For each parent, generate as many detailed sub-tasks as needed to complete the parent.
@@ -171,14 +217,19 @@ Tasks without consumers are incomplete. Tasks that don't address old code paths
     - Completable as a single focused change
 
   - **What to INCLUDE in sub-tasks:**
-    - ✅ Technical terms (JWT, REST, WebSocket, React hooks, SQL queries)
-    - ✅ Architecture patterns (middleware, pub/sub, observer, factory)
-    - ✅ Integration points (which components connect, API contracts)
-    - ✅ File/component names (UserProfileComponent, authMiddleware.ts)
-    - ✅ Technical constraints (max file size, timeout duration, data format)
-    - ✅ **Produces**: What output this creates (variable name, return value, prop)
-    - ✅ **Consumed by**: What uses this output (component, hook, render path)
-    - ✅ **Replaces**: What old code path this supersedes (if any)
+    - Technical terms (JWT, REST, WebSocket, React hooks, SQL queries)
+    - Architecture patterns (middleware, pub/sub, observer, factory)
+    - Integration points (which components connect, API contracts)
+    - File/component names (UserProfileComponent, authMiddleware.ts)
+    - Technical constraints (max file size, timeout duration, data format)
+    - **Produces**: What output this creates (variable name, return value, prop)
+    - **Consumed by**: What uses this output (component, hook, render path)
+    - **Replaces**: What old code path this supersedes (if any)
+    - **Context** (required): a self-contained payload an executor can use without re-reading the full plan. Include:
+      - 2–4 file:line refs pulled from research (the exact code being modified or extended)
+      - 1 canonical reference pointer (a file:line from `@patterns` research that shows the shape to follow)
+      - 1 link/anchor into `plan.md` for the relevant section
+    - **Predecessor** (sub-task level, optional): a sub-task ID this depends on. Only when intra-parent ordering is non-obvious.
 
   - **What to AVOID in sub-tasks:**
     - ❌ Code snippets or pseudo-code
@@ -187,12 +238,11 @@ Tasks without consumers are incomplete. Tasks that don't address old code paths
     - ❌ Specific library API calls (unless architecturally significant)
 
   - **Acceptance criteria**:
-    - Describe technical behaviors and observable outcomes
-    - Include integration expectations and error handling
-    - 2-3 verifiable outcomes per sub-task
-    - Be specific about technical requirements
+    - Every criterion MUST be one of the three executable types (see "Acceptance Criteria Types" above): test passes / observable behavior / state condition.
+    - 2–3 criteria per sub-task. If a sub-task needs more than 3 to be checkable, split it.
+    - Prose criteria ("works correctly", "is consistent", "user-friendly") are forbidden — they're not self-checkable.
 
-  - **Decomposition**: Split if 5+ criteria or multiple concerns
+  - **Decomposition (hard size cap)**: Split if ANY of: >3 files touched, >5 criteria, >~200 LOC, mid-task scope judgment required, or more than one concern.
 
 ### 4d. Validate Task Structure
 - **Action** — VerifyCoverage: Cross-reference tasks against extracted requirements.
@@ -204,13 +254,19 @@ Tasks without consumers are incomplete. Tasks that don't address old code paths
   - **Coverage Validation**:
     - [ ] All extracted requirements from Step 3 addressed by tasks?
     - [ ] No gaps in requirement coverage?
+    - [ ] Every "Verification" entry from `plan.md` mapped to at least one acceptance criterion?
   - **Exclusion Validation**:
-    - [ ] Adding anything beyond explicit requests?
-    - [ ] Avoiding "nice-to-have" additions not requested?
+    - [ ] No additions beyond explicit requests?
+    - [ ] `plan.md`'s "Out-of-Bounds — DO NOT add" list carried forward verbatim into tasks.md banner?
+    - [ ] No task implements anything in the Out-of-Bounds list?
   - **Structure Validation**:
     - [ ] Parent tasks are small-medium scope, sub-tasks are atomic?
-    - [ ] Each sub-task has 2-3 acceptance criteria?
-    - [ ] Acceptance criteria verifiable (not implementation steps)?
+    - [ ] Each sub-task has 2-3 acceptance criteria, each one of the three executable types?
+    - [ ] No sub-task exceeds the size cap (>3 files / >5 criteria / >~200 LOC / multi-concern / mid-task scope judgment)?
+    - [ ] Every behavior-changing sub-task is preceded by a RED test sub-task?
+    - [ ] Every sub-task has a Context payload (2–4 file:line refs, 1 canonical reference, 1 plan.md anchor)?
+    - [ ] Every parent task has Predecessor and Unblocks declared?
+    - [ ] Phase 0 — Dependency Verification is present and unblocks Phase 1?
 
 - **Action** — ValidateIntegration: Verify every build task is wired to consumers.
   - **Consumer Specified**:
@@ -288,6 +344,13 @@ Save to `${TASKS_FILE}`:
 - **In Scope**: {bullet list}
 - **Out of Scope**: {bullet list}
 
+## Out-of-Bounds — DO NOT add
+*Carried forward verbatim from plan.md. Executors: if a task tempts you to add any of these, stop and ask.*
+- {Forbidden addition 1, e.g. "rate limiting"}
+- {Forbidden addition 2, e.g. "retry/backoff"}
+- {Forbidden addition 3, e.g. "telemetry events"}
+- {Forbidden addition 4, e.g. "admin UI"}
+
 ## Requirements Traced
 | ID | Description | Source | Tasks |
 |----|-------------|--------|-------|
@@ -315,30 +378,66 @@ Save to `${TASKS_FILE}`:
 
 ## Tasks
 
+### Phase 0: Dependency Verification
+*Confirms every external dependency in plan.md exists at the declared version before any implementation begins.*
+
+#### [0.1] Verify external dependencies
+- **Predecessor**: none
+- **Unblocks**: 1.1
+- [ ] **0.1.1** Verify each package@version from plan.md "External Dependencies" section exists
+  - **Produces**: confirmation log of resolved package metadata
+  - **Consumed by**: Phase 1 implementation tasks
+  - **Context**:
+    - plan.md anchor: `## External Dependencies — Verify Before Implementation`
+    - check commands listed in plan section
+  - [ ] State condition: `npm view <pkg>@<ver>` returns valid metadata for every package
+  - [ ] State condition: no package in the list is flagged as deprecated or security-advised
+  - [ ] Test passes: minimal import-and-call smoke for each new package
+
 ### Phase 1: {Phase Name}
 
 #### [1.1] {Parent Task Title}
-- [ ] **1.1.1** {Sub-task with technical specifics}
+- **Predecessor**: 0.1
+- **Unblocks**: 1.2
+
+- [ ] **1.1.1 RED** Write failing test `{test_name}` asserting `{behavior}`
+  - **Produces**: a failing test that pins the desired behavior
+  - **Consumed by**: 1.1.2 (turns this red to green)
+  - **Replaces**: N/A
+  - **Context**:
+    - `path/to/existing/code.ts:42` — current behavior being changed
+    - `path/to/similar/test.ts:18` — canonical test shape to follow
+    - plan.md anchor: `### Verification — How We Know This Works`
+  - [ ] State condition: file `path/to/test.ts` exists and contains test `{test_name}`
+  - [ ] Test passes: the new test fails, with failure message referencing the unimplemented behavior
+
+- [ ] **1.1.2 Build** {Implement the change}
   - **Produces**: {output variable/value/prop}
   - **Consumed by**: {component/hook that uses this}
   - **Replaces**: {old code path, or "N/A" if new}
-  - [ ] {Technical outcome 1}
-  - [ ] {Technical outcome 2}
-  - [ ] {Technical outcome 3}
-
-- [ ] **1.1.2** {Sub-task with technical specifics}
-  - **Produces**: {output variable/value/prop}
-  - **Consumed by**: {component/hook that uses this}
-  - [ ] {Technical outcome 1}
-  - [ ] {Technical outcome 2}
+  - **Context**:
+    - `path/to/file.ts:120` — code to modify
+    - `path/to/file.ts:180` — adjacent code that must not regress
+    - `path/to/canonical/example.ts:55` — pattern to follow (from @patterns research)
+    - plan.md anchor: `## Technical Approach`
+  - [ ] Test passes: `{test_name}` (from 1.1.1) now passes
+  - [ ] Test passes: existing tests in `path/to/related.test.ts` still pass
+  - [ ] Observable behavior: `{specific runtime signal, e.g. log line, HTTP response shape}`
 
 #### [1.2] {Parent Task Title} — Integration
-*This task wires outputs from 1.1 to consumers*
-- [ ] **1.2.1** {Wire X to Y}
-  - **Wires**: {1.1.1 output} → {consumer component/render}
+- **Predecessor**: 1.1
+- **Unblocks**: {next parent or "terminal"}
+
+- [ ] **1.2.1** Wire {1.1.2 output} to {consumer}
+  - **Wires**: {1.1.2 output} → {consumer component/render}
   - **Removes**: {old code path being replaced}
-  - [ ] {Consumer uses new data source}
-  - [ ] {Old data source removed/redirected}
+  - **Context**:
+    - `path/to/consumer.tsx:30` — where the wire lands
+    - `path/to/old/path.ts:12` — old code path to remove
+    - plan.md anchor: `### Technical Approach`
+  - [ ] Test passes: integration test asserting consumer renders new data source
+  - [ ] State condition: old code path file `path/to/old/path.ts` deleted or import removed
+  - [ ] Observable behavior: data flows from producer to rendered output (with `{specific assertion}`)
 
 ### Phase 2: {Phase Name}
 ...

package/plugins/spectre/skills/execute/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: execute
-description: 👻 | Adaptive Wave-Based Build -> Code_Review -> Validate Flow
+description: 👻 | Adaptive Wave-Based Build with Per-Wave Verification Gate
 user-invocable: true
 ---
 
@@ -11,9 +11,9 @@ user-invocable: true
 Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
 
 
-# execute: Adaptive Task Execution with Quality Gates
+# execute: Adaptive Task Execution with Per-Wave Verification
 
-Execute tasks in parallel waves with full scope context, adapt based on learnings, code review loop, validate requirements. Outcome: complete implementation with verified quality and E2E requirement coverage.
+Execute tasks in parallel waves with full scope context, verify each wave before proceeding, adapt based on learnings, audit cross-wave integration, generate manual test guide. Outcome: complete implementation with verified quality and E2E requirement coverage.
 
 ## ARGUMENTS
 
@@ -39,7 +39,9 @@ $ARGUMENTS
 
   2. **Dispatch Wave**: Launch parallel @dev subagents (1 per task batch)
      - **CRITICAL**: Each subagent MUST read `SCOPE_DOCS` before executing
-     - Each receives: task batch assignment, dependency completion reports, SCOPE_DOCS paths
+     - Each receives: task batch assignment, SCOPE_DOCS paths, and (after wave 1) a **Prior-Wave Context** block
+     - **Prior-Wave Context** (REQUIRED in waves 2+): the orchestrator appends each prior wave's @dev Completion Reports verbatim into this wave's dispatch prompt under a `## Prior-Wave Context` header. Includes Completed tasks, Files changed, Scope signal, Discoveries, and Guidance from each prior batch. This is how state is carried forward — there is no separate state file.
+     - **Test discovery**: instruct @dev to use the project's native related-test command (`jest --findRelatedTests <file>`, `pytest` by path, `vitest related`, `cargo test <path>`). Do not create parallel test files for code already covered.
      - Instruct: "Read scope docs first to understand E2E UX and integration points. Load @skill-spectre:spectre-tdd, then execute tasks sequentially using its TDD methodology. **Commit after each parent task** with conventional commit format (e.g., `feat(module): add X`, `fix(module): resolve Y`). Return completion report with **Implementation Insights** + **E2E Completeness Check**."
 
      **E2E Completeness Check** (subagent returns one per batch):
@@ -47,15 +49,64 @@ $ARGUMENTS
      - 🟡 Gap — [specific functionality missing for E2E UX]
      - 🔴 Blocker — [cannot deliver spec without changes to other tasks]
 
-  3. **Mark Complete**: Update tasks doc with `[x]` for completed tasks
+  3. **Per-Wave Verification Gate**: Verify the wave's output before adapting or advancing.
 
-  4. **Reflect**: Review completion reports for:
+     **3a. Deterministic pre-gate (no AI)**
+     - Detect project commands from `package.json` / `pyproject.toml` / `Cargo.toml` / `Makefile`
+     - Run lint, typecheck, build — whichever apply
+     - If any fail: dispatch @dev to fix the failures, re-run the gate. Do NOT invoke @reviewer until all deterministic checks pass.
+
+     **3b. Parallel review lenses (single message, two @reviewer dispatches)**
+
+     Build each reviewer prompt from:
+     - Wave diff: `git diff <parent-of-first-wave-commit>..HEAD`
+     - Acceptance criteria: verbatim text from scope/tasks docs for this wave's tasks
+     - Files-touched manifest
+
+     **Forbidden in reviewer prompts**: @dev completion reports, implementer rationale, orchestrator paraphrase of "what the dev did and why". The reviewer is a clean room — diff + criteria only.
+
+     **Lens 1 — security + correctness**
+     - OWASP Top-10, injection, auth, secrets, data exposure
+     - Logic, edge cases, state transitions
+     - Scope adherence (flag only in-scope issues; do not flag missing out-of-scope work)
+
+     **Lens 2 — wiring**
+     - Apply the Defined → Connected → Reachable methodology:
+       - Defined: code exists in a file
+       - Connected: code is imported/called by other code
+       - Reachable: a user action can trigger the code path
+     - For each new function/component, grep for usage (not just definition)
+     - For UI features, trace render-backward: JSX ← variable ← source ← user action
+     - Flag dead computations (computed but never reach output) and old code paths still active when replaced
+
+     **Severity & evidence rule** (enforced in both lens prompts):
+     - Every CRITICAL or HIGH finding MUST include:
+       1. `file:line` reference
+       2. A reproducible failure scenario or exploit path describing observable behavior
+     - Findings without an evidence chain are auto-downgraded one severity level. "Could potentially" is not evidence.
+     - Each finding includes a hash: `sha256(file_path + line + finding_category)` for the fix-loop ledger (3c).
+
+     **3c. Bounded fix loop**
+
+     If lens dispatches return CRITICAL/HIGH:
+     - **Iteration cap**: 3 fix waves maximum
+     - **Hash ledger**: maintain a set of finding hashes addressed. If a finding with a hash already in the ledger reappears in a later review, classify as "reviewer disagreement" and escalate to user — do NOT re-queue.
+     - **Fix/test ratio**: monitor changes per fix wave. If test-file changes > 0.5 × implementation-file changes, halt and surface to user — likely "fixing the test instead of the bug."
+     - **Diff-growth circuit-breaker**: if cumulative fix-wave diff grows > 25% per iteration, halt and surface — fixes are adding surface area, not reducing it.
+     - **Dispatch fix**: parallel @dev subagents address each CRITICAL/HIGH finding. Each fix-dev receives the finding's full evidence chain (file:line + scenario), not just the description.
+     - **Re-verify**: after fixes commit, return to 3a (deterministic) then 3b (lenses).
+
+     **3d. Exit condition**: No CRITICAL/HIGH remain, OR iteration cap reached and user has been notified of unresolved findings.
+
+  4. **Mark Complete**: Update tasks doc with `[x]` for completed tasks
+
+  5. **Reflect**: Review completion reports for:
      - Scope signals (🟡/🟠/🔴) from implementation insights
      - E2E completeness gaps (🟡/🔴) from completeness checks
-     - **If** all ⚪ across both → skip to step 6
+     - **If** all ⚪ across both → skip to step 7
      - **Else** → adapt tasks
 
-  5. **Adapt** (only if triggered):
+  6. **Adapt** (only if triggered):
      - Modify future tasks with learned context
      - Add tasks for E2E gaps with `[ADDED - E2E gap]` prefix
      - Add required sub-tasks with `[ADDED]` prefix
@@ -63,34 +114,28 @@ $ARGUMENTS
      - Flag cross-task integration issues to remaining waves
      - **Guardrails**: ❌ No "nice-to-have" additions, ❌ No scope expansion, ✅ Only adapt for spec compliance
 
-  6. **Next Wave**: Identify next tasks, gather relevant completion reports, return to step 1
-
-## Step 2 - Code Review Loop
-
-- **Action** — ExecutedeveviewLoop: Until no critical/high feedback:
+  7. **Next Wave**: Identify next tasks, gather prior-wave completion reports for the Prior-Wave Context block, return to step 1
 
-  1. **Spawn Review**: @dev subagent runs `Skill(code_review)` (Claude slash route: `/spectre:code_review`)
-  2. **Analyze**: Identify critical/high items
-     - **If** none → exit loop
-  3. **Address**: Parallel @dev subagents fix feedback
-  4. **Re-verify**: Return to step 1
+## Step 2 - Cross-Wave Validate
 
-## Step 3 - Validate Requirements
+- **Action** — SpawnValidation: @analyst runs `Skill(validate)` (Claude slash route: `/spectre:validate`) with **narrowed scope**:
+  - Focus: cross-wave integration audit (did later waves silently break earlier waves' wiring?) + scope-creep audit (anything implemented that is NOT in the acceptance criteria?) + dead-computation sweep across the full cumulative diff
+  - Skip: per-area wiring verification (already done per-wave in Step 1.3b's wiring lens)
 
-- **Action** — SpawnValidation: @reviewer runs `Skill(validate)` (Claude slash route: `/spectre:validate`) with task list
-- **Action** — AddressGaps: If high priority gaps → dispatch @dev subagents to fix
+- **Action** — AddressGaps: If high priority gaps surface → dispatch @dev subagents to fix.
 
-## Step 4 - Prepare for QA
+## Step 3 - Prepare for QA
 
 - **Action** — GenerateTestGuide: @dev runs `Skill(create_test_guide)` (Claude slash route: `/spectre:create_test_guide`)
   - Save to `{OUT_DIR}/test_guide.md`
 
-## Step 5 - Report
+## Step 4 - Report
 
 - **Action** — SummarizeCompletion:
-  - Tasks completed, waves executed, code review iterations, validation status
+  - Tasks completed, waves executed, per-wave fix-loop iteration counts, validation status
   - Test guide location
   - **Task Evolution Summary**: Adaptations made (or "None - original plan executed")
   - **E2E Gaps Addressed**: Summary of completeness issues found and resolved
+  - **Unresolved Findings** (if any): Any CRITICAL/HIGH that hit the fix-loop cap and were escalated to user
 
 - **Action** — RenderFooter: Use `@skill-spectre:spectre-guide` skill for Next Steps

package/plugins/spectre/skills/plan/SKILL.md

@@ -49,9 +49,11 @@ Treat the current command arguments as this workflow's input. When invoked from
   - `OUT_DIR=docs/tasks/{branch_name}` (or user-specified)
   - `mkdir -p "${OUT_DIR}"`
 
-- **Action** — ScanExistingContext: Read all existing artifacts in `{OUT_DIR}/ (if you haven’t already)` and assess coverage across 4 dimensions.
+- **Action** — ScanExistingContext: Read all existing artifacts in `{OUT_DIR}/ (if you haven't already)` and assess coverage across 4 dimensions.
 
-  Scan for: `task_context.md`, `specs/plan.md`, `concepts/scope.md`, `research/*.md`
+  Scan for: `task_context.md`, `specs/plan.md`, `concepts/scope.md`, `specs/ux.md`, `research/*.md`
+
+  While scanning `concepts/scope.md` and `specs/ux.md`, extract any **filled assumptions** — places where the upstream artifact defaulted a value because the user didn't specify (e.g., DB choice, retry policy, copy variants, segment fallbacks). Carry these forward to Step 3's design surface so they're reviewer-visible before plan generation.
 
   | Dimension | Covered if artifact contains... | Covered by |
   | --- | --- | --- |
@@ -95,13 +97,26 @@ Use research findings from Step 1 to determine appropriate planning depth.
   | Integration points | Research findings | Internal only = Low, 1-2 external = Med, 3+ external = High |
   | External complexity | @web-research | Well-documented with libraries = Low, Some prior art = Med, Novel/emerging = High |
 
-- **Action** — CheckHardStops: Any true = automatic COMPREHENSIVE | db_schema_destructive | new_service_or_component | auth_or_pii_change | | payment_billing_logic | public_api_change | caching_consistency | slo_sla_risk |
+- **Action** — CheckHardStops: Any true = automatic COMPREHENSIVE.
+  - `db_schema_destructive` — drops, renames, or non-additive column changes
+  - `data_migration_required` — backfill, transform, or row-by-row data change
+  - `new_service_or_component` — net-new service, daemon, or top-level component
+  - `auth_or_pii_change` — authn/authz flow, session handling, PII storage/exposure
+  - `secrets_or_credentials_handling` — new secret introduced, rotation, or boundary change
+  - `payment_billing_logic` — money flow, invoicing, charge logic
+  - `public_api_change` — externally-consumed API surface modified
+  - `concurrent_writes_or_locking` — concurrency, locking, or distributed coordination
+  - `caching_consistency` — cache invalidation, staleness windows, multi-tier caching
+  - `cross_service_or_cross_workspace_change` — coordinated change across services or workspaces
+  - `slo_sla_risk` — latency, throughput, or availability budget at stake
+
+- **Action** — DetermineTier (decisive rules, not point-scoring):
 
-- **Action** — DetermineTier:
+  - **COMPREHENSIVE** — if ANY hard-stop is triggered OR any signal scores High OR two or more signals score Medium
+  - **STANDARD** — if no hard-stops AND no High signals AND at most one Medium signal
+  - **LIGHT** — only if every signal scores Low AND no hard-stops AND the change is plausibly a single-file diff
 
-  - **LIGHT**: All/most Low signals, single component, clear pattern match, no hard-stops
-  - **STANDARD**: Mix of Low/Med signals, multi-file but contained scope, no hard-stops
-  - **COMPREHENSIVE**: Any High signal, multiple Med signals, or any hard-stop triggered
+  When in doubt between two tiers, choose the higher. The cost of over-planning a small change is hours; the cost of under-planning a large one is weeks.
 
 - **Action** — LogTier: Note the assessed tier in your response for transparency, then proceed immediately to the next step. Do NOT ask for confirmation.
 
@@ -129,6 +144,14 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
   > - [decision] — [rationale; alternative considered]
   > - [decision] — [rationale; alternative considered]
   >
+  > **How we'll know it works** (verification spine):
+  > - [change] → [test name | observable behavior | state condition]
+  > - [change] → [test name | observable behavior | state condition]
+  >
+  > **Filled assumptions** (surfaced from scope.md / ux.md / inferred):
+  > - [assumption] — *source: [scope.md / ux.md / default]*
+  > - [assumption] — *source: [scope.md / ux.md / default]*
+  >
   > **Open questions** (with default assumption):
   > 1. [question] — *default: [assumption]*
   > 2. [question] — *default: [assumption]*
@@ -138,6 +161,8 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
   **CRITICAL**:
   - **Single proposed approach**, not a menu. If a true fork exists, surface it as an open question with your recommendation — not as parallel options.
   - Stay at the *shape* level: components, key decisions, structural changes. Defer file-by-file detail to `create_plan`.
+  - **Verification is mandatory.** Every major change in the approach must declare how it will be checked — falsifiable signal, not prose. This becomes the spine that `create_plan` and `create_tasks` build on.
+  - **Filled assumptions are mandatory.** If scope.md or ux.md left something silent and you defaulted it, surface the default here. Reviewer-visible by design — these are the silent decisions that bite at execution.
   - Open questions should be specific and answerable; pair each with a default assumption so the user can skip if the default is fine.
 
 - **Action** — IterateDesign: If the user replies with answers, edits, or pushback, update the design and re-present. Loop until user says 'looks good' (or equivalent).
@@ -208,4 +233,24 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
 
 ---
 
+### Post-Tasks Tier Re-check
+
+After tasks return, do a fast self-check against tier signals:
+
+- Count parent tasks, sub-tasks, files touched (sum of unique paths in Context blocks), and Phase 0 dep count.
+- **Escalation triggers** (any true → recommend re-running at a higher tier):
+  - Tier was LIGHT but tasks touch >3 files OR have >2 parent tasks
+  - Tier was STANDARD but tasks reveal a hard-stop signal not caught earlier (e.g., a migration sub-task appeared)
+  - Tasks contain any Out-of-Bounds violation
+- **Downgrade triggers** (rare; only suggest if confident):
+  - Tier was COMPREHENSIVE but tasks collapsed to a single parent with no migrations, no new components, and no API change
+
+If an escalation/downgrade is triggered, surface it as a recommendation — do NOT silently re-run. Format:
+
+> Tier reassessment: I planned this as {original tier}, but tasks revealed {signal}. Recommend re-running as {new tier}. Reply 'rerun' to regenerate or 'keep' to proceed as-is.
+
+Only proceed past this checkpoint when the user confirms.
+
+---
+
 - **Action** — RenderFooter: Use `@skill-spectre:spectre-guide` skill for Next Steps