@3fn/core 13.0.0 → 14.1.0

package/governance/MCP-Integration-Guide.md

@@ -151,7 +151,7 @@ Both `find_docs` and keyworded `find_components` emit a three-layer confidence s
 
 **Token exemption:** token tools perform structured predicate retrieval with no relevance ranking — the three-layer model does not apply. Trigger: if a token tool is introduced with open-ended intent input and ranked output, it inherits this model. Bright line: predicate filter → no tier; relevance ranking → tier required.
 
-**119 Decision 4a cross-reference:** the agent-side certainty-calibration protocol that consumes a `partial` (propose best-fit + confidence + rationale → human go/no-go, with the proposal required to carry its own uncertainty) is captured in `.kiro/specs/119-steering-progressive-disclosure-redesign/design-outline.md` under Decision 4a. 121 emits the signal; 119 defines what the agent does with a `partial`.
+**119 Decision 4a cross-reference:** the agent-side certainty-calibration protocol that consumes a `partial` (propose best-fit + confidence + rationale → human go/no-go, with the proposal required to carry its own uncertainty) is captured in `.kiro/specs/119-agent-experience-architecture/design-outline.md` under Decision 4a. 121 emits the signal; 119 defines what the agent does with a `partial`.
 
 ---
 

package/governance/Process-Cross-Reference-Standards.md

@@ -8,7 +8,7 @@ description: Cross-reference standards for documentation — formatting rules, c
 # Process-Cross-Reference-Standards
 
 **Date**: 2026-01-03
-**Last Reviewed**: 2026-01-03
+**Last Reviewed**: 2026-07-09
 **Purpose**: Comprehensive guide for creating and maintaining cross-references in documentation
 **Organization**: process-standard
 **Scope**: cross-project
@@ -34,7 +34,7 @@ Cross-references MUST be used in the following documentation types:
 - **Completion Documents**: Task completion documentation in `.kiro/specs/[spec-name]/completion/`
 - **README Files**: Project and directory README files that provide navigation and context
 - **Overview Documents**: Master documents that map components to their documentation (e.g., `docs/token-system-overview.md`)
-- **Process Documentation**: Standards and methodology documents in `.kiro/steering/` and `docs/processes/`
+- **Process Documentation**: Standards and methodology documents in the MCP-served governance corpus (`governance/`), the always-loaded identity docs (`.kiro/steering/`), and `docs/processes/`
 
 **Rationale**: These are documentation artifacts where cross-references add value by helping readers discover related information and navigate between connected concepts.
 
@@ -113,11 +113,25 @@ export const TypographyTokens = {
 
 ## How to Format Cross-References
 
-Cross-references should follow consistent formatting patterns to ensure clarity and maintainability.
+Cross-references should follow consistent formatting patterns to ensure clarity and maintainability. **Which pattern applies depends on what you are linking to** — there are two reference classes:
+
+### Two Reference Classes (pick by target)
+
+| Target | How to reference | Example |
+|--------|------------------|---------|
+| **Governance corpus** — an MCP-served doc under `governance/` that carries an `id:` | **Bare-`id`** markdown link: `[Human Label](<doc-id>)` — the target's `id`, no path, no `.md`. Bare-id links are validated against the served index (Spec 119-B OB-1): a target that is not MCP-served will be dropped from cross-ref enumeration and flagged unresolved | `[Token Governance](token-governance)` |
+| **The 9 identity docs** under `.kiro/steering/` — always-loaded, NEVER MCP-served (Spec 119-A: identity refs never take the MCP round-trip; they carry `id:` for the uniqueness guard, not for resolution) | **Relative path** markdown link, like other non-id-indexed repo files (amended 2026-08-02, Civitas health-check follow-up #4 — the prior bare-id clause implied MCP resolvability these docs deliberately do not have) | `[Core Goals](../.kiro/steering/core-goals.md)` |
+| **Spec-local / repo-file** — spec artifacts (requirements/design/tasks/completion docs, spec guides), READMEs, and other repo files that are **not** `id`-indexed | **Relative path** markdown link (see "Relative Path Usage" below) | `[Design Decisions](../design.md#design-decisions)` |
+
+**Why the split.** Spec 119-A gave every doc in the MCP-served corpus a stable, relocation-independent `id` and made bare-`id` the addressing form (226 intra-corpus refs migrated). An `id`-addressed link survives file moves because the `id` — not the path — is the address. Spec artifacts and loose repo files carry no `id`, so relative paths remain their correct form.
+
+**The addressing grammar is owned elsewhere — do not re-derive it here.** The canonical source for the `id` form, the composite `docid#sectionid` section grammar, kebab-case filenames, and `aliases` is [Steering Addressing Conventions](steering-addressing-conventions). This document governs cross-reference *practice* (when to link, link-text quality, anti-patterns, maintenance); it defers the *grammar* to that doc so the two never drift.
+
+> **Tooling caveat (119-B OB-1).** Bare-`id` cross-refs **resolve** correctly (resolver strategy-1), but the cross-reference *parser* still only enumerates `.md`-suffixed targets, so `list_cross_references` and the `crossReferences` map currently under-count bare-`id` links. Enumeration parity is deferred to 119-B OB-1. Until then, do not treat an empty `list_cross_references` result as proof a doc has no inbound links.
 
 ### Relative Path Usage
 
-Always use relative paths from the current document location. Relative paths ensure links remain valid when the repository structure changes or when viewing documentation in different contexts.
+For **spec-local and repo-file references** (the second class above), use relative paths from the current document location. Relative paths ensure these links remain valid when viewed across different contexts. (For steering/governance-corpus targets, use the bare-`id` form instead — see the table above.)
 
 **Pattern**: Use `../` to navigate up directories and `./` for same-directory references
 
@@ -483,7 +497,7 @@ where properties are separated by concern.
 
 ## Related Guides
 
-- [Compositional Color Guide](https://github.com/3fn/DesignerPunkv2/blob/main/.kiro/specs/typography-token-expansion/compositional-color-guide.md)
+- [Compositional Color Guide](https://github.com/3fn/DesignerPunk/blob/main/.kiro/specs/typography-token-expansion/compositional-color-guide.md)
 - [Strategic Flexibility Guide](/Users/peter/.kiro/specs/typography-token-expansion/strategic-flexibility-guide.md)
 - [Inline Emphasis Guide](/.kiro/specs/typography-token-expansion/inline-emphasis-guide.md)
 ```
@@ -611,7 +625,7 @@ Strategic Flexibility Guide.
 
 When files are moved during organization:
 
-1. Update all cross-reference links to reflect new locations
+1. **Bare-`id` references to steering/governance-corpus docs need no update** — the `id` is the address, so it survives the move (this move-resilience is the reason 119-A adopted `id`-addressing). Update the *relative-path* references (spec-local / repo-file links) to reflect new locations.
 2. Verify bidirectional links remain consistent
 3. Test navigation by clicking links in rendered markdown
 4. Document any broken links and fix them immediately
@@ -621,10 +635,12 @@ When files are moved during organization:
 Periodically validate cross-reference integrity:
 
 - Verify all links resolve to existing documents
-- Check that relative paths are correct from document location
+- Check that relative paths are correct from document location (bare-`id` links resolve by `id`, not path, so there is no path to verify — confirm the `id` exists)
 - Confirm section anchors exist in target documents
 - Test navigation efficiency (related docs reachable in 2 clicks or less)
 
+> **Caveat (119-B OB-1):** automated link-graph tooling built on `list_cross_references` currently under-counts bare-`id` links (the parser enumerates only `.md`-suffixed targets). Until OB-1 lands, supplement automated enumeration with a text search for bare-`id` targets when auditing a doc's inbound/outbound links.
+
 ### Navigation as Aid, Not Dependency
 
 Cross-references should be navigation aids, not content dependencies:
@@ -654,12 +670,14 @@ Cross-references should be navigation aids, not content dependencies:
 
 ## Related Documentation
 
-- **File Organization Standards** - Metadata and directory structure
-- **Completion Documentation Guide** - Completion doc cross-reference patterns
-- **Development Workflow** - Task completion workflow
+- [Steering Addressing Conventions](steering-addressing-conventions) - **Canonical** `id` / `docid#sectionid` grammar, filename and `aliases` conventions (this doc defers the grammar there)
+- [Process File Organization](process-file-organization) - Metadata and directory structure
+- [Completion Documentation Guide](completion-documentation-guide) - Completion doc cross-reference patterns
+- [Process Development Workflow](process-development-workflow) - Task completion workflow
 
-**MCP Queries**:
+**MCP Queries** (bare-`id` in the `path` argument — the resolver addresses by `id`):
 ```
-get_section({ path: ".kiro/steering/Process-File-Organization.md", heading: "Required Metadata Fields" })
-get_document_full({ path: ".kiro/steering/Completion Documentation Guide.md" })
+get_section({ path: "steering-addressing-conventions", heading: "Convention 2: Composite `docid#sectionid` Addressing Grammar" })
+get_section({ path: "process-file-organization", heading: "Required Metadata Fields" })
+get_document_full({ path: "completion-documentation-guide" })
 ```

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-08-12
 **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" })`
+- **Releases**: `get_section({ path: "release-management-system", heading: "The Release Recipe" })`
+- **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-delta check**: `git log $(git describe --tags --abbrev=0)..main --oneline` shows everything shipped since the last release (squash titles are the changelog spine — see Release Management System)
 
 **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>`)
+- 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
@@ -109,10 +109,7 @@ All files use explicit metadata to declare organizational intent, enabling safe
 **Task**: Associated task number and name (if applicable)
 ```
 
-**Civitas Governance Note:** Steering documents require additional metadata fields (`Last Reviewed`, `Layer`, `Relevant Tasks`, `inclusion` in YAML frontmatter). For the complete steering doc metadata requirements and lifecycle process (creation → review → update → deprecation), see Thurgood's Civitas Steward operational mode or query:
-```
-get_section({ path: ".kiro/steering/Civitas-System-Overview.md", heading: "Governance Processes" })
-```
+**Civitas Governance Note:** Steering documents require additional metadata fields (`Last Reviewed`, `Layer`, `Relevant Tasks`, `inclusion` in YAML frontmatter). For the complete steering doc metadata requirements and lifecycle process (creation → review → update → deprecation), see Thurgood's Civitas Steward operational mode, or the always-loaded Civitas System Overview § "Governance Processes" (an identity doc — never MCP-served, already in every agent's context; no query needed).
 
 #### Optional: `aliases:` frontmatter field (steering docs)
 
@@ -172,13 +169,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 +191,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 +290,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 +385,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 +558,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

@@ -2,13 +2,13 @@
 id: process-hook-operations
 inclusion: manual
 name: Process-Hook-Operations
-description: Agent hook operational guidance — dependency chains, execution order, automatic file organization, troubleshooting, and best practices. Load when debugging hook issues, setting up or modifying hooks, or troubleshooting automation failures. NOTE - Release detection sections are outdated; the release system was rebuilt in Spec 065 as an on-demand CLI tool at src/tools/release/. See Release Management System.md for current architecture.
+description: Agent hook operational guidance — dependency chains, execution order, automatic file organization, troubleshooting, and best practices. Load when debugging hook issues, setting up or modifying hooks, or troubleshooting automation failures. NOTE - Release detection sections are historical; the Spec-065 release CLI was RETIRED 2026-08-12 (Q6 ballot) in favor of the manual release recipe. See Release Management System for current process.
 ---
 
 # 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.** The Spec-065 release CLI was itself RETIRED on 2026-08-12 (Q6 ballot: `.kiro/docs/ballots/2026-08-12-q6-release-manager-retirement.md`), and the `release-manager.sh` hook described below was DELETED the same day; this content is retained solely as Kiro-hook operational history. See [Release Management System](release-management-system) for the current release recipe.
+>
+> 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
@@ -1175,20 +1187,19 @@ Release detection triggers automatically when parent task summary documents are
 - `.kiro/` directory is filtered from Kiro IDE file watching (hooks don't trigger there)
 
 **Quick Reference**:
-- **Summary docs**: `docs/specs/[spec-name]/task-N-summary.md` (triggers hooks)
+- **Summary docs**: `docs/specs/[spec-name]/task-N-summary.md` (release-note source material)
 - **Detailed docs**: `.kiro/specs/[spec-name]/completion/task-N-parent-completion.md` (internal)
-- **Manual trigger**: `./.kiro/hooks/release-manager.sh auto`
 
-**For detailed guidance** on release detection pipeline, troubleshooting, hook debugging, and manual triggers, query Release Management System via MCP:
+**For the current release process** (the manual recipe; the detection hook was deleted 2026-08-12, Q6 ballot), 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: "The Release Recipe" })
+get_section({ path: "release-management-system", heading: "Discovering What Changed and Why" })
 ```
 
 ---