Capability Contract¶

A Capability record answers exactly one question: "what is provided, and who currently provides it?" This contract is the schema every Capability record must satisfy. It supersedes the two previously-fragmented, non-reconciled capability inventories (authority/Capability-Registry.md, whose data rows were column-shifted against their own header, and catalog/capabilities.md, a separate simpler table) — both are retired in favor of the single Portfolio Registry.

1. Required Fields¶

Field	Type	Description
`id`	string, unique	e.g. `CAP-HUB-001`. Never reused after retirement.
`name`	string	Human-readable capability name.
`owner`	string	Current implementing owner (a repo, product, or vendor).
`authority_ref`	string	ID of the Authority record this capability's ownership decision is bound to, if any.
`consumers`	list\<string>	Who/what depends on this capability.
`lifecycle_state`	enum	The Deletion Ledger state machine: `NOT_REVIEWED`, `UNDER_REVIEW`, `UPSTREAM_INSUFFICIENT`, `UPSTREAM_EQUIVALENT`, `RETAINED`, `REMOVED`. This field is machine-validated; do not invent new states.
`reason`	string	Human rationale (retention justification, gap description, or LOC removed) — always separate from `lifecycle_state`, never embedded in it.
`loc_removable`	string	`n/a`, `TBD`, or a signed integer with provenance (e.g. `-15 (branch deleted 2026-07-13)`).
`evidence_ref`	string	What was actually checked (a `--help` output, a source file, a bead ID) — not an assertion.

2. Column Discipline¶

Every Capability record is authored as one YAML mapping in the Portfolio Registry, never as a hand-typed markdown table row. This is the direct fix for the corruption found in authority/Capability-Registry.md on 2026-07-13, where every data row was silently shifted one column relative to its own 11-column header across all five sections of the file — a defect a generated projection cannot have, because the projection script binds each value to its named field, not to column position.

3. Relationship to Product and Pack¶

A Capability is provided by exactly one current owner at a time, but that owner may be a Product, a Pack, or an external vendor — see Portfolio Object Model §Capability. A Capability never directly references a Deployment; deployments realize Products/Packs, which in turn provide capabilities.

4. Worked Examples (real entities, migrated and de-corrupted from Capability-Registry.md)¶

- id: CAP-HUB-001
  name: Agent Platform Hub
  owner: ContextControl.ai
  authority_ref: null
  consumers: [Internal Operators]
  lifecycle_state: RETAINED
  reason: Core Business IP — no upstream candidate evaluated yet
  loc_removable: TBD
  evidence_ref: Bluefly Architecture (estimated, not yet verified)

- id: CAP-INT-001
  name: OSSA Adapter
  owner: OpenClaw
  authority_ref: null
  consumers: [OSSA Studio]
  lifecycle_state: RETAINED
  reason: Intentional thin composition over OpenClaw SDK
  loc_removable: n/a
  evidence_ref: SDK Parity Doc

- id: CAP-WT-001
  name: Worktree lifecycle
  owner: blu-cli (blu worktree)
  authority_ref: null
  consumers: [Bluefly engineers, background jobs]
  lifecycle_state: RETAINED
  reason: >
    gt worktree/polecat sandboxes operate only within Gas Town's own
    ~/gt/<rig>/crew/ rig-and-crew model; blu-worktree manages NAS-bare-repo
    product-repo checkouts with no rig/crew concept, plus prune/status/
    issue-linking neither upstream command has. Different capability domain.
  loc_removable: "n/a (no upstream candidate covers this domain)"
  evidence_ref: "gt worktree --help, gt polecat --help, blu-cli/src/commands/blu-worktree.ts (2026-07-13)"

- id: CAP-GUARD-001
  name: Canonical-repo protection
  owner: null
  authority_ref: AUTH-RUNTIME-GT-001
  consumers: [All agent sessions]
  lifecycle_state: REMOVED
  reason: >
    gt tap guard (PreToolUse, exit 2) is the upstream owner; blu-cli's
    parallel pre-commit mechanism (commit 27f7457, chore/hq-k7eq-execution-boundary)
    was a duplicate, verified live and deleted (local + origin) 2026-07-13.
  loc_removable: "-15 (branch deleted 2026-07-13, local + origin)"
  evidence_ref: "bead hq-58wi, bead hq-k7eq, gt tap --help"

This contract governs Capability structure only. See Authority Contract for what decides ownership, and Portfolio Object Model for how capabilities compose into Products.