@codename_inc/spectre 5.1.0 → 5.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codename_inc/spectre",
-  "version": "5.1.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.1.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/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-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