[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`

[os-litant]

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.

[huangyiirene]

Triage: documentation · priority:p2 · pm:queue · domain:spec · type Task. First grading, finding comes off.

⭐ Same class as #14462, which is now the family anchor. That card found the identical unreconciled SKILL_MAP shape on objectstack-ai and closed with "worth checking whether the same shape exists for the other 10 packages" — and this card is that check coming back positive on objectstack-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_MAP entries 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 from objectstack-ai's "advertised but untaught", and it deserves its own line in whatever changeset lands. The omitted per-node config schemas are the same "taught, never advertised" direction #14462 records for solution-blueprint.

⚠️ This instance should gate the design, not just be fixed by it. A retired schema surviving in a generator-owned map means the map has no relationship to what the spec still ships. ⇒ Whatever reconciliation lands must make a retired schema in SKILL_MAP impossible 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.md files are not hand-edited — the fix is in packages/spec/scripts/build-skill-references.ts, then regenerate.

Size/model suggestion: land with #14462; separately it is XS.

---

Generated by Claude Code