@codename_inc/spectre 5.1.0 → 5.2.1

package/package.json

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

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

@@ -1,5 +1,5 @@
 {
   "name": "spectre",
-  "version": "5.1.0",
+  "version": "5.2.1",
   "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/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_review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan_review
-description: 👻 | Independent multi-lens review of plan.md + tasks.md — finds overengineering, missing verification, hallucinated deps, weak references
+description: 👻 | Independent multi-lens review of plan.md and/or tasks.md — finds overengineering, missing verification, hallucinated deps, weak references
 user-invocable: true
 ---
 
@@ -10,12 +10,12 @@ user-invocable: true
 
 Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
 
-# plan_review: Multi-Lens Review of Plan & Tasks
+# plan_review: Multi-Lens Review of Plan and/or Tasks
 
 ## Description
 
-- **What** — Independent review of `plan.md` + `tasks.md` from four specialized lenses, dispatched in parallel
-- **Outcome** — Structured findings with concrete edit suggestions; optional write-back to update both artifacts
+- **What** — Independent review of any available planning artifacts (`plan.md`, `tasks.md`, and optional `task_context.md`) from four specialized lenses, dispatched in parallel
+- **Outcome** — Structured findings with concrete edit suggestions; optional write-back to update the available artifacts
 - **Role** — Senior staff engineer + reviewer panel; bias toward pragmatic problem-solving, YAGNI enforcement, and verifiability
 
 ## ARGUMENTS Input
@@ -42,25 +42,30 @@ A single reviewer biases toward the issues it notices first. Published practice
   - **If** user specifies path in ARGUMENTS → `TASK_DIR={that value}`
   - **Else** → `TASK_DIR=docs/tasks/{branch_name}`
 
-- **Action** — ResolveArtifacts: Locate the three required inputs.
+- **Action** — ResolveArtifacts: Locate the available review inputs.
   - `PLAN=${TASK_DIR}/specs/plan.md` (or scoped name)
   - `TASKS=${TASK_DIR}/specs/tasks.md` (or scoped name)
   - `CONTEXT=${TASK_DIR}/task_context.md`
-  - If any are missing, list what's missing and stop — do NOT review against a partial set. Suggest the user run `/spectre:plan` or `/spectre:create_tasks` first.
+  - `plan.md` and `tasks.md` are independently reviewable. It is valid to review only `plan.md`, only `tasks.md`, or both.
+  - `task_context.md` is helpful context but is not required. If it is missing, continue and note that requirements traceability is limited.
+  - If both `plan.md` and `tasks.md` are missing, stop and suggest the user run `/spectre:plan` or `/spectre:create_tasks` first.
+  - If exactly one of `plan.md` or `tasks.md` is missing, list it as absent context and continue. Do not decline, stop, or ask the user to create the missing artifact.
 
-- **Action** — ReadAll: Read each file completely into context before dispatching reviewers. Reviewers receive curated excerpts, not raw paths.
+- **Action** — ReadAvailable: Read each available file completely into context before dispatching reviewers. Reviewers receive curated excerpts plus an artifact manifest that says which files are present and absent. Every reviewer must review the artifacts that exist and must not treat absent artifacts as a blocker.
 
 ## Step 2 — Dispatch Four Parallel Reviewers
 
-Spawn all four subagents in a single message (parallel). Each receives the same artifact excerpts but a different review brief.
+Spawn all four subagents in a single message (parallel). Each receives the same available artifact excerpts, the artifact manifest, and a different review brief.
+
+Missing-artifact rule for every lens: review what exists. If a finding depends on a missing artifact, phrase it as "not reviewable because `<artifact>` is absent" only when that context is necessary; do not fail the review or ask for the missing artifact.
 
 ### Lens 1 — YAGNI / Familiar-Shape Bias (`@reviewer`)
 
-> Review this plan and task list for unrequested complexity. Agents have a documented "familiar-shape bias": shown a feature, they reproduce the mature-system shape from their training data (auth → adds rate-limiting; CRUD → adds soft-delete; form → adds optimistic UI; service → adds telemetry; module → adds feature flags). Your job is to find that bias here.
+> Review the available plan and/or task list for unrequested complexity. Agents have a documented "familiar-shape bias": shown a feature, they reproduce the mature-system shape from their training data (auth → adds rate-limiting; CRUD → adds soft-delete; form → adds optimistic UI; service → adds telemetry; module → adds feature flags). Your job is to find that bias here.
 >
 > Find:
-> 1. Anything in `plan.md` Technical Approach that isn't traceable to a requirement in `task_context.md` / scope / PRD.
-> 2. Tasks in `tasks.md` that implement something the requirements don't ask for.
+> 1. When `plan.md` is present: anything in Technical Approach that isn't traceable to a requirement in available context (`task_context.md` / scope / PRD). If context is absent, use the plan's own requirements and boundaries.
+> 2. When `tasks.md` is present: tasks that implement something the available requirements don't ask for. If requirements context is absent, use the task list's stated goals and boundaries.
 > 3. Abstractions, interfaces, or layers introduced for a single concrete caller.
 > 4. Generality (config files, plugin points, factories) where the actual need is one specific behavior.
 > 5. Overlap with the `Out-of-Bounds — DO NOT add` list (if anything violates that list, it's a hard fail).
@@ -69,36 +74,36 @@ Spawn all four subagents in a single message (parallel). Each receives the same
 
 ### Lens 2 — Verifiability (`@analyst`)
 
-> Review this plan and task list for verification quality. The single highest-correlate of successful AI-agent execution is the ability to self-verify. Find every place where verification is missing, prose-only, or disconnected.
+> Review the available plan and/or task list for verification quality. The single highest-correlate of successful AI-agent execution is the ability to self-verify. Find every place where verification is missing, prose-only, or disconnected.
 >
 > Find:
-> 1. Items in `plan.md` "Verification — How We Know This Works" that are prose ("works correctly", "is consistent") rather than executable (test name / observable behavior / state condition).
-> 2. Phases in `plan.md` that don't declare a verification signal.
-> 3. Sub-tasks in `tasks.md` whose acceptance criteria aren't one of the three executable types (test passes / observable behavior / state condition).
-> 4. Verification signals in `plan.md` with no matching acceptance criterion in `tasks.md`.
-> 5. Behavior-changing sub-tasks in `tasks.md` that lack a preceding RED test sub-task.
+> 1. When `plan.md` is present: items in "Verification — How We Know This Works" that are prose ("works correctly", "is consistent") rather than executable (test name / observable behavior / state condition).
+> 2. When `plan.md` is present: phases that don't declare a verification signal.
+> 3. When `tasks.md` is present: sub-tasks whose acceptance criteria aren't one of the three executable types (test passes / observable behavior / state condition).
+> 4. When both `plan.md` and `tasks.md` are present: verification signals in `plan.md` with no matching acceptance criterion in `tasks.md`.
+> 5. When `tasks.md` is present: behavior-changing sub-tasks that lack a preceding RED test sub-task.
 >
 > Required output: list every non-executable criterion with a proposed rewrite in one of the three types. Cite file:line for each.
 
 ### Lens 3 — Existence / Hallucination (`@finder`)
 
-> Review this plan and task list for references to things that may not exist. AI-generated plans hallucinate file paths, package names, function signatures, and API endpoints at measurable rates (~20% for packages per Snyk analysis). Your job is to verify every reference is real.
+> Review the available plan and/or task list for references to things that may not exist. AI-generated plans hallucinate file paths, package names, function signatures, and API endpoints at measurable rates (~20% for packages per Snyk analysis). Your job is to verify every reference is real.
 >
 > Verify:
-> 1. Every file path mentioned in `plan.md` "Critical Files for Implementation" and in `tasks.md` Context blocks — does the file exist in the repo today? Use Glob/Read to confirm.
-> 2. Every package in `plan.md` "External Dependencies" — does it exist at the named version? (Note: actual install/registry check is the executor's Phase 0 job; your job is to flag suspicious names — typos, near-misses to well-known packages, lookalikes.)
-> 3. Every function, class, or symbol named in plan/tasks — grep the repo, confirm it exists where claimed.
+> 1. Every file path mentioned in available artifacts, including `plan.md` "Critical Files for Implementation" and `tasks.md` Context blocks when present — does the file exist in the repo today? Use Glob/Read to confirm.
+> 2. Every package in `plan.md` "External Dependencies" when `plan.md` is present — does it exist at the named version? (Note: actual install/registry check is the executor's Phase 0 job; your job is to flag suspicious names — typos, near-misses to well-known packages, lookalikes.)
+> 3. Every function, class, or symbol named in available plan/tasks — grep the repo, confirm it exists where claimed.
 > 4. Every API endpoint, env var, or CLI flag referenced — confirm it's defined in the codebase.
 >
 > Required output: list every reference that fails verification, with `expected: <plan claim>` and `actual: <repo state>`. If everything checks out, say so explicitly — don't pad.
 
 ### Lens 4 — Canonical Reference Quality (`@patterns`)
 
-> Review this plan and task list for the quality of "follow existing pattern" references. Anthropic's own guidance is to anchor plans with concrete examples (e.g., "HotDogWidget.php is a good example"). Vague "follow existing patterns" without a file:line anchor is a documented failure mode.
+> Review the available plan and/or task list for the quality of "follow existing pattern" references. Anthropic's own guidance is to anchor plans with concrete examples (e.g., "HotDogWidget.php is a good example"). Vague "follow existing patterns" without a file:line anchor is a documented failure mode.
 >
 > Find:
-> 1. Places in `plan.md` Technical Approach that reference "existing patterns" or "similar features" without a specific file:line.
-> 2. Sub-tasks in `tasks.md` whose Context block lacks a canonical reference pointer.
+> 1. When `plan.md` is present: places in Technical Approach that reference "existing patterns" or "similar features" without a specific file:line.
+> 2. When `tasks.md` is present: sub-tasks whose Context block lacks a canonical reference pointer.
 > 3. Better canonical references that the plan missed — actual files in the codebase that more closely match the intended shape.
 > 4. Reuse opportunities the plan ignored: utilities, hooks, helpers, or types already in the repo that the plan re-implements.
 >
@@ -150,12 +155,12 @@ Spawn all four subagents in a single message (parallel). Each receives the same
   > - `1,3,5` — apply specific finding numbers
   > - `skip` — leave artifacts unchanged
   >
-  > For findings I apply, I'll edit plan.md and/or tasks.md inline and re-run a fast self-check.
+  > For findings I apply, I'll edit the relevant available artifact(s) inline and re-run a fast self-check.
 
 - **Wait** — User selects.
 
 - **Action** — ApplyEdits: For each selected finding:
-  - Open the named artifact (plan.md or tasks.md)
+  - Open the named artifact (`plan.md` or `tasks.md`)
   - Apply the Suggested Edit verbatim where possible; if the edit needs adaptation, make the minimum change consistent with the finding's intent
   - Track which findings were applied
 
@@ -168,7 +173,7 @@ Spawn all four subagents in a single message (parallel). Each receives the same
 - **Action** — ReportApplied:
 
   > Applied: {list of finding numbers}. Skipped: {list}.
-  > {Path to updated plan.md and tasks.md}.
+  > {Path to updated artifact(s)}.
 
 ## Step 5 — Next Steps
 
@@ -178,6 +183,6 @@ Spawn all four subagents in a single message (parallel). Each receives the same
 
 ## Notes
 
-- This skill does NOT generate plans or tasks. It reviews them. If `plan.md` or `tasks.md` doesn't exist, route the user to `/spectre:plan` first.
+- This skill does NOT generate plans or tasks. It reviews available planning artifacts. If only one of `plan.md` or `tasks.md` exists, review that artifact. Only route the user to `/spectre:plan` or `/spectre:create_tasks` when neither reviewable artifact exists.
 - The four lenses are intentionally non-overlapping by design but will surface overlap in practice — dedupe at synthesis, don't ask reviewers to coordinate.
 - The "Must-Delete" nomination from Lens 1 is mandatory output — even on a tight plan, naming the single weakest element is a forcing function against under-review.

package/plugins/spectre-codex/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-codex/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-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: `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: `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: `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: `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-guide)` skill for Next Steps

package/plugins/spectre-codex/skills/plan_review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "plan_review"
-description: "👻 | Independent multi-lens review of plan.md + tasks.md — finds overengineering, missing verification, hallucinated deps, weak references"
+description: "👻 | Independent multi-lens review of plan.md and/or tasks.md — finds overengineering, missing verification, hallucinated deps, weak references"
 user-invocable: true
 ---
 
@@ -10,12 +10,12 @@ user-invocable: true
 
 Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
 
-# plan_review: Multi-Lens Review of Plan & Tasks
+# plan_review: Multi-Lens Review of Plan and/or Tasks
 
 ## Description
 
-- **What** — Independent review of `plan.md` + `tasks.md` from four specialized lenses, dispatched in parallel
-- **Outcome** — Structured findings with concrete edit suggestions; optional write-back to update both artifacts
+- **What** — Independent review of any available planning artifacts (`plan.md`, `tasks.md`, and optional `task_context.md`) from four specialized lenses, dispatched in parallel
+- **Outcome** — Structured findings with concrete edit suggestions; optional write-back to update the available artifacts
 - **Role** — Senior staff engineer + reviewer panel; bias toward pragmatic problem-solving, YAGNI enforcement, and verifiability
 
 ## ARGUMENTS Input
@@ -42,25 +42,30 @@ A single reviewer biases toward the issues it notices first. Published practice
   - **If** user specifies path in ARGUMENTS → `TASK_DIR={that value}`
   - **Else** → `TASK_DIR=docs/tasks/{branch_name}`
 
-- **Action** — ResolveArtifacts: Locate the three required inputs.
+- **Action** — ResolveArtifacts: Locate the available review inputs.
   - `PLAN=${TASK_DIR}/specs/plan.md` (or scoped name)
   - `TASKS=${TASK_DIR}/specs/tasks.md` (or scoped name)
   - `CONTEXT=${TASK_DIR}/task_context.md`
-  - If any are missing, list what's missing and stop — do NOT review against a partial set. Suggest the user run `plan` or `create_tasks` first.
+  - `plan.md` and `tasks.md` are independently reviewable. It is valid to review only `plan.md`, only `tasks.md`, or both.
+  - `task_context.md` is helpful context but is not required. If it is missing, continue and note that requirements traceability is limited.
+  - If both `plan.md` and `tasks.md` are missing, stop and suggest the user run `plan` or `create_tasks` first.
+  - If exactly one of `plan.md` or `tasks.md` is missing, list it as absent context and continue. Do not decline, stop, or ask the user to create the missing artifact.
 
-- **Action** — ReadAll: Read each file completely into context before dispatching reviewers. Reviewers receive curated excerpts, not raw paths.
+- **Action** — ReadAvailable: Read each available file completely into context before dispatching reviewers. Reviewers receive curated excerpts plus an artifact manifest that says which files are present and absent. Every reviewer must review the artifacts that exist and must not treat absent artifacts as a blocker.
 
 ## Step 2 — Dispatch Four Parallel Reviewers
 
-Spawn all four subagents in a single message (parallel). Each receives the same artifact excerpts but a different review brief.
+Spawn all four subagents in a single message (parallel). Each receives the same available artifact excerpts, the artifact manifest, and a different review brief.
+
+Missing-artifact rule for every lens: review what exists. If a finding depends on a missing artifact, phrase it as "not reviewable because `<artifact>` is absent" only when that context is necessary; do not fail the review or ask for the missing artifact.
 
 ### Lens 1 — YAGNI / Familiar-Shape Bias (`@reviewer`)
 
-> Review this plan and task list for unrequested complexity. Agents have a documented "familiar-shape bias": shown a feature, they reproduce the mature-system shape from their training data (auth → adds rate-limiting; CRUD → adds soft-delete; form → adds optimistic UI; service → adds telemetry; module → adds feature flags). Your job is to find that bias here.
+> Review the available plan and/or task list for unrequested complexity. Agents have a documented "familiar-shape bias": shown a feature, they reproduce the mature-system shape from their training data (auth → adds rate-limiting; CRUD → adds soft-delete; form → adds optimistic UI; service → adds telemetry; module → adds feature flags). Your job is to find that bias here.
 >
 > Find:
-> 1. Anything in `plan.md` Technical Approach that isn't traceable to a requirement in `task_context.md` / scope / PRD.
-> 2. Tasks in `tasks.md` that implement something the requirements don't ask for.
+> 1. When `plan.md` is present: anything in Technical Approach that isn't traceable to a requirement in available context (`task_context.md` / scope / PRD). If context is absent, use the plan's own requirements and boundaries.
+> 2. When `tasks.md` is present: tasks that implement something the available requirements don't ask for. If requirements context is absent, use the task list's stated goals and boundaries.
 > 3. Abstractions, interfaces, or layers introduced for a single concrete caller.
 > 4. Generality (config files, plugin points, factories) where the actual need is one specific behavior.
 > 5. Overlap with the `Out-of-Bounds — DO NOT add` list (if anything violates that list, it's a hard fail).
@@ -69,36 +74,36 @@ Spawn all four subagents in a single message (parallel). Each receives the same
 
 ### Lens 2 — Verifiability (`@analyst`)
 
-> Review this plan and task list for verification quality. The single highest-correlate of successful AI-agent execution is the ability to self-verify. Find every place where verification is missing, prose-only, or disconnected.
+> Review the available plan and/or task list for verification quality. The single highest-correlate of successful AI-agent execution is the ability to self-verify. Find every place where verification is missing, prose-only, or disconnected.
 >
 > Find:
-> 1. Items in `plan.md` "Verification — How We Know This Works" that are prose ("works correctly", "is consistent") rather than executable (test name / observable behavior / state condition).
-> 2. Phases in `plan.md` that don't declare a verification signal.
-> 3. Sub-tasks in `tasks.md` whose acceptance criteria aren't one of the three executable types (test passes / observable behavior / state condition).
-> 4. Verification signals in `plan.md` with no matching acceptance criterion in `tasks.md`.
-> 5. Behavior-changing sub-tasks in `tasks.md` that lack a preceding RED test sub-task.
+> 1. When `plan.md` is present: items in "Verification — How We Know This Works" that are prose ("works correctly", "is consistent") rather than executable (test name / observable behavior / state condition).
+> 2. When `plan.md` is present: phases that don't declare a verification signal.
+> 3. When `tasks.md` is present: sub-tasks whose acceptance criteria aren't one of the three executable types (test passes / observable behavior / state condition).
+> 4. When both `plan.md` and `tasks.md` are present: verification signals in `plan.md` with no matching acceptance criterion in `tasks.md`.
+> 5. When `tasks.md` is present: behavior-changing sub-tasks that lack a preceding RED test sub-task.
 >
 > Required output: list every non-executable criterion with a proposed rewrite in one of the three types. Cite file:line for each.
 
 ### Lens 3 — Existence / Hallucination (`@finder`)
 
-> Review this plan and task list for references to things that may not exist. AI-generated plans hallucinate file paths, package names, function signatures, and API endpoints at measurable rates (~20% for packages per Snyk analysis). Your job is to verify every reference is real.
+> Review the available plan and/or task list for references to things that may not exist. AI-generated plans hallucinate file paths, package names, function signatures, and API endpoints at measurable rates (~20% for packages per Snyk analysis). Your job is to verify every reference is real.
 >
 > Verify:
-> 1. Every file path mentioned in `plan.md` "Critical Files for Implementation" and in `tasks.md` Context blocks — does the file exist in the repo today? Use Glob/Read to confirm.
-> 2. Every package in `plan.md` "External Dependencies" — does it exist at the named version? (Note: actual install/registry check is the executor's Phase 0 job; your job is to flag suspicious names — typos, near-misses to well-known packages, lookalikes.)
-> 3. Every function, class, or symbol named in plan/tasks — grep the repo, confirm it exists where claimed.
+> 1. Every file path mentioned in available artifacts, including `plan.md` "Critical Files for Implementation" and `tasks.md` Context blocks when present — does the file exist in the repo today? Use Glob/Read to confirm.
+> 2. Every package in `plan.md` "External Dependencies" when `plan.md` is present — does it exist at the named version? (Note: actual install/registry check is the executor's Phase 0 job; your job is to flag suspicious names — typos, near-misses to well-known packages, lookalikes.)
+> 3. Every function, class, or symbol named in available plan/tasks — grep the repo, confirm it exists where claimed.
 > 4. Every API endpoint, env var, or CLI flag referenced — confirm it's defined in the codebase.
 >
 > Required output: list every reference that fails verification, with `expected: <plan claim>` and `actual: <repo state>`. If everything checks out, say so explicitly — don't pad.
 
 ### Lens 4 — Canonical Reference Quality (`@patterns`)
 
-> Review this plan and task list for the quality of "follow existing pattern" references. Anthropic's own guidance is to anchor plans with concrete examples (e.g., "HotDogWidget.php is a good example"). Vague "follow existing patterns" without a file:line anchor is a documented failure mode.
+> Review the available plan and/or task list for the quality of "follow existing pattern" references. Anthropic's own guidance is to anchor plans with concrete examples (e.g., "HotDogWidget.php is a good example"). Vague "follow existing patterns" without a file:line anchor is a documented failure mode.
 >
 > Find:
-> 1. Places in `plan.md` Technical Approach that reference "existing patterns" or "similar features" without a specific file:line.
-> 2. Sub-tasks in `tasks.md` whose Context block lacks a canonical reference pointer.
+> 1. When `plan.md` is present: places in Technical Approach that reference "existing patterns" or "similar features" without a specific file:line.
+> 2. When `tasks.md` is present: sub-tasks whose Context block lacks a canonical reference pointer.
 > 3. Better canonical references that the plan missed — actual files in the codebase that more closely match the intended shape.
 > 4. Reuse opportunities the plan ignored: utilities, hooks, helpers, or types already in the repo that the plan re-implements.
 >
@@ -150,12 +155,12 @@ Spawn all four subagents in a single message (parallel). Each receives the same
   > - `1,3,5` — apply specific finding numbers
   > - `skip` — leave artifacts unchanged
   >
-  > For findings I apply, I'll edit plan.md and/or tasks.md inline and re-run a fast self-check.
+  > For findings I apply, I'll edit the relevant available artifact(s) inline and re-run a fast self-check.
 
 - **Wait** — User selects.
 
 - **Action** — ApplyEdits: For each selected finding:
-  - Open the named artifact (plan.md or tasks.md)
+  - Open the named artifact (`plan.md` or `tasks.md`)
   - Apply the Suggested Edit verbatim where possible; if the edit needs adaptation, make the minimum change consistent with the finding's intent
   - Track which findings were applied
 
@@ -168,7 +173,7 @@ Spawn all four subagents in a single message (parallel). Each receives the same
 - **Action** — ReportApplied:
 
   > Applied: {list of finding numbers}. Skipped: {list}.
-  > {Path to updated plan.md and tasks.md}.
+  > {Path to updated artifact(s)}.
 
 ## Step 5 — Next Steps
 
@@ -178,6 +183,6 @@ Spawn all four subagents in a single message (parallel). Each receives the same
 
 ## Notes
 
-- This skill does NOT generate plans or tasks. It reviews them. If `plan.md` or `tasks.md` doesn't exist, route the user to `plan` first.
+- This skill does NOT generate plans or tasks. It reviews available planning artifacts. If only one of `plan.md` or `tasks.md` exists, review that artifact. Only route the user to `plan` or `create_tasks` when neither reviewable artifact exists.
 - The four lenses are intentionally non-overlapping by design but will surface overlap in practice — dedupe at synthesis, don't ask reviewers to coordinate.
 - The "Must-Delete" nomination from Lens 1 is mandatory output — even on a tight plan, naming the single weakest element is a forcing function against under-review.