[US-263] feat: coupling-balance guideline + assess-coupling capability

.claude/skills/pair-capability-assess-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pair-capability-assess-architecture
 description: "Evaluates and recommends an architecture pattern (layered, hexagonal, microservices, modular monolith, etc.) when the choice is open. Output-only: emits a proposal + target for /pair-capability-record-decision to persist."
-version: 0.5.0
+version: 0.6.0
 author: Foomakers
 ---
 
@@ -42,6 +42,7 @@ Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standard
    - [Architecture README](../../../.pair/knowledge/guidelines/architecture/README.md) — decision tree, complexity matrix, selection criteria
    - [Architectural Patterns](../../../.pair/knowledge/guidelines/architecture/architectural-patterns/README.md) — pattern descriptions and trade-offs
    - [Project Constraints](../../../.pair/knowledge/guidelines/architecture/project-constraints/README.md) — team, platform, deployment constraints
+   - [Coupling Balance](../../../.pair/knowledge/guidelines/architecture/design-patterns/coupling-balance.md) — the three-dimensional coupling model (integration strength × distance × volatility + balance rule); its criteria inform pattern scoring in Step 3 (a pattern that lowers strength or aligns distance to volatility scores higher for a volatile, tightly-coupled domain)
 2. **Act**: If PRD exists, read [adoption/product/PRD.md](../../../.pair/adoption/product/PRD.md) for project context (team size, scale, compliance).
 3. **Verify**: Every file listed in 1-2 above has been read; any that's missing follows [Graceful Degradation](#graceful-degradation) (ask the developer directly) instead of silently proceeding to Step 3.
 

.claude/skills/pair-next/SKILL.md

@@ -7,7 +7,7 @@ author: Foomakers
 
 # /pair-next — Project Navigator
 
-Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 39-skill catalog across all lifecycle phases.
+Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 40-skill catalog across all lifecycle phases.
 
 ## Arguments (optional)
 
@@ -37,9 +37,9 @@ Keep only candidate issues that carry the given label. `--filter` takes a **sing
 
 The scope is **stateless across steps**. Every run — and every step of a multi-step run — re-queries the PM tool and **re-evaluates** `--root` and `--filter` against the **current** board state. If an issue's tags change between steps (e.g. a review raises `risk:yellow` → `risk:red`), the next step's selection reflects the change immediately. `/pair-next` never reuses a selection computed in a previous step.
 
-## Skill Catalog (39 skills)
+## Skill Catalog (40 skills)
 
-The catalog is **derived from the installed corpus**: every skill directory under `.skills/` must appear here — 9 process + 29 capability + `/pair-next` itself = 39. If an installed skill is missing from these tables (or a row names a skill that is not installed), the catalog has drifted: update the tables, the stated counts, and the cascade rows together.
+The catalog is **derived from the installed corpus**: every skill directory under `.skills/` must appear here — 9 process + 30 capability + `/pair-next` itself = 40. If an installed skill is missing from these tables (or a row names a skill that is not installed), the catalog has drifted: update the tables, the stated counts, and the cascade rows together.
 
 ### Process Skills (9)
 
@@ -55,7 +55,7 @@ The catalog is **derived from the installed corpus**: every skill directory unde
 | `/pair-process-implement`       | Sprint Execution   | Implement story tasks with TDD                  |
 | `/pair-process-review`          | Sprint Execution   | Review PR through structured phases             |
 
-### Capability Skills (29)
+### Capability Skills (30)
 
 | Skill                    | Category        | Description                                                                  |
 | ------------------------ | --------------- | ---------------------------------------------------------------------------- |
@@ -81,6 +81,7 @@ The catalog is **derived from the installed corpus**: every skill directory unde
 | `/pair-capability-assess-observability`  | Assessment      | Assess observability strategy                                                |
 | `/pair-capability-assess-security`       | Assessment      | Assess security posture (review verdict + one-shot audit)                    |
 | `/pair-capability-assess-cost`           | Assessment      | Classify cost exposure (green/yellow/orange/red) at review — output-only     |
+| `/pair-capability-assess-coupling`       | Assessment      | Assess coupling balance (strength × distance × volatility) — diff verdict + full audit |
 | `/pair-capability-analyze-debt`          | Analysis        | Analyze technical debt with prioritization                                   |
 | `/pair-capability-analyze-code-quality`  | Analysis        | Analyze code quality with metrics                                            |
 | `/pair-capability-estimate`              | Planning        | Estimate story using adopted methodology                                     |
@@ -218,4 +219,4 @@ See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standar
 - This skill is read-only: it inspects state but never modifies files or PM tool data.
 - Row order encodes the tie-break (delivery proximity) — see the **Tie-break** note under the Step 3 table.
 - Re-run `/pair-next` after completing any skill to get an updated recommendation.
-- **Full catalog coverage**: nearly all of the 39 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (row 7 `/pair-capability-checkpoint`, rows 12-16 including `/pair-capability-grill`) or process-skill composition. `/pair-capability-publish-pr` will be reachable via `/pair-process-implement` once wired (not yet composed), so `/pair-next` cannot surface it today.
+- **Full catalog coverage**: nearly all of the 40 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (row 7 `/pair-capability-checkpoint`, rows 12-16 including `/pair-capability-grill`) or process-skill composition. `/pair-capability-publish-pr` will be reachable via `/pair-process-implement` once wired (not yet composed), so `/pair-next` cannot surface it today.

.pair/adoption/decision-log/2026-07-25-ul-borrowed-terms-and-docs-site-dissemination-ownership.md

@@ -0,0 +1,45 @@
+# DDR: Borrowed-term marking in UL tables + the docs site as a dissemination channel
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-25
+
+## Context
+
+Two attribution defects surfaced while analysing PR #381 (story #263, coupling-balance guideline + `assess-coupling`). Both are boundary-documentation defects in `adoption/tech/boundedcontext/`, not code:
+
+1. **Duplicate owned term.** `development-collaboration.md` declared `Adoption` in its own Ubiquitous Language table ("a recorded decision about which practice, tool, or pattern the project follows"), while `adoption/product/context-map.md` assigns `Adoption` to the **Adoption & Guidelines** subdomain and `knowledge-standards.md` owns `Adoption file`. The same term appeared as *owned* in two bounded contexts with two definitions — the classic ubiquitous-language collision. Development Collaboration does legitimately touch adoptions (skills read them), so deleting the row would lose real information.
+2. **Unattributed deployable.** `apps/website/**` maps to no registered subdomain, and the existing "ownership splits by concern, not by path" rule was scoped explicitly to `packages/knowledge-hub/dataset/.pair/knowledge/**` — it said nothing about the site. Every PR touching the docs site therefore had to re-invent an attribution. The same PR's `$scope: full` dogfood independently found *website ↔ knowledge-hub dataset* to be the repo's single **CRITICAL** coupling: skill-catalog rows and `N skills` counts hand-copied across ~10 `.mdx` files. The missing ownership rule and the CRITICAL coupling are the same defect seen from two sides — nothing declared the site's facts to be derived rather than authored.
+
+**Hard to reverse / surprising without context:** ownership rules are cited by every subsequent PR's bounded-context analysis and by `/pair-capability-assess-coupling`; changing them later invalidates prior attributions.
+
+**Real trade-off considered:** the rejected alternative for (2) was to register a new subdomain (e.g. "Documentation & Dissemination"). Rejected — the site produces no knowledge of its own, it renders facts other subdomains author; a new subdomain would legitimise the duplication instead of forbidding it, and the catalog's stated philosophy favours fewer contexts for a two-person team.
+
+## Decision
+
+1. **Borrowed-term convention.** A term a context consumes but does not own is marked *(consumed)* in its UL table and names its owning context, reusing the owner's definition in substance. A term is *owned* in exactly one bounded context; an unmarked duplicate across two UL tables is a boundary defect, not a synonym. Applied: `development-collaboration.md` now lists `Adoption *(consumed)* — owned by Knowledge & Standards (Adoption & Guidelines)`.
+2. **The docs site is a dissemination channel, and "splits by concern" extends to it.** `apps/website/**` is owned by **Integration & Process Standardization** as a distribution channel (build/deploy pipeline, routing/IA, the `docs-staleness` gate) and maps to no business subdomain. The facts it renders — catalog rows, skill/capability counts, guideline prose — are *authored-by* the content contexts (Knowledge & Standards for guidelines/how-to, Development Collaboration for skills/workflows) and only *disseminated-by* Integration.
+3. **Load-bearing corollary.** Those facts MUST be derived from the dataset, never hand-copied into `.mdx`. The derivation checks in `apps/website/lib/docs-staleness-check.ts` are the contract test of that derivation; hand-maintained duplication of dataset facts in the site is a CRITICAL coupling defect. This makes the rebalance already shipped in PR #381 (Check 2c — catalog row *content* single-sourced from dataset SKILL.md frontmatter) the enforced norm rather than a one-off cleanup.
+
+## Consequences
+
+### Benefits
+
+- Bounded-context attribution for a docs-site PR is now deterministic — no per-PR re-derivation, no silent double-attribution.
+- UL collisions become detectable by inspection: an unmarked duplicate term is, by definition, a defect.
+- The CRITICAL coupling cannot silently regress: the rule names the derivation contract that forbids re-introducing hand-copied dataset facts.
+
+### Trade-offs and Limitations
+
+- The convention is prose-enforced, not gate-enforced: no test asserts that `(consumed)` markers stay accurate or that a new `.mdx` fact is derived. Nothing reads `boundedcontext/*.md` programmatically today; adding a conformance check is a candidate follow-up if drift appears.
+- Integration & Process Standardization grows broader still (integration + process + KB distribution + site dissemination). Same limitation already recorded in DDR `2026-07-19-merge-kb-management-into-integration.md`; if dissemination grows its own concern it may warrant re-splitting, superseding both DDRs.
+
+## Context Map Impact
+
+- No change to `adoption/product/context-map.md` — it indexes the five registered subdomains, and no subdomain is added or removed.
+- `adoption/tech/boundedcontext/development-collaboration.md`: `Adoption` re-marked as a consumed term + borrowed-term convention stated under the UL table.
+- `adoption/tech/boundedcontext/integration-process-standardization.md`: Data Ownership gains the docs-site dissemination bullet and the derivation corollary.

.pair/adoption/tech/boundedcontext/development-collaboration.md

@@ -35,8 +35,10 @@ This context orchestrates the collaboration between developers and AI assistants
 | Term | Definition |
 | ---- | ---------- |
 | Workflow | A sequence of collaborative phases (requirements → design → implementation → review) between developer and AI assistant |
-| Adoption | A recorded decision about which practice, tool, or pattern the project follows |
 | Skill | An atomic, invocable unit of operational knowledge that an AI assistant executes |
+| Adoption *(consumed)* | A project's committed choice of a practice, tool, or process, recorded as a delta over KB defaults. **Owned by Knowledge & Standards** (subdomain Adoption & Guidelines); workflows and skills here *read* adoptions, they do not define or own them. |
+
+**Borrowed-term convention.** A term this context consumes but does not own is marked *(consumed)* and names its owning context, reusing that context's definition verbatim in substance. A term appears as owned in exactly one bounded context — an unmarked duplicate across two UL tables is a boundary defect, not a synonym.
 
 ## Quality Attributes
 

.pair/adoption/tech/boundedcontext/integration-process-standardization.md

@@ -29,6 +29,7 @@ This context manages all integration logic and process standardization for the p
 - Owns integration configurations, process definitions, and automation scripts.
 - Owns the KB dataset, its distribution artifacts/metadata, and the local KB cache.
 - **Ownership splits by concern, not by path.** This context owns the *packaging & distribution* of KB content — the dataset as a release artifact, the flatten/prefix/symlink transform, the `pair update` mirror, and the cache. It does **not** own the content's *authoring*: guidelines and conventions are authored and owned by **Knowledge & Standards**, skills and workflows by **Development Collaboration**. A file under `packages/knowledge-hub/dataset/.pair/knowledge/**` is therefore *authored-by* its content subdomain and *distributed-by* this context — its co-location in the dataset directory is packaging, not content ownership. (Resolves the recurring "same edit lands in two bounded contexts" attribution ambiguity.)
+- **The docs site is dissemination, and the same split applies.** `apps/website/**` is a separate deployable owned by this context as a *distribution channel*: its build/deploy pipeline, its routing/IA, and the `docs-staleness` gate. It maps to no business subdomain of its own. The **facts** it renders — skill catalog rows, `N skills` / `N capabilities` counts, guideline prose — are *authored-by* the content contexts (**Knowledge & Standards** for guidelines/how-to, **Development Collaboration** for skills/workflows) and only *disseminated-by* this context. Corollary, load-bearing: those facts MUST be derived from the dataset (single source of truth), never hand-copied into `.mdx`; the derivation checks in `apps/website/lib/docs-staleness-check.ts` are the contract test of that derivation. Hand-maintained duplication of dataset facts in the site is a CRITICAL coupling defect (see the `$scope: full` dogfood triage in story #263).
 
 ## Team Alignment
 

.pair/knowledge/getting-started.md

@@ -79,7 +79,7 @@ Welcome to the AI-Human pairing repository template! This guide provides essenti
 
 - **`way-of-working.md`**: Main process documentation – the starting point to understand the full workflow
 - **`getting-started.md`**: This guide – essential information to get started with the framework
-- **`skills-guide.md`**: Full catalog of 39 Agent Skills (9 process + 29 capability + 1 navigator) with composition patterns, adoption file mapping, and usage instructions
+- **`skills-guide.md`**: Full catalog of 40 Agent Skills (9 process + 30 capability + 1 navigator) with composition patterns, adoption file mapping, and usage instructions
 - **`how-to/`**: Step-by-step guides for each development phase and LLM collaboration
   - Process guides (01-11): Operational documentation for each phase
 - **`assets/`**: Templates, checklists, and document examples (e.g., PRD, bootstrap checklist)

.pair/knowledge/guidelines/architecture/design-patterns/README.md

@@ -78,6 +78,11 @@ This folder contains guidelines for establishing solid architectural foundations
    - Lazy, human-approved subdomain context split convention
    - Loading and conflict-flag instructions for brainstorm/refine sessions
 
+10. **Coupling Balance** (`coupling-balance.md`)
+    - Three-dimensional coupling model: integration strength × socio-technical distance × volatility
+    - The balance rule + severity criteria (critical/significant/tolerable)
+    - DDD-pattern mapping, fractal application, and test implications; criteria source for `assess-coupling`
+
 ## 🔄 Decision Support
 
 ### Pattern Selection Decision Tree