wize-dev-kit 0.2.0 → 0.2.5

package/CHANGELOG.md

@@ -5,6 +5,91 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.5] — 2026-06-12
+
+Fixes a real install-time bug that bit non-TTY users (CI smoke + anyone piping input into `wize-dev-kit install`).
+
+### Fixed
+
+- **Non-TTY prompt stall.** The CLI's `prompt()` helper created a new `readline.createInterface` per call and used `rl.question()`. Both choices misbehave in pipe mode: per-call interfaces close stdin on the first `rl.close()`, and even with a shared interface `readline.question` stalls when it has to read an empty line in non-TTY mode (Node 24 behavior). After step 1 of `install` (project name), every subsequent prompt would hang silently. Replaced with an event-based line reader: subscribe once to `line`, push waiters in order, propagate empty lines as `""`, treat EOF as "remaining waiters resolve empty". `printf '...\n\n\n\n\nName\n\n' | wize-dev-kit install` now runs cleanly to completion.
+
+### Notes
+
+This was the actual cause behind the CI smoke E2E loop. The 0.2.4 fix to the smoke script (using `npm install <tarball>` instead of `npx <tarball>`) was correct, but the underlying CLI couldn't accept piped input either, so the smoke kept failing at the second prompt. With both fixed, the smoke runs end-to-end.
+
+## [0.2.4] — 2026-06-12
+
+CI-only hotfix to actually unblock the publish pipeline. Surface area of wize-dev-kit unchanged.
+
+### Fixed
+
+- Smoke E2E step used `npx --yes "$tarball" install`. On the GitHub Actions runner that path is interpreted as a shell command, which tries to **execute the tarball directly** before npx ever extracts it — exit code 126, `Permission denied`. Rewrote the step to: install the tarball into a throwaway project via `npm install <tarball>`, then invoke `$NODE_MODULES/.bin/wize-dev-kit` directly. `npm install` extracts the archive properly and sets the bin executable bit, so the rest of the smoke (`install` → assertions → `update` → `agent list`) runs cleanly. Same coverage, named-per-check error messages, and now also sets `WIZE_DISABLE_UPDATE_CHECK=1` so the registry isn't probed mid-smoke.
+
+## [0.2.3] — 2026-06-11
+
+Hotfix: 0.2.1 and 0.2.2 publish workflows hung because `test/version-check.test.js` had a sync/async bug in its test scaffolding. CI's smoke E2E never started for those releases. This release fixes the test and re-runs the same smoke for 0.2.2 + 0.2.3.
+
+### Fixed
+
+- `withTempCacheHome` helper in `test/version-check.test.js` was synchronous (`return fn(dir)`), so its `finally` block restored the env var before the async callback's `writeCache` resolved. The cache lookup inside the callback then landed in the real `~/.cache/wize-dev-kit/`, contaminating subsequent test runs and intermittently failing the `getLatestVersion returns the cached value when fresh` assertion. Fix: make the helper `async` and `return await fn(dir)`. Confirmed locally + ensures CI doesn't get a stuck cache file across tags.
+
+### Notes
+
+No surface area changed; behavior of `wize-dev-kit` itself is identical to 0.2.2. The bump exists only so the publish workflow re-runs cleanly.
+
+## [0.2.2] — 2026-06-11
+
+Closes the "documentation always stale" gap: inline knowledge captures per story, Hawkeye enforces, sprint-end refresh consolidates. Plus auto-update nudges on the CLI and Wizer.
+
+### Added — knowledge stays current
+
+- **`wize-dev-story` step 8 — Knowledge update (inline).** After commits and before pre-PR check, Shuri checks whether the story touched any of the 5 baseline axes (architecture / conventions / risk-spots / dependencies / overview) and, if yes, adds 1–3 dated bullets to the matching `.wize/knowledge/document-project/*.md` file — same PR. ~60 seconds when applicable; skipped otherwise.
+- **`wize-quick-dev` step 5 — Knowledge update (only if applicable).** Quick-dev rarely touches axes; when it does (dep bump that shifts API, rename that breaks a contract), one line lands in the relevant doc.
+- **`wize-tea-review` step 5 — Knowledge update check.** Hawkeye walks the diff. Touched-but-not-updated stories get a `KN-NN` finding. `tea-review` frontmatter now carries `knowledge_axes_touched` + `knowledge_axes_updated`.
+- **`wize-tea-gate` decision rule extended.** When `knowledge_axes_touched ≠ knowledge_axes_updated`, recommendation flips to `CONCERNS` (advisory) or `FAIL` (enforcing). Example `KN-NN` finding shape documented in the canonical YAML.
+- **`wize-refresh-knowledge` (new workflow).** Sprint-end consolidation: Pepper + Peggy roll the dated bullets accumulated through the sprint into the narrative prose of each axis file, demote stale claims to a `Deprecated` section, freeze a snapshot at `.wize/knowledge/document-project/_history/{YYYY-Qn}/sprint-{N}.md`, and stamp `last_refreshed` in each file. Triggered when `wize-help next` detects the sprint emptied.
+- **`wize-document-project` — Update mode section.** Documents the two-cadence loop (inline-per-story + sprint-refresh) and the file frontmatter convention (`last_refreshed`).
+
+### Added — proactive nudges
+
+- **`wize-help` skill — version-skew detection.** Wizer now reads `kit_version` from `.wize/config/project.toml`, compares with the installed package version and (via Bash tool when available) the registry, and proactively suggests `npx wize-dev-kit@latest update` when behind. Worded as a single short line, never as a banner.
+- **`wize-help` skill — sprint-end detection.** Heuristic refined: when sprint-status shows all stories gated and no `ready-for-dev` left, the next-step recommendation is `wize-retrospective` + `wize-refresh-knowledge`, not just retro.
+- **CLI version check (camera 1).** `wize-dev-kit list / sync / agent / workflow / help` now print a one-line `↑ Update available: X → Y` at the top when a newer version sits in the npm registry. Cached for 1 hour, 1.5s network timeout, silent on offline / non-TTY / `WIZE_DISABLE_UPDATE_CHECK=1`. Never blocks. New module `tools/installer/version-check.js`.
+
+### Tests
+
+- Total: **104 passing** (was 94 in 0.2.1).
+- 10 new tests in `test/version-check.test.js` covering semver compare, cache freshness, fetch fallback (offline + non-2xx), TTY guard, env disable.
+
+### Files
+
+- `src/method-skills/1-analysis/wize-refresh-knowledge/workflow.md` (new).
+- `tools/installer/version-check.js` (new).
+- Edits to `wize-dev-story`, `wize-quick-dev`, `wize-tea-review`, `wize-tea-gate`, `wize-help` skill, `wize-document-project`, `tools/installer/wize-cli.js`.
+
+## [0.2.1] — 2026-06-11
+
+Focused polish: brownfield baseline finally runs end-to-end through a detected harness CLI, CI publishes without the deprecated-config warning, and every release is now smoke-tested before going up.
+
+### Added
+
+- **Brownfield baseline runs real now.** When the installer detects existing code and you accept the `Run wize-document-project?` prompt, it now scans your PATH for an AI harness CLI (Claude Code, then Codex, then OpenCode), prioritizes whichever you selected as an IDE target, asks you to confirm the headless invocation, and spawns it with the right flags (`claude -p`, `codex exec`, `opencode run`). If no harness CLI is on PATH, the installer prints the exact command you can run later in your IDE. Set `WIZE_SKIP_BASELINE=1` to disable the headless run entirely (used by CI and unattended setups).
+- `tools/installer/baseline.js` — exports `detectHarnessCli`, `runHeadlessBaseline`, `manualInstructions`, `defaultPrompt`. Self-contained, no extra deps; uses a manual PATH walk for hermetic, cross-platform detection.
+- 7 new unit tests covering detection priority, PATH isolation, the skip-baseline env, and instruction strings.
+
+### Fixed
+
+- CI publish workflow now strips the deprecated `always-auth=false` line from the runner's `.npmrc` before installing. Removes the `npm warn Unknown user config "always-auth"` noise that appeared in every 0.2.0 publish log. See actions/setup-node#1129.
+
+### Added — CI
+
+- **Smoke E2E before publish.** The workflow now packs the tarball, installs it in a temp git repo via `npx`, and asserts that `.wize/`, the Claude adapter SKILL.md, generic AGENTS-equivalent, `kit_version` in `project.toml`, `update`, and `agent list` all work — exactly like a user would experience. Fails the release if anything is off, so we never publish a broken tarball again.
+- Sets `WIZE_SKIP_BASELINE=1` in the smoke step so the harness-run prompt doesn't try to spawn `claude` inside GitHub's runner.
+
+### Tests
+
+- Total now **94 passing** (was 87 in 0.2.0).
+
 ## [0.2.0] — 2026-06-11
 
 First release that delivers the lifecycle end-to-end. Workflows have real bodies; CLI commands work for real; the team has a Walkthrough to follow.
@@ -177,7 +262,12 @@ Ignore (handled by the suggested block): `.wize/config/user.toml`, `.wize/scratc
 - Inspired by [BMAD Method v6.8.0](https://github.com/bmad-code-org/BMAD-METHOD).
 - WDS module inspired by [bmad-method-wds-expansion](https://github.com/bmad-code-org/bmad-method-wds-expansion).
 
-[Unreleased]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.5...HEAD
+[0.2.5]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.5...v0.2.0
 [0.1.5]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.3...v0.1.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.2.0",
+  "version": "0.2.5",
   "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/method-skills/1-analysis/wize-document-project/workflow.md

@@ -150,6 +150,46 @@ Co-located with the file under test. `.spec.ts` for unit; `.e2e.ts` for end-to-e
 - Some files use `_test.ts` suffix instead of `.spec.ts` — older code.
 ```
 
+## Update mode (how the baseline stays alive)
+
+The first run of this workflow produces the **baseline**. Two complementary mechanisms keep it current after:
+
+### 1. Inline updates per story (the daily cadence)
+
+Every `wize-dev-story` ends with a Knowledge Update step (step 8). If the story touched any of the 5 axes (architecture, conventions, risk-spots, dependencies, overview), Shuri appends 1–3 dated bullets to the matching `document-project/*.md` file **in the same PR**. Hawkeye verifies in `tea-review`; a touched-but-not-updated story gets a `KN-NN` finding at gate.
+
+`wize-quick-dev` has a lighter version: only when a dep bump or a public rename actually shifts the baseline.
+
+This produces dated bullets like:
+
+```markdown
+## 2026-06-12 — E01-S03
+- Conventions: `data-testid="invite-*"` published as public contract.
+- Risk: R-1 (mailer) mitigation confirmed.
+```
+
+### 2. Sprint-end refresh (the narrative cadence)
+
+`wize-refresh-knowledge` runs at sprint end (triggered by `wize-help next` when it detects the sprint emptied). Pepper + Peggy consolidate the inline bullets into the narrative prose of each axis file, demote stale claims to a "Deprecated" section, freeze a sprint snapshot in `_history/{YYYY-Qn}/sprint-{N}.md`, and stamp `last_refreshed` in each file.
+
+Result: the baseline reads like a single coherent document, not a chronological log. New devs can read it linearly and form a mental model. Forensics readers (six months later, asking "when did X change?") consult `_history/`.
+
+### File frontmatter convention
+
+Each `document-project/*.md` file ships with:
+
+```yaml
+---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: 2026-04-02
+last_refreshed: 2026-06-25
+sampled: "wkly + sprint refresh"
+---
+```
+
+`last_refreshed` tells the reader how much to trust the file vs the inline bullets accumulating since.
+
 ## Anti-patterns Pepper rejects
 
 - "TODO: document later." The baseline IS the documentation pass; later doesn't come.
@@ -157,6 +197,7 @@ Co-located with the file under test. `.spec.ts` for unit; `.e2e.ts` for end-to-e
 - Architecture diagrams that show what the team *wishes* exists. Diagram the real state.
 - Risk-spot table with no confidence label. Without confidence, readers can't act.
 - Open questions with no owner. They never get answered.
+- Treating the baseline as one-shot. The mode + refresh exist precisely because point-in-time docs lie within weeks.
 
 ## Hand-off
 

package/src/method-skills/1-analysis/wize-refresh-knowledge/workflow.md

@@ -0,0 +1,127 @@
+---
+code: wize-refresh-knowledge
+name: Refresh Project Knowledge
+phase: 1-analysis
+owner: wize-agent-analyst    # Pepper (drives), with Peggy on prose
+status: ready
+---
+
+# Refresh Project Knowledge
+
+**Goal.** Consolidate the dated bullets added to `document-project/*.md` over the sprint (via `wize-dev-story` step 8 and `wize-quick-dev` step 5) into a coherent, narrated, current-state baseline. Keep what's still true; demote what's outdated; archive what's no longer relevant.
+
+This is the workflow that **keeps `document-project` honest over months**, instead of letting it stale within a sprint.
+
+Pepper drives the consolidation. Peggy edits prose. Tony reviews architecture-snapshot changes. Hawkeye reviews risk-spots changes.
+
+## When to run
+
+- **End of sprint** (default cadence). `wize-help next` suggests it when it detects the sprint ended.
+- **After a major epic ships.** Architecture often shifts visibly; this is the moment to consolidate.
+- **Before onboarding a new engineer.** The baseline is the first thing they read; keep it fresh.
+- **Before an audit / external review.** Same.
+
+Don't run after every story — that's why each story already does its own inline update. This is the *periodic narration pass*.
+
+## Inputs
+
+- `.wize/knowledge/document-project/{overview,architecture-snapshot,conventions,dependencies,risk-spots,open-questions}.md`
+- `.wize/implementation/tea/**/gate.md` from this sprint (look for `KN-NN` findings — they flag where the baseline got out of sync).
+- Git log of the sprint window (`git log --since="<sprint-start>" --until="<sprint-end>"`).
+- `.wize/implementation/sprint-status.md` (latest sprint block).
+
+## Outputs
+
+- Updated `.wize/knowledge/document-project/*.md` (in place).
+- `.wize/knowledge/document-project/_history/{YYYY-Qn}/{sprint-N}.md` — sprint-scoped snapshot (frozen).
+- Optional new entries appended to `open-questions.md`.
+
+## Steps
+
+### 1. Collect the inline notes
+
+For each of the 5 axes, list every dated bullet added since the previous refresh (or since the baseline was created). They look like:
+
+```
+## 2026-06-12 — E01-S03
+- Conventions: `data-testid="invite-*"` published as public contract.
+- Risk: R-1 (mailer) mitigation confirmed.
+```
+
+Pepper extracts them by axis.
+
+### 2. Narrate, don't list
+
+For each axis, write a short paragraph that **integrates** the new bullets into the surrounding context. The bullets disappear; the prose grows. Each axis remains a single coherent file — not a chronological log.
+
+Example for `conventions.md` before refresh:
+
+```markdown
+## Tests
+Co-located with the file under test. `.spec.ts` for unit; `.e2e.ts` for end-to-end.
+```
+
+After refresh integrating an inline note "data-testid='invite-*' is a public contract":
+
+```markdown
+## Tests
+Co-located with the file under test. `.spec.ts` for unit; `.e2e.ts` for end-to-end. Test IDs follow the `data-testid="{feature}-{element}"` convention and are treated as a **public contract** — renaming one is a breaking change for end-to-end tests; ping Hawkeye before changing.
+```
+
+### 3. Demote what's outdated
+
+If a previous claim no longer holds (a service was retired, a convention was replaced), don't delete silently. Move it to a "Deprecated" section at the bottom of the file with the date it was replaced and the new pattern. Future readers need the breadcrumb.
+
+### 4. Archive a sprint snapshot
+
+Freeze the *current* state into `_history/{YYYY-Qn}/sprint-{N}.md`. This file is read-only after creation. Six months from now, when someone asks "when did we change the test-id convention?", the answer is in `_history/`.
+
+### 5. Open questions sweep
+
+Pull any `KN-NN` findings that weren't resolved (the gap was acknowledged but the doc still wasn't updated) and copy them as `open-questions.md` entries with owners.
+
+### 6. Diff narrative
+
+Append a one-paragraph summary to the bottom of each updated file:
+
+```markdown
+## Last refresh: 2026-06-25 (Sprint 7)
+- Architecture: 2 new components documented (`<InviteForm>`, `<TeamList>`); ADR-008 anchored in the auth section.
+- Conventions: test-id public contract documented; eslint plugin added (commit 7a3d2f).
+- Risk-spots: R-1 (mailer) closed; R-7 (rate limiter) added.
+- Dependencies: bumped zod, drizzle, expo (notes in dependencies.md).
+- Overview: unchanged; no new top-level feature in this sprint.
+```
+
+### 7. Hand off
+
+- All updated docs flip frontmatter `last_refreshed: YYYY-MM-DD`.
+- Wizer announces in `sprint-status.md`: *"Knowledge refresh done; baseline current."*
+- Maria Hill carries this into the retrospective: was the refresh smooth, or did the team accumulate too many KN findings?
+
+## Frontmatter convention for `document-project/*.md`
+
+Each baseline file ships with:
+
+```yaml
+---
+status: baseline
+owner: Pepper + Peggy
+created: 2026-04-02
+last_refreshed: 2026-06-25
+sampled: "wkly + sprint refresh"
+---
+```
+
+`last_refreshed` tells the next reader how much to trust the file vs read the more recent inline notes from `_history/`.
+
+## Anti-patterns Pepper rejects
+
+- **Refreshing into a chronological log.** That defeats narration; if a new dev opens `conventions.md` and sees 47 dated bullets, they can't form a mental model. Narrate.
+- **Refresh without reading the gate findings.** `KN-NN` findings are exactly the gaps you should be patching here; ignoring them recreates the original problem.
+- **Refresh every sprint regardless of activity.** If the sprint touched zero axes (rare but possible — a sprint of pure UI polish), say so in the diff narrative and skip the bulk of the work.
+- **Demotion without breadcrumb.** Future readers need the trail.
+
+## Hand-off
+
+> Knowledge refresh for Sprint 7 done. Baseline current; 1 historical snapshot frozen at `_history/2026-Q2/sprint-7.md`. KN-01 closed, KN-03 still open (deferred to S8 — assigned to Aaliyah).

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

@@ -81,7 +81,31 @@ feat(invite): validate email per AC-02-1 / AC-02-2
 
 Until every AC has at least one test + minimum code that makes it pass.
 
-### 8. Pre-PR self-check
+### 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.
 - No `test.skip` / `.only` left.
@@ -91,15 +115,16 @@ Until every AC has at least one test + minimum code that makes it pass.
 - Story file frontmatter → `status: ready-for-review`.
 - Self-walk the screen (web) or smoke a tab on simulator (app).
 
-### 9. Open PR
+### 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.
 
-### 10. Address gate findings
+### 11. Address gate findings
 
 If `tea-review` flags issues, fix them in the same PR or open a follow-up if the story has shipped a separate value-bearing slice.
 

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

@@ -80,7 +80,19 @@ Append one line to `.wize/implementation/quick-dev-log.md`:
 2026-06-11 | shuri | rename UserService → AccountService | smoke PASS | PR #420
 ```
 
-### 5. Commit + open PR
+### 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.
 

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-gate/workflow.md

@@ -34,6 +34,7 @@ Hawkeye drives. The four inputs (`design`, `trace`, `review`, plus `nfr` at epic
 | 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.
@@ -82,6 +83,12 @@ findings:
     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

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

@@ -47,11 +47,22 @@ If the story touches any `R-x` from the risk profile, walk the mitigation contra
 
 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. Findings
+### 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.
 
-### 6. Recommend gate outcome
+### 7. Recommend gate outcome
 
 Review doesn't *make* the gate decision (that's `tea-gate`); it recommends. Possible recommendations:
 - `gate PASS`
@@ -73,6 +84,8 @@ ac_check:
   - 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

package/tools/installer/baseline.js

@@ -0,0 +1,128 @@
+// Brownfield baseline runner — detects AI harness CLIs available on PATH and,
+// when authorized, executes `/wize-document-project` headlessly to populate
+// .wize/knowledge/document-project/. Falls back to printed instructions when
+// no harness is present or the user opts out.
+//
+// Harness priority is:
+//   1. user's selected IDE targets (from .wize/config/project.toml), highest first
+//   2. claude > codex > opencode (universal fallback)
+//
+// Set WIZE_SKIP_BASELINE=1 in the environment to disable any execution (the
+// install still suggests the next step). Useful for CI and unattended setups.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+// Harness registry — for each supported CLI we know:
+//   binary  : the executable name to find on PATH
+//   ideCode : the matching `ide_targets` code in project.toml (so we can prioritize)
+//   buildCmd: returns the spawnSync args (binary + arg list) for a headless run
+const HARNESSES = [
+  {
+    code: 'claude-code',
+    binary: 'claude',
+    buildCmd: (prompt) => ({ cmd: 'claude', args: ['-p', prompt] })
+  },
+  {
+    code: 'codex',
+    binary: 'codex',
+    buildCmd: (prompt) => ({ cmd: 'codex', args: ['exec', '--', prompt] })
+  },
+  {
+    code: 'opencode',
+    binary: 'opencode',
+    buildCmd: (prompt) => ({ cmd: 'opencode', args: ['run', prompt] })
+  }
+];
+
+function whichSync(bin) {
+  // Manual PATH walk — more predictable than shelling out to `which`/`where`,
+  // honors PATH overrides set by callers (and our tests), and stays portable.
+  const PATH = process.env.PATH || '';
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const exts = process.platform === 'win32'
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';')
+    : [''];
+  for (const dir of PATH.split(sep).filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext);
+      try {
+        const st = fs.statSync(candidate);
+        if (st.isFile() && (process.platform === 'win32' || (st.mode & 0o111))) {
+          return candidate;
+        }
+      } catch (_) { /* not here, keep looking */ }
+    }
+  }
+  return null;
+}
+
+// Returns an ordered list of harnesses present on PATH. When `preferIde`
+// includes a harness's `code`, it floats to the top of the result.
+function detectHarnessCli({ preferIde = [] } = {}) {
+  const found = [];
+  for (const h of HARNESSES) {
+    const p = whichSync(h.binary);
+    if (p) found.push({ ...h, path: p });
+  }
+  // Float preferred IDE targets to the top, keep relative order otherwise.
+  return found.sort((a, b) => {
+    const ai = preferIde.indexOf(a.code);
+    const bi = preferIde.indexOf(b.code);
+    if (ai === -1 && bi === -1) return 0;
+    if (ai === -1) return 1;
+    if (bi === -1) return -1;
+    return ai - bi;
+  });
+}
+
+// Run the harness headless with the document-project prompt. Returns
+// { ok: boolean, exitCode, stdout, stderr }.
+function runHeadlessBaseline({ harness, projectRoot, prompt, log = console.log }) {
+  if (process.env.WIZE_SKIP_BASELINE === '1') {
+    log('WIZE_SKIP_BASELINE=1 — not running the baseline; you can do it later in your IDE.');
+    return { ok: false, skipped: true };
+  }
+  const { cmd, args } = harness.buildCmd(prompt);
+  log(`Running ${cmd} ${args.map(a => /\s/.test(a) ? '"' + a + '"' : a).join(' ')}\n`);
+  const r = spawnSync(cmd, args, { cwd: projectRoot, stdio: 'inherit' });
+  return { ok: r.status === 0, exitCode: r.status, signal: r.signal };
+}
+
+function manualInstructions(harness) {
+  if (!harness) {
+    return [
+      '',
+      'No AI harness CLI was detected on PATH (claude / codex / opencode).',
+      'Open your IDE in this repo and run:',
+      '  /wize-document-project',
+      ''
+    ].join('\n');
+  }
+  const { cmd, args } = harness.buildCmd('/wize-document-project');
+  const shown = `${cmd} ${args.map(a => /\s/.test(a) ? '"' + a + '"' : a).join(' ')}`;
+  return [
+    '',
+    `Skipping the headless run. When you're ready, run from this folder:`,
+    `  ${shown}`,
+    '',
+    `Or open your IDE and type:  /wize-document-project`,
+    ''
+  ].join('\n');
+}
+
+function defaultPrompt() {
+  return 'Activate the wize-document-project skill and execute it on this repository. Follow the steps in .claude/skills/wize-document-project/SKILL.md (or the equivalent path for your IDE). Output the baseline docs under .wize/knowledge/document-project/.';
+}
+
+module.exports = {
+  HARNESSES,
+  whichSync,
+  detectHarnessCli,
+  runHeadlessBaseline,
+  manualInstructions,
+  defaultPrompt
+};

package/tools/installer/version-check.js

@@ -0,0 +1,117 @@
+// Best-effort, non-blocking npm registry check for "is there a newer wize-dev-kit
+// version than the one I'm running?". Designed so the CLI can call it from
+// `list` / `agent list` / `help` and print a single hint at the top, without
+// ever blocking the command if the network is slow, the user is offline, or
+// the registry is misbehaving.
+//
+// Strategy:
+//   - Cache the registry answer in $XDG_CACHE_HOME (or ~/.cache) for 1 hour.
+//   - Resolve via fetch with a 1.5s timeout. Failure is silent.
+//   - Compare with the kit version baked into the running CLI.
+//   - Expose a `printUpdateHintIfAny(currentVersion)` helper for the CLI.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const CACHE_TTL_MS = 60 * 60 * 1000;       // 1h
+const NETWORK_TIMEOUT_MS = 1500;
+
+function cacheFile() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'wize-dev-kit', 'registry-version.json');
+}
+
+function readCache() {
+  const f = cacheFile();
+  try {
+    const stat = fs.statSync(f);
+    if (Date.now() - stat.mtimeMs > CACHE_TTL_MS) return null;
+    return JSON.parse(fs.readFileSync(f, 'utf-8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeCache(payload) {
+  const f = cacheFile();
+  try {
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, JSON.stringify(payload), 'utf-8');
+  } catch (_) { /* cache failure is harmless */ }
+}
+
+async function fetchLatestFromRegistry() {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), NETWORK_TIMEOUT_MS);
+  try {
+    const res = await fetch('https://registry.npmjs.org/wize-dev-kit', {
+      signal: ctrl.signal,
+      headers: { Accept: 'application/vnd.npm.install-v1+json' }
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const latest = body && body['dist-tags'] && body['dist-tags'].latest;
+    return typeof latest === 'string' ? latest : null;
+  } catch (_) {
+    return null;   // any error → silent fallback
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Returns the registry-latest version, hitting the cache first. Never throws,
+// never blocks meaningfully (network call is capped + abortable).
+async function getLatestVersion({ skipCache = false } = {}) {
+  if (!skipCache) {
+    const c = readCache();
+    if (c && c.version) return c.version;
+  }
+  const fresh = await fetchLatestFromRegistry();
+  if (fresh) writeCache({ version: fresh, fetched_at: Date.now() });
+  return fresh;
+}
+
+function semverGreater(a, b) {
+  const pa = String(a).split('.').map(n => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return true;
+    if ((pa[i] || 0) < (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+// Prints a one-line hint when a newer version is available. Silent otherwise.
+// Designed to be awaited near the top of a CLI command; if anything is slow
+// or off, it just returns.
+async function printUpdateHintIfAny(currentVersion, { log = console.log, isTTY = process.stdout.isTTY } = {}) {
+  if (process.env.WIZE_DISABLE_UPDATE_CHECK === '1') return;
+  if (!isTTY) return;            // don't spam pipes
+  try {
+    const latest = await getLatestVersion();
+    if (!latest) return;
+    if (semverGreater(latest, currentVersion)) {
+      log('');
+      log(`  ↑ Update available: wize-dev-kit ${currentVersion} → ${latest}`);
+      log(`    Run \`npx wize-dev-kit@latest update\` in your project to refresh adapters.`);
+      log('');
+    }
+  } catch (_) {
+    /* total fallback — never block the command */
+  }
+}
+
+module.exports = {
+  CACHE_TTL_MS,
+  NETWORK_TIMEOUT_MS,
+  cacheFile,
+  readCache,
+  writeCache,
+  fetchLatestFromRegistry,
+  getLatestVersion,
+  semverGreater,
+  printUpdateHintIfAny
+};

package/tools/installer/wize-cli.js

@@ -16,6 +16,8 @@ const readline = require('node:readline');
 const prompts = require('prompts');
 const { applyGitignore, generateUserToml } = require('./setup-helpers.js');
 const { cmdUpdate } = require('./commands/update.js');
+const { detectHarnessCli, runHeadlessBaseline, manualInstructions, defaultPrompt } = require('./baseline.js');
+const { printUpdateHintIfAny } = require('./version-check.js');
 const { cmdSync: cmdSyncReal } = require('./commands/sync.js');
 const { cmdAgentList, cmdAgentCreate, cmdAgentEdit } = require('./commands/agent.js');
 
@@ -89,9 +91,41 @@ function logo() {
   ].join('\n');
 }
 
+// Pipe-safe line reader.
+//
+// `readline.question()` has two bugs that bite us when stdin is a pipe (e.g.
+// `printf ... | wize-dev-kit install` or our CI smoke test):
+//   1. Opening a new createInterface per call closes stdin on .close().
+//   2. Even with a shared interface, the second `question` after a single
+//      empty line ("\n") never resolves — readline's question machinery
+//      stalls in non-TTY mode.
+//
+// We replace it with an event-based queue: subscribe to `line` once, push
+// resolved promises in order. Empty lines are propagated as `""`. EOF is
+// treated as end of the queue (remaining waiters resolve with `""`).
+let _rl = null;
+let _queue = [];
+let _waiters = [];
+
+function getRl() {
+  if (_rl) return _rl;
+  _rl = readline.createInterface({ input: process.stdin, terminal: false });
+  _rl.on('line', (line) => {
+    if (_waiters.length) _waiters.shift()(line);
+    else _queue.push(line);
+  });
+  _rl.on('close', () => {
+    while (_waiters.length) _waiters.shift()('');
+  });
+  process.on('exit', () => { if (_rl) { _rl.close(); _rl = null; } });
+  return _rl;
+}
+
 function prompt(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise(resolve => rl.question(question, ans => { rl.close(); resolve(ans.trim()); }));
+  process.stdout.write(question);
+  getRl();
+  if (_queue.length) return Promise.resolve(_queue.shift().trim());
+  return new Promise(resolve => _waiters.push((line) => resolve(line.trim())));
 }
 
 async function confirm(question, defaultYes = true) {
@@ -385,7 +419,34 @@ async function cmdInstall(args) {
   if (detection.brownfield) {
     const baseline = await confirm('\nRun `wize-document-project` to baseline the existing repo now?', true);
     if (baseline) {
-      console.log('(stub) Pepper + Peggy would now produce the baseline docs in .wize/knowledge/document-project/.');
+      const preferIde = targets.map(t => t.code);
+      const harnesses = detectHarnessCli({ preferIde });
+      if (process.env.WIZE_SKIP_BASELINE === '1') {
+        console.log('\nWIZE_SKIP_BASELINE=1 — not running the baseline.');
+        console.log(manualInstructions(harnesses[0]));
+      } else if (harnesses.length === 0) {
+        console.log(manualInstructions(null));
+      } else {
+        const chosen = harnesses[0];
+        console.log(`\nDetected harness: ${chosen.binary} (${chosen.path}).`);
+        const confirmRun = await confirm(
+          `Run /wize-document-project via ${chosen.binary} now?`,
+          true
+        );
+        if (confirmRun) {
+          const r = runHeadlessBaseline({
+            harness: chosen,
+            projectRoot: cwd,
+            prompt: defaultPrompt()
+          });
+          if (!r.ok && !r.skipped) {
+            console.log(`\n${chosen.binary} exited with code ${r.exitCode}. You can re-run later with:`);
+            console.log(manualInstructions(chosen));
+          }
+        } else {
+          console.log(manualInstructions(chosen));
+        }
+      }
     }
   }
 
@@ -475,12 +536,22 @@ function cmdValidate() {
   require('./validators/run-all.js')(KIT_ROOT);
 }
 
+// Commands worth nudging the user about when a newer version exists. Skipped
+// for `update` (already updating), `install` (already setting up), `uninstall`
+// (already leaving), `validate` (developer-tool), and `version` (the user is
+// already asking about versions).
+const HINT_COMMANDS = new Set(['list', 'sync', 'agent', 'workflow', 'help']);
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    await printUpdateHintIfAny(KIT_VERSION);
     console.log(HELP);
     return;
   }
+  if (HINT_COMMANDS.has(cmd)) {
+    await printUpdateHintIfAny(KIT_VERSION);
+  }
   switch (cmd) {
     case 'install':   return cmdInstall(rest);
     case 'update':    return cmdUpdate({ kitRoot: KIT_ROOT, projectRoot: process.cwd() });