[finding] The skill-reference `Exports:` fallback ranks by source order, so DEPRECATED_/NON_AUTHORABLE_/LEGACY_ constants headline customer-facing rows

[os-litant]

Filed unassigned while converging build-skill-references.ts on the shared module-docblock selector (#12094). Out of that card's scope — that one fixes which doc block is published; this is about what the fallback publishes when there is no module doc block at all. #12094 explicitly left the fallback chain in place and named the follow-up question, so this records the measurement rather than pre-judging it.

What

When a .zod.ts has no module doc block, extractDescription() in packages/spec/scripts/build-skill-references.ts falls through to an export list:

const re = /export\s+const\s+(\w+Schema|\w+)\s*(?:[:=])/g;
// …
if (exports.length > 0) return `Exports: ${exports.slice(0, 5).join(', ')}`;

Two properties combine badly on a customer-facing surface:

1. Rank is source order, not importance — slice(0, 5) keeps whichever five happen to be declared first.
2. The regex has no notion of public authorable surface — any export const qualifies, including constants whose own names say they are not for authoring.

Measured

After #12094 lands, these rows are what skills/** publishes (measured on main at 22c42c9 plus that change):

• skills/objectstack-automation/references/_index.md

  - `…/src/automation/approval.zod.ts` — Exports: ApproverType, DEPRECATED_APPROVER_TYPES, NON_AUTHORABLE_APPROVER_TYPES, ORG_MEMBERSHIP_LEVELS, APPROVER_EXPRESSION_ROOTS
  

  Two of the five named constants are explicitly deprecated or explicitly non-authorable.

• skills/objectstack-i18n/references/_index.md

  - `…/src/system/translation.zod.ts` — Exports: LocaleSchema, FieldTranslationSchema, ActionResultDialogTranslationSchema, ObjectTranslationDataSchema, LEGACY_OBJECT_FIRST_KEYS
  

Why it is worth a card

The line is true — it is an accurate list of what the module exports, which is why #12094 kept it (an honest export list beats a confidently wrong prose sentence). It is the ranking that is the hazard, and only on this surface: skills/** is loaded whole into a customer agent's context window, and its job is to teach that agent what it may author. A row that headlines DEPRECATED_APPROVER_TYPES and NON_AUTHORABLE_APPROVER_TYPES is pointing an authoring agent at exactly the vocabulary it must not use, with nothing on the line marking them as such.

This is the "make AI-written metadata hard to get wrong" axis rather than a correctness bug — nothing is broken, and no gate is wrong today.

Options (not pre-judging)

• Rank or filter the fallback list — prefer *Schema exports, or skip SCREAMING_SNAKE constants, which are machine constants rather than authorable metadata.
• Require a module doc block on any .zod.ts reachable from SKILL_MAP and drop the fallback (the loud-refusal answer build-skill-references.ts still picks the first JSDoc block anywhere in the file — the defect build-docs.ts fixed, publishing a private constant's comment to customers #12094 declined to take for that card, since it would make "write a module docblock" an implicit prerequisite and red the gate on ~9 files).
• Leave it — the export list is honest, and the real repair is authoring module doc blocks on the files that lack them.

The middle option interacts with the third: the population that reaches the fallback at all is the same ~9 files, so authoring their module doc blocks removes the symptom without any generator change.

[os-zhuang]

Skills-lane self-triage: finding → promoted with the middle option, narrowed: in extractDescription()'s fallback, prefer *Schema exports and skip SCREAMING_SNAKE constants (machine vocabulary, never authorable); keep the honest Exports: form for what remains; regenerate. ⛔ The loud-refusal alternative (require module doc blocks, drop the fallback) is NOT taken — #12094 already declined it for the same population and the reasoning stands. Authoring the ~9 missing module doc blocks stays a separate editorial question and is not this card. Routing note: the file is packages/spec/scripts/build-skill-references.ts (spec toolchain) but central triage routed the card here and the affected surface is the published skills catalog — accepted as skills-lane work; the serial check found no open PR on the file (#12094's change is merged).

Claim: skills seat, session session_01RMTpSRF5CjMmQBFfPtPCwJ. Single-card dispatch. Branch: claude/issue-12201-exports-fallback-ranking. Regenerated skills/** artifacts ride under the #11705-A ruling's class (generator-owned outputs), but until that exemption LANDS in the checker, this PR still takes the governed path: draft, human merge.

---

Generated by Claude Code

[claude]

{
 "issue": 12201,
 "status": "blocked",
 "branch": "claude/issue-12201-exports-fallback-ranking",
 "pr": null,
 "premise_still_valid": false,
 "summary": "Stopped before the first edit: the card's premise is false on origin/main, and the fix collides with in-flight work. (1) PR #12202 (OPEN, draft, session_01NDGG54XF5gbTLdQzCtnaVV, branch claude/issue-12094-skill-refs-module-docblock) is in flight on packages/spec/scripts/build-skill-references.ts and rewrites extractDescription() itself, plus 7 of the same skills/**/_index.md artifacts. #12094 is OPEN, not merged. The dispatch's two load-bearing assumptions -- '#12094's change is merged' and 'the serial check found no open PR on the file' -- are both incorrect. (2) Consequently the card's two quoted rows DO NOT EXIST on origin/main at eeec62a98: automation reads '-- Approval Step Approver Type' and i18n reads '-- Shared history sentence for every shape in this file.' Both quoted 'Exports:' rows are produced by #12202, not by main. (3) On main only THREE 'Exports:' rows exist in the whole catalog (shared/enums.zod.ts x2, shared/metadata-types.zod.ts) and NONE names a SCREAMING_SNAKE constant -- so the acceptance scan the card demands is already vacuously green, and the requested positive control has no live subject. Implementing here would ship a filter with zero observable effect on the published catalog, unverifiable by the card's own acceptance evidence, while guaranteeing a text conflict with #12202 on generator-owned artifacts that do not text-merge (AGENTS.md Multi-agent SS11). Recommendation: re-dispatch this card rebased on #12202 AFTER it lands. No edits were made. The branch claude/issue-12201-exports-fallback-ranking exists on origin but is EMPTY -- it points at eeec62a98, identical to origin/main, and carries no commits and no PR; it was pushed as the first-minute write-route probe before the premise was checked. Deleting it was attempted and REFUSED: `git push origin --delete` fails at the transport and the REST ref delete returns HTTP 403 'Write access to this GitHub API path is not permitted through this proxy.' Left in place rather than routed around; the local worktree and branch were removed.",
 "tests": "No build/test run -- stopped at premise verification before the first edit, so there was nothing to verify. Evidence is read-only measurement at BASE=eeec62a98d1ffafd0fadf2b6e9d34a6d48e381c7 (origin/main), the base the dispatch named. (a) Checked-in artifacts, verbatim: `grep -n approval.zod.ts skills/objectstack-automation/references/_index.md` -> '12:- `node_modules/@objectstack/spec/src/automation/approval.zod.ts` - Approval Step Approver Type'; `grep -n translation.zod.ts skills/objectstack-i18n/references/_index.md` -> '12:- `node_modules/@objectstack/spec/src/system/translation.zod.ts` - Shared history sentence for every shape in this file.' Neither matches the card's quoted row. (b) `grep -rn '— Exports:' skills/` returns exactly 3 rows (objectstack-ui/_index.md:34 and objectstack-data/_index.md:40, both shared/enums.zod.ts -> 'SortDirectionEnum, SortItemSchema, MutationEventEnum, IsolationLevelEnum'; objectstack-platform/_index.md:43, shared/metadata-types.zod.ts -> 'MetadataFormatSchema, BaseMetadataRecordSchema'). Zero SCREAMING_SNAKE among them: the card's acceptance scan is already green on main with no fix applied. (c) Ran the generator's own fallback regex (/export\\s+const\\s+(\\w+Schema|\\w+)\\s*(?:[:=])/g, build-skill-references.ts:213) over every source #12202's census routes into the fallback. Three files would publish a SCREAMING_SNAKE in their top-5 row, but only AFTER #12202 lands: automation/approval.zod.ts (DEPRECATED_APPROVER_TYPES, NON_AUTHORABLE_APPROVER_TYPES, ORG_MEMBERSHIP_LEVELS, APPROVER_EXPRESSION_ROOTS), system/translation.zod.ts (LEGACY_OBJECT_FIRST_KEYS), kernel/plugin.zod.ts (CORE_PLUGIN_TYPES, CONSUMER_INSTALLABLE_TYPES). The third is a scope gap: the card names only automation and i18n. (d) No filtered export list goes empty, so the 'fall through to the next fallback' arm the dispatch specifies has no live subject either: approval 17 exports -> 6 kept, translation 13 -> 12, plugin 4 -> 2, enums 4 -> 4.",
 "open_questions": [
 {
 "question": "The two sub-rules ('prefer *Schema first' AND 'skip SCREAMING_SNAKE') disagree on automation/approval.zod.ts, the card's headline row. Skip-only yields 'ApproverType, ApprovalDecision, ApprovalNodeApproverSchema, DecisionOutputDefSchema, ApprovalEscalationSchema'; adding Schema-first yields 'ApprovalNodeApproverSchema, DecisionOutputDefSchema, ApprovalEscalationSchema, ApprovalNodeConfigSchema, ApproverType' -- which demotes ApproverType, the approver-type enum an author actually writes, out of the headline. Which ranking is intended?",
 "options": [
 "A. Skip SCREAMING_SNAKE only, keep source order for what remains -- removes the hazard the card is about, changes nothing else, and keeps the most authorable name first on the one row the card quotes.",
 "B. Skip SCREAMING_SNAKE and sort *Schema first, as dispatched -- more uniform across rows, but demotes plain-named authorable enums (ApproverType, ApprovalDecision, HookBodyCapability, TransportProtocol) below schema objects on every row."
 ],
 "recommendation": "A. The measured hazard is machine vocabulary appearing at all, not schemas appearing late; skip-only fixes exactly that and is the smaller, more reviewable change on a governed surface. Schema-first is an additional ranking opinion that, on the card's own headline row, makes the result worse by the card's own 'teach the authoring agent what it may author' standard."
 },
 {
 "question": "Sequencing: how should this card be landed relative to #12202?",
 "options": [
 "A. Hold this card until #12202 merges, then re-dispatch on the new main -- all three hazard rows exist, before/after is measurable, the positive control has a real subject.",
 "B. Fold the filter into #12202 itself (same function, same artifacts, same author session).",
 "C. Branch this card off claude/issue-12094-skill-refs-module-docblock now."
 ],
 "recommendation": "A. It is the only option that produces a reviewable diff against main and a non-vacuous acceptance measurement. B re-opens a PR already through its census review and mixes two decisions on a governed surface. C yields a PR that cannot merge until #12202 does and whose diff is unreadable against main."
 }
 ],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

[os-zhuang]

ACCEPT (blocked) — premise-first stop was right, and the dispatch error was mine. My claim comment asserted "the serial check found no open PR on the file (#12094's change is merged)" — asserted, not measured. PR #12202 (draft, in flight) rewrites extractDescription() itself and carries 7 of the same artifacts; the card's two quoted rows exist only on that branch. Both load-bearing dispatch assumptions were false; the dev's read-only refutation (3 Exports: rows on main, zero SCREAMING_SNAKE, acceptance scan vacuously green) is complete. This is a #11936-family instance on my side: a serial-constraint claim written without the measurement that defines it.

Both open questions adjudicated per the dev's recommendations:

• Ranking = A (skip-only): filter SCREAMING_SNAKE, keep source order for what remains. ⛔ Schema-first is NOT taken — on the card's own headline row it demotes ApproverType, the enum an author actually writes, which fails the card's own standard. This supersedes the Schema-first half of my grading comment.
• Sequencing = A (hold until fix(spec): publish each skill reference's own module doc block, not the first block in the file #12202 lands, re-dispatch on the new main) — the only shape with a reviewable diff and a non-vacuous acceptance measurement. Scope note for the re-dispatch: the fallback census found a THIRD affected file the card missed — kernel/plugin.zod.ts (CORE_PLUGIN_TYPES, CONSUMER_INSTALLABLE_TYPES) — include it in the acceptance scan.

State: pm:dispatched → pm:blocked.
Blocked-by: #12094
Unlock-action: when PR #12202 merges, re-dispatch this card on the new main with ranking A and the three-file scope; the branch claude/issue-12201-exports-fallback-ranking exists on origin but is empty at old main (ref delete was refused by the write proxy — harmless; the re-dispatch may reuse or replace it).

---

Generated by Claude Code

[os-zhuang]

Unlock-action fired: PR #12202 merged to main (18c432ed2). Re-dispatching per the recorded adjudication — ranking A (skip SCREAMING_SNAKE, keep source order; ⛔ no Schema-first reordering), acceptance scope = the THREE files the fallback census found (automation/approval.zod.ts, system/translation.zod.ts, kernel/plugin.zod.ts), measured on the post-#12202 main where the hazard rows now exist.

Claim (round 2): skills seat, session session_01RMTpSRF5CjMmQBFfPtPCwJ. Branch: claude/issue-12201-exports-fallback-ranking (reset onto current main; it exists empty on origin).

State: pm:blocked → pm:dispatched.

---

Generated by Claude Code