refactor(engine): premise-witness drift + single-resolution prompt cascade + per-unit worktrees + studio trim

.claude-plugin/marketplace.json

@@ -4,15 +4,14 @@
     "name": "GigSmart",
     "url": "https://gigsmart.com"
   },
-  "metadata": {
-    "description": "H·AI·K·U — universal lifecycle orchestration with hat-based workflows, completion criteria, and automatic context preservation.",
-    "version": "8.0.0"
-  },
   "plugins": [
     {
       "name": "haiku",
       "description": "H·AI·K·U methodology — universal lifecycle orchestration with hat-based workflows, completion criteria, and automatic context preservation.",
-      "source": "./plugin",
+      "source": {
+        "source": "npm",
+        "package": "haiku-method"
+      },
       "category": "Pattern",
       "keywords": [
         "haiku",

.claude/rules/architecture-prototype-sync.md

@@ -4,6 +4,22 @@ The interactive runtime-architecture map lives at `/studios/<slug>/architecture`
 
 **Whenever the architecture changes, update this map.** It is part of the sync surface, not a one-off.
 
+## Sync surface — files that must move together
+
+Any change to the cursor's per-stage walk or the per-action prompt structure has to be reflected across all of these. They are the canonical reference for "what does the engine actually do" and they drift away from each other silently if not kept in sync.
+
+| File | What it owns | When to update |
+|---|---|---|
+| `packages/haiku/src/orchestrator/workflow/cursor.ts` | The authoritative per-stage walk + role-list ordering | Any change to phase order, role lists, or what action fires when |
+| `packages/haiku/src/orchestrator/prompts/PROMPTS.md` | The prompt-folder layout taxonomy + the "where does a new prompt go" decision tree | Any change to phase order, action lifecycle, or scope/phase taxonomy. **Folder layout block under `## Scope / phase taxonomy` must reflect the same lifecycle order as `cursor.ts`** — `cursor.ts` is the source of truth; PROMPTS.md is the human-readable cross-reference |
+| `website/app/studios/[slug]/architecture/_data/actors.ts` | Orchestrator's `notes` field — the prose cursor description | Any per-stage walk reorder, any role-list change, any cascade or engine-built-role change |
+| `website/app/studios/[slug]/architecture/_data/payload-for.ts` | Per-transition action payloads, validations, writes, instructions | Any new/changed cursor action; any role-list reorder; any mandate-resolution path change |
+| `website/app/studios/[slug]/architecture/_components/ArchitectureMap.tsx` | The visual flow (phase order, gate captions, role nameplates) | Phase reorder, new gate kinds, new pills, post-intent role changes |
+| `CLAUDE.md` (project root) | "Concept-to-Implementation Mapping" table | Any new concept/component, terminology change, or cross-component contract |
+| `plugin/studios/ARCHITECTURE.md` | The structural reference for studio/stage/unit/hat/feedback boundaries | Any structural change to that boundary surface |
+
+The general principle: **`cursor.ts` is the source of truth**, and PROMPTS.md + the architecture map + CLAUDE.md are all secondary projections of it. When they disagree, fix the projection, not the engine.
+
 ## Auto-generated workflow diagrams (per studio)
 
 The per-studio Mermaid `stateDiagram-v2` files at `website/public/workflow-diagrams/<studio>.mmd` are derived from the workflow engine in `packages/haiku/src/orchestrator/workflow/` and the StudioConfig built from `plugin/studios/<studio>/`. They show every stage's full phase progression, every hat sequence enumerated inside `execute`, and every (bolt × fix-hat) combination inside `review_fix`.
@@ -67,6 +83,26 @@ Any change to one of the following requires verifying or updating the architectu
 
 The map claims to be canonical. If it diverges from the orchestrator code, **the orchestrator is right and the map is wrong** — fix the map, do not fix the orchestrator to match.
 
+## 2026-05-17 — pre/post review/approve split + three-tier cascade
+
+`dispatch_review` moved from post-execute to **PRE-execute** — it now fires between `elaborate_loop` completion and wave-ready hat dispatch, auditing the planned SPEC before any code lands. `dispatch_approval` stayed POST-execute, auditing the WORK against the SPEC the pre-execute walk already approved. The same engine-built roles (`spec`, `continuity`, `cross-stage-consistency`) fire in BOTH walks; each renders phase-appropriate mandate prose from sibling files:
+
+- `packages/haiku/src/orchestrator/prompts/stage/review/dispatch_review/engine-bodies/<role>.eta.md` (pre-execute prose: "audit the planned spec")
+- `packages/haiku/src/orchestrator/prompts/stage/approve/dispatch_approval/engine-bodies/<role>.eta.md` (post-execute prose: "audit the built work")
+- `packages/haiku/src/orchestrator/prompts/intent/review/intent_review/engine-bodies/<role>.eta.md` (intent-completion prose)
+
+Studio review-agent, hat, and fix-hat mandates resolve via a three-tier cascade: `project/.haiku/studios/<studio>/stages/<stage>/<kind>/<role>.md` → `plugin/studios/<studio>/stages/<stage>/<kind>/<role>.md` → `plugin/studios/<studio>/<kind>/<role>.md` → `plugin/<kind>/<role>.md`. First hit wins.
+
+Studio-level intent-completion review agents were renamed from `plugin/studios/<studio>/review-agents/` to `plugin/studios/<studio>/intent-review-agents/` to free the studio tier in the cascade for stage-scope agents.
+
+Orphan cursor actions removed: `review` and `intent_completion_review` (both had prompt builders but no emit clauses).
+
+Map reflects these in:
+- `_data/actors.ts` — orchestrator's cursor walk description shows the pre/post ordering and lists the engine roles + the cascade.
+- `_data/payload-for.ts` — header comment + every review/approval entry document the new role list, engine-bodies path, and cascade.
+- `_components/ArchitectureMap.tsx` — pre-execute review block (`elab-to-prereview`) sits BEFORE the execute phase visually; nested-gate caption names all three engine roles + the cascade; post-intent card names `intent-review-agents/` instead of `review-agents/`.
+- `packages/haiku/src/orchestrator/prompts/PROMPTS.md` — folder layout block under `## Scope / phase taxonomy` lists phases in lifecycle order (elaborate → review (PRE-execute) → execute → approve (POST-execute) → complete).
+
 ## 2026-04-27 — `feedback_dispatch` route
 
 The per-stage gate handler at `packages/haiku/src/orchestrator/workflow/handlers/gate.ts` no longer re-pops the review UI when a human-authored FB has `resolution: null`. It returns `feedback_dispatch` instead, handing the items back to the agent for inline triage / reply. The map reflects this in two places:
@@ -77,7 +113,7 @@ The per-stage gate handler at `packages/haiku/src/orchestrator/workflow/handlers
 
 ## Known terminology drift (followup work)
 
-The AI-DLC paper (`website/content/papers/ai-dlc-2026.md`) and several docs (`docs/concepts.md`, `docs/workflows.md`, `docs/example-*.md`) reference an **operating-mode taxonomy: HITL / OHOTL / AHOTL** that the implementation has moved past. Today the only mode field is `intent.mode` (`continuous` / `discrete` / `hybrid`); user involvement is determined by per-stage `gate` type in `STAGE.md` plus which skill the user invoked (`/haiku:start`, `/haiku:pickup`, `/haiku:autopilot`, `/haiku:revisit`).
+The AI-DLC paper (`website/content/papers/ai-dlc-2026.md`) and several docs (`docs/concepts.md`, `docs/workflows.md`, `docs/example-*.md`) reference an **operating-mode taxonomy: HITL / OHOTL / AHOTL** that the implementation has moved past. Today the only mode field is `intent.mode` (`continuous` / `discrete` / `hybrid`); user involvement is determined by per-stage `gate` type in `STAGE.md` plus which skill the user invoked (`/haiku:haiku-start`, `/haiku:haiku-pickup`, `/haiku:haiku-autopilot`, `/haiku:revisit`).
 
 The prototype reflects the **implementation**, not the legacy paper terminology. When the paper/docs are revised to align with the implementation, this note can be removed and the prototype's User-actor modal "terminology drift" callout can also be removed.
 

.claude/rules/blog-general-audience.md

@@ -0,0 +1,85 @@
+# Blog: write for a general audience, even when the topic is technical
+
+Posts under `website/content/blog/**/*.{md,mdx}` are read by people who are NOT in the codebase. They may be senior engineers from other stacks, technical product leads, founders evaluating a harness, or curious AI-adjacent readers. The post earns their attention by explaining **what** the thing does and **why it matters to them** — not by giving them a guided tour of the implementation.
+
+This rule pairs with `.claude/rules/blog-humanize.md` and `.claude/rules/content-voice.md`. Where they conflict, voice wins; where they agree, this rule fills in the specific "don't tour the codebase" failure mode that humanize and voice don't explicitly cover.
+
+## The bar
+
+A post passes the bar when a reader who has never opened the repo can:
+
+1. Tell you what the feature does in one sentence.
+2. Tell you why it would change how they work.
+3. Tell you what a reasonable next step would be (read the related post, try the install, look at the linked PR).
+
+A post fails the bar when those three answers require the reader to recognize a function name, a file path, or an internal jargon term.
+
+## Specific bans
+
+These shapes show up over and over and should not pass review:
+
+### "Implementation: `funcName` in `<path>:<line>`" tail sentences
+
+The pattern: a paragraph makes its point in plain language, then closes with `Implementation: validateOutputLiveness in packages/haiku/src/orchestrator/validators.ts`. The tail adds zero value for the general reader. The PR link or commit SHA at the bottom of the post is the verification surface.
+
+- **Wrong**: "The gate refuses to advance until every unit's outputs exist on disk. Implementation: `validateOutputLiveness` in `packages/haiku/src/orchestrator/validators.ts:284`."
+- **Right**: "The gate refuses to advance until every unit's outputs exist on disk." (Link the PR or commit at the end of the post if the reader wants to verify.)
+
+### MCP tool names dropped beyond first introduction
+
+Naming the tool once at the moment of introduction is fine and often load-bearing (e.g., "the agent calls `haiku_run_next` to get its next instruction"). Sprinkling it through three more paragraphs reads as engineer-flavoring.
+
+- **Wrong**: "The agent calls `haiku_run_next` to advance. Later, when feedback piles up, it calls `haiku_run_next` again, and `haiku_run_next` returns a `feedback_dispatch` action."
+- **Right**: "The agent calls `haiku_run_next` to advance. Later, when feedback piles up, the next tick hands back a feedback dispatch."
+
+### File-path inventories
+
+A bullet list or comma-separated run of file paths reads as "here is the codebase tour I gave myself." The user value is what each file *does*, in one sentence.
+
+- **Wrong**: "The design-stage runtime verifier at `plugin/studios/software/stages/design/review-agents/runtime-verifier.md`, the development-stage runtime verifier at `plugin/studios/software/stages/development/review-agents/runtime-verifier.md`, and the studio-level intent-completion runtime verifier at `plugin/studios/software/intent-review-agents/runtime-verifier.md` each…"
+- **Right**: "Runtime verifiers fire at three points: when the design renders, when the build runs, and when the intent closes. Each one drives the page in a browser and judges what it saw."
+
+### Frontmatter field-name lists in prose
+
+Naming the field once when the post is specifically about that field is fine. Listing four or five field names in a sentence to flavor the prose is not.
+
+- **Wrong**: "Every other inheritance-shaped decision lives in the unit's metadata — `model:`, `depends_on:`, `inputs:`, `outputs:`, `quality_gates:`."
+- **Right**: "Every other inheritance-shaped decision lives in the unit's metadata. One more field belongs there."
+
+### Internal jargon as if the reader already speaks it
+
+Words like "the cursor," "the FSM," "the orchestrator," "the cascade," "FB-as-unit," "pre-tick," "wave-ready architect," "feedback-assessor hat" are precise inside the team and opaque outside. When you need to use them, define them at first mention with one short clause. If you don't need to use them to make the point, don't.
+
+- **Wrong**: "The wave-ready architect fans out parallel hat invocations against pre-tick-classified feedback in the FB-as-unit fix loop."
+- **Right**: "When feedback lands, the engine routes each finding to a specialist agent to fix it, then re-runs the same check that flagged it."
+
+### Hook-name inventories
+
+A reader skimming the page does not gain anything from learning that there are eight named hooks. They gain something from learning that "guardrails fire before the agent moves." Skip the inventory; keep the takeaway.
+
+### `.haiku/intents/<slug>/...` path expansions on repeat
+
+Expanding the path the first time the post discusses the artifact layout is fine. Expanding it three more times in the same post is noise. Refer to "the unit file," "the intent record," "the feedback file" after the first mention.
+
+## What stays
+
+The rule does not ban citation — it bans citation-as-flavoring. These citations earn their place every time and should NOT be cut:
+
+- **A specific commit SHA, PR number, or test path** that the post uses as load-bearing evidence ("PR #265 broke when the design-stage components shipped but never rendered"). This is the No-Empty-Authority rule paying off.
+- **A single named file or function** when the post is specifically about what that file or function enforces (and the post uses it once, not three times).
+- **The pattern-name coined inside the post** ("the continuity contract", "the workshop has two editors", "the agent in the seat") — those are doing the work the rule is trying to protect.
+- **Links to other blog posts** — internal cross-references stay linked.
+- **MCP tool names** at the first moment they're introduced as the actor in the sentence.
+- **Branch names, skill commands** (`/haiku:haiku-start`, `/haiku:haiku-pickup`) that the reader will type — these are user-surface, not implementation tour.
+
+## The test
+
+Before reporting a blog post done, read it through once with the question: "If I deleted every backticked identifier and every file path from this post, would the argument still land?" If yes, you've succeeded — the backticked identifiers were earning their place by adding precision to an argument that already worked. If no, the argument was leaning on the identifiers, and they were doing the load-bearing work the prose should have done.
+
+A second test: would a senior engineer from a different stack — Python, Go, Rust — finish this post knowing what the feature does and why it matters? If they'd put it down halfway because the paragraph required familiarity with TypeScript file layouts they don't have, you've written for the team, not for the audience.
+
+## Scope
+
+This rule applies only to `website/content/blog/**`. UI copy, internal docs, paper revisions, READMEs, plugin descriptions, and code comments all have a different register and audience — the general-audience rule would fight them.
+
+When writing or editing a blog post, this rule runs alongside `blog-humanize.md`: apply the voice-first pass, the AI-tell sweep, the general-audience cut, and the final self-audit before reporting done.