@3fn/core 13.0.0 → 14.0.0

package/governance/Process-Development-Workflow.md

@@ -8,7 +8,7 @@ description: Development workflow and task completion practices — task complet
 # Development Workflow and Task Completion Practices
 
 **Date**: 2025-10-20
-**Last Reviewed**: 2026-07-03
+**Last Reviewed**: 2026-07-14
 **Purpose**: Task completion workflow and git practices for all development work
 **Organization**: process-standard
 **Scope**: cross-project
@@ -31,10 +31,10 @@ description: Development workflow and task completion practices — task complet
 5. ❌ **SKIP**: Agent Hook Dependency Chains (priming only - query MCP for details), Troubleshooting sections, Hook Integration details
 
 **MCP Queries for Detailed Guidance** (query when needed):
-- **Completion Documentation**: `get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Two-Document Workflow" })`
-- **Release Detection**: `get_section({ path: ".kiro/steering/Release Management System.md", heading: "Release Pipeline Architecture" })`
-- **File Organization**: `get_section({ path: ".kiro/steering/Process-File-Organization.md", heading: "Organization Implementation (Conditional Loading)" })`
-- **Hook Operations**: `get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Agent Hook Dependency Chains" })`
+- **Completion Documentation**: `get_section({ path: "completion-documentation-guide", heading: "Two-Document Workflow" })`
+- **Release Detection**: `get_section({ path: "release-management-system", heading: "Release Pipeline Architecture" })`
+- **File Organization**: `get_section({ path: "process-file-organization", heading: "Organization Implementation (Conditional Loading)" })`
+- **Hook Operations**: `get_section({ path: "process-hook-operations", heading: "Agent Hook Dependency Chains" })`
 
 ### WHEN Debugging Hook Issues THEN Read:
 1. ✅ **Task Completion Workflow** (context)
@@ -43,11 +43,11 @@ description: Development workflow and task completion practices — task complet
 4. ❌ **SKIP**: Spec Planning, Kiro Agent Hook Integration
 
 **MCP Queries for Detailed Guidance** (query when needed):
-- **Hook Dependency Chains**: `get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Agent Hook Dependency Chains" })`
-- **Hook Troubleshooting**: `get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Troubleshooting" })`
-- **Common Issues**: `get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Common Issues and Solutions" })`
-- **Release Detection Issues**: `get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Release Detection Not Triggering" })`
-- **Hook Best Practices**: `get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Best Practices" })`
+- **Hook Dependency Chains**: `get_section({ path: "process-hook-operations", heading: "Agent Hook Dependency Chains" })`
+- **Hook Troubleshooting**: `get_section({ path: "process-hook-operations", heading: "Troubleshooting" })`
+- **Common Issues**: `get_section({ path: "process-hook-operations", heading: "Common Issues and Solutions" })`
+- **Release Detection Issues**: `get_section({ path: "process-hook-operations", heading: "Release Detection Not Triggering" })`
+- **Hook Best Practices**: `get_section({ path: "process-hook-operations", heading: "Best Practices" })`
 
 ### WHEN Setting Up or Modifying Hooks THEN Read:
 1. ✅ **Agent Hook Dependency Chains** (priming - then query MCP for detailed guidance)
@@ -56,15 +56,15 @@ description: Development workflow and task completion practices — task complet
 4. ❌ **SKIP**: Task Completion Workflow, Quality Standards
 
 **MCP Queries for Detailed Guidance** (query when needed):
-- **Hook Dependency Chains**: `get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Agent Hook Dependency Chains" })`
-- **Hook Troubleshooting**: `get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Troubleshooting" })`
-- **Kiro Agent Hook Integration**: `get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Kiro Agent Hook Integration" })`
+- **Hook Dependency Chains**: `get_section({ path: "process-hook-operations", heading: "Agent Hook Dependency Chains" })`
+- **Hook Troubleshooting**: `get_section({ path: "process-hook-operations", heading: "Troubleshooting" })`
+- **Kiro Agent Hook Integration**: `get_section({ path: "process-hook-operations", heading: "Kiro Agent Hook Integration" })`
 
 ### WHEN Creating Completion Documentation THEN Read:
 1. ✅ **Task Completion Workflow** (quick reference section)
 2. ✅ Query **Completion Documentation Guide** via MCP for detailed guidance:
-   - `get_document_full({ path: ".kiro/steering/Completion Documentation Guide.md" })`
-   - Or specific sections: `get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Documentation Tiers" })`
+   - `get_document_full({ path: "completion-documentation-guide" })`
+   - Or specific sections: `get_section({ path: "completion-documentation-guide", heading: "Documentation Tiers" })`
 
 ---
 
@@ -72,18 +72,12 @@ description: Development workflow and task completion practices — task complet
 
 ### Recommended Process (IDE-based with Automation)
 1. **[MANUAL]** **Complete Task Work**: Implement all requirements and create specified artifacts
-2. **[MANUAL]** **Validate Implementation**: 
-   - For regular tasks: Run `npm test` (functional lanes only, timing-assertion-free; ~1 min warm)
-   - For parent tasks (default): Run `npm test` (comprehensive functional validation, ~1 min warm)
-   - For parent tasks modifying release tool: Run `npm run test:all` (~1 min — includes performance suites; the cost delta over `npm test` is seconds)
-   - For performance tasks: Run `npm run test:performance` AND `npm run test:performance:isolated` (seconds each; perf coverage is split across the two lanes — or run `npm run test:all`). Performance assertions are wall-clock-sensitive: run on an otherwise-idle machine
-   
-   > Lane semantics reworked 2026-07-03 (commit `29bba7de`; see Spec 125 design-outline addendum): default lanes are timing-assertion-free; performance coverage is split across `test:performance` + `test:performance:isolated`.
+2. **[MANUAL]** **Local validation**: the unit PR's required checks run the full functional suite at the gate; validating locally first catches failures before they block the merge. Test-command and lane selection (incl. the performance lanes and the 2026-07-03 lane-semantics note): Start Up Tasks §4–§5.
 3. **[MANUAL]** **Create Detailed Completion Document**: For parent tasks, create comprehensive completion doc at `.kiro/specs/[spec-name]/completion/task-N-parent-completion.md` (Tier 3)
 4. **[MANUAL]** **Create Summary Document**: For parent tasks, create concise summary doc at `docs/specs/[spec-name]/task-N-summary.md`
 5. **[MANUAL]** **Mark Task Complete**: Use `taskStatus` tool to update task status to "completed" when finished
-6. **[MANUAL]** **Commit Changes**: Run `./.kiro/hooks/commit-task.sh "Task Name"` to automatically commit, push, and run release analysis
-7. **[MANUAL]** **Verify on GitHub**: Confirm changes appear in repository with correct commit message
+6. **[MANUAL]** **Open the Task PR**: Run `./.kiro/hooks/complete-task.sh "Task Name"` to commit on the task branch, push, and open the PR; report the PR URL and STOP
+7. **[MANUAL]** **Merge = completion**: Peter merges on green — the merge accepts the work into `main` (no separate GitHub verification step; the merged PR is the verification). Release analysis runs post-merge on `main`.
 
 **Why use `taskStatus` tool?**
 - Triggers agent hooks for automatic file organization
@@ -100,22 +94,22 @@ description: Development workflow and task completion practices — task complet
 **For detailed guidance** on documentation tiers, naming conventions, templates, and the two-document workflow, query Completion Documentation Guide via MCP:
 
 ```
-get_document_full({ path: ".kiro/steering/Completion Documentation Guide.md" })
+get_document_full({ path: "completion-documentation-guide" })
 ```
 
 Or query specific sections:
 ```
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Two-Document Workflow" })
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Documentation Tiers" })
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Naming Conventions" })
+get_section({ path: "completion-documentation-guide", heading: "Two-Document Workflow" })
+get_section({ path: "completion-documentation-guide", heading: "Documentation Tiers" })
+get_section({ path: "completion-documentation-guide", heading: "Naming Conventions" })
 ```
 
 ### Alternative Process (Script-based without Automation)
 1. **Complete Task Work**: Implement all requirements and create specified artifacts
 2. **Manually update tasks.md**: Change task status from `[ ]` to `[x]`
-3. **Commit Changes**: Run `./.kiro/hooks/commit-task.sh "Task Name"` to automatically commit and push
-4. **Verify on GitHub**: Confirm changes appear in repository with correct commit message
-5. **[OPTIONAL]** **Release Analysis**: Run `npm run release:analyze` if you want detailed release analysis beyond what commit-task.sh provides
+3. **Open the Task PR**: Run `./.kiro/hooks/complete-task.sh "Task Name"` to commit on the task branch, push, and open the PR
+4. **Merge = completion**: Peter merges on green; the merged PR is the verification
+5. **[OPTIONAL]** **Release Analysis**: Run `npm run release:analyze` for detailed local analysis (the standing analysis runs post-merge on `main`)
 
 **When to use this approach:**
 - Quick fixes or minor changes
@@ -131,10 +125,10 @@ get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading:
 - Example: "Task 6 Complete: Strategic Framework Documentation Package"
 
 ### Git Practices
-- **Repository**: https://github.com/3fn/DesignerPunkv2
-- **Branch**: All work on `main` branch (single-branch workflow for now)
-- **Commits**: Atomic commits per task completion with descriptive messages
-- **Push**: Always push immediately after commit to maintain synchronization
+- **Repository**: https://github.com/3fn/DesignerPunk
+- **Branch**: All work on task branches (`task/<spec>-<N>-<slug>`); `main` is protected — direct pushes are rejected, admins included
+- **Commits**: Atomic commits per subtask on the branch; squash-merge yields one `main` commit per **merge unit** with the PR title as its subject (a unit is the whole spec for small specs, or a tasks.md-declared grouping for large specs — see Task-Completion-Protocol § Coherent Units)
+- **PRs**: Title = `Task <N> Complete: <Description> (<spec>)`; body carries Spec / Task / Agent / completion-doc path / validation note
 
 ## Spec Planning (Conditional Loading)
 
@@ -167,17 +161,13 @@ See **Spec Planning Standards** (`.kiro/steering/Process-Spec-Planning.md`) for
 ## Hook System Usage
 
 ### Available Tools
-- **`.kiro/hooks/commit-task.sh`**: Simple wrapper for task completion commits
-- **`.kiro/hooks/task-completion-commit.sh`**: Full automation script with message extraction
+- **`.kiro/hooks/complete-task.sh`**: Task-completion PR tooling — branch, commit, push, PR-open, URL report
 - **`.kiro/hooks/README.md`**: Complete documentation and usage examples
 
 ### Usage Examples
 ```bash
-# Standard task completion commit
-./.kiro/hooks/commit-task.sh "1. Create North Star Vision Document"
-
-# For different specs or custom task files
-./.kiro/hooks/task-completion-commit.sh path/to/tasks.md "Task Name"
+# Standard task completion — opens the task PR
+./.kiro/hooks/complete-task.sh "Task N Complete: Description (spec)"
 ```
 
 ---
@@ -195,14 +185,14 @@ Agent hooks use `runAfter` configuration to create dependency chains where hooks
 **For detailed guidance** on dependency chain behavior, troubleshooting, and best practices, query Process-Hook-Operations via MCP:
 
 ```
-get_document_full({ path: ".kiro/steering/Process-Hook-Operations.md" })
+get_document_full({ path: "process-hook-operations" })
 ```
 
 Or query specific sections:
 ```
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Agent Hook Dependency Chains" })
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Dependency Chain Behavior" })
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Best Practices" })
+get_section({ path: "process-hook-operations", heading: "Agent Hook Dependency Chains" })
+get_section({ path: "process-hook-operations", heading: "Dependency Chain Behavior" })
+get_section({ path: "process-hook-operations", heading: "Best Practices" })
 ```
 
 ---
@@ -237,15 +227,15 @@ When experiencing errors or failures during task completion, hooks not triggerin
 **For detailed troubleshooting guidance**, query Process-Hook-Operations via MCP:
 
 ```
-get_document_full({ path: ".kiro/steering/Process-Hook-Operations.md" })
+get_document_full({ path: "process-hook-operations" })
 ```
 
 Or query specific sections:
 ```
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Troubleshooting" })
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Common Issues and Solutions" })
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Release Detection Not Triggering" })
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Quick Reference: Diagnostic Commands" })
+get_section({ path: "process-hook-operations", heading: "Troubleshooting" })
+get_section({ path: "process-hook-operations", heading: "Common Issues and Solutions" })
+get_section({ path: "process-hook-operations", heading: "Release Detection Not Triggering" })
+get_section({ path: "process-hook-operations", heading: "Quick Reference: Diagnostic Commands" })
 ```
 
 **Quick Reference - Common Issues**:
@@ -255,9 +245,9 @@ get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Quick
 - **Hook script errors**: Ensure scripts have execute permissions (`chmod +x`)
 
 **Quick Reference - Error Recovery**:
-- If commit fails: Fix issues and re-run hook script
-- If push fails: Run `git push origin main` manually
-- If wrong message: Use `git commit --amend -m "Correct Message"` then force push
+- If commit fails: Fix issues and re-run the tooling
+- If push fails: Push the TASK BRANCH manually (`git push -u origin <branch>`) — never `main`
+- If the PR title is wrong: Edit the PR title on GitHub (squash-merge takes the title as the commit subject)
 
 
 ---
@@ -298,13 +288,13 @@ Agent hooks provide automatic file organization and release detection when tasks
 **For detailed guidance** on hook execution order, automatic file organization, release detection, and troubleshooting, query Process-Hook-Operations via MCP:
 
 ```
-get_document_full({ path: ".kiro/steering/Process-Hook-Operations.md" })
+get_document_full({ path: "process-hook-operations" })
 ```
 
 Or query specific sections:
 ```
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Kiro Agent Hook Integration" })
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Agent Hook Execution Order" })
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Automatic File Organization" })
-get_section({ path: ".kiro/steering/Process-Hook-Operations.md", heading: "Release Detection" })
+get_section({ path: "process-hook-operations", heading: "Kiro Agent Hook Integration" })
+get_section({ path: "process-hook-operations", heading: "Agent Hook Execution Order" })
+get_section({ path: "process-hook-operations", heading: "Automatic File Organization" })
+get_section({ path: "process-hook-operations", heading: "Release Detection" })
 ```

package/governance/Process-File-Organization.md

@@ -9,7 +9,7 @@ description: File organization standards — metadata-driven organization, direc
 # File Organization Standards
 
 **Date**: 2025-01-10
-**Last Reviewed**: 2026-06-23
+**Last Reviewed**: 2026-07-05
 **Purpose**: Metadata-driven file organization system for sustainable project structure
 **Organization**: process-standard
 **Scope**: cross-project
@@ -34,8 +34,8 @@ description: File organization standards — metadata-driven organization, direc
 
 **Query via MCP for detailed guidance:**
 ```
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Two-Document Workflow" })
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Cross-References" })
+get_section({ path: "completion-documentation-guide", heading: "Two-Document Workflow" })
+get_section({ path: "completion-documentation-guide", heading: "Cross-References" })
 ```
 
 ### WHEN Creating Spec Documents (Requirements, Design, Tasks)
@@ -58,8 +58,8 @@ get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading:
 
 **Query via MCP for detailed guidance:**
 ```
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Naming Conventions" })
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Document Templates" })
+get_section({ path: "completion-documentation-guide", heading: "Naming Conventions" })
+get_section({ path: "completion-documentation-guide", heading: "Document Templates" })
 ```
 
 ### WHEN Adding Cross-References
@@ -69,9 +69,9 @@ get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading:
 
 **Query via MCP for detailed guidance:**
 ```
-get_section({ path: ".kiro/steering/Process-Cross-Reference-Standards.md", heading: "How to Format Cross-References" })
-get_section({ path: ".kiro/steering/Process-Cross-Reference-Standards.md", heading: "Common Cross-Reference Patterns" })
-get_section({ path: ".kiro/steering/Process-Cross-Reference-Standards.md", heading: "Anti-Patterns to Avoid" })
+get_section({ path: "process-cross-reference-standards", heading: "How to Format Cross-References" })
+get_section({ path: "process-cross-reference-standards", heading: "Common Cross-Reference Patterns" })
+get_section({ path: "process-cross-reference-standards", heading: "Anti-Patterns to Avoid" })
 ```
 
 ### WHEN Organizing Existing Files AND Creating New Implementation Files
@@ -172,13 +172,13 @@ aliases: RTL, bidirectional, internationalization, i18n
 **For detailed guidance** on completion documentation naming conventions, templates, and the two-document workflow, query Completion Documentation Guide via MCP:
 
 ```
-get_document_full({ path: ".kiro/steering/Completion Documentation Guide.md" })
+get_document_full({ path: "completion-documentation-guide" })
 ```
 
 Or query specific sections:
 ```
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Naming Conventions" })
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Directory Structure" })
+get_section({ path: "completion-documentation-guide", heading: "Naming Conventions" })
+get_section({ path: "completion-documentation-guide", heading: "Directory Structure" })
 ```
 
 #### Summary Documents
@@ -194,19 +194,19 @@ get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading:
 - Summary docs are ONLY for parent tasks (not subtasks)
 - Naming pattern: `task-N-summary.md` (e.g., `task-1-summary.md`)
 - Hook pattern: `**/task-*-summary.md`
-- AI workflows: `commit-task.sh` runs release analysis automatically after commit
+- AI workflows: release analysis runs post-merge on `main` (summary docs traverse the PR gate with the work)
 
 **For detailed guidance** on summary document templates, cross-references, and the two-document workflow, query Completion Documentation Guide via MCP:
 
 ```
-get_document_full({ path: ".kiro/steering/Completion Documentation Guide.md" })
+get_document_full({ path: "completion-documentation-guide" })
 ```
 
 Or query specific sections:
 ```
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Two-Document Workflow" })
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Cross-References" })
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Document Templates" })
+get_section({ path: "completion-documentation-guide", heading: "Two-Document Workflow" })
+get_section({ path: "completion-documentation-guide", heading: "Cross-References" })
+get_section({ path: "completion-documentation-guide", heading: "Document Templates" })
 ```
 
 #### Spec-Specific Guides
@@ -293,13 +293,13 @@ strategic-framework/
 **For detailed guidance** on completion documentation directory structure, naming patterns, and the two-document workflow, query Completion Documentation Guide via MCP:
 
 ```
-get_document_full({ path: ".kiro/steering/Completion Documentation Guide.md" })
+get_document_full({ path: "completion-documentation-guide" })
 ```
 
 Or query specific sections:
 ```
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Directory Structure" })
-get_section({ path: ".kiro/steering/Completion Documentation Guide.md", heading: "Naming Conventions" })
+get_section({ path: "completion-documentation-guide", heading: "Directory Structure" })
+get_section({ path: "completion-documentation-guide", heading: "Naming Conventions" })
 ```
 
 ### Audit Findings
@@ -388,7 +388,7 @@ After moving files, update any cross-reference links to reflect new locations.
 
 #### Enhanced Commit Hook
 ```bash
-# .kiro/hooks/commit-task-organized.sh "Task Name" [--organize]
+# .kiro/hooks/complete-task.sh "Task Name" [--organize]   (organization option folded into the PR-flow tooling)
 # Optional organization during task completion
 # Human-controlled with hook assistance
 # Maintains fallback to current behavior
@@ -561,14 +561,14 @@ Cross-references are markdown links that connect related documentation, enabling
 **For detailed guidance** on cross-reference formatting, patterns, anti-patterns, and maintenance, query Process-Cross-Reference-Standards via MCP:
 
 ```
-get_document_full({ path: ".kiro/steering/Process-Cross-Reference-Standards.md" })
+get_document_full({ path: "process-cross-reference-standards" })
 ```
 
 Or query specific sections:
 ```
-get_section({ path: ".kiro/steering/Process-Cross-Reference-Standards.md", heading: "How to Format Cross-References" })
-get_section({ path: ".kiro/steering/Process-Cross-Reference-Standards.md", heading: "Common Cross-Reference Patterns" })
-get_section({ path: ".kiro/steering/Process-Cross-Reference-Standards.md", heading: "Anti-Patterns to Avoid" })
+get_section({ path: "process-cross-reference-standards", heading: "How to Format Cross-References" })
+get_section({ path: "process-cross-reference-standards", heading: "Common Cross-Reference Patterns" })
+get_section({ path: "process-cross-reference-standards", heading: "Anti-Patterns to Avoid" })
 ```
 
 ---

package/governance/Process-Hook-Operations.md

@@ -8,7 +8,7 @@ description: Agent hook operational guidance — dependency chains, execution or
 # Hook Operations Guide
 
 **Date**: 2026-01-04
-**Last Reviewed**: 2026-01-04
+**Last Reviewed**: 2026-07-09
 **Purpose**: Comprehensive operational guidance for agent hook dependency chains, troubleshooting, and best practices
 **Organization**: process-standard
 **Scope**: cross-project
@@ -19,6 +19,16 @@ description: Agent hook operational guidance — dependency chains, execution or
 
 This document provides detailed operational guidance for working with Kiro agent hooks. It covers dependency chain behavior, troubleshooting procedures, and best practices for reliable automation.
 
+> ## ⚠️ Scope & runtime — read before applying any of this
+>
+> **1. This describes a Kiro-IDE-only mechanism.** The "agent hooks" here are the Kiro event-hook runtime — `.kiro/agent-hooks/*.json` configs fired by the Kiro IDE on `taskStatusChange` events. **Claude Code has no equivalent event-hook system** (the same runtime gap that the always-layer has under CC — see 122 / OB-7). Under Claude Code none of these hooks fire; file organization and any release steps are performed by explicit tooling/CLI steps, not by IDE events. Read every "hooks fire on task completion" statement below as *Kiro-runtime behavior*, not a cross-runtime guarantee.
+>
+> **2. "Task completion" now means merge (125-A PR-gate).** Since the ratified 125-A workflow, a task is accepted when its unit's **PR is merged** — not when a local status flips. The completion tool is `./.kiro/hooks/complete-task.sh` (opens the PR), which **superseded** the old commit-on-completion tooling. Work reaches `main` only through a merged, branch-protected PR. So the troubleshooting guidance below that frames "direct git commits" as *bypassing hooks* (versus using the `taskStatus` tool) is **Kiro-IDE-specific and predates the branch→PR→merge flow** — under the current workflow, committing and pushing a branch is a *correct, expected* step, not an error to avoid.
+>
+> **3. Release detection here is historical.** As the frontmatter notes, the release system was rebuilt in Spec 065 into an on-demand CLI (`src/tools/release/`); the release-detection-on-task-completion hook content below is retained for Kiro-hook operational history. See [Release Management System](release-management-system) for the current architecture.
+>
+> This doc is preserved for Kiro-runtime hook operations and history. A cross-runtime rework belongs with the 122 agent-generator work (OB-7), not here.
+
 **When to use this document**:
 - Debugging hook issues or automation failures
 - Understanding hook dependencies and execution order
@@ -509,6 +519,8 @@ ls -la .kiro/release-triggers/
    # git commit -m "message" && git push
    ```
 
+   > **Kiro-runtime framing only (see the Scope banner).** "`git commit && push` bypasses hooks" is true *only* of the Kiro IDE event mechanism. Under the 125-A PR-gate workflow, committing and pushing a branch is the **correct** step — subtask/parent work reaches `main` through a merged PR, and `taskStatus` marks completion *on the branch*. This "wrong approach" label applies to Kiro hook-triggering, not to the git workflow itself.
+
 2. **Verify task status changed**: Check tasks.md to confirm task is marked `[x]`
 
 3. **Check hook configurations**: Verify JSON files are valid and enabled
@@ -1155,13 +1167,13 @@ File organization triggers automatically when task status changes to "completed"
 **For detailed guidance** on file organization workflow, metadata values, directory structure, scope rationale, and manual organization options, query File Organization Standards via MCP:
 
 ```
-get_document_full({ path: ".kiro/steering/Process-File-Organization.md" })
+get_document_full({ path: "process-file-organization" })
 ```
 
 Or query specific sections:
 ```
-get_section({ path: ".kiro/steering/Process-File-Organization.md", heading: "Organization Implementation (Conditional Loading)" })
-get_section({ path: ".kiro/steering/Process-File-Organization.md", heading: "File Organization Scope (Conditional Loading)" })
+get_section({ path: "process-file-organization", heading: "Organization Implementation (Conditional Loading)" })
+get_section({ path: "process-file-organization", heading: "File Organization Scope (Conditional Loading)" })
 ```
 
 ### Release Detection
@@ -1182,13 +1194,13 @@ Release detection triggers automatically when parent task summary documents are
 **For detailed guidance** on release detection pipeline, troubleshooting, hook debugging, and manual triggers, query Release Management System via MCP:
 
 ```
-get_document_full({ path: ".kiro/steering/Release Management System.md" })
+get_document_full({ path: "release-management-system" })
 ```
 
 Or query specific sections:
 ```
-get_section({ path: ".kiro/steering/Release Management System.md", heading: "Release Pipeline Architecture" })
-get_section({ path: ".kiro/steering/Release Management System.md", heading: "AI Agent Decision Points" })
+get_section({ path: "release-management-system", heading: "Release Pipeline Architecture" })
+get_section({ path: "release-management-system", heading: "AI Agent Decision Points" })
 ```
 
 ---

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" })
+```