feat(canvas): two-way decision write-back (#352)

Turn canvas pages into a decision surface. The agent declares a decision
with canvas_decision_open; the operator answers in the browser via
activated <choice>/<approve> controls; the answer flows back into the
live session through canvas_decision_await, a bounded long-poll with an
event-bus fast path over a durable, restart-surviving inbox using a
first-wins claim for exactly-once delivery.

Adds an authenticated decision/submit route, the canvas-decision skill,
a canvas doctrine rewrite, and a develop decision_surface preference
(feature-config Question 8) honored at the design and plan approval
gates. Activates the Approve and Choice shortcodes in the admin SPA with
plain-text free-text echo and wires the CanvasDecisionProvider.

Co-authored-by: elijahr <153711+elijahr@users.noreply.github.com>

Author: elijahr

.gemini/config.yaml

@@ -0,0 +1,10 @@
+# Gemini Code Assist app config — exclude large generated lockfiles from review diffs.
+have_fun: false
+code_review:
+  disable: false
+  comment_severity_threshold: MEDIUM
+  pull_request_opened:
+    summary: true
+    code_review: true
+ignore_patterns:
+  - "package-lock.json"

.gemini/styleguide.md

@@ -20,7 +20,7 @@ Flag as **high severity** if the version bump or changelog entry is missing. Fla
 ## General Review Focus
 
 - Python code should follow PEP 8 and use type hints
-- All MCP tool functions must have `@mcp.tool()` and `@inject_recovery_context` decorators
+- All MCP tool functions must have the `@mcp.tool()` decorator
 - Silent `except Exception: pass` blocks should log the exception
 - Prefer top-level imports over function-level imports unless there is a circular dependency
 

.version

@@ -1 +1 @@
-0.72.1
+0.73.0

CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Canvas two-way decisions.** Canvas pages become a decision surface: the
+  agent declares a decision (`canvas_decision_open`), the operator answers in
+  the browser via activated `<choice>`/`<approve>` controls, and the answer
+  flows back into the live session (`canvas_decision_await` — a bounded
+  long-poll with event-bus fast path over a durable inbox with first-wins
+  claim and exactly-once delivery, surviving daemon restarts). Adds a new
+  authenticated submit endpoint, the `canvas-decision` skill (when-to-use
+  boundary, main-context-only), a canvas skill doctrine rewrite, and a develop
+  `decision_surface` preference (feature-config Question 8, default `terminal`)
+  honored at the design and plan approval gates.
 - **`/dedupe` Stage 5.5 — structural template floor.** New
   `skills/dedupe/references/template-headings.md` allowlist short-circuits
   intra-bucket pairs whose `bucket_key` matches a slot in spellbook's

README.md

@@ -193,7 +193,7 @@ Reusable workflows for structured development:
 | **Code Quality** | [enforcing-code-quality], [code-review], [advanced-code-review], [adversarial-review], [auditing-green-mirage], [fixing-tests], [fact-checking], [finding-dead-code], [distilling-prs], [requesting-code-review]† |
 | **Feature Dev** | [develop], [reviewing-design-docs], [reviewing-impl-plans], [reviewing-prs], [devils-advocate], [dispatching-sub-orchestrators] *(deprecated)*, [merging-worktrees], [resolving-merge-conflicts], [creating-issues-and-pull-requests] |
 | **Autonomous Dev** | [autonomous-roundtable], [gathering-requirements], [dehallucination], [reflexion], [analyzing-domains], [assembling-context], [designing-workflows], [deep-research], [fractal-thinking] |
-| **Specialized** | [async-await-patterns], [using-lsp-tools], [managing-artifacts], [polish-repo], [security-auditing], [generating-diagrams], [shared-references], [tooling-discovery], [canvas], [dedupe], [estimating-tickets], [rounding-up-worktree-sessions] |
+| **Specialized** | [async-await-patterns], [using-lsp-tools], [managing-artifacts], [polish-repo], [security-auditing], [generating-diagrams], [shared-references], [tooling-discovery], [canvas], [canvas-decision], [dedupe], [estimating-tickets], [rounding-up-worktree-sessions] |
 | **Meta** | [using-skills]†, [writing-skills]†, [writing-commands], [instruction-engineering], [sharpening-prompts], [optimizing-instructions], [dispatching-parallel-agents]†, [smart-reading], [project-encyclopedia] *(deprecated)*, [analyzing-skill-usage], [documenting-tools], [documenting-projects], [testing-strategy], [opportunity-awareness], [branch-context], [permissions-from-transcripts] |
 | **Session** | [fun-mode], [tarot-mode], [emotional-stakes], [session-mode-init], [session-resume], [audio-notifications], [agent2agent] |
 
@@ -258,6 +258,7 @@ Reusable workflows for structured development:
 [branch-context]: https://axiomantic.github.io/spellbook/latest/skills/branch-context/
 [agent2agent]: https://axiomantic.github.io/spellbook/latest/skills/agent2agent/
 [canvas]: https://axiomantic.github.io/spellbook/latest/skills/canvas/
+[canvas-decision]: https://axiomantic.github.io/spellbook/latest/skills/canvas-decision/
 [dedupe]: https://axiomantic.github.io/spellbook/latest/skills/dedupe/
 [permissions-from-transcripts]: https://axiomantic.github.io/spellbook/latest/skills/permissions-from-transcripts/
 [distilling-prs]: https://axiomantic.github.io/spellbook/latest/skills/distilling-prs/

commands/feature-config.md

@@ -328,9 +328,26 @@ Options:
 - Work-item level: Tokens gate work item start/complete only
 - Gate level (Recommended): Each quality gate requires a token
 - Every step: Every phase transition requires a token
+
+### Question 8: Decision Surface
+Header: "How should I ask you to decide?"
+Question: "When I hit a turning point that needs your direction — a design
+approval, a fork between approaches, a blocker — and there's real context to
+weigh (several options, trade-offs, a diagram that helps), where do you want to
+make the call?"
+
+Options:
+- Terminal questions (Recommended): I ask right here with a multiple-choice
+  prompt. Fast, no context-switch. Best when the choice is quick to grasp.
+- Interactive canvas page: I open a browser page that lays out the options with
+  explanations and diagrams, and you submit your decision there; it flows back
+  to me automatically. Best when a decision benefits from seeing it visually.
+  (I still ask in the terminal for quick yes/no gates regardless.)
 ```
 
-Store all preferences in `SESSION_PREFERENCES`.
+Store all preferences in `SESSION_PREFERENCES`. Question 8 stores
+`SESSION_PREFERENCES.decision_surface ∈ {"terminal", "canvas"}`, default
+`"terminal"`.
 
 **Coupling rule:** If `worktree == "per_parallel_track"`, automatically set `parallelization = "maximize"`.
 

commands/feature-design.md

@@ -153,6 +153,20 @@ Task:
 
 ### 2.3 Approval Gate
 
+**Decision surface (honors `SESSION_PREFERENCES.decision_surface`):** the
+design-approval prompt below is presented via `AskUserQuestion` when
+`decision_surface == "terminal"` (default). When `decision_surface == "canvas"`
+AND this approval meets the boundary in the "When to Use (testable boundary)"
+section of the canvas-decision skill (context-heavy: multiple options with
+non-obvious trade-offs, prose/diagram aids, or a hard-to-reverse design
+choice), invoke the `canvas-decision` skill instead — render the approval as a
+canvas page and await the operator's submission. This wraps the gate; it does
+NOT change it: the never-auto-proceed contract holds, and quick yes/no
+acknowledgments stay terminal even under `canvas`. Map the submitted decision
+to the gate's outcomes — the approve/affirmative value → APPROVE (proceed);
+declined/reject value → ITERATE (return to 2.1/2.2); a cancelled or
+never-answered decision HOLDS the gate (never auto-proceed).
+
 ```python
 def handle_review_checkpoint(findings, mode):
     if mode == "autonomous":

commands/feature-implement.md

@@ -106,6 +106,20 @@ Task (or subagent simulation):
 
 ### 3.3 Approval Gate
 
+**Decision surface (honors `SESSION_PREFERENCES.decision_surface`):** the
+plan-approval prompt is presented via `AskUserQuestion` when
+`decision_surface == "terminal"` (default). When `decision_surface == "canvas"`
+AND this approval meets the boundary in the "When to Use (testable boundary)"
+section of the canvas-decision skill (context-heavy: several plan options or
+trade-offs, a diagram that aids the call, or a hard-to-reverse plan
+commitment), invoke the `canvas-decision` skill instead — render the
+plan/one-pager approval as a canvas page and await the operator's submission.
+This wraps the gate; it does NOT change it: the never-auto-proceed contract
+holds, and quick yes/no acknowledgments stay terminal even under `canvas`. Map
+the submitted decision to the gate's outcomes — the approve/affirmative value →
+APPROVE (proceed); declined/reject value → ITERATE (return to 3.1/3.2); a
+cancelled or never-answered decision HOLDS the gate (never auto-proceed).
+
 **Interactive mode:** Present findings to user. Ask: APPROVE (proceed to 3.4.5) or ITERATE (return to 3.1/3.2).
 **Autonomous mode:** If findings are critical/important → fix automatically (dispatch executing-plans subagent). If minor → proceed.