fix: seven CLI defects a real end-to-end run exposed - #46
Draft
david-hudec-networg wants to merge 7 commits into
Draft
fix: seven CLI defects a real end-to-end run exposed#46david-hudec-networg wants to merge 7 commits into
david-hudec-networg wants to merge 7 commits into
Conversation
david-hudec-networg
added a commit
to david-hudec-networg/skills
that referenced
this pull request
Sep 7, 2026
It said nextid scans the workspace. It prefers a cache that goes stale, which is the opposite of the guarantee that sentence was offering. The hypotheses scaffold is not the only broken one either - the sweep behind TALXIS/ubml#46 found all thirteen types emit something their own schema rejects, so the advice is now validate after scaffolding rather than avoid one template. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Each is independent of the others and of anything else; together they are what
can be fixed without touching how templates are generated.
The hypotheses tree used an {id, text, ...} node and array children where the
schema wants HY-keyed maps. The process wrote an id property inside the item,
where the ID is the key and Process declares none. Both scaffolds were teaching
a shape the bundled validator refuses, which is worse than being merely broken:
the natural reading is that the schema is stricter than the docs, so you hand-
write around a validator that was right.
The entities schema set templateDefaults.entities.type to "business-object".
Entity has no type property and sets additionalProperties: false, so that one
default was enough on its own to keep every scaffolded entities document
invalid.
Verified: hypotheses and process now scaffold and validate clean. entities
still fails on an unrelated defect - the generated templates carry no property
information at all - which is the next change in this series.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
david-hudec-networg
force-pushed
the
fix/add-scaffolds-invalid-documents
branch
2 times, most recently
from
September 7, 2026 18:08
bf47bb1 to
06cc5af
Compare
This is the defect behind most of the invalid scaffolds. One line in
transformTemplateData:
properties: [], // every section, every type
TemplateSection never carried properties and the transform hardcoded an empty
list, so TEMPLATE_DATA held nothing for anything. The scaffolder's default path
builds an item from section.properties.filter(required), which is always empty,
and writes a bare key:
terms:
TM01000:
TM01000: with an empty body parses as null, not an object, and validate rejects
a file add has just written. The types that looked healthy were the ones with a
hand-written example in items.ts; nothing else stood between the generator and
the output.
Extraction now finds the schema for one item of a section - patternProperties
for an ID-keyed map, items for a sequence, either inline or behind a $ref into
types/ - and records name, type, description, required, enum values and default.
resolveRef returns null rather than throwing on a shape it does not recognise,
so an unfamiliar reference degrades to the previous behaviour instead of
breaking generation.
Three things fell out of reading the schema properly. Reference placeholders
were always AC#####, whatever the field accepts, so a scaffolded step link
failed its own pattern check; the prefix now comes from the referenced
definition's own pattern, StepRef declaring ^ST\d{5,}$. Required array and
object properties were filled with the string 'TODO'. And section ID prefixes
were matched with [A-Z]{2}, so roiAnalyses (ROI#####) became RO#####.
Sequence sections are still written as maps after this; that is the next commit.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
links and glossary categories are YAML sequences in the schema, and the scaffolder had one way of emitting a section, so it wrote them as maps keyed by an ID that does not belong there. They now scaffold as an empty list with the item shape in comments, rather than as a sample row. A links item requires from and to, and any value there points at step IDs the user has not created yet, so a populated sample fails cross-reference validation the moment it is written. An empty list validates and the comment still teaches the shape - including the correct reference prefix, which the previous commit made available. With this, every document type add can create scaffolds a document validate accepts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Asserts the property that was missing the whole time: scaffold a document of each type, then validate the workspace it landed in. It can fail. Rebuilt from pre-fix sources, all 13 cases fail; with the series applied, all 13 pass. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
david-hudec-networg
force-pushed
the
fix/add-scaffolds-invalid-documents
branch
from
September 7, 2026 18:16
06cc5af to
3058bd8
Compare
Three defects compounding, all of which made the answer wrong without saying so. It wrote its own answer back to the cache, so asking what the next id would be consumed it. Three calls in a row gave three answers, each higher. A query that mutates the state it reports has no honest use. writeIdStats kept only the larger of the cached and the supplied value, so a scan could never lower a stale entry - which is precisely what syncids exists to do. Reported "AC: 1020 -> 11" and wrote nothing. And minStart was applied even when ids already existed, so a workspace numbered from AC00001 was told its next actor was AC01000. That floor is documented as the starting number for add templates; applying it to a continuation query leaves a 989-wide hole and two disjoint ranges in one document. The consequence was a command that printed Highest: AC00008 and Next ID: AC01020 one line apart and meant both. Following it numbers a model from another branch's high-water mark. Tests cover all three: the query is idempotent, a scan can lower a cached value, and a continuation continues. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every other element type could cite the insights behind it. Strategy could not, so a strategy document's provenance was prose the validator never saw - the one document in a workspace where the pipeline's guarantee did not hold, and no way to tell from inside it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
david-hudec-networg
added a commit
to david-hudec-networg/skills
that referenced
this pull request
Sep 7, 2026
The repo's principle is that every workaround a skill has to describe is a defect in the tools. Four were: add scaffolded invalid documents, nextid could not be trusted, strategy elements could not cite their evidence, and supersedes takes a single reference. Three are fixed in TALXIS/ubml#46 and the prose they justified is gone from the skills. The fourth stays proposed - accepting a list there is a language semantics change, not a bug fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
david-hudec-networg
added a commit
to david-hudec-networg/skills
that referenced
this pull request
Sep 7, 2026
The repo's principle is that every workaround a skill has to describe is a defect in the tools. Four were: add scaffolded invalid documents, nextid could not be trusted, strategy elements could not cite their evidence, and supersedes takes a single reference. Three are fixed in TALXIS/ubml#46 and the prose they justified is gone from the skills. The fourth stays proposed - accepting a list there is a language semantics change, not a bug fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
david-hudec-networg
added a commit
to david-hudec-networg/skills
that referenced
this pull request
Sep 7, 2026
The repo's principle is that every workaround a skill has to describe is a defect in the tools. Four were: add scaffolded invalid documents, nextid could not be trusted, strategy elements could not cite their evidence, and supersedes takes a single reference. Three are fixed in TALXIS/ubml#46 and the prose they justified is gone from the skills. The fourth stays proposed - accepting a list there is a language semantics change, not a bug fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
david-hudec-networg
added a commit
to david-hudec-networg/skills
that referenced
this pull request
Sep 7, 2026
The repo's principle is that every workaround a skill has to describe is a defect in the tools. Four were: add scaffolded invalid documents, nextid could not be trusted, strategy elements could not cite their evidence, and supersedes takes a single reference. Three are fixed in TALXIS/ubml#46 and the prose they justified is gone from the skills. The fourth stays proposed - accepting a list there is a language semantics change, not a bug fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
david-hudec-networg
added a commit
to david-hudec-networg/skills
that referenced
this pull request
Sep 7, 2026
The repo's principle is that every workaround a skill has to describe is a defect in the tools. Four were: add scaffolded invalid documents, nextid could not be trusted, strategy elements could not cite their evidence, and supersedes takes a single reference. Three are fixed in TALXIS/ubml#46 and the prose they justified is gone from the skills. The fourth stays proposed - accepting a list there is a language semantics change, not a bug fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
david-hudec-networg
added a commit
to david-hudec-networg/skills
that referenced
this pull request
Sep 7, 2026
The repo's principle is that every workaround a skill has to describe is a defect in the tools. Four were: add scaffolded invalid documents, nextid could not be trusted, strategy elements could not cite their evidence, and supersedes takes a single reference. Three are fixed in TALXIS/ubml#46 and the prose they justified is gone from the skills. The fourth stays proposed - accepting a list there is a language semantics change, not a bug fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
david-hudec-networg
added a commit
to david-hudec-networg/skills
that referenced
this pull request
Sep 7, 2026
The repo's principle is that every workaround a skill has to describe is a defect in the tools. Four were: add scaffolded invalid documents, nextid could not be trusted, strategy elements could not cite their evidence, and supersedes takes a single reference. Three are fixed in TALXIS/ubml#46 and the prose they justified is gone from the skills. The fourth stays proposed - accepting a list there is a language semantics change, not a bug fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Which insight is next, in the order the material was produced, with the source text beside the claim and a position counter. And recording the answer once a human has given one. It stops at bookkeeping on purpose. Reading a reviewer's reply, judging whether an ambiguous answer counts, noticing that a correction changed the meaning rather than the wording - none of that is a CLI's job. The payload and the state are mechanical; the judgement is not. set rewrites one line rather than reserialising. A workspace is a document a human is reading: its comments, its quoting and its line breaks are content, and round-tripping them through the serializer would rewrite a file underneath the reviewer. Tests cover it - one line changes, a comment survives, and setting a status and setting it back returns the original bytes. A restatement means a claim repeated from a source already walked, so it points at an insight belonging to an earlier source. Counting every related link instead would tell a reviewer "15 insights, 13 restating" on a workspace where almost nothing restated - worse than silence, because the map exists so they can pace themselves. The ordering, the labelled blocks, evidence before claim, position ahead of identity and the ID last were all prose in the consulting plugin's validate-insights skill. They are assertions here now. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
david-hudec-networg
force-pushed
the
fix/add-scaffolds-invalid-documents
branch
from
September 8, 2026 06:57
0124970 to
faebe65
Compare
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
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.
This is the fixes PR. Seven defects the CLI shipped, all of them hit by
running a five-source discovery engagement through it end to end rather than
found by reading. Its companion #47 is
the improvements PR and proposes language changes; nothing here does.
That split is deliberate. These are bugs, and they should not wait on a design
debate about the other one.
Read it in seven commits
Each builds on the last. Nothing is written and then rewritten.
ubml addproduced a documentubml validaterejectsSwept across every type
addcan create: 13 of 13 failed.One line in
generate-template-data.ts:TemplateSectionnever carried properties, soTEMPLATE_DATAheld none foranything and the scaffolder wrote a bare key.
TM01000:with an empty bodyparses as
null. The types that appeared to work only did so becauseitems.tshappened to carry a hand-written example, and two of those were wrong in other
ways.
Extraction now resolves the item schema from the document schema —
patternPropertiesfor an ID-keyed map,itemsfor a sequence, inline or behinda
$ref. Five shape bugs fell out of the sweep:add hypothesesroot/childrenas{id, text, …}and arraysHY#####-keyed mapsadd processid: PR01000inside the itemAC#####roiAnalysesRO#####ROI#####— the prefix regex was[A-Z]{2}ubml nextidcould not be trustedThree defects compounding, none of which announced itself.
It consumed the ID it reported. Asking what the next ID would be wrote that
answer back, so three calls gave three answers, each higher.
syncidscould not repair a stale cache. It kept only the larger of cachedand supplied, so a scan finding a lower truth was discarded. It printed
AC: 1020 → 11and wrote nothing — the one case the command exists for.minStartwas applied to a continuation. A workspace numbered fromAC00001was told its next actor was
AC01000, leaving a 989-wide hole.The visible symptom was
Highest: AC00008andNext ID: AC01020printed oneline apart, both meant.
Two additions
derivedFromonvalueStreamsandcapabilities— the one element familywhose provenance the validator could not see.
ubml walk— which insight is next, in the order the material was produced,with the source text beside the claim; and recording the answer. It stops at
bookkeeping: reading a reply, judging an ambiguous answer, noticing a correction
changed the meaning are not a CLI's job.
setrewrites one line rather thanreserialising, because a workspace is a document a human is reading.
Tests
291 passed, 3 skipped.
typecheckandlintclean.cli-add-validates.test.tsfails 13 of 13 against the previous behaviour — Irebuilt from pre-fix sources to confirm the test can fail.
id-scanner.test.tscovers all three
nextiddefects.cli-walk.test.tscovers ordering, evidencebefore claim, ID last, one line changed, and a byte-identical round trip.
Note on ordering
#47 is stacked on this one and shows
these commits too until this merges. Merge this first.