Conversation
A catalogue member was invisible to calm diff. Adding or removing one reported no change at all, and hasChanges stayed false, so calm diff --exit-code passed. An unchanged member appeared in no bucket, so the Hub painted it with no diff status. The catalogue is a choice block, so it is read as one more declaration source and expandAlternatives flattens it into the existing partition. Members land in the buckets that already exist. No new buckets, no change to NodeChange or hasChanges. An items schema that declares a node directly is not read, matching validation and the pattern renderer. The allOf traversal was written for prefixItems only, so it becomes findField, which takes what the caller is after. Reporting a change in obligation is out of scope and filed as finos#3111. It reproduces on main with no items involved.
The guide described prefixItems in sixteen places and never mentioned items, so an agent following it could only write patterns where every declared element is built. Adds a worked catalogue example, a table choosing between the two sites by obligation, the four rules items carries, and the requirement that a decision stays in relationships prefixItems.
Both pages taught the positional model only. Neither mentioned that a pattern can list candidates an architecture may add.
github-actions
Bot
added
cli
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
A pattern may declare nodes and relationships under
itemsas well asprefixItems. None of the documentation said so. The agent authoring guide describedprefixItemsin sixteen places and never mentioneditems, so an agent following it could only write patterns where every declared element is built. The two user-facing pages taught the positional model alone.This is the documentation half of #2859, and it lands last so the guidance is never ahead of the tooling.
Part of #2859.
PR sequence
Six stacked PRs, each reviewable alone, in this order:
prefixItemsalternatives — the pre-existing gaps that had to be fixed firstitemsin pattern validationitemsin generationitemsin the pattern diagramitemsin the pattern differitemsin the VS Code pattern pickerGitHub will not let a cross-fork PR target a branch in my fork, so all of them sit on
mainand each diff carries the ones below it. The commits to review here are the last two.What the authoring guide gains
A worked catalogue example, a table that chooses between the two declaration sites by obligation rather than by how many candidates there are, and the four rules
itemscarries — a member must sit insideoneOf/anyOf,maxItemsmust leave room, two members that can coexist may not share ids the way two alternatives of one entry may, anditemscannot cap how many times one member is used. It also states that a decision stays inrelationships.prefixItems.The example is not hand-written prose. I extracted the JSON from the file, wrapped it in a minimal pattern and ran
calm validate(no errors) andcalm generate(builds the positional node, correctly omits the unselected catalogue members).What the user documentation gains
A list entry and a bullet in
core-concepts/patterns.md, two table rows and a learning objective in the patterns tutorial. Both are deliberately light — the full contract lives inPATTERN-DECISIONS.md.One correction beyond adding
items: the tutorial said an architecture satisfying a pattern "is free to add extra nodes, relationships, interfaces, and metadata". That stops being true once a pattern declaresitems, which constrains what those extras may be.Gotcha
docs(calm-ai)triggers a CLI patch release —cli/.releaserc.jsoncarries release rules for thecalm-aiscope. Commitlint also warns on that scope, becausecalm-aiis missing from itsscope-enumwhile the release config has seven rules for it. Both are pre-existing config inconsistencies, not introduced here.Type of Change
No code changes.
Affected Components
cli/)calm/)calm-ai/)calm-hub/)calm-hub-ui/)calm-server/)calm-widgets/)docs/)shared/)calm-plugins/vscode/)Commit Message Format ✅
docs(calm-ai): document items catalogues in the pattern authoring guidedocs: describe items catalogues in the pattern documentationTesting
The documented example was validated and generated with the CLI, as above. The Docusaurus site builds clean.
Checklist
🤖 Generated with Claude Code