haiku-method 2.2.0

package/studios/software/stages/development/review-agents/architecture.md

@@ -0,0 +1,12 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify the implementation follows the project's architectural patterns and does not introduce structural debt.
+
+**Check:**
+- The agent **MUST** verify that new code follows existing module boundaries and dependency directions
+- The agent **MUST** verify that no circular dependencies introduced
+- The agent **MUST** verify that public APIs are minimal — implementation details are encapsulated
+- The agent **MUST** verify that naming conventions match the codebase (not the agent's preference)
+- The agent **MUST** verify that no unnecessary abstractions or premature generalizations
+- The agent **MUST** verify that changes to shared code consider all consumers

package/studios/software/stages/development/review-agents/correctness.md

@@ -0,0 +1,11 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify the implementation correctly satisfies the behavioral specification and completion criteria.
+
+**Check:**
+- The agent **MUST** verify that all acceptance criteria from the behavioral spec are implemented, not approximated
+- The agent **MUST** verify that error handling covers the specified error states, not just the happy path
+- The agent **MUST** verify that data validation matches the data contracts exactly (types, nullability, ranges)
+- The agent **MUST** verify that no logic errors, off-by-one mistakes, or silent failures
+- The agent **MUST** verify that edge cases specified in the product stage are handled

package/studios/software/stages/development/review-agents/performance.md

@@ -0,0 +1,12 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** identify performance regressions or inefficiencies in the implementation.
+
+**Check:**
+- The agent **MUST** verify that no N+1 query patterns or unbounded data fetches
+- The agent **MUST** verify that database queries use appropriate indexes (check against schema)
+- The agent **MUST** verify that large collections are paginated, not loaded entirely into memory
+- The agent **MUST** verify that no blocking operations on hot paths
+- The agent **MUST** verify that caching is used where specified, with correct invalidation
+- The agent **MUST** verify that bundle size impact is reasonable for frontend changes

package/studios/software/stages/development/review-agents/security.md

@@ -0,0 +1,12 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** identify security vulnerabilities introduced by the implementation.
+
+**Check:**
+- The agent **MUST** verify that no injection vectors (SQL, command, XSS, template injection)
+- The agent **MUST** verify that authentication and authorization checks are present on all protected paths
+- The agent **MUST** verify that secrets are not hardcoded or logged
+- The agent **MUST** verify that input validation occurs at system boundaries
+- The agent **MUST** verify that no insecure defaults (permissive CORS, debug mode, disabled TLS verification)
+- The agent **MUST** verify that dependencies do not have known critical vulnerabilities

package/studios/software/stages/development/review-agents/test-quality.md

@@ -0,0 +1,12 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify tests actually validate behavior, not just exercise code paths.
+
+**Check:**
+- The agent **MUST** verify that tests assert on behavior and outcomes, not implementation details
+- The agent **MUST** verify that test names describe the scenario and expected result
+- The agent **MUST** verify that edge cases from the behavioral spec have corresponding tests
+- The agent **MUST** verify that no tests that always pass (tautological assertions, mocked everything)
+- The agent **MUST** verify that integration tests cover system boundaries (API, database, external services)
+- The agent **MUST** verify that test data is realistic, not minimal placeholder values

package/studios/software/stages/inception/STAGE.md

@@ -0,0 +1,27 @@
+---
+name: inception
+description: Understand the problem, define success, and elaborate into units
+hats: [researcher, distiller, verifier]
+fix_hats: [researcher, feedback-assessor]
+review: ask
+elaboration: collaborative
+inputs: []
+---
+
+# Inception
+
+Understand the problem, define success, and elaborate into units.
+
+## Overlap Awareness
+
+During elaboration, check for other active H·AI·K·U branches working on overlapping files:
+
+```bash
+# List active haiku branches and their changed files
+for branch in $(git branch -r --list 'origin/haiku/*/main' 2>/dev/null); do
+  changed=$(git diff --name-only main...$branch 2>/dev/null)
+  [ -n "$changed" ] && echo "Branch: $branch" && echo "$changed"
+done
+```
+
+If overlap is detected with files this intent plans to modify, note it in the discovery document. Not a blocker — just awareness for the researcher hat to factor in.

package/studios/software/stages/inception/discovery/DISCOVERY.md

@@ -0,0 +1,83 @@
+---
+name: discovery
+location: .haiku/intents/{intent-slug}/knowledge/DISCOVERY.md
+scope: intent
+format: text
+required: true
+---
+
+# Discovery
+
+Comprehensive understanding of the **problem space, business context, and high-level scope**. Inception captures **WHAT** we're solving and **WHY**, plus enough constraints for the design stage to plan. It does **NOT** specify **HOW**.
+
+## Content Guide
+
+The discovery document should cover:
+
+### Business Context
+- **Feature goal & vision** — what problem this solves, the desired outcome when it ships, and why now (urgency drivers, strategic alignment, dependencies)
+- **Origin & context** — where the request came from: customer feedback with specific quotes or references, internal discussions, strategic initiatives, or upstream dependencies
+- **Success criteria** — both functional (what users can do) and outcome-based (what business or user results we expect). Frame in user-observable terms, not implementation metrics.
+
+### Competitive Landscape
+- **Who offers something similar** — specific competitors with a brief description of their approach and links to relevant product pages
+- **What they do well** — acknowledge strong implementations fairly
+- **Gaps and opportunities** — where competitor solutions fall short and what can be done differently
+
+### Considerations & Risks
+- **Strategic considerations** — compliance scope, pricing implications, rollout strategy questions
+- **Capability needs** — high-level dependencies the solution will require (e.g., "needs a relational database", "needs OAuth", "needs Slack integration"). Name the capability, not the specific technology choice.
+- **Open questions** — things without answers yet, framed as questions for the team to resolve during design
+- **Risks** — what could go wrong at the strategic or product level, what assumptions are being made
+
+### UI Impact
+- **Affected surfaces** — which screens, flows, or user-facing areas are new or modified, with a brief description per area. Name the surface ("user dashboard", "settings page"), not the components.
+
+### Existing Code Structure
+
+A backward-looking inventory of code paths the new work will interact with — what already exists in the tree at the moment inception runs. This grounds downstream stages in real source rather than guesses. Tag every cited reference with its era / status so design and development can tell active from dormant patterns.
+
+**Tag values (one per reference, inline parenthetical):**
+
+- `(active)` — code that runs in the current production path and is the source-of-truth for new work
+- `(dormant)` — code that exists in the tree but is feature-flagged off, behind a deprecated provider, or otherwise not exercised in current production. Reference for context only — do NOT treat as ground truth for new work.
+- `(deprecated)` — code being actively phased out. Note the migration target on the same line.
+- `(in-flight)` — code under active development on a non-merged branch. Cite the branch.
+
+Tags MUST appear inline with the file reference, not in a separate legend, so the tag survives excerpt-into-subagent-prompt operations. Untagged references are ambiguous and downstream stages will treat them as `active` — which is wrong by default in any codebase that has both legacy and current paths coexisting.
+
+**Worked example:**
+
+```markdown
+## Existing Code Structure
+
+- `apps/worker/src/wallet/PayoutProvidersSection.tsx` (active) — current production payout flow; gates `AccountBalanceCard` off when Branch is active (L34-44)
+- `apps/worker/src/wallet/account-balance.tsx` (dormant) — Stripe-era Transfer button. Hidden under Branch; reference for context only.
+- `apps/worker/src/wallet/BranchWalletCard.tsx` (active) — Branch destination card; current source of truth for the wallet surface
+- `apps/worker/src/wallet/legacy-payout.tsx` (deprecated) — being removed in INTENT-XXX. Migration target: `PayoutProvidersSection`.
+```
+
+## Out of Scope for Inception
+
+The following belong in **later stages** and **MUST NOT** appear in the discovery document:
+
+- **Entity field names, types, or relationships** → design stage
+- **API endpoints, methods, request/response shapes** → design stage
+- **Architecture patterns, module boundaries, file paths** → design stage
+- **Infrastructure resources, port numbers, deployment topology** → operations stage
+- **Performance budgets, security policies, accessibility specs** → design stage (when they shape contracts) or operations stage (when they shape runtime config)
+- **Specific shell commands, build scripts, or test runs** → development / validation stages
+- **Code-archaeology summaries that pre-bind future implementation locations** ("the new auth module will live at `packages/foo/src/bar.ts`") — design owns implementation locations; inception MUST NOT pre-commit. **Backward-looking inventory of existing code with era-tagged references** under `## Existing Code Structure` is the explicit exception — see content guide.
+
+If the agent feels the urge to specify any of the above, that signals the wrong stage. Capture it as an **open question** or a **capability need** instead, and let the downstream stage answer it.
+
+## Quality Signals
+
+- A team member unfamiliar with the feature can understand the full picture from this document
+- Business context is clear enough for non-technical stakeholders
+- Competitive research includes specific competitors with links, not vague references
+- Risks are framed at the product/strategic level ("we don't yet know how customers want to authenticate"), not at the implementation level ("the auth middleware has no test coverage")
+- Success criteria are **observable by users**, not measured in implementation terms (✅ "user can publish in one click"; ❌ "publish endpoint p99 < 200ms")
+- The document distinguishes the problem space from any specific solution
+- Capability needs are named at the dependency level ("needs OAuth"), not the implementation level ("needs Auth0 with PKCE flow")
+- Untagged file references in `## Existing Code Structure` are a spec gap. Either tag every reference, or surface the era ambiguity as an open question for the user to resolve.

package/studios/software/stages/inception/hats/distiller.md

@@ -0,0 +1,42 @@
+**Focus:** Break the intent into **knowledge-topic units** that together cover the problem space. Each unit's body answers a specific research question (e.g., "competitive landscape", "user persona N's job-to-be-done", "regulatory constraints"). Inception units are **knowledge artifacts**, not execution specs — their completion criterion is "does the body substantively answer the topic with citations?", not "does this command exit 0?".
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** create units whose topic is an implementation deliverable (e.g., "implement the auth middleware", "write the migration script") — those belong to the design or development stage
+- The agent **MUST NOT** create units that prescribe schemas, API shapes, file paths, or specific commands — those belong to design / development
+- The agent **MUST NOT** write executable completion criteria for inception units (no `pytest`, no `npm run …`, no bash commands). Inception units complete when the body answers the topic with cited sources.
+- The agent **MUST NOT** create units that are too large (the body must be answerable within a single bolt's research effort)
+- The agent **MUST NOT** create units with circular dependencies
+- The agent **MUST** define clear topical boundaries between units (each unit owns one research question)
+- The agent **MUST NOT** elaborate by implementation layer (all backend research, then all frontend research) — elaborate by **problem-space topic** (one unit per discovery question)
+
+## Model Assignment
+
+Every unit **MUST** be assigned a `model:` field during elaboration. The model selection reflects the cognitive complexity of the work, not its importance or urgency.
+
+### Three Model Tiers
+
+**opus** — Architectural decisions, competing approaches, no established pattern to follow, high cascading-failure risk.
+- Signals: "How should we structure this?", "Should we use X or Y approach?", "What's the safest design here?", "This could break other systems if we get it wrong."
+- Example: "Redesign the state machine for intent lifecycle" — requires architectural judgment.
+
+**sonnet** — Known patterns with judgment calls, standard feature additions, cross-file changes requiring coordination.
+- Signals: "Here's the pattern, apply it consistently", "This feature uses our normal flow", "Multiple files change but integration is clear", "We've done similar work before."
+- **Default when uncertain.** If you can't decide between sonnet and opus, pick sonnet — the elaborator can always escalate upward.
+- Example: "Add a new field to unit frontmatter and wire it through the orchestrator" — standard pattern, clear scope.
+
+**haiku** — Purely mechanical execution, copy-paste-adapt patterns, additive-only changes, no decision-making required.
+- Signals: "Just repeat what we already do here", "No design choices involved", "Following a single clear path", "Zero risk of breaking other systems."
+- Example: "Add a new hat to the development stage" — copy existing hat template, update names, done.
+
+### Decision Heuristic
+
+Start at **sonnet**. Justify upward to **opus** if the unit involves architectural or trade-off decisions. Justify downward to **haiku** if the unit is purely mechanical with no judgment calls.
+
+### Anti-patterns (RFC 2119)
+
+- The agent **MUST NOT** assign `opus` to units with fully-specified mechanical execution paths.
+- The agent **MUST NOT** leave the `model:` field unset — every unit spec **MUST** include the field.
+- The agent **MUST NOT** assign the same model to all units without assessing each individually.
+- The agent **MUST NOT** use "this is important work" as justification for `opus` — importance and complexity are different concepts.
+
+> **Note:** Model assignments are always recorded in unit frontmatter. The orchestrator only uses them for subagent spawning when `HAIKU_MODEL_SELECTION` is set. When unset, all subagents inherit the session default.

package/studios/software/stages/inception/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**Focus:** Independently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** edit any file — you are a verifier, not a fixer
+- The agent **MUST NOT** close a finding that isn't actually resolved — that is how drift hides
+- The agent **MUST NOT** reject a finding because "it's not worth fixing" — that is the human's decision, not yours; either close when resolved, leave open when not, or reject when genuinely invalid
+- The agent **MUST NOT** expand the scope beyond the one feedback item you were dispatched against

package/studios/software/stages/inception/hats/researcher.md

@@ -0,0 +1,13 @@
+**Focus:** Understand the **problem space** at a business level — what problem are we solving, who benefits, what does success look like? Gather origin context, research the competitive landscape, surface strategic considerations and risks, identify affected user surfaces, and name high-level capability needs (e.g., "needs a database", "needs OAuth"). Frame everything in terms of user outcomes and business goals. Inception captures **WHAT and WHY**; the design stage owns **HOW**.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** jump to solutions before understanding the problem
+- The agent **MUST NOT** over-design at the discovery phase — this is understanding, not design
+- The agent **MUST NOT** produce implementation artifacts (database schemas, API specs, migration plans, infrastructure configs, file paths, code snippets) — those belong in the design and development stages
+- The agent **MUST NOT** specify non-functional requirements as concrete budgets ("p99 < 200ms", "TLS 1.3", "WCAG 2.2 AA"). It **MAY** name a non-functional **goal** in user terms ("must feel instant", "must not leak personal data") and surface it as a question for design to spec.
+- The agent **MUST NOT** specify which framework, library, or service to use; technology choices happen in the design stage
+- The agent **MUST NOT** read the codebase to bind specific files, modules, or patterns into the discovery document. A skim for context is fine; pre-binding implementation locations is not.
+- The agent **MUST** frame discoveries in terms of user outcomes and business value, not technical implementation
+- The agent **MUST** research the competitive landscape before finalizing the discovery document
+- The agent **MUST** trace and document the origin of the request when context is available
+- The agent **MUST** define success criteria with both functional and outcome dimensions, observable by users (not measured in implementation terms)

package/studios/software/stages/inception/hats/verifier.md

@@ -0,0 +1,51 @@
+**Focus:** Validate the per-unit knowledge artifact that the prior hat (researcher → distiller, or whatever the stage's do-role produced) committed to this unit's body. Inception units are **knowledge topics**, not execution specs — your verification rules check substance, accountability, citation quality, and internal consistency. NOT executable verify-commands or DAG validity (those are workflow engine concerns or build-stage concerns).
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** read or interpret unit frontmatter for any mechanical purpose. workflow engine territory.
+- The agent **MUST NOT** validate against execution-spec rules (depends_on resolution, quality_gates shape, executable acceptance criteria) — those are wrong for knowledge artifacts.
+- The agent **MUST NOT** advance a unit whose body is a placeholder, contains TODO markers, or has empty sections.
+- The agent **MUST NOT** reject for stylistic preferences. Substantive gaps only.
+- The agent **MUST** name a specific failed criterion in any rejection.
+- The agent **MUST NOT** invent rules not in this mandate. Stage scope is the contract.
+
+## What you check (BODY ONLY)
+
+### 1. The artifact answers the unit's topic
+
+Each inception unit has a topic — its title and the first paragraph of its body. The remaining body MUST answer that topic substantively. A unit titled "Competitive landscape" must contain actual competitive analysis, not a placeholder, an outline, or a forwarding note ("see other unit").
+
+Reject if the body is a placeholder, an outline without content, or a redirect.
+
+### 2. Sources are cited where claims are made
+
+Knowledge artifacts without sources are opinions. The body MUST cite specific sources (URL, doc path, dated stakeholder conversation, or a clearly-named industry standard) for non-trivial claims. Acceptable citation shapes:
+
+- "[Acme Corp pricing page, accessed 2026-04-15]"
+- "[Internal user interview with Jane Doe, 2026-04-12]"
+- "[npm registry, package `foo` v3.2.1, downloads/week]"
+- "[Project README, lines 45-67]"
+
+Bad: "industry common knowledge", "as is well-known", or unsupported numerical claims ("market size is approximately $50B").
+
+Reject if non-trivial claims lack citation.
+
+### 3. Internal consistency
+
+The body must not contradict itself or its own framing. Specifically:
+- The unit's title and the first paragraph (mission/purpose) must align with what the rest of the body delivers
+- Numerical claims must be consistent across the body (don't say market size is $50B in one paragraph and $5B in another)
+- Recommendations / conclusions must follow from the evidence presented, not skip steps
+
+### 4. Decision-register consistency
+
+The unit body MUST NOT propose, default to, or recommend an option that contradicts a Decision already recorded in the intent's decision register. If the unit's analysis recommends an option the user explicitly ruled out, REJECT and cite the Decision ID.
+
+(How: the dispatch payload inlines the intent's decision register. Read it. Compare it to the unit body. If you find a contradiction, that's a hard reject.)
+
+### 5. Open questions accounted for
+
+If the unit body contains an "Open Questions" section, every entry must either:
+- Have an answer or proposed default in the body, or
+- Be flagged with **(needs human escalation)** with a clear reason for why the agent couldn't resolve it.
+
+Open questions left unresolved without escalation flag are a reject — they mean the artifact isn't actually complete.

package/studios/software/stages/inception/outputs/KNOWLEDGE.md

@@ -0,0 +1,28 @@
+---
+name: knowledge
+location: .haiku/intents/{intent-slug}/stages/inception/artifacts/
+scope: intent
+format: text
+required: true
+---
+
+# Knowledge Artifacts
+
+Research outputs from inception units. Each unit MUST produce at least one knowledge artifact written to the intent's `knowledge/` directory.
+
+## Expected Artifacts
+
+- **Discovery documents** — business context, feature goal, origin, competitive landscape, technical landscape, constraint analysis
+- **Competitive analysis** — competitor approaches, strengths, gaps, and opportunities with links to relevant product pages
+- **Risk assessments** — specific risks with severity and mitigation
+- **Architecture notes** — existing patterns, module boundaries, dependencies
+- **Stakeholder findings** — requirements gathered from domain experts, customer feedback, or internal discussions
+- **UI impact maps** — affected screens and flows with brief descriptions of expected changes
+
+## Quality Signals
+
+- Every research unit produces at least one artifact
+- Artifacts are named descriptively (not "notes.md")
+- Findings are specific and actionable, not vague summaries
+- Business context and technical landscape are both represented
+- Cross-references between related artifacts

package/studios/software/stages/inception/package.json

@@ -0,0 +1,3 @@
+{
+	"private": true
+}

package/studios/software/stages/inception/phases/ELABORATION.md

@@ -0,0 +1,52 @@
+# Inception Stage — Elaboration
+
+Inception is a **research / distillation** stage. Its units are knowledge topics, not execution specs. Each unit produces one knowledge artifact that downstream stages (`product`, `design`, `development`, etc.) consume as input.
+
+## What a unit IS in this stage
+
+One investigable knowledge topic. Examples:
+- "Competitive landscape for the addressed problem"
+- "Existing user persona and pain map"
+- "Technical landscape: relevant existing systems and their constraints"
+- "Origin and business motivation"
+- "Success criteria — outcome metrics and functional capabilities"
+- "Risk inventory and mitigation surfaces"
+
+What a unit is **NOT** in this stage:
+- ❌ A code module to build (those are execution specs — `software/development` authors them in its own elaborate phase)
+- ❌ A database schema, API endpoint, or migration plan (technical-design artifacts — `software/design` owns these)
+- ❌ A Gherkin scenario or acceptance-criteria spec (PRD-style artifacts — `software/product` owns these)
+
+If you find yourself drafting `depends_on:`-heavy execution DAGs or `quality_gates:` with shell commands, you're authoring the wrong stage's units. Stop and ask whether the work belongs downstream.
+
+## What "completion criteria" means here
+
+Knowledge-artifact criteria are about **substance and accountability**, not executability. Acceptable shapes:
+
+### Good criteria — substantive and checkable
+
+- "Document names ≥3 alternatives the user could buy instead, with a one-paragraph differentiation per alternative"
+- "Persona section names primary user, secondary user, and one user explicitly out of scope"
+- "Risk inventory lists ≥5 distinct failure modes with severity (low/med/high) and detection signal"
+- "Each cited source is a specific URL, doc path, or stakeholder conversation date — not 'industry common knowledge'"
+- "Open questions section has ≥0 entries; each open question has a proposed default for veto-style approval OR a `(needs human escalation)` flag"
+
+### Bad criteria — vague or build-class language wrongly applied
+
+- ❌ "Domain is understood" (no concrete check; "understood" by whom?)
+- ❌ "Discovery is complete" (tautological)
+- ❌ "Each unit has 3-5 completion criteria, each verifiable by a specific command or test" — execution-spec language; inception artifacts are not testable by command
+- ❌ "Database schema is defined" — wrong stage; defer to design/development
+- ❌ "Implementation passes the test suite" — there is no implementation in inception
+
+## How verification happens
+
+Knowledge artifacts are validated by the verifier hat (see `hats/verifier.md` once added). The verifier checks **substance, completeness, citation quality, and internal consistency** — body-content checks only, no frontmatter interpretation.
+
+Frontmatter for inception units stays minimal — `depends_on:` is allowed when one knowledge topic genuinely informs another (e.g., "competitive landscape" feeds "differentiation analysis"), but most inception units are independent and run in parallel.
+
+## Anti-patterns
+
+- **Mixing knowledge and execution specs in one stage.** If you find a unit drifting into "implement X" language, split it: keep the inception unit at the knowledge level ("specify what X needs to do at a behavior level") and let the downstream stage author the execution spec.
+- **Single-document syndrome.** Producing one giant "discovery document" with 7 sections defeats the per-unit model — each section can't be revisited or rejected independently. One topic per unit.
+- **Skipping citation.** Knowledge artifacts without sources are opinions; the verifier rejects them.

package/studios/software/stages/inception/review-agents/completeness.md

@@ -0,0 +1,24 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify the discovery document fully captures the **problem space** and that unit elaboration covers the intent's **scope** (the what + why) without venturing into design or implementation territory.
+
+**Check (in scope — what inception MUST cover):**
+- The agent **MUST** verify that feature goal, origin context, and success criteria are present and clearly articulated
+- The agent **MUST** verify that competitive landscape research is included with specific competitors, not generic claims
+- The agent **MUST** verify that strategic considerations and product-level risks are surfaced
+- The agent **MUST** verify that high-level capability needs are named (e.g., "needs a database", "needs OAuth"), not specified ("needs Postgres 15 with PgBouncer on port 6432")
+- The agent **MUST** verify that affected user-facing surfaces are identified at the screen/flow level
+- The agent **MUST** verify that unit topics together cover the intent's scope with no obvious gaps in the **problem space** (not the solution space)
+
+**Reject (out of scope — what inception MUST NOT contain):**
+- The agent **MUST** reject any unit body that specifies entity field names, types, or relationships → that's design-stage work
+- The agent **MUST** reject any unit body that specifies API endpoints, methods, request/response shapes, or auth flows → that's design-stage work
+- The agent **MUST** reject any unit body that names file paths, module boundaries, or specific architecture patterns → that's design-stage work
+- The agent **MUST** reject any unit body that specifies infrastructure resources, port numbers, deployment topology, or operational scripts → that's operations-stage work
+- The agent **MUST** reject any unit body that includes performance budgets, security policies, or accessibility specs as concrete measurements → those are design or operations concerns
+- The agent **MUST** reject any unit body that prescribes shell commands, build scripts, or test runs → that's development / validation stage work
+- The agent **MUST NOT** demand "verifiable completion criteria as specific commands or tests" at this stage — inception units are knowledge artifacts, not execution specs. Their completion criterion is "does the body substantively answer the unit's topic?"
+- The agent **MUST NOT** require a specific implementation approach to be named (e.g., "must say which framework"); approach selection happens in the design stage
+
+**On gaps:** If the agent identifies a gap in the problem-space coverage, the finding **MUST** target the gap as a research question or capability need to add — never as an implementation specification to bind.

package/studios/software/stages/inception/review-agents/feasibility.md

@@ -0,0 +1,18 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** challenge whether the **problem is solvable at all** within reasonable constraints. Feasibility at this stage is about **strategic viability**, not architectural compatibility.
+
+**Check (in scope):**
+- The agent **MUST** verify that the named capability needs (e.g., "needs OAuth", "needs Slack integration") have at least one viable supplier in principle — not which library, just that the capability is achievable
+- The agent **MUST** verify that the success criteria, as written, are measurable in user-observable terms (not impossible to evaluate)
+- The agent **MUST** verify that the highest-impact strategic risks are surfaced (compliance, dependency-on-a-single-vendor, regulatory, irreversibility), not just obvious tactical ones
+- The agent **MUST** flag any capability need that is fundamentally incompatible with a Decision already recorded in the intent's decision register (e.g., "needs SOC2-certified database" while a Decision rules out paid SaaS)
+
+**Out of scope (do NOT check at this stage):**
+- The agent **MUST NOT** check compatibility with specific frameworks, libraries, or codebase conventions — that's the **design stage's** feasibility check, after the design proposes a specific approach
+- The agent **MUST NOT** check whether existing modules / files / classes can support the planned usage — that requires reading code as a designer, not an inception reviewer
+- The agent **MUST NOT** demand that any unit specify a particular technology choice; technology selection happens in the design stage
+- The agent **MUST NOT** raise findings that say "the codebase doesn't have X" unless X is a fundamental capability that the intent absolutely requires (e.g., "we need to ship a mobile app but have zero mobile expertise")
+
+**On rejection:** If the problem itself is infeasible (e.g., the success criteria are inherently unmeasurable, or a capability need contradicts a hard Decision), name the specific blocker. Otherwise, downstream stages own feasibility for their own scope.

package/studios/software/stages/operations/STAGE.md

@@ -0,0 +1,24 @@
+---
+name: operations
+description: Deployment, monitoring, and operational readiness
+hats: [ops-engineer, sre, verifier]
+fix_hats: [ops-engineer, feedback-assessor]
+review: auto
+elaboration: autonomous
+inputs:
+  - stage: inception
+    discovery: discovery
+  - stage: product
+    discovery: behavioral-spec
+  - stage: development
+    output: code
+  - stage: development
+    discovery: architecture
+review-agents-include:
+  - stage: development
+    agents: [security]
+---
+
+# Operations
+
+Deployment, monitoring, and operational readiness.

package/studios/software/stages/operations/discovery/RUNBOOK.md

@@ -0,0 +1,36 @@
+---
+name: runbook
+location: .haiku/knowledge/RUNBOOK.md
+scope: project
+format: text
+required: true
+---
+
+# Runbook
+
+Operational runbook for handling failure scenarios. Written for the person who gets paged at 3 AM — every entry should be actionable without needing to read the codebase.
+
+## Content Guide
+
+Organize by failure scenario. For each entry:
+
+- **Symptom description** — what the oncall sees (alert text, dashboard signal, user report)
+- **Diagnostic steps** — specific commands to run to confirm the issue and assess severity
+- **Remediation steps** — specific commands or actions to fix the problem
+- **Escalation criteria** — when to page additional people, and who
+- **Rollback procedure** — how to revert if the remediation makes things worse
+
+Common scenarios to cover:
+- Service restart (graceful and forced)
+- Database failover
+- Cache invalidation
+- Dependency failure handling (upstream service down)
+- Certificate rotation
+- Intent-specific operational scenarios
+
+## Quality Signals
+
+- Every step has a specific command, not a vague instruction ("restart the service" vs. `kubectl rollout restart deployment/api -n production`)
+- Diagnostic steps come before remediation — understand before acting
+- Escalation criteria are specific ("if error rate exceeds 5% after restart, page the database oncall")
+- Rollback procedures are tested, not theoretical

package/studios/software/stages/operations/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**Focus:** Independently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** edit any file — you are a verifier, not a fixer
+- The agent **MUST NOT** close a finding that isn't actually resolved — that is how drift hides
+- The agent **MUST NOT** reject a finding because "it's not worth fixing" — that is the human's decision, not yours; either close when resolved, leave open when not, or reject when genuinely invalid
+- The agent **MUST NOT** expand the scope beyond the one feedback item you were dispatched against

package/studios/software/stages/operations/hats/ops-engineer.md

@@ -0,0 +1,9 @@
+**Focus:** Configure deployment pipeline, define infrastructure as code, set up CI/CD, and ensure deployment is repeatable and rollback-safe. Every deployment should be automated, auditable, and reversible.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** use manual deployment steps that require human intervention
+- The agent **MUST NOT** hardcode secrets or environment-specific values in code
+- The agent **MUST NOT** omit rollback strategy — every deployment must be reversible
+- The agent **MUST NOT** skip health checks — the system must verify its own readiness
+- The agent **MUST NOT** create deployment config without testing it (terraform plan, docker build, etc.)
+- The agent **MUST NOT** mix infrastructure concerns with application code

package/studios/software/stages/operations/hats/sre.md

@@ -0,0 +1,8 @@
+**Focus:** Define SLOs (availability, latency, error rate), set up monitoring and alerting, and write runbooks for common failure modes. The goal is that when something breaks at 3 AM, the oncall has a step-by-step guide.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** alert on symptoms instead of causes (alert on error rate, not individual errors)
+- The agent **MUST NOT** sLOs without error budgets — an SLO without a budget is just a wish
+- The agent **MUST NOT** runbooks that say "page the oncall" without diagnostic steps
+- The agent **MUST NOT** monitor that generates noise (alert fatigue makes real alerts invisible)
+- The agent **MUST** define what "healthy" looks like before defining what "unhealthy" looks like

package/studios/software/stages/operations/hats/verifier.md

@@ -0,0 +1,26 @@
+**Focus:** Validate the per-unit operational artifact for the operations stage of software. Units here are ops/deployment step — operational steps with concrete preconditions, actions, and post-condition checks. Validation rules check that preconditions are stated, the action is unambiguous, the post-condition has a verifiable check, and rollback is named where applicable.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** read or interpret unit frontmatter for any mechanical purpose. workflow engine territory per architecture §1.1.
+- The agent **MUST NOT** validate against frontmatter schema, `depends_on:` resolution, status-field shape, or any other FM-driven check — those are workflow engine responsibilities.
+- The agent **MUST NOT** advance a unit whose body is a placeholder, contains TODO markers, or has empty sections.
+- The agent **MUST NOT** reject for stylistic preferences. Substantive gaps only.
+- The agent **MUST** name a specific failed criterion in any rejection.
+- The agent **MUST NOT** invent rules not in this mandate. Stage scope is the contract.
+
+## What you check (BODY ONLY)
+
+### 1. Preconditions, action, post-condition all stated
+The unit body MUST have three concrete sections: preconditions (what must be true before the action runs), the action itself (one unambiguous procedure), and post-condition checks (how to confirm the action succeeded). Reject if any of the three is missing or vague.
+
+### 2. Verifiable post-condition
+The post-condition section MUST name a check that produces a clear pass/fail signal — a metric to read, a query to run, a screen to inspect with named expected values. "Verify by eye that things look good" is a reject.
+
+### 3. Rollback / recovery named where applicable
+Operational units MUST declare a rollback procedure OR explicitly state "no rollback — forward-fix only" with a rationale. Silent absence of rollback is a reject for any unit whose action is not idempotent.
+
+### 4. Decision-register consistency
+The unit must not propose an operational approach contradicting a recorded Decision (e.g., blue-green deploy when Decision N chose canary). Cite the Decision ID.
+
+### 5. Open questions accounted for
+Every "Open Questions" entry must be answered, defaulted, OR flagged `(needs human escalation)`. Operational open questions left to runtime are how outages happen.

package/studios/software/stages/operations/outputs/DEPLOYMENT-CONFIG.md

@@ -0,0 +1,30 @@
+---
+name: deployment-config
+location: (project source tree — e.g., deploy/, .github/workflows/, infrastructure/)
+scope: repo
+format: code
+required: true
+---
+
+# Deployment Config
+
+Deployment configuration written directly to the project source tree. Like the code output, this is not a document to author — it is working infrastructure-as-code.
+
+## Content Guide
+
+Depending on the project's deployment tooling, this includes:
+
+- **Infrastructure-as-code** — Terraform, CloudFormation, Pulumi, or similar manifests
+- **Container definitions** — Dockerfile, docker-compose.yml
+- **CI/CD pipeline definitions** — GitHub Actions workflows, GitLab CI, Jenkins pipelines
+- **Environment configuration** — environment variable definitions, config maps, secrets references
+
+Written to the appropriate location for the project's deployment tooling (e.g., `deploy/`, `.github/workflows/`, `infrastructure/`).
+
+## Quality Signals
+
+- No hardcoded secrets — all sensitive values reference secret stores or environment variables
+- Pipeline includes plan/preview step before apply/deploy
+- Health checks are configured and verified
+- Rollback mechanism is defined and tested
+- Configuration is environment-agnostic (staging and production use the same templates with different values)

package/studios/software/stages/operations/phases/ELABORATION.md

@@ -0,0 +1,17 @@
+# Operations Stage — Elaboration
+
+## Criteria Guidance
+
+### Good criteria — concrete and verifiable
+
+- "Deployment pipeline runs `terraform plan` in CI and requires approval before `apply`"
+- "Runbook covers: service restart, database failover, cache flush, and certificate rotation with step-by-step commands"
+- "Alerts fire when error rate exceeds 1% over 5 minutes, with PagerDuty routing"
+- "Health check endpoint responds within 5 seconds and verifies database connectivity"
+
+### Bad criteria — vague (no clear check)
+
+- "Deployment is automated"
+- "Runbook exists"
+- "Monitoring is set up"
+

package/studios/software/stages/operations/review-agents/observability.md

@@ -0,0 +1,11 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify the system is observable enough to diagnose issues in production.
+
+**Check:**
+- The agent **MUST** verify that key operations emit structured logs with correlation IDs
+- The agent **MUST** verify that metrics cover the four golden signals (latency, traffic, errors, saturation)
+- The agent **MUST** verify that alerts have clear runbooks or at minimum actionable descriptions
+- The agent **MUST** verify that dashboards exist for the critical user journeys
+- The agent **MUST** verify that no sensitive data in logs or metrics (PII, credentials, tokens)