Repository navigation
[finding] The objectstack-automation reference index routes to the ADR-0020-retired state-machine.zod.ts and omits both per-node config schemas — SKILL_MAP in build-skill-references.ts #14466
Description
Out-of-scope finding from the skills optimization flight on #14308 (audit id AUTO-B-05), filed for the spec lane. Nothing in this card was changed by that flight — its ruling deferred the generator map because the fix lives in packages/spec, outside the flight's file surface.
Sibling of #14462, which is the same defect class (SKILL_MAP unreconciled with the body) for a different package. Worth triaging together; possibly one fix.
Measured at origin/main a98b61b.
What the map says
packages/spec/scripts/build-skill-references.ts:120-129:
'objectstack-automation': [
'automation/flow.zod.ts',
'automation/time-relative-trigger.zod.ts',
'automation/approval.zod.ts',
'automation/state-machine.zod.ts',
'automation/execution.zod.ts',
'automation/webhook.zod.ts',
'automation/node-executor.zod.ts',
'data/validation.zod.ts',
],
Why that is wrong in two directions
1. It points authors at a schema ADR-0020 retired for the thing they are authoring. packages/spec/src/automation/state-machine.zod.ts:15-21 says so in its own header: ADR-0020 "retired this shape as a record-lifecycle declaration — the top-level workflow metadata type and object.stateMachines are both gone", and a record's legal transitions are now a state_machine validation rule in data/validation.zod.ts. That correct destination is already the last entry of the same list, so the retired file adds no reachable surface. Its one surviving door is ai/agent.zod.ts:197 lifecycle, marked [EXPERIMENTAL - not enforced] ... Parsed but no runtime consumer yet — an objectstack-ai door, not an automation one.
2. It omits the two files that answer the question the index exists to answer. The per-node-type config shapes live in automation/builtin-node-config.zod.ts (screen fields, the loop/parallel/try_catch containers reach it) and automation/io-node-config.zod.ts (NotifyConfigSchema at :178-258, http timeoutMs). Neither is in this list nor in any other package's. An agent told "always Read the source for exact field shapes" has no route to either. automation/control-flow.zod.ts reaches the generated skills/objectstack-automation/references/_index.md:23 only as a transitive dependency, not as a named entry.
The #14308 flight has just added the ADR-0031 container rows and a notify config fence to SKILL.md, both citing exactly these two files — so the index now advertises a retired schema while the body teaches two schemas the index does not list.
Proposal
In SKILL_MAP['objectstack-automation']: drop automation/state-machine.zod.ts; add automation/builtin-node-config.zod.ts and automation/io-node-config.zod.ts. Then pnpm --filter @objectstack/spec gen:skill-refs and commit the regenerated references/_index.md (generator-owned; check:skill-refs is the drift gate).
Note for whoever picks this up: skills/objectstack-automation/references/_index.md is ratchet-measured but not ratcheted (generator-owned), so the entry swap has no token ceiling to satisfy.
Unassigned and unprioritised — PM triage decides.
Activity
huangyiirene commentedon Sep 2, 2026
Triage:
documentation·priority:p2·pm:queue·domain:spec· typeTask. First grading,findingcomes off.⭐ Same class as #14462, which is now the family anchor. That card found the identical unreconciled
SKILL_MAPshape onobjectstack-aiand closed with "worth checking whether the same shape exists for the other 10 packages" — and this card is that check coming back positive onobjectstack-automation, filed independently within the hour. Two discoveries in one hour is a class, not two incidents.⇒ #14462 carries the census across all eleven
SKILL_MAPentries plus one uniform reconciliation ruling (narrow the map to what the body teaches; add the schemas the body already names; ⛔ do not widen a SKILL.md to earn extra entries — that fights the token ratchet and the zero-consumer measurement).⛔ This card is NOT closed as a duplicate, and that is deliberate: its specific fact is the sharpest one in the family and must not be summarised away. The index routes readers to
state-machine.zod.ts, which ADR-0020 retired — so the published index does not merely over-promise, it points at something the platform deliberately removed. That is a different failure fromobjectstack-ai's "advertised but untaught", and it deserves its own line in whatever changeset lands. The omitted per-nodeconfigschemas are the same "taught, never advertised" direction #14462 records forsolution-blueprint.SKILL_MAPimpossible rather than corrected once — otherwise the census is a one-off and the next ADR retirement re-opens it. If deriving the map from a checkable source is out of reach, say so in the PR rather than hand-fixing eleven lists; that is a finding, not a failure.⛔ The generated
references/_index.mdfiles are not hand-edited — the fix is inpackages/spec/scripts/build-skill-references.ts, then regenerate.Size/model suggestion: land with #14462; separately it is XS.
Generated by Claude Code
os-justin commentedon Sep 4, 2026
Claim: PM loop round R1 —
domain:specseat (seat post #6017). Family member of theSKILL_MAPreconciliation fold anchored on #14462 (anchor claim 5536672000-series, read the anchor for the full surface, serial constraints and exclusion list). Member criterion: on the shared branch,SKILL_MAP['objectstack-automation']no longer namesautomation/state-machine.zod.tsand namesautomation/builtin-node-config.zod.ts+automation/io-node-config.zod.ts; the regeneratedskills/objectstack-automation/references/_index.mdshows exactly that; the guard the design adds refuses a retired schema in the map (or the PR says why that source is out of reach). Own commit; ownFixes #14466line in the PR body.Session:
session_01H2oQebDDxYKfWZusyd8GXk(GitHubos-justin)Branch:
claude/issue-14462-skill-map-reconciliation(shared, named after the anchor — no branch of its own by design)Worktree:
objectstack-issue-14462Domain:
domain:specContainer & model: folded into the anchor's M /
opus/mode:subagent.Clause-②: no
Generated by Claude Code
os-justin commentedon Sep 4, 2026
Implemented in draft PR #15268 (family branch
claude/issue-14462-skill-map-reconciliation, one commit per member —fc2acf06is this card's). Criterion met:automation/state-machine.zod.tsis absent from the whole regenerated index, not merely moved to the transitive section, and both per-nodeconfigschemas are core rows. Fullos-dev-reporton the anchor #14462 (comment 5537415234). Note for the reviewer: addingautomation/io-node-config.zod.tsturnedcheck:doc-authoringred on the tracker citation in its module header, and the PR resolves that at the catalog boundary rather than in the schema source — argued in the PR body, with the alternative spelled out.Generated by Claude Code
os-justin commentedon Sep 4, 2026
Family review pointer — ACCEPT on the anchor #14462 (comment 5537457796, 2026-09-04T07:56Z) covers this member: PR #15268 (head
eed6bb0f) removes the ADR-0020-retiredautomation/state-machine.zod.tspointer from the automation index entirely and addsautomation/builtin-node-config.zod.ts+automation/io-node-config.zod.tsas core rows. Governed surface ⇒ the PR stays draft for a human merge (reviewersos-zhuang+hotlong);Fixes #14466closes this card on merge.Generated by Claude Code