Skip to content

Commit 002bf47

Browse files
dmealingclaude
andcommitted
docs(changelog): the 0.23.0 vocabulary had no Added entry
The commit that introduced `@disposition`, `@trackedBy`, `status: planned` and optional `@level` on `requirement.architectural` touched no changelog. Three later entries then referred to "the 0.23.0 requirement vocabulary" as a thing that had been announced, so the headline feature of the next MINOR existed only in a commit message. Written from the feature commit rather than from memory, including the two measurements that justify the shape -- 235 ledger entries, 62 recorded gaps and no way to ask which had been ruled on -- and the reason a wording correction to the levelling guidance is a cross-port change: that text is byte-gated in expected-registry.json. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent cb1496e commit 002bf47

1 file changed

Lines changed: 53 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,59 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
77

88
## [Unreleased]
99

10+
### Added — a requirement records the DECISION about a gap, not just the gap (all five ports)
11+
12+
**New registered vocabulary on both `requirement.*` subtypes, which is why this line is a
13+
MINOR.** Purely additive: a ledger written against 0.22.x loads unchanged and produces the
14+
same diagnostics.
15+
16+
`@status: partial` said there IS a gap. It never said what anyone DECIDED about it, so a
17+
known-and-tolerated gap and a gap nobody has looked at were the same value. Dogfooding a real
18+
235-entry adopter ledger is what surfaced it: **62 recorded gaps, and no way to ask which of
19+
them had been ruled on** without writing a script. Three additions close that:
20+
21+
- **`@status: planned`** — intended, not built. Its `@implementedBy` **may dangle** (write the
22+
requirement before the entity exists) and it is exempt from the architectural universality
23+
check, which would otherwise fire on precisely the entries meant to apply to nothing yet. A
24+
`planned` entry **never counts toward object coverage** — without that rule the cheapest way
25+
to clear an unclaimed-entity warning would be to declare an intention, and the gate would
26+
measure ambition rather than work.
27+
- **`@disposition`** — closed enum `accepted` (understood, deliberately not closing) or
28+
`deferred` (will close, not now). **Absent means UNDECIDED**, and keeping that distinct is
29+
the point: folding it into `@status` would make "there is a gap" and "we chose to live with
30+
it" the same fact, and lose the question a review exists to ask.
31+
- **`@trackedBy`** — issue/ticket references, a string array. Free-form and deliberately
32+
**never resolved** (`verify` has no network), and deliberately not a workflow vocabulary:
33+
which sprint, who owns it and whether it is in progress live in the tracker, because two
34+
systems holding that answer will drift and only one of them is refreshed daily.
35+
36+
Two new warnings: a `@disposition` on a status with **no outstanding work** (there, the
37+
decision IS the status), and `deferred` naming **no ticket** — which is how a known problem
38+
becomes an unknown one.
39+
40+
**`meta verify` now prints a requirements summary on EVERY run, clean or not** — entry counts
41+
by status, entities claimed, and the number of gaps carrying no disposition. A gate that says
42+
nothing when it passes cannot be told apart from a gate that checked nothing, and a ledger
43+
that skipped a whole grain read exactly like a complete one.
44+
45+
**Architectural requirements can now nest.** `requirement.functional` declared a `requirement.*`
46+
child rule and `requirement.architectural` declared none — so an architectural node could nest
47+
under a *functional* parent but never under another architectural one, which made a quality
48+
taxonomy inexpressible. That asymmetry was an omission, not a design: flat-by-design would have
49+
rejected nesting under `functional` too. **`@level` is now OPTIONAL on `architectural`** —
50+
absent keeps the original flat, object-independent form (so every existing ledger stays valid),
51+
present opts the node into a tree, and from that point the same nesting and link-floor rules
52+
apply as to a functional node, so a grouping tier cannot quietly start naming entities. The
53+
first cut of that fired the universality check on levelled ORGANISATIONAL nodes, which name
54+
nothing by design; `mayReferenceModel()` is the right predicate, since it already encodes "is
55+
this tier allowed to name the model at all".
56+
57+
Also corrects the levelling guidance in the spec, the feature doc and the `metaobjects-authoring`
58+
skill: **L1–L3 are levels of abstraction and ownership in the problem domain, never a directory,
59+
package, deployable or module** — with the test that if a behaviour-preserving refactor would
60+
force a node to move, its level is wrong. That text is byte-gated in `expected-registry.json`,
61+
which is why a wording correction is a cross-port change rather than a doc edit.
62+
1063
### Fixed — the 0.23.0 requirement vocabulary reaches C#, Java, Kotlin and Python
1164

1265
**`main` was RED on four of five ports**, and had been since the commit that introduced

0 commit comments

Comments
 (0)