The rule-key proposal keys every unkeyed rule as a change proposal

problem

Keying every rule of a large corpus by hand is slow and uneven, and an agent asked to do it in one pass edits carriers with no reviewable record of what it intends.

outcome

Write one change proposal that adds a key to each unkeyed rule and flow entry in a scope, so an agent applies it after the proposal check and the corpus validates with no error.

rule.proposesKeys line 25 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:25

The rule-key proposal, recipe 48, writes one change proposal that adds a key to each unkeyed rule and flow entry in its scope, in the shape the change-proposal contract states, and edits nothing.

spec:consumers.upgrade-kit.rule-key-proposal.proposal-applies-clean · enabled

rule.keepsText line 26 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:26

Each change adds only the key marker to its entry and keeps the entry's text, so keying a rule changes no rule's meaning and no frozen projection's text.

spec:consumers.upgrade-kit.rule-key-proposal.proposal-applies-clean · enabled

rule.coinedKey line 27 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:27

Each key is coined from its entry's text by fixed steps, so the same graph and parameters give the same keys.

spec:consumers.upgrade-kit.rule-key-proposal.collision-and-unkeyable · enabled, spec:consumers.upgrade-kit.rule-key-proposal.proposal-applies-clean · enabled

rule.uniqueKey line 28 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:28

A coined key is lower camel on the rule-key grammar, unique among the rule and flow keys of its Spec, the keys it already carries and the keys coined before it, and never a name the carrier refuses as a key.

spec:consumers.upgrade-kit.rule-key-proposal.collision-and-unkeyable · enabled

rule.unkeyable line 29 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:29

An entry whose text yields no word to coin from is listed apart, with its Spec, entry and line, and gets no change; the recipe never invents a key from nothing.

spec:consumers.upgrade-kit.rule-key-proposal.collision-and-unkeyable · enabled

rule.applyAfterCheck line 30 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:30

An agent reads the proposal check per change: a change whose scope moved since the named commit goes to a person, and the remaining changes are applied as ordinary carrier edits, so one moved scope never holds back the whole proposal. A person may rename a coined key before it is applied. The proposal check grants no approval and edits nothing; conformance and honesty checks remain the only gate.

spec:consumers.upgrade-kit.rule-key-proposal.proposal-applies-clean · enabled

0 unkeyed rules.

Verifying examples

Given a probe Spec whose unkeyed rules read {rules: "A part fits the budget. / Every part fits the budget again. / Ο κανόνας ισχύει."}
When the rule-key proposal runs for it at a commit and the proposal check reads it against the graph of that commit
Then the proposal adds the keys {keys: "partFitsBudget, partFitsBudget2"}
Then the proposal leaves {unkeyable: 1} entries unkeyed
Then the proposal check reports {moved: 0} moved changes and {problems: 0} schema problems

Given a probe Spec whose unkeyed rules read {rules: "The bundle is composed on each invocation. / Each part fits the budget."}
When the rule-key proposal runs for it at a commit and the proposal check reads it against the graph of that commit
Then the proposal adds the keys {keys: "bundleComposedInvocation, partFitsBudget"}
Then the proposal leaves {unkeyable: 0} entries unkeyed
Then the proposal check reports {moved: 0} moved changes and {problems: 0} schema problems
Then the probe validates with {errors: 0} errors once an agent applies the proposal

Example space

Given a probe Spec whose unkeyed rules read {rules:string}
When the rule-key proposal runs for it at a commit and the proposal check reads it against the graph of that commit
Then the proposal adds the keys {keys:string}
Then the proposal leaves {unkeyable:number} entries unkeyed
Then the proposal check reports {moved:number} moved changes and {problems:number} schema problems
Then the probe validates with {errors:number} errors once an agent applies the proposal

proposalRecipe line 33 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:33

recipe 48, the rule-key proposal, takes params.commit, the commit whose graph it reads, required, and at most one scope, params.pack or params.specs, the whole corpus with neither; a missing commit, both scopes, or an id that does not resolve returns { diagnostics: [{ parameter, problem }] } and no proposal.

proposalAnswer line 34 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:34

{ scope, totals: { specs, entries, keyed, proposed, unkeyable }, proposal, unkeyable }, where scope is { corpus: true }, { pack } or { specs }, entries counts the rule and flow entries in scope, keyed those that already carry a key, proposal is the change-proposal document, or null when no entry needs a key, and unkeyable lists the entries no key could be coined for.

no citation recorded

proposalDocument line 35 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:35

{ "schema": "sdp-proposal/1", "base": "<commit>", "reason": "Key every rule and flow entry in <scope> so a review, a register row or an example can cite it.", "changes": [change] }, with <scope> the Pack id, the Spec ids joined by a comma and a space, or the corpus.

no citation recorded

keyChange line 36 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:36

{ "scope": ["<spec id>"], "request": "<request>", "text": "[#<key>] <entry text>", "reason": "Gives the entry the address <spec id>#rule.<key>." }, one per unkeyed entry, by Spec in scope order, then its rules before its flows, each in authored order; text is the entry's text as its carrier writes it once keyed, after its rule: or flow: label where it has one.

no citation recorded

keyRequest line 37 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:37

Add the key marker [#<key>] and one space at the start of the text of <entry> of <spec id>, at <file> line <line>, after its rule: or flow: label where it has one., with <entry> the location table's rule[<i>] or flow[<i>] and , at <file> alone when the line is not located.

no citation recorded

keyCoining line 38 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:38

decompose the text and drop combining marks; drop the bracketed groups that open it, such as [extension]; drop an 's or ’s not followed by an ASCII letter, digit or underscore, then any remaining apostrophe; split the rest into words at every character other than an ASCII letter or digit and at each change from a lowercase letter or digit to an uppercase letter; lowercase each word; drop the stop words, unless that leaves no word; drop the leading words that do not open with a letter and every repeat of a word kept before it; join the first three words left in lower camel case, the first all lowercase and each later one with its first letter uppercased.

stopWords line 39 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:39

a, an, the, and, or, but, nor, so, then, than, if, when, while, where, of, to, in, on, at, by, for, with, from, into, onto, as, per, via, over, under, about, is, are, was, were, be, been, being, do, does, did, has, have, had, can, could, may, might, must, shall, should, will, would, it, its, this, that, these, those, there, their, they, them, which, who, whom, whose, what, each, every, any, also, only and own.

no citation recorded

keyCollision line 40 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:40

a coined key already taken in its Spec, or equal to a key the carrier refuses, takes the smallest suffix from 2 up that makes it unique.

unkeyableRow line 41 · specs/consumers/upgrade-kit.rule-key-proposal.sdp.md:41

{ spec, entry, file, line, reason: "no word to coin a key from" }, with entry the location table's rule[<i>] or flow[<i>] and line null when not located.

no citation recorded

Verifier bindings

• spec:consumers.upgrade-kit.rule-key-proposal.collision-and-unkeyable · Two rules that coin one key stay apart, and a rule with no ASCII word stays unkeyed · declared · example enabled · specs/consumers/upgrade-kit.rule-key-proposal.collision-and-unkeyable.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 1: external run evidence from vitest 4.1.10

  Build: CI 380 · Branch: feature/roadmap-and-slices-v0 · Commit: 34909918bf0be0e849959644401797191cae379f · Start: 2026-10-22T17:40:31.456Z · Stop: 2026-10-22T17:42:16.171Z

  Name	Suite	Result	Duration
  applies unchanged scopes while sending only moved changes to a person	upgrade kit	passed	1.93 ms
  names a carrying Spec in every guide section	upgrade kit	passed	0.58 ms
  teaches the upgrade steps in the pinned order	upgrade kit	passed	1.14 ms
  teaches epic reparenting and advisory roadmap adoption	upgrade kit	passed	0.48 ms
  runs the guide's rules file on a clean corpus with no address parameters	upgrade kit	passed	26.18 ms
  names the recipes' carrying Specs and teaches rule-key proposal as the rule-key action	upgrade kit	passed	1.8 ms
  ships the guide and names every reported capability's law and measurement	upgrade kit	passed	17.05 ms
  counts rules, reasons and unknown external perspectives	upgrade kit	passed	21.17 ms
  coins collisions and lists an unkeyable entry	upgrade kit	passed	11.27 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	9.23 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	12.56 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	13.93 ms
  counts distinct step skeletons and vocabulary keys inherited through refines	capability adoption details	passed	15.36 ms
  counts distinct step skeletons and vocabulary keys inherited through verifies	capability adoption details	passed	17.05 ms
  counts repeated vocabulary and example steps once per skeleton within a Spec	capability adoption details	passed	3.68 ms
  counts all capabilities and deduplicates shared components and repeated Pack members	capability adoption details	passed	20.68 ms
  diagnoses detail null	capability adoption details	passed	2.27 ms
  diagnoses detail 1	capability adoption details	passed	2.16 ms
  diagnoses detail "all"	capability adoption details	passed	2.08 ms
  diagnoses detail {}	capability adoption details	passed	2.06 ms
  diagnoses detail "spec:missing"	capability adoption details	passed	1.97 ms
  diagnoses detail true	capability adoption details	passed	1.94 ms
  drops possessives and apostrophes before coining keys	rule-key proposal details	passed	2.38 ms
  preserves scope and entry order and skips existing keys and tags	rule-key proposal details	passed	12.62 ms
  diagnoses both scopes even when each resolves	rule-key proposal details	passed	2.4 ms
  diagnoses invalid parameters {}	rule-key proposal details	passed	2.06 ms
  diagnoses invalid parameters {"commit":""}	rule-key proposal details	passed	2.07 ms
  diagnoses invalid parameters {"commit":1}	rule-key proposal details	passed	1.99 ms
  diagnoses invalid parameters {"commit":"abc","pack":"pack:missing"}	rule-key proposal details	passed	1.73 ms
  diagnoses invalid parameters {"commit":"abc","specs":["spec:missing"]}	rule-key proposal details	passed	2.12 ms
  diagnoses invalid parameters {"commit":"abc","specs":[],"pack":"pack:missing"}	rule-key proposal details	passed	1.32 ms
  diagnoses invalid parameters {"commit":"abc","specs":"all"}	rule-key proposal details	passed	1.26 ms
  drops leading digit words before checking word repeats	not recorded	passed	1.48 ms

• spec:consumers.upgrade-kit.rule-key-proposal.proposal-applies-clean · A rule-key proposal passes the proposal check and validates once applied · declared · example enabled · specs/consumers/upgrade-kit.rule-key-proposal.proposal-applies-clean.sdp.md

Requirement drawing

Decisions

No decision record named.

• impl:protocol.rule-key-proposal-recipe · realizes the rule-key proposal in the shipped recipe catalog · test/upgrade-kit.test.ts:742

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.