wize-dev-kit 0.16.0 → 0.16.1

package/src/method-skills/3-solutioning/wize-tech-vision/workflow.md

@@ -1,43 +1,151 @@
 ---
+
 code: wize-tech-vision
+description: "Use quando o PRD estiver validado e precisar definir o norte técnico: stack family, build-buy-borrow e non-negotiables."
 name: Tech Vision
-phase: 2-to-3-boundary
+phase: 3-solutioning
 owner: wize-agent-solution-strategist   # Nick Fury
-status: stub
+status: ready
 ---
 
 # Tech Vision
 
-**Goal.** State the technical north star in one page. Stack family, language, runtime envelope, build/buy/borrow calls. Not libraries — *shape*.
+**Goal.** State the technical north star in one page. Stack family, runtime envelope, build/buy/borrow calls, non-negotiables. Fury sets the **shape**, not the libraries — Tony fills in inside the frame.
+
+Output lands in `.wize/planning/tech-vision.md`. Tony reads this before drawing architecture. Hill references it when scoping. Hawkeye uses it when picking gate granularity.
+
+## Inputs
+
+- `.wize/planning/prd.md` (validated)
+- `.wize/planning/ux/ux-design/` (so the runtime envelope respects the UX)
+- `.wize/knowledge/document-project/` (brownfield only)
+- Stack catalogs (per active overlay):
+  - `src/web-overlay/stack-catalog.md`
+  - `src/app-overlay/stack-catalog.md`
+
+## Outputs
 
-## Output
 - `.wize/planning/tech-vision.md`
 
-## Template
+## Steps
+
+### 1. Pick the stack family
+
+By order of constraint:
+
+1. **Audience reach.** Public + SEO-critical? Authenticated app? Native mobile required?
+2. **Latency budget.** Sub-1s LCP on 3G or richer-but-slower OK?
+3. **Team familiarity.** Favor what the team has shipped before unless the project truly demands new.
+4. **Backend coupling.** Separate API / fullstack monolith / BaaS?
+5. **Deploy target.** Edge / container / self-managed.
+
+Don't pick libraries here. Pick the *shape*: "Next.js-class SSR fullstack on edge" or "React Native + Expo with a Supabase backend" or "Compose Multiplatform with Kotlin services."
+
+### 2. State the runtime envelope
+
+| Dimension | Decision |
+|---|---|
+| Language(s) of record | TS, Kotlin, etc. |
+| Runtime(s) | Browser / Node / Edge / Native iOS / Native Android / JVM |
+| Persistence | Postgres / SQLite / KV / cloud-native |
+| Deploy target | Vercel / Cloudflare / Fly / EKS / EAS / etc. |
+| Edge vs origin | Edge-first / origin-first |
+
+### 3. Build / buy / borrow
+
+For each capability the PRD implies, declare:
+
+| Capability | Build | Buy | Borrow (OSS) |
+|---|---|---|---|
+| Auth | — | Clerk / Auth0 | NextAuth / Lucia |
+| Payments | — | Stripe | — |
+| Search | — | Algolia / Typesense Cloud | Meilisearch self-hosted |
+| Queues | — | SQS / Cloud Tasks | BullMQ |
+| Analytics | — | Amplitude | PostHog OSS |
+| Email | — | Resend / Postmark | — |
+| Realtime | — | Pusher / Ably | Supabase Realtime |
+
+One row per capability. Empty cells are explicit choices.
+
+### 4. Non-negotiables
+
+The 2–5 things the team will not compromise on.
+
+Examples:
+- *"All endpoint responses ≤ 200ms p95 from the user's region."*
+- *"Single source of truth for user data — no shadow stores."*
+- *"PII never leaves the EU."*
+- *"On-call burden ≤ 0.5 pages per engineer per week."*
+
+These outrank PRD goals. If they conflict, Fury escalates.
+
+### 5. Deferred (with triggers)
+
+What we won't decide yet, and what would trigger the decision. Don't list "could be revisited"; list the *signal* that forces the decision.
+
+- *"Multi-region storage: revisit when EU+US daily active users > 5k."*
+- *"WebSockets vs SSE: revisit when realtime updates < 500ms become a PRD goal."*
+
+### 6. Hand off
+
+Mark `status: aligned`. Tony reads it as the frame; he can argue specific decisions but not redraw the family without escalating.
+
+## Output template
+
 ```markdown
-# Tech Vision
+---
+status: aligned
+owner: Nick Fury
+created: YYYY-MM-DD
+---
 
-## Stack family
-- {Web|Mobile|Hybrid}
+# Tech Vision — {{project_name}}
 
-## Language(s) of record
-- …
+## Stack family
+Next.js-class SSR fullstack on edge, with Supabase Postgres as the system of record.
 
 ## Runtime envelope
-- {Browser|Node|Edge|Native iOS|Native Android}
+| Dimension | Decision |
+|---|---|
+| Language | TypeScript end-to-end |
+| Runtime | Edge (Vercel Edge Functions) + Node (server actions) |
+| Persistence | Supabase Postgres (RLS) + PgBouncer |
+| Deploy target | Vercel for app; Supabase managed for data |
+| Edge vs origin | Edge-first for reads; origin for writes |
 
-## Build vs buy vs borrow
-| Capability | Decision | Why |
-|---|---|---|
-| Auth | … | … |
-| Payments | … | … |
-| Search | … | … |
-| Queues | … | … |
-| Analytics | … | … |
+## Build / buy / borrow
+| Capability | Decision |
+|---|---|
+| Auth | Buy — Supabase Auth |
+| Payments | Buy — Stripe |
+| Search | Buy — Algolia (1st year), revisit |
+| Queues | Borrow — pg_cron + outbox pattern |
+| Analytics | Borrow — PostHog OSS |
+| Email | Buy — Resend |
 
 ## Non-negotiables
-- …
+1. PII (incl. emails) stored in the user's region only.
+2. p95 server response ≤ 200ms in the user's region.
+3. Single auth identity per human (no shadow accounts).
+4. On-call rotation never exceeds 0.5 pages/eng/week.
+
+## Deferred
+- Multi-region writes: revisit when EU active users > 2k.
+- Native mobile clients: revisit when web TTI > 4s on > 20% of sessions or PRD demands offline.
 
-## Deferred (revisit when)
-- … (trigger: …)
+## Constraints that drove this
+- Brief constraint #2 (LGPD/GDPR) ruled out global-replica DBs.
+- PRD goal G1 ruled in edge-first reads.
+- Hiring tail in TypeScript ruled out Compose Multiplatform.
 ```
+
+## Anti-patterns Fury rejects
+
+- **Picking a library here.** That's Tony. Pick the *family*.
+- **Non-negotiables that are aspirations.** "Always 100% uptime." Wrong. "Error budget ≤ 0.1% in EU region."
+- **Deferred items with no trigger.** That's procrastination.
+- **A non-negotiable that contradicts a PRD constraint silently.** Surface it, escalate it, decide it.
+
+## Hand-off
+
+> Tech vision at `.wize/planning/tech-vision.md`. Tony, build the architecture inside this frame. Hill, scope the PRD against the non-negotiables (item 1 means the global launch is back on the table only after EU baseline holds). Hawkeye, pick gate granularity assuming `policy = advisory`.

package/src/method-skills/4-implementation/wize-agent-dev/persona.md

@@ -12,6 +12,18 @@ I am **Shuri**. Wakandan technologist. I implement the story Tony wrote, against
 4. **Security & perf.** I think about both at write-time, not at review-time.
 5. **Commit with AC IDs.** Every commit cites the story acceptance criteria it advances.
 
+## Before I write new code (the reuse ladder)
+
+At the "green" step, before typing a new function, I walk this ladder in order and stop at the first "yes":
+
+1. **Does this need to exist?** → no: skip it (YAGNI).
+2. **Already in this codebase?** → reuse it, don't rewrite it.
+3. **Does the stdlib do it?** → use the stdlib.
+4. **Native platform/framework feature?** → use that.
+5. **An installed dependency does it?** → use the dependency.
+6. **Is it one line?** → write the one line.
+7. **Only then** do I write the minimum new code that makes the test pass.
+
 ## Style
 
 - File paths, AC IDs, commit-message brevity.

package/src/method-skills/4-implementation/wize-changelog/workflow.md

@@ -0,0 +1,184 @@
+---
+code: wize-changelog
+description: "Use quando precisar gerar ou atualizar o changelog no formato Keep a Changelog a partir das stories concluídas."
+name: Changelog
+phase: 4-implementation
+owner: wize-agent-dev   # Shuri
+status: ready
+---
+
+# Changelog
+
+**Goal.** Gerar `CHANGELOG.md` no formato [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) a partir das stories concluídas no sprint, agrupadas por epic e categoria.
+
+Shuri executa. O changelog é gerado em pt-BR (texto voltado ao usuário) e segue a convenção do projeto.
+
+## Inputs
+
+- `.wize/implementation/sprint-status.yaml` — stories concluídas
+- `.wize/solutioning/stories/{epic}/*.md` — detalhes das stories
+- `.wize/solutioning/epics/*.md` — nomes legíveis dos epics
+- `CHANGELOG.md` — changelog existente (se houver)
+- `git tag --list 'v*' --sort=-v:refname | head -1` — última tag
+
+## Output
+
+- `CHANGELOG.md` criado ou atualizado com a nova entrada pré-pendida
+
+## Formato Keep a Changelog
+
+Seguir estritamente o formato [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/):
+
+```markdown
+# Changelog
+
+All notable changes to this project are documented here.
+Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.12.0] — 2026-08-08
+
+### Added
+- **Epic 09 — UX / intent:** Release e changelog skills (`wize-release`, `wize-changelog`). #E09-S07
+
+### Changed
+- **Epic 09 — UX / intent:** Roteamento por intenção expandido com release/changelog. #E09-S03
+
+### Fixed
+- **Epic 09 — UX / intent:** Descrições de skill corrigidas (block scalars). #E09-S01
+
+### Security
+- (vazio se não houver stories de segurança)
+```
+
+### Regras de categoria
+
+| Categoria | Quando usar |
+|---|---|
+| **Added** | Nova feature, nova skill, nova funcionalidade |
+| **Changed** | Mudança em funcionalidade existente, alteração de comportamento |
+| **Deprecated** | Funcionalidade que será removida em breve |
+| **Removed** | Funcionalidade removida |
+| **Fixed** | Correção de bug |
+| **Security** | Correção de vulnerabilidade, melhoria de segurança |
+
+### Regras de agrupamento
+
+- Agrupar por **epic** dentro de cada categoria.
+- Cada linha começa com `- **Epic NN — Nome:**` seguido da descrição e `#story_id`.
+- Stories sem epic definido vão sob `- **Geral:**`.
+- Se uma categoria não tiver stories, escrever `- (vazio)` ou omitir (consistente com o changelog existente).
+
+## Steps
+
+### 1. Coletar stories concluídas
+
+Ler `sprint-status.yaml`. Para cada story com status `done`:
+
+1. Localizar o arquivo em `.wize/solutioning/stories/{epic}/{story}.md`
+2. Extrair do frontmatter: `story_id`, `epic`
+3. Extrair do corpo: título (linha `# Story:`) e primeira frase da seção `## Context` como sumário
+
+Se o arquivo da story não existir, usar apenas o `story_id` como referência.
+
+### 2. Classificar por categoria
+
+Para cada story, determinar a categoria com base no conteúdo:
+
+| Padrão no título/contexto | Categoria |
+|---|---|
+| "Adicionar", "Criar", "Novo", "Added", "Add" | Added |
+| "Corrigir", "Consertar", "Bug", "Fix", "Hotfix", "Correção" | Fixed |
+| "Alterar", "Mudar", "Refatorar", "Change", "Update" | Changed |
+| "Remover", "Deprecar" | Removed / Deprecated |
+| "Segurança", "Vulnerabilidade", "Security", "CVE" | Security |
+
+Se ambíguo, default `Added` para stories novas, `Changed` para alterações.
+
+### 3. Agrupar por epic
+
+Para cada story, resolver o nome do epic:
+
+1. Se o frontmatter tem `epic: NN-nome`, usar `Epic NN — Nome`
+2. Buscar em `.wize/solutioning/epics/{epic}.md` o título (`# Epic NN: Nome`)
+3. Fallback: `Epic {epic_id}`
+
+Agrupar stories por epic, depois por categoria.
+
+### 4. Gerar entrada do changelog
+
+Montar a entrada no formato:
+
+```markdown
+## [{version}] — {YYYY-MM-DD}
+
+{descrição curta do release — 1-2 frases sobre o que esta versão entrega}
+
+### Added
+- **{epic_nome}:** {descrição}. #{story_id}
+
+### Changed
+- **{epic_nome}:** {descrição}. #{story_id}
+
+### Fixed
+- **{epic_nome}:** {descrição}. #{story_id}
+
+### Security
+- **{epic_nome}:** {descrição}. #{story_id}
+```
+
+### 5. Atualizar CHANGELOG.md
+
+Se `CHANGELOG.md` não existir, criar com o cabeçalho padrão:
+
+```markdown
+# Changelog
+
+All notable changes to this project are documented here.
+Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+> **Language:** entries are written in **Portuguese (pt-BR)**.
+
+## [Unreleased]
+```
+
+Se existir:
+1. Localizar a linha `## [Unreleased]`
+2. Inserir a nova entrada entre `## [Unreleased]` e a primeira `## [versão]` existente
+3. Se não houver `## [Unreleased]`, inserir após o cabeçalho
+
+### 6. Verificar formatação
+
+- A data está no formato `YYYY-MM-DD`
+- A versão segue semver (`X.Y.Z`)
+- Cada story tem referência ao `#story_id`
+- Categorias vazias foram omitidas
+- O link do Keep a Changelog está presente
+
+## Exemplo de saída
+
+```markdown
+## [0.12.0] — 2026-08-08
+
+Release do cluster de ship: skills de release e changelog para o perfil core, roteamento por intenção expandido.
+
+### Added
+- **Epic 09 — UX / intent:** Skill `wize-release` para bump de versão, changelog e tag git a partir das stories gated. #E09-S07
+- **Epic 09 — UX / intent:** Skill `wize-changelog` para geração de changelog no formato Keep a Changelog. #E09-S07
+
+### Changed
+- **Epic 09 — UX / intent:** Tabela de roteamento por intenção expandida com release, changelog, lançar, publicar, notas de versão. #E09-S03
+```
+
+## Anti-patterns
+
+- Changelog escrito à mão sem referência às stories — perde rastreabilidade.
+- Categoria "Added" para correção de bug — usar "Fixed".
+- Data fora do formato ISO — usar `YYYY-MM-DD`.
+- Pular stories concluídas — toda story `done` no sprint entra no changelog.
+- Escrever changelog em inglês quando o projeto usa pt-BR — seguir o idioma do changelog existente.
+
+## Hand-off
+
+> Changelog atualizado em `CHANGELOG.md`. {count} stories de {epic_count} epics registradas. Próximo: `/wize-release` para bump de versão e tag, ou revisão manual do changelog.

package/src/method-skills/4-implementation/wize-checkpoint-preview/workflow.md

@@ -0,0 +1,117 @@
+---
+
+code: wize-checkpoint-preview
+description: "Use quando uma story estiver parcialmente implementada e precisar de preview de checkpoint para validar direção antes de continuar."
+name: Checkpoint Preview
+phase: 4-implementation
+owner: wize-agent-dev   # Shuri (+ wize-agent-architect Tony on call)
+status: ready
+---
+
+# Checkpoint Preview
+
+**Goal.** Pause mid-story to validate direction before continuing. For larger stories where the cost of going off-rail is high, a quick checkpoint catches drift before it becomes rework.
+
+Shuri drives. Tony on call for architectural drift. Hawkeye on call for test design drift.
+
+## When to run
+
+- Manually, when a story is running long or feels off-track.
+- After the first 2-3 commits of a larger story.
+- When a new constraint is mentioned (security review, perf budget, vendor change).
+
+## When NOT to run
+
+- Quick-dev / small stories (overhead exceeds the value).
+- When the story is < 50% done and no surprise has come up yet.
+
+## Inputs
+
+- The current story file: `.wize/solutioning/stories/{epic}/{story}.md`
+- The git diff: uncommitted + committed since story start
+- The `tea-design.md` for the story
+- The `design-system/` tokens used so far
+
+## Output
+
+- `.wize/implementation/checkpoints/{story_id}.md` (one file per checkpoint, append over time)
+- A decision: continue / pivot / stop
+
+## Steps
+
+### 1. Pause
+
+Stop writing code. Do not commit any pending work until the checkpoint is recorded.
+
+### 2. Snapshot
+
+Write 5 lines:
+
+- Files touched: (list, max 10)
+- ACs done vs. remaining: (X / Y)
+- Tests added: (count, by split)
+- New dependencies: (list)
+- Commits so far: (count)
+
+### 3. Sanity check (3 questions)
+
+- **Are we solving the right problem?** Compare the implementation with the story's Context and ACs. If the story's intent was misunderstood, pivot.
+- **Is the design holding?** Compare the code with the architecture. If a new pattern emerged without an ADR, flag it.
+- **Any new constraints?** Did anything new appear (security finding, perf regression, vendor change, new stakeholder)?
+
+### 4. Decide
+
+One of three:
+
+- **Continue** — the path is right. Record the snapshot; resume.
+- **Pivot** — change scope or approach. Open a follow-up story with `wize-create-story`; do not edit the current story's ACs.
+- **Stop** — the story is no longer worth it. Move it to `backlog` via `wize-correct-course`.
+
+One decision per checkpoint. Re-run for additional decisions.
+
+### 5. Hand off
+
+Notify the next workflow:
+
+- Continue → `/wize-dev-story` (resume).
+- Pivot → `/wize-create-story` (new story for the pivot).
+- Stop → `/wize-correct-course` (defer the original).
+
+## Output template
+
+```markdown
+---
+story_id: E04-S02
+checkpoint: 1
+date: 2026-06-16
+author: Shuri
+---
+
+# Checkpoint — E04-S02
+
+## Snapshot
+- Files touched: src/...
+- ACs done vs. remaining: 1 / 4
+- Tests added: 2 unit, 1 integration
+- New dependencies: none
+- Commits so far: 3
+
+## Sanity check
+- Right problem? Yes.
+- Design holding? Yes.
+- New constraints? Vendor X deprecated their API; need a different client lib.
+
+## Decision
+**Pivot** — see follow-up E04-S04 (client lib migration).
+```
+
+## Anti-patterns Shuri rejects
+
+- Skipping the snapshot to "save time" — the snapshot is the artifact.
+- Auto-pivoting (changing scope without an explicit checkpoint).
+- Recording "continue" without the sanity check answers.
+- Bundling multiple pivots in one checkpoint (one decision per run).
+
+## Hand-off
+
+> "Checkpoint recorded for **{story_id}** (decision: {continue|pivot|stop}). Next: `/wize-dev-story` / `/wize-create-story` / `/wize-correct-course`."

package/src/method-skills/4-implementation/wize-code-review/customize.toml

@@ -0,0 +1,21 @@
+# Wize Dev Kit — overrides for the built-in workflow "wize-code-review".
+# DO NOT EDIT in the installed kit; copy to .wize/custom/workflows/wize-code-review/
+# for project-level overrides.
+
+[workflow]
+
+# Steps to run before standard activation (config load, greet).
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run.
+persistent_facts = [
+  "file:{project-root}/.wize/knowledge/document-project/conventions.md",
+]
+
+# Scalar executed when the workflow reaches its final step,
+# after review findings are presented and sprint status is synced.
+# Override wins. Leave empty for no custom post-completion behavior.
+on_complete = ""

package/src/method-skills/4-implementation/wize-code-review/steps/step-01-gather-context.md

@@ -0,0 +1,64 @@
+---
+diff_output: ''
+spec_file: ''
+review_mode: ''
+story_key: ''
+---
+
+# Step 1: Gather Context
+
+## Rules
+
+- Speak in `{communication_language}`.
+- The prompt that triggered this workflow IS the intent.
+- Do not modify any files in this step. Read-only.
+
+## Instructions
+
+1. **Find the review target.** Check in this order and stop as soon as the target is identified:
+
+   **Tier 1 — Explicit argument.**
+   Did the user pass a PR, commit SHA, branch, spec file, or diff source?
+   - PR reference → resolve to branch/commit via `gh pr view`.
+   - Commit or branch → use directly.
+   - Spec file → set `{spec_file}` to the path. Check its frontmatter for `baseline_commit`.
+   - Diff-mode keywords: `staged`, `uncommitted`, `branch diff`, `commit range`, `this diff`.
+
+   **Tier 2 — Recent conversation.**
+   Look for refs in the last few messages.
+
+   **Tier 3 — Sprint tracking.**
+   Look for `*sprint-status*` files and find stories with status `review`.
+
+   **Tier 4 — Current git state.**
+   If not on the default branch, confirm whether to review the current branch.
+
+   **Tier 5 — Ask.**
+   Present options: uncommitted changes, staged changes, branch diff, commit range, provided diff.
+
+2. **Construct `{diff_output}`.**
+   - Staged only: `git diff --cached`
+   - Uncommitted: `git diff HEAD`
+   - Branch diff: `git diff <base>..<branch>`
+   - Commit range: `git diff <from>..<to>`
+   - Provided diff: validate and use verbatim
+   - File list: `git diff HEAD -- <files...>`, with untracked files included via `git diff --no-index /dev/null <path>`
+
+   If `{diff_output}` is empty, halt and say so.
+
+3. **Set the spec context.**
+   - If `{spec_file}` is set and readable, set `{review_mode}` = `"full"`.
+   - Otherwise ask: "Is there a spec or story file that provides context for these changes?"
+     - Yes → set `{spec_file}`, verify it, set `{review_mode}` = `"full"`.
+     - No → set `{review_mode}` = `"no-spec"`.
+
+4. **Sanity check.**
+   If the diff exceeds ~3000 lines, warn and offer to chunk.
+
+### Checkpoint
+
+Present a summary: diff stats, `{review_mode}`, loaded spec/context docs. Halt and wait for confirmation to proceed.
+
+## Next
+
+Read fully and follow `./step-02-review.md`.

package/src/method-skills/4-implementation/wize-code-review/steps/step-02-review.md

@@ -0,0 +1,40 @@
+---
+failed_layers: ''
+---
+
+# Step 2: Review
+
+## Rules
+
+- Speak in `{communication_language}`.
+- The Blind Hunter subagent receives **only** the diff — no project context.
+- The Edge Case Hunter subagent receives the diff and project read access.
+- The Acceptance Auditor subagent receives the diff, spec, and context docs.
+- All review subagents run at the same model capability as the current session.
+
+## Instructions
+
+This step is an instance of Wizer's subagent fan-out pattern (see `wize-orchestrator` persona): name, scope, dispatch on whatever the current harness natively supports, tolerate partial failure.
+
+1. If `{review_mode}` = `"no-spec"`, note: "Acceptance Auditor skipped — no spec file provided."
+
+2. Launch parallel subagents without conversation context:
+
+   - **Blind Hunter** — receives `{diff_output}` only. Invoke via `wize-review-adversarial`.
+     Prompt: "Review this diff cynically. Assume problems exist. Find at least ten issues. Output as a Markdown list with one-line titles."
+
+   - **Edge Case Hunter** — receives `{diff_output}` and read access to the project. Invoke via `wize-review-edge-case-hunter`.
+     Prompt: "Walk every branching path and boundary condition in this diff. Report only unhandled edge cases as a JSON array."
+
+   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — receives `{diff_output}`, `{spec_file}` content, and context docs.
+     Prompt: "Review this diff against the spec. Check for violations of acceptance criteria, deviations from spec intent, and missing behavior. Output findings as a Markdown list with AC/constraint reference and evidence."
+
+3. If subagents are unavailable, generate prompt files in `{implementation_artifacts}` and halt, asking the user to run each in a separate session.
+
+4. If any subagent fails, times out, or returns empty, append the layer name to `{failed_layers}` and proceed with findings from the remaining layers.
+
+5. Collect all findings from completed layers.
+
+## Next
+
+Read fully and follow `./step-03-triage.md`.

package/src/method-skills/4-implementation/wize-code-review/steps/step-03-triage.md

@@ -0,0 +1,43 @@
+# Step 3: Triage
+
+## Rules
+
+- Speak in `{communication_language}`.
+- Be precise. When uncertain between categories, prefer the more conservative classification.
+
+## Instructions
+
+1. **Normalize** findings into a common format. Expected input formats:
+   - Blind Hunter: Markdown list of descriptions.
+   - Edge Case Hunter: JSON array with `location`, `trigger_condition`, `guard_snippet`, `potential_consequence`.
+   - Acceptance Auditor: Markdown list with title, AC/constraint reference, and evidence.
+
+   Convert all to a unified list with:
+   - `id` — sequential integer
+   - `source` — `blind`, `edge`, `auditor`, or merged (`blind+edge`, etc.)
+   - `title` — one-line summary
+   - `detail` — full description
+   - `location` — file and line reference if available
+
+2. **Deduplicate.** Merge findings that describe the same issue:
+   - Use the most specific finding as the base (prefer Edge Case Hunter JSON with location).
+   - Append unique detail, reasoning, or locations from other findings.
+   - Set `source` to merged sources.
+
+3. **Classify** each finding into exactly one bucket:
+   - **decision_needed** — ambiguous choice requiring human input. Only possible if `{review_mode}` = `"full"`.
+   - **patch** — code issue fixable without human input.
+   - **defer** — pre-existing issue not caused by this change.
+   - **dismiss** — noise, false positive, or handled elsewhere.
+
+   If `{review_mode}` = `"no-spec"` and a finding would be `decision_needed`, reclassify as `patch` or `defer`.
+
+4. **Drop** all `dismiss` findings. Record the dismiss count.
+
+5. If `{failed_layers}` is non-empty, report which layers failed. If zero findings remain and layers failed, warn the user that the review may be incomplete.
+
+6. If zero findings remain after triage, state: "✅ Clean review — all layers passed."
+
+## Next
+
+Read fully and follow `./step-04-present.md`.