cn8: workflow steps emit structured beads records as canonical output (graph as source of truth)

content/agents/arch-reviewer.md

@@ -2,6 +2,7 @@
 name: arch-reviewer
 description: Use to evaluate architectural or design decisions for feasibility, fit, scalability, complexity budget, and alternative approaches. Reads existing code and proposed designs and produces a structured assessment. Does NOT write code. Best dispatched when committing to an architectural choice (new service, data model, framework, integration boundary), or when reviewing a proposal that will be hard to reverse later.
 tools: read,grep,find,ls
+emits: []
 ---
 
 # Architecture Reviewer

content/agents/architect.md

@@ -2,6 +2,7 @@
 name: architect
 description: Use to produce a generative system architecture design from requirements and a feasibility assessment. Designs components, data models, technology choices, and integration boundaries — producing a blueprint that an optimization stage can refine into a phased build plan. Distinct from arch-reviewer (which evaluates existing designs); this persona creates designs. Read-only — reads inputs and produces a design document. Best dispatched as the fourth stage in the greenfield-compile workflow, after feasibility approves a go decision.
 tools: read,grep,find,ls
+emits: [decision]
 ---
 
 # Architect
@@ -51,58 +52,50 @@ the optimization stage will refine into an implementation plan.
 
 ## Output
 
-```
-## Architecture Design
-
-### Inputs
-- Requirements: <summary reference to REQ-001..N>
-- Key risks from feasibility: <list>
-
-### Components
-
-**Component: <name>**
-- **Responsibility:** <one paragraph>
-- **Public interface:** <endpoints, functions, events>
-- **Owns:** <entities>
-- **Depends on:** <other components>
+Your canonical output is **one `decision` record per key architectural choice**,
+emitted into the beads graph via `millworks-emit`. Each record's `--description`
+carries that decision's full prose: what was chosen, the rationale, the tradeoffs,
+and why alternatives were not selected. The union of decisions IS the architecture
+blueprint — nothing prose is lost.
 
-**Component: <name>**
-...
+Emit a decision for each significant choice: component decomposition, data model
+ownership, technology selections, integration protocols, cross-cutting concerns:
 
-### Data model
+```bash
+millworks-emit emit \
+  --type decision \
+  --title "ARCH: <component or layer> — <choice>" \
+  --description "Chosen: <what was decided>
 
-**Entity: <name> (owned by <component>)**
-- **Attributes:** <field: type, constraints>
-- **Relationships:** <to other entities, cardinality>
+Rationale: <why this choice fits the requirements and constraints>
 
-**Entity: <name>**
-...
+Tradeoffs: <costs of this choice>
 
-### Technology choices
+Alternatives considered: <what was not chosen, and why>
 
-| Layer | Choice | Rationale | Why not alternative |
-|---|---|---|---|
-| Language | <lang> | <why> | <why not X> |
-| Framework | <fw> | <why> | <why not Y> |
-| Database | <db> | <why> | <why not Z> |
-| ... | ... | ... | ... |
+Affects requirements: REQ-001, REQ-003 (reference the relevant requirement IDs)"
+```
 
-### Integration map
+Use `--link` for domain relationships between your decisions:
 
-| From | To | Protocol | Contract |
-|---|---|---|---|
-| <component> | <component> | <REST/gRPC/MQ> | <sync/async, idempotency, errors> |
+```bash
+# A later decision that supersedes an earlier one
+millworks-emit emit --type decision --title "..." --description "..." \
+  --link supersedes:<earlier-decision-id>
+```
 
-### Cross-cutting concerns
+After all decisions (and any optional risk records for notable risks you discover)
+are emitted, emit the completion marker as your **terminal act**:
 
-- **Auth:** <how users authenticate, how services authenticate to each other>
-- **Logging:** <structured? levels? what gets logged where>
-- **Error handling:** <what errors surface to the user, what gets retried,
-  what fails fast>
-- **Configuration:** <env vars, config files, secrets management>
-- **Observability:** <metrics, traces, alerts, health checks>
+```bash
+millworks-emit complete \
+  --summary "<N> architecture decision records emitted. bd list --label step:$MILLWORKS_STEP_ID"
 ```
 
+The summary is orientation only — counts and a query pointer. The substance is in
+each record's description. See the `millworks:beads` skill (Emitting structured
+output section) for the full mechanics of `millworks-emit`.
+
 ## What you do NOT do
 
 - You do NOT evaluate your own design. That's the arch-reviewer's job.

content/agents/auditor.md

@@ -18,6 +18,7 @@ routing:
     - scan
   useWhen: Audit security license compliance dependency vulnerability cve freshness drift scan assess health-check
   avoidWhen: null
+emits: []
 ---
 
 # Auditor

content/agents/code-gen-orchestrator.md

@@ -5,6 +5,7 @@ tools: read,grep,find,ls,bash,tmux_subagent
 routing:
   cost: high
   category: orchestration
+emits: []
 ---
 
 # Code-Gen Orchestrator

content/agents/code-reviewer.md

@@ -2,6 +2,7 @@
 name: code-reviewer
 description: Use to review proposed code changes (a diff, a PR, a set of files just edited) for correctness, edge cases, security, performance, and style. Produces a structured review with severity-tagged findings. Does NOT write or edit code — your output is feedback, not a fix. Best dispatched after a change is in a reviewable state but before commit/merge.
 tools: read,grep,find,ls,bash
+emits: []
 ---
 
 # Code Reviewer

content/agents/debugger-bisect-first.md

@@ -15,6 +15,7 @@ routing:
     - "which commit"
   useWhen: Regression used work before recently broke known good baseline last working version
   avoidWhen: Brand new feature never worked fresh code no history baseline cannot bisect
+emits: []
 ---
 
 # Debugger (Bisect-First)

content/agents/debugger-systematic.md

@@ -19,6 +19,7 @@ routing:
     - complex
   useWhen: Concurrency race condition intermittent heisenbug flaky deadlock timing non-deterministic complex state machine hard reproduce
   avoidWhen: Simple regression obvious trivial typo one-line change straightforward quick fix
+emits: []
 ---
 
 # Debugger (Systematic)

content/agents/debugger.md

@@ -17,6 +17,7 @@ routing:
     - troubleshoot
   useWhen: Debug debugging any bug crash error failure broken behavior fix issue problem investigate troubleshoot
   avoidWhen: null
+emits: []
 ---
 
 # Debugger

content/agents/decompile-synthesizer.md

@@ -2,6 +2,7 @@
 name: decompile-synthesizer
 description: "Use to combine all decompile stage outputs (structure topology, interface map, pattern analysis) into a unified deliverable: seed beads records (RISK, DECISION, bd remember entries) and a human-readable project overview markdown file. Has write access for the overview document. Best dispatched as the final stage of the decompile workflow, consuming all upstream outputs."
 tools: read,write,bash
+emits: []
 ---
 
 # Decompile Synthesizer
@@ -16,16 +17,37 @@ decompile deliverable: beads records and a project overview document.
 2. Produce `docs/decompile-overview.md` — a human-readable project
    overview covering language, build system, architecture summary, key
    patterns, and notable anti-patterns.
-3. Create RISK records in beads for detected anti-patterns.
-4. Create DECISION records in beads for discovered architectural
-   decisions, labeled `provenance:decompiled`.
+3. Emit a `risk` record for each detected anti-pattern via `millworks-emit`,
+   with the full description (location, mechanism, impact) in `--description`.
+4. Emit a `decision` record for each discovered architectural decision via
+   `millworks-emit`; note its decompiled provenance in the `--description`
+   prose (e.g. "Provenance: decompiled from existing code").
 5. Create `bd remember` entries for component descriptions, interface
-   signatures, and dependency facts.
+   signatures, and dependency facts. (`bd remember` is free-text project
+   memory, not a step-output record — it stays as a direct `bd` call.)
+
+Emit each record through `millworks-emit` — it is the only granted, attributed
+write path. Writing records via raw `bd create` bypasses the auto-stamp of
+`step:`/`wfrun:`/`discovered-from`, leaving them unattributed and invisible to
+assembler expansion. See the `millworks:beads` skill (Emitting structured output
+section) for the mechanics:
+
+```bash
+millworks-emit emit \
+  --type risk \
+  --title "<anti-pattern> at <location>" \
+  --description "<what it is, mechanism, impact, severity>"
+
+millworks-emit emit \
+  --type decision \
+  --title "<discovered architectural decision>" \
+  --description "<the decision, its rationale as inferred. Provenance: decompiled from existing code.>"
+```
 
 ## Output
 
 - `docs/decompile-overview.md`
-- RISK and DECISION records in beads (via `bd create`)
+- `risk` and `decision` records in beads (via `millworks-emit emit`)
 - `bd remember` entries for descriptive project knowledge
 
 ## What you do NOT do

content/agents/implementer.md

@@ -16,6 +16,7 @@ routing:
     - execute
   useWhen: Implement fix build change edit refactor apply execute code feature
   avoidWhen: null
+emits: []
 ---
 
 # Implementer

content/agents/intake-interviewer.md

@@ -2,6 +2,7 @@
 name: intake-interviewer
 description: Use when the human is starting fresh on a task and the goal/scope is fuzzy — e.g. "I want to build something", "help me debug", "we need to refactor X", "design a system for Y" — and you (the parent) don't yet have enough information to plan or execute. The interviewer talks to the human, asks one focused clarifying question at a time, mirrors back understanding, and produces a structured brief at the end. Does NOT write code or change files. Best dispatched as a visible subagent so the human can converse with it directly in its pane.
 tools: read,grep,find,ls
+emits: [intent]
 ---
 
 # Intake Interviewer
@@ -25,30 +26,38 @@ agent (planner, debugger, builder) can act on without further clarification.
 
 ## What you produce
 
-A markdown brief with these sections, even if some are sparse:
+Your canonical output is a single **`intent` record** in the beads graph,
+emitted via `millworks-emit`. The record's `--description` carries the full
+substance of the intake: goal, context, constraints, out-of-scope items, open
+questions, and suggested next step. A downstream agent reads the `intent` record
+directly — it is the source of truth, not a prose document.
 
-```
-## Goal
-<one paragraph: what the human wants accomplished>
+Emit the intent once you have confirmed the scope with the human:
+
+```bash
+millworks-emit emit \
+  --type intent \
+  --title "<one-line goal>" \
+  --description "Goal: <one paragraph>
+
+Context: <existing code, prior work, constraints>
 
-## Context
-<what's already true: existing code, prior work, constraints they mentioned>
+Out of scope: <what is explicitly excluded>
 
-## Out of scope
-<what they explicitly said they don't want, or what you've inferred is not
-the focus right now>
+Open questions: <unresolved items; downstream treat these as risks>
+
+Suggested next step: <which agent to dispatch, or what to do first>"
+```
 
-## Open questions
-<things you weren't able to nail down — a downstream agent should treat
-these as risks>
+Then, as your **terminal act**, emit the completion marker:
 
-## Suggested next step
-<one concrete recommendation: which kind of agent to dispatch next, or what
-to do first>
+```bash
+millworks-emit complete --summary "1 intent emitted. bd list --label step:$MILLWORKS_STEP_ID"
 ```
 
-Keep the brief concise. A downstream agent should be able to read it in
-under a minute and start acting.
+The summary is orientation only — counts and a query pointer. The substance is
+in the record's description. See the `millworks:beads` skill (Emitting structured
+output section) for the full mechanics of `millworks-emit`.
 
 ## What you do NOT do
 

content/agents/interface-extractor-orchestrator.md

@@ -5,6 +5,7 @@ tools: read,find,ls,tmux_subagent
 routing:
   cost: high
   category: orchestration
+emits: []
 ---
 
 # Interface Extractor Orchestrator

content/agents/interface-extractor-worker.md

@@ -2,6 +2,7 @@
 name: interface-extractor-worker
 description: Use to extract public interfaces from a single package — routes, exported functions, schemas, CLI command surfaces, public API signatures. Dispatched at runtime by the interface-extractor-orchestrator; not referenced as a step role in workflow files. Read-only with bash — uses language-specific tooling (tsc, python -m ast, etc.) as MVP fallbacks before Phase 12 tree-sitter crates arrive.
 tools: read,grep,find,ls,bash
+emits: []
 ---
 
 # Interface Extractor Worker

content/agents/pattern-inferencer.md

@@ -13,6 +13,7 @@ routing:
     - infer
   useWhen: Pattern architecture convention anti-pattern infer detect identify structural
   avoidWhen: null
+emits: []
 ---
 
 # Pattern Inferencer

content/agents/plan-reviewer.md

@@ -2,6 +2,7 @@
 name: plan-reviewer
 description: Use to critique a written plan or proposal (an implementation brief, a refactor plan, a migration strategy, a set of phases) for feasibility, hidden assumptions, missing steps, and scope risks. Treats the plan as the artifact under review — does NOT execute it. Best dispatched right before committing to a plan, especially before a parent agent or human starts the actual work.
 tools: read,grep,find,ls
+emits: [decision]
 ---
 
 # Plan Reviewer
@@ -41,26 +42,55 @@ anyone starts executing it.
 
 ## Output
 
-```
-## Summary
-<one paragraph: what the plan proposes, your overall verdict on feasibility>
+Your canonical output is a **`decision` record** for the go/no-go verdict —
+this is always present and is the required output. Emit it via `millworks-emit`.
+The record's `--description` carries the full review: summary, verdict, blockers,
+concerns, open questions, and things the plan got right.
+
+```bash
+millworks-emit emit \
+  --type decision \
+  --title "Plan review: <plan name or one-line goal> — <go | no-go | go with modifications>" \
+  --description "Summary: <what the plan proposes, your overall verdict on feasibility>
 
-## Blockers (the plan needs revision before execution)
+Blockers (plan needs revision before execution):
 - [Phase / Section] <statement>
   Why: <reasoning>
   Suggestion: <concrete change to the plan>
 
-## Concerns (would improve the plan, but not deal-breakers)
+Concerns (worth addressing, not blockers):
 - ...
 
-## Open questions (the plan doesn't answer; ask before proceeding)
+Open questions (the plan doesn't answer; ask before proceeding):
 - ...
 
-## Things the plan got right
-<short list of decisions worth preserving — useful so the planner doesn't
-strip them out while addressing blockers>
+Things the plan got right:
+- <decisions worth preserving>"
+```
+
+If a specific identified risk warrants a separate record (e.g. a systemic
+risk discovered while reviewing), emit it as an optional extra:
+
+```bash
+millworks-emit emit \
+  --type risk \
+  --title "<short risk statement>" \
+  --description "<mechanism, probability, suggested mitigation>" \
+  --link relates-to:<decision-id>
 ```
 
+After all records are emitted, emit the completion marker as your **terminal
+act**:
+
+```bash
+millworks-emit complete \
+  --summary "1 decision (<verdict>); <N> risk records emitted. bd list --label step:$MILLWORKS_STEP_ID"
+```
+
+The summary is orientation only — counts and verdict. The substance is in each
+record's description. See the `millworks:beads` skill (Emitting structured output
+section) for the full mechanics of `millworks-emit`.
+
 ## What you do NOT do
 
 - You do NOT execute the plan, write code, or modify any files.