test(spec): discover the migrate-sentence markdown corpus instead of naming one file

[claude]

Fixes #13859

What was wrong

packages/spec/src/shared/retired-key-migrate-sentence.test.ts pinned the house tombstone sentence over two source corpora and a markdown corpus of exactly one hard-coded file — the internal retirement playbook (RETIREMENT_SKILL_MD).

The regex was never the defect; the population was. WITHDRAWN_CLAIM matches the withdrawn "rewrite it automatically" claim verbatim, and that claim nevertheless reached skills/objectstack-upgrade/SKILL.md — published, customer-facing — with nothing scanning it. It was corrected by hand in #13861 (commit 88c30af, one line: rewrite it automatically. becomes list the mechanical edits for existing sources; apply them by hand.). Nothing mechanical found it, and until this PR nothing stopped it coming back.

What this changes

One test file. The markdown corpus is discovered, not named: the internal retirement playbook plus every .md file under skills/. Discovery is

• deterministic — readdirSync(...).sort() at every level, so the corpus order and every failure message read the same on every machine and every run;
• symlink-safe — lstatSync skips a symlink instead of following one out of the repo (or back in, judging a file twice);
• non-vacuous, and asserted to be — the corpus must be non-empty, must contain the playbook, and must contain at least one published skill. A walk that silently reached zero published files would restore exactly the one-file blindness this card is about, while every other assertion in the suite stayed green.

The three existing markdown assertions keep their intent:

assertion	population after this PR
every prescription sentence is house-form or MIXED two-clause	the whole discovered corpus
anti-vacuity: BOTH shapes are taught, so at least two sites are judged	the playbook only
[#9529] the withdrawn automatic-rewrite claim is absent, in every spelling	the whole discovered corpus

The BOTH-shapes floor stays pinned to the one file that owns both templates, deliberately: a published skill that names the command once is not a regression, so widening that floor would fail on the catalog's editorial choices rather than on drift.

SKILL_MARKER keeps its leading-Run requirement — naming the command mid-prose is not prescribing a sentence, and the published upgrade skill names it a dozen times without prescribing anything. WITHDRAWN_CLAIM stays English-only by design, so Chinese prose anywhere in the wider corpus cannot fabricate a match.

The one thing the widening needed that the card could not predict

A naive widening does not land green, and the file that reds it is the very file this card is about.

The old anchors required a judged sentence to end at a double-backtick code-span close. That is how the playbook writes its two taught templates, so on a one-file corpus it read as "the sentence must be last in its container". On a wider corpus it means something else: any occurrence that is not inside a code span is an unconditional RED, because nothing but a code span can supply the terminator. That is not a property — it is a trap that fires the moment the corpus stops being one file.

Measured on origin/main at 4a37870, with the pin's own regexes over the widened corpus: 3 markers, 1 violation — skills/objectstack-upgrade/SKILL.md, quoting the corrected house sentence verbatim inside a rendered parse-error transcript whose next line is expected: never. The span-only anchor would have red-flagged the text #13861 had just fixed.

So "container" is now two things, and the judge asks which one it is looking at:

• a taught template — the marker opens a double-backtick code span — must close that span, so prose still cannot bury the command mid-span;
• a sentence quoted in prose or a transcript has no span to close, and is judged on its wording, ending at its own period.

What that gives up, deliberately and only in prose: burying (... apply them by hand. Also do X.) passes there. It stays RED inside a template and RED in every .ts prescription — the two places from which a reader actually copies text.

skills/** is read by the widened corpus and never written by this PR: the diff is one test file, and the corpus found no other violation to report.

Verification

Union re-run after the final commit, at db374e225.

• The changed pin, pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/shared/retired-key-migrate-sentence.test.ts — Test Files 1 passed (1) / Tests 14 passed (14).

• Whole @objectstack/spec suite — Test Files 451 passed (451) / Tests 12190 passed (12190). Not sharded.

• pnpm --filter @objectstack/spec build && ... typecheck — check:test-typecheck: OK ... 54 file(s) / 262 error(s) / 146 pinned signature(s), the ledgered counts unchanged. The edited file is genuinely in that program, not merely adjacent to it: tsc -p tsconfig.test.json --listFiles lists it (1 hit), and none of the 262 ledgered errors names it.

• Reverse verification (the widening is real, not declarative). The exact withdrawn sentence was appended to skills/objectstack-upgrade/SKILL.md in the worktree, after the implementation was committed. Mutation proven on disk before the run — occurrence count 0 then 1, blob 16b7a39e then 87b24b72. The pin went RED, 2 failed / 12 passed, both failures naming the file:

  • every prescription sentence in the markdown corpus is house-form or MIXED two-clause — AssertionError: skills:objectstack-upgrade/SKILL.md [prose] — "Run ... to rewrite it automatically."
  • [#9529] the withdrawn automatic-rewrite claim is absent from the corpus, in every spelling — same file.

  Restored with git checkout HEAD -- (absolute path) under an EXIT INT TERM trap on absolute paths, and proven restored by bytes rather than by an exit code: blob back to 16b7a39e (equal to the HEAD blob, non-empty), occurrence count back to 0, git diff HEAD empty, git status --porcelain empty. The mutation was never committed or pushed. On origin/main neither assertion could have seen that file at all.

• Gate family, derived mechanically with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at db374e225 (1 path vs merge base 4a37870): 47 commands. 44 measured green — each exit code captured to a file before any pipe. Among them check:cross-package-test-inputs (the widened read of skills/ is already inside this package's declared globs, and turbo.json already hashes them), check:test-source-alias, check:type-check-coverage, check:published-files, and every @objectstack/spec check:* in the family. Plus pnpm check:nul-bytes — OK (scanned 7938 text file(s) ... no raw ASCII control bytes).

• 3 gates NOT MEASURED, all prerequisite-not-met on an unbuilt workspace, none a finding: check-dev-prereqs (The workspace is not built — 1 unmet precondition), check:doc-formula-expressions (exit 3, needs @objectstack/formula dist), check:dual-build-cjs-loads (exit 3, PREREQUISITE NOT MET — this gate reads built output), check:type-check-debt (exit 3, PREREQUISITE NOT MET), and check-test-completeness (exit 3, whose own text says to record it as NOT MEASURED when run without a turbo run test log). CI builds the workspace and measures all of them.

• Declared narrowing: the repo-wide pnpm lint sweep was not run locally. It is CI-owned and CI runs it on this PR regardless.

Changeset

None. This is a test-only change — one *.test.ts file, publishing nothing from any package — so it carries the repo's documented test-only handling, the skip-changeset label, rather than a fabricated release note.

Draft on purpose: the PM seat reviews and lands. Not marked ready, no auto-merge.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 53d368921b06abdc76502234ceb31733ad9d3ab1 → packageMentionDocs.