@lumenflow/cli 4.24.0 → 5.0.1

package/templates/core/_frameworks/lumenflow/wu-sizing-guide.md.template

@@ -14,7 +14,7 @@ Before claiming a WU, estimate its "weight" using these heuristics.
 
 | Complexity    | Files | Tool Calls | Context Budget | Strategy                                                                                                    |
 | :------------ | :---- | :--------- | :------------- | :---------------------------------------------------------------------------------------------------------- |
-| **Simple**    | <20   | <50        | <30%           | **Single Session** (Tier 2 Context)                                                                         |
+| **Simple**    | <20   | <50        | <30%           | **Single Session**                                                                                          |
 | **Medium**    | 20-50 | 50-100     | 30-50%         | **Checkpoint-Resume** (Standard Handoff)                                                                    |
 | **Complex**   | 50+   | 100+       | >50%           | **Orchestrator-Worker** or **Checkpoint-Resume**; split only if non-atomic                                  |
 | **Oversized** | 100+  | 200+       | —              | **Re-check cohesion**; split only when the work cannot land as one coherent outcome or no exception applies |
@@ -75,6 +75,33 @@ Agents consistently under-apply the cohesion rule, defaulting to micro-splitting
 
 **Apply this checklist iteratively.** After your first pass at splitting, re-run the checklist. If any merges are possible, merge and re-run again. Stop only when no further merges pass the checklist. Real-world experience shows the first pass typically over-splits by 2-3x.
 
+### 1.0.2 How to Estimate
+
+The matrix in §1 demands `estimated_files` and `estimated_tool_calls` numbers, but agents (and humans) consistently under-estimate scope. WU-1215 declared 708 LOC and shipped against 768 LOC + 100 control-flow statements — an 8% file-size miss that compounded into a 5x tool-call miss. Use the heuristics below before you commit to a sizing strategy.
+
+**Pre-claim heuristics (run these in order):**
+
+1. **Read the entry point.** Open the file you'll modify first and skim it end-to-end. If it's >500 lines or contains >50 control-flow branches, treat the WU as Medium minimum even if file count looks Simple.
+2. **Grep call sites for any symbol you'll rename or change.** `rg -l '<symbol>'` gives you a hard floor on file count. If grep returns >20 hits, you are at least Medium — stop estimating from intuition.
+3. **Count test files that touch the area.** `rg -l '<symbol>' --type ts -g '*.test.*'`. Each test file is at minimum 1 read + 1 edit + 1 verify = 3 tool calls.
+4. **Multiply by 3 for unfamiliar code, 1.5 for familiar code.** Rough rule: if you have not touched this module in the last 30 days, your first instinct is wrong by ~3x. Bias upward.
+5. **Add a 30% buffer for gates and handoff.** Format, lint, typecheck, test runs, `wu:prep`, `wu:done`, and any rebase/conflict resolution typically consume 15-20 tool calls before you ship — bake them into the estimate.
+
+**Sanity-check thresholds:**
+
+- If your estimate sits at exactly the boundary (e.g., 19 files, 49 tool calls), round up a tier. Boundary estimates almost always tip over once execution starts.
+- If you find yourself justifying why a Complex estimate "should really be Medium," you are wrong. Honour the larger estimate and pick the matching strategy.
+- If estimation itself takes >10 tool calls, the WU is probably oversized — re-check cohesion (§1.0) and consider whether a §1.5 Pre-Phase Audit would scope it better.
+
+**When to skip estimation:**
+
+- Trivial bug fixes where you have already opened the file and identified the change (1-2 tool calls). Mark `single-session` and move on.
+- Documentation WUs touching one file (this WU, for example).
+
+For everything else, the 5 minutes of grep + skim spent estimating saves the cost of a mid-WU spawn-fresh recovery.
+
+---
+
 ### 1.1 Documentation-Only Exception
 
 Documentation WUs (`type: documentation`) have relaxed file count thresholds because:
@@ -140,14 +167,16 @@ A WU touching 30 files where each requires unique logic changes, test updates, o
 
 ### 1.3 Examples Summary
 
-| WU Type                     | Files | Eligible for Override? | Reasoning                                      |
-| :-------------------------- | :---- | :--------------------- | :--------------------------------------------- |
-| Docs: update 25 markdown    | 25    | Yes (docs exception)   | <40 files, docs-only, low complexity           |
-| Docs: reorg 60 doc files    | 60    | Yes (docs exception)   | <80 files = Medium, checkpoint-resume strategy |
-| Code: rename import in 45   | 45    | Yes (shallow override) | Uniform 1-line changes, no structural edits    |
-| Code: refactor 30 files     | 30    | No                     | Each file has unique logic changes             |
-| Code: add feature across 25 | 25    | No                     | Exceeds 20-file threshold, structural changes  |
-| Docs + Code: mixed 15 files | 15    | No                     | Not docs-only, standard code thresholds apply  |
+| WU Type                      | Files | Eligible for Override?   | Reasoning                                                           |
+| :--------------------------- | :---- | :----------------------- | :------------------------------------------------------------------ |
+| Docs: update 25 markdown     | 25    | Yes (docs exception)     | <40 files, docs-only, low complexity                                |
+| Docs: reorg 60 doc files     | 60    | Yes (docs exception)     | <80 files = Medium, checkpoint-resume strategy                      |
+| Code: rename import in 45    | 45    | Yes (shallow override)   | Uniform 1-line changes, no structural edits                         |
+| Code: refactor 30 files      | 30    | No                       | Each file has unique logic changes                                  |
+| Code: add feature across 25  | 25    | No                       | Exceeds 20-file threshold, structural changes                       |
+| Docs + Code: mixed 15 files  | 15    | No                       | Not docs-only, standard code thresholds apply                       |
+| Review: audit 80 components  | 80    | Yes (review-audit, §1.4) | Read-only; spawn 4-6 parallel sub-agents with non-overlapping scope |
+| Review: security audit, auth | 30    | Yes (review-audit, §1.4) | Read-only; spawn 3-4 agents (RLS, middleware, secrets, API surface) |
 
 ---
 
@@ -236,7 +265,51 @@ sizing_estimate:
 
 ---
 
-### 1.5 Sizing Contract (Tooling-Backed Enforcement) (WU-2141)
+### 1.5 Pre-Phase Audit (No WU)
+
+Sometimes the orchestrator needs to investigate _before_ it can scope the next phase of work correctly. This is **not** a review WU — the output is the scope of the follow-up WU(s), not a standalone report. It is also not an exception clause for an over-sized single WU (sections 1.1/1.2) — it is a scoping activity the orchestrator performs inline, with no WU YAML at all.
+
+#### When to use
+
+- An earlier phase surfaced an architectural unknown (cycle, dep, interface shape) that blocks clean scoping of the next WU
+- The investigation is read-only, narrow, and bounded
+- The output is used immediately by the orchestrator to write the next WU spec
+
+#### Criteria (ALL must be true)
+
+- **Read-only**: no code changes, no YAML edits, no commits
+- **Narrow scope**: typically one dep-graph question, one file interaction, or one schema shape
+- **Bounded budget**: tool-call count fits in a single orchestrator turn (typically <25 tool calls)
+- **Output = next WU scope**: findings inform WU creation immediately; they are not promoted to a standalone document
+
+#### Not to use
+
+- If the investigation spans multiple files or concerns → use section 1.4 (Review, Audit, Exploration WU) instead, and spawn parallel sub-agents with a report as the output
+- If the output would become a design document or ADR → create a documentation WU for it
+- If any findings require code changes → those belong in their own WU, not inline
+
+#### How this differs from neighbouring sections
+
+- **vs §1.4 (Review/Audit/Exploration WU)** — §1.4 WUs produce a report as their output and typically spawn parallel sub-agents. Pre-phase audits produce no report; their only artifact is the next WU's scope, captured in the follow-up WU YAML.
+- **vs §1.1 / §1.2 (Docs-only / Shallow multi-file exceptions)** — those sections relax sizing thresholds for a _single WU that is being executed_. Pre-phase audits happen _before_ a WU is scoped; there is no WU to apply an exception to.
+
+#### Example
+
+During INIT-058 Wave 2, WU-2672 failed with a turbo cyclic dependency error. Before scoping follow-up work, the orchestrator ran an inline audit in ~5 tool calls:
+
+1. Grep `packages/@lumenflow/packs/software-delivery` for `@lumenflow/core` imports
+2. Inspect `packages/@lumenflow/packs/software-delivery/package.json` dependencies
+3. Check the two files that imported `CoverageMode`
+
+Finding: the pack's `package.json` declared only `@lumenflow/kernel` as a LumenFlow dep, and the pack had zero static imports of `@lumenflow/core` (one lazy dynamic import in one file). The cycle was self-inflicted by the previous sub-agent adding `@lumenflow/core` to the pack's deps. That audit took minutes, bypassed the need for a dedicated audit WU, and unblocked scoping of WU-2674 (a correct cohesion-closed bundle strategy) without a dead WU-2672-style shim attempt. Without this pattern, future orchestrators would default to §1.4 (overkill for a read-only 5-call check) or dispatch blind (re-introducing the same failure mode).
+
+#### Contract
+
+This pattern is informal — no `sizing_estimate` metadata, no WU YAML. The orchestrator's conversation log is the audit trail; significant findings should be captured via `pnpm mem:create --type discovery` so downstream agents can see them. If the investigation starts expanding beyond the bounded budget, stop and create a §1.4 Review WU instead.
+
+---
+
+### 1.6 Sizing Contract (Tooling-Backed Enforcement) (WU-2141)
 
 The sizing thresholds in sections 1.0-1.2 are now enforced by CLI tooling. The `sizing_estimate` metadata contract lets agents declare their sizing intent at WU creation time, and the tooling validates compliance.
 
@@ -363,52 +436,75 @@ Strict mode is intended for teams that want to enforce sizing discipline before
 
 ## 2. Strategy Decision Tree
 
-Use this logic to select your approach. If `git status` ever shows >20 modified files, STOP and re-evaluate cohesion and strategy. Do not auto-split on file count alone. First check the cohesion rule, the required ship/review/rollback question, and the documented exceptions.
+Cohesion comes first. Sizing is a strategy question, not a splitting question. Use this tree to pick an execution strategy **after** the cohesion rule (§1.0) and consolidation checklist (§1.0.1) have confirmed you have one coherent outcome. If `git status` ever shows >20 modified files mid-WU, STOP and re-evaluate cohesion before continuing.
 
 ```
-┌─────────────────────────┐
-│   Start WU Analysis     │
-└────────────┬────────────┘
-             │
-             ▼
-      ┌──────────────┐
-      │ Est. Tool    │
-      │ Calls > 50?  │
-      └──┬────────┬──┘
-         │        │
-        No       Yes
-         │        │
-         ▼        ▼
-   ┌─────────┐  ┌────────────────┐
-   │Standard │  │ Complexity     │
-   │Strategy │  │ Type?          │
-   │(Tier 2) │  └──┬──────────┬──┘
-   └─────────┘     │          │
-                   │          │
-           Single Domain   Multi-Domain
-           Clear Phases    High Coordination
-                   │          │
-                   ▼          ▼
-         ┌──────────────┐  ┌────────────────┐
-         │Checkpoint-   │  │ Must Land      │
-         │Resume        │  │ Atomically?    │
-         │• Investigate │  └──┬──────────┬──┘
-         │• Implement   │     │          │
-         │• Mid-WU      │    Yes        No
-         │  Handoff     │     │          │
-         └──────────────┘     ▼          ▼
-                    ┌──────────────┐ ┌──────────────┐
-                    │Orchestrator- │ │Decomposition │
-                    │Worker        │ │• Split WUs   │
-                    │• Main Agent  │ │• Feature     │
-                    │  = Coord.    │ │  Flags       │
-                    │• Spawns:     │ │• Dependencies│
-                    │  Tester,     │ └──────────────┘
-                    │  Guardian,   │
-                    │  Coder       │
-                    └──────────────┘
+┌─────────────────────────────────────────┐
+│         Start WU Analysis               │
+└────────────────────┬────────────────────┘
+                     │
+                     ▼
+         ┌───────────────────────┐
+         │ §1.0 Cohesion check:  │
+         │ one coherent outcome? │
+         └──┬─────────────────┬──┘
+            │                 │
+           Yes               No
+            │                 │
+            │                 ▼
+            │       ┌───────────────────────┐
+            │       │ §1.0.1 Consolidation  │
+            │       │ checklist (iterate)   │
+            │       └──────────┬────────────┘
+            │                  │
+            │          Still multiple
+            │          independent outcomes?
+            │                  │
+            │           ┌──────┴──────┐
+            │          No             Yes
+            │           │              │
+            │           ▼              ▼
+            │       (one WU)    ┌──────────────┐
+            │           │       │Decomposition │
+            │           │       │(§3 patterns) │
+            │           │       └──────────────┘
+            ▼           │
+   ┌───────────────────┴──┐
+   │ §1.0.2 Estimate:     │
+   │ files & tool calls   │
+   └──────────┬───────────┘
+              │
+              ▼
+      ┌───────────────┐
+      │ Estimated     │
+      │ tool calls?   │
+      └──┬──────┬──┬──┘
+         │      │  │
+       <50   50-100 >100
+         │      │   │
+         ▼      ▼   ▼
+   ┌─────────┐ ┌─────────────┐ ┌────────────────────┐
+   │ Single  │ │ Checkpoint- │ │ Multi-domain or    │
+   │ Session │ │ Resume      │ │ atomic delivery?   │
+   └─────────┘ └─────────────┘ └──┬──────────────┬──┘
+                                  │              │
+                                 Yes            No
+                                  │              │
+                                  ▼              ▼
+                        ┌──────────────────┐ ┌────────────┐
+                        │ Orchestrator-    │ │ Checkpoint-│
+                        │ Worker (§3       │ │ Resume     │
+                        │ patterns; spawn  │ └────────────┘
+                        │ tester/guardian) │
+                        └──────────────────┘
 ```
 
+**Reading the tree:**
+
+- The first branch is always cohesion. Decomposition (§3) is reachable only when the consolidation checklist confirms genuinely independent outcomes — never as a default response to a high tool-call estimate.
+- Once cohesion is settled, the second branch picks an _execution_ strategy from the §1 matrix. A Complex WU stays one WU; it just needs Orchestrator-Worker or Checkpoint-Resume to ship.
+- Exceptions (§1.1 docs-only, §1.2 shallow multi-file, §1.4 review/audit) bypass the sizing-tier branch — apply them at estimation time, not in the tree.
+
 ---
 
 ## 3. Splitting Patterns (Decomposition)
@@ -487,91 +583,57 @@ Only use these patterns after you have confirmed the work is no longer one coher
 
 ---
 
-## 4. Context Safety Triggers
-
-**Heading:** Default Triggers (Deviations require written justification in WU notes)
-
-If you hit ANY of these triggers during a session, you MUST perform a Standard Session Handoff:
-
-- **Token Limit:** Context usage hits **50% (Warning)** or **80% (Critical)**.
-- **Tool Volume:** **50+ tool calls** in current session.
-- **File Volume:** **20+ files** modified in `git status`.
-- **Session Staleness:** Repeated redundant queries or forgotten context (performance degradation).
-
-**Why these triggers matter:** Ignoring them led to the WU-1215 failure. An agent consumed 40% of context (80k tokens) on analysis alone, violated worktree discipline using absolute paths, and failed to deliver implementation. Preserve your reasoning capability by clearing context before you crash.
-
-**Performance degradation symptoms:**
+## 4. Context Safety and Handoff
 
-- Redundant tool calls (re-fetching already retrieved information)
-- Lost worktree discipline (edits landing in main instead of worktree)
-- Forgotten decisions or contradicting earlier conclusions
-- Increased latency on similar operations
+When a session approaches its limits, the correct response is to checkpoint and spawn a fresh agent — not to continue through compaction. Compaction summarises the conversation, which routinely loses worktree discipline, WU context, and constraint rules. Spawning fresh from a clean checkpoint is simpler and more reliable than any recovery mechanism. This is the policy that emerged from the WU-1215 failure (analysis consumed 40% of context, worktree discipline lost, zero implementation shipped).
 
-**When triggers fire:**
-
-1. Update WU YAML `notes` field with progress, decisions, and next steps
-2. Run `pnpm mem:checkpoint --wu WU-XXX`
-3. Commit work to the lane branch (in the worktree)
-4. Push the lane branch to origin
-5. Generate a fresh handoff with `pnpm wu:brief --id WU-XXX --client <client>`
-6. Resume fresh from the documented checkpoint
-
-**Deviation protocol:** If a trigger fires but you believe an exception applies, check section 1.1 (Documentation-Only Exception) or section 1.2 (Shallow Multi-File Exception). If your WU qualifies:
-
-1. Document the justification in WU notes (required)
-2. Specify which exception applies and why
-3. Monitor for performance degradation symptoms listed above
-4. If symptoms appear, checkpoint and spawn fresh regardless of file count
-
----
-
-## 5. Spawn Fresh, Don't Continue (Mandatory Policy)
-
-**When approaching context limits, spawn a fresh agent instead of continuing after compaction.**
-
-Context compaction (summarization) causes agents to lose critical rules. The recommended approach from [Anthropic's engineering guidance](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) is:
+This aligns with [Anthropic's engineering guidance for long-running harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):
 
 > "An initializer agent that sets up the environment, and a coding agent tasked with **making incremental progress in every session**, while leaving clear artifacts for the next session."
 
-### When to Spawn Fresh
+### Triggers (Mandatory Handoff)
 
-Spawn a fresh agent when ANY of these apply:
+Perform a handoff if **any** of these fire:
 
-- Context usage exceeds 80%
-- Tool calls exceed 50 in current session
-- You notice performance degradation (redundant queries, forgotten context)
-- You're about to run `/compact` or `/clear`
+- **Context budget:** usage reaches **50% (Warning)** or **80% (Critical)**.
+- **Tool volume:** **50+ tool calls** in the current session.
+- **File volume:** **20+ files** modified in `git status` (re-evaluate cohesion first — see §1.0).
+- **Performance degradation:** redundant tool calls, edits landing in main instead of the worktree, forgotten or contradicted earlier decisions, increasing latency on similar operations.
+- **About to run `/compact` or `/clear`:** spawn fresh instead.
 
-### Spawn Fresh Protocol
+### Handoff Protocol
 
 ```bash
-# 1. Checkpoint your progress
+# 1. Checkpoint your progress (memory layer)
 pnpm mem:checkpoint "Progress: completed X, next: Y" --wu WU-XXX
 
-# 2. Commit and push work
+# 2. Update WU YAML notes via wu:edit (decisions, next steps)
+pnpm wu:edit --id WU-XXX --notes "<progress + next steps>"
+
+# 3. Commit and push the lane branch (from the worktree)
 git add -A && git commit -m "checkpoint: progress on X"
 git push origin lane/<lane>/wu-xxx
 
-# 3. Generate fresh agent prompt
+# 4. Generate the fresh-agent prompt
 pnpm wu:brief --id WU-XXX --client <client>
 
-# 4. EXIT current session (do NOT continue after compaction)
+# 5. EXIT this session — do NOT continue after compaction.
 
-# 5. Start fresh agent with the generated prompt
+# 6. Start a fresh agent with the generated prompt.
 ```
 
-### Why Not Continue After Compaction?
+### Deviation Protocol (Exceptions)
 
-- Compaction summarizes conversation → rules get lost in summary
-- Agent forgets worktree discipline, WU context, constraints
-- Recovery mechanisms are complex and vendor-specific
-- Prevention (fresh agent) is simpler and more reliable than recovery
+If a trigger fires but you believe an exception applies, check §1.1 (docs-only), §1.2 (shallow multi-file), or §1.4 (review/audit). If your WU qualifies:
 
-**This is not failure—it's disciplined execution.** Each agent session makes bounded progress and leaves clear artifacts for the next session.
+1. Document the justification in WU notes (required, not optional).
+2. Name the exception and explain why it applies.
+3. Watch for the degradation symptoms above.
+4. If symptoms appear, checkpoint and spawn fresh regardless of the exception — exceptions cover sizing thresholds, not cognitive ones.
 
 ---
 
-## 6. Quick Reference
+## 5. Quick Reference
 
 | Scenario                                         | Strategy            | Action                                                        |
 | :----------------------------------------------- | :------------------ | :------------------------------------------------------------ |
@@ -587,7 +649,7 @@ pnpm wu:brief --id WU-XXX --client <client>
 
 ---
 
-## 7. Case Study: WU-1215 (Learning from Failure)
+## 6. Case Study: WU-1215 (Learning from Failure)
 
 **WU:** Refactor wu-done.mjs 768-line `main()` function
 
@@ -617,7 +679,7 @@ This is a case study in genuinely non-atomic work. Do not generalize it into "mu
 
 ---
 
-## 8. Related Documentation
+## 7. Related Documentation
 
 - [agent-safety-card.md](./agent/onboarding/agent-safety-card.md) — Quick reference safety thresholds
 - [agent-invocation-guide.md](./agent/onboarding/agent-invocation-guide.md) — Orchestrator-worker patterns
@@ -627,16 +689,18 @@ This is a case study in genuinely non-atomic work. Do not generalize it into "mu
 
 ---
 
-**Version:** 1.6 ({{DATE}})
+**Version:** 1.8 ({{DATE}})
 **Last Updated:** {{DATE}}
 **Contributors:** Claude (research), Codex (pragmatic framing), Gemini (trigger enforcement)
 
 **Changelog:**
 
+- v1.8 ({{DATE}}): Re-rooted §2 decision tree at the cohesion check (so it now matches the prose in §1.0/§1.0.1 instead of starting at the tool-call branch). Merged former §4 (Context Safety Triggers) and §5 (Spawn Fresh) into a single §4 "Context Safety and Handoff" — duplicated trigger lists and handoff protocols collapsed. Added §1.0.2 "How to Estimate" with concrete pre-claim heuristics (read entry point, grep call sites, count test files, multiplier rule, gates buffer). Added review-WU rows to §1.3 examples summary. Removed the undefined "Tier 2 Context" parenthetical from the §1 matrix. Renumbered §6 Quick Reference → §5, §7 Case Study → §6, §8 Related Documentation → §7. Sorted this changelog reverse-chronological. (WU-2676)
+- v1.7 ({{DATE}}): Added section 1.5 (Pre-Phase Audit / No WU) — orchestrator inline investigation pattern distinct from §1.4 Review WUs. Renumbered Sizing Contract to §1.6. Emerged from INIT-058 Wave 2 orchestration (WU-2675).
 - v1.6 ({{DATE}}): Added section 1.4 (Review, Audit, and Exploration WUs) addressing multi-agent parallelism for read-heavy WUs. Fixes the "multiple passes" problem where agents under-scope review WUs. Deleted stale CLI docs shadow copy missed by WU-2398. Fixed broken relative links. Renumbered sizing contract to section 1.5.
 - v1.5 ({{DATE}}): Consolidated from two files into single canonical doc. Added consolidation checklist (1.0.1) to counter systematic agent over-splitting. Strengthened anti-patterns with additional examples.
-- v1.3 ({{DATE}}): Added sizing contract section (1.4) documenting tooling-backed enforcement via `sizing_estimate` metadata, advisory warnings in `wu:create`, and `--strict-sizing` mode in `wu:brief` (WU-2141, WU-2143).
 - v1.4 ({{DATE}}): Tightened anti-fragmentation guidance. Complex and oversized heuristics now force a cohesion re-check before decomposition, added explicit anti-patterns for backend/tests/docs micro-splitting, and replaced `/clear`-centric recovery advice with checkpoint + `wu:brief` handoff guidance.
+- v1.3 ({{DATE}}): Added sizing contract section (1.4) documenting tooling-backed enforcement via `sizing_estimate` metadata, advisory warnings in `wu:create`, and `--strict-sizing` mode in `wu:brief` (WU-2141, WU-2143).
 - v1.2 ({{DATE}}): Added documentation-only exception (section 1.1), shallow multi-file exception with single-session override criteria (section 1.2), and examples summary table (section 1.3). Updated deviation protocol to reference exceptions.
 - v1.1 ({{DATE}}): Removed time-based estimates (hours); replaced with tool-call and context-budget heuristics. Agents operate in context windows, not clock time.
 - v1.0 ({{DATE}}): Initial version based on WU-1215 post-mortem.

package/templates/core/ai/onboarding/agent-invocation-guide.md.template

@@ -8,7 +8,7 @@ Use this document when:
 
 - Generating delegation briefs for sub-agents or parallel WUs
 - Recording `wu:brief` evidence when implementing a WU in the current session
-- Writing orchestrator prompts
+- Reviewing orchestration handoff artifacts
 - Starting a new session after `/clear`
 - Coordinating multi-wave initiatives
 
@@ -23,7 +23,7 @@ Load context in this order to reduce "lost in the middle" failures:
 3. `lumenflow-agent-capsule.md` — constraints + governance
 4. WU YAML — current task spec
 5. Task instructions — what to do
-6. **Critical Constraints block** — append at the end (see below)
+6. **Critical Constraints block** — use only for non-canonical prompts (see below)
 
 **Tier guidance:**
 
@@ -110,7 +110,7 @@ It also stores **brief attestation metadata** (SHA-256 prompt hash, client, time
 
 It does **not** by itself prove pickup or execution. Pickup/execution confirmation comes from lifecycle evidence (claim/completion events, checkpoints, signals, and final `wu:done`).
 
-`wu:done` now enforces, for initiative-governed and explicitly delegated WUs:
+For initiative-governed and explicitly delegated WUs, `wu:done` enforces:
 
 - Delegation lineage exists
 - Claim-time pickup evidence exists
@@ -133,9 +133,21 @@ pnpm wu:brief --id WU-XXX --client <client>
 
 ---
 
-## 3) Spawn Prompt Structure (Recommended)
+## 3) Canonical Handoff Surfaces
 
-Use this structure for sub-agent prompts:
+Use the canonical handoff output verbatim when you have it:
+
+- `pnpm wu:brief --id WU-XXX --client <client>` for self-implementation
+- `pnpm wu:delegate --id WU-XXX --parent-wu <P> --client <client>` for auditable delegation
+- `pnpm orchestrate:initiative ... --print-handoffs` when you need orchestration to replay stored
+  handoff artifacts inline for manual copy/paste
+
+These surfaces already assemble the objective, scope, code paths, tests, recovery guidance,
+constraints block, and evidence metadata. Do not prepend or append a second wrapper block around
+them.
+
+If you are building a fully custom or experimental prompt outside those canonical surfaces, use
+this structure:
 
 1. **Objective** — clear, single outcome
 2. **Scope** — what is in/out of scope
@@ -143,7 +155,7 @@ Use this structure for sub-agent prompts:
 4. **Tests/Gates** — required checks
 5. **Progress Artifacts** — checkpoints, commits, signals
 6. **Recovery** — what to do if blocked
-7. **Critical Constraints** — append at the end
+7. **Critical Constraints** — include only if the canonical renderer is not in use
 
 ---
 
@@ -174,9 +186,13 @@ This ensures documentation WUs do not receive TDD directives, and methodology-sp
 
 ---
 
-## 4) Append These Constraints at the End (Mandatory)
+## 4) Manual Fallback Constraints (Non-Canonical Prompts Only)
+
+Use this block only when you are assembling a prompt outside `wu:brief`, `wu:delegate`, or the
+stored orchestration handoff artifacts. If you are using one of those canonical surfaces, do not
+append this block again.
 
-Paste this block at the end of every multi-agent prompt:
+When needed, paste this block at the end of the custom prompt:
 
 ```
 CRITICAL CONSTRAINTS (append at end, do not omit):
@@ -206,6 +222,8 @@ After spawning:
 
 - Monitor with `pnpm mem:inbox --since 30m`
 - Use `pnpm mem:ready --wu WU-XXX` for handoff status
+- Use the stored orchestration handoff artifact path or `--print-handoffs` if a human needs the
+  inline payload; do not rebuild the handoff text locally
 
 ---