@3fn/core 13.0.0 → 14.0.0

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]_
@@ -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
 
@@ -2220,7 +2245,7 @@ Developers can now:
 
 **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 Analysis**: The release tool (`src/tools/release/`) scans summary documents via git log to generate release notes. Release analysis runs post-merge on `main` (non-blocking); run `npm run release:analyze` for on-demand detail.
 
 **Format Template**:
 
@@ -2400,9 +2425,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.
+
+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.
 
-**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.
+**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 +2464,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,18 +2489,18 @@ 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 +2672,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 +2718,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.

package/governance/Rosetta-System-Architecture.md

@@ -631,16 +631,16 @@ The exemption is **not silent**: each exempt subsystem has a **paired boot/smoke
 
 ```
 # Get this document
-get_document_full({ path: ".kiro/steering/Rosetta-System-Architecture.md" })
+get_document_full({ path: "rosetta-system-architecture" })
 
 # Get specific sections
-get_section({ path: ".kiro/steering/Rosetta-System-Architecture.md", heading: "Token Pipeline Architecture" })
-get_section({ path: ".kiro/steering/Rosetta-System-Architecture.md", heading: "OKLCH Color Pipeline" })
-get_section({ path: ".kiro/steering/Rosetta-System-Architecture.md", heading: "Component Token Integration" })
-get_section({ path: ".kiro/steering/Rosetta-System-Architecture.md", heading: "Subsystem Entry Points Summary" })
+get_section({ path: "rosetta-system-architecture", heading: "Token Pipeline Architecture" })
+get_section({ path: "rosetta-system-architecture", heading: "OKLCH Color Pipeline" })
+get_section({ path: "rosetta-system-architecture", heading: "Component Token Integration" })
+get_section({ path: "rosetta-system-architecture", heading: "Subsystem Entry Points Summary" })
 
 # For token creation governance and guides
-get_section({ path: ".kiro/steering/Token-Governance.md", heading: "Token Creation Guides" })
+get_section({ path: "token-governance", heading: "Token Creation Guides" })
 ```
 
 ---

package/governance/Test-Behavioral-Contract-Validation.md

@@ -14,7 +14,7 @@ description: Framework for validating behavioral contracts across web, iOS, and
 **Scope**: cross-project
 **Layer**: 2
 **Relevant Tasks**: component-development, cross-platform-validation, testing
-**Last Reviewed**: 2026-01-02
+**Last Reviewed**: 2026-07-15
 
 ---
 
@@ -210,13 +210,11 @@ pressable_validation_checklist:
     - [ ] Click/tap triggers action
     - [ ] Enter key triggers action (web)
     - [ ] Space key triggers action (web)
-    - [ ] Action NOT triggered when disabled
     
   state_validation:
     - [ ] Default state is correct
     - [ ] Hover state appears (desktop only)
     - [ ] Pressed/active state appears
-    - [ ] Disabled state prevents interaction
     
   outcome_validation:
     - [ ] onPress callback is invoked
@@ -226,7 +224,6 @@ pressable_validation_checklist:
     
   accessibility_validation:
     - [ ] role="button" or semantic button (web)
-    - [ ] aria-disabled when disabled (web)
     - [ ] Screen reader announces button
     
   cross_platform_validation:
@@ -305,38 +302,49 @@ error_state_validation_checklist:
     - [ ] Android: TalkBack announces error
 ```
 
-### Disabled State Contract Validation
+### Disabled State Exclusion Guard Validation
 
-**Contract Definition**: Prevents interaction when disabled
+**Provenance**: As of the 2026-07-15 adjudication (`.kiro/issues/button-cta-disabled-state-adjudication.md`), the no-disabled-states philosophy holds corpus-wide with **zero exceptions** — Button-CTA was the last component carrying `state_disabled`, and it has been removed. No component in the corpus may declare a disabled state as a behavioral contract, and `blend.disabledDesaturate` (along with the other disabled-state blend wrappers) is deprecated. Validation for this contract type has inverted: rather than validating that a disabled state behaves correctly, validation now confirms a disabled state does **not exist** and cannot be reintroduced.
+
+**Contract Definition**: Component has no disabled state. Interaction affordances are always active; unavailable actions are handled by not rendering the component (or by another contract — see Philosophy Alternatives below), never by disabling it in place.
+
+**Rationale**: DesignerPunk does not support disabled states for usability and accessibility reasons. If an action is unavailable, the component should not be rendered.
 
 ```yaml
-disabled_state_validation_checklist:
-  trigger_validation:
-    - [ ] Disabled state activates when disabled=true
-    - [ ] Disabled state deactivates when disabled=false
-    
-  state_validation:
-    - [ ] Component cannot receive focus
-    - [ ] Component cannot be clicked/tapped
-    - [ ] Visual styling indicates disabled state
-    - [ ] Cursor shows not-allowed (web)
-    
-  outcome_validation:
-    - [ ] onPress/onChange NOT called when disabled
-    - [ ] Desaturated colors applied (blend.disabledDesaturate)
-    - [ ] Component is visually distinct from enabled
-    
-  accessibility_validation:
-    - [ ] aria-disabled="true" set (web)
-    - [ ] Disabled state communicated to AT
-    - [ ] Component removed from tab order (web)
-    
+disabled_state_exclusion_guard_checklist:
+  schema_validation:
+    - [ ] state_disabled is declared under contracts.yaml `excludes:` (NOT under `contracts:`)
+    - [ ] Excludes entry carries the standardized reason: "DesignerPunk does not support disabled states for usability and accessibility reasons. If an action is unavailable, the component should not be rendered."
+
+  api_surface_validation:
+    - [ ] Component exposes no disabled prop/property
+    - [ ] Component does not list `disabled` in observedAttributes (web) or an equivalent observed-attribute mechanism per platform
+
+  ignored_input_validation:
+    - [ ] A consumer-set disabled attribute is ignored — not forwarded to internal/shadow elements
+    - [ ] No disabled-styling class is applied when a disabled attribute is set
+    - [ ] No aria-disabled (or platform-equivalent) attribute is applied when a disabled attribute is set
+    - [ ] Press/activation still fires normally even when a consumer sets a disabled attribute
+
+  rendered_output_validation:
+    - [ ] No disabled attribute is ever rendered on any platform
+    - [ ] No aria-disabled attribute is ever rendered on any platform
+    - [ ] No platform-equivalent disabled semantic (e.g., Android `enabled = false`, iOS `.disabled()`) is ever applied
+
   cross_platform_validation:
-    - [ ] Web: aria-disabled and tabindex=-1
-    - [ ] iOS: .disabled() modifier applied
-    - [ ] Android: enabled = false in semantics
+    - [ ] Web: no disabled/aria-disabled attribute, no tabindex=-1 for disabled reasons
+    - [ ] iOS: no `.disabled()` modifier applied
+    - [ ] Android: no `enabled = false` in semantics
 ```
 
+**Philosophy Alternatives** — when a spec's design outline reaches for "disabled," redirect to the pattern that actually fits:
+
+- **In-flight async action** → `state_loading` (component shows a loading/busy state; the action remains conceptually available, just pending)
+- **Form input momentarily invalid** → validate-on-press / validate-on-submit (surface the error, do not disable the control)
+- **Action genuinely unavailable** → do not render the component/action at all
+
+**Mirror reference**: `src/components/core/Button-CTA/__tests__/ButtonCTA.test.ts`, `describe('No Disabled State (philosophy exclusion)')` — the canonical exclusion-guard test block this checklist is derived from.
+
 ### Hover State Contract Validation
 
 **Contract Definition**: Visual feedback on hover (desktop only)
@@ -347,7 +355,6 @@ hover_state_validation_checklist:
     - [ ] Hover state triggers on mouse enter
     - [ ] Hover state clears on mouse leave
     - [ ] Hover state NOT shown on touch devices
-    - [ ] Hover state NOT shown when disabled
     
   state_validation:
     - [ ] Background color changes on hover

package/governance/Test-Failure-Audit-Methodology.md

@@ -8,7 +8,7 @@ description: Reusable methodology for conducting test failure audits — workflo
 # Test Failure Audit Methodology
 
 **Date**: 2025-12-26
-**Last Reviewed**: 2025-12-26
+**Last Reviewed**: 2026-07-08
 **Purpose**: Reusable methodology guidance for conducting test failure audits, including workflow steps, pattern identification, and lessons learned from Specs 025/026/029
 **Organization**: process-standard
 **Scope**: cross-project