@codename_inc/spectre 5.0.0 → 5.2.0

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

@@ -1,6 +1,6 @@
 ---
 name: plan_review
-description: 👻 | Find simplifications in a plan or tasks
+description: 👻 | Independent multi-lens review of plan.md + tasks.md — finds overengineering, missing verification, hallucinated deps, weak references
 user-invocable: true
 ---
 
@@ -10,33 +10,174 @@ 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
 
-You are a senior staff engineer with deep expertise in system design, architecture, and pragmatic problem-solving. Your specialty is finding the simplest path to meet all requirements.
+## Description
 
-Review the following [plan/document/tasks/context] and identify opportunities to simplify while ensuring all requirements and functionality are delivered.
+- **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
+- **Role** — Senior staff engineer + reviewer panel; bias toward pragmatic problem-solving, YAGNI enforcement, and verifiability
 
-For each simplification opportunity, provide:
-1. **What to simplify** - Specific component, process, or decision
-2. **Why** - What complexity it removes (cognitive load, dependencies, maintenance burden, etc.)
-3. **Impact** - Confirm that all original requirements remain satisfied
-4. **Risk** - Any trade-offs or risks introduced by the simplification
+## ARGUMENTS Input
 
-Focus on:
-- Removing unnecessary abstractions or indirection
-- Consolidating duplicated logic or patterns
-- Questioning assumptions that add complexity
-- Identifying over-engineering
-- Suggesting proven, boring solutions over novel approaches
+<ARGUMENTS>
+$ARGUMENTS
+</ARGUMENTS>
 
-## Testing Review
-**Context**: We use fast TDD with 1 happy path test + 1 unhappy path test per feature. A separate task handles achieving 100% test coverage post-feature work.
+## Why Four Lenses
 
-Evaluate the testing approach and flag:
-- **Over-testing**: Tests beyond 1 happy + 1 unhappy path that should be deferred to the coverage task
-- **Wrong tests**: Testing implementation details instead of behavior, brittle tests that will break on refactors, or tests that don't actually validate requirements
-- **Missing critical paths**: Cases where the 1+1 approach genuinely misses a requirement-breaking scenario (rare, but call it out)
-- **Test complexity**: Overly elaborate test setup, mocking, or assertions that could be simpler
+A single reviewer biases toward the issues it notices first. Published practice (Cognition, Anthropic, Osmani) converges on four high-yield review angles for AI-agent-authored plans. We dispatch each as a parallel subagent so coverage is structurally guaranteed, not dependent on a single reviewer remembering everything.
 
-Remember: The goal is fast feedback during development. More comprehensive testing comes later.
+| Lens | Subagent | Finds |
+|------|----------|-------|
+| **YAGNI / familiar-shape bias** | `@reviewer` | Mature-system patterns that crept in unprompted (auth → rate-limit, CRUD → soft-delete, etc.). Forces ONE "delete this" recommendation. |
+| **Verifiability** | `@analyst` | Acceptance criteria that aren't executable; verification gaps between plan and tasks. |
+| **Existence / hallucination** | `@finder` | File paths, packages, APIs, or symbols referenced that don't actually exist. The slopsquatting fence. |
+| **Canonical reference quality** | `@patterns` | "Follow existing pattern" claims without a real file:line anchor; missed reuse opportunities. |
 
-End with a prioritized list of recommendations (high/medium/low impact).
+## Step 1 — Locate Artifacts
+
+- **Action** — DetermineTaskDir:
+  - `branch_name=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)`
+  - **If** user specifies path in ARGUMENTS → `TASK_DIR={that value}`
+  - **Else** → `TASK_DIR=docs/tasks/{branch_name}`
+
+- **Action** — ResolveArtifacts: Locate the three required 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.
+
+- **Action** — ReadAll: Read each file completely into context before dispatching reviewers. Reviewers receive curated excerpts, not raw paths.
+
+## 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.
+
+### 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.
+>
+> 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.
+> 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).
+>
+> Required output: nominate the SINGLE highest-leverage thing to delete and justify it. You must pick one. Then list other simplifications ranked by impact. For each finding, cite the exact file:line or section header it lives in.
+
+### 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.
+>
+> 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.
+>
+> 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.
+>
+> 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.
+> 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.
+>
+> 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.
+> 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.
+>
+> Required output: for each weak/missing reference, propose a specific file:line that should be the anchor. For each missed reuse, cite the existing utility and which task should use it.
+
+## Step 3 — Synthesize Findings
+
+- **Action** — CollectFindings: Wait for all four reviewers to return. Read every finding.
+
+- **Action** — DeduplicateAndPrioritize: Merge findings that overlap (e.g., a missing canonical reference may surface from both Lens 4 and Lens 2). Assign severity:
+  - **Blocker** — would cause execution to fail or produce wrong output (hallucinated file path, criterion the executor can't check, Out-of-Bounds violation)
+  - **High** — meaningfully reduces output quality (missing RED test, weak canonical reference, prose criterion)
+  - **Medium** — overengineering or reuse miss without functional blast radius
+  - **Low** — stylistic or nice-to-have
+
+- **Action** — RenderFindingsTable: Output a single structured table. Schema is fixed.
+
+  ```markdown
+  ## Review Findings — {feature name}
+
+  ### Must-Delete (Lens 1 — YAGNI)
+  > {The single nominated highest-leverage cut, with rationale.}
+
+  ### Findings
+
+  | # | Severity | Lens | Location | Finding | Suggested Edit |
+  |---|----------|------|----------|---------|----------------|
+  | 1 | Blocker  | Existence | plan.md `## External Dependencies` | `react-use-undocumented@2.4.0` doesn't exist on npm | Remove; the plan can use `useReducer` from React stdlib (see `src/hooks/useFormState.ts:18`) |
+  | 2 | High     | Verifiability | tasks.md `1.2.1` | "Component renders correctly" is prose | Replace with: Test passes `<ProductCard /> renders product.title and product.price` |
+  | 3 | High     | YAGNI | plan.md `## Technical Approach` | Adds retry-with-backoff for a sync internal call | Delete; not in requirements; Out-of-Bounds list already forbids retry logic |
+  | … |          |       |          |         |                |
+
+  ### Summary
+  - Blockers: {N} — must resolve before /execute
+  - High: {N}
+  - Medium: {N}
+  - Low: {N}
+  ```
+
+## Step 4 — Surface Findings & Apply Edits
+
+- **Action** — PresentFindings: Render the findings table inline.
+
+- **Action** — OfferWriteBack: After the table, prompt:
+
+  > Reply with which findings to apply:
+  > - `all` — apply every suggested edit
+  > - `blockers` — apply Blocker + High severity only
+  > - `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.
+
+- **Wait** — User selects.
+
+- **Action** — ApplyEdits: For each selected finding:
+  - 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
+
+- **Action** — SelfCheck: After edits, run a fast pass over the modified sections:
+  - Re-verify any file:line refs touched
+  - Re-verify acceptance criteria are still executable
+  - Confirm no edit introduced a new Out-of-Bounds violation
+  - If any check fails, surface it and ask the user before continuing
+
+- **Action** — ReportApplied:
+
+  > Applied: {list of finding numbers}. Skipped: {list}.
+  > {Path to updated plan.md and tasks.md}.
+
+## Step 5 — Next Steps
+
+- **Action** — RenderFooter: Use `@skill-spectre:spectre-guide` skill for Next Steps footer.
+
+---
+
+## 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.
+- 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/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-codex/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}
 ...