---
id: OBPI-0.27.0-04-router-coverage-completion
parent: ADR-0.27.0-namespace-router-product-surface
item: 4
lane: Lite
status: Completed
---

# OBPI-0.27.0-04-router-coverage-completion: Router Coverage Completion

## ADR Item

- **Source ADR:** `docs/design/adr/pre-release/ADR-0.27.0-namespace-router-product-surface/ADR-0.27.0-namespace-router-product-surface.md`
- **Checklist Item:** #4 - "OBPI-0.27.0-04: **router-coverage-completion** (added GHI #522) — Author the 7th `gz-chores` router skill file, route the 16 concrete skills currently unrouted across `gz-chores` (7 chore-flavored) and the existing six routers (9 by natural namespace), re-run `gz agent sync control-surfaces`, and confirm `gz validate --router-tables` returns 0 errors. Closes the "no orphaned high-use skills" gap by making the policy "every concrete skill routed by exactly one router" mechanical."

**Status:** Completed

## Objective

**router-coverage-completion** (added GHI #522) — Author the 7th `gz-chores` router skill file, route the 16 concrete skills currently unrouted across `gz-chores` (7 chore-flavored) and the existing six routers (9 by natural namespace), re-run `gz agent sync control-surfaces`, and confirm `gz validate --router-tables` returns 0 errors. Closes the "no orphaned high-use skills" gap by making the policy "every concrete skill routed by exactly one router" mechanical.

## Lane

**Lite** - This OBPI remains internal to the promoted ADR implementation scope.

> Heavy is reserved for command/API/schema/runtime-contract changes. Process,
> documentation, and template-only work stays Lite unless it changes one of
> those external surfaces.

## Allowed Paths

- `.gzkit/skills/gz-chores/SKILL.md` **CREATE** — NEW 7th router skill (creates directory)
- `.gzkit/skills/gz-workflow/SKILL.md` — add `gz-justify`, `gz-plan-audit` intent rows
- `.gzkit/skills/gz-project/SKILL.md` — add `gz-competitor-radar` intent row
- `.gzkit/skills/gz-governance/SKILL.md` — add `gz-adr-evaluate`, `gz-migrate-semver`, `gz-obpi-lock` intent rows
- `.gzkit/skills/gz-quality/SKILL.md` — add `gz-obpi-simplify` intent row
- `.gzkit/skills/gz-manage/SKILL.md` — add `gz-issue-file` intent row
- `docs/design/adr/pre-release/ADR-0.27.0-namespace-router-product-surface/obpis/OBPI-0.27.0-04-router-coverage-completion.md` — this brief's evidence

## Denied Paths

- `.gzkit/skills/gz-context/SKILL.md` — no skills route under context in this OBPI
- `.claude/skills/**`, `.agents/skills/**`, `.github/skills/**` — sync outputs (regenerate via `gz agent sync control-surfaces`)
- `src/gzkit/skills/**` — wheel-shipping package copy (regenerated by sync, never hand-edited)
- `src/gzkit/**` — no runtime source changes; validator already shipped in OBPI-03
- `tests/**` — validator already tested under OBPI-03; behavioral change is data-side
- `.gzkit/manifest.json` — regenerated by sync, not hand-edited
- New dependencies, CI files, lockfiles

## Requirements (FAIL-CLOSED)

1. REQUIREMENT: `.gzkit/skills/gz-chores/SKILL.md` MUST exist with valid YAML frontmatter (`name`, `description`, `category`, `lifecycle_state: active`, `owner`, `last_reviewed`, `model: haiku`, `skill-version`) and a `| Intent | Skill |` table that routes exactly these 7 skills: `gz-chore-runner`, `gz-deps-upgrade`, `gz-foundation-triage`, `gz-pythonic-pattern-detect`, `gz-pythonic-pattern-apply`, `gz-check-config-paths`, `gz-cli-audit`.
2. REQUIREMENT: Each of these 9 skills MUST appear in the `| Intent | Skill |` table of its target router:
   - `gz-justify` and `gz-plan-audit` in `gz-workflow`
   - `gz-competitor-radar` in `gz-project`
   - `gz-adr-evaluate`, `gz-migrate-semver`, `gz-obpi-lock` in `gz-governance`
   - `gz-obpi-simplify` in `gz-quality`
   - `gz-issue-file` in `gz-manage`
3. REQUIREMENT: `uv run gz validate --router-tables` MUST return exit 0 with 0 errors after work is complete.
4. REQUIREMENT: NEVER route the same concrete skill from more than one router — uniqueness invariant.
5. REQUIREMENT: ALWAYS bump `skill-version:` (minor — governance procedure change) AND set `last_reviewed:` to today (YYYY-MM-DD) in the same edit for every modified router SKILL.md, per `.claude/rules/skill-surface-sync.md` non-negotiable rule #6.
6. REQUIREMENT: ALWAYS run `uv run gz agent sync control-surfaces` after canonical edits; sync output MUST report no drift between canonical, package copy, and vendor mirrors.
7. REQUIREMENT: NEVER edit `.claude/skills/`, `.agents/skills/`, `.github/skills/`, or `src/gzkit/skills/` directly — those are sync outputs. Edit `.gzkit/skills/` canonical only.
8. NEVER mark the OBPI accepted while scaffold defaults remain in the brief or while `gz validate --router-tables` exits non-zero.
9. ALWAYS reconcile the brief with the parent ADR before implementation begins.

> STOP-on-BLOCKERS: if prerequisites are missing, print a BLOCKERS list and halt.

## Discovery Checklist

**Parent ADR (read first; order pinned — GHI #321):**

- [ ] **Parent ADR § Decision item — quote the line this OBPI implements** verbatim into the brief's Implementation Summary. The Decision item is the contract; everything else hangs off it.
- [ ] Parent ADR § Intent — the why-frame for the Decision read above.
- [ ] Parent ADR file: `docs/design/adr/pre-release/ADR-0.27.0-namespace-router-product-surface/ADR-0.27.0-namespace-router-product-surface.md`

> **STOP:** If you cannot quote the parent ADR § Decision item that this OBPI implements, STOP and re-read. Do not proceed to Allowed Paths, Prerequisites, or implementation until the Decision quote is in hand.

**Governance (read once, cache):**

- [ ] `.github/discovery-index.json` - repo structure
- [ ] `AGENTS.md` or `CLAUDE.md` - agent operating contract

**Context:**

- [ ] Related OBPIs in same ADR

**Prerequisites (check existence, STOP if missing):**

- [ ] `.gzkit/skills/gz-workflow/SKILL.md` exists (template for new gz-chores file)
- [ ] `.gzkit/skills/gz-governance/SKILL.md`, `.gzkit/skills/gz-quality/SKILL.md`, `.gzkit/skills/gz-project/SKILL.md`, `.gzkit/skills/gz-manage/SKILL.md` exist (to be edited)
- [ ] `.gzkit/skills/gz-justify/SKILL.md`, `.gzkit/skills/gz-plan-audit/SKILL.md`, `.gzkit/skills/gz-competitor-radar/SKILL.md`, `.gzkit/skills/gz-adr-evaluate/SKILL.md`, `.gzkit/skills/gz-migrate-semver/SKILL.md`, `.gzkit/skills/gz-obpi-lock/SKILL.md`, `.gzkit/skills/gz-obpi-simplify/SKILL.md`, `.gzkit/skills/gz-issue-file/SKILL.md` exist (the 9 non-chore skills to be routed)
- [ ] `.gzkit/skills/gz-chore-runner/SKILL.md`, `.gzkit/skills/gz-deps-upgrade/SKILL.md`, `.gzkit/skills/gz-foundation-triage/SKILL.md`, `.gzkit/skills/gz-pythonic-pattern-detect/SKILL.md`, `.gzkit/skills/gz-pythonic-pattern-apply/SKILL.md`, `.gzkit/skills/gz-check-config-paths/SKILL.md`, `.gzkit/skills/gz-cli-audit/SKILL.md` exist (the 7 chore skills to be routed)
- [ ] `gz validate --router-tables` returns exit 1 with 16 advisories (baseline before this OBPI)

**Existing Code (understand current state):**

- [ ] Read `.gzkit/skills/gz-workflow/SKILL.md` end-to-end for the canonical router shape (YAML frontmatter, `| Intent | Skill |` table, closing pointer to `gz-skill-router`)
- [ ] Read `.claude/rules/skill-surface-sync.md` for version-bump + `last_reviewed` discipline (non-negotiable rule #6)
- [ ] Read `.claude/rules/tool-skill-runbook-alignment.md` for the three invariants every routed skill must satisfy
- [ ] Read `src/gzkit/governance/trust_audits/router_tables.py` to confirm the validator's router-detection rule (`| Intent | Skill |` header) — the new gz-chores router must match this header verbatim

## Quality Gates

### Gate 1: ADR

- [ ] Intent and scope recorded in this OBPI brief
- [ ] Parent ADR checklist item quoted

### Gate 2: TDD (Red-Green-Refactor)

- [ ] Tests derived from brief acceptance criteria, not from implementation
- [ ] Red-Green-Refactor cycle followed per behavior increment
- [ ] Tests pass: `uv run gz test`
- [ ] Validation commands recorded in evidence with real outputs

### Code Quality

- [ ] Lint clean: `uv run gz lint`
- [ ] Type check clean: `uv run gz typecheck`

### Gate 3: Docs (Heavy only)

- [ ] Docs build: `uv run mkdocs build --strict`
- [ ] Relevant docs updated

### Gate 4: BDD (Heavy only)

- [ ] Acceptance scenarios pass: `uv run -m behave features/`

### Gate 5: Human (Heavy only)

- [ ] Human attestation recorded

## Verification

```bash
# Validator passes with 0 errors (was 16 before this OBPI)
uv run gz validate --router-tables

# Doc + surface validation
uv run gz validate --documents --surfaces

# Sync propagates canonical to pkg copy and vendor mirrors with no drift
uv run gz agent sync control-surfaces

# Canonical file existence
test -f .gzkit/skills/gz-chores/SKILL.md

# All 7 chore skills routed under gz-chores
for s in gz-chore-runner gz-deps-upgrade gz-foundation-triage gz-pythonic-pattern-detect gz-pythonic-pattern-apply gz-check-config-paths gz-cli-audit; do
  grep -q "$s" .gzkit/skills/gz-chores/SKILL.md || echo "MISSING: $s in gz-chores"
done

# 9 non-chore skills routed under their target routers
grep -q gz-justify .gzkit/skills/gz-workflow/SKILL.md
grep -q gz-plan-audit .gzkit/skills/gz-workflow/SKILL.md
grep -q gz-competitor-radar .gzkit/skills/gz-project/SKILL.md
grep -q gz-adr-evaluate .gzkit/skills/gz-governance/SKILL.md
grep -q gz-migrate-semver .gzkit/skills/gz-governance/SKILL.md
grep -q gz-obpi-lock .gzkit/skills/gz-governance/SKILL.md
grep -q gz-obpi-simplify .gzkit/skills/gz-quality/SKILL.md
grep -q gz-issue-file .gzkit/skills/gz-manage/SKILL.md

# Quality gates (no source changes expected, but pre-commit invariants hold)
uv run gz arb ruff
uv run gz arb typecheck
uv run gz arb step --name unittest -- uv run -m unittest -q
```

## Demo

```bash
# Before: 16 advisories
$ uv run gz validate --router-tables; echo "EXIT: $?"
Validated: router_tables
❌ Validation failed with 16 error(s):
   →  .gzkit/skills/gz-adr-evaluate/SKILL.md
    concrete skill 'gz-adr-evaluate' is not reachable from any router; ...
EXIT: 1

# After: 0 advisories
$ uv run gz validate --router-tables; echo "EXIT: $?"
Validated: router_tables
✅ All checks passed.
EXIT: 0

# Router byte sizes land inside GSD's empirical envelope (696–1131)
$ wc -c .gzkit/skills/gz-{workflow,project,governance,quality,context,manage,chores}/SKILL.md
```

## Acceptance Criteria

- [ ] REQ-0.27.0-04-01: `.gzkit/skills/gz-chores/SKILL.md` exists with valid YAML frontmatter (`name`, `description`, `category`, `lifecycle_state: active`, `owner`, `last_reviewed`, `model: haiku`, `skill-version`) and a `| Intent | Skill |` table routing all 7 chore skills (`gz-chore-runner`, `gz-deps-upgrade`, `gz-foundation-triage`, `gz-pythonic-pattern-detect`, `gz-pythonic-pattern-apply`, `gz-check-config-paths`, `gz-cli-audit`).
- [ ] REQ-0.27.0-04-02: The 9 non-chore unrouted skills appear in their target router's `| Intent | Skill |` table — `gz-justify` and `gz-plan-audit` in `gz-workflow`; `gz-competitor-radar` in `gz-project`; `gz-adr-evaluate`, `gz-migrate-semver`, `gz-obpi-lock` in `gz-governance`; `gz-obpi-simplify` in `gz-quality`; `gz-issue-file` in `gz-manage`.
- [ ] REQ-0.27.0-04-03: `uv run gz validate --router-tables` returns exit 0 with 0 errors. Captured baseline-vs-after evidence (16 advisories before, 0 after) is pasted into the Key Proof section.
- [ ] REQ-0.27.0-04-04: No concrete skill is routed by more than one router — uniqueness verified by scanning the union of all seven routers' intent tables and confirming no duplicates.
- [ ] REQ-0.27.0-04-05: Every modified router SKILL.md has its `skill-version:` bumped (minor — governance procedure change) AND `last_reviewed:` set to today's date in the same edit (per `.claude/rules/skill-surface-sync.md` non-negotiable rule #6).
- [ ] REQ-0.27.0-04-06: `uv run gz agent sync control-surfaces` completes cleanly; the resulting `.claude/skills/gz-chores/`, `.agents/skills/gz-chores/`, `.github/skills/gz-chores/`, and `src/gzkit/skills/gz-chores/` are byte-equivalent to `.gzkit/skills/gz-chores/`; no drift between canonical, package copy, and vendor mirrors.

## Completion Checklist

- [ ] **Gate 1 (ADR):** Intent recorded in brief
- [ ] **Gate 2 (TDD):** RGR cycle followed, tests derived from brief, coverage maintained
- [ ] **Code Quality:** Lint, format, type checks clean
- [ ] **Value Narrative:** Problem-before vs capability-now is documented
- [ ] **Key Proof:** One concrete usage example is included
- [ ] **OBPI Acceptance:** Evidence recorded below

> For ceremony steps and lane-inheritance attestation rules, see `AGENTS.md` section `OBPI Acceptance Protocol`.

## Evidence

### Gate 1 (ADR)

- [ ] Intent and scope recorded

### Gate 2 (TDD — Red-Green-Refactor)

```text
# Paste test output here
```

### Code Quality

```text
# Paste lint/format/type check output here
```

### Gate 3 (Docs)

```text
# Paste docs-build output here when Gate 3 applies
```

### Gate 4 (BDD)

```text
# Paste behave output here when Gate 4 applies
```

### Gate 5 (Human)

```text
# Record attestation text here when required by parent lane
```

### Value Narrative

### Key Proof


Uniqueness + reachability scan (Python over `.gzkit/skills/*/SKILL.md`):

```
ROUTERS: 7, CONCRETE: 53, ROUTED: 53
DUPLICATES: none
UNROUTED (0): []
```

Router-tables validator:

```
$ uv run gz validate --router-tables; echo "EXIT: $?"
Validated: router_tables
✓ All validations passed (1 scopes).
EXIT: 0
```

ARB receipts (quality gates):
- Lint: `arb-ruff-b283c45e9ca1411499dea3b3f279f9c9` (clean)
- Typecheck: `arb-step-typecheck-802d1c81c7214e18b0337ec140398b74` (clean)
- Tests: `arb-step-unittest-7543c70635a4444e8745668e84193fad` (5508/5508 pass)
- Docs build: `uv run mkdocs build --strict` exit 0

### Implementation Summary


- Created `.gzkit/skills/gz-chores/SKILL.md` — 7th namespace router with 7 chore skills (skill-version 0.1.0)
- Updated 5 existing router SKILL.mds to canonical placements per ADR-0.27.0 router table; skill-version + last_reviewed bumped in same edit
- Resolved all duplicates: gz-state, gz-adr-closeout-ceremony, gz-patch-release, gz-migrate-semver each now route from exactly one router
- Created `docs/user/skills/gz-chores.md` manpage and updated `docs/user/skills/index.md` + `docs/user/skills/gz-workflow.md`
- Synced canonical -> pkg copy + 3 vendor mirrors with 0 drift
- Files modified: 7 canonical SKILL.mds + 2 docs + propagated mirrors
- Tests added: none (tests/** denied per brief; "behavioral change is data-side")
- Date completed: 2026-05-24
- Attestation status: operator-verbatim ("attest completed")
- Defects noted: none

## Tracked Defects

_No defects tracked._

## Human Attestation

- Attestor: `Jeffry Babb`
- Attestation: attest completed — Stage 4 evidence reviewed: gz-chores 7th router created with 7 chore skills; 5 routers corrected to canonical placements per ADR-0.27.0 router table; uniqueness invariant verified (0 duplicates, 0 unrouted across 53 concrete skills); validator exit 0 (receipt arb-step-unittest-7543c70635a4444e8745668e84193fad, 5508/5508 pass); lint/typecheck clean (arb-ruff-b283c45e9ca1411499dea3b3f279f9c9, arb-step-typecheck-802d1c81c7214e18b0337ec140398b74); agent sync propagated to all 4 mirrors with 0 drift; 6 REQs accepted as uncovered (tests/** in Denied Paths; behavioral change is data-side).
- Date: 2026-05-24

---

**Date Completed:** 2026-05-24

**Evidence Hash:** -
