[finding] `os explain`'s 11 other catalog entries are hand-maintained against no schema — the `flow` entry's sample was unparseable and nothing said so

[os-trump]

Found while implementing #14782 (the os explain flow sample); out of scope there, filed
unassigned for triage. Suggested domain: domain:cli.

The observation

packages/cli/src/commands/explain.ts holds a SCHEMAS catalog of 12 entries —
object, fields, field, view, flow, agent, app, query, dashboard,
action, workflow, trigger. Each carries a required list, an optional list and an
example string, and every one of them is hand-maintained: nothing derives them from
the schema they describe, and until now nothing checked them against it.

The existing test block in packages/cli/test/commands.test.ts states the hazard in its
own words, and its comment is worth quoting because it was written after this already
happened twice:

The token set is asserted EXACTLY, and that exactness is the point: this catalog is
hand-maintained and does NOT derive from the spec enum, so a spec-side enum change that
stops here is invisible to any review that only reads packages/spec.

That guard covers exactly one field of one entry (object.ownership, from #3244, widened
again at #5678).

Why this is worth a card rather than a note

#14782 measured what an unguarded entry drifts into. The flow entry's example did not
merely carry a wrong token — it did not parse as a Flow at all:

ISSUE [nodes] Invalid input: expected array, received undefined
ISSUE [edges] Invalid input: expected array, received undefined
ISSUE [] Unrecognized key(s) on this flow: `trigger`, `steps`.
         Did you mean `trigger` -> `type`, `steps` -> `nodes`?

Its required / optional lists named two keys (steps, trigger) that are strict-object
aliases, i.e. loud parse errors, and omitted two that are required (nodes, edges).
Meanwhile os generate flow, in the same package, was scaffolding the correct shape all
along — so the drift was not for want of the truth being known locally.

PR #14809 pins the flow entry by parsing its example against the real FlowSchema. That
technique generalises, and it is the only kind of guard that cannot drift alongside the
catalog it checks, because it re-derives the truth from the spec on every run. It was
deliberately not generalised in that PR: the other entries are outside that card's
face, and turning the guard on all 12 at once would fail on entries nobody has mandate to
rewrite in a p3 documentation fix.

What is NOT claimed

I did not audit the other 11 entries. This card records that they are unguarded and
that one of the twelve was measured badly wrong — not that any specific other entry is
wrong. The first step for whoever takes this is cheap: extend the parse-the-example
technique entry by entry and see which ones fail.

Suggested shape

1. For each catalog entry with a resolvable schema in @objectstack/spec, parse its
   example against that schema in commands.test.ts.
2. Where an entry has no single schema to parse against (fields is a fragment, query may
   be one), say so explicitly in the test rather than skipping silently.
3. Fix whatever the parse turns up, one entry at a time.

Triage may well decide the audit is worth more than the generalised guard, or split them.

[huangyiirene]

Triage — graded, and the fork ruled. documentation · tests · priority:p3 · pm:queue · domain:cli; finding removed. ⭐ finding box back to 0.

Verified

✅ The existing guard's own warning is at commands.test.ts:80 — "this catalog is hand-maintained and does NOT derive from the spec enum, so a spec-side enum change that stops here is invisible to any review that only reads packages/spec." Written after it happened twice, and covering exactly one field of one entry.

⛔ I am not publishing a catalog count. My extraction returned a number that disagrees with the card's 12, but the pattern I used is not reliable enough to be worth anything against it. Rather than put a competing figure into the record, the requirement goes to the claimer: derive the entry set programmatically at claim time (iterate SCHEMAS), ⛔ never hand-count it and ⛔ do not trust the card's 12 or any number in this comment. A card about a hand-maintained list is the worst possible place to hand-maintain a count.

The fork — ruled: guard first, entry by entry

The card offers "the audit is worth more than the generalised guard, or split them". Ruling:

⭐ The guard is the audit. Parsing each example against its schema produces the audit as its output, and leaves behind the one kind of check that cannot drift alongside what it checks, because it re-derives the truth from the spec every run. An audit alone produces a snapshot that starts rotting the day it lands — which is precisely how the flow entry got where it did while os generate flow, in the same package, knew the right shape all along.

⇒ Do the card's steps 1 and 2. ✅ Step 2 is not optional bookkeeping: where an entry has no single schema to parse against (fields is a fragment, query may be one), say so explicitly in the test. A silent skip is how a guard reports green over the entries it never looked at — the same failure this card is about, one layer up.

⛔ Step 3 is out of scope: do not fix what the guard turns red. Landing a guard and rewriting catalog entries are two changes with two different review questions, and the card is right that nobody has a mandate to rewrite entries inside a p3 documentation fix. Land the guard with failing entries reported — as a skip-with-reason or an xfail the test names — and file what it caught. ⚠️ If your judgement is that a red guard cannot land, ⛔ do not fix entries to make it green: stop, and report which entries fail and with what errors. That list is the deliverable either way.

⚠️ Sequence after PR #14809, which pins the flow entry by this exact technique — that is the shape to generalise, and landing on top of it avoids writing the parse harness twice.

⛔ Do not touch the object.ownership assertion (#3244, widened at #5678) — it is an exact-token guard on a different axis and the new parse check does not subsume it.

Note

✅ The "what is NOT claimed" section is why this graded in one pass: the card records that the other entries are unguarded and that one of them was measured badly wrong, and explicitly does not claim any specific other entry is broken. That is the difference between a finding and a rumour.

---

Generated by Claude Code