wize-dev-kit 0.16.0 → 0.16.1

package/src/tea-skills/wize-tea-nfr/workflow.md

@@ -1,37 +1,130 @@
 ---
+
 code: wize-tea-nfr
+description: "Use quando um epic estiver próximo do merge e precisar verificar se atende aos princípios de NFR definidos pelo Fury."
 name: TEA NFR Assessment
+phase: 4-implementation
 gate: nfr
 owner: wize-agent-test-architect   # Hawkeye
 when: pre-merge-per-epic
-status: stub
+status: ready
 ---
 
 # TEA — NFR Assessment
 
-**Goal.** Verify the epic meets Fury's NFR principles: performance, security, reliability, maintainability, accessibility, cost.
+**Goal.** Verify that the **epic** as a whole meets Fury's NFR principles: performance, security, reliability, maintainability, accessibility, cost. Story-level gates miss NFRs that emerge only at integration; this gate catches them.
+
+Hawkeye drives. Tony reviews perf + security findings. Fury escalates if a non-negotiable is at risk. Runs **per epic**, just before any of its stories merges.
 
 ## Inputs
-- `.wize/planning/nfr-principles.md`
+
+- `.wize/planning/nfr-principles.md` (Fury's targets)
 - Code from all stories in the epic
-- Telemetry/benchmark output
+- Telemetry / benchmark output (lighthouse, web-vitals, macrobenchmark, Sentry perf)
+- Overlay perf playbooks: `web-perf-budgets.md`, `mobile-perf-budgets.md`
 
 ## Output
+
 - `.wize/implementation/tea/nfr/{epic}.md`
 
-## YAML frontmatter
+## Steps
+
+### 1. For each category, run the verifier
+
+| Category | Verifier (typical) |
+|---|---|
+| Performance | lighthouse-ci against epic-scope routes; web-vitals beacon delta |
+| Security | `npm audit --omit=dev`; manual OWASP Top 10 walk; secret scan |
+| Reliability | injected-failure tests (`@chaos` tag); retry policy review; idempotency check |
+| Maintainability | coverage delta; cyclomatic complexity delta; lint baseline |
+| Accessibility | axe on every epic-scope route; keyboard walk on critical flows |
+| Cost | cost dashboard delta in the epic window |
+
+### 2. Score each
+
+For each category: `PASS` (meets non-negotiable) / `CONCERNS` (within stretch range; below non-negotiable on a measurable item with mitigation plan) / `FAIL` (non-negotiable missed; no plan) / `WAIVED` (with documented reason + sign-off).
+
+### 3. Findings (one per slip)
+
+If anything failed or concerned, write the finding: what we measured, what was expected, why the slip, what the next step is.
+
+### 4. Hand off
+
+`PASS` → epic can merge. `CONCERNS` (advisory) → flag in PR description. `FAIL` (enforcing) → blocks merge.
+
+## YAML frontmatter (canonical)
+
 ```yaml
 ---
 gate: nfr
-epic: …
-status: PASS | CONCERNS | FAIL | WAIVED
+epic: 01-onboarding
+status: CONCERNS
 scores:
-  performance: …
-  security: …
-  reliability: …
-  maintainability: …
-  accessibility: …
-  cost: …
-findings: [...]
+  performance: PASS
+  security: PASS
+  reliability: CONCERNS
+  maintainability: PASS
+  accessibility: PASS
+  cost: PASS
+findings:
+  - id: NFR-01-1
+    category: reliability
+    severity: medium
+    summary: "Outbox retry interval too aggressive for Resend's documented backoff."
+    expected: "Exponential 30s/2m/10m; we set 5s/15s/45s."
+    actual: "Spike in Resend 429s during integration test."
+    recommendation: "Update retry policy in `lib/email/outbox.ts`; capture with `outbox-retry.spec.ts`."
+    owner: shuri
+    blocking: false
+created_at: 2026-06-11T18:00:00Z
 ---
 ```
+
+## Body of `nfr/{epic}.md`
+
+```markdown
+## Summary
+Epic 01 (onboarding) at gate. Performance and a11y pass non-negotiables; reliability has one mid-severity concern around outbox backoff.
+
+## Per category
+
+### Performance — PASS
+- LCP (signup): 1.45s p75 (target ≤ 2.5s).
+- INP (signup): 90ms p75 (target ≤ 200ms).
+- CLS (signup): 0.03 (target ≤ 0.1).
+- LCP (onboarding): 1.7s p75.
+
+### Security — PASS
+- `npm audit` clean (dev advisories noted in `.audit-ignore.md`).
+- OWASP Top 10 walk: no findings.
+- RLS verified on `users`, `teams`, `memberships`.
+
+### Reliability — CONCERNS
+- See NFR-01-1.
+
+### Maintainability — PASS
+- Coverage 84% on logic modules in this epic.
+- No file > 300 LOC introduced.
+
+### Accessibility — PASS
+- axe clean on `/signup`, `/signup/error`, `/onboarding`, `/onboarding/invite-sent`.
+- Keyboard walk: focus order matches visual; modal traps + restores.
+
+### Cost — PASS
+- No cost dashboard change beyond expected (account creation; mailer spend within budget).
+
+## Action items
+- Shuri: PR-XXX fixes NFR-01-1. Re-run NFR after merge.
+- Hawkeye: re-baseline web-vitals after epic ships to prod.
+```
+
+## Anti-patterns Hawkeye rejects
+
+- **Self-reported "looks fine" with no verifier output.** Attach the artifact.
+- **Concerns left for "later."** Either an action item with owner+deadline or it's not a concern.
+- **Waived without sign-off.** WAIVED needs `waived_by: NAME` + reason.
+- **NFR run on stage with synthetic data.** Use realistic distributions whenever possible.
+
+## Hand-off
+
+> NFR gate for Epic 01: **CONCERNS**. PR can proceed if the reliability finding (NFR-01-1) is committed to be addressed in the next sprint. Otherwise hold the merge.

package/src/tea-skills/wize-tea-review/workflow.md

@@ -1,35 +1,145 @@
 ---
+
 code: wize-tea-review
+description: "Use quando uma story terminar implementação e precisar de revisão estruturada de AC fulfillment, disciplina de teste e cobertura de risco."
 name: TEA Story Review
+phase: 4-implementation
 gate: review
 owner: wize-agent-test-architect   # Hawkeye
 when: story-end
-status: stub
+status: ready
 ---
 
 # TEA — Story Review
 
-**Goal.** Structured story review (separate from Shuri's `wize-code-review`).
+**Goal.** A structured review of one story before its gate decision. Distinct from Shuri's `wize-code-review` (which audits code health). This one audits **AC fulfillment, test discipline, and risk-spot coverage**.
+
+Hawkeye drives. Runs at story end, right before `tea-gate`.
 
 ## Inputs
-- Story file (ACs)
-- Test results
-- Trace doc
+
+- Story file (the AC list, out-of-scope, notes).
+- `tea-design.md` + `tea-trace.md`.
+- Test run results (PR CI).
+- Code diff (the PR).
 
 ## Output
+
 - `.wize/implementation/tea/{epic}/{story}/review.md`
 
-## YAML frontmatter
+## Steps
+
+### 1. AC check (per AC)
+
+For each AC, observe the actual behavior on a staging or local build and decide: `met` / `partial` / `not-met`. Use the recorded video/screenshot when CI captured one (Playwright `screenshot: only-on-failure` or always for review tag).
+
+### 2. Test discipline
+
+Walk:
+- Are `tea-design.md`'s declared tests present in code?
+- Is every assertion meaningful (not just `expect(true).toBe(true)`)?
+- Are selectors stable (role/label/testid) rather than brittle (CSS classes)?
+- Are mocks at the network boundary (MSW) rather than in the unit under test?
+- Are there `test.skip` or `test.only` left in?
+
+### 3. Risk-spot coverage
+
+If the story touches any `R-x` from the risk profile, walk the mitigation contract and confirm it's met.
+
+### 4. Story scope discipline
+
+Did the story stay within its declared scope? Any out-of-scope item that crept in is flagged in the review (and either moved to a new story or backed out).
+
+### 5. Knowledge update check
+
+Did this story touch any of the 5 `document-project` axes (architecture / conventions / risk-spots / dependencies / overview)? If yes, walk the PR diff and confirm the corresponding `.wize/knowledge/document-project/*.md` got 1–3 new lines this commit.
+
+Decision:
+- **Touched + updated** → record as PASS, no finding.
+- **Touched + NOT updated** → record finding `KN-NN` (severity `medium`); recommendation: `gate CONCERNS` (advisory mode) or `gate FAIL` (enforcing).
+- **Not touched** → write `knowledge: n/a` in the body, move on.
+
+This is what keeps the brownfield baseline alive instead of stale. Without it, `document-project` is honest in week 1 and obsolete in week 24.
+
+### 6. Findings
+
+For each issue, write: severity (`low / medium / high`), what, why it matters, what to do.
+
+### 7. Recommend gate outcome
+
+Review doesn't *make* the gate decision (that's `tea-gate`); it recommends. Possible recommendations:
+- `gate PASS`
+- `gate CONCERNS` with N findings
+- `gate FAIL` (only if a non-negotiable AC is `not-met`)
+- `gate WAIVED` (only with documented reason + senior signoff)
+
+## YAML frontmatter (canonical)
+
 ```yaml
 ---
 gate: review
-story_id: …
-status: PASS | CONCERNS | FAIL
+story_id: E01-S03
+status: PASS
 ac_check:
-  - id: AC-1
-    met: true|partial|false
-    evidence: …
-findings: [...]
-recommendations: [...]
+  - id: AC-02-1
+    met: true
+    evidence: "e2e/onboarding/invite.spec.ts::happy path passed on PR-#412; recording in CI artifact #412-1"
+  - id: AC-02-2
+    met: true
+    evidence: "InviteForm.spec.tsx::error region announces"
+knowledge_axes_touched: [conventions, risk-spots]
+knowledge_axes_updated: [conventions, risk-spots]   # leave empty array if axes touched but no update happened
+findings:
+  - id: REV-01
+    severity: low
+    summary: "Empty-state copy slightly differs from Mantis' spec."
+    recommendation: "Update `<EmptyTeamPanel>` heading to 'Invite your first teammate'."
+    owner: shuri
+    blocking: false
+risk_links: [R-1]
+recommendation: gate-PASS
+created_at: 2026-06-11T20:00:00Z
 ---
 ```
+
+## Body of `review.md`
+
+```markdown
+## Per-AC
+
+### AC-02-1 — met
+Evidence: E2E `e2e/onboarding/invite.spec.ts::happy path` passed locally + CI run #412. Banner appears 720ms after click (well within 1s NFR).
+
+### AC-02-2 — met
+Evidence: Unit + component test both pass. Manually walked screen-reader output — VoiceOver announces "Email — error — Enter a valid email." correctly.
+
+## Test discipline
+- All declared tests present.
+- `data-testid` discipline solid (invite-form, invite-email, invite-cta, invite-sent-banner).
+- No `test.skip` / `.only`.
+- One snapshot test — small enough to be useful; not a tree snapshot.
+
+## Risk coverage
+- R-1 (mailer): integration test covers the right path; happy path E2E confirms end-to-end. PASS.
+
+## Scope discipline
+- Two minor copy tweaks crept in (out-of-spec; logged as REV-01).
+
+## Findings
+- REV-01 (low): empty-state copy.
+
+## Recommendation
+Recommend `gate PASS` with one low-severity finding to fix in a follow-up.
+```
+
+## Anti-patterns Hawkeye rejects
+
+- **Review without walking the code.** Reading the test names isn't review.
+- **AC marked "met" without observed evidence.** Tests passing + screenshot/recording, please.
+- **Findings without owners.** Same as everywhere else in the kit.
+- **Recommending PASS when an AC is `partial`.** No.
+- **Recommending PASS when a non-negotiable NFR slipped.** That's a gate FAIL.
+
+## Hand-off
+
+> Review for E01-S03 at `.wize/implementation/tea/E01-S03/review.md`. All ACs `met`, one low-severity copy finding. Recommending `gate PASS`. Final at `wize-tea-gate`.

package/src/tea-skills/wize-tea-risk/workflow.md

@@ -1,39 +1,142 @@
 ---
+
 code: wize-tea-risk
+description: "Use quando a arquitetura for assinada e precisar construir a matriz probabilidade × impacto que prioriza todo o trabalho de TEA."
 name: TEA Risk Profile
+phase: 4-implementation
 gate: risk
 owner: wize-agent-test-architect   # Hawkeye
 when: once-after-architecture
-status: stub
+status: ready
 ---
 
 # TEA — Risk Profile
 
-**Goal.** Build the probability × impact matrix that prioritizes the rest of TEA's work.
+**Goal.** Build the **probability × impact** matrix that prioritizes the rest of TEA's work. Areas in `HIGH` get deep test design; areas in `LOW` get smoke. Without a risk profile, every story is tested the same — wasteful, and unsafe.
+
+Hawkeye drives. Tony co-signs. Runs **once**, right after architecture is signed off; revisit only on significant scope or architecture changes.
 
 ## Inputs
+
 - `.wize/solutioning/architecture.md`
 - `.wize/solutioning/epics/`
+- `.wize/planning/nfr-principles.md`
+- `.wize/knowledge/document-project/risk-spots.md` (brownfield)
+- `.wize/knowledge/document-project/index.md` (documentation gap markers)
 
 ## Output
+
 - `.wize/implementation/tea/risk-profile.md`
 
+## Steps
+
+### 1. List candidate hot spots
+
+For every architectural component + every epic, ask: *"If this misbehaves, what hurts?"*. Write candidates without filtering.
+
+### 2. Score each
+
+| Axis | Levels |
+|---|---|
+| Probability | `low` (would be a surprise), `medium` (could happen), `high` (likely without explicit work) |
+| Impact | `low` (cosmetic / opex), `medium` (user friction / revenue dent), `high` (data loss / outage / regulatory) |
+
+Composite score:
+- `low × low` = LOW
+- `low × medium`, `medium × low`, `medium × medium` = MEDIUM
+- anything touching `high` = HIGH
+
+### 3. For each finding, write the mitigation contract
+
+Per row:
+- **What test makes us confident?** Unit / integration / E2E / NFR / manual.
+- **Who owns the mitigation?** Shuri / Tony / external service.
+- **When is it verified?** Story-level / epic-level / pre-launch.
+
+### 4. Hand off
+
+Hawkeye uses this in every `tea-design.md`. Tony respects it when picking ADR options.
+
 ## YAML frontmatter (canonical)
+
 ```yaml
 ---
 gate: risk
 status: PASS | CONCERNS | FAIL | WAIVED
 score: 0-100
-created_at: ISO-8601
+created_at: 2026-06-11T12:00:00Z
 findings:
   - id: R-1
-    area: …
-    probability: low | medium | high
-    impact: low | medium | high
-    rationale: …
-    mitigation: …
+    area: "Outbox / mailer"
+    probability: high
+    impact: medium
+    rationale: "Sign-up flow depends on email delivery; first impression failure is high-cost."
+    mitigation: "Integration test against Resend sandbox; outbox retry with backoff; on-call alert on delivery failure rate > 5%."
+    owner: shuri + tony
+    verified_when: story E01-S04 + NFR per epic
+  - id: R-2
+    area: "Database migrations under load"
+    probability: medium
+    impact: high
+    rationale: "Future migrations must be rolled out without lock contention."
+    mitigation: "Online schema changes; canary on staging with synthetic load; ADR-006 process."
+    owner: tony
+    verified_when: pre-launch
+  - id: R-3
+    area: "Auth: token refresh during long-running tabs"
+    probability: medium
+    impact: medium
+    rationale: "Cookie refresh race in RSC + edge can sign user out unexpectedly."
+    mitigation: "E2E covering > 1h tab; refresh strategy ADR-008; on-call alert on `auth_session_expired_unexpected`."
+    owner: shuri
+    verified_when: story E04-S02 + post-launch monitoring
 ---
 ```
 
-## Body
-Narrative summary; the structured data is the YAML.
+## Body of `risk-profile.md`
+
+The narrative explains the matrix; the YAML is the structured truth. Hawkeye writes 1–2 lines per finding explaining the *why*.
+
+```markdown
+## Matrix
+
+| | Impact LOW | Impact MEDIUM | Impact HIGH |
+|---|---|---|---|
+| **Prob HIGH** | R-7 | R-1 | R-2 |
+| **Prob MEDIUM** | R-4 | R-3 | R-5 |
+| **Prob LOW** | — | R-6 | — |
+
+## Top-3 (drive test design)
+
+1. **R-2** — Database migrations under load. Pre-launch verification mandatory.
+2. **R-1** — Outbox/mailer. Story E01-S04 covers; epic NFR re-verifies.
+3. **R-5** — Payment idempotency. Story E03-S02 covers.
+
+## What this means for `tea-design.md`
+
+- E01-S04 (mailer): 1 unit (retry policy), 1 integration (Resend sandbox), 1 E2E (sign-up arrives within 5min).
+- E03-S02 (payments): 2 integration (Stripe idempotency keys), 1 E2E (double-click guard).
+- Other stories follow the default 70/20/10 split.
+```
+
+## Documentation gap risk category
+
+In brownfield repos, missing or stale documentation is an operational risk: new contributors make unsafe assumptions, AI agents hallucinate context, and reviews miss implicit contracts. Hawkeye treats it as a first-class risk area.
+
+| Symptom | Severity | Rationale | Mitigation |
+|---|---|---|---|
+| `index.md` contains `_(To be generated)_` markers | medium | Conditional docs were skipped; the baseline is incomplete. | Schedule `wize-document-project initial_scan` for the next cooldown. |
+| Baseline files older than 60 days | medium | Docs may no longer reflect the codebase. | Run `wize-refresh-knowledge` at sprint end. |
+| No baseline exists in a brownfield repo | high | Team is flying blind; architecture and conventions are tribal knowledge. | Run `wize-dev-kit document-project quick` immediately. |
+
+## Anti-patterns Hawkeye rejects
+
+- **Findings without mitigation.** A finding without a contract is a wish.
+- **Mitigation owned by "the team."** Name a persona/human.
+- **HIGH impact, MEDIUM probability, no NFR re-check.** Wire it into epic NFR gate.
+- **Cosmetic risks scored HIGH.** Calibration. Reserve HIGH for data, outage, regulatory.
+- **Risk profile rewritten per sprint.** Run once; revise on real architecture changes.
+
+## Hand-off
+
+> Risk profile at `.wize/implementation/tea/risk-profile.md`. Top-3 drive deep `tea-design.md` for E01-S04, E03-S02, plus pre-launch migration drill. Default 70/20/10 split for the rest.

package/src/tea-skills/wize-tea-trace/workflow.md

@@ -1,36 +1,110 @@
 ---
+
 code: wize-tea-trace
+description: "Use quando uma story estiver em implementação e precisar mapear cada AC para testes concretos no repositório."
 name: TEA Traceability
+phase: 4-implementation
 gate: trace
 owner: wize-agent-test-architect   # Hawkeye
 when: during-or-after-implementation
-status: stub
+status: ready
 ---
 
 # TEA — Traceability
 
-**Goal.** Map every Acceptance Criterion to one or more concrete tests in the repo.
+**Goal.** Map every Acceptance Criterion to **one or more concrete tests in the repo**. Reports honest coverage: `covered`, `partial`, `missing`. A story with `missing` rows cannot pass gate.
+
+Hawkeye drives. Runs while Shuri implements (or right after PR open).
 
 ## Inputs
-- Story file (ACs)
-- Test files produced by Shuri
+
+- Story file (the AC list).
+- `tea-design.md` (the test contract).
+- Repo (the actual test files).
 
 ## Output
+
 - `.wize/implementation/tea/{epic}/{story}/trace.md`
 
-## YAML frontmatter
+## Steps
+
+### 1. Walk every AC
+
+For each AC ID:
+- Find the test(s) that exercise it.
+- Reference the file + test name precisely.
+- Decide status: `covered` (every assertion of the AC has a test) / `partial` (some assertions only) / `missing` (no test).
+
+### 2. Compute coverage score
+
+- `covered_count / total_acs`.
+- Reported but doesn't drive gate alone; the **per-AC status** drives gate.
+
+### 3. Flag holes
+
+For every `partial` / `missing`, write what's needed in one line. Hawkeye proposes the test; Shuri writes it.
+
+### 4. Hand off
+
+If everything is `covered`, status `PASS`. Otherwise `CONCERNS` (advisory) or `FAIL` (enforcing) until holes are closed.
+
+## YAML frontmatter (canonical)
+
 ```yaml
 ---
 gate: trace
-story_id: …
-status: PASS | CONCERNS | FAIL
+story_id: E01-S03
+status: PASS
 coverage:
-  - ac_id: AC-1
+  - ac_id: AC-02-1
+    status: covered
+    tests:
+      - "src/onboarding/invite/__tests__/validateInviteEmail.spec.ts::valid email"
+      - "src/onboarding/invite/__tests__/inviteTeammate.spec.ts::calls mailer with right args"
+      - "e2e/onboarding/invite.spec.ts::happy path on Playwright @chromium"
+  - ac_id: AC-02-2
+    status: covered
     tests:
-      - path/to/test.spec.ts::case-name
-    status: covered | partial | missing
+      - "src/onboarding/invite/__tests__/validateInviteEmail.spec.ts::invalid email rules"
+      - "src/onboarding/invite/__tests__/InviteForm.spec.tsx::error region announces"
+created_at: 2026-06-11T15:30:00Z
 ---
 ```
 
-## Body
-For any `missing` or `partial`, propose what to write.
+## Body of `trace.md`
+
+```markdown
+## Per-AC
+
+### AC-02-1 — covered
+Tests:
+- `validateInviteEmail.spec.ts::valid email`
+- `inviteTeammate.spec.ts::calls mailer with right args`
+- `e2e/onboarding/invite.spec.ts::happy path`
+
+### AC-02-2 — covered
+Tests:
+- `validateInviteEmail.spec.ts::invalid email rules`
+- `InviteForm.spec.tsx::error region announces`
+
+## Edges (from `design.md`)
+
+- E1 (empty) — covered (validateInviteEmail.spec.ts::empty).
+- E3 (idempotency) — **partial**. Integration test exists but doesn't assert second insert is no-op. Propose: assert `db.invites.count({ email, team_id })` = 1 after two calls.
+- E4 (offline) — **missing**. Propose: Playwright `context.setOffline(true)` before click; assert offline banner.
+
+## Action items
+- Shuri: add the missing offline E2E (or split into next story; flag in `review.md` then).
+- Hawkeye: re-run trace once PR has the new tests.
+```
+
+## Anti-patterns Hawkeye rejects
+
+- **Trace by file count, not per-AC.** "We have 24 tests" tells you nothing. Per AC, please.
+- **Counting passing CI as trace.** CI passes when a test exists; trace cares whether the test exercises the AC.
+- **`partial` left unflagged.** Either close or list as a known-open with story link.
+- **Re-naming tests after trace.** The trace breaks; Shuri renames in agreement with Hawkeye or doesn't rename.
+
+## Hand-off
+
+> Trace for E01-S03 at `.wize/implementation/tea/E01-S03/trace.md`. All ACs `covered`. Two edges still open (E3, E4); proposing follow-up. Ready for `tea-review`.

package/src/web-overlay/wize-web-deploy/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-web-deploy
+description: "Use quando o projeto web estiver pronto para deploy e precisar do playbook de publicação."
 name: Web Deploy Playbook
 overlay: web
 owner: wize-agent-architect   # Tony

package/src/web-overlay/wize-web-scaffold/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-web-scaffold
+description: "Use quando precisar criar o scaffold inicial de um projeto web com a stack aprovada pelo Fury."
 name: Web Scaffold
 overlay: web
 owner: wize-agent-architect   # Tony executes; Fury approves stack family

package/src/web-overlay/wize-web-seo-audit/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-web-seo-audit
+description: "Use quando o projeto web estiver no ar e precisar de auditoria de SEO."
 name: Web SEO Audit
 overlay: web
 owner: wize-agent-pm   # Maria Hill commissions; Mantis + Tony execute