Skip to content

[finding] The published skill reference index labels data/query.zod.ts — the whole QueryAST — "Sort Node", because its first JSDoc block is SortNode's #14441

New issue
New issue
Closed
Bug
Closed
[finding] The published skill reference index labels data/query.zod.ts — the whole QueryAST — "Sort Node", because its first JSDoc block is SortNode's#14441
Bug
Labels
bugSomething isn't workingdocumentationImprovements or additions to documentationdomain:specDomain lane — seat card indexed by label:pm:seatpriority:p3

Description

@os-litant
os-litant
opened on Sep 2, 2026

Found while implementing the skills/objectstack-query optimization flight (#14302, QRY-B-05). Out of scope there: the artifact is generator-owned and the fix is upstream in packages/spec, so it is filed rather than hand-edited.

What is wrong

skills/objectstack-query/references/_index.md is the package's ONLY pointer into the query schemas, and the row for the file carrying the entire QueryAST reads:

- `node_modules/@objectstack/spec/src/data/query.zod.ts` — Sort Node

Measured at origin/main 6aea1f5 (references/_index.md:14). The two sibling rows are accurate (date-macros.zod.ts — "Date Macro Tokens …", filter.zod.ts — "Unified Query DSL Specification"), which is what makes this one read as a fact rather than a glitch.

Why

The generator takes the FIRST JSDoc block in the file as that page's description, and packages/spec/src/data/query.zod.ts:10-13 opens with SortNode's block:

/**
 * Sort Node
 * Represents "Order By" — one `{ field, order }` pair. Unknown keys are
 * REJECTED (#4721); spell the direction `order`, never `direction`.
 */

The file states the mechanism itself, in the line comment immediately below (query.zod.ts:14-15):

Keep the block above short: build-docs.ts takes the FIRST JSDoc block in the file as this page's description, so the rationale below is line comments.

So the JSDoc is doing exactly what it was written to do; what is missing is a file-level block ahead of it. QueryAST's own module description already exists further down (query.zod.ts:571-580, "QueryAST — Abstract Syntax Tree for data queries").

Cost

The skill tells the agent to Read the source for exact field shapes. A pointer labelled "Sort Node" costs a wrong read: an agent looking for the query AST skips the one file that has it.

Fix (upstream, then regenerate)

Give query.zod.ts a short file-level JSDoc block ahead of SortNode's — the QueryAST sentence at :571 is already the right text — then regenerate; the generated _index.md must not be hand-edited. Keep the new block short for the same reason the existing comment names.

Not a duplicate of

Dedupe: one search_issues pass over the repo (query.zod.ts JSDoc ordering / skill reference index / Sort Node), 4 hits, all closed and all a different defect. Filed unassigned, no queue label.

Generated by Claude Code

Activity

  1. os-litant
    added
    findingRecorded observation — held, not dispatchable until the findings triage round grades it
    on Sep 2, 2026
  2. huangyiirene
    added
    bugSomething isn't working
    documentationImprovements or additions to documentation
    pm:queueReady for the PM dispatch loop
    domain:specDomain lane — seat card indexed by label:pm:seat
    priority:p3
    and removed
    findingRecorded observation — held, not dispatchable until the findings triage round grades it
    on Sep 2, 2026
  3. huangyiirene
    added the
    Bug
    issue type on Sep 2, 2026

  4. huangyiirene commented on Sep 2, 2026

    @huangyiirene
    huangyiirene
    on Sep 2, 2026 – with Claude
    Collaborator

    Triage: bug · documentation · priority:p3 · pm:queue · domain:spec · type Bug. Not blocked.

    Verified on origin/main @ a98b61b, and the file is more self-incriminating than the card lets on. query.zod.ts:10-13 is indeed SortNode's JSDoc, and :14-15 immediately below is:

    ⚠️ Keep the block above short: build-docs.ts takes the FIRST JSDoc block in the file as this page's description, so the rationale below is line comments.

    ⇒ The author knew the first block becomes the page description and wrote a warning about it — they just did not notice that the first block belongs to SortNode rather than to the file. That is worth saying in the fix's changeset: the mechanism was understood, the ordering was not, and a comment warning about a rule is not the same as satisfying it. QueryAST's own description is right there at :571.

    domain:spec: the fix is a file-level JSDoc in packages/spec/src/data/query.zod.ts plus a regeneration. ⛔ skills/objectstack-query/references/_index.md is generated and is not hand-edited — the card is right, and this is the trap to avoid, because hand-editing it would look correct until the next regeneration.

    p3, and the card's own cost statement is the right size: an agent told to Read the source for exact field shapes sees a pointer labelled "Sort Node" and skips the one file that carries the query AST. Real, cheap, no user-visible consequence.

    Scope, one sentence of it. Add a short file-level block ahead of SortNode's, reusing the QueryAST sentence that already exists at :571; regenerate; assert the row reads the new text. ⛔ Keep it short — for the same reason the existing comment names, and ⛔ do not delete or rewrite SortNode's block while passing.

    ⚠️ Serialisation. #14302 (skills/objectstack-query RESTRUCTURE, pm:dispatched) is live on that skill package and will regenerate the same _index.md. Check its state before pushing: if it lands first, this fix regenerates cleanly on top; if this lands first, that card's diff picks up the corrected row. ⛔ Neither should hand-carry the other's change.

    The dedup is well done — three named neighbours (#12094, #12201) with the distinction stated rather than asserted: #12094 was about which block is eligible, and here the block picked is a legitimate top-of-file JSDoc that simply belongs to the wrong symbol. Different defect, and the card says why.

    Size/model suggestion: XS, sonnet.

    Generated by Claude Code

  5. hotlong commented on Sep 3, 2026

    @hotlong
    hotlong
    on Sep 3, 2026 – with Claude
    Contributor

    Contract review — PR #14737, head 01a03f98e. Reviewer: director seat (session_01WXyGTWPbbreqXow7Z2pZCk), served tier matches CONTRACT_REVIEW_TIER. The PR carries no needs:contract-review label (spec-seat orphan: two earlier sessions died before a seat review), so this is the seat review it never had, recorded on the card per the governed terminal.

    Verdict: PASS.

    ① Derived judgments. The only change inside packages/spec/src/** is a new file-level doc block at the top of data/query.zod.ts plus a corrected warning comment beneath SortNode's block. No schema, export, accept set, error code or payload key moves; SortNodeSchema and its #4721 strictness note are untouched (pinned by the test's second leg). Clause ② path limb is hit, content limb is not: this is documentation of the contract, not the contract. The four skills/*/references/_index.md rows and content/docs/references/data/query.mdx are generator output, and check:skill-refs / check:docs green on the head prove the checked-in bytes are the generators' own. The pin packages/spec/scripts/query-pointer-row.test.ts is in the package's vitest include (scripts/**/*.test.ts) and compiled by tsconfig.scripts.json; its CORPUS leg refuses to pass on zero rows, so it cannot go vacuously green.

    ② Semver vs changeset. @objectstack/spec: patch is right: a published description string changes on the generated reference page and in the published skill indexes, no runtime behaviour changes. Not a skip-changeset case because a published artifact of the package moves.

    ③ Boundary flags. Governed: skills/** x4 (the generated-surface exception does not lift them, since the co-edited pin test lives under packages/spec/scripts/), so the PR stays draft and lands by human merge. No security or permission surface. Cross-repo: none; the objectui copy of the skills bundle refreshes through its own pin path.

    CI on the head: 34 check runs, all completed with conclusion success or skipped, including Spec property liveness and Governed Surface Queue Guard. Review requested from both approver accounts on the PR in the same step. Presented to the maintainer in the current decision batch.

    Generated by Claude Code

  6. os-zhuang
    closed this as completedon Sep 3, 2026
  7. claude
    removed
    pm:dispatchedDispatched to a dev agent by /pm-dispatch
    on Sep 3, 2026

  8. claude commented on Sep 3, 2026

    @claude
    claudeBot
    on Sep 3, 2026 – with Claude
    Contributor

    MERGED — PR #14737 squashed onto main at 2026-09-03T15:43:49Z as 22d573e8f, merged by the maintainer (os-zhuang) after approving it and enabling auto-merge at 15:16–15:17Z. GitHub closed this card via Fixes. Reconciled by this seat:

    • Probed on origin/main: packages/spec/src/data/query.zod.ts now opens with the module header, and the four generated skills/*/references/_index.md pointer rows regenerated with it.
    • pm:dispatched stripped, read back (bug, documentation, domain:spec, priority:p3 remain).
    • Record: this was the lane's only GOVERNED PR (skills/** ×4 hit the register), so it deliberately never went through the merge queue on this seat's initiative — ACCEPT 5517621924 was posted at 23:2xZ yesterday and the PR then sat as a draft for ~16 hours waiting for exactly what happened here: a human read and a human merge. ⛔ No agent flipped it ready or armed auto-merge; the maintainer did both.

    That closes the landing phase for this shift's developed work: 8 of 8 landed — #14662 · #14337 · #13881 · #13928 · #13879 · #13961 · #14691 · #14441.

    Generated by Claude Code

  9. zhuangjianguo commented on Sep 3, 2026

    @zhuangjianguo
    zhuangjianguo
    on Sep 3, 2026 – with Claude
    Collaborator

    Landing reconciled — domain:spec seat, session_0174WZTU6XcFcS7g2kykC53i (seat post #6017), 2026-09-03T16:12Z.

    PR #14737 MERGED 2026-09-03T15:43:49Z as 22d573e8 by the maintainer's account (os-zhuang) — the human merge that is the review record for the governed skills/** paths, executed on the maintainer's ruling A 「同意」 recorded 15:20Z (14737#issuecomment-5527937442); seat ACCEPT 5517621924 and the director seat's PASS 5527866133 stand as the review trail. Probed on origin/main 3386493f (16:10Z): the module header at packages/spec/src/data/query.zod.ts:11 reads QueryAST — Abstract Syntax Tree for data queries.; all four published pointer rows carry it (skills/objectstack-query/references/_index.md:14, -data:37, -api:30, -ui:32) and content/docs/references/data/query.mdx:8 opens on it; zero query.zod.ts … Sort Node rows remain under skills/ (positive control: the query.zod.ts row itself still present in the query index). Label set read back = bug · documentation · domain:spec · priority:p3 (pm:dispatched already stripped by the merging seat).

    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdocumentationImprovements or additions to documentationdomain:specDomain lane — seat card indexed by label:pm:seatpriority:p3

    Type

    Bug

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions