wize-dev-kit 0.1.5 → 0.2.5

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

@@ -3,22 +3,97 @@ code: wize-sprint-planning
 name: Sprint Planning
 phase: 4-implementation
 owner: wize-agent-pm   # Maria Hill
-status: stub
+status: ready
 ---
 
 # Sprint Planning
 
-**Goal.** Pick what enters this sprint. Capacity-honest, priority-honest.
+**Goal.** Pick what enters this sprint. Capacity-honest, priority-honest, risk-honest. The sprint is a commitment about a small slice of the future, not a wish list.
+
+Maria Hill chairs. Tony advises on slicing. Hawkeye flags risk on stories. Shuri commits to the load.
 
 ## Inputs
-- Story backlog from `.wize/solutioning/stories/`
-- Velocity history (if exists) from `.wize/implementation/sprint-status.md`
-- Hawkeye risk profile (`risk-profile.md`)
 
-## Outputs
-- Sprint entry appended to `.wize/implementation/sprint-status.md`
+- Story backlog: `.wize/solutioning/stories/`
+- Velocity history: `.wize/implementation/sprint-status.md` (previous sprints) — when present.
+- `.wize/implementation/tea/risk-profile.md`
+- Open `tea-gate` outcomes from last sprint.
+- Team availability for the next interval (vacations, on-call rotation, planned meetings).
+
+## Output
+
+- New sprint block appended to `.wize/implementation/sprint-status.md`.
+- Story files updated `priority: 1` for chosen stories.
 
 ## Rules
-- High-risk stories get TEA design done first or are deferred.
-- Velocity = the smaller of "what we shipped last sprint" and "what we estimate we can ship this sprint."
-- Stretch goals are explicit, not silent.
+
+1. **Capacity = min(history velocity, declared availability).** Not the average of optimistic estimates.
+2. **High-risk stories** (linked to `R-x` HIGH in risk profile) get TEA design done in the planning meeting, not at story start.
+3. **Stretch goals** are explicit, named, not silent. If a stretch ships, great. If not, the sprint isn't a failure.
+4. **Don't carry over without reason.** A carried-over story gets a one-line "why" in the sprint log.
+
+## Steps
+
+### 1. Look back (3 min)
+
+Last sprint: what shipped, what slipped, what surprised. Don't relitigate; observe.
+
+### 2. Refresh capacity
+
+- Person-days available this sprint = sum(working days) × (1 - meetings load).
+- Subtract on-call burden, oncall handoff time, planned reviews.
+
+### 3. Pull stories (in priority order)
+
+Default selection algorithm:
+- Always pull continuation stories (in-flight from last sprint) first.
+- Then highest-priority stories that fit the capacity.
+- Then risk-driven: high-risk stories (R-HIGH) preferred over more low-risk ones when capacity is tight.
+
+For each pulled story, confirm INVEST still holds; re-slice if needed.
+
+### 4. Reserve buffer
+
+10–15% buffer for unknowns (bug fixes, support escalations). Don't fill the sprint to 100% — you'll always pay.
+
+### 5. Walk the gate plan
+
+For each story pulled, what's the TEA gate cadence? Most stories: design at start, trace + review + gate at end. High-risk: include NFR re-check at epic close.
+
+### 6. Commit (verbal + written)
+
+Each engineer reads back the stories they're owning. Hill writes them into the sprint block. Sprint starts.
+
+## Sprint block template (appended to `sprint-status.md`)
+
+```markdown
+## Sprint 7 — 2026-06-12 → 2026-06-25
+
+**Capacity:** 24 person-days (3 engineers × 10 days × 0.8 utilization)
+**Carry-over:** E01-S05 (90% done; Shuri); E03-S01 (TEA review pending)
+**Pulled:**
+- E01-S06 — M — owner: Shuri — gate cadence: design+gate
+- E02-S02 — L — owner: Shuri — gate cadence: design+trace+review+gate (R-3)
+- E03-S02 — M — owner: Aaliyah — gate cadence: design+trace+review+gate (R-1)
+- E04-S01 — S — owner: Shuri — gate cadence: smoke (quick-dev pattern)
+- E02-S03 — S — stretch
+
+**Out (deferred to Sprint 8):**
+- E03-S03 — reason: depends on E03-S02 ADR
+- E05-S01 — reason: out of NFR-cost budget; revisit
+
+**Risks flagged:**
+- E02-S02 — auth refresh story; high-risk; TEA design done at planning.
+```
+
+## Anti-patterns Hill rejects
+
+- **"Optimistic" velocity that ignores history.** Use observed velocity.
+- **Stories pulled without owners.** Don't aspire; commit.
+- **Stretch goals so big they're really plan.** Stretch = optional, not "we hope we can."
+- **Pulling a story when its dependency hasn't shipped.** It will sit blocked.
+- **No buffer.** Real sprints have surprises.
+
+## Hand-off
+
+> Sprint 7 committed at `.wize/implementation/sprint-status.md`. Shuri owns most; Aaliyah picks up E03-S02. Hawkeye, NFR gate due on E03 at sprint end. Wizer, retro on the 25th.

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

@@ -3,23 +3,108 @@ code: wize-sprint-status
 name: Sprint Status
 phase: 4-implementation
 owner: wize-agent-pm   # Maria Hill
-status: stub
+status: ready
 ---
 
 # Sprint Status
 
-**Goal.** Daily snapshot of in-flight stories. Blockers up front.
+**Goal.** Keep a snapshot of in-flight work that the team and stakeholders can read in 60 seconds. Sprint status is read by everyone, written by Hill (or delegated to Wizer); the source of truth is the file, not Slack.
 
-## Outputs
-- Updates appended to `.wize/implementation/sprint-status.md`
+Update **daily** during a sprint, or after any state change (story moves, blocker appears, gate fails).
+
+## Inputs
+
+- `.wize/solutioning/stories/` (current statuses)
+- `.wize/implementation/tea/{epic}/{story}/gate.md` (gate outcomes)
+- The team (verbal stand-up or async update)
+
+## Output
+
+- Updated entry in `.wize/implementation/sprint-status.md`.
+
+## Steps
+
+### 1. Per story, name a status
+
+| Status | Meaning |
+|---|---|
+| `pulled` | Committed for this sprint, not started yet |
+| `in-progress` | Engineer actively working it (or paused < 1 day) |
+| `paused` | Started, paused > 1 day, reason listed |
+| `blocked` | Cannot proceed; depends on a named external resolution |
+| `in-review` | PR open; Hawkeye running design → trace → review |
+| `gate-PASS` / `gate-CONCERNS` / `gate-FAIL` | TEA gate outcome |
+| `shipped` | Merged to main + deployed (when applicable) |
+
+### 2. Blockers up front
+
+Blockers always appear in the top section. Each gets:
+- Owner (the person who can unblock it).
+- Specific ask (the action they should take).
+- Deadline.
+
+If a blocker sits longer than 2 days, Hill escalates. Stalled blockers are how sprints fail silently.
+
+### 3. Trend
+
+Daily, write a one-line trend: *"On track."* / *"At risk for E03-S02 due to vendor outage."* / *"Slipping; will defer E04-S01 to next sprint."*
+
+### 4. Capture decisions
+
+If something material was decided during the sprint that affects the plan (story sliced, scope dropped, ADR opened), append a one-line entry.
+
+## File template
 
-## Format
 ```markdown
-## Sprint N — Day D
-- Story E01-S03 — in progress (Shuri). Blocked: no.
-- Story E01-S04 — TEA design — Hawkeye.
-- Story E02-S01 — done (gate PASS).
+# Sprint status
 
-Blockers:
-- (none) | or specific list
+## Sprint 7 — 2026-06-12 → 2026-06-25
+
+### Day 4 (2026-06-15)
+**Trend:** On track.
+
+**Blockers:**
+- (none)
+
+**Stories:**
+- E01-S05 — gate-PASS — shipped (carry-over from S6).
+- E01-S06 — in-progress — Shuri.
+- E02-S02 — in-review — PR #418; Hawkeye doing trace.
+- E03-S02 — in-progress — Aaliyah.
+- E04-S01 — pulled — Shuri starts after E01-S06.
+- E02-S03 (stretch) — pulled — Aaliyah picks up if capacity allows.
+
+**Decisions:**
+- E03-S03 sliced into two stories (E03-S03a, E03-S03b) — ADR-009 incoming.
+
+### Day 5 (2026-06-16)
+**Trend:** At risk on E02-S02 (vendor sandbox down; Hawkeye unblocked at 14:00).
+**Blockers:** Resolved.
+**Stories:** (changes from Day 4)
+- E02-S02 — gate-PASS at 16:30; merged.
+- E01-S06 — in-review — PR #419.
+
+## Sprint 6 — 2026-05-29 → 2026-06-11
+{{archived}}
 ```
+
+## Daily cadence (lean)
+
+A daily standup, when present, is 5 minutes max:
+
+- "What did I ship since last time?"
+- "What am I shipping next?"
+- "Anything blocking me?"
+
+Hill updates `sprint-status.md` immediately after; Wizer reads it before any other agent's session that day.
+
+## Anti-patterns Hill rejects
+
+- "Status: in progress" for 4 days with no further detail. Either it really is, in which case slice progress, or it's stuck.
+- Blockers without an owner or a deadline.
+- Sprint goals that drift silently (added stories without removing others).
+- Stale entries in the file. Update daily or delegate the update.
+
+## Hand-off
+
+> `sprint-status.md` updated. Day 5 trend: at-risk-mitigated. Wizer, if asked about state, the file is the answer. Pepper, brief stays valid; no scope move triggered.

package/src/orchestrator-skills/wize-help/skill.md

@@ -58,10 +58,34 @@ Apply this heuristic, top-down. Stop at the first match.
 12. **Has active sprint, oldest in-flight story has no `tea/.../design.md`.** → Next: **Hawkeye / `wize-tea-design`** for that story.
 13. **In-flight story exists, no implementation commits.** → Next: **Shuri / `wize-dev-story`** on that story.
 14. **In-flight story exists with code, no `gate.md`.** → Next: **Hawkeye / `wize-tea-trace` → `wize-tea-review` → `wize-tea-gate`** for that story.
-15. **All stories gated.** → Next: **Wizer / `wize-retrospective`** + plan next epic.
+15. **All sprint stories gated `PASS`/`CONCERNS`, backlog has no `ready-for-dev` left.** → Sprint ended. Next: **Wizer / `wize-retrospective`** + **Pepper+Peggy / `wize-refresh-knowledge`** (the inline knowledge notes pile up over the sprint; the refresh consolidates them into the baseline docs).
+16. **All stories gated and no new epic pulled.** → Plan next epic with Tony + Hill, or run a roadmap session.
 
 For brownfield repos where `.wize/knowledge/document-project/` is missing, prepend: "Run `wize-document-project` first to baseline the codebase."
 
+## Step 2.5 — version-skew detection (proactive)
+
+Before routing, compare:
+- `kit_version` in `.wize/config/project.toml`
+- The version of the installed kit (from `node_modules/wize-dev-kit/package.json` — *or* the version baked into the activated skills if you don't have a node-side check)
+
+If you have access to the user's terminal (Claude Code Bash tool, Codex exec, OpenCode), additionally check the npm registry with a 2-second timeout:
+
+```bash
+npm view wize-dev-kit version 2>/dev/null
+```
+
+Cases:
+- **Installed version > project.toml's `kit_version`** → suggest `npx wize-dev-kit update` (no `@latest` needed; the installed version is already newer).
+- **Registry > installed version** → suggest `npx wize-dev-kit@latest update` to pick up the newer release.
+- **All three match** → no message; carry on.
+
+Phrase it as one short line, not a banner. Example:
+
+> *"Heads up: registry has 0.2.3, you're on 0.2.2. Want me to run `npx wize-dev-kit@latest update`? (it preserves your `user.toml` and re-renders adapters)"*
+
+If the user says yes and you can execute Bash, run it in the project root and stream output. Otherwise, print the command for them to run.
+
 ## Step 3 — respond
 
 Default response shape (3 lines). When `user.toml` provides a `[user] name`, include it in the greeting:

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

@@ -4,35 +4,126 @@ name: TEA Test Design
 gate: design
 owner: wize-agent-test-architect   # Hawkeye
 when: per-story-start
-status: stub
+status: ready
 ---
 
 # TEA — Test Design
 
-**Goal.** For one story: declare the test split (unit / integration / e2e), required fixtures, mocks, environments.
+**Goal.** For **one story**: declare the test split, the fixtures, the mocks, the environments, and the assertion targets. This is Hawkeye's contract Shuri implements against. No story enters dev without one.
+
+Hawkeye drives. Runs at the start of every story (advisory; can be relaxed only when `tea.toml` says so).
 
 ## Inputs
+
 - `.wize/solutioning/stories/{epic}/{story}.md`
 - `.wize/solutioning/architecture.md`
+- `.wize/implementation/tea/risk-profile.md`
+- Overlay test playbooks if active:
+  - `web-overlay/playbooks/playwright-vitest.md`
+  - `app-overlay/playbooks/detox-maestro.md`
 
 ## Output
+
 - `.wize/implementation/tea/{epic}/{story}/design.md`
 
-## YAML frontmatter
+## Steps
+
+### 1. Read the story; map every AC
+
+For each AC, write **one assertion-shape sentence**: *"There will be a {kind} test that does {what} and expects {observable}."*
+
+### 2. Pick the test split
+
+Defaults (from `playwright-vitest.md` / `detox-maestro.md`):
+- **Low-risk story:** 70% unit / 20% integration / 10% E2E.
+- **Risk-profile flagged story (R-1..R-3):** add 1–2 dedicated E2E + integration for the risk area.
+- **UI-only story:** 60% unit / 30% component (Testing Library) / 10% E2E.
+- **Server-only story:** 80% unit / 20% integration; no E2E unless an upstream consumer story bundles it.
+
+### 3. Declare fixtures + mocks
+
+- Fixtures: known users, known DB rows, known files.
+- Mocks: external services at the network boundary (MSW). Don't mock the unit under test.
+
+### 4. Environment
+
+- Where it runs (local sim, headless emulator, real device farm).
+- Network conditions (offline / 3G slow / lossy WiFi).
+- OS / browser matrix (from `device-matrix.md` or playwright projects).
+
+### 5. Edge cases (cheap; pay back × 10)
+
+List 3–7 edge cases the ACs don't name but the user might hit:
+- Empty / max-length inputs.
+- IME / paste / autofill.
+- Offline mid-action.
+- Concurrent users on the same resource.
+- Time-zone / DST.
+- Localized number/currency.
+
+Each gets a test of its own (usually unit).
+
+### 6. Hand off
+
+Mark `status: ready-for-dev` in the design.md frontmatter. Shuri reads before starting.
+
+## YAML frontmatter (canonical)
+
 ```yaml
 ---
 gate: design
-story_id: …
-ac_ids: [AC-1, AC-2, …]
+story_id: E01-S03
+ac_ids: [AC-02-1, AC-02-2]
+status: PASS
+created_at: 2026-06-11T12:00:00Z
 test_split:
-  unit: count + brief description
-  integration: count + brief description
-  e2e: count + brief description
-fixtures: [...]
-mocks: [...]
-environment: dev|staging|isolated
+  unit: { count: 4, description: "validation, server-action contract, error mapper, mailer payload" }
+  integration: { count: 1, description: "server action calls mailer with right args, against MSW" }
+  e2e: { count: 1, description: "happy path; Playwright @chromium @ios" }
+fixtures:
+  - "new-admin user"
+  - "empty team"
+mocks:
+  - "Resend via MSW"
+  - "Auth session via fixture cookie"
+environment: "local + Playwright project chromium + ios"
+risk_links: [R-1]
+edges:
+  - "invalid email rules: blank, missing @, weird IME chars"
+  - "duplicate teammate email"
+  - "offline at submit time"
 ---
 ```
 
-## Body
-Plain-English rationale + edge-case list.
+## Body of `design.md`
+
+```markdown
+## Per-AC assertion shapes
+
+- **AC-02-1**: Vitest unit on `validateInviteEmail()` → returns `{ ok: true }` for `name+tag@example.com`. Vitest integration on `inviteTeammate()` server action → asserts `mailer.send` called once with `{ to: 'name@example.com', template: 'team-invite' }`. Playwright E2E → clicks "Send invite", asserts `[data-testid="invite-sent-banner"]` appears within 1s.
+
+- **AC-02-2**: Vitest unit on `validateInviteEmail()` → returns `{ ok: false, code: 'invalid_format', field: 'email' }` for empty/no-@. Component test (Testing Library) on `<InviteForm>` → asserts the input's `aria-describedby` error region announces "Enter a valid email."
+
+## Edge cases (additional tests)
+
+- E1: Empty email — `validateInviteEmail('')` → `invalid_format`.
+- E2: 254-char local part — boundary check; expect graceful clipping.
+- E3: Same email submitted twice — second call hits `inviteTeammate()`, asserts second insert is a no-op (idempotency key based on `(team_id, email)`).
+- E4: Offline at submit — Playwright `context.setOffline(true)` after click; banner shows "We'll retry when you're back online."
+
+## Run plan
+- On every PR: full unit + integration; E2E `@smoke` tag only (≤ 30s).
+- Nightly: full E2E suite + Lighthouse baseline.
+```
+
+## Anti-patterns Hawkeye rejects
+
+- **`design.md` written after dev started.** Then the story slipped through; flag.
+- **One test per AC, no edges.** Edges are where users live.
+- **Mocking the unit under test.** You'd be testing the mock.
+- **E2E that test the happy path only.** Cover failure too.
+- **Selectors by visible text in a multilingual app.** Use `data-testid` or `role` with locale-aware patterns.
+
+## Hand-off
+
+> Test design for E01-S03 at `.wize/implementation/tea/E01-S03/design.md`. 4 unit, 1 integration, 1 E2E, plus 4 edges. Shuri can start; I'll check `tea-trace.md` against this when the PR opens.

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

@@ -4,48 +4,138 @@ name: TEA Gate Decision
 gate: gate
 owner: wize-agent-test-architect   # Hawkeye
 when: story-final
-status: stub
+status: ready
 ---
 
 # TEA — Gate Decision
 
-**Goal.** Final per-story gate. PASS / CONCERNS / FAIL / WAIVED with documented rationale.
+**Goal.** Final per-story decision. **PASS / CONCERNS / FAIL / WAIVED** with documented rationale, score, and policy mode. This is the line: a story doesn't advance past it without a recorded gate.
+
+Hawkeye drives. The four inputs (`design`, `trace`, `review`, plus `nfr` at epic boundary) feed in. Policy is read from `.wize/config/tea.toml`.
 
 ## Inputs
-- `design.md`, `trace.md`, `review.md` for the story
-- `nfr/{epic}.md` if applicable
-- Story file
+
+- `.wize/implementation/tea/{epic}/{story}/design.md`
+- `.wize/implementation/tea/{epic}/{story}/trace.md`
+- `.wize/implementation/tea/{epic}/{story}/review.md`
+- `.wize/implementation/tea/nfr/{epic}.md` (when the story is the last of its epic)
+- `.wize/config/tea.toml`
 
 ## Output
+
 - `.wize/implementation/tea/{epic}/{story}/gate.md`
 
+## Decision rules
+
+| Inputs | Recommendation |
+|---|---|
+| All ACs `met`, no findings | **PASS** |
+| All ACs `met`, only low/medium non-blocking findings | **PASS** with notes (or **CONCERNS** depending on count) |
+| Any AC `partial` | **CONCERNS** |
+| Any AC `not-met` | **FAIL** |
+| NFR `FAIL` on the epic (last story) | **FAIL** |
+| `tea-review` flagged `knowledge_axes_touched` ≠ `knowledge_axes_updated` (any axis touched without update) | **CONCERNS** (advisory mode) / **FAIL** (enforcing mode) — adds finding `KN-NN` |
+| Failing AC OR non-neg NFR with documented business rationale + senior signoff | **WAIVED** |
+
+Score (0–100): heuristic. `100 - (10 × high) - (5 × medium) - (2 × low)`. Floor 0.
+
+## Policy
+
+`.wize/config/tea.toml` sets `policy = "advisory"` (default) or `"enforcing"`.
+
+- **Advisory:** `FAIL` is a visible warning in PR; merge isn't auto-blocked. The team decides.
+- **Enforcing:** `FAIL` blocks merge via CI status check (`tea-gate`). PASS / CONCERNS allowed through.
+
+## Steps
+
+### 1. Read the three inputs
+
+If trace shows `partial`, you know the recommendation. If review recommends FAIL, you've got your decision. The gate doc just records it.
+
+### 2. Compute score
+
+Don't game it. The score communicates magnitude to humans skimming a backlog.
+
+### 3. Write the doc
+
+Frontmatter is the structured truth. The body is the narrative for humans.
+
+### 4. Notify
+
+Update the PR description with the gate verdict + link to the doc. Maria Hill watches the gate status in `sprint-status.md`.
+
 ## YAML frontmatter (canonical)
+
 ```yaml
 ---
 gate: gate
-story_id: …
-status: PASS | CONCERNS | FAIL | WAIVED
-score: 0-100
-policy: advisory | enforcing
+story_id: E01-S03
+status: PASS
+score: 95
+policy: advisory
 inputs:
-  - design.md: …
-  - trace.md: …
-  - review.md: …
-  - nfr/{epic}.md: …
+  design: ".wize/implementation/tea/E01-S03/design.md"
+  trace:  ".wize/implementation/tea/E01-S03/trace.md"
+  review: ".wize/implementation/tea/E01-S03/review.md"
+  nfr:    null   # not the last story of E01
 findings:
-  - id: G-1
-    severity: low | medium | high
-    summary: …
-    recommendation: …
-waived_by: null | "wizer"
-waived_reason: null | "…"
-created_at: ISO-8601
+  - id: REV-01
+    severity: low
+    summary: "Empty-state copy slightly differs from Mantis' spec."
+    recommendation: "Update `<EmptyTeamPanel>` heading in a follow-up."
+  - id: KN-01
+    severity: medium
+    summary: "Story added a new component (`<InviteForm>`) but architecture-snapshot.md was not updated."
+    recommendation: "Add 2 lines to `.wize/knowledge/document-project/architecture-snapshot.md` under a dated bullet referencing the new component + its public testid contract."
+    owner: shuri
+    blocking: false   # advisory mode; would be true under enforcing
+waived_by: null
+waived_reason: null
+created_at: 2026-06-11T20:30:00Z
 ---
 ```
 
-## Body
-Narrative explanation; structured data is the YAML.
+## Body of `gate.md`
 
-## Policy
-- **advisory** (default): FAIL is a warning. Merge proceeds.
-- **enforcing**: FAIL blocks merge via CI. Configured in `.wize/config/tea.toml`.
+```markdown
+## Verdict
+**PASS** (score 95)
+
+## Why
+- All ACs met with observed evidence.
+- Trace clean; coverage 100% on ACs, partial on edges (E3, E4) — tracked for follow-up.
+- Review found one low-severity copy finding (REV-01).
+- Story is not the last in epic 01; NFR gate runs separately at epic boundary.
+
+## Notes for follow-up
+- Open a tiny story (or include in next sprint planning) to fix REV-01 and close edges E3, E4.
+
+## Trail
+- design.md → 4/1/1 split (unit/integration/e2e) + 4 edges declared.
+- trace.md → all ACs `covered`; E3 `partial`, E4 `missing` (follow-up).
+- review.md → ACs `met`, scope mostly disciplined, copy nit.
+- nfr.md → N/A (mid-epic).
+```
+
+## When to WAIVE
+
+Rare. Examples:
+- A failing E2E that depends on a flaky external sandbox; the production code is unaffected; sign-off by Tony + Hill.
+- A non-negotiable temporarily slipped because of an external integration blocker; we ship with mitigation in place; sign-off by Fury.
+
+A WAIVE always lists:
+- Who waived (`waived_by`).
+- Why (`waived_reason`).
+- The compensating control (a follow-up story, an SLA monitor, a feature flag).
+
+## Anti-patterns Hawkeye rejects
+
+- **Gating without `review.md`.** No review → no gate.
+- **PASS with a `not-met` AC.** Auto-fail.
+- **WAIVED with no `waived_by` field.** Reject.
+- **Scoring jiggered to clear a threshold.** Trust trumps point-scoring; if the count says 70, don't write 91.
+- **Enforcing mode gates without CI check wiring.** Ghost gate; remove or wire it.
+
+## Hand-off
+
+> Gate for E01-S03: **PASS** (score 95). One low-severity finding logged for follow-up. Maria Hill, sprint-status updated; Shuri, ready to start the next story.