@webpresso/plugin-antigravity 0.0.0-stage → 0.0.17

package/skills/plan-refine/references/full-methodology.md

@@ -0,0 +1,654 @@
+# Full reference moved from SKILL.md
+
+> **Implementation Status: Production-Ready**
+>
+> Blueprint hardening and lifecycle infrastructure are production-ready:
+>
+> - Blueprint dependency parsing, format validation, and the lifecycle state
+>   machine with evidence-gated task completion (fully tested, in-package)
+>   batches independent tasks by dependency order and blocks dependents of
+>   failed tasks
+>
+> **Remaining gaps:** execution docs and wrappers must stay aligned with the currently shipped runtime and CLI surface.
+
+# Plan Refinement Methodology
+
+## Core Principle
+
+> **"A plan is only as strong as its weakest unchecked claim — only as elegant as what it refuses to add — and only as fast as its coarsest task granularity."**
+
+Every technology claim, file path, API, version, and architecture decision must be verified against reality before implementation. **Zero assumptions:** model memory is not evidence. Unverified plans cascade into execution failure. Coarse tasks serialize work that should run in parallel.
+
+### Non-negotiable bar (always)
+
+| Target              | Definition                                                                                | Fail condition                                                 |
+| ------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| **100% confidence** | Every material claim has a code pinpoint and/or official-doc citation at a stated version | Any “probably / should work / AI recall” left standing         |
+| **Elegance**        | Smallest coherent design; delete/reuse over add                                           | Heavier option kept without recorded rejection of lighter ones |
+| **Durability**      | Survives upgrades and adjacent change; ownership boundaries clear                         | Rewrite-prone seams or version-blind third-party usage         |
+| **Efficiency**      | Minimal critical path; true parallel waves; no speculative work                           | False dependencies, CP > 0, busywork tasks                     |
+
+Refinement goals (all required):
+
+1. **Correctness** — Every claim fact-checked; every edge case documented
+2. **Zero assumptions** — Unproven statements removed or proven
+3. **Code pinpoints** — Paths, symbols, and signatures anchored in the repo
+4. **Official latest docs** — Third-party behavior from primary sources at latest/pinned version
+5. **Parallelizability** — Maximum independent tasks for `/goal` / `ultragoal`
+6. **Elegance, durability, efficiency** — Not merely correct; DRY/SOLID/YAGNI/KISS + public-package safety
+
+## When to Use
+
+**ALWAYS refine a plan when:**
+
+- A new blueprint has been created from Q&A or brainstorming
+- A blueprint references specific technologies, libraries, or APIs
+- A blueprint makes assumptions about existing codebase structure
+- A blueprint has cross-plan dependencies (upstream/downstream)
+- Before moving a blueprint from `draft/` to `in-progress/`
+- After significant codebase changes that may invalidate assumptions
+- Tasks are too coarse for parallel execution (should be split)
+
+**Don't use for:**
+
+- Trivial single-task plans (just verify inline)
+- Plans that are purely process/methodology (no code assumptions)
+- Plans already verified and in execution
+
+## The Refinement Pipeline
+
+Phases 1–3 (and independent review lenses) run **in parallel**. Only cross-plan alignment, blueprint enforcement, and apply need their inputs.
+
+```
+Blueprint (Draft/In-Progress)
+        │
+        ├──────────────────┬──────────────────┐
+        ▼                  ▼                  ▼
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+│ PHASE 1 (//)    │ │ PHASE 2 (//)    │ │ PHASE 3 (//)    │
+│ Official latest │ │ Code pinpoints  │ │ Architecture +  │
+│ 3rd-party docs  │ │ path + symbol   │ │ elegance/       │
+│ version-pinned  │ │ 0 assumptions   │ │ durability      │
+└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
+         └──────────────────┬──────────────────┘
+                            ▼
+┌─────────────────────────────────┐
+│  PHASE 4: Cross-Plan Alignment  │
+│  - Upstream/downstream contracts│
+│  - Shared decisions consistent  │
+└──────────────┬──────────────────┘
+               ▼
+┌─────────────────────────────────┐
+│  PHASE 5: Max-parallel Blueprint│
+│  - Split/merge for RW/CPR/CP=0  │
+│  - Depends + Files + TDD        │
+└──────────────┬──────────────────┘
+               ▼
+┌─────────────────────────────────┐
+│  PHASE 6: Apply & Consolidate   │
+│  - Fx tags, tables, waves       │
+│  - Ready only at 100% confidence│
+└─────────────────────────────────┘
+```
+
+---
+
+## Folded plan-review pipeline
+
+`/autoplan` is folded into this skill. For non-trivial plans, run the plan review
+lenses in the order that matches the risk: CEO/founder scope, design/UX,
+engineering architecture, then DevEx/migration. Consolidate the reviews into
+keep/change/drop decisions, unresolved taste calls, required tests, and a final
+go/no-go. Do not edit implementation code during plan refinement.
+
+## Required Policy Gates
+
+Apply these gates to every refined blueprint:
+
+- **Engineering principles:** enforce `.agent/rules/engineering-principles.md`.
+  Reject speculative abstractions, unused extension seams, avoidable
+  dependencies, and designs that can be simpler without losing behavior.
+- **Public package safety:** when a plan touches `package.json`, `files`, `bin`,
+  `exports`, package docs, catalog assets, generated agent surfaces, or release
+  workflows, enforce `.agent/rules/public-package-safety.md`. Require a
+  tarball/package-surface check and explicitly keep private content out.
+
+If either gate fails, record the finding and simplify or quarantine the public
+surface before execution.
+
+---
+
+## Phase 1: Technology Fact-Check (official, latest, version-pinned)
+
+**Goal:** Verify every external technology claim against **official/upstream primary sources** at the **latest stable or plan-pinned version**. Secondary sources (blogs, forums, model memory) never stand alone.
+
+### Source order (strict)
+
+1. Vendor/official docs for that version (docs site, OpenAPI, man pages)
+2. Upstream release notes / changelog for that version
+3. Package registry metadata (resolved version, peer deps, engines)
+4. Maintainer GH issues/discussions **only** as supplemental after (1–3)
+
+Route through `best-practice-research` when reusable; escalate to `deep-research` for multi-source depth. Prefer Context7/WebFetch of the **official** URL over search snippets.
+
+### What to Check
+
+| Category                       | Check                                        | How                                                        |
+| ------------------------------ | -------------------------------------------- | ---------------------------------------------------------- |
+| **Library compatibility**      | Does library X work with runtime Y at ver Z? | Official compat matrix + engines field + release notes     |
+| **API correctness**            | Does the API exist as described at that ver? | Official docs page for **that version**, not “latest blog” |
+| **Version constraints**        | Pinned/latest available? Breaking changes?   | Registry + changelog between plan version and current      |
+| **Native addon compatibility** | Compiles for all targets?                    | Official platform support + CI matrix docs                 |
+| **Protocol correctness**       | Wire protocol right?                         | Official protocol/spec docs                                |
+| **Platform limits**            | Timeout/memory/size limits?                  | Platform official limits docs (e.g. Workers)               |
+
+### Output Format
+
+For each finding, assign:
+
+- **ID**: F1, F2, F3...
+- **Severity**: CRITICAL (blocks implementation), HIGH (causes bugs), MEDIUM (suboptimal), LOW (cosmetic)
+- **Claim**: What the blueprint says
+- **Reality**: What official docs show (quote or paraphrase + **URL + version/date**)
+- **Fix**: Concrete change to the blueprint
+
+### Anti-Patterns
+
+| Anti-Pattern                          | Why It's Wrong                    | Do This Instead                                   |
+| ------------------------------------- | --------------------------------- | ------------------------------------------------- |
+| "Library X should work"               | Untested assumption               | Official docs + version-pinned evidence           |
+| Trusting AI knowledge of library APIs | Models hallucinate API signatures | Fetch official docs for the exact version         |
+| "Latest" without stating which latest | Drift between refine and execute  | Record version identity (semver / date / channel) |
+| Blog/SO as sole source                | Often wrong or version-skewed     | Primary docs first; blogs only as supplemental    |
+| Ignoring native addon constraints     | Build failures in CI/CD           | Official target matrix + engines                  |
+
+## Phase 2: Codebase Verification (pinpoint to code)
+
+**Goal:** Prove every local claim against the live tree with **exact anchors** — path + symbol (+ line range when it reduces ambiguity). No “roughly around” or “probably in utils”.
+
+Use the lightest reliable inspection tool first: prefer `rg -n` for search, read exact ranges for definitions, and only escalate to ad hoc scripts when structure across many files is required.
+
+### What to Check
+
+| Category               | Check                                      | How — evidence shape                         |
+| ---------------------- | ------------------------------------------ | -------------------------------------------- |
+| **File paths**         | Do referenced files exist at stated paths? | Path exists; cite path in the fix            |
+| **API signatures**     | Parameters/returns match the plan?         | `path` + symbol + signature snippet          |
+| **Import paths**       | Package exports available?                 | `package.json` `exports` field + importer    |
+| **Existing patterns**  | Assumed pattern actually used?             | 1–3 real call sites (path + symbol)          |
+| **Naming conventions** | New files match neighbors?                 | Sibling directory listing + one exemplar     |
+| **Configuration**      | Config/env keys real?                      | Config file / `.env.example` path + key name |
+
+### Evidence rule
+
+Every material correction must include a **code pinpoint** of the form:
+
+- `packages/foo/src/bar.ts` — `export function baz(...)` (or equivalent symbol)
+- or `packages/foo/package.json` — `exports["./bar"]`
+
+If you cannot produce a pinpoint, the claim is an **assumption** → drop it or block.
+
+### Codebase Red Flags
+
+- Blueprint says `targets/` but codebase uses `emitters/`
+- Blueprint imports from `package/subpath` but package.json has no subpath export
+- Blueprint extends a class that doesn't exist yet (timing dependency)
+- Blueprint assumes a function returns X but it actually returns Y
+- Blueprint references env var that isn't in any config
+- Blueprint cites a helper without a path/symbol (un-pinpointed)
+
+## Phase 3: Architecture Review
+
+**Goal:** Adversarial critique of the architecture — find every way it can break — then select the most **elegant, durable, and efficient** design the constraints allow (not merely a correct one). Record why lighter alternatives were rejected when a heavier option is kept.
+
+### The Adversarial Checklist
+
+Think like a hostile system trying to break the design:
+
+#### Concurrency & Race Conditions
+
+- [ ] What happens if two processes write simultaneously?
+- [ ] What happens if operation A completes between steps of operation B?
+- [ ] Is there a time-of-check-to-time-of-use (TOCTOU) gap?
+- [ ] Can operations interleave in a way that corrupts state?
+
+#### Echo Loops & Infinite Cycles
+
+- [ ] If A triggers B which triggers A, what breaks the cycle?
+- [ ] Is the cycle-break mechanism robust to timing variations?
+- [ ] Can events batch in a way that bypasses the cycle-break?
+
+#### Error Cascades
+
+- [ ] If step N fails, do steps N+1...M still make sense?
+- [ ] Can a partial failure leave the system in an inconsistent state?
+- [ ] Is there a dead-letter queue for permanently failed operations?
+- [ ] What happens after N retries? Is there a max?
+
+#### Authentication & Sessions
+
+- [ ] What happens when tokens expire during long operations?
+- [ ] Is there a refresh mechanism? What if refresh also fails?
+- [ ] Do WebSocket connections survive token rotation?
+
+#### Data Integrity
+
+- [ ] Can the ABA problem occur? (A→B→A looks like no change)
+- [ ] Are soft deletes propagated correctly in both directions?
+- [ ] What happens during schema changes with in-flight data? (Note: repos that prefer `db push` over migrations have different edge cases from migration-based repos.)
+- [ ] Can orphaned records accumulate?
+
+#### Platform Constraints
+
+- [ ] Workers: 100s idle timeout, 30s CPU, 128MB memory
+- [ ] SQLite: single-writer, no network FS, WAL checkpoint starvation
+- [ ] WebSocket: protocol negotiation, heartbeat requirements
+- [ ] File watchers: missed events during rapid bursts, git operations
+
+### Output: Severity Classification
+
+| Severity | Definition                                             | Example                                    |
+| -------- | ------------------------------------------------------ | ------------------------------------------ |
+| CRITICAL | Will cause infinite loops, data loss, or build failure | Echo loop with no break mechanism          |
+| HIGH     | Will cause bugs in normal usage                        | Duplicate outbox entries from dual process |
+| MEDIUM   | Will cause bugs in edge cases                          | Race condition during schema push          |
+| LOW      | Suboptimal but functional                              | Unnecessary payload size                   |
+
+## Phase 4: Cross-Plan Alignment
+
+**Goal:** Ensure the plan is coherent with all related blueprints.
+
+### What to Check
+
+1. **Upstream dependencies** — Are the interfaces/packages this plan depends on still designed the same way?
+2. **Downstream impacts** — Do plans that depend on this one need updating?
+3. **Shared decisions** — If two plans both chose a technology (e.g., Drizzle ORM), are they using compatible versions/patterns?
+4. **Non-goals consistency** — If plan A says "X is out of scope" and plan B says "depends on X from plan A", there's a contradiction.
+5. **Timeline consistency** — If plan A depends on plan B Phase 2, is plan B still structured with that phase?
+
+### Cross-Plan Update Protocol
+
+When a fix in Plan A affects Plan B:
+
+1. Read Plan B in full
+2. Identify the specific section that needs updating
+3. Add a dated architecture note (not a rewrite)
+4. Add/update the cross-plan reference in both plans
+
+---
+
+## Phase 5: Blueprint Format Enforcement & Parallelization
+
+> **"If the parallel execution surface (`/goal` autopilot, `ultragoal`) can't run 6-8 agents simultaneously, the plan is too coarse."**
+
+**Goal:** Ensure every task follows Blueprint format and the dependency graph maximizes parallelism for `/goal` (autopilot) / `ultragoal` with Kahn's Algorithm.
+
+The parallel orchestrator is production-ready. This phase ensures plans are structured to maximize parallel agent throughput.
+
+### Task Granularity Optimization (Parallel-First)
+
+**Goal**: Maximize independent tasks while avoiding file conflicts and hidden dependencies.
+
+**Rules of thumb**:
+
+- **1 task = 1 file cluster** (touch 1–3 related files; split if >3 distinct areas)
+- **No mixed concerns** (separate UI, data, and infra tasks)
+- **Explicit dependencies only** (if a task needs outputs from another, list it in `Depends`)
+- **Avoid shared-file contention** (if two tasks touch the same file, either merge or serialize)
+- **Target wave size ≥ 6 tasks** for plans intended to run with 6–8 agents
+
+**Split tasks when**:
+
+- A task mixes **setup + implementation + refactor** in one block
+- It touches **multiple packages** without a clear sequencing need
+- It includes both **schema changes** and **feature code**
+- It bundles **tests** for multiple components (split per component)
+
+**Merge tasks when**:
+
+- Two tasks always touch the **same files**
+- One task is only **a tiny follow-up** (e.g., rename, lint fix) for another
+- Dependencies create a chain with no parallelism
+
+### The Blueprint Task Template (Mandatory)
+
+Every task MUST follow this exact structure:
+
+```markdown
+#### [lane] Task X.Y: [Component Name]
+
+**Status:** todo
+
+**Depends:** Task 1.1, Task 1.2 (or "None" for Tier 0)
+
+[Description paragraph — enough context for an independent agent to execute
+without reading other tasks. Include: what, why, constraints, gotchas.]
+
+**Files:**
+
+- Create: `exact/path/to/file.ts`
+- Create: `exact/path/to/file.test.ts`
+- Modify: `exact/path/to/existing.ts`
+
+**Steps (TDD):**
+
+1. Write failing test for [specific behavior]
+2. Run: `wp test --files <path/to/test-file.test.ts>` — verify the current contract
+3. Implement minimal code to pass
+4. Run: `wp test --files <path/to/test-file.test.ts>` — verify PASS
+5. Refactor if needed (complexity ≤ 8)
+6. Run: `wp lint --files <changed-file.ts> <changed-test.ts>` and `wp typecheck --files <changed-file.ts> <changed-test.ts>`
+
+**Acceptance:**
+
+- [ ] Positive contract test covers the requested behavior
+- [ ] Implementation passes all tests
+- [ ] `wp lint --files <changed-files...>` passes
+- [ ] `wp typecheck --files <changed-files...>` passes
+```
+
+Use `#### Task X.Y: ...` only when a lane prefix would add no value, but prefer lane-prefixed headers such as `[schema]`, `[backend]`, `[ui]`, `[infra]`, `[docs]`, or `[qa]`.
+
+### Project Conventions
+
+These are enforced project conventions (with webpresso's conventions as the example):
+
+| Convention           | Rule                                  | Rationale                                                           |
+| -------------------- | ------------------------------------- | ------------------------------------------------------------------- |
+| **Estimates**        | Use t-shirt sizing ONLY (XS/S/M/L/XL) | No day/week estimates — too inaccurate and cause false expectations |
+| **Database Changes** | Follow the repo's preferred workflow  | e.g. `db push` before production launch, migrations after           |
+
+**Violations to flag:**
+
+- Task says "1 day", "3 hours", "2 weeks" → Change to t-shirt size
+- Task creates migration files or migration infrastructure when the repo prefers `db push` → Use the repo's chosen workflow
+- References a retired database command when the repo uses `db push` → Use `db push` (entity YAML → schema generation → push)
+
+### Blueprint Validation Checklist
+
+Run this audit on every task in the blueprint:
+
+| Check                             | Violation                                            | Fix                                                      |
+| --------------------------------- | ---------------------------------------------------- | -------------------------------------------------------- |
+| Has `**Depends:**` line?          | Missing → parallel execution can't build DAG         | Add explicit dependency or "None"                        |
+| Has `**Files:**` section?         | Missing → agents can't detect file conflicts         | List every file touched (Create/Modify)                  |
+| Has `**Steps (TDD):**`?           | Missing → agents skip tests                          | Add positive verification steps with exact `wp` commands |
+| Has `**Acceptance:**` checkboxes? | Missing → no completion criteria                     | Add testable acceptance criteria                         |
+| Description self-contained?       | References "see above" or "as described in Task X.Y" | Inline the context — each task runs independently        |
+| Files overlap with another task?  | Two tasks modify same file → conflict in parallel    | Merge tasks or add explicit `**Depends:**`               |
+| Uses t-shirt sizing?              | Day/week estimates used                              | Replace with XS/S/M/L/XL                                 |
+| Follows repo DB workflow?         | Diverges from repo's chosen workflow                 | Use repo's chosen workflow instead                       |
+
+### Granularity Rules
+
+**The Goldilocks Zone:** Each task should be **XS-S size** (single focused change with tests). Smaller = overhead. Larger = blocks other work.
+
+#### Too Coarse (Split It)
+
+```markdown
+BAD: "Implement sync engine with push, pull, and connection manager"
+```
+
+This is 3+ independent concerns. An agent working on this blocks 30+ minutes while push, pull, and connection could all run in parallel.
+
+```markdown
+GOOD: Split into:
+Task 3.1: Push engine (client-side) Depends: 2.3
+Task 3.2: Pull engine (client-side) Depends: 1.2
+Task 4.2: WebSocket auth proxy Depends: None
+Task 5.1: Connection manager + orchestrator Depends: 3.1, 3.2, 4.1, 4.2
+```
+
+#### Too Fine (Merge It)
+
+```markdown
+BAD:
+Task 1.1a: Create package.json for sync package
+Task 1.1b: Create tsconfig.json for sync package
+Task 1.1c: Add subpath exports to package.json
+```
+
+These can't be tested independently and have no value as separate agent work.
+
+```markdown
+GOOD: "Task 1.2: Scaffold sync package + local DB"
+— package.json, tsconfig, exports, db client, tests — all one task
+```
+
+### Splitting Rules
+
+| Signal                                       | Action                                    |
+| -------------------------------------------- | ----------------------------------------- |
+| Task touches 3+ unrelated files              | Split into independent tasks              |
+| Task has "and" in the title                  | Split at the "and"                        |
+| Task is M or larger                          | Split by concern (data layer, API, tests) |
+| Two subtasks have no data dependency         | They should be separate tasks             |
+| Task can't start until 3+ other tasks finish | Check if some deps are artificial         |
+
+### Merging Rules
+
+| Signal                                            | Action                                 |
+| ------------------------------------------------- | -------------------------------------- |
+| Task is XS with no tests                          | Merge with related task                |
+| Task creates a file that only one other task uses | Merge into that task                   |
+| Three tasks all modify the same file              | Merge or serialize them                |
+| Task has no test (pure config/scaffold)           | Merge with the first task that uses it |
+
+### Dependency Graph Optimization
+
+**Goal:** Maximize the width of each wave (more tasks in parallel = faster execution).
+
+#### Wave Analysis
+
+```
+Wave 0 (Tier 0): Tasks with no dependencies     → All run in parallel
+Wave 1 (Tier 1): Tasks depending only on Wave 0  → Run as Wave 0 completes
+Wave 2 (Tier 2): Tasks depending on Wave 0+1     → Run as deps clear
+...
+```
+
+**Metric: Critical path length** — The longest chain of sequential dependencies. This is the minimum wall-clock time regardless of how many agents you throw at it.
+
+### State-of-the-Art Parallelization Metrics (Required)
+
+Use these metrics when refining or challenging a blueprint:
+
+1. **Ready Width (RW)**
+   - Number of runnable tasks at each wave.
+   - Target: first two waves should keep planned agents busy (for 6 agents, RW ≥ 6 in Wave 0 or Wave 1).
+
+2. **Critical Path Ratio (CPR)**
+   - `CPR = total_tasks / critical_path_length`
+   - Higher is better (more theoretical parallel speedup).
+   - Target: CPR ≥ 2.5 for parallel plans.
+
+3. **Dependency Density (DD)**
+   - `DD = total_dependency_edges / total_tasks`
+   - Lower is usually better (fewer coordination constraints).
+   - Target: DD ≤ 2.0 unless architecture requires strict sequencing.
+
+4. **Conflict Pressure (CP)**
+   - Count of same-file overlaps across tasks in the same wave.
+   - Hard target: CP = 0 for every wave.
+
+If metrics miss target, refine task granularity or dependency design before execution.
+
+#### Optimization Techniques
+
+1. **Break false dependencies.** If Task 2.1 "depends on" Task 1.2 but only needs the _interface_ (not the implementation), extract the interface into a Tier 0 task.
+
+2. **Parallelize within phases.** If Phase 2 has 3 tasks that all depend on Phase 1 but not on each other, they should all be in the same wave.
+
+3. **Front-load independent work.** Move tasks that don't depend on anything to Wave 0 — they start immediately.
+
+4. **Minimize the fan-in bottleneck.** If Task 5.1 depends on Tasks 3.1, 3.2, 4.1, and 4.2 — that's 4 tasks that must ALL complete before 5.1 starts. Ask: can any of 5.1's work start earlier?
+
+#### File Conflict Detection
+
+Two tasks running in parallel MUST NOT modify the same file. If they do:
+
+1. **Preferred:** Restructure so each task has its own files
+2. **Acceptable:** Add explicit `**Depends:**` to serialize them
+3. **Last resort:** Document the conflict in the Quick Reference table
+
+### Quick Reference Table (Required)
+
+Every refined blueprint MUST include this table for parallel execution (`/goal` autopilot, `ultragoal`):
+
+```markdown
+## Quick Reference (Execution Waves)
+
+| Wave              | Tasks                             | Dependencies     | Parallelizable | Effort (T-shirt) |
+| ----------------- | --------------------------------- | ---------------- | -------------- | ---------------- |
+| **Wave 0**        | 1.1, 1.2, 1.3                     | None             | 3 agents       | XS-S             |
+| **Wave 1**        | 2.1, 2.2, 2.3                     | Wave 0           | 3 agents       | S-M              |
+| **Wave 2**        | 3.1, 3.2, 4.2                     | Wave 1 (partial) | 3 agents       | S-M              |
+| **Wave 3**        | 4.1, 5.1                          | Wave 2           | 2 agents       | M                |
+| **Wave 4**        | 6.1                               | Wave 3           | 1 agent        | S                |
+| **Critical path** | 1.1 → 2.3 → 3.1 → 4.1 → 5.1 → 6.1 | —                | 6 waves        | L                |
+
+### Parallel Metrics Snapshot (Required)
+
+| Metric | Formula / Meaning                  | Target               | Actual  |
+| ------ | ---------------------------------- | -------------------- | ------- |
+| RW0    | Ready tasks in Wave 0              | ≥ planned agents / 2 | <value> |
+| CPR    | total_tasks / critical_path_length | ≥ 2.5                | <value> |
+| DD     | dependency_edges / total_tasks     | ≤ 2.0                | <value> |
+| CP     | same-file overlaps per wave        | 0                    | <value> |
+
+If any target misses, include a short "refinement delta" note describing task split/merge changes.
+```
+
+### Parallelization Score
+
+Rate the plan's parallelizability:
+
+| Score | Definition                            | Action                              |
+| ----- | ------------------------------------- | ----------------------------------- |
+| **A** | RW target met, CPR ≥ 2.5, CP = 0      | Ready for parallel execution        |
+| **B** | RW near target, CPR 2.0-2.49, CP = 0  | Improve dependencies before execute |
+| **C** | CPR 1.5-1.99 or frequent narrow waves | Split coarse tasks, reduce fan-in   |
+| **D** | CPR < 1.5 or CP > 0 in planned waves  | Must restructure before execution   |
+
+### Self-Contained Task Test
+
+For each task, ask: **"Can an agent execute this task with ONLY the task description, the codebase, and the repository's `wp` commands?"**
+
+If the answer is no, the task is missing context. Common fixes:
+
+- Inline interface definitions (don't say "use the interface from Task 1.1")
+- Include the schema/type the task needs to implement
+- Specify exact import paths
+- Include example input/output for test cases
+
+---
+
+## Phase 6: Apply & Consolidate
+
+**Goal:** Write all fixes into the blueprint as a single coherent update.
+
+### Fix Tagging Convention
+
+Every fix gets an `(Fx)` tag that appears:
+
+1. In the inline task where the fix is applied
+2. In the Edge Cases table
+3. In the Risks table (if applicable)
+4. In the Technology Choices table (if applicable)
+
+This creates **traceability** — anyone reading the blueprint can trace why a particular decision was made back to the fact-check finding.
+
+### Required Updates
+
+After applying all fixes, verify:
+
+- [ ] **Blueprint format** — Every task has Depends, Files, Steps (TDD), Acceptance
+- [ ] **Self-contained tasks** — Each task can be executed by an independent agent
+- [ ] **Engineering principles** — DRY, SOLID, YAGNI, and KISS are applied; unnecessary abstractions, dependencies, and config are removed
+- [ ] **Public package safety** — Plans that touch package or release surfaces include tarball/package-surface leak checks and denied-content exclusions
+- [ ] **No file conflicts** — No two parallel tasks modify the same file
+- [ ] **Quick Reference table** — Updated with correct waves and agent counts
+- [ ] **Edge Cases table** — Every finding with severity ≥ MEDIUM has a row
+- [ ] **Risks table** — Every finding with severity ≥ HIGH has a row with mitigation
+- [ ] **Technology Choices table** — Any library/tool changes reflected
+- [ ] **Key Decisions table** — Any decision changes reflected with rationale
+- [ ] **Cross-Plan References** — Downstream plans updated if affected
+- [ ] **Progress field** — Updated to note fact-check completion
+- [ ] **Architecture diagram** — Updated if technology names changed
+
+### Verification Report
+
+At the end, produce a summary:
+
+```markdown
+## Refinement Summary
+
+| Metric                    | Value                 |
+| ------------------------- | --------------------- |
+| Findings total            | 20                    |
+| Critical                  | 3                     |
+| High                      | 5                     |
+| Medium                    | 8                     |
+| Low                       | 4                     |
+| Fixes applied             | 20/20                 |
+| Cross-plans updated       | 2                     |
+| Edge cases documented     | 15                    |
+| Risks documented          | 12                    |
+| **Parallelization score** | B (5 tasks in Wave 0) |
+| **Critical path**         | 6 waves (~90 min)     |
+| **Max parallel agents**   | 3                     |
+| **Total tasks**           | 11                    |
+| **Blueprint compliant**   | 11/11                 |
+```
+
+---
+
+## Red Flags — STOP
+
+Stop and escalate to the user if:
+
+- A CRITICAL finding invalidates the core architecture (e.g., the chosen database doesn't work on the target runtime)
+- Two findings contradict each other (fix A requires X, fix B requires not-X)
+- A cross-plan dependency is broken and requires re-planning
+- The number of CRITICAL + HIGH findings exceeds 10 (plan may need fundamental rethinking)
+- A technology assumption affects more than 3 tasks (cascading rewrite needed)
+- Parallelization score is **D** (1 task in Wave 0) — plan needs fundamental restructure
+- Any material claim still lacks a **code pinpoint** or **official-doc + version** after a full pass (confidence ≠ 100%)
+- The “ready” design is only correct, not the most **elegant / durable / efficient** option under constraints
+
+## Parallel Agent Strategy
+
+The refinement pipeline itself **must** maximize concurrency:
+
+| Lane | Phase                    | Tools                                   | Focus                                                   |
+| ---- | ------------------------ | --------------------------------------- | ------------------------------------------------------- |
+| A    | Technology fact-check    | WebSearch, WebFetch, Context7, registry | Official latest docs, version-pinned APIs               |
+| B    | Codebase verification    | Grep, Glob, Read                        | Path + symbol pinpoints, 0 assumptions                  |
+| C    | Architecture review      | Blueprint + evidence from A/B           | Races, elegance, durability, efficiency                 |
+| D    | Review lenses (optional) | plan-*-review skills                    | CEO / design / eng / DevEx in parallel when independent |
+
+**Lanes A–C(/D) run in parallel.** Phases 4–6 (cross-plan, blueprint enforcement, apply) run after their inputs land — not after an artificial full serial wait when a subset already unblocks the next edit.
+
+**Do not** refine serially “for simplicity” when claims partition cleanly (external vs local vs architecture).
+
+## Related Skills
+
+- **plan** — Creating plans (this skill refines them)
+- **question-flow** — Supported user-input pattern for plan clarification
+- **testing-philosophy** — Test strategy validation within plans (integration-first, 85% mutation)
+- **verify** — Evidence-based completion and post-implementation verification
+- **systematic-debugging** — When refinement finds broken assumptions
+
+## Related Commands
+
+- `wp blueprint new "<goal>" --complexity <size>` — Create a new blueprint (this skill refines it)
+- `wp blueprint audit --all --strict` — Audit blueprint format/lifecycle before or after refinement
+- `/goal` (autopilot) / `ultragoal` — Operator-facing parallel execution workflow for refined Blueprint-shaped work
+- `/verify <target>` — Post-implementation quality gate
+- `/soa <target>` — Apply SOA 2026 quality standards (TDD, complexity ≤8, mutation ≥85%)
+
+**Parallel Execution:** Refined plans should execute through the current workflow surface while Blueprint remains the durable lifecycle source of truth via `wp blueprint start|task|finalize`. See the `autopilot` and `ultragoal` skills for the current operator guidance.
+
+## Planned eligibility verdict
+
+Before declaring a blueprint planned-eligible, complete its Trust Dossier, evidence material claims, close material decisions, define Promotion Gates, and emit exactly one verdict: `planned-eligible` or `not-planned-eligible`. Reject speculative abstractions, unverifiable material claims, and "decide during implementation" placeholders. Blueprints implementing this gate before it lands may document that the dossier becomes required once the gate exists.