wize-dev-kit 0.16.0 → 0.17.0

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

@@ -1,33 +1,201 @@
 ---
+
 code: wize-dev-story
+description: "Use quando uma story estiver pronta para implementação e precisar ser desenvolvida com TDD e commits rastreáveis."
 name: Dev Story
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri
-status: stub
+status: ready
 ---
 
 # Dev Story
 
-**Goal.** Implement one story under TDD discipline.
+**Goal.** Implement one story under TDD discipline. Tests first; minimum code to pass; refactor with green. Each commit cites an AC ID. The PR ends in a clean gate, not a "looks good to me."
+
+Shuri drives. Hawkeye observes (test design is binding). Tony stays available for architectural questions.
+
+## Operating contract
+
+I work inside a repo with WDK installed: `.wize/`, `AGENTS.md`, and the `wize-*` skills are my instructions and memory, not background reading. This section is the execution slice of the story's **mission contract** (see `/wize mission` or `/wize-help mission`).
+
+- **Inspect before editing.** Read the story, its sources of truth, and the touched code first.
+- **Reuse ladder before new code** (see `wize-agent-dev` persona): needs to exist → already here → stdlib → framework feature → installed dep → one-liner → only then new code.
+- **Test-first, unconditionally.** Red before green, per the loop below — this is the strict-TDD workflow; the "when applicable" latitude lives in `wize-quick-dev`, not here. Smallest sufficient change; follow existing conventions.
+- **Run real commands.** No success claim without evidence — a passing run, not "should pass."
+- **Never stop at planning.** Planning is a step, not a deliverable.
 
 ## Inputs
-- `.wize/solutioning/stories/{epic}/{story-id}.md`
+
+- `.wize/solutioning/stories/{epic}/{story}.md`
 - `.wize/solutioning/architecture.md`
-- `.wize/implementation/tea/{epic}/{story-id}/design.md` (Hawkeye must have produced this)
+- `.wize/solutioning/design-system/` (use existing components)
+- `.wize/implementation/tea/{epic}/{story}/design.md` (the test contract)
 
 ## Outputs
-- Code + tests in the target repo
-- Commit messages reference AC IDs
-- Story file updated to `status: ready-for-review`
-
-## Steps (TDD loop)
-1. **Read.** Story ACs and Hawkeye's design.
-2. **Red.** Write the failing test first.
-3. **Green.** Minimum code to pass.
-4. **Refactor.** Clean — only with green tests.
-5. **Repeat** until every AC has at least one test.
-6. **Self-check.** Security, perf, dead code, naming.
-7. **Hand-off.** Ping Hawkeye for trace + review.
+
+- Code + tests in the target repo.
+- Commit messages reference AC IDs.
+- Story file updated to `status: ready-for-review`.
+
+## The loop (TDD, story-scoped)
+
+### 1. Read
+
+Story ACs, out-of-scope, notes, `tea-design.md`. Confirm the test split. If the design doesn't match the story (mismatch on test count, mock, environment), ping Hawkeye **before** writing code.
+
+### 2. Slice the story into micro-cycles
+
+Each cycle is one AC (or part of one) and produces a green test + small code change. Don't try to ship the whole story in one commit.
+
+### 3. Red
+
+Write the failing test first. Match the assertion shape in `design.md`. Don't write code yet.
+
+```ts
+// red — first run, fails
+test('valid email returns ok', () => {
+  expect(validateInviteEmail('a@b.co')).toEqual({ ok: true });
+});
+```
+
+### 4. Green
+
+Before writing anything new, run Shuri's reuse ladder (see `wize-agent-dev` persona): does this need to exist → already in the codebase → stdlib → native/framework feature → installed dependency → one-liner → only then new code. Write the **minimum** code that turns the test green. No anticipated branches; no "just-in-case" handling.
+
+```ts
+// green — minimum to pass
+export const validateInviteEmail = (s: string) => ({ ok: /@/.test(s) });
+```
+
+### 5. Refactor
+
+Now harden, with the test as safety net.
+
+```ts
+// refactor — same green tests, real logic
+import { z } from 'zod';
+const schema = z.string().email();
+export const validateInviteEmail = (s: string) =>
+  schema.safeParse(s).success ? { ok: true } : { ok: false, code: 'invalid_format', field: 'email' };
+```
+
+### 6. Commit
+
+Conventional commits, AC IDs referenced.
+
+```
+feat(invite): validate email per AC-02-1 / AC-02-2
+- add validateInviteEmail with zod
+- add 4 unit tests covering valid + invalid rules
+```
+
+### 7. Repeat
+
+Until every AC has at least one test + minimum code that makes it pass.
+
+### 7.5. Loop verification (auto-check)
+
+Before declaring the loop done, run these checks:
+
+| Check | How | Fail → |
+|---|---|---|
+| **Evidence of iteration** | `git log --oneline` shows ≥2 commits with AC IDs (skip if story has only 1 AC) | Return to step 2 |
+| **AC-to-test mapping** | Every AC in the story file has a corresponding test case name | Return to step 3 (Red) |
+| **All AC tests green** | `npx vitest run --reporter=verbose` (or equivalent) — grep output for each AC's test name | Return to step 4 (Green) |
+
+**Max-cycles guard.** If the same AC cycles through Red→Green→Refactor 3+ times without staying green, stop and escalate to Wizer: the test design may be wrong, the AC may be mis-sized, or the approach may need Tony.
+
+### 8. Knowledge update (inline, ~60s)
+
+Before opening the PR, ask: **did this story touch any of the 5 baseline axes** documented in `.wize/knowledge/document-project/`?
+
+| Axis | Touched when… | File to update |
+|---|---|---|
+| **Architecture** | new component, new sequence, changed data flow | `architecture-snapshot.md` |
+| **Conventions** | new naming/folder/test pattern published as public contract (incl. `testid`) | `conventions.md` |
+| **Risk-spots** | introduced a complexity hot spot OR resolved one | `risk-spots.md` |
+| **Dependencies** | added / removed / upgraded a runtime dep | `dependencies.md` |
+| **Overview** | new user-visible feature a new dev should know about | `overview.md` |
+
+If yes for any axis: open the file and add **1–3 lines** under a new dated bullet — in the same PR.
+
+```markdown
+## 2026-06-12 — E01-S03
+- Conventions: `data-testid="invite-*"` published as public contract; Hawkeye E2E depends on these.
+- Risk: R-1 (mailer) mitigation now confirmed (integration test covers retry policy).
+```
+
+If no axis was touched, you skip this step entirely — quick-dev-style changes don't need it. Hawkeye will check whether the call was correct in `tea-review`. A story that touched an axis but skipped the update gets a `KN-NN` finding in the gate (recommendation `CONCERNS` advisory, or `FAIL` enforcing).
+
+This is how the brownfield baseline stays alive instead of going stale 6 months in.
+
+### 9. Pre-PR self-check
+
+- All Hawkeye-declared tests exist + pass — **AC → test mapping complete**, every AC traced to a named passing test.
+- Required checks run: unit + integration + e2e (as the test contract declares), lint, format, type-check, build — and security when the story touches auth/payments/boundaries. If a command couldn't run, say **exactly which and why** — don't silently drop it.
+- No `test.skip` / `.only` left.
+- Authz enforced at every server boundary the story adds.
+- Loading / empty / error states rendered and asserted.
+- `data-testid` matches story's "notes for Hawkeye".
+- Story file frontmatter → `status: ready-for-review`.
+- Self-walk the screen (web) or smoke a tab on simulator (app).
+
+### 10. Open PR
+
+PR description includes:
+- Story link.
+- AC list with the test names that cover them.
+- Screenshots / recordings of happy + failure paths.
+- Knowledge update line (`Touched axis: <none|architecture|conventions|risk-spots|dependencies|overview>`).
+- TEA expected next: design → trace → review → gate.
+
+### 11. Address gate findings
+
+If `tea-review` or `tea-gate` flags issues, fix them in the same PR or open a follow-up if the story has shipped a separate value-bearing slice.
+
+**Loop-back protocol:**
+1. Read each finding's `severity` and `blocking` flag.
+2. For each `blocking: true` finding → return to step 3 (Red) for the affected AC.
+3. For each `blocking: false` finding → log in story `notes` and fix in same PR before re-submitting to gate.
+4. **Max-retry guard:** if the same story cycles through gate → fix → gate 3+ times, stop and escalate to Wizer. The story may be mis-sized, the test design may be wrong, or the ACs may need renegotiation with Hill.
+
+## Security + perf during implementation
+
+Shuri thinks both at write time, not at review time:
+
+- Auth context on every server entry point — confirm via Tony's middleware pattern.
+- Tokens never logged.
+- Inputs validated at the boundary; trusted by the time they reach domain.
+- Network calls in handlers wrapped with timeout + retry policy from architecture.
+- Don't `await` in a loop without batching.
+- Don't ship dead code (`isFooEnabled = true` always).
 
 ## Quick-dev exception
-If invoked via `wize-quick-dev`, the design step is replaced by smoke-test-only commitment.
+
+If the work is small / well-scoped and Wizer invoked `wize-quick-dev` instead of this workflow, the design step is replaced by smoke-test-only commitment and the gate is a single one-line entry in `quick-dev-log.md`.
+
+## Anti-patterns Shuri rejects in her own work
+
+- Writing code first and tests "after the bug fix" — that's not TDD; that's regression-tests.
+- Commits that don't cite an AC.
+- "Refactor while green" turning into "rewrite while green."
+- Bundling cross-cutting refactors into the story PR. Split.
+- Editing tests so they pass instead of editing code so tests pass.
+
+## Final report
+
+When the story is done, report to the thread in this shape — decisions, evidence, results, blockers only; no extended private reasoning:
+
+1. **Route used** — full lifecycle (dev-story).
+2. **Solution summary** — what changed and why, in a few lines.
+3. **Files changed.**
+4. **AC → test mapping** — each AC and the passing test that covers it.
+5. **Commands run + results** — the real checks and their outcomes; name any that couldn't run and why.
+6. **`.wize/` artifacts updated** — story status, TEA artifacts, knowledge axes.
+7. **Relevant decisions** — including any ADR if architectural.
+8. **Residual risks / limitations / skipped items** — including recommended extras logged separately (no silent scope creep).
+9. **Single recommended next action** — usually the TEA gate.
+
+## Hand-off
+
+> Story E01-S03 implemented. All ACs covered by tests; CI green. PR opened (#412). Hawkeye, ready for trace + review. Notes section of the story has the testid map you'll use.

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

@@ -0,0 +1,123 @@
+---
+
+code: wize-investigate
+description: "Use quando um bug ou comportamento inesperado surgir e precisar de investigação estruturada com root cause analysis."
+name: Investigate
+phase: 4-implementation
+owner: wize-agent-dev   # Shuri (+ wize-agent-test-architect Hawkeye on call)
+status: ready
+---
+
+# Investigate
+
+**Goal.** Structured root-cause analysis for a failed test, regression, or unexpected behavior. Produces a written report so the team (and future-you) can retrace the steps.
+
+Shuri drives. Hawkeye on call for test-specific analysis. Wizer is on call for cross-cutting impact.
+
+## When to run
+
+- A test fails and the cause is not obvious from the diff.
+- A regression appears in production or CI.
+- A user reports a bug with unclear repro steps.
+- An incident triggers post-mortem.
+
+## When NOT to run
+
+- The cause is obvious from the diff → use `wize-quick-dev` to fix directly.
+- A new feature is needed (use `wize-create-story`).
+- A security finding is suspected (escalate immediately; do not investigate solo).
+
+## Inputs
+
+- The failing test, error log, or user report.
+- The commit range since the last known-good state.
+- The relevant story file (if any).
+- A free-form description of the symptoms.
+
+## Output
+
+- `.wize/implementation/investigations/{YYYY-MM-DD}-{short-slug}.md` — a written report.
+
+## Steps
+
+### 1. Frame
+
+One paragraph: what broke, when it was first noticed, who reported it, and how serious. If you cannot write this in 3 sentences, the report is too broad.
+
+### 2. Reproduce
+
+Step-by-step: how to reproduce locally. Include environment (OS, Node version, branch), commands, expected vs. actual output. If unreproducible, mark "not reproducible after N attempts" and stop.
+
+### 3. Hypothesize
+
+List 3 root causes, ranked by likelihood. For each:
+- What would explain the symptoms.
+- A 1-line test to confirm or refute.
+- Confidence: low / medium / high.
+
+### 4. Verify
+
+For each hypothesis, run the 1-line test. Record: confirmed / refuted / inconclusive. If all refuted, return to step 3 and re-rank.
+
+### 5. Conclude
+
+Pick the surviving root cause. State:
+- **Root cause:** {description}.
+- **Fix path:** {one paragraph: what to change and why}.
+- **Effort:** S / M / L.
+- **Risk of fix:** low / medium / high.
+- **Recommended next step:** open a quick-dev, open a story, or escalate.
+
+### 6. Hand off
+
+Notify the next workflow:
+- S / low risk → `/wize-quick-dev` (Shuri fixes directly).
+- M+ or higher risk → `/wize-create-story` (new story for the fix).
+- Escalation → `/wize-correct-course` (involve PM + Wizer).
+
+## Output template
+
+```markdown
+---
+date: 2026-06-16
+author: Shuri
+severity: high
+related_story: E04-S02
+related_test: test/document-project-classify.test.js
+status: concluded
+---
+
+# Investigation — {short-slug}
+
+## Frame
+{one paragraph}
+
+## Reproduce
+1. ...
+2. ...
+**Expected:** {x}
+**Actual:** {y}
+
+## Hypotheses
+1. **{hypothesis}** — Confidence: high. Test: {1-liner}. Result: confirmed.
+2. ...
+
+## Conclude
+- **Root cause:** {description}
+- **Fix path:** {one paragraph}
+- **Effort:** M
+- **Risk of fix:** low
+- **Next:** /wize-create-story (E04-S05)
+```
+
+## Anti-patterns Shuri rejects
+
+- Skipping the hypothesis ranking. (Ranking forces you to consider alternatives.)
+- Stopping at "I think it's X" without the verification test. (Confirmation bias.)
+- Mixing the investigation with the fix. (Investigate, then propose; do not edit code yet.)
+- One-paragraph reports. (If it's a real investigation, it's at least 5 sections.)
+- Sharing the report only in chat. (Always write to disk for archival.)
+
+## Hand-off
+
+> "Investigation concluded. Root cause: {summary}. Next: `/wize-create-story` (M+ fix) or `/wize-quick-dev` (S fix)."

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

@@ -1,33 +1,151 @@
 ---
+
 code: wize-quick-dev
+description: "Use quando a demanda for pequena e bem delimitada (bug fix, copy edit, refactor) e não justificar o ciclo completo."
 name: Quick Dev (lifecycle shortcut)
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri
-status: stub
+status: ready
 ---
 
 # Quick Dev
 
-**Goal.** When the task is small and well-scoped (bug fix, copy edit, small refactor), skip the full lifecycle.
+**Goal.** When the task is small and well-scoped (bug fix, copy edit, small refactor, dep bump, brownfield maintenance), skip Phase 1–3 and execute with light TEA. Save the full lifecycle for new value.
+
+Wizer authorizes the shortcut (via routing). Shuri runs it. Hawkeye does smoke-only.
+
+## Operating contract (light)
+
+Still a **mission contract**, just a small one: `.wize/` + `AGENTS.md` + skills are the instructions. Inspect before editing, reuse ladder before new code, smallest sufficient change, test-first when the change has a testable surface, run the real smoke + checks, no success claim without evidence. If it grows past ~1h or touches a new feature/architecture/UX/security surface, stop and re-route to Full Lifecycle — don't force it through here.
+
+## When to use (yes)
+
+- Bug fix with a clear root cause.
+- Copy or content edit.
+- Small refactor with no behavior change.
+- Dependency bump (security or minor).
+- Brownfield maintenance: rename, structural cleanup, dead-code removal.
+- Hotfix during incident response (post-mortem after).
+
+## When NOT to use (no)
+
+- New feature, even small.
+- Cross-cutting change touching architecture.
+- Changes where ACs need to be agreed.
+- Anything that should be a story.
+- Anything that touches security/auth/payments without senior review.
+
+## Decision tree
+
+```
+Question                              Yes              No
+Is there an AC to write?              → full lifecycle  → next
+Does it touch architecture?           → full lifecycle  → next
+Does it need UX input?                → full lifecycle  → next
+Could it surprise a user?             → full lifecycle  → next
+Is it ≤ 1 hour to a careful dev?      → quick-dev       → full lifecycle
+```
+
+## Inputs
 
-## When to use
-- Bug fix with clear root cause
-- Copy or content edit
-- Small refactor with no behavior change
-- Dependency bump
-- Brownfield maintenance
+- Issue / Slack message / PR comment describing the problem.
+- Repo state.
+- `.wize/config/tea.toml` (smoke-only policy when `policy = "advisory"`).
 
-## When NOT to use
-- New feature
-- Cross-cutting change touching architecture
-- Anything where ACs need to be agreed
+## Output
+
+- Code change (single PR).
+- Single-line entry appended to `.wize/implementation/quick-dev-log.md`.
+- Conventional commit.
 
 ## Steps
-1. **Frame.** One paragraph: what changes and why.
-2. **Implement.** TDD or smoke-test-and-fix, depending on risk.
-3. **Hawkeye lite.** Smoke test + lint only (no design/trace/nfr/review).
-4. **Gate.** Tiny `gate.md` (PASS or CONCERNS) appended to a rolling `.wize/implementation/quick-dev-log.md`.
-5. **Commit.** Conventional commit referencing the change.
+
+### 1. Frame in one paragraph
+
+What changes, why, and what could break. If the paragraph is hard to write, you're not in quick-dev territory.
+
+### 2. Implement
+
+- TDD when reasonable; smoke-test-and-fix when the cost of TDD is greater than the value.
+- Run Shuri's reuse ladder (see `wize-agent-dev` persona) before writing anything new: does this need to exist → already in the codebase → stdlib → native/framework feature → installed dependency → one-liner → only then new code. Don't introduce new abstractions.
+
+### 3. Hawkeye lite
+
+- Smoke test: imports load, the changed flow doesn't break.
+- Lint + format + type-check clean.
+- No `tea-design / trace / review / nfr` written.
+- Single one-line gate entry instead of full `gate.md`.
+
+### 4. Log
+
+Append one line to `.wize/implementation/quick-dev-log.md`:
+
+```
+2026-06-11 | shuri | dep-bump zod 3.22→3.23 | smoke PASS | PR #418
+2026-06-11 | shuri | fix copy on /signin help link | smoke PASS | PR #419
+2026-06-11 | shuri | rename UserService → AccountService | smoke PASS | PR #420
+```
+
+### 5. Knowledge update (only if applicable)
+
+Most quick-dev changes don't touch the baseline axes (copy edit, small refactor, dep bump in a stable lib). When they do — typically a **dependency bump** or a **rename that breaks a public contract** — add **one line** to the matching `document-project/*.md` file:
+
+```markdown
+## 2026-06-11
+- Dependencies: bump zod 3.22 → 3.23. No API changes; validateInviteEmail unaffected.
+- Conventions: `AccountService` replaces `UserService` (rename); imports updated repo-wide.
+```
+
+Heuristic: *"would a new dev hitting `document-project/*.md` next week be misled if I don't add this?"* Yes → write. No → skip.
+
+### 6. Commit + open PR
+
+Conventional commit. PR description: the paragraph from step 1.
+
+```
+fix(auth): typo in error message for AC-04-2 follow-up
+
+The error shown after rate-limit said "Sloow down" — corrected to "Slow down".
+No behavior change; copy-only.
+```
+
+## Quick-dev log template
+
+```markdown
+# Quick-dev log
+
+| Date | Owner | What | Smoke | PR |
+|---|---|---|---|---|
+| 2026-06-11 | shuri | … | PASS | #N |
+```
+
+## Done report (compact)
+
+Report in four lines — no ceremony:
+
+1. What changed + why.
+2. Files changed.
+3. Checks run + results (smoke, lint, format, type-check). Name any that couldn't run and why.
+4. Recommended next action, if any.
 
 ## Disabling
-Set `quick_dev_enabled = false` in `.wize/config/project.toml` to force full lifecycle for everything.
+
+To force every change through the full lifecycle (for very high-stakes products), set in `.wize/config/project.toml`:
+
+```toml
+[install]
+quick_dev_enabled = false
+```
+
+Wizer respects this; quick-dev becomes unavailable; every change must go through Pepper → … → Hawkeye gate.
+
+## Anti-patterns Shuri rejects in herself
+
+- Reaching for quick-dev to skip writing an AC because she doesn't want to argue with Hill.
+- Quick-dev that touches security/auth/payments.
+- A "small refactor" that ends up changing behavior.
+- Skipping the log entry.
+
+## Hand-off
+
+> `dep-bump zod 3.23` is in. PR #418, smoke PASS. Logged. No further TEA artifacts; moving on.

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

@@ -0,0 +1,162 @@
+---
+code: wize-release
+description: "Use quando todas as stories do sprint estiverem gated e você precisar gerar release: bump de versão, changelog e tag git."
+name: Release
+phase: 4-implementation
+owner: wize-agent-dev   # Shuri + Maria Hill
+status: ready
+---
+
+# Release
+
+**Goal.** Bump de versão, changelog a partir das stories gated e tag git. O release é o passo entre "todas as stories passaram no gate" e a retrospectiva.
+
+Shuri executa. Maria Hill confirma o escopo (quais epics entram).
+
+## Pré-requisitos
+
+Antes de iniciar, verificar:
+
+1. **Sprint ativo** — `sprint-status.yaml` deve ter `development_status` com stories.
+2. **Todas as stories gated** — cada story no sprint ativo deve estar `done` no `sprint-status.yaml`. Stories com gate `FAIL` bloqueiam o release. Stories com `CONCERNS` precisam de waiver documentado.
+3. **Git limpo** — `git status --porcelain` deve estar vazio (ou conter apenas arquivos não rastreados que não fazem parte do release).
+4. **Branch main** — releases saem da `main`. Se estiver em feature branch, abortar e orientar merge via PR.
+
+Se qualquer pré-requisito falhar, reportar o bloqueio e parar. Não fazer release parcial.
+
+## Inputs
+
+- `.wize/implementation/sprint-status.yaml` — stories concluídas
+- `.wize/solutioning/stories/{epic}/*.md` — detalhes das stories
+- `package.json` — versão atual
+- `CHANGELOG.md` — changelog existente (se houver)
+- `git tag --list 'v*'` — tags existentes
+
+## Outputs
+
+- `package.json` com versão atualizada
+- `CHANGELOG.md` atualizado com a nova versão
+- Tag git `v{semver}`
+- `sprint-status.yaml` atualizado (sprint marcado como concluído)
+- Resumo do release no terminal
+
+## Steps
+
+### 1. Verificar pré-requisitos
+
+```bash
+git status --porcelain  # deve estar vazio
+git branch --show-current  # deve ser main
+```
+
+Ler `sprint-status.yaml` e validar que todas as stories do sprint ativo estão `done`. Se houver stories `backlog`, `ready-for-dev`, `in-progress` ou `review`, listar cada uma e abortar.
+
+### 2. Coletar stories concluídas
+
+Varrer `development_status` no `sprint-status.yaml`. Para cada story com status `done`:
+
+1. Localizar o arquivo da story em `.wize/solutioning/stories/{epic}/{story}.md`
+2. Extrair do frontmatter: `story_id`, `epic`, `status`
+3. Extrair do corpo: título (linha `# Story:`), acceptance criteria
+
+Agrupar por epic. Se o epic tiver `epic_id` no `sprint-status.yaml`, usar o nome do arquivo do epic em `.wize/solutioning/epics/` para obter o título legível.
+
+### 3. Determinar o bump de versão
+
+Ler a versão atual de `package.json`:
+
+```
+Versão atual: 0.11.0
+Qual o bump?
+  1. patch (0.11.1) — correções, hotfix, docs
+  2. minor (0.12.0) — novas features compatíveis
+  3. major (1.0.0) — breaking changes
+```
+
+Em modo interativo, perguntar ao usuário. Em modo não-interativo, usar o primeiro argumento (`patch`, `minor` ou `major`). Se nenhum argumento for passado, default `patch`.
+
+Calcular a nova versão com `semver.inc(current, bump)` — usar Node built-in (regex parse + increment, sem dependência externa).
+
+### 4. Gerar changelog
+
+Delegar a geração do changelog ao `wize-changelog`:
+
+1. Invocar o fluxo do `wize-changelog` com a nova versão e a lista de stories coletadas no passo 2.
+2. O changelog é gerado no formato Keep a Changelog e pré-pendido ao `CHANGELOG.md`.
+
+Se `CHANGELOG.md` não existir, criar com o cabeçalho padrão.
+
+### 5. Bump de versão
+
+Atualizar o campo `version` em `package.json` com a nova versão. Preservar a formatação existente (indentação, aspas duplas).
+
+### 6. Commit e tag
+
+```bash
+git add package.json CHANGELOG.md
+git commit -m "chore: release v{version}"
+git tag v{version} -m "Release v{version}"
+```
+
+A mensagem de commit deve listar os epics incluídos no release.
+
+### 7. Atualizar sprint-status.yaml
+
+Adicionar ao `sprint-status.yaml`:
+
+```yaml
+release:
+  version: "{version}"
+  date: "{YYYY-MM-DD}"
+  sprint: "{active_cycle}"
+  stories_released: {count}
+```
+
+Marcar o sprint como concluído e adicionar entrada de retrospectiva pendente.
+
+### 8. Resumo
+
+Emitir no terminal:
+
+```
+✓ Release v{version} criado
+
+Epics incluídos:
+  - {epic_name} ({story_count} stories)
+
+Changelog: CHANGELOG.md
+Tag: v{version}
+Commit: {commit_hash}
+
+Próximos passos:
+  - git push origin main --tags
+  - /wize-retrospective
+```
+
+**Não executar `git push` automaticamente.** O push é sempre manual — o desenvolvedor revisa antes de publicar.
+
+## Bump semver (built-in, zero-dep)
+
+```js
+function bumpVersion(current, type) {
+  const [major, minor, patch] = current.split('.').map(Number);
+  switch (type) {
+    case 'major': return `${major + 1}.0.0`;
+    case 'minor': return `${major}.${minor + 1}.0`;
+    case 'patch': return `${major}.${minor}.${patch + 1}`;
+    default: throw new Error(`Tipo de bump inválido: ${type}. Use patch, minor ou major.`);
+  }
+}
+```
+
+## Anti-patterns
+
+- Fazer release com stories não gated — o gate existe para proteger a main.
+- Fazer release de feature branch — releases saem da main.
+- Push automático — o desenvolvedor revisa antes de publicar.
+- Pular o changelog — "depois eu escrevo" = nunca escreve.
+- Bump manual de versão — usar o bump semver para evitar off-by-one.
+
+## Hand-off
+
+> Release v{version} criado. Changelog atualizado, tag aplicada. Execute `git push origin main --tags` quando revisar. Depois: `/wize-retrospective`.