@3fn/core 13.0.0 → 14.1.0

package/governance/completion-documentation-guide.md

@@ -8,7 +8,7 @@ description: Comprehensive completion and summary documentation guide — two-do
 # Completion Documentation Guide
 
 **Date**: 2026-01-03
-**Last Reviewed**: 2026-02-28
+**Last Reviewed**: 2026-07-05
 **Purpose**: Comprehensive guide for creating completion and summary documentation
 **Organization**: process-standard
 **Scope**: cross-project
@@ -24,9 +24,9 @@ This guide consolidates all guidance for creating completion documentation, incl
 - What content to include (documentation tiers)
 - Where to place files (directory structure)
 - How to name files (naming conventions)
-- Why summary docs matter (release detection)
+- Why summary docs matter (release-note source material)
 
-**Key Principle**: Parent task completion requires TWO documents - a detailed completion doc for internal knowledge preservation and a summary doc for release detection and public-facing release notes.
+**Key Principle**: Parent task completion requires TWO documents - a detailed completion doc for internal knowledge preservation and a summary doc as public-facing release-note source material.
 
 ---
 
@@ -39,12 +39,12 @@ Parent task completion produces two complementary documents:
 | Document Type | Location | Purpose | Audience |
 |---------------|----------|---------|----------|
 | **Detailed Completion Doc** | `.kiro/specs/[spec-name]/completion/` | Comprehensive internal documentation | Internal team, knowledge preservation |
-| **Summary Doc** | `docs/specs/[spec-name]/` | Concise, commit-style summary | Public-facing, release notes, hook trigger |
+| **Summary Doc** | `docs/specs/[spec-name]/` | Concise, commit-style summary | Public-facing, release-note source |
 
 **Rationale**:
-- **Hook Triggering**: The `.kiro/` directory is filtered from Kiro IDE's file watching system. Summary documents in `docs/specs/` enable automatic release detection.
-- **Dual Purpose**: Summary documents serve both as hook triggers and as concise, public-facing release note content.
+- **Dual Purpose**: Summary documents are the concise, public-facing record of each parent task — the source material the release recipe reads when authoring release notes.
 - **Clear Separation**: Detailed completion docs (internal knowledge preservation) remain in `.kiro/`, while summaries (public-facing) live in `docs/`.
+- *(Historical: the `docs/`-placement also served a Kiro release-detection hook, deleted 2026-08-12 — Q6 ballot. The placement stays: the public/internal split earns it on its own.)*
 
 ### When to Create Each Document
 
@@ -78,7 +78,7 @@ Documentation tiers define the depth and comprehensiveness of completion documen
 **For complete tier definitions and templates**, query Spec Planning Standards via MCP:
 
 ```
-get_section({ path: ".kiro/steering/Process-Spec-Planning.md", heading: "Three-Tier Completion Documentation System" })
+get_section({ path: "process-spec-planning", heading: "Three-Tier Completion Documentation System" })
 ```
 
 ---
@@ -130,10 +130,10 @@ docs/specs/cross-platform-build-system/
 ### Two-Directory Structure
 
 ```
-docs/specs/[spec-name]/                   # Public-facing documentation (TRIGGERS HOOKS)
-├── task-1-summary.md                     # ✅ Parent task summary (triggers release detection)
-├── task-2-summary.md                     # ✅ Parent task summary (triggers release detection)
-└── task-N-summary.md                     # ✅ Parent task summary (triggers release detection)
+docs/specs/[spec-name]/                   # Public-facing documentation
+├── task-1-summary.md                     # ✅ Parent task summary (release-note source)
+├── task-2-summary.md                     # ✅ Parent task summary (release-note source)
+└── task-N-summary.md                     # ✅ Parent task summary (release-note source)
 
 .kiro/specs/[spec-name]/                  # Internal documentation (NO HOOK TRIGGERS)
 ├── requirements.md                        # ❌ Spec requirements (no hook trigger)
@@ -150,7 +150,7 @@ docs/specs/[spec-name]/                   # Public-facing documentation (TRIGGER
 
 | Location | Purpose | Hook Trigger | Audience |
 |----------|---------|--------------|----------|
-| `docs/specs/[spec-name]/` | Concise summaries | ✅ Yes | Public-facing, release notes |
+| `docs/specs/[spec-name]/` | Concise summaries | — (hook retired) | Public-facing, release-note source |
 | `.kiro/specs/[spec-name]/completion/` | Comprehensive docs | ❌ No | Internal, knowledge preservation |
 
 ---
@@ -166,6 +166,7 @@ docs/specs/[spec-name]/                   # Public-facing documentation (TRIGGER
 **Task**: N.M [Task description from tasks.md]
 **Type**: Implementation
 **Status**: Complete
+**Delegated-tier** _(optional — include ONLY if the executing agent/model diverged from the task's planned `**Agent**: <agent> (<Model>)`)_: planned `<agent> (<Model>)` → actual `<agent> (<Model>)` — <one-line reason; flag whether it was agent-evolution (routing/scope) or model-evolution (cognitive-demand)>. See `process-orchestration-model-selection`.
 
 ---
 
@@ -281,18 +282,10 @@ Detailed completion documents can optionally link to the summary document:
 ### How Summary Documents Feed Release Notes
 
 1. **Summary document created** in `docs/specs/[spec-name]/`
-2. **Release tool** (`npm run release:analyze`) scans summary docs via git log since last tag
-3. **ChangeExtractor** parses markdown sections into structured data
-4. **ChangeClassifier** maps changes to priority tiers (🔴/🟡/🔵)
-5. **NotesRenderer** generates public + internal markdown release notes
+2. **At release time**, the release author derives the shipped delta from squash-commit titles since the last tag (`git log <last-tag>..main --oneline`) and reads summary docs for each change's substance and classification (🔴/🟡/🔵)
+3. **Release notes are hand-authored** at `docs/releases/release-X.Y.Z.md` from that material — summaries are the notes' source, and the durable per-task record
 
-### Automatic Analysis
-
-`commit-task.sh` runs release analysis automatically after each task commit. For on-demand analysis:
-
-```bash
-npm run release:analyze
-```
+*(The automated release tool that formerly scanned summaries was retired 2026-08-12 — Q6 ballot `.kiro/docs/ballots/2026-08-12-q6-release-manager-retirement.md`. See Release Management System § "The Release Recipe".)*
 
 ---
 
@@ -325,14 +318,6 @@ task-10-summary.md
 
 Summary documents are ONLY for parent tasks. Subtasks only need detailed completion docs.
 
-### ❌ Forgetting Manual Trigger for AI Workflows
-
-If AI agent created the summary document, you MUST run:
-```bash
-./.kiro/hooks/release-manager.sh auto
-```
-
----
 
 ## Workflow Checklist
 
@@ -349,10 +334,11 @@ If AI agent created the summary document, you MUST run:
 - [ ] Run validation (`npm test` or `npm run test:all`)
 - [ ] Create detailed completion doc: `.kiro/specs/[spec-name]/completion/task-N-completion.md`
 - [ ] Create summary doc: `docs/specs/[spec-name]/task-N-summary.md`
-- [ ] Trigger release detection: `./.kiro/hooks/release-manager.sh auto`
 - [ ] Mark parent task complete using `taskStatus` tool
-- [ ] Commit changes: `./.kiro/hooks/commit-task.sh "Task N Complete: Description"`
-- [ ] STOP and wait for user authorization
+- [ ] Complete the parent on its unit branch: `./.kiro/hooks/complete-task.sh "..."` — completion and summary docs travel on the branch.
+   - **If this parent IS its own merge unit** (a standalone task, or a small single-unit spec): the tooling opens the PR.
+   - **If this parent is one of several in a declared multi-parent unit** (spec's tasks.md unit grouping): the tooling commits the docs on the branch — **no PR yet**; the PR opens at UNIT completion.
+- [ ] STOP — if a PR opened, report the PR URL; otherwise report the on-branch parent completion. The task is **accepted when the UNIT merges**.
 
 ---
 
@@ -365,7 +351,7 @@ If AI agent created the summary document, you MUST run:
 
 **MCP Queries**:
 ```
-get_section({ path: ".kiro/steering/Process-Spec-Planning.md", heading: "Three-Tier Completion Documentation System" })
-get_section({ path: ".kiro/steering/Process-Development-Workflow.md", heading: "Task Completion Workflow" })
-get_section({ path: ".kiro/steering/Release Management System.md", heading: "Release Pipeline Architecture" })
+get_section({ path: "process-spec-planning", heading: "Three-Tier Completion Documentation System" })
+get_section({ path: "process-development-workflow", heading: "Task Completion Workflow" })
+get_section({ path: "release-management-system", heading: "The Release Recipe" })
 ```

package/governance/component-meta-authoring-guide.md

@@ -229,7 +229,7 @@ Component-meta.yaml does NOT currently include a `data_shapes:` field for descri
 
 Or query via MCP:
 ```
-get_section({ path: ".kiro/steering/Component-Meta-Data-Shapes-Governance.md", heading: "Trigger Criteria" })
+get_section({ path: "component-meta-data-shapes-governance", heading: "Trigger Criteria" })
 ```
 
 **Any agent creating or reviewing a component-meta.yaml should evaluate the trigger criteria in that doc.** If any criterion is met, follow the escalation process defined there.

package/governance/cross-platform-vs-platform-specific-decision-framework.md

@@ -9,7 +9,7 @@ description: Strategic guidance on when to use cross-platform patterns vs platfo
 # Cross-Platform vs Platform-Specific Decision Framework
 
 **Date**: 2025-12-19
-**Last Reviewed**: 2025-12-19
+**Last Reviewed**: 2026-07-08
 **Purpose**: Strategic guidance on when to use cross-platform patterns vs platform-specific idioms
 **Organization**: process-standard
 **Scope**: cross-project

package/governance/platform-implementation-guidelines.md

@@ -14,7 +14,7 @@ description: Guidelines for maintaining cross-platform behavioral consistency
 **Scope**: cross-project
 **Layer**: 2
 **Relevant Tasks**: component-development, cross-platform-validation, testing
-**Last Reviewed**: 2026-01-02
+**Last Reviewed**: 2026-07-08
 
 ---
 
@@ -50,7 +50,7 @@ behavioral_contract_compliance:
 
 **Example - Float Label Animation Contract**:
 ```
-Contract: provides_float_label_animation
+Contract: content_float_label
 
 All platforms MUST:
 ✅ Animate label from placeholder to floating position on focus
@@ -465,7 +465,6 @@ pre_implementation:
   contract_review:
     - [ ] Each contract has clear trigger conditions
     - [ ] Each contract has measurable outcomes
-    - [ ] WCAG references included for accessibility contracts
     - [ ] Contracts are platform-agnostic (WHAT not HOW)
     
   human_ai_checkpoint:

package/governance/release-management-system.md

@@ -1,14 +1,19 @@
 ---
 id: release-management-system
 inclusion: manual
+name: Release Management System
+description: The release recipe (derive-classify-ratify, hand-authored notes) and how agents discover what changed and why — replaces the retired automated release tool
+aliases: release recipe, release process, release notes, what changed, version bump, changelog, release delta
 ---
 
 # Release Management System
 
+> **Audience framing**: this documents **DesignerPunk's own** release process. Consumers of the package read it as a worked example of a recipe-over-tooling release model — the paths, scripts, and named roles below are DesignerPunk's, not yours. (Whether DesignerPunk's release notes themselves ship to consumers is an open Spec 123 question, deferred by the Q6 ballot.)
+
 **Date**: 2026-02-28
-**Last Reviewed**: 2026-02-28
-**Last Updated**: 2026-02-28
-**Purpose**: Mental model of the release management system for AI agents
+**Last Reviewed**: 2026-08-12
+**Last Updated**: 2026-08-12
+**Purpose**: Mental model of the release process for AI agents — the recipe, and how to discover what changed and why
 **Organization**: process-standard
 **Scope**: cross-project
 **Layer**: 2
@@ -18,72 +23,32 @@ inclusion: manual
 
 ## Overview
 
-The release tool is an on-demand CLI at `src/tools/release/`. It replaces the previous 203-file system with a focused pipeline: discover summary docs since last git tag → extract structured changes → classify by priority → recommend version bump → generate markdown release notes → optionally create GitHub release.
-
-**Key principles:**
-- Runs on-demand only. No timers, no hooks, no passive file generation.
-- Git tags are the only persistent state. No state files, no caches, no history accumulation.
-- Human-reviewed before publishing. The tool recommends; Peter decides.
+Releases are executed by a **documented recipe, not a standing tool**. The automated release manager (an on-demand CLI that scanned spec summary docs to recommend versions and generate notes) was **RETIRED on 2026-08-12** — Q6 ballot: `.kiro/docs/ballots/2026-08-12-q6-release-manager-retirement.md`. It was retired because the PR gate made it redundant-and-worse: every merge to `main` is one squash commit whose title is a disciplined change description, so the release delta is derivable with one `git log` — while the tool, reading only spec summaries, was structurally blind to issue-driven work and mis-recommended the v14.0.0 release outright (patch/"no consumer-facing changes" against a breaking component wave).
 
----
+**Key principles (unchanged by the retirement):**
+- Human-reviewed, human-decided: the recipe derives and drafts; **the repo's release owner (in DesignerPunk: Peter) ratifies the version bump and merges the release PR**.
+- Git tags are the only persistent release state.
+- Verification stays mechanized; judgment stays human. DesignerPunk's publish guard scripts (`check:drift`, `verify:token-index-clean`, the `prepublishOnly` chain — this repo's package scripts, not shipped to consumers) block a broken publish mechanically and are NOT part of the retired tool.
 
-## Architecture
+## The Release Recipe
 
-```
-CLI Entry Point (src/tools/release/cli/release-tool.ts)
-  ├── analyze  → ReleasePipeline.analyze()
-  ├── notes    → ReleasePipeline.generateNotes()
-  └── release  → ReleasePipeline.release()
+The operational sequence lives in `.kiro/hooks/RELEASE-FLOW.md` (the PR-gated release flow). The judgment half, summarized:
 
-ReleasePipeline (src/tools/release/cli/ReleasePipeline.ts)
-  ├── TagResolver        — git describe --tags --abbrev=0
-  ├── SummaryScanner     — git log + glob docs/specs/*/task-*-summary.md
-  ├── ChangeExtractor    — parse summary doc markdown sections
-  ├── ChangeClassifier   — map to 🔴 breaking / 🟡 prominent / 🔵 context
-  ├── NotesRenderer      — markdown generation (public + internal)
-  └── GitHubPublisher    — git tag + GitHub release creation
-```
-
----
+1. **Derive the delta**: `git log $(git describe --tags --abbrev=0)..main --oneline` — every line is a squash-merged PR title (the changelog spine). Scope a second pass to the shipped surface to separate consumer-facing from internal — **the authoritative shipped-surface list is `package.json` `files[]`** (fifteen-plus roots beyond `src/`, including `governance/` and the other served-content roots; scoping to `src/` alone would have dropped v14.0.0's docs-corpus entry).
+2. **Classify**: for each change, read its task summary (`docs/specs/…`) or PR body for substance; classify 🔴 breaking / 🟡 minor / 🔵 patch-or-internal. Issue-driven work has no summary doc — its PR title and body are the record; do not assume spec-shaped work is the whole delta (the retired tool's fatal assumption).
+3. **Recommend the bump; the release owner ratifies.** Removals or behavior breaks → major. New behavior → minor. Fixes/internal → patch.
+4. **Hand-author the notes** at `docs/releases/release-X.Y.Z.md` (v14.0.0 is the format precedent). Notes ride the release PR with the version bump and any token-index regeneration.
+5. **Publish per RELEASE-FLOW.md** (repo-internal; and the dual-registry playbook it references): release PR → the release owner merges → publish from merged `main` → then tag and GitHub release: `git tag -a vX.Y.Z && git push origin vX.Y.Z && gh release create vX.Y.Z --notes-file docs/releases/release-X.Y.Z.md`.
 
-## CLI Commands
-
-| Command | What It Does | When to Use |
-|---------|-------------|-------------|
-| `npm run release:analyze` | Scan changes since last tag, display recommendation | Check what's accumulated |
-| `npm run release:notes` | Generate markdown release notes to `docs/releases/` | Preview release content |
-| `npm run release:run` | Full release: notes + tag + GitHub publish | Actual release |
-| `npm run release:run -- --dry-run` | Preview release without tagging or publishing | Pre-release check |
-
-Shell wrapper: `./.kiro/hooks/release-manager.sh analyze|notes|release`
-
----
+## Discovering What Changed and Why
 
-## AI Agent Decision Points
+Agents answering "what changed, and why?" — for any purpose, not just releases — follow the record chain. *(Consumer note: in a consumer repo only the served governance corpus is reachable; the chain's other paths are DesignerPunk-internal — the PATTERN transfers, the paths don't.)*
 
-### 1. Summary Document Quality
-Release notes are generated from summary docs. Better summaries → better release notes.
-- **What Was Done** → becomes the change description
-- **Key Changes** → becomes the bullet points
-- **Deliverables** → drives priority classification (🔴/🟡/🔵)
+1. **What, at a glance**: squash-commit titles on `main` (`git log vX..vY --oneline`, or between any two points). Every commit is a PR with a disciplined title.
+2. **What, curated per release**: `docs/releases/release-X.Y.Z.md` — hand-authored, consumer-facing framing, breaking changes called out with migration guidance.
+3. **Why, per task**: `docs/specs/[spec]/task-N-summary.md` (public summary) and `.kiro/specs/[spec]/completion/` (detailed record) — for spec-shaped work. For issue-driven work: the PR body and any `.kiro/issues/` record.
+4. **Why, decision-grade**: `.kiro/docs/ballots/` (ratified decisions with their evidence and counter-arguments) and `governance/classification-map.md` (per-rule classifications with dated history). When a change traces to a ruling, the ballot is the authoritative why.
 
-### 2. Deliverables Section
-When present, the `## Deliverables *(optional)*` section drives classification directly:
-- `🔴` → breaking/consumer-facing → major bump
-- `🟡` → ecosystem → minor bump
-- `🔵` → internal/context → patch bump
-
-When absent, keyword heuristics apply (less accurate, human-reviewed anyway).
-
-### 3. Summary Document Location
-Must be `docs/specs/[spec-name]/task-N-summary.md` — the scanner looks here via git log.
-
----
-
-## Post-Commit Analysis
-
-`commit-task.sh` runs `release:analyze` after each task commit (non-blocking, fails silently). This provides immediate feedback on accumulated change significance. Skip with `--no-analyze` flag.
-
----
+## Historical Note
 
-*For operational task completion workflow, see Process-Development-Workflow.md.*
+The retired tool's own history is instructive: it replaced a 203-file predecessor (Spec 065's rebuild), and its retirement continues that simplification — 203 files → 24 files → a recipe — completed once the PR gate supplied, as a by-product of merge discipline, the structured change record the tooling existed to reconstruct. Records: Spec 065 (the rebuild), the Q6 ballot (the retirement), `docs/releases/release-14.0.0.md` (the live trial that settled it).

package/governance/rosetta-system-principles.md

@@ -13,7 +13,7 @@ description: Rosetta System foundational principles — primitive-to-semantic hi
 **Scope**: cross-project
 **Layer**: 2
 **Relevant Tasks**: token-development, architecture, spec-planning
-**Last Reviewed**: 2026-01-03
+**Last Reviewed**: 2026-07-09
 
 ---
 
@@ -138,10 +138,12 @@ Mathematical foundation allows documented exceptions for design requirements:
 | **Radius** | Shape definition | radius100, radius200 | radius.button, radius.card |
 | **Shadow** | Depth and elevation | shadowBlur200, shadowOpacity300 | shadow.container, shadow.modal |
 | **Glow** | Emphasis effects | glowBlur200, glowOpacity100 | glow.focus, glow.highlight |
-| **Opacity** | Transparency | opacity048, opacity080 | opacity.disabled, opacity.hover |
+| **Opacity** | Transparency | opacity048, opacity080 | opacity.ghost, opacity.heavy |
 | **Blend** | Color modification | blend100, blend200 | blend.hoverDarker, blend.focusSaturate |
 | **Border** | Edge definition | borderWidth100, borderWidth200 | border.input, border.focus |
 | **Motion** | Animation timing | duration250, easingStandard | motion.floatLabel |
+| **Sizing** | Component dimensions (width, height, box size) | size100, size300 | - |
+| **Blur** | Edge softness, radial spread, backdrop obscuring (composed into Shadow, Glow) | blur100, blur200 | - |
 | **Layering** | Stacking order | - | zIndex.modal, elevation.card |
 | **Accessibility** | WCAG compliance | tapArea44, tapArea48 | accessibility.touchTarget |
 
@@ -522,8 +524,8 @@ Rosetta Token System
 Rosetta System documentation is accessible via MCP:
 
 ```
-get_document_summary({ path: ".kiro/steering/rosetta-system-principles.md" })
-get_section({ path: ".kiro/steering/rosetta-system-principles.md", heading: "Mathematical Relationships" })
+get_document_summary({ path: "rosetta-system-principles" })
+get_section({ path: "rosetta-system-principles", heading: "Mathematical Relationships" })
 ```
 
 ---
@@ -581,8 +583,8 @@ get_section({ path: ".kiro/steering/rosetta-system-principles.md", heading: "Mat
 ## Related Documentation
 
 - [Stemma System Principles](stemma-system-principles) - Relational foundation for component development
-- [Civitas System Overview](civitas-system-overview) - Governance foundation for operational consistency
-- [DesignerPunk Systems Overview](designerpunk-systems-overview) - Visual architecture of all three systems
+- [Civitas System Overview](../.kiro/steering/Civitas-System-Overview.md) - Governance foundation for operational consistency
+- [DesignerPunk Systems Overview](../.kiro/steering/DesignerPunk-Systems-Overview.md) - Visual architecture of all three systems
 - [Token System Overview](../../docs/token-system-overview.md) - Master document mapping token files
 - [Token Quick Reference](token-quick-reference) - Token documentation routing
 - [Token Architecture 2.0 Mathematics](../../preserved-knowledge/token-architecture-2-0-mathematics.md) - Detailed mathematical formulas

package/governance/stemma-system-principles.md

@@ -13,7 +13,7 @@ description: Foundational principles and governance for systematic component dev
 **Scope**: cross-project
 **Layer**: 2
 **Relevant Tasks**: component-development, architecture, spec-planning
-**Last Reviewed**: 2026-01-01
+**Last Reviewed**: 2026-07-09
 
 ---
 
@@ -127,7 +127,7 @@ Behavioral contracts work uniformly across web, iOS, and Android:
 | **Data Displays** | Information presentation | DataDisplay-Base | Placeholder |
 | **Dividers** | Visual separation | Divider-Base | Placeholder |
 | **Loading** | Progress indication | Loading-Base | Placeholder |
-| **Navigation** | Wayfinding | Nav-Base | Placeholder |
+| **Navigation** | Wayfinding | Nav-Header-Base | Active |
 
 ### Family Inheritance Structure
 
@@ -161,7 +161,8 @@ base_contracts:
   - validatable
   - float_label_animation
   - error_state_display
-  - disabled_state
+  # No disabled_state — DesignerPunk does not support disabled states
+  # (adjudicated 2026-07-15). If unavailable, don't render the component.
 
 # Input-Text-Email extends with:
 extended_contracts:
@@ -554,11 +555,9 @@ Input-Text-Base:
       type: string
       required: false
       description: Placeholder text when empty
-    disabled:
-      type: boolean
-      required: false
-      default: false
-      description: Whether input is disabled
+    # No `disabled` prop — DesignerPunk does not support disabled states
+    # (adjudicated 2026-07-15). If the field is unavailable, don't render it;
+    # use `readOnly` when the value should stay visible but not be editable.
     error:
       type: string
       required: false
@@ -577,10 +576,9 @@ Input-Text-Base:
       description: Displays error message and visual error indication
       platforms: [web, ios, android]
       required: true
-    - name: supports_disabled_state
-      description: Prevents interaction when disabled
-      platforms: [web, ios, android]
-      required: true
+    # No supports_disabled_state contract — DesignerPunk does not support
+    # disabled states for usability and accessibility reasons (adjudicated
+    # 2026-07-15). If unavailable, don't render the component.
   
   tokens:
     - typography.input.*
@@ -712,7 +710,10 @@ LoginForm:
   behavioral_contracts:
     - form_validation_on_submit
     - field_validation_on_blur
-    - submit_button_disabled_until_valid
+    # Submit button stays interactive at all times — validation runs on press
+    # and surfaces field errors. DesignerPunk does not support disabled states
+    # (adjudicated 2026-07-15), so never gate the button on form validity.
+    - submit_validates_on_press
 ```
 
 #### Feed Post Pattern
@@ -828,8 +829,8 @@ Rosetta Token System
 Stemma System documentation is accessible via MCP:
 
 ```
-get_document_summary({ path: ".kiro/steering/stemma-system-principles.md" })
-get_section({ path: ".kiro/steering/stemma-system-principles.md", heading: "Component Schema Format" })
+get_document_summary({ path: "stemma-system-principles" })
+get_section({ path: "stemma-system-principles", heading: "Component Schema Format" })
 ```
 
 ---
@@ -886,8 +887,8 @@ get_section({ path: ".kiro/steering/stemma-system-principles.md", heading: "Comp
 
 ## Related Documentation
 
-- [Civitas System Overview](civitas-system-overview) - Governance foundation for operational consistency
-- [DesignerPunk Systems Overview](designerpunk-systems-overview) - Visual architecture of all three systems
+- [Civitas System Overview](../.kiro/steering/Civitas-System-Overview.md) - Governance foundation for operational consistency
+- [DesignerPunk Systems Overview](../.kiro/steering/DesignerPunk-Systems-Overview.md) - Visual architecture of all three systems
 - [Primitive vs Semantic Usage Philosophy](primitive-vs-semantic-usage-philosophy) - Comprehensive decision guidance for component selection
 - [Component Schema Format Specification](component-schema-format) - Formal schema structure and validation rules
 - [Component Readiness Status System](component-readiness-status) - Comprehensive readiness status definitions and transition guidelines

package/mcp-server/src/index.ts

@@ -346,7 +346,15 @@ class MCPDocumentationServer {
   }
 
   /**
-   * Set up graceful shutdown handlers
+   * Set up graceful shutdown handlers.
+   *
+   * stdin EOF ('end'/'close') is a first-class shutdown trigger: a stdio MCP server
+   * whose parent client died (or gracefully closed the pipe) has no one to serve, but
+   * the file watcher keeps the event loop alive forever — found live at Spec 122 U3
+   * (~230 orphaned servers accumulated across harness runs, wedging later boots).
+   * Self-exiting on EOF also makes graceful client closes immediate: the MCP SDK's
+   * StdioClientTransport.close() ends stdin and waits up to 2s for exactly this exit
+   * before escalating to SIGTERM.
    */
   private setupShutdownHandlers(): void {
     const shutdown = async () => {
@@ -356,6 +364,8 @@ class MCPDocumentationServer {
 
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    process.stdin.on('end', shutdown);
+    process.stdin.on('close', shutdown);
   }
 }
 
@@ -417,11 +427,19 @@ async function main(): Promise<void> {
   await server.start();
 }
 
-// Run the server
-main().catch((error) => {
-  console.error('[MCP Server] Fatal error:', error);
-  process.exit(1);
-});
+// Run the server ONLY when this module is the process entry point (executed
+// directly — `node mcp-server/dist/index.js`, or the esbuild `dist/mcp/docs-mcp.js`
+// bundle a consumer launches). Importing this module as a LIBRARY (Spec 122 imports
+// the re-exported WORKFLOW_RULES from the package entry) must NOT start the server;
+// the previous unconditional call started an MCP server as an import side effect.
+// This module is CommonJS (tsconfig `module: commonjs`), so `require.main === module`
+// is the correct entry check — verified to still fire under the esbuild CJS bundle.
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('[MCP Server] Fatal error:', error);
+    process.exit(1);
+  });
+}
 
 // Export for testing
 export { MCPDocumentationServer };