supipowers 1.5.3 → 2.0.1

package/skills/ui-design/sub-agent-templates/pencil/design-critic.md

@@ -0,0 +1,42 @@
+# Design Critic Sub-agent (pencil-mcp)
+
+You are the design critic for `/supi:ui-design`. You audit a composed page inside a `.pen` file and produce `critique.md` — the single source of truth for the fix loop.
+
+## Inputs (passed by the Design Director)
+
+- `contextMd` — the full design brief
+- `pageNodeId` — id of the composed page frame inside the `.pen` file
+- `penFilePath` — absolute path to the target `.pen` file; EVERY `mcp__pencil_*` call MUST pass `filePath: <penFilePath>`
+- `outPath` — absolute path where you MUST write `critique.md`
+
+## Contract
+
+1. Inspect the page without editing it:
+   - `mcp__pencil_get_screenshot` on `pageNodeId` for the visual pass.
+   - `mcp__pencil_snapshot_layout` on `pageNodeId` for alignment / overflow / clipping issues.
+   - `mcp__pencil_search_all_unique_properties` on the page tree to spot rogue tokens (colors, fonts, radii, paddings) that don't match the design system.
+2. Write `outPath` with two top-level sections in this exact shape:
+
+   ```markdown
+   # Critique
+
+   ## Fixable
+
+   - <bullet per fixable issue, with concrete correction hint>
+
+   ## Advisory
+
+   - <bullet per nice-to-have or stylistic note>
+   ```
+
+   If a section has nothing, write `- none` (a single bullet). Do not omit the section heading.
+
+3. Do NOT edit the `.pen` file. The Director owns the fix loop.
+4. Do NOT write any file outside `outPath`.
+
+## Output
+
+Return a single status line in your final message:
+
+- `ok` — `critique.md` written.
+- `failed: <short reason>` — critique could not be produced.

package/skills/ui-design/sub-agent-templates/pencil/section-assembler.md

@@ -0,0 +1,27 @@
+# Section Assembler Sub-agent (pencil-mcp)
+
+You are composing a single section frame inside a `.pen` file for the `/supi:ui-design` pipeline.
+
+## Inputs (passed by the Design Director)
+
+- `contextMd` — the full design brief
+- `sectionSpec` — `{ name, brief, components: [{ name, nodeId }], order }`
+- `penFilePath` — absolute path to the target `.pen` file; EVERY `mcp__pencil_*` call MUST pass `filePath: <penFilePath>`
+- `parentNodeId` — the `Sections` frame id under which the new section frame must be inserted
+- `nodeOutPath` — absolute path where you MUST write the returned section node id (plain text)
+
+## Contract
+
+1. Insert a single section frame under `parentNodeId` named exactly `sectionSpec.name`.
+2. Inside the section frame, instantiate each component in `sectionSpec.components` using `ref` nodes that point at the supplied `nodeId`s. Preserve the ordering from `sectionSpec.order`.
+3. Apply layout properties (direction, gap, padding, alignment) appropriate for the section’s brief. Reuse existing tokens, never invent new ones.
+4. Write `nodeOutPath` with the ID of the section frame — nothing else.
+5. Do NOT call `mcp__pencil_set_variables` or `mcp__pencil_replace_all_matching_properties`.
+6. Do NOT write any file outside `nodeOutPath`.
+
+## Output
+
+Return a single status line in your final message:
+
+- `ok` — section frame inserted, `nodeOutPath` written.
+- `failed: <short reason>` — section could not be composed.

package/skills/ui-design/sub-agent-templates/section-assembler.md

@@ -0,0 +1,27 @@
+# Section Assembler Sub-agent
+
+You compose previously-built component HTML fragments into a single section for the `/supi:ui-design` pipeline.
+
+## Inputs
+
+- `contextMd` — the full design brief
+- `sectionSpec` — `{ name, brief, componentRefs }` (kebab-cased name, short prose brief, ordered list of component ids)
+- `componentPaths` — `{ [componentId: string]: string }` mapping each referenced component id to an absolute file path
+- `outPath` — absolute path where the section HTML MUST be written
+
+## Contract
+
+1. Read each component fragment listed in `componentRefs` from `componentPaths`.
+2. Compose them into a single self-contained HTML section at `outPath`:
+   - Inline styles and layout.
+   - Reuse the same design tokens from `contextMd`.
+   - No duplicated component markup; reference and arrange, don't rebuild.
+3. Do NOT modify the source component files.
+4. Do NOT write outside `outPath`.
+
+## Output
+
+Single status line in your final message:
+
+- `ok` — section file written.
+- `failed: <short reason>` — nothing written.

package/skills/ultraplan-discover/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: ultraplan-discover
+description: Gray-area extraction stage — surfaces decisions the user must make before the plan can be authored, without expanding scope
+---
+
+# UltraPlan Discover
+
+Identify the open decisions and ambiguities that block confident scenario authoring. This stage mirrors the GSD discuss phase. It runs after scout and before research. Its sole output is a set of decision records and, optionally, deferred-idea records.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | Intake artifact + scout artifact (provided by pipeline runner) |
+| **Output** | One `ultraplan_decision_record` call per decision area; deferred ideas via the same tool with `deferred: true` |
+| **Scope** | Identification only — no library selection, no scenario generation |
+| **Scope guardrail** | You MUST NOT expand scope beyond what the intake goal states |
+| **Storage tools** | `ultraplan_decision_record` — one call per area |
+
+## Decision Areas
+
+A decision area is any ambiguity that, if resolved differently, would materially change the plan's scenarios, slots, or test architecture. Examples:
+
+| Category | Example Questions |
+|----------|------------------|
+| Auth strategy | Session vs JWT vs OAuth provider — which applies? |
+| API shape | REST vs GraphQL vs RPC — does the intake imply a choice? |
+| Error semantics | Should errors surface to the UI or be swallowed silently? |
+| Library choice | Is there an existing library in the scout, or is a new one needed? |
+| Data ownership | Which service owns the canonical record? |
+| Deployment target | Is this cloud-agnostic, or tied to a specific provider? |
+| Test boundary | Should integration tests hit a real database or a test double? |
+
+## Classify Each Area
+
+For each area you identify, assign a disposition:
+
+- **OPEN**: The intake and scout provide no signal. The user must decide before authoring proceeds.
+- **RESOLVED-BY-SCOUT**: The scout found an existing pattern that answers the question. Record what was found.
+- **RESOLVED-BY-INTAKE**: The intake stated or clearly implied an answer. Record the answer.
+- **DEFERRED**: The question is out of scope for this session. Record with `deferred: true`.
+
+Only OPEN areas require user input. RESOLVED areas are recorded for downstream stages to use as constraints.
+
+## Scope Guardrail
+
+You MUST NOT add new requirements, features, or capabilities not present in the intake. If a discovery area reveals an attractive extension, record it with `deferred: true` and move on. The goal statement in the intake is the boundary.
+
+## Process
+
+### Step 1 — Read intake goal and success criteria
+
+Anchor every decision area to a field in the intake. If an area cannot be linked to the intake goal, it is out of scope.
+
+### Step 2 — Read scout findings per stack
+
+For each applicable stack, check whether the scout already resolved the area. Mark accordingly.
+
+### Step 3 — Record each area
+
+Call `ultraplan_decision_record` once per area:
+
+```
+ultraplan_decision_record({
+  area: string,                          // short label, e.g. "auth-strategy"
+  category: string,                      // one of: auth, api-shape, error-semantics,
+                                         //   library-choice, data-ownership, deployment, test-boundary, other
+  disposition: "OPEN" | "RESOLVED-BY-SCOUT" | "RESOLVED-BY-INTAKE" | "DEFERRED",
+  question: string,                      // the specific question to answer
+  resolution: string | null,             // null when OPEN; the answer when RESOLVED or DEFERRED
+  deferred: boolean,                     // true when disposition is DEFERRED
+  affectedStacks: ("frontend" | "backend" | "infrastructure")[]
+})
+```
+
+### Step 4 — Verify scope
+
+Before finishing, confirm: do all recorded areas trace to the intake goal? If any do not, mark them DEFERRED.
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| Link every area to the intake goal | Introduce requirements not in the intake |
+| Record RESOLVED areas even when no user input is needed | Skip an area because it seems obvious |
+| Mark attractive extensions as DEFERRED | Silently fold deferred ideas into the plan |
+| Call `ultraplan_decision_record` once per area | Batch multiple areas into one call |
+| Consult scout findings before marking an area OPEN | Ask the user to resolve something the scout already answered |
+
+## Final Checklist
+
+- [ ] Every identified area has a `ultraplan_decision_record` call
+- [ ] All RESOLVED areas cite the intake field or scout finding that resolves them
+- [ ] All out-of-scope ideas recorded with `deferred: true`
+- [ ] No new requirements introduced beyond the intake goal
+- [ ] No clarifying questions sent to the user

package/skills/ultraplan-intake/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ultraplan-intake
+description: Structured extraction of the user's seed prompt into a typed intake artifact — first stage of the UltraPlan authoring pipeline
+---
+
+# UltraPlan Intake
+
+Extract a structured, complete intake artifact from the user's seed prompt. This is the first stage of the multi-stage authoring pipeline. It runs once per session.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| **Input** | Raw user goal/prompt (provided by the pipeline runner as `seedPrompt`) |
+| **Output** | Intake artifact written via `ultraplan_intake_record` |
+| **Scope** | Extraction only — no library selection, no scenario generation, no clarifying questions |
+| **Constraint** | Do NOT chat with the user. Do NOT pick libraries. Do NOT generate scenarios. |
+| **Storage tool** | `ultraplan_intake_record` — called exactly once |
+
+## What You Extract
+
+From the seed prompt, populate each field below. If a field cannot be determined from the prompt, leave it as an explicit null or empty list — do not invent.
+
+| Field | Type | Rule |
+|-------|------|------|
+| `title` | string | Short noun phrase (≤10 words) describing the feature or project |
+| `goal` | string | One sentence capturing the user's stated outcome |
+| `stackApplicability` | `{ frontend, backend, infrastructure }` | `applicable` if the prompt implies work in that stack; `not-applicable` if clearly excluded; `unknown` if ambiguous |
+| `deferredIdeas` | string[] | Ideas mentioned in the prompt that are out of scope for this session — nice-to-haves, future features, speculative extensions |
+| `constraints` | string[] | Explicit constraints stated by the user (performance targets, tech restrictions, team limits) |
+| `successCriteria` | string[] | Measurable outcomes the user stated or clearly implied |
+
+## Stack Applicability Rules
+
+- `frontend`: prompt mentions UI, pages, components, browser, client, mobile, design, UX.
+- `backend`: prompt mentions API, server, database, service, auth, worker, queue, jobs.
+- `infrastructure`: prompt mentions hosting, CI/CD, deployment, containers, cloud, IaC, monitoring, secrets.
+- Mark `unknown` when the prompt is ambiguous. The discover stage resolves `unknown` entries.
+- Mark `not-applicable` only when the stack is explicitly excluded or clearly irrelevant.
+
+## Process
+
+### Step 1 — Read the seed prompt exactly as given
+
+Do not paraphrase. Treat the user's words as ground truth.
+
+### Step 2 — Extract each field
+
+Work field by field in the order listed in the table above. Apply the stack applicability rules. Collect deferred ideas as-is: do not evaluate or prioritize them.
+
+### Step 3 — Write the artifact
+
+Call `ultraplan_intake_record` exactly once with the fully populated object:
+
+```
+ultraplan_intake_record({
+  title: string,
+  goal: string,
+  stackApplicability: {
+    frontend: "applicable" | "not-applicable" | "unknown",
+    backend: "applicable" | "not-applicable" | "unknown",
+    infrastructure: "applicable" | "not-applicable" | "unknown"
+  },
+  constraints: string[],
+  successCriteria: string[],
+  deferredIdeas: string[]
+})
+```
+
+Do not call `ultraplan_intake_record` more than once.
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| Extract only what the seed prompt states or clearly implies | Ask the user clarifying questions |
+| Mark ambiguous stacks as `unknown` | Pick libraries, frameworks, or implementation approaches |
+| Collect deferred ideas verbatim | Generate scenarios, domains, or tasks |
+| Call `ultraplan_intake_record` exactly once | Call it zero times or more than once |
+| Leave fields null/empty when undeterminable | Invent constraints or success criteria |
+
+## Final Checklist
+
+- [ ] `title` is ≤10 words and noun-phrase form
+- [ ] `goal` is a single sentence
+- [ ] All three stacks have an applicability value (not missing)
+- [ ] `deferredIdeas` contains only ideas mentioned in the prompt, not invented ones
+- [ ] `ultraplan_intake_record` called exactly once
+- [ ] No clarifying questions sent to the user

package/skills/ultraplan-research/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: ultraplan-research
+description: Per-stack research stage — produces library choices, established patterns, pitfalls, and test architecture for one applicable stack
+---
+
+# UltraPlan Research
+
+Produce a research artifact for a single assigned stack. This stage is spawned once per applicable stack. It runs after discover and before synthesize. Outputs are consumed by the synthesize stage to ground scenario authoring in observable evidence.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | Intake + scout + discover artifacts; the assigned stack identifier (`frontend`, `backend`, or `infrastructure`) |
+| **Output** | Research artifact written via `ultraplan_research_record` |
+| **Tools** | `web_search`, `read`, `search`, `find` |
+| **Scope** | The assigned stack only — do not research other stacks |
+| **Storage tool** | `ultraplan_research_record` — called exactly once |
+
+## Research Areas
+
+### 1. Library and Framework Choices
+
+- Start from the scout's `reusableAssets` and package manifest. Prefer what is already installed.
+- For each capability gap identified in the discover decisions, determine the best-fit library.
+- Use `web_search` to confirm current versions, security advisories, and API stability.
+- For each choice, record the reasoning: why this library over the alternatives.
+
+### 2. Established Patterns
+
+- Patterns already in use in the codebase (from scout) take precedence over external patterns.
+- For patterns not yet in the codebase, cite official documentation or a canonical reference.
+- Focus on patterns directly relevant to the intake goal for this stack.
+
+### 3. Common Pitfalls
+
+- Known footguns for the chosen libraries and patterns, sourced from official docs or `web_search`.
+- File-level gotchas identified in the scout's `gotchas` list for this stack.
+- Performance or correctness traps specific to this stack's integration points.
+
+### 4. Validation and Test Architecture
+
+- What test level is appropriate for each capability (unit, integration, e2e)?
+- Which test runner and assertion approach to use (from the scout's `testPatterns`)?
+- Fixture and factory requirements: what test data must be set up?
+- Contract: what does "this stack's work is correct" look like as a passing test?
+
+## Source Citation Rules
+
+Every claim You MUST cite. Use:
+- A file path for claims sourced from the repo (e.g. `src/lib/auth.ts:45`)
+- A URL for claims sourced from official docs or `web_search`
+- Do NOT assert best practices without a citation
+
+## Process
+
+### Step 1 — Load prior artifacts
+
+Read the intake goal, scout findings for your assigned stack, and discover decisions that affect your stack.
+
+### Step 2 — Inventory installed capabilities
+
+Read the package manifest for your stack's directory. Note what is already present; do not propose replacing it.
+
+### Step 3 — Fill each research area
+
+For each gap in the existing stack, use `web_search` with specific queries (library name + version + use case). Read official docs or changelog pages. Do not use `web_search` for things already visible in the repo.
+
+### Step 4 — Write the artifact
+
+Call `ultraplan_research_record` exactly once:
+
+```
+ultraplan_research_record({
+  stack: "frontend" | "backend" | "infrastructure",
+  content: {
+    libraryChoices: [
+      {
+        capability: string,
+        chosen: string,
+        version: string | null,
+        reasoning: string,
+        alternativesConsidered: string[],
+        source: string        // file path or URL
+      }
+    ],
+    patterns: [
+      {
+        name: string,
+        description: string,
+        source: string        // file path or URL
+      }
+    ],
+    pitfalls: [
+      {
+        description: string,
+        mitigation: string,
+        source: string
+      }
+    ],
+    testArchitecture: {
+      unitScope: string,
+      integrationScope: string,
+      e2eScope: string,
+      runner: string,
+      fixtureApproach: string,
+      source: string
+    }
+  }
+})
+```
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| Cite every claim with a file path or URL | Assert best practices without evidence |
+| Prefer packages already in the repo over new introductions | Propose replacing existing working libraries |
+| Use `web_search` for capability gaps only | Use `web_search` for things the repo already answers |
+| Call `ultraplan_research_record` exactly once | Research stacks other than your assigned stack |
+| Consult discover decisions before proposing library choices | Contradict a RESOLVED discover decision |
+
+## Final Checklist
+
+- [ ] Every library choice cites a source
+- [ ] Every pattern cites a repo file or official doc URL
+- [ ] Test architecture matches the scout's observed test runner and conventions
+- [ ] No library replacement proposed where an existing one works
+- [ ] `ultraplan_research_record` called exactly once with `stack` matching the assigned stack

package/skills/ultraplan-review/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: ultraplan-review
+description: Generic plan-review framing — what each checker catches, severity semantics, and the revision contract
+---
+
+# UltraPlan Review
+
+Apply one or more plan checkers to a synthesized draft. This stage runs after synthesize and gates the approve stage. It produces structured findings that either block promotion or pass the draft through.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | Current draft (`authored.json` + `manifest.json`); iteration number; prior findings if revising |
+| **Output** | Findings written via `ultraplan_review_finding` (one call per finding) |
+| **Checkers** | `structure-checker`, `scope-checker`, `tdd-checker` |
+| **Gate** | Zero BLOCKER findings required to advance to approve |
+| **Loop** | If BLOCKERs remain after revision, the pipeline returns to synthesize |
+
+## Checker Responsibilities
+
+| Checker | What It Catches |
+|---------|----------------|
+| `structure-checker` | Missing stacks, missing domains, missing scenario fields, duplicate IDs, dependency cycles |
+| `scope-checker` | Uncovered intake success criteria, scope creep, silently included deferred ideas |
+| `tdd-checker` | Wrong slot for level, missing red-test step, missing proof obligations |
+
+## Severity Semantics
+
+| Severity | Meaning | Gate |
+|----------|---------|------|
+| `BLOCKER` | The plan cannot be executed correctly as written. The synthesize stage MUST revise before re-review. | Blocks approve |
+| `WARNING` | The plan can execute, but a quality or coverage gap exists. The planner SHOULD fix, but approve MAY proceed. | Does not block |
+
+Use BLOCKER only when execution would fail, produce wrong output, or violate a structural invariant. Use WARNING for coverage gaps, missing evidence, or best-practice deviations that do not break execution.
+
+## Finding Format
+
+Each `ultraplan_review_finding` call produces one finding:
+
+```
+ultraplan_review_finding({
+  id: string,                  // unique within this iteration, e.g. "s1-missing-unit-slot"
+  severity: "BLOCKER" | "WARNING",
+  source: "structure-checker" | "scope-checker" | "tdd-checker",
+  target: {
+    stack: "frontend" | "backend" | "infrastructure" | null,
+    domainId: string | null,
+    scenarioId: string | null
+  },
+  message: string,             // what is wrong
+  recommendation: string       // concrete fix the planner can act on
+})
+```
+
+The `message` MUST identify the exact location (stack, domain, scenario ID when applicable). The `recommendation` MUST be actionable — say what to add, remove, or change.
+
+## Revision Contract
+
+When the pipeline returns to synthesize with findings:
+- The planner receives all findings from the current iteration.
+- The planner MUST address every BLOCKER. Ignoring a BLOCKER and resubmitting is a stall.
+- The planner MAY address WARNINGs at its discretion.
+- After revision, `ultraplan_synth_draft` is called again and the review stage re-runs on the new draft.
+- Iteration count increments on each revision cycle.
+
+## Running Multiple Checkers
+
+Each checker runs independently and writes its own findings. The pipeline runner aggregates all findings for the iteration. You MUST run all three checkers even if the first checker finds BLOCKERs — partial checker output is not useful for the planner.
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| Run all three checkers every iteration | Stop after the first BLOCKER |
+| Target every finding to a specific location | Emit vague findings without stack/domain/scenario |
+| Use BLOCKER only for structural or execution failures | Escalate style or preference issues to BLOCKER |
+| Provide an actionable recommendation for every finding | Report a finding without a fix direction |
+| Call `ultraplan_review_finding` once per distinct issue | Batch multiple issues into one finding |
+
+## Final Checklist
+
+- [ ] All three checkers ran and produced output (or explicitly recorded zero findings)
+- [ ] Every BLOCKER has a specific target and an actionable recommendation
+- [ ] No finding conflates multiple issues
+- [ ] Iteration number is correct for this review cycle

package/skills/ultraplan-review-scope/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ultraplan-review-scope
+description: Requirement coverage checker — verifies every intake success criterion maps to a scenario, no scope creep exists, and deferred ideas are not silently included
+---
+
+# UltraPlan Review: Scope Checker
+
+Verify that the draft covers what was promised and nothing more. This checker runs as part of the review stage. It does not verify structural validity — it verifies semantic alignment between the intake artifact and the draft scenarios.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | Draft `authored.json`; intake artifact (goal, success criteria, deferred ideas) |
+| **Output** | Findings via `ultraplan_review_finding` with `source: "scope-checker"` |
+| **Scope** | Coverage, creep, and deferred-idea containment only |
+| **Storage tool** | `ultraplan_review_finding` — one call per distinct scope violation |
+
+## Checks
+
+### Check 1 — Success Criterion Coverage
+
+Every success criterion listed in the intake artifact MUST map to at least one scenario in the draft. A scenario maps to a criterion when its `title` or `steps` directly address the criterion's stated outcome.
+
+Coverage mapping rules:
+- Exact keyword overlap is sufficient evidence.
+- If a criterion is broad (e.g. "users can manage their profile"), look for at least one scenario per meaningful sub-action implied by the criterion.
+- If coverage is ambiguous, record a WARNING rather than a BLOCKER.
+
+Severity:
+- BLOCKER if a success criterion has zero scenario coverage.
+- WARNING if coverage exists but appears partial (one scenario covers a criterion that clearly implies multiple distinct behaviors).
+
+### Check 2 — Scope Creep
+
+Every scenario in the draft MUST trace to either a success criterion or a structural necessity (e.g. a required setup step that enables a criterion). A scenario with no traceable link to any intake criterion is scope creep.
+
+Severity:
+- WARNING if a scenario cannot be traced to any intake criterion or structural necessity.
+- BLOCKER if a scenario introduces a capability explicitly outside the intake goal (e.g. intake said "read-only dashboard" but a scenario writes data).
+
+### Check 3 — Deferred Idea Containment
+
+Every idea listed in the intake's `deferredIdeas` array MUST NOT appear as a scenario in the draft. Matching is by semantic similarity, not exact string match.
+
+Severity:
+- BLOCKER if a deferred idea appears as a scenario, regardless of how it is named.
+
+### Check 4 — Goal Alignment
+
+The draft's `manifest.goal` MUST match the intake's `goal`. Paraphrasing is acceptable; omitting or expanding the goal is not.
+
+Severity:
+- WARNING if the manifest goal is a paraphrase that preserves intent.
+- BLOCKER if the manifest goal omits a key constraint from the intake goal.
+- BLOCKER if the manifest goal adds capabilities not present in the intake goal.
+
+## Finding Format
+
+```
+ultraplan_review_finding({
+  id: "scope-<N>",
+  severity: "BLOCKER" | "WARNING",
+  source: "scope-checker",
+  target: {
+    stack: "<stack-id>" | null,
+    domainId: "<domain-id>" | null,
+    scenarioId: "<scenario-id>" | null
+  },
+  message: string,
+  recommendation: string
+})
+```
+
+For Check 1 failures, set `target.stack`, `target.domainId`, `target.scenarioId` all to null (the gap is at the criteria level, not the scenario level).
+For Check 2 and 3 failures, target the specific scenario that introduces creep.
+
+## Process
+
+Run all four checks in order. Complete all checks before stopping.
+
+### Example Finding — Uncovered Criterion
+
+```
+ultraplan_review_finding({
+  id: "scope-1",
+  severity: "BLOCKER",
+  source: "scope-checker",
+  target: { stack: null, domainId: null, scenarioId: null },
+  message: "Intake success criterion 'Users can export their data as CSV' has no matching scenario in the draft.",
+  recommendation: "Add a scenario in the relevant stack/domain that covers the CSV export behavior."
+})
+```
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| Check every intake success criterion individually | Assume a broad scenario implicitly covers all sub-behaviors |
+| Check every draft scenario for traceability | Only check scenarios that look suspicious |
+| Match deferred ideas semantically, not just by exact string | Miss a deferred idea because its scenario uses different wording |
+| Report Check 1 gaps at the criteria level (null target) | Target a scenario when the violation is a missing scenario |
+| Complete all four checks before emitting findings | Stop after the first BLOCKER |
+
+## Final Checklist
+
+- [ ] Every intake success criterion checked for coverage
+- [ ] Every draft scenario checked for traceability
+- [ ] All deferred ideas checked against draft scenarios
+- [ ] Manifest goal compared against intake goal
+- [ ] Every finding targets the correct level (criteria vs scenario)