v1.5.0

What's Changed

• Agent team: four repo-defined teammates for parallel work by @maglionejm in #68
• Ideate exit requires the concept-selection decision (fixes #65) by @maglionejm in #69
• Dossier/report hardening: honesty propagation, injection flattening, structured Ulwick reads by @maglionejm in #70
• Changelog: team-loop fixes (#69, #70) by @maglionejm in #71
• Docs: full redocumentation pass post #69/#70 (6 corrections) by @maglionejm in #72
• Review B batch: exploration honesty, corpus caps, sidekick contract (8 findings) by @maglionejm in #73
• Review C batch: demo resumes stay offline + surface hardening (7 findings) by @maglionejm in #74
• Review A batch: step bounds, torn-journal resilience, budget-key validation (8 findings) by @maglionejm in #75
• Changelog: full team review cycle (#72–#75) by @maglionejm in #76
• Exploration mining v2: ratification, quoted spans, glossary, deliverable surfacing, cost split by @maglionejm in #78
• Agent-ergonomics layer: codebase map, gotchas ledger, task recipes, AGENTS.md by @maglionejm in #79
• Enable Agent Teams for the repo teammates by @maglionejm in #80
• Specs: v1.5 slate (diff, backlog, heatmap, estimate) by @maglionejm in #81
• bokken backlog — ranked, exportable validation to-do (v1.5) by @maglionejm in #82
• bokken estimate — modeled pre-flight cost estimate (v1.5) by @maglionejm in #83
• bokken diff — cross-run comparison of two finalized runs (v1.5) by @maglionejm in #84
• Segment × outcome opportunity heatmap + bokken opportunities (v1.5) by @maglionejm in #85
• Docs: the v1.5 verb slate (diff, backlog, estimate, opportunities) by @maglionejm in #86
• ci: run OpenSpec validation through the npm CLI by @maglionejm in #87
• chore: repo-wide dead-code removal and line-by-line simplification (v1.5 cleanup) by @maglionejm in #88
• docs: v1.5 audit — README structure, codebase map, events, MCP, operating, agents, changelog by @maglionejm in #89
• chore(release): v1.5.0 — verb slate, exploration mining v2, team review cycle, cleanup by @maglionejm in #91

Full Changelog: v1.4.0...v1.5.0

v1.4.0 — code exploration, review hardening, docs audit

Code exploration (#62)

When the corpus includes code, Empathize now opens with a citation-validated map of current capabilities (actor + trigger + observable outcome), journaled as current_capability interpretations before anyone is interviewed. Every corpus source carries its evidence role in the context header — code establishes implemented behavior, never desired intent — so no prompt can launder one into the other. The map targets the UI feature tests, replacing regex route discovery. Adapted from the exploration discipline in build-software-with-style.

Review hardening — 25 fixes (#63, #64, #66)

A three-agent full-code review produced 28 verified findings; 25 were fixed (3 were duplicates):

• Safety/security: the destructive-control guard is now enforced when acting, not just in the element digest; browser startup failures journal an abstention instead of killing the run and leaking Chromium; report escaping is attribute-safe and the inline data JSON cannot break out of its script tag; a malformed handoff package no longer costs a completed run its report.
• Governance: loop-backs clear stale pending gates; kata budgets hold within a single engine pass; stalls and missing engines journal session.stopped; MCP-created sessions get the CLI's 20M-token default guardrail (with a test — the docs audit caught this fix having been silently dropped from an earlier batch).
• Reliability/UX: torn-journal fuse guard with write rollback; no stranded dirs on failed creation; founder picks validated with an explicit journaled fallback; Twilio multi-message answers preserved; transient research failures no longer become permanent skips; vote-id mapping can't silently crown the first option; novelty_floor: 0 honored; typo'd journal filters raise; one torn library line can't break future finalizations; clean refusals (exit 2) on malformed briefs and handoff errors.

Docs audit (#66)

Every documentation file verified claim-by-claim against the code — 31 corrections (verb inventory, tool counts, event taxonomy incl. the new citations extension, terminal snippets matched to real output). Test suite: 326 tests.

uvx bokken demo        # a full run: offline, $0.00
pip install -U bokken

Full diff: v1.3.1...v1.4.0

v1.3.1 — Claude Desktop one-click bundle (.mcpb)

Bokken installs natively in Claude Desktop: download bokken-1.3.1.mcpb below and double-click it (or drag it onto the app). The bundle prompts for an optional API key (the built-in demo costs $0.00 and needs none), the workspace, and the input roots that govern what Bokken may read.

• The bundle carries configuration, never code — it wraps uvx bokken==1.3.1 serve, so Desktop always runs the released package (requires uv).
• A drift test pins the manifest's declared tools to the server's registered tools, and the packed version to the package version; the manifest validates against the official @anthropic-ai/mcpb schema.
• From this tag onward, the publish pipeline builds and attaches the bundle automatically (#59).

Other installs unchanged: pip install -U bokken, claude mcp add bokken -- uvx bokken serve, or uvx bokken demo to see a full run first.

Full diff: v1.3.0...v1.3.1

v1.3.0 — repo-drafted briefs, session bundles, executable handoffs, environment diagnostics, report themes

The packaging release: ten changes that shorten the path from install to a shareable, executable result (issue #48, PRs #49–#56).

Onboarding

• bokken init --from-repo PATH — drafts the brief from your repository's own corpus: one extraction-lane call for product facts, one cognition-lane call for the draft, field-by-field review, cost disclosed (~$0.10–0.30), scratch journal discarded.
• bokken doctor [--network] — one-screen environment diagnosis (keys as presence only, extras with their consequences, browser, workspace, input roots); every failing row carries its exact fix command.

Deliverables

• bokken pack NAME [--deliverables-only] — one portable archive per run: manifest with verdict, list-price cost, and a sha256 file index; the deliverables-only variant states exactly what was omitted.
• Report themes — --theme bokken|plain|file.json (brand color, label, footer): chrome only, never content; journaled at new so regeneration is stable.
• Self-contained HTML — Chart.js is vendored and inlined; the report opens fully offline.

Handoff

• bokken handoff --emit claude-code|cursor|codex — renders the canonical OpenSpec package as an executable HANDOFF.md (execution order, binding exclusions, evidence-lookup paths down to the journal) plus target-native command files.

Also

• MCP server.json manifest + one-line installs for Claude Code/Desktop; --json on version/stop/validate; CI on every PR; CHANGELOG; quickstart fix (the documented OpenAI model was not in the allowlist); session-config readers consolidated; dead code removed.

uvx bokken demo        # see a full run: offline, $0.00
pip install -U bokken

Full diff: v1.2.1...v1.3.0

v1.2.1 — sidekick lane off frontier prices

Contributed by @mpuig (#37), accepted by the maintainers.

• The Anthropic sidekick lane — verbatim corpus reads and mechanical UI stepping — routes to claude-sonnet-5 (was claude-opus-5): delegated reading stops paying frontier prices, per the Fusion rule that frontier is for judgment only.
• Model capability is now a per-model set of routing lanes, enforced at session creation: the extraction-grade model is refused outside extraction mechanically, not by convention.
• bokken costs (and the MCP cost tool) now report persona turns, abstention share, and the share of abstentions caused by invalid citations — so a lane-quality regression is observable in the same place as the spend it would save.
• The CLAUDE.md charter now names the sidekick lane explicitly.

Note: prompt caches are per-model, so the first run after upgrading pays one cache write on the new sidekick model. Nothing is invalidated.

pip install -U bokken

Full diff: v1.2.0...v1.2.1

v1.2.0 — honest token accounting and prompt-cache reuse

Cost work contributed by @mpuig.

• Budgets count what providers bill (#36) — SessionState.tokens_spent now includes the cached prompt prefix and every other usage bucket the provider reports, each priced exactly once. bokken costs, the run receipts, and the token guardrail all see the same number.
• Prompt-cache reuse in per-call loops (#38) — the cache boundary now covers the per-persona loops that repeat one large shared prefix across calls; two templates were reordered so their stable material sits above the varying material and can actually cache.

Also archives the OpenSpec change for the OpenAI provider (#24, shipped in v1.1.0).

pip install -U bokken

Full diff: v1.1.1...v1.2.0

v1.1.1 — consent, provenance, and input-path confinement

Three governance fixes on the honesty core, contributed by @mpuig.

• Affirmative interview consent (#30) — a Twilio answer-window timeout, silence, or an ambiguous reply no longer reads as opt-in. The consent contact and its outcome are journaled (interview.consent_requested / interview.consent_resolved) before any question reaches a real human; the consent request is sent once, never retried. The terminal channel requires the operator to confirm consent live.
• Input answer provenance (#31) — answers submitted through the MCP mailbox are attributed to the submitting client's handshake identity and journaled as simulated machine contributions, never as human testimony. Decisions driven by machine answers carry requires_real_validation.
• Input path confinement (#32) — client-supplied brief.inputs paths on the MCP surface are confined to authorized roots (traversal, symlink escapes, and outside absolute paths are refused before session creation; refusals are journaled as evidence.input_rejected). CLI operator paths are unchanged; BOKKEN_INPUT_ROOTS widens the reach explicitly.

Security-relevant (#32), shipped immediately per the patch policy.

pip install -U bokken

Full diff: v1.1.0...v1.1.1

v1.1.0 — onboarding: demo, init, receipts, gallery

The onboarding release (issue #27): from pip install to a full report without spending a cent.

Highlights

• bokken demo — a complete Design Thinking run on a bundled fictional product (Lanzadera, a commuter-shuttle SaaS whose ±6-minute pickup promise is quietly breaking). Offline, deterministic, no API key, ~10 seconds, $0.00. Every citation resolves against the shipped corpus; the feasibility lens casts a red veto that stays on the record; the verdict is an honest iterate with a quantified next step. See the published output: https://maglionejm.github.io/bokken/gallery/demo-report.html
• bokken init — a guided brief from three templates (saas-retention, consumer-app, internal-tool), validated against the Brief schema before writing, ending with the exact new/run commands.
• Cost framing and receipts — bokken run states the typical full-run range ($20–35 list price) and the session's token guardrail before spending, and prints a journal-derived receipt (USD + model calls) at every halt. --json carries cost_usd/model_calls.
• Page gallery — the demo report and deck are published on the Page and rebuilt from a fresh run via make gallery; the specimen is journal-derived, never hand-edited. https://maglionejm.github.io/bokken/#demo

Install

uvx bokken demo          # see a whole run first — free
pip install bokken       # or: uv tool install bokken

Full diff: v1.0.0...v1.1.0

v1.0.0 — Bokken

Bokken is an agentic harness for Design Thinking: the Empathize → Define → Ideate → Prototype → Test loop as an executable, event-sourced, governed process. Terminal-first, MCP-consumable, no GUI.

Install

uvx bokken version

Extras: bokken[ui] (browser walkthrough + per-feature functional tests + wireframe exercise, plus uvx playwright install chromium once) · bokken[interview] (Twilio validation interviews).

What a run gives you

• Grounded synthetic research: persona panels that answer only from your corpus with citations or abstain (abstentions become research debt); JTBD desired outcomes scored into a deterministic Ulwick opportunity ranking.
• Your product, actually tested: with --app-url, an SPA-aware browser walkthrough plus per-feature functional tests with works/broken/unclear verdicts; prototypes include HTML wireframes on your repo's own design tokens, exercised before the panel judges them.
• The market on the record: authorized web research on the chosen concept — competitors with overlap, sourced signals, regulatory notes — as reported evidence.
• Three firewalled convergence lenses: adversarial feasibility against your real code (red = veto), independent RICE with no code access, outcome desirability. A mandatory skeptic. Dissent preserved verbatim.
• Honesty enforced in code: simulated contributions labeled at record level; decisions on synthetic evidence carry requires-real-validation; killed concepts get no build handoff.
• Real humans close the loop: bokken validate turns research debt into an interview guide; an agentic interviewer moderates real participants (terminal or Twilio SMS/WhatsApp) and the register is rescored on reported human evidence.
• Deliverables: Session Dossier (evidence graph incl.), strict OpenSpec handoff with slice plans and sequencing, a strategic PPTX deck, and a portable single-file HTML report (agent deliberation, per-feature test cards, Opportunity Solution Tree, next actions).
• Learnings compound: every finalized run feeds the insights library; the next run on the same product starts from what was already supported, contradicted, or broken.
• Fusion cost architecture: frontier lanes judge (Fable 5 / Opus 5), a cached sidekick lane reads; bokken costs reports spend and cache hit-rate straight from the journal.

Stability

The Journal taxonomy (v1), CLI verbs and --json shapes, MCP tools, and deliverable formats are stable. Tuning knobs, the Twilio channel, and the library record shape are experimental. Active development is paused while real-user feedback accumulates — run it against your product and tell us what happened.

Docs: https://maglionejm.github.io/bokken/

v0.9.0 — prototypes that speak the product's language, memory that compounds

Three roadmap features: wireframe_html prototypes generated on the declared repository's real CSS design tokens and exercised in a real browser before the test panel judges them; an Opportunity Solution Tree chapter (Teresa Torres's discovery structure, read straight from the journal graph); and the insights library — every finalized run appends its learnings, and the next run on the same product starts knowing what was already supported, contradicted, or broken, with session provenance on every borrowed line. Merged via #18.