Capability adoption counts where each capability is used and where it could apply

problem

An adopter learns which authoring capabilities its corpus uses, and where each could apply, only by writing a query per capability.

outcome

Report, for the whole corpus, each Pack and each Spec, how many places use each capability and how many places it could apply, from the graph alone.

rule.capabilityRows line 37 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:37

Capability adoption, recipe 47, reports one row per capability with the places that use it and the places it could apply, counted from the graph, each row naming the Spec that carries the capability's law.

spec:consumers.upgrade-kit.capability-adoption.counts-a-corpus · enabled

rule.corpusTotals line 38 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:38

Beside the rows it reports the corpus's size and its readiness statements: Specs, Packs, examples, decisions, anchored component units, the Specs stated ready and the Specs whose floor allows ready.

no example exercises it

rule.perPackAndSpec line 39 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:39

It counts each capability's places within each Pack's members and, on request, within each Spec, a place two members share counted once, so an adopter sees where each capability could apply.

no example exercises it

rule.outsideTheGraph line 40 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:40

A capability the graph does not hold, such as the perspectives a corpus keeps as files, is counted only from data the caller passes, and its row reads null otherwise; the recipe reads no file.

spec:consumers.upgrade-kit.capability-adoption.counts-a-corpus · enabled

rule.countsOnly line 41 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:41

A count is a place a capability could apply, never a score, a ranking or a finding, and the answer carries no findings.

no example exercises it

0 unkeyed rules.

Verifying examples

Given a probe corpus with {rules: 3} rule entries of which {keyed: 1} carry a key, and {relations: 2} authored relations of which {reasons: 1} carry a reason
When capability adoption runs over it without perspectives
Then the rule-key row reads {ruleKeys: "1 of 3"}
Then the relation-reason row reads {relationReasons: "1 of 2"}
Then the perspectives row reads {perspectives: "null of null"}

Example space

Given a probe corpus with {rules:number} rule entries of which {keyed:number} carry a key, and {relations:number} authored relations of which {reasons:number} carry a reason
When capability adoption runs over it without perspectives
Then the rule-key row reads {ruleKeys:string}
Then the relation-reason row reads {relationReasons:string}
Then the perspectives row reads {perspectives:string}

adoptionRecipe line 44 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:44

recipe 47, capability adoption, takes params.detail, false by default, true for every Spec row or a list of Spec ids for those rows, and params.perspectives, the list of perspective objects the corpus keeps, absent by default; another detail value returns { diagnostics: [{ parameter, problem }] }.

adoptionAnswer line 45 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:45

{ totals, capabilities, packs, specs, leftOut }, where totals is { specs, packs, examples, decisions, componentUnits, statedReady, floorReady }, capabilities holds one row per capability in the order below, packs one row per Pack in id order, specs the Spec rows detail asks for, empty by default, and leftOut holds the one line Spec rows; pass detail: true or a list of Spec ids. whenever a Spec row is left out, and is empty otherwise.

no citation recorded

capabilityRow line 46 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:46

{ capability, inUse, applicable, carriedBy }, where inUse counts the places that use the capability, applicable the places it could apply, and carriedBy is the id of the Spec that carries its law; a count the graph cannot give is null.

no citation recorded

capabilityList line 47 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:47

each row as capability (carriedBy): places used, of places it could apply. ruleKeys (spec:model.rule-keys): rule and flow entries that carry a key, of all rule and flow entries; questionKeys (spec:model.open-question-keys): open questions that carry a key, of all open questions; questionFields (spec:model.open-question-fields): open questions that carry decider, links, provisional or trigger, of all open questions; relationReasons (spec:model.relation-reasons): authored relations that carry a reason, of all authored relations; exercises (spec:model.rule-keys): declared verifies edges from an example that carry exercises, of all such edges; pinnedDeclarations (spec:extraction.contract-declarations): keyed Design entries whose value opens with a code span, of every keyed Design entry other than description; componentDesigns (spec:model.planned-architecture): components that have a component design, of the distinct components a component design or a component: anchor names; stepKeys (spec:carrier.step-keys): keyed example steps, of all example steps; termKeys (spec:model.term-addresses): keyed Model terms, of all Model terms; entryCitations (spec:extraction.entry-citations): pinned declarations an anchored line cites, of all pinned declarations; perspectives (spec:consumers.review-perspectives): the perspective objects passed, of null.

packRow line 48 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:48

{ id, members, capabilities }, where capabilities maps each capability but perspectives to { inUse, applicable } summed over the Pack's resolving members, except componentDesigns, which counts once each the components a member names as a component design or a component: anchor names when it satisfies a member, inUse being those that have a component design anywhere in the corpus.

no citation recorded

specRow line 49 · specs/consumers/upgrade-kit.capability-adoption.sdp.md:49

{ id, packs, inUse, couldApply }, where inUse maps each capability the Spec uses to its count and couldApply maps each capability with places left to applicable minus inUse, both leaving out perspectives and every zero, and componentDesigns counts as a Pack row does for that Spec alone; rows sort by id.

no citation recorded

Verifier bindings

• spec:consumers.upgrade-kit.capability-adoption.counts-a-corpus · Capability adoption counts keyed rules and reasoned relations · declared · example enabled · specs/consumers/upgrade-kit.capability-adoption.counts-a-corpus.sdp.md

  External run evidence from test/upgrade-kit.test.ts

  Test anchors: test:protocol.capability-adoption.counts-a-corpus, test:protocol.rule-key-proposal.collision-and-unkeyable, test:protocol.rule-key-proposal.proposal-applies-clean, test:protocol.upgrade-guide. Specs verified by those bindings: spec:consumers.upgrade-kit, spec:consumers.upgrade-kit.capability-adoption, spec:consumers.upgrade-kit.capability-adoption.counts-a-corpus, spec:consumers.upgrade-kit.rule-key-proposal, spec:consumers.upgrade-kit.rule-key-proposal.collision-and-unkeyable, spec:consumers.upgrade-kit.rule-key-proposal.proposal-applies-clean.

  Run 2: external run evidence from vitest 4.1.10

  Build: CI 439 · Branch: docs/articles-refresh-1 · Commit: 61576184ea9f39b7f91c51fef5ff991b0bf2d0e6 · Start: 2026-11-04T07:59:39.962Z · Stop: 2026-11-04T08:03:39.928Z

  Name	Suite	Result	Duration
  applies unchanged scopes while sending only moved changes to a person	upgrade kit	passed	3.25 ms
  names a carrying Spec in every guide section	upgrade kit	passed	2.21 ms
  teaches the upgrade steps in the pinned order	upgrade kit	passed	2.3 ms
  teaches epic reparenting and advisory roadmap adoption	upgrade kit	passed	4.22 ms
  runs the guide's rules file on a clean corpus with no address parameters	upgrade kit	passed	33.87 ms
  names the recipes' carrying Specs and teaches rule-key proposal as the rule-key action	upgrade kit	passed	2.01 ms
  ships the guide and names every reported capability's law and measurement	upgrade kit	passed	25.2 ms
  counts rules, reasons and unknown external perspectives	upgrade kit	passed	9.53 ms
  coins collisions and lists an unkeyable entry	upgrade kit	passed	8.61 ms
  executes the bound example against a fresh world	Capability adoption counts keyed rules and reasoned relations (spec:consumers.upgrade-kit.capability-adoption.counts-a-corpus)	passed	12.73 ms
  executes the bound example against a fresh world	A rule-key proposal passes the proposal check and validates once applied (spec:consumers.upgrade-kit.rule-key-proposal.proposal-applies-clean)	passed	38.74 ms
  executes the bound example against a fresh world	Two rules that coin one key stay apart, and a rule with no ASCII word stays unkeyed (spec:consumers.upgrade-kit.rule-key-proposal.collision-and-unkeyable)	passed	32.87 ms
  counts distinct step skeletons and vocabulary keys inherited through refines	capability adoption details	passed	37.78 ms
  counts distinct step skeletons and vocabulary keys inherited through verifies	capability adoption details	passed	10.92 ms
  counts repeated vocabulary and example steps once per skeleton within a Spec	capability adoption details	passed	4.61 ms
  counts all capabilities and deduplicates shared components and repeated Pack members	capability adoption details	passed	29.39 ms
  diagnoses detail null	capability adoption details	passed	3.81 ms
  diagnoses detail 1	capability adoption details	passed	3.99 ms
  diagnoses detail "all"	capability adoption details	passed	3.71 ms
  diagnoses detail {}	capability adoption details	passed	3.81 ms
  diagnoses detail "spec:missing"	capability adoption details	passed	4.37 ms
  diagnoses detail true	capability adoption details	passed	3.44 ms
  drops possessives and apostrophes before coining keys	rule-key proposal details	passed	4.02 ms
  preserves scope and entry order and skips existing keys and tags	rule-key proposal details	passed	24.97 ms
  diagnoses both scopes even when each resolves	rule-key proposal details	passed	3.99 ms
  diagnoses invalid parameters {}	rule-key proposal details	passed	3.75 ms
  diagnoses invalid parameters {"commit":""}	rule-key proposal details	passed	3.54 ms
  diagnoses invalid parameters {"commit":1}	rule-key proposal details	passed	3.44 ms
  diagnoses invalid parameters {"commit":"abc","pack":"pack:missing"}	rule-key proposal details	passed	3.38 ms
  diagnoses invalid parameters {"commit":"abc","specs":["spec:missing"]}	rule-key proposal details	passed	4.46 ms
  diagnoses invalid parameters {"commit":"abc","specs":[],"pack":"pack:missing"}	rule-key proposal details	passed	6.7 ms
  diagnoses invalid parameters {"commit":"abc","specs":"all"}	rule-key proposal details	passed	4.36 ms
  drops leading digit words before checking word repeats	not recorded	passed	3.84 ms

Requirement drawing

Decisions

No decision record named.

• impl:protocol.capability-adoption-recipe · realizes capability adoption in the shipped recipe catalog · test/upgrade-kit.test.ts:514

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.