wize-dev-kit 0.16.0 → 0.16.1

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

@@ -0,0 +1,100 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step 4: Present and Act
+
+## Rules
+
+- Speak in `{communication_language}`.
+- When `{spec_file}` is set, always write findings to the story file before offering action choices.
+- `decision_needed` findings must be resolved before handling `patch` findings.
+
+## Instructions
+
+### 1. Clean review shortcut
+
+If zero findings remain after triage, state that and proceed to section 6 (Sprint Status Update).
+
+### 2. Write findings to the story file
+
+If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Review Findings` subsection in this order:
+
+1. `decision_needed` (unchecked):
+   ```
+   - [ ] [Review][Decision] <Title> — <Detail>
+   ```
+2. `patch` (unchecked):
+   ```
+   - [ ] [Review][Patch] <Title> [<file>:<line>]
+   ```
+3. `defer` (checked):
+   ```
+   - [x] [Review][Defer] <Title> [<file>:<line>] — deferred, pre-existing
+   ```
+
+Also append each `defer` finding to `{deferred_work_file}` under `## Deferred from: code review ({date})`.
+
+### 3. Present summary
+
+```
+Code review complete.
+- decision_needed: {D}
+- patch: {P}
+- defer: {W}
+- dismissed: {R}
+```
+
+If `{spec_file}` is set, add: "Findings written to `{spec_file}`."
+
+### 4. Resolve decision_needed findings
+
+Present each `decision_needed` finding and ask the user to decide. Once resolved, each becomes a `patch`, `defer`, or is dismissed.
+
+If deferred, ask for a one-line reason and append it to both the story file bullet and the deferred-work file.
+
+### 5. Handle patch findings
+
+If `patch` findings exist, ask:
+
+```
+How would you like to handle the {P} patch findings?
+1. Apply every patch — fix all now, no per-finding confirmation.
+2. Leave as action items — they are already in the story file (only if spec_file set).
+3. Walk through each patch — show details before deciding.
+```
+
+Wait for the numbered choice. Do not proceed until selected.
+
+- **Apply every patch**: apply all patch findings. Afterward, present a summary of changes and check off patch items in the story file if applicable.
+- **Leave as action items**: done.
+- **Walk through each patch**: present each finding with detail and suggested fix, then re-offer the menu.
+
+### 6. Update story status and sync sprint tracking
+
+Skip if `{spec_file}` is not set.
+
+Determine `{new_status}`:
+- If all `decision_needed` and `patch` findings are resolved and no unresolved issues remain → `done`
+- If patch findings were left as action items or unresolved issues remain → `in-progress`
+
+Update the story file status and save it.
+
+If `{story_key}` is set and a sprint-status file exists, update the matching `development_status` entry.
+
+### 7. Next steps
+
+Present options:
+
+```
+What would you like to do next?
+1. Start the next story — run wize-dev-story to pick up the next ready-for-dev story.
+2. Re-run code review — address findings and review again.
+3. Done — end the workflow.
+```
+
+Wait for the numbered choice.
+
+## On complete
+
+Run `{workflow.on_complete}` if non-empty.

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

@@ -1,24 +1,66 @@
 ---
+
 code: wize-code-review
+description: "Use quando um PR estiver aberto e precisar de revisão de código por pares focada em saúde do código."
 name: Code Review
 phase: 4-implementation
-owner: wize-agent-dev   # Shuri (peer Shuri — done at PR open time)
-status: stub
+owner: wize-agent-dev   # Shuri (peer review)
+status: ready
 ---
 
 # Code Review
 
-**Goal.** Self/peer review focused on code health. Separate from Hawkeye's story review.
+**Goal.** Review code changes adversarially using parallel review layers and structured triage into actionable categories.
+
+This is **Shuri's peer code review** — separate from Hawkeye's `wize-tea-review` (which audits AC fulfillment). Both run on every story PR; they are complementary.
+
+## When to run
+
+Every PR that ships code. Quick-dev PRs get a lighter review (skip architecture checks unless they touched architecture).
 
-## What this checks
-- Naming, structure, dead code
-- Test coverage and quality (not just presence)
-- Security obvious-misses
-- Performance obvious-misses
-- Architectural drift (call Tony if found)
+## Inputs
 
-## What this does NOT check
-- AC fulfillment — that's Hawkeye's `trace` + `review` + `gate`.
+- The diff, PR, branch, or commit range to review.
+- The spec/story file for context (optional but recommended).
+- Existing code style and project context from `.wize/knowledge/document-project/`.
 
 ## Outputs
-- Inline comments / suggestions on the diff.
+
+- Inline-style findings presented in the conversation.
+- Optional patch application if the user chooses to fix findings now.
+- Updated story file with a `### Review Findings` section when a spec file is provided.
+- Updated sprint status when a story key is discovered.
+
+## Workflow architecture
+
+This skill uses **step-file architecture**:
+
+- Each step is self-contained and followed exactly.
+- Sequential enforcement: complete steps in order, no skipping.
+- State tracked in frontmatter variables set at runtime.
+- Append-only building of findings.
+
+## Critical rules
+
+- **Read completely** each step file before acting.
+- **Never** load multiple step files simultaneously.
+- **Always** halt at checkpoints and wait for human input.
+- Use CWD-relative `path:line` for every code reference.
+
+## On activation
+
+1. Load `.wize/config/project.toml` and `.wize/config/user.toml`.
+2. Resolve `user_name`, `communication_language`, `document_output_language`, `implementation_artifacts`, `planning_artifacts`.
+3. Greet the user in `communication_language`.
+4. Read fully and follow `./steps/step-01-gather-context.md`.
+
+## Steps
+
+1. `step-01-gather-context.md` — identify the diff source, construct `{diff_output}`, set `{review_mode}` and `{spec_file}`.
+2. `step-02-review.md` — launch parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor).
+3. `step-03-triage.md` — normalize, deduplicate, and classify findings into `decision_needed`, `patch`, `defer`, `dismiss`.
+4. `step-04-present.md` — present findings, resolve decisions, apply patches, update story status.
+
+## Hand-off
+
+> Code review complete for `{story_key or change}`. `{decision_needed}` decision(s), `{patch}` patch(es), `{defer}` deferred, `{dismissed}` dismissed as noise. Next: re-run review or continue to `wize-tea-review` (Hawkeye).

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

@@ -0,0 +1,93 @@
+---
+
+code: wize-correct-course
+description: "Use quando o projeto desviar do plano e precisar de correção de curso com decisão documentada."
+name: Correct Course
+phase: 4-implementation
+owner: wize-agent-pm   # Maria Hill, with wize-orchestrator
+status: ready
+---
+
+# Correct Course
+
+**Goal.** React when a sprint drifts. Detect the deviation, classify the cause, propose one of three corrective moves (cut scope, re-route, escalate), and update `sprint-status.yaml` after the user confirms.
+
+Maria Hill chairs. Wizer is on call for cross-cutting decisions. The human always confirms the action.
+
+## When to run
+
+- `wize-sprint-status` flagged a risk: "slipping" or "at risk".
+- The team says "we won't make it" during a stand-up.
+- A story's TEA gate came back as `FAIL` mid-sprint.
+- An external event (incident, vendor outage) consumed capacity.
+- **Automatic trigger:** any skill that completes step 7.5 (loop verification) and hits the max-cycles guard escalates to Wizer, who runs this skill.
+- **Staleness monitor:** if `wize-sprint-status` has not been updated in 2+ days, Wizer auto-runs this skill on session start (detected in step 1).
+
+## Inputs
+
+- `.wize/implementation/sprint-status.yaml`
+- `.wize/implementation/tea/{epic}/{story}/gate.md` (when a gate failed)
+- `.wize/knowledge/document-project/risk-spots.md` (for context on known risks)
+- A free-form reason from the user: chat message, stand-up note, or incident link.
+
+## Output
+
+- Updated `.wize/implementation/sprint-status.yaml` (statuses changed, items deferred).
+- One-line entry in `.wize/implementation/course-corrections.md` with date, cause, action, owner.
+
+## Steps
+
+### 1. Detect
+
+Wizer pulls the latest status file. If `last_updated` is older than 2 days, the sprint is stale. Mark this as risk #0: stale signal.
+
+### 2. Classify
+
+Pick exactly one cause:
+
+- **Cut scope.** Story turned out larger than one PR, or a non-essential AC can be deferred.
+- **Re-route.** Story needs a different agent (e.g., Mantis for UX) or skill (e.g., `wize-investigate` for a regression).
+- **Escalate.** Story needs more hands, or a decision outside the team.
+
+A sprint can have multiple causes; the workflow handles one per run. Re-run for additional causes.
+
+### 3. Propose
+
+For each cause, propose 1–3 specific actions. Each action is bounded: a story ID to move, a date to defer to, or a person to page. No vague "communicate more" — that’s not an action.
+
+### 4. Confirm with the human
+
+List the actions; the human picks which to apply. Apply only what the human approved.
+
+### 5. Update the sprint
+
+For each approved action:
+
+- Change `sprint-status.yaml` statuses (e.g., story from `in-progress` → `backlog` if deferred).
+- Append a row to `course-corrections.md` with `date`, `cause`, `action`, `owner`.
+
+### 6. Hand off
+
+Notify the next workflow that should run (usually `wize-sprint-status` to confirm the new state, or `wize-dev-story` to continue the remaining work).
+
+## Output template — `course-corrections.md`
+
+```markdown
+# Course corrections
+
+| Date | Sprint | Cause | Action | Owner |
+|---|---|---|---|---|
+| 2026-06-15 | 4 | cut scope | E04-S02 split into S02a + S02b; S02b deferred to S5 | Hill |
+| 2026-06-15 | 4 | escalate | Paged Tony to unblock E04-S01 (waiting on ADR-010) | Wizer |
+```
+
+## Anti-patterns Hill rejects
+
+- Cutting scope without confirming the trade-off with the user.
+- Moving a story to `done` to "stop tracking it" when it isn’t actually done.
+- Re-routing to an agent who doesn’t have the context (always include a 3-sentence brief).
+- Escalating without naming a specific decision blocker.
+
+## Hand-off
+
+> "Course correction applied at `.wize/implementation/course-corrections.md`. Sprint {N} updated. Run `/wize-sprint-status` to confirm the new state."

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

@@ -1,27 +1,171 @@
 ---
+
 code: wize-create-story
+description: "Use quando um epic estiver definido e precisar criar uma story individual com acceptance criteria detalhados."
 name: Create Story
 phase: 4-implementation
 owner: wize-agent-architect   # Tony writes; Shuri may refine
-status: stub
+status: ready
 ---
 
 # Create Story
 
-**Goal.** Author one Pull-Request-sized story unit with crisp acceptance criteria.
+**Goal.** Author one Pull-Request-sized story with crisp acceptance criteria, named touch-points, and a contract for Hawkeye's `tea-design.md`. This is the single most-edited artifact in the lifecycle; make it useful.
+
+Tony drives. Shuri reads and proposes refinements before pulling the story.
+
+> **No estimates.** Never attach a time or effort estimate (hours, days, story points, S/M/L/XL) to a story — at any step. AI development speed has made them noise that only burns time and tokens. The only sizing question is binary: **does it fit one PR?** If not, slice it. Nothing else.
+
+## When to use
+
+- New story splits from an epic (most common — done in `wize-create-epics-and-stories`).
+- A story that comes in mid-sprint and needs a quick scaffold.
+- A `tea-gate` waived rationale created a follow-up story.
 
 ## Inputs
+
+Read central docs first, expand by dependency; don't pad with unrelated files:
+
+- `AGENTS.md` + `.wize/config/project.toml` — profiles, languages, conventions.
 - `.wize/solutioning/architecture.md`
 - `.wize/solutioning/epics/{epic}.md`
-- (optional) UX screen reference
+- `.wize/planning/prd.md` (the AC list)
+- `.wize/knowledge/document-project/` (brownfield baseline, if present)
+- (optional) `.wize/planning/ux/ux-design/{screen}.md`
+
+## Output
 
-## Outputs
 - `.wize/solutioning/stories/{epic}/{story-id}.md`
 
-## Story template
-(See `wize-create-epics-and-stories` for the canonical template.)
+## Steps
+
+### 1. Name it by outcome
+
+Verb-led, user-visible. *"Onboarding: invite first teammate"* not *"Build invite form."*
+
+### 2. Frontmatter
+
+```yaml
+---
+story_id: E01-S03
+epic: 01-onboarding
+status: ready-for-dev
+priority: 2          # 1=now, 2=next, 3=later
+linked_screens: [onboarding-step-1, invite-modal]
+linked_acs: [AC-02-1, AC-02-2]
+---
+```
+
+### 3. Context (3–5 lines)
+
+What place this story occupies in the user journey, why it matters here, what it depends on.
+
+### 4. ACs (lifted from PRD; not reworded)
+
+Don't reword PRD ACs in a story — copy them verbatim. If they're not crisp enough, fix in the PRD first.
+
+### 5. Out of scope
+
+Explicit. Other ACs the user might think this story touches, with a one-line reason it's not here.
+
+### 6. Sources of truth
+
+List the exact docs Shuri must read before coding: `AGENTS.md`, `project.toml`, `document-project/*`, the parent epic, `architecture.md`, the linked screen, the TEA test contract, and the related code + tests already on this path.
+
+### 7. Restrictions
+
+Beyond out-of-scope: name **protected behaviors** (what must not change), **compatibility** constraints (keys, contracts, migrations), and **security** constraints (boundary validation, authz). No silent scope creep — log recommended extras separately.
+
+### 8. Validation contract
+
+Declare the **AC → test** map and the **required checks** (unit / integration / e2e, lint, format, type-check, build, security when applicable) plus which UI states (loading / empty / error) must be asserted. Hawkeye writes the real `tea-design.md`, but this is the binding shape it fills.
+
+### 9. Notes for Shuri
+
+- Touch points: files Shuri will likely edit.
+- Reuse: components from `design-system` already named.
+- `testid` map: names Hawkeye expects.
+- Edge cases worth flagging (only ones not derivable from ACs).
+
+### 10. Notes for Hawkeye
+
+A one-paragraph hint: suggested split, fixtures, mocks, environment. Hawkeye writes the real `tea-design.md` but reads this hint.
+
+## INVEST rules
+
+Every story passes:
+
+- **I**ndependent.
+- **N**egotiable.
+- **V**aluable.
+- **S**mall (≤ 1 PR) — the *only* sizing test; if it doesn't fit one PR, slice.
+- **T**estable.
+
+(INVEST's "Estimable" is dropped on purpose — see **No estimates** above. We don't size in time or points.)
+
+If any letter fails, fix before queueing.
+
+## Full story template
+
+```markdown
+---
+story_id: E01-S03
+epic: 01-onboarding
+status: ready-for-dev
+priority: 2
+linked_screens: [onboarding-step-1, invite-modal]
+linked_acs: [AC-02-1, AC-02-2]
+---
+
+# Story: Onboarding step 1 — invite first teammate
+
+## Context
+After sign-up the admin lands on `/onboarding`. This story implements the first
+moment-of-truth from scenario S1: inviting the first teammate.
+
+## Sources of truth (Shuri reads before coding)
+- `AGENTS.md` + `.wize/config/project.toml` · `.wize/knowledge/document-project/*`.
+- `prd.md` (AC source) · `architecture.md` · `ux-design/onboarding-step-1.md` · parent epic `01-onboarding.md`.
+- The TEA test contract for this story · related code + tests already on this path.
+
+## Acceptance criteria
+- **AC-02-1:** Given a new admin on `/onboarding`, When they enter a valid email and click "Send invite", Then a `teammate_invited` event fires and the screen advances to "Invite sent" within 1s.
+- **AC-02-2:** Given an invalid email, When the user blurs the field, Then error text appears (200ms) identifying which rule failed.
+
+## Restrictions
+- **Out of scope:** bulk invite (multiple emails) → E01-S07; custom invite message → E02-S03; "Skip for now" button — not a moment-of-truth path; out.
+- **Protected behaviors:** existing sign-up + session flow must not change.
+- **Compatibility:** `(team_id, email)` composite idempotency key — don't break existing invite rows.
+- **Security:** validate email at the server boundary; auth context required on `inviteTeammate`.
+
+## Notes for Shuri (Dev)
+- Touch points: `app/(onboarding)/invite/page.tsx`, `lib/email/send-invite.ts`, new server action `inviteTeammate`.
+- Reuse: `Button` (primary), `Input`, `Banner` (success/error) from design-system.
+- testid: `invite-form`, `invite-email`, `invite-cta`, `invite-sent-banner`.
+
+## Validation contract
+- **AC → test:** AC-02-1 → E2E happy path (Playwright @chromium @ios) + unit `validateInviteEmail`; AC-02-2 → unit invalid-email rules + component error-state.
+- **Required checks:** the unit/integration/E2E split Hawkeye declares below, plus lint, format, type-check, build. Authz asserted on the server action.
+- **States:** loading, empty, error rendered and asserted.
+
+## Notes for Hawkeye (TEA)
+Suggested split: 4 unit, 1 integration, 1 E2E.
+- Unit: validateInviteEmail, mailer payload, server action error mapping, retry policy.
+- Integration: server action calls mailer with right args (MSW on Resend).
+- E2E: happy path on Playwright @chromium @ios.
+- Risk: R-1 (mailer) — extra E2E asserts banner within 1s of click.
+
+## Done means
+Every AC has a passing test (mapped above), gate PASS/CONCERNS, story `status: ready-for-review`, knowledge axes updated if touched.
+```
+
+## Anti-patterns Tony rejects
+
+- **ACs reworded from PRD.** Source-of-truth drift.
+- **Stories with no touch points.** Shuri spends an hour finding the files.
+- **No notes for Hawkeye.** TEA designs in the dark.
+- **Stories named by feature** ("Add invite button") — name by **outcome**.
+
+## Hand-off
 
-## Rules
-- One story = one PR. If two, split.
-- Each AC must be testable. If Hawkeye can't write a test for it, rewrite the AC.
-- "Out of scope" is mandatory. Force the cut.
+> Story E01-S03 ready. Shuri, pull when sprint allows. Hawkeye, `tea-design.md` for this story whenever you're ready.

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.