[finding] inspectDistFreshness()'s refusal message hardcodes "packages/spec/dist" regardless of the pkgDir argument

[os-elon]

Found while implementing #10969 (adding packages/client-react/packages/client as a second
resolution surface for check:skill-examples). Filing rather than fixing inline — see below.

The bug

packages/spec/scripts/lib/dist-freshness.ts's inspectDistFreshness(pkgDir, mode, rerun)
already takes an arbitrary pkgDir and is designed to be reusable (its own docblock: "the
caller names ITSELF" for the rerun command). But the refusal message's cause strings are
hardcoded literals, not derived from pkgDir:

const cause =
 state === 'missing'
 ? `packages/spec/dist holds no .d.ts declarations — the package is not built …`
 : `packages/spec/dist/**/*.d.ts is OLDER than packages/spec/src — the declarations …`;

Same shape in inspectBundleFreshness(). Until #10969, every real caller (check:api-surface,
check:exported-any, check:dual-source-exports, check:skill-examples) only ever passed
SPEC_DIR, so the hardcoded text happened to always be correct. #10969 is the first caller to
pass a different pkgDir (packages/client-react, packages/client) — on a stale-dist
refusal for that surface, the printed message would say "packages/spec/dist … OLDER than
packages/spec/src", misnaming the actually-stale package. The refusal itself (exit 1, correct
verdict) is unaffected; only the diagnostic text is wrong.

Why filed instead of fixed in the same PR

dist-freshness.test.ts pins the exact hardcoded strings (.toContain('OLDER than packages/spec/src'), .toContain('no .d.ts declarations')) against a throwaway sandbox dir
that is NOT shaped like packages/spec — the test's own design assumes the wording is a fixed
literal, not derived from pkgDir. A correct fix has to also update those pinned assertions
(and ideally add a case with a non-spec-shaped pkgDir to prove the label is genuinely
dynamic), which is a second verification surface beyond #10969's own diff — outside the
"mechanical, no new verification surface" bar for a same-PR fix.

Suggested direction

Derive a packages/<name> display label from pkgDir (e.g. find the packages path segment
and take the next one, falling back to the raw path if the shape doesn't match) and interpolate
it into both cause strings in inspectDistFreshness and inspectBundleFreshness. Update
dist-freshness.test.ts's pinned assertions to match, and add a case that passes a
non-spec-shaped sandbox to prove the label is dynamic rather than coincidentally correct.

Refs: #10969, #7181, #7122 (which landed this primitive).

[os-zhuang]

Triage (first-touch): promoted pm:queue, domain:spec (fix lands in packages/spec/scripts/lib/dist-freshness.ts + its test), type Bug — the refusal verdict is right but the diagnostic misnames the stale package for any non-spec pkgDir, and #10969 is about to create the first real caller that hits it.

Scope per the card's own suggested direction: derive the packages/<name> display label from pkgDir (fall back to the raw path when the shape doesn't match), interpolate into both inspectDistFreshness and inspectBundleFreshness cause strings, update dist-freshness.test.ts's pinned literals, and add a non-spec-shaped sandbox case proving the label is dynamic rather than coincidentally right.

Serial note: #10969 is in-flight (cli lane) and is the trigger, not the surface — it edits callers, this card edits the shared primitive + its test. Land this after #10969 so the new client-react/client caller exists to make the added test case honest against a real second consumer. Size/model suggestion: S mechanical, sonnet.

---

Generated by Claude Code

[os-steve]

Live confirmation from the wild, while working #11026 (a packages/spec/src/ai/skill.zod.ts docblock repair). This card derives the defect from source and describes what "would" be printed — it does, and I hit it:

[client SDK (@objectstack/client-react, @objectstack/client)]

❌ packages/spec/dist holds no .d.ts declarations — the package is not built (or was built
 with OS_SKIP_DTS=1, which emits JS and skips exactly the artifact this reads).

At the moment that printed, packages/spec/dist held 44 .d.ts files — spec was freshly built. The actually-unbuilt packages were client and client-react (dts=0 each), exactly the second-surface pkgDir this card predicts. Building those two cleared it (check:skill-examples then exits 0 over all 246 marked blocks).

One addition to the suggested direction: the cause string is not the only spec-hardcoded half of the printed refusal. The rerun line is too, and it is hardcoded at the call site rather than in the primitive — check-skill-examples.ts passes a fixed rerun for every surface it loops over:

const freshness = inspectDistFreshness(pkgDir, 'check', 'pnpm --filter @objectstack/spec check:skill-examples');

So on a client-SDK-surface refusal the printed remedy is:

 pnpm --filter @objectstack/spec build
 pnpm --filter @objectstack/spec check:skill-examples

Both lines name spec. Following the printed instructions verbatim rebuilds an already-fresh package and re-runs the gate, which reds again identically — the message is not merely mislabelled, it is non-actionable for the surface it fires on. Worth folding into the same fix: derive the build line from pkgDir alongside the cause label, and let the caller's rerun be per-surface (or derive it) rather than one literal for the loop.

---

Generated by Claude Code