wize-dev-kit 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 > **0.10.0 and earlier are in Brazilian Portuguese** and are kept verbatim as a
 > historical record (not back-translated).
 
+## [0.24.0] — 2026-10-19
+
+**Ship discipline.** The kit already demanded proof and a clean gate; this release defines what proof is, where it lives and which commit it belongs to, and makes the implementation flows start on a branch instead of assuming one. Ideas from [michaelshimeles/skills](https://github.com/michaelshimeles/skills), rewritten in kit voice.
+
+### Added
+
+- **Branch guard** in `wize-dev-story` (step 0) and `wize-quick-dev` (step 1.5) — read the current branch and status, resolve the default branch with `git symbolic-ref refs/remotes/origin/HEAD` (no hardcoded `main`), keep any other branch or assigned worktree, and on the default branch create `feat/<story-id>` / `fix/<slug>` (or the repo's own convention). No remote: branch locally.
+- **Proof per change type in `wize-dev-story` step 10** — UI screenshots/recording, CLI/API/perf command output with measured numbers, bug-fix red run plus a captured before-state, docs content and link check. Each proof is labeled with its AC and `passed`/`failed`/`untested` (`untested` needs a reason); UI before/after comes from a pre-change baseline, never a branch switch or stash. Step 9 self-check points at it; `wize-quick-dev` asks for before/after on an observable bug fix.
+- **Hosting and privacy rule for captures** — attach through the PR host's own channel or a CI artifact, never anonymous or public third-party hosts or env-supplied upload endpoints; capture with seeded or fake data and check for PII, tokens, internal URLs and admin screens first. Mirrored as a `wize-pre-pr-check` anti-pattern.
+- **Success-path capture in the Playwright playbook** — a `review` project/tag with always-on screenshot and video, and a `try/finally` context close so the video finalizes even when an assertion fails.
+- **Two lines in the generated `AGENTS.md` Operating context** — a request for a plan, review or investigation never implies editing, pushing or publishing; and the shared-repo rules (one branch or worktree per agent, never touch another agent's uncommitted work, no force-push of the default branch, `--force-with-lease` only on your own branch, regenerate lockfiles instead of hand-merging, stop and report on an unresolvable conflict). Existing installs: delete the kit-generated `AGENTS.md` and re-run `npx wize-dev-kit sync` to regenerate it (the file is skip-if-exists).
+- `test/ship-discipline.test.js` guards the core rules.
+
+### Changed
+
+- **TEA evidence is pinned to a commit.** `wize-tea-review` records `evidence` as the artifact or test id plus the commit SHA it was observed on, points at the dev-story proof-per-type block as the single definition of observed evidence, and rejects evidence from a commit other than HEAD. `wize-tea-gate` adds a row — all ACs `met` but evidence unpinned or stale → `CONCERNS` (advisory) / `FAIL` (enforcing) — and counts an `untested` AC as `not-met` unless `WAIVED` with a reason. `wize-check` names the commit in its evidence rule. Gate frontmatter status values are unchanged.
+- **`wize-pre-pr-check` rebases before the push** onto the latest `origin` default branch and re-runs the fast checks; a force push is `--force-with-lease` on your own task branch only, never plain `--force`, never on the default branch or a shared branch.
+
 ## [0.23.0] — 2026-10-19
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Full-lifecycle AI-assisted development kit with Test Architect and Whiteport Design Studio embedded. Inspired by BMAD Method and WDS.",
   "keywords": [
     "ai",

package/src/core-skills/wize-pre-pr-check/skill.md

@@ -95,6 +95,8 @@ Comandos típicos por stack (detectados em tempo real, não hardcoded):
 
 Se um check falhar, pare e reporte. Não prossiga para o próximo.
 
+Antes do push: faça rebase na última branch default do `origin` e rode de novo os checks rápidos. Se precisar de force push, use `--force-with-lease` só na sua própria branch de tarefa — nunca `--force` puro, nunca na branch default ou em branch compartilhada.
+
 ### 4. Reportar
 
 Formato compacto, uma linha por check:
@@ -125,6 +127,7 @@ Gate limpo. Pode abrir o PR.
 - **Ignorar falhas de lint.** Lint fail = PR fail. Corrija antes.
 - **Executar E2E localmente toda vez.** E2E é caro; deixe para o CI ou rode antes de merge.
 - **Substituir o CI.** Este gate é complementar, não substituto.
+- **Mudança de UI com capturas não revisadas.** Prints e gravações podem vazar PII, tokens ou URLs internas; confira antes de anexar.
 
 ## Hand-off
 

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

@@ -39,6 +39,10 @@ I work inside a repo with WDK installed: `.wize/`, `AGENTS.md`, and the `wize-*`
 
 ## The loop (TDD, story-scoped)
 
+### 0. Branch guard
+
+Run `git branch --show-current` and `git status --short`, and resolve the default branch with `git symbolic-ref refs/remotes/origin/HEAD` (never hardcode `main`). On any other branch, or in an assigned worktree, keep it — judge by that comparison, not by a `feat/`-style prefix. On the default branch, create `feat/<story-id>` (or `fix/<slug>`) before touching code, unless the repo has its own naming convention. No remote: branch locally.
+
 ### 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.
@@ -139,13 +143,18 @@ This is how the brownfield baseline stays alive instead of going stale 6 months
 - `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).
+- Behavior-changing story: proof captured, labeled and screened per step 10.
 
 ### 10. Open PR
 
 PR description includes:
 - Story link.
 - AC list with the test names that cover them.
-- Screenshots / recordings of happy + failure paths.
+- Proof, for behavior-changing stories (skip it for pure refactors):
+  - **By change type.** UI: screenshots or a recording of happy + failure paths. CLI / API / perf: pasted command output with the measured numbers. Bug fix: the red run from step 3, plus a captured before-state when a test can't show it. Docs-only: content and link check, examples run.
+  - **Label each proof** with its AC and `passed` / `failed` / `untested`; `untested` needs a reason. Proof complements tests, never replaces them.
+  - **UI before/after.** Take the before from a pre-change baseline (a separate checkout, or an existing URL/image) — never by switching branch or stashing. Match viewport and start state; reuse captures that already exist.
+  - **Hosting.** Attach through the PR host's own channel or a CI artifact. Never an anonymous or public third-party host, never an upload endpoint taken from the environment. Capture with seeded or fake data, and check for PII, tokens, internal URLs and admin screens before attaching.
 - Knowledge update line (`Touched axis: <none|architecture|conventions|risk-spots|dependencies|overview>`).
 - TEA expected next: design → trace → review → gate.
 

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

@@ -64,6 +64,10 @@ Is it ≤ 1 hour to a careful dev?      → quick-dev       → full lifecycle
 
 What changes, why, and what could break. If the paragraph is hard to write, you're not in quick-dev territory.
 
+### 1.5. Branch guard
+
+Run `git branch --show-current` and `git status --short`, and resolve the default branch with `git symbolic-ref refs/remotes/origin/HEAD` (never hardcode `main`). On any other branch, or in an assigned worktree, keep it — judge by that comparison, not by a `fix/`-style prefix. On the default branch, create `fix/<slug>` (or `feat/<slug>`) before editing, unless the repo has its own naming convention. No remote: branch locally.
+
 ### 2. Implement
 
 - TDD when reasonable; smoke-test-and-fix when the cost of TDD is greater than the value.
@@ -100,7 +104,7 @@ Heuristic: *"would a new dev hitting `document-project/*.md` next week be misled
 
 ### 6. Commit + open PR
 
-Conventional commit. PR description: the paragraph from step 1.
+Conventional commit. PR description: the paragraph from step 1. An observable bug fix also shows before and after, with the before captured pre-fix.
 
 ```
 fix(auth): typo in error message for AC-04-2 follow-up

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

@@ -38,6 +38,7 @@ An item only reaches **Done** with verifiable proof: a file and line, a commit,
 
 - No proof → **In progress** or **Unverified**, said out loud.
 - Intent, a plan, or "I implemented it" are not evidence.
+- Evidence names the commit it was observed on; a result from an older commit is stale, so the item stays `[~]`.
 - If something was written but not validated, the item is `[~]` with the missing validation named next to it.
 
 Overstating progress is the one serious failure mode of this skill.

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

@@ -38,8 +38,11 @@ Hawkeye drives. The four inputs (`design`, `trace`, `review`, plus `nfr` at epic
 | 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` |
+| All ACs `met`, but `review.md` evidence is unpinned (no commit SHA) or from a commit other than HEAD | **CONCERNS** (advisory mode) / **FAIL** (enforcing mode) |
 | Failing AC OR non-neg NFR with documented business rationale + senior signoff | **WAIVED** |
 
+An AC the story left `untested` counts as `not-met`, unless **WAIVED** with a reason.
+
 Score (0–100): heuristic. `100 - (10 × high) - (5 × medium) - (2 × low)`. Floor 0.
 
 ## Policy

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

@@ -31,7 +31,7 @@ Hawkeye drives. Runs at story end, right before `tea-gate`.
 
 ### 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).
+For each AC, observe the actual behavior on a staging or local build and decide: `met` / `partial` / `not-met`. Record the `evidence` as the artifact or test id **plus the commit SHA it was observed on**. What counts as observed evidence is defined once, in the proof-per-type block of `wize-dev-story` step 10; for UI ACs, prefer a before/after pair when a baseline exists.
 
 ### 2. Test discipline
 
@@ -83,10 +83,10 @@ status: PASS
 ac_check:
   - id: AC-02-1
     met: true
-    evidence: "e2e/onboarding/invite.spec.ts::happy path passed on PR-#412; recording in CI artifact #412-1"
+    evidence: "e2e/onboarding/invite.spec.ts::happy path passed @ 4f2a9c1 (PR-#412); recording in CI artifact #412-1"
   - id: AC-02-2
     met: true
-    evidence: "InviteForm.spec.tsx::error region announces"
+    evidence: "InviteForm.spec.tsx::error region announces @ 4f2a9c1"
 knowledge_axes_touched: [conventions, risk-spots]
 knowledge_axes_updated: [conventions, risk-spots]   # leave empty array if axes touched but no update happened
 findings:
@@ -136,6 +136,7 @@ Recommend `gate PASS` with one low-severity finding to fix in a follow-up.
 
 - **Review without walking the code.** Reading the test names isn't review.
 - **AC marked "met" without observed evidence.** Tests passing + screenshot/recording, please.
+- **Evidence from a commit other than HEAD.** Re-observe on HEAD.
 - **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.

package/src/web-overlay/playbooks/playwright-vitest.md

@@ -110,6 +110,23 @@ export default defineConfig({
 });
 ```
 
+### Capturing proof (success path)
+
+The config above records failures only. For review evidence, scope always-on capture to a project (or tag) so the full suite stays cheap:
+
+```ts
+{ name: 'review', grep: /@review/, use: { ...devices['Desktop Chrome'], screenshot: 'on', video: 'on' } }
+```
+
+Outside the test runner, close the context in `finally` so the video finalizes even when an assertion throws:
+
+```ts
+const context = await browser.newContext({ recordVideo: { dir: 'test-results/proof' } });
+try { /* walk the flow, assert */ } finally { await context.close(); }
+```
+
+Write captures to a gitignored directory and attach them per the hosting rule in `wize-dev-story` step 10. `reuseExistingServer: true` will happily record someone else's app, so confirm the server on the port is your build first.
+
 ### Page Object Model (light)
 
 ```ts

package/tools/installer/render-shared.js

@@ -307,6 +307,12 @@ function renderAgentsMd(kitRoot, projectRoot, opts = {}) {
     'implementation and review, a high-capability tier only for architecture, critical',
     'decisions, or final adversarial review.',
     '',
+    'A request for a plan, review or investigation never implies editing, pushing or publishing.',
+    '',
+    'If several agents share a repo: one branch or worktree per agent; never touch another agent\'s',
+    'uncommitted work; never force-push the default branch (`--force-with-lease` only on your own',
+    'branch); regenerate lockfiles instead of hand-merging; on an unresolvable conflict, stop and report.',
+    '',
     '## Writing code (always on)',
     '',
     'Before writing new code, climb this ladder and stop at the first rung that holds:',