@3fn/core 13.0.0 → 14.1.0

package/governance/Process-Orchestration-Model-Selection.md

@@ -0,0 +1,92 @@
+---
+id: process-orchestration-model-selection
+inclusion: manual
+name: Process-Orchestration-Model-Selection
+description: How an orchestrating agent picks a model tier for delegated subagent work — match the tier to the task's cognitive demand (decide vs. implement) weighted by blast radius, default to inheriting the session model, and always independently verify subagent output. Load when delegating work to subagents or deciding which model a subagent should run.
+---
+
+# Orchestration Model Selection
+
+**Date**: 2026-07-07
+**Last Reviewed**: 2026-07-09
+**Purpose**: How an orchestrating agent chooses the model tier for delegated subagent work, and why verification — not the tier — is the guardrail (content AND placement)
+**Organization**: process-standard
+**Scope**: cross-project
+**Layer**: 2
+**Relevant Tasks**: agent-architecture, general-task-execution
+
+---
+
+## The Policy (one sentence)
+
+**Match the model tier to the task's cognitive demand — *decide* vs. *implement*, weighted by *blast radius* — default to inheriting the session model, and always independently verify subagent output. Delegate-then-verify is the guardrail, not the tier.**
+
+## The Axis: decide vs. implement
+
+The question is never "is this a subagent?" It is "what cognition does this task demand?"
+
+- **Implement** — carry out an already-settled design, contract, or spec: component/token/test authoring against a fixed model, scripted or mechanical multi-file sweeps with a defined pattern, ports/transcriptions, measurements and probes, applying a ratified ballot. The hard calls are made; the work is faithful execution.
+- **Decide** — produce architecture, make a consequential or hard-to-reverse call, weigh cross-cutting tradeoffs, or reason through multiple failure modes: spec design and review rounds, ballot drafting, incorporation/adjudication passes, choosing a system boundary or a new cross-component contract.
+
+**Weight by blast radius.** A wrong *implementation* detail is usually local and cheap to fix under verification. A wrong *architectural* call propagates and is costly to unwind — that is exactly where marginal model capability earns its cost, and exactly the wrong place to chase savings.
+
+## The tiering rule
+
+- **Implement against a settled design/contract/spec → the cheaper capable tier** (currently Sonnet). Bias toward it for concrete work: on Spec 121 the cheaper tier was *diligent*, not merely adequate — it caught real edge cases (a comma-tokenizer bug, an empty-owner schema gap, a latent import-time side effect) rather than silently papering over them.
+- **Decide → the higher tier** (currently Opus).
+- **The main orchestration loop stays top-tier.** Synthesis, cross-checking subagent output, and human-facing judgment are the highest-leverage cognition in the session; do not downgrade the loop that verifies everything else.
+
+## The default: inherit the session model
+
+When the orchestrator does not specify a tier, a subagent **inherits the session model**. Agents carry **no per-agent default tier** — the tier is a property of the *task*, chosen at delegation, not a fixed attribute of the agent (the same agent does implement-work on one task and decide-work on another).
+
+Inherit is the right default because it **fails expensive, not wrong**: forgetting to specify runs the task at the orchestrator's own tier — over-provisioned for cheap work (a *cost* failure: visible in spend and session limits, self-correcting) rather than under-powered for consequential work (a *quality* failure: silent, shipped). But inherit is **silent in both directions**, so it is only safe alongside the always-visible calibration rule:
+
+- **Calibrate bidirectionally relative to the session model** — *downgrade* for implementation, *upgrade* for a decide task. Do not assume inherit is safe because the session is usually top-tier: under a cheaper session, a forgotten decide task would silently under-power.
+- Omitting the tier is a decision, not a non-decision. Make it consciously.
+
+## The real guardrail: delegate-then-verify
+
+**The safety mechanism is independent verification by the main loop, NOT the model tier.** Every subagent's output is re-checked before it is trusted: re-run the relevant tests and type-check, read the actual diff, spot-check against the contract. That review layer is what catches problems — including from capable tiers (a subagent once wrote a contrast *ratio* into a field expecting a color *value*; the main-loop review caught it, not the tier). The rule holds regardless of which tier ran the work: a higher tier is never a substitute for verifying; a cheaper tier under verification is safe *because* it is verified.
+
+**Verification covers placement, not just content.** When you delegate a **file edit**, the check is two-part: the content is correct AND the edit landed **where you intended** — in the intended working tree, on the intended branch. A subagent can silently act on a *different* working tree than you meant and report success anyway, because relative paths resolve from *its* working directory, not yours. Defend against it on both ends: **hand the subagent absolute paths to the intended tree** when you delegate, and **after it reports done, confirm the change is where you expect** (`git status`/`git diff` in the intended tree, or read the file at its absolute path) before you trust or commit it. This extends the content-verification rule above to *placement*; a "done" report is a claim about content, never a guarantee about location.
+
+- **Claude Code symptom (harness-specific).** CC nests worktrees *inside* the repo (`.claude/worktrees/<name>/`), so upward path or module resolution from a subagent (`../../../`) can cross the worktree boundary into the **parent repo** — a delegated edit lands on the parent-repo copy instead of the worktree branch, esbuild reads the parent's `package.json`, etc. Observed 3× in one session. The placement check above is the mitigation; the durable fix is upstream (place worktrees as *siblings* of the repo, not nested — a Claude Code harness-behavior request), which this guardrail does not own. Other harnesses carry this symptom note only if they reproduce the nesting condition.
+
+## Escalation, not default-when-unsure
+
+The higher tier is an **escalation with a concrete trigger**, not a fallback for uncertainty. Reflexively reaching for it "to be safe" quietly gives back the cost savings without a proven need. Escalate on a concrete signal — the task requires *choosing between non-obvious tradeoffs* or *reasoning through multiple failure modes* — not on a vague sense that the work is important.
+
+## The load-bearing qualifier
+
+The way to keep delegated work in the cheaper tier is to **front-load the architecture into the spec** so the subagent *implements a decided design*. Across Spec 121 the cheaper tier was safe because the hard calls were made in the requirements/design phase *before* any subagent ran (one task was typed "Architecture," yet its decisions were already settled in the spec — implementation in practice). The corollary is the trigger: **if a subagent must *make* the architectural call** — an open module-resolution strategy, a new cross-MCP contract, a system boundary — **that is the higher tier regardless of it being "a subagent."** Task **Type** is a *prior, not the answer*: an Architecture-typed task whose design is genuinely settled implements at the cheaper tier, and an Implementation-typed task that still requires a consequential call is a decide task — confirm the design is actually settled before downgrading, rather than reading the tier off the Type label.
+
+## Recording the tier per task (spec-driven work)
+
+Spec-driven work has a natural place to pre-record the judgment: the task's `**Agent**:` metadata in `tasks.md`, set at formalization, when the author knows whether the architecture is settled. Format: `**Agent**: <agent> (<Model>)` (e.g. `Thurgood (Sonnet)`; cross-domain `Agent A (Model) + Agent B (Model)`) — the model rides the *task*, so the same agent may carry different models on different tasks. The recorded model is **advisory as of authoring**: the executing orchestrator re-checks it against the current model lineup (delegate-then-verify is the net). It jumpstarts calibration even if this policy is not loaded — the concrete name is actionable without the policy's vocabulary. See `Process-Spec-Planning.md` § "Agent Assignment" for the field rule. This is a *reinforcement* for spec work, not a replacement for the always-visible rule, which covers all orchestration.
+
+## Why the tier matters (cost rationale)
+
+Capability tiers are priced differently (higher tier ≈ higher $/token on both input and output; ordering as of 2026-07: Opus > Sonnet > Haiku). Two consequences: a *minor-version* downgrade within a tier saves nothing (same price) — the real lever is **tier**, not version; and running a cheaper *subagent* tier than the orchestrator also **preserves the main-loop prompt cache**, whereas switching the *main* model mid-conversation would invalidate it.
+
+## Still calibrating (this section is expected to move)
+
+The concrete tier assignments track the current model lineup and **will change** as models change. Recalibration lands *here*, not in the policy above.
+
+- Current mapping (set 2026-07-06/07, Fable-era): **Sonnet** = implementation against settled specs; **Opus** = the decide tier (design, review, adjudication, ballot drafting); **Fable** = the main orchestration loop only.
+- Treat specific tier *names* as the current instantiation of the *policy*, not as the policy. When the lineup shifts, re-map the names; the decide-vs-implement axis and delegate-then-verify guardrail are the stable parts.
+
+## Per-harness field mechanics (mechanics, not policy)
+
+*How* an orchestrator selects a tier is harness-specific; the policy above is not.
+
+- **Claude Code**: the subagent's `model:` frontmatter (or the Agent-tool `model` param) accepts a tier alias (`sonnet` / `opus` / `haiku` / `fable`), a full model ID, or `inherit`. **Omitting it means `inherit` — the session's current model.** Under a top-tier session, omission silently runs every subagent top-tier; set `model:` explicitly for cheaper work. Generated agent definitions carry **no** `model:` — they inherit by design; the tier is chosen per invocation.
+- **Kiro**: model-selection mechanism may differ and is not characterized here. Document it when a Kiro orchestrator needs it; the policy is identical across harnesses.
+
+## MCP Query
+
+```
+get_document_full({ path: "process-orchestration-model-selection" })
+get_section({ path: "process-orchestration-model-selection", heading: "The tiering rule" })
+get_section({ path: "process-orchestration-model-selection", heading: "The default: inherit the session model" })
+```

package/governance/Process-Spec-Planning.md

@@ -9,7 +9,7 @@ description: Standards for creating spec documents — requirements format (EARS
 
 **Date**: 2025-01-10
 **Updated**: October 20, 2025
-**Last Reviewed**: 2025-12-15
+**Last Reviewed**: 2026-07-05
 **Purpose**: Standards for creating requirements, design, and task documents for feature specifications
 **Organization**: process-standard
 **Scope**: cross-project
@@ -35,7 +35,7 @@ description: Standards for creating spec documents — requirements format (EARS
 
 1. ✅ **Component-Templates** - Query "Behavioral Contract Templates" section for:
    - Interaction contracts (Focusable, Pressable, Hoverable)
-   - State contracts (Disabled, Error, Success, Loading)
+   - State contracts (Error, Success, Loading)
    - Accessibility contracts (Focus Ring, Reduced Motion, Screen Reader Hidden)
    - Visual contracts (Pressed State, Float Label Animation)
 
@@ -46,8 +46,8 @@ description: Standards for creating spec documents — requirements format (EARS
 
 **MCP Queries**:
 ```
-get_section({ path: ".kiro/steering/Component-Templates.md", heading: "Behavioral Contract Templates" })
-get_section({ path: ".kiro/steering/Component-Quick-Reference.md", heading: "Naming Convention" })
+get_section({ path: "component-family-templates", heading: "Behavioral Contract Templates" })
+get_section({ path: "component-quick-reference", heading: "Naming Convention" })
 ```
 
 **Why**: Component specs need behavioral contracts for interaction states, accessibility patterns, and platform-specific behaviors that generic spec guidance doesn't cover.
@@ -59,8 +59,8 @@ get_section({ path: ".kiro/steering/Component-Quick-Reference.md", heading: "Nam
 
 ### WHEN Creating Tasks Document THEN Read:
 1. ✅ **Tasks Document Format** (MUST READ)
-2. ✅ **Task Type Classification System** (MUST READ - understand Setup/Implementation/Architecture)
-3. ✅ **Reference: Task Type Definitions** (`.kiro/steering/Process-Task-Type-Definitions.md` - if unclear on classification)
+2. ✅ **Task Type Classification System** (MUST READ - understand Setup/Implementation/Architecture/Documentation)
+3. ✅ **Reference: Task Type Definitions** (`governance/Process-Task-Type-Definitions.md` - if unclear on classification)
 4. ✅ **Spec Workflow: Phase 3** (scroll to Spec Workflow section)
 5. ❌ **SKIP**: Detailed validation tiers, detailed documentation tiers, rationale sections
 
@@ -366,17 +366,17 @@ During spec formalization (design-outline → requirements.md), Thurgood will id
   - [Path to completion doc]
 
   - [ ] [N.1] [Sub-task Title]
-    **Type**: [Setup | Implementation | Architecture]
+    **Type**: [Setup | Implementation | Architecture | Documentation]
     **Validation**: [Tier 1: Minimal | Tier 2: Standard | Tier 3: Comprehensive]
-    **Agent**: [Agent name]
+    **Agent**: [Agent name (Model)]
     - [Implementation step 1]
     - [Implementation step 2]
     - _Requirements: [Requirement IDs]_
 
   - [ ] [N.2] [Sub-task Title]
-    **Type**: [Setup | Implementation | Architecture]
+    **Type**: [Setup | Implementation | Architecture | Documentation]
     **Validation**: [Tier 1: Minimal | Tier 2: Standard | Tier 3: Comprehensive]
-    **Agent**: [Agent name]
+    **Agent**: [Agent name (Model)]
     - [Implementation step 1]
     - [Implementation step 2]
     - _Requirements: [Requirement IDs]_
@@ -403,8 +403,8 @@ During spec formalization (design-outline → requirements.md), Thurgood will id
 **Completion Documentation**:
 - Two documents per primary task:
   - Detailed: `.kiro/specs/[spec-name]/completion/task-[N]-parent-completion.md` (comprehensive internal documentation)
-  - Summary: `docs/specs/[spec-name]/task-[N]-summary.md` (concise public-facing summary, used by release tool)
-- Detailed docs preserve comprehensive knowledge; summary docs trigger hooks and serve as release notes
+  - Summary: `docs/specs/[spec-name]/task-[N]-summary.md` (concise public-facing summary — source material for hand-authored release notes)
+- Detailed docs preserve comprehensive knowledge; summary docs serve as release-note source material
 
 **Sub-tasks**:
 - Focus on implementation steps
@@ -427,6 +427,9 @@ During spec formalization (design-outline → requirements.md), Thurgood will id
 - Indicates the optimal agent based on domain boundaries (Ada: tokens/pipeline, Lina: components/tests, Thurgood: governance/specs)
 - For cross-domain tasks, use `Agent A + Agent B` with rationale
 - Agent field is a recommendation — Peter may route differently based on context
+- **Recommended model rides the Agent field, per task**: `**Agent**: Thurgood (Sonnet)` — agent, then model in parentheses. The model is the *task's* tier, not the agent's — the same agent may carry different models on different tasks (implement-work → the cheaper tier; a decide task → the higher tier). Cross-domain: `Agent A (Model) + Agent B (Model)`.
+- The model is a **concrete name and advisory as of authoring, never a binding** — the executing orchestrator re-checks it against the current model lineup (delegate-then-verify is the net). It jumpstarts tier calibration even when the always-loaded cue is absent; a stale or rote stamp is re-derived at delegation, never treated as permission to skip calibration.
+- When the recommended tier **diverges from what the task's Type implies** (an Architecture task run at the cheaper tier because design already settled the calls, or the reverse), add a one-line reason. See `process-orchestration-model-selection` for the decide-vs-implement axis.
 - Parent tasks use Type: Parent with Tier 3: Comprehensive validation
 - Type determines which validation tier and documentation tier to apply
 
@@ -436,7 +439,7 @@ During spec formalization (design-outline → requirements.md), Thurgood will id
 
 **Contract Traceability:**
 - Every platform implementation subtask in a component spec must include `_Contracts:` lines listing the contracts that subtask satisfies
-- Format: `_Contracts: interaction_focusable, interaction_pressable, state_disabled_`
+- Format: `_Contracts: interaction_focusable, interaction_pressable, state_loading_`
 - This maps implementation work to behavioral guarantees, enabling review and audit
 
 ### Task Format Examples
@@ -466,8 +469,7 @@ During spec formalization (design-outline → requirements.md), Thurgood will id
   
   **Post-Completion:**
   - Mark complete: Use `taskStatus` tool to update task status
-  - Commit changes: `./.kiro/hooks/commit-task.sh "Task 1 Complete: Build System Foundation"` (runs release analysis automatically)
-  - Verify: Check GitHub for committed changes
+  - Complete the parent on its unit branch: `./.kiro/hooks/complete-task.sh "Task 1 Complete: Build System Foundation (spec)"`. If this parent IS its own merge unit → the tooling opens the PR; report the URL and STOP. If it is one of several in a declared multi-parent unit → docs commit on the branch (no PR); the PR opens at unit completion. **Accepted when the UNIT merges.**
 
   - [ ] 1.1 Create directory structure
     **Type**: Setup
@@ -569,8 +571,7 @@ During spec formalization (design-outline → requirements.md), Thurgood will id
   
   **Post-Completion:**
   - Mark complete: Use `taskStatus` tool to update task status
-  - Commit changes: `./.kiro/hooks/commit-task.sh "Task 5 Complete: Token Generation System"` (runs release analysis automatically)
-  - Verify: Check GitHub for committed changes
+  - Complete the parent on its unit branch: `./.kiro/hooks/complete-task.sh "Task 5 Complete: Token Generation System (spec)"`. If this parent IS its own merge unit → the tooling opens the PR; report the URL and STOP. If it is one of several in a declared multi-parent unit → docs commit on the branch (no PR); the PR opens at unit completion. **Accepted when the UNIT merges.**
 
   - [ ] 5.1 Set up generator directory structure
     **Type**: Setup
@@ -614,7 +615,7 @@ During spec formalization (design-outline → requirements.md), Thurgood will id
 
 ### Overview
 
-The Task Type Classification System provides a three-tier approach to categorizing tasks based on their complexity, risk, and nature of work. Task types are determined during the planning phase (when creating tasks.md) and guide the appropriate level of validation and completion documentation during execution.
+The Task Type Classification System provides a structured approach to categorizing tasks based on their complexity, risk, and nature of work. Task types are determined during the planning phase (when creating tasks.md) and guide the appropriate level of validation and completion documentation during execution.
 
 This classification system enables:
 - **Objective task categorization** based on clear characteristics
@@ -622,7 +623,7 @@ This classification system enables:
 - **Proportional documentation detail** aligned with task type
 - **Consistent AI agent execution** through unambiguous task metadata
 
-### Three Task Types
+### Task Types
 
 #### Setup Tasks
 
@@ -691,6 +692,28 @@ This classification system enables:
 
 **Validation & Documentation**: Tier 3 - Comprehensive
 
+#### Documentation Tasks
+
+**Definition**: Writing work that produces or updates documentation artifacts
+
+**Characteristics**:
+- Produces or updates documentation files; no production code, test, or configuration behavior changes
+- Applies only when the *entire* output is documentation artifacts: mixed code+doc tasks are classified by the code work (Implementation/Architecture), and tooling-consumed metadata (component schemas, `component-meta.yaml`) is Implementation, not Documentation
+- Success measured by artifact existence and content acceptance criteria (SHALL/SHALL NOT where relevant)
+- No runtime risk; risk is informational (inaccuracy, staleness, broken cross-references)
+- Governance-*law* targets route through the ballot-measure model (agent drafts, Peter ratifies); spec-authorized steering updates proceed under the spec's authority; rebuild the affected MCP index after application either way
+- Validated by artifact and content checks, not test suites
+
+**Examples**:
+- Author completion and summary documentation
+- Deliver cross-spec handback or closeout notes
+- Draft ballot-measure steering proposals
+- Log deferred findings in the issues registry
+- Write or update consumer-facing guides
+- Apply spec-authorized steering-doc updates
+
+**Validation & Documentation**: Tier 1 - Minimal (default; escalate to Tier 2 - Standard only when the artifact BOTH carries SHALL/SHALL NOT contract semantics AND other specs' decisions depend on it)
+
 #### Parent Tasks
 
 **Definition**: Container tasks that encompass multiple subtasks and define overall success criteria
@@ -716,7 +739,7 @@ Task types are determined during **Phase 3: Tasks** of the spec workflow, when c
 2. **Identify task characteristics** (structural vs coding vs design work)
 3. **Assess complexity and risk** (low vs medium vs high)
 4. **Determine validation needs** (minimal vs standard vs comprehensive)
-5. **Assign task type** (Setup, Implementation, or Architecture)
+5. **Assign task type** (Setup, Implementation, Architecture, or Documentation)
 6. **Add type metadata** to task in tasks.md
 
 #### Classification Decision Examples
@@ -787,7 +810,7 @@ Document decision in tasks.md for future reference
 #### Clear Classification
 
 When task type is obvious from characteristics:
-1. Assign appropriate type (Setup, Implementation, Architecture)
+1. Assign appropriate type (Setup, Implementation, Architecture, Documentation)
 2. Add type metadata to task
 3. Proceed with task creation
 
@@ -811,7 +834,7 @@ When encountering a task pattern not covered by existing definitions:
 
 For detailed task type definitions with comprehensive examples, see:
 
-**Task Type Definitions**: `.kiro/steering/Process-Task-Type-Definitions.md`
+**Task Type Definitions**: `governance/Process-Task-Type-Definitions.md`
 
 This living document provides:
 - Detailed definitions for each task type
@@ -826,7 +849,7 @@ Task type metadata is included in the tasks.md format:
 
 ```markdown
 - [ ] [N.1] [Sub-task Title]
-  **Type**: [Setup | Implementation | Architecture]
+  **Type**: [Setup | Implementation | Architecture | Documentation]
   **Validation**: [Tier 1: Minimal | Tier 2: Standard | Tier 3: Comprehensive]
   - [Implementation step 1]
   - [Implementation step 2]
@@ -1085,7 +1108,7 @@ This document provides:
 
 ### Overview
 
-The Three-Tier Validation System aligns validation depth with task complexity and risk. Each task type (Setup, Implementation, Architecture, Parent) has a corresponding validation tier that specifies the checks required before marking a task complete.
+The Three-Tier Validation System aligns validation depth with task complexity and risk. Each task type (Setup, Implementation, Architecture, Documentation, Parent) has a corresponding validation tier that specifies the checks required before marking a task complete.
 
 This validation system ensures:
 - **Appropriate error detection** matched to task complexity
@@ -1107,18 +1130,19 @@ This validation system ensures:
 
 ### Validation Tier Definitions
 
-The three validation tiers (Minimal, Standard, Comprehensive) align with task types (Setup, Implementation, Architecture/Parent). Each tier specifies the required checks before marking a task complete.
+The three validation tiers (Minimal, Standard, Comprehensive) align with task types (Setup/Documentation, Implementation, Architecture/Parent). Each tier specifies the required checks before marking a task complete.
 
 **For detailed tier definitions**, including required checks, validation examples, and failure handling, query Task-Type-Definitions via MCP:
 
 ```
-get_section({ path: ".kiro/steering/Process-Task-Type-Definitions.md", heading: "Setup Tasks" })
-get_section({ path: ".kiro/steering/Process-Task-Type-Definitions.md", heading: "Implementation Tasks" })
-get_section({ path: ".kiro/steering/Process-Task-Type-Definitions.md", heading: "Architecture Tasks" })
+get_section({ path: "process-task-type-definitions", heading: "Setup Tasks" })
+get_section({ path: "process-task-type-definitions", heading: "Implementation Tasks" })
+get_section({ path: "process-task-type-definitions", heading: "Architecture Tasks" })
+get_section({ path: "process-task-type-definitions", heading: "Documentation Tasks" })
 ```
 
 **Quick Reference**:
-- **Tier 1 (Setup)**: Syntax validation, artifact verification, basic structure check
+- **Tier 1 (Setup/Documentation)**: Syntax validation, artifact verification, basic structure check
 - **Tier 2 (Implementation)**: Syntax, functional correctness, integration, requirements compliance
 - **Tier 3 (Architecture/Parent)**: All Tier 2 checks plus design soundness, system integration, edge cases, success criteria verification
 
@@ -1220,7 +1244,7 @@ get_section({ path: ".kiro/steering/Process-Task-Type-Definitions.md", heading:
 
 ### Overview
 
-The Three-Tier Completion Documentation System aligns documentation detail with task complexity and type. Each task type (Setup, Implementation, Architecture, Parent) has a corresponding documentation tier that specifies the required sections and level of detail for completion documentation.
+The Three-Tier Completion Documentation System aligns documentation detail with task complexity and type. Each task type (Setup, Implementation, Architecture, Documentation, Parent) has a corresponding documentation tier that specifies the required sections and level of detail for completion documentation.
 
 This documentation system ensures:
 - **Appropriate documentation depth** matched to task complexity
@@ -1240,12 +1264,12 @@ This documentation system ensures:
 
 ---
 
-### Tier 1: Minimal Documentation (Setup Tasks)
+### Tier 1: Minimal Documentation (Setup and Documentation Tasks)
 
 **📖 CONDITIONAL SECTION - Read only when needed**
 
 **Load when**:
-- Documenting Setup task completion (Tier 1)
+- Documenting Setup or Documentation task completion (Tier 1)
 - Need to understand minimal documentation requirements
 - Creating completion docs for structural work
 - Need template for Setup task documentation
@@ -1261,6 +1285,7 @@ This documentation system ensures:
 
 **When to Apply**:
 - Setup tasks (directory creation, configuration files, dependency installation)
+- Documentation tasks (completion docs, handbacks, guides — Tier 1 default)
 - Low complexity, low risk work
 - Straightforward operations with clear outcomes
 
@@ -2202,25 +2227,20 @@ Developers can now:
 
 ### Parent Task Summary Documents
 
-**Purpose**: Create concise, commit-style summaries of parent task completion that serve as release note content for the release tool.
+**Purpose**: Create concise, commit-style summaries of parent task completion that serve as source material for hand-authored release notes.
 
 **Location**: `docs/specs/[spec-name]/task-N-summary.md`
 
 **When to Create**: After completing a parent task and writing detailed completion documentation in `.kiro/specs/[spec-name]/completion/task-N-parent-completion.md`
 
-**Hook Limitation**: Kiro IDE's `fileCreated` and `fileSaved` hooks only trigger for manual file operations through the IDE UI, not for programmatically created files by AI agents. This requires a hybrid approach:
-- **Automatic hooks**: Work for manually created/edited files through IDE UI
-- **Manual trigger**: Required for AI-assisted workflows after summary document creation
-
-**Rationale**: 
-- **Hook Triggering**: The `.kiro/` directory is filtered from Kiro IDE's file watching system, preventing hooks from triggering on files created there. Summary documents in `docs/specs/` directory enable automatic release detection for manual file operations.
-- **Dual Purpose**: Summary documents serve both as hook triggers and as concise, public-facing release note content.
+**Rationale**:
+- **Dual Purpose**: Summary documents are the concise, public-facing record of each parent task — the source material the release recipe reads when authoring release notes.
 - **Clear Separation**: Detailed completion docs (internal knowledge preservation) remain in `.kiro/`, while summaries (public-facing) live in `docs/`.
-- **Hybrid Approach**: Automatic hooks for manual edits, manual trigger for AI workflows ensures release detection works in all scenarios.
+- *(Historical: `docs/`-placement also served a Kiro release-detection hook and its manual trigger, deleted 2026-08-12 — Q6 ballot. The public/internal split stands on its own.)*
 
 **Forward-Looking Note**: This summary document workflow applies to new specs going forward. Existing completion documents don't need changes.
 
-**Release Analysis**: The release tool (`src/tools/release/`) scans summary documents via git log to generate release notes. `commit-task.sh` runs release analysis automatically after each commit.
+**Release notes**: hand-authored per the release recipe (Release Management System) — the author derives the delta from squash titles since the last tag and reads summary docs for each change's substance. (The automated release tool was retired 2026-08-12, Q6 ballot.)
 
 **Format Template**:
 
@@ -2269,7 +2289,7 @@ Developers can now:
 - 🟡 **Ecosystem** — new tools, agents, MCPs, build system changes, or third-party integrations. Surfaced prominently.
 - 🔵 **Internal** — governance updates, process changes, infrastructure work. Included as context.
 
-When present, the release tool uses this for accurate classification. When absent, it falls back to section-based extraction. Include when your task delivers artifacts that should appear in release notes.
+When present, the release-notes author uses this for accurate classification. Include when your task delivers artifacts that should appear in release notes.
 
 **Example - Task 1 Summary**:
 
@@ -2400,9 +2420,22 @@ When creating cross-references, calculate relative paths based on the source doc
 
 ## Spec Workflow
 
-### Phase 1: Requirements
+### Phase 0: Design Outline
+
+**Current practice (standard since early 2026)**: specs begin with a design outline (`design-outline.md` in the spec directory) that explores the problem, options, and scope before any formal document is written. Recent specs (121–125) all follow this pattern.
 
-**For component development**: Consider creating a design outline before requirements to explore variants, token usage, and platform considerations. See Component Development Guide for component-specific spec methodology.
+1. Create `design-outline.md` in `.kiro/specs/[spec-name]/`
+2. Create the feedback document(s) alongside it — a single `feedback.md` or a split-by-phase `feedback/` directory (e.g., `feedback/design-outline.md`). Both structures are defined in the **Spec Feedback Protocol** (Layer 1, always loaded), which is the authority for feedback structure, stamp format (`[AGENT R#]`), directed questions, and incorporation passes
+3. Request feedback rounds from identified stakeholders; incorporate feedback into the outline body as a coherent revision (woven, not appended), recording session decisions and incorporation notes in the feedback doc
+4. Proceed to requirements only after outline feedback is incorporated and the project lead approves
+
+**STUB outlines for gated specs**: When formalization is blocked on an upstream decision, a design outline may be created as an explicit **STUB** — capturing scope, dependencies, and cross-references only, with a clear "do not formalize until [gate]" marker and no architecture decisions (which would pre-empt the upstream spec). Precedents: Specs 123 (gated on 118) and 125.
+
+**Sequential formalization gates**: requirements → design → tasks each pause for agent feedback before proceeding, unless the project lead explicitly waives the gate. See Spec Feedback Protocol § "Sequential Formalization Gate" — this document defers to it.
+
+**For component development**: the Component Development Guide adds component-specific design-outline methodology (variants, token usage, platform considerations).
+
+### Phase 1: Requirements
 
 1. Generate initial requirements based on feature idea
 2. Use EARS format for acceptance criteria
@@ -2426,7 +2459,7 @@ When creating cross-references, calculate relative paths based on the source doc
    - Assess complexity and risk (low vs medium vs high)
    - Assign task type (Setup, Implementation, or Architecture)
    - Add **Type** and **Validation** metadata to each subtask
-   - Reference **Task Type Definitions** (`.kiro/steering/Process-Task-Type-Definitions.md`) for classification guidance
+   - Reference **Task Type Definitions** (`governance/Process-Task-Type-Definitions.md`) for classification guidance
    - Prompt human for clarification if task type is ambiguous
 4. Add success criteria at primary task level
 5. Include artifacts and completion documentation paths
@@ -2451,21 +2484,20 @@ When creating cross-references, calculate relative paths based on the source doc
    - **Tier 1 (Setup)**: Minimal format - artifacts, notes, validation
    - **Tier 2 (Implementation)**: Standard format - artifacts, details, validation, requirements
    - **Tier 3 (Architecture/Parent)**: Comprehensive format - artifacts, decisions, algorithm, validation, lessons, integration
-6. **Commit changes**: Run `./.kiro/hooks/commit-task.sh "Task Name"` to commit and push
-7. Verify all validation checks passed before moving to next task
+6. **Open the task PR**: Run `./.kiro/hooks/complete-task.sh "Task Name"` — commit on the task branch, push, open the PR, report the URL, STOP
+7. The task completes at merge (Peter merges on green); required checks must pass on the PR before it is mergeable
 
 **Two Workflow Paths:**
 
 **Path A (Recommended - IDE-based with automation)**:
-- Use `taskStatus` tool → Triggers agent hooks → Auto organization → Auto release detection → Manual commit
+- Use `taskStatus` tool → Triggers agent hooks → Auto organization → Auto release detection → `complete-task.sh` (commits on the task branch; opens the unit PR at unit completion)
 - **Benefit**: Automated file organization and release detection
 - **Use when**: Working within Kiro IDE on spec tasks
 
 **Path B (Manual - Script-based)**:
-- Manual task status updates → Manual commit via script → No agent hooks triggered
+- Manual task status updates → `complete-task.sh` on the task branch → No agent hooks triggered
 - **Benefit**: Simpler, direct control
 - **Use when**: Quick fixes, non-spec work, or when agent hooks aren't needed
-- **Note**: Run `npm run release:analyze` for on-demand release analysis
 
 ---
 
@@ -2634,6 +2666,20 @@ When your spec depends on another spec, declare dependencies explicitly in the h
   - **BLOCKER**: Cannot write integration tests until ButtonCTA works in test environment
 ```
 
+#### Handoff Notes (`inbound-from-*.md`)
+
+**Current practice**: when one spec (or a named analysis) produces decisions, findings, or obligations that a different spec must consume, a handoff note is written into the receiving spec's directory:
+
+```
+.kiro/specs/[receiving-spec]/inbound-from-[source].md
+```
+
+- The source may be a spec number (`inbound-from-118.md`) or a named analysis (`inbound-from-wordpress-thesis.md`)
+- Handoff notes capture what the receiving spec must honor or evaluate during formalization — they are inputs to the design outline, not spec artifacts themselves
+- During formalization, the spec author reconciles all inbound notes into the outline and formal documents
+
+Precedents in the spec record: 118, 119, 122, 123, 124, and 125 all carry inbound handoff notes.
+
 #### When to Check Dependencies
 
 **During Requirements Phase**:
@@ -2666,7 +2712,7 @@ When a task cannot proceed due to external dependencies, mark it as blocked with
 
 ```markdown
 - [ ] X.Y Task Name
-  **Type**: [Setup | Implementation | Architecture]
+  **Type**: [Setup | Implementation | Architecture | Documentation]
   **Validation**: [Tier 1 | Tier 2 | Tier 3]
   **Status**: BLOCKED
   **Blocker**: [Spec XXX Task Y.Z] - [Specific reason]

package/governance/Process-Task-Type-Definitions.md

@@ -8,7 +8,7 @@ description: Task type definitions for the three-tier validation and documentati
 # Task Type Definitions
 
 **Date**: 2025-10-20
-**Last Reviewed**: 2025-12-15
+**Last Reviewed**: 2026-07-05
 **Purpose**: Define task types for three-tier validation and documentation system
 **Organization**: process-standard
 **Scope**: cross-project
@@ -23,7 +23,7 @@ description: Task type definitions for the three-tier validation and documentati
 
 ### WHEN Creating Tasks Document (Planning Phase) THEN Read:
 1. ✅ **Overview** (MUST READ - understand task type purpose)
-2. ✅ **All Task Type Definitions** (Setup, Implementation, Architecture)
+2. ✅ **All Task Type Definitions** (Setup, Implementation, Architecture, Documentation)
 3. ✅ **Characteristics and Examples** for each type
 4. ✅ **Validation and Documentation Tiers** for each type
 5. ❌ **SKIP**: Update History (unless encountering new patterns)
@@ -57,7 +57,7 @@ description: Task type definitions for the three-tier validation and documentati
 
 **Note**: This section intentionally uses the same heading as other steering documents because each document provides an overview of its specific system or process. This structural pattern enables consistent navigation across documentation.
 
-This document defines the three task types used in the Spec Planning Standards to determine appropriate validation depth and completion documentation detail. Task types are determined during the planning phase and guide execution practices.
+This document defines the four task types used in the Spec Planning Standards to determine appropriate validation depth and completion documentation detail. Task types are determined during the planning phase and guide execution practices. Task type also informs the **recommended model tier** for delegated work (Architecture → *decide* / higher tier; Setup / Implementation / Documentation → *implement* / cheaper tier) — see `process-orchestration-model-selection`.
 
 **Layer Context**: This is a Layer 2 (Frameworks and Patterns) document that provides reusable classification framework for spec planning. It works with Spec Planning Standards to enable consistent task type assignment across all specs.
 
@@ -302,6 +302,74 @@ Architecture tasks use comprehensive documentation to capture design decisions a
 
 ---
 
+## Documentation Tasks
+
+### Definition
+
+Documentation tasks are **writing work that produces or updates documentation artifacts** — completion documentation, cross-spec handoffs and closeout notes, issues-registry entries, consumer-facing guides, and drafts or spec-authorized updates of governance/steering content. They change what the project knows and records, not what the code does: no production code, test, or configuration behavior is modified.
+
+### Characteristics
+
+- **Artifact-producing**: Creates or updates documentation files; success is measured by artifact existence and content matching stated acceptance criteria
+- **Content acceptance criteria**: Well-formed Documentation tasks state what the artifact SHALL contain (and, where relevant, SHALL NOT contain)
+- **No runtime risk**: Cannot break builds, tests, or shipped behavior; the risk is informational — inaccuracy, staleness, broken cross-references
+- **The output decides the classification**: Documentation applies only to tasks whose *entire* output is documentation artifacts — content read by humans and agents, not executed or consumed by tooling. Two corollaries: a task that modifies code AND documentation is classified by the code work (Implementation or Architecture); and metadata artifacts consumed by tooling (component schemas, `component-meta.yaml`) are Implementation, not Documentation — writing work that changes shipped-tool behavior fails the "no configuration behavior" test
+- **Governance routing**: When the target is governance *law* (task taxonomy, process standards, steering content whose change is not already authorized by an approved spec), the task produces a *proposal* — the edit routes through the ballot-measure model (agent drafts, Peter ratifies). Steering-doc updates that an approved spec explicitly authorizes proceed under that spec's authority (precedent: Spec 102 Task 1.8; Specs 020 and 036 are entire steering-doc specs). Either way, rebuild the affected MCP index after application
+- **Artifact-based validation**: Validated by artifact and content checks (files exist, criteria met, cross-references resolve, metadata valid), not by test suites
+
+### Examples
+
+1. **Author completion documentation**
+   - Write detailed completion doc + concise summary doc for a parent task
+   - Record decisions, deferred items, and out-of-scope routing
+   (Precedent: Spec 124 Task 5)
+
+2. **Deliver a cross-spec handback or closeout note**
+   - Write a guidance note into another spec's directory with defined SHALL/SHALL NOT content
+   - Cross-reference it from the receiving spec's decision record
+   (Precedent: Spec 124 Task 6; Spec 118 Task 6)
+
+3. **Draft ballot-measure steering proposals**
+   - Draft proposed steering-doc changes with before/after text for Peter's ratification
+   (Precedent: Spec 117 Task 6.1; Spec 118 Task 5.2)
+
+4. **Log deferred findings in the issues registry**
+   - Record out-of-scope findings with rationale; mark superseded issues resolved
+   (Precedent: Spec 117 Task 6.2)
+
+5. **Write or update consumer-facing documentation**
+   - README, onboarding, and usage guides
+   (Precedent: Specs 101, 102, 077)
+
+6. **Spec-authorized steering-doc updates**
+   - Apply steering-doc changes an approved spec explicitly authorizes; rebuild the affected MCP index
+   (Precedent: Spec 102 Task 1.8; Specs 020, 036)
+
+### Validation Tier
+
+**Tier 1: Minimal (default)**
+
+Documentation tasks default to minimal validation because they carry no runtime risk and have artifact-based success criteria:
+
+- Verify all specified artifacts were created or updated
+- Verify content satisfies the task's stated success criteria
+- Verify cross-references resolve
+- For governance/steering artifacts: metadata validates (`scripts/validate-steering-metadata.js`) and the affected MCP index is rebuilt after application
+
+**Escalation to Tier 2 - Standard (planner's option)**: Escalate only when BOTH conditions hold — the artifact carries SHALL/SHALL NOT contract semantics, AND another spec's decisions depend on the artifact. The criterion is conjunctive: cross-spec dependency alone does not escalate (Spec 124 Task 6 — a gated cross-spec handback without contract semantics — stayed Tier 1), and neither does "this document is important." (Precedent for escalation: Spec 118 Tasks 5.2 and 6, which had both properties.)
+
+**What Tier 2 means for a Documentation task**: all Tier 1 checks, PLUS per-criterion verification that each stated SHALL is satisfied and each stated SHALL NOT is absent from the artifact, PLUS verification that the receiving spec's cross-reference exists and resolves. (Grounded in Spec 118 Tasks 5.2/6 practice.)
+
+### Documentation Tier
+
+**Tier 1: Minimal**
+
+Documentation tasks use minimal completion documentation:
+
+- **Artifacts Created/Updated**: List of documentation files created or changed
+- **Implementation Notes**: Brief description of what was written and any routing (ballot staging, MCP index rebuild)
+- **Validation**: Document Tier 1 validation results (or Tier 2, if escalated)
+
 ## Update History
 
 This section tracks updates to task type definitions as new patterns emerge through human-AI collaborative decision-making.
@@ -314,7 +382,7 @@ Each update should follow this format:
 ### [Date] - [Pattern Name]
 
 **Pattern**: [Brief description of the new task pattern or edge case]
-**Classification Decision**: [Setup / Implementation / Architecture]
+**Classification Decision**: [Setup / Implementation / Architecture / Documentation]
 **Rationale**: [Why this classification was chosen]
 **Decided By**: [Human name] + [AI Agent]
 **Examples**: [Specific examples of this pattern]
@@ -376,3 +444,11 @@ Each update should follow this format:
 ---
 
 *This document provides clear task type definitions with examples to enable consistent classification during spec planning and execution.*
+
+### July 5, 2026 - Documentation Task Type Ratified
+
+**Pattern**: Tasks that produce or update documentation artifacts (completion docs, cross-spec handbacks, ballot proposals, issues-registry entries, consumer docs, spec-authorized steering updates) with no production code changes.
+**Classification Decision**: Documentation (new task type)
+**Rationale**: Practice used `Type: Documentation` in 123 tasks across 23 specs while this document defined only three types; Task-Completion-Protocol (Layer 1) already enumerated four. Ratified via ballot measure (2026-07-05, from the A9 governance review; reviewed by Stacy, Ada, Lina) to reconcile law with practice. Default Tier 1 - Minimal; escalate to Tier 2 only when the artifact BOTH carries SHALL/SHALL NOT contract semantics AND other specs' decisions depend on it (precedent: Spec 118 Tasks 5.2, 6; counterexample: Spec 124 Task 6 stayed Tier 1). Classification follows the output: mixed code+doc tasks are classified by the code work; tooling-consumed metadata is Implementation.
+**Decided By**: Peter Michaels Allen + Thurgood
+**Examples**: Spec 124 Tasks 5, 6; Spec 118 Tasks 5.2, 6; Spec 117 Tasks 6.1, 6.2; Spec 102 Task 1.8; Specs 101/077 doc tasks.

package/governance/Product-Handoff-Protocol.md

@@ -143,6 +143,8 @@ During implementation, lessons accumulate from multiple sources — Leonardo's d
 
 Without this step, lessons collect but never get acted on.
 
+> **Return-edge note (Spec 125-B Req 14)**: this review is the PRODUCT-side half of the strategy→tactics→validation loop's return edge — the channel through which validation evidence feeds back into what the docs teach. The SYSTEM-side half is the monthly Civitas governance health check's recurring-required-check-failure review item (canonical source: `canonical/agents/thurgood.md`, Cadence-driven section) — the two halves name each other by design, with no new machinery. The edge's first manual exercise was the 125-B U1 pilot observation window, recorded in that spec's closeout record; neither cadence claims it anew.
+
 ### Timing
 
 **Default trigger**: After a complete feature or flow is implemented across active platforms.