skills(formula): optimization flight — cut the cron/template quickrefs and section-5 narration, teach virtual formula fields and fault-open form predicates (net −844 tokens)

[os-litant]

Part of #14316

Member of the skills catalog optimization program #14292 (maintainer mandate 2026-09-02: 「审核所有的 skills，进行全面的优化。」). Verdict DIET. The audit record is on the card as the audit-record comment.

Transliteration key — the GitHub body sanitizer eats angle-bracket-shaped fragments, so this body spells them out: LT = opening angle bracket, GT = closing angle bracket, and a name in CAPS inside a path (record.FIELD, vars.STEP.KEY) stands for a placeholder the file writes in angle brackets.

Governed face — three of the changes below are contract-semantics claims, so this PR stays draft and carries needs:contract-review; the card carries it too.

Review round 1 — both FAILs fixed, paid in-file

In-seat contract review at d3a32664 returned FAIL on two spans, PASS on everything else. Both were re-verified at source before editing, both are fixed, and both are paid inside SKILL.md: the file lands back on 5,158 tokens exactly, the same figure it carried at review time. Nothing grew.

#	what was wrong	what it says now	verified at
1	the query-axis note gave all three axes one code, 400 INVALID_FIELD	where and searchableFields answer 400 INVALID_FIELD; orderBy answers 400 INVALID_SORT	packages/objectql/src/engine.ts — assertOrderByIsMaterializable sets err.code = 'INVALID_SORT'; assertSortFieldsExist is the same code at the ingress. An agent branching on the code would have branched wrong on the sort refusal.
2	the cron/template paragraph sent readers to shared/expression.zod.ts for "the formatter whitelist and the cron alias set"	the seven aliases are inlined in the cron row; the template row names TEMPLATE_FORMATTERS, exported from @objectstack/formula, as the introspectable whitelist; the expression.zod.ts pointer is narrowed to the carrier lists it really declares	packages/formula/src/cron-engine.ts (@yearly @annually @monthly @weekly @daily @hourly @reboot); packages/formula/src/template-engine.ts exports TEMPLATE_FORMATTERS via packages/formula/src/index.ts. That file carried neither set, and the sets had lived in the quick references this flight deleted — so the pointer was the last mention of both, resolving to nothing.

Paid by cutting narration of the same class this flight exists to remove: the asc/desc anecdote from the new note, and the Skill Boundaries cron parenthetical now that the surfaces table names Job.schedule.expression and the dialect. Two new identifiers were added and both are live — check:skill-identifier-liveness Leg 1 went 476 → 477 citations and stayed OK.

Token delta

file	before	after	ceiling	headroom
skills/objectstack-formula/SKILL.md	6,002	5,158	6,002	844

Net −844 tokens (−14.1%), 551 → 374 lines. Convention is the ratchet's own: ceil(utf8 bytes / 4), so ceil($(wc -c < file) / 4) reproduces it. Ceiling untouched (FRM-I-01 re-lock is deferred). The generated references/_index.md (302 tok) is untouched.

Gap against the audit's −1,265, itemised per cluster — not smoothed

cluster (commit)	audit est.	measured	gap	why
F-06 / A-01 / G-05 / B-04 / F-07	−515	−440	+75	the two collapsed rows keep their real carrier lists (4 cron carriers, 3 template carriers) so the last mention still points somewhere; F-07 is a small addition inside a deletion cluster
D-05 / D-04 / B-03	−522	−389	+133	all three are MERGE-INTO, not DELETE. Rules the audit's raw span estimate wrote off survive: the onError clause, "a condition that does not even compile aborts the same way", the ADR-0058 per-row statement
D-01 / B-07 / B-06 / D-09 / D-07 / D-02 / B-05 / D-03 / G-03 / G-01 / G-02 / G-04 / E-03	−511	−392	+119	B-06 and B-05 are merges: "Verify your work" absorbed the runtime-throw half of the ADR-0032 callout, and the three determinism conditions folded into the seed pattern's own note rather than vanishing
F-01 / F-03 / F-02 / F-04 / B-01 / B-02 / E-01 / D-08	+237	+356	+119	the two contract notes have to name both refusal doors and both fault directions to be actionable; the type-checked block needs a real import
A-02	+18	+21	+3	—
review round 1	—	0	—	both fixes paid in-file

The gap is one thing four times: a MERGE-INTO finding cannot pay what a DELETE would. Where the audit measured a span's bytes, I measured what was left after the rule inside it was preserved. I did not re-wrap, pad, or cut anything the audit did not name to close the difference.

Per-item 落点 | before | after

Deletions

id	落点	before	after
FRM-F-06 / A-01	### Cron surfaces, ### Template surfaces, ## Cron quick reference, ## Template quick reference	four sections, a formatter table and two code blocks	one ### Cron and template surfaces table, one row each, carriers named, the seven cron aliases inlined and the formatter whitelist named. Both are live surfaces with 0 corpus usages, so neither loses its last mention; the frontmatter no longer says "Do not use for cron schedules" while the body teaches cron
FRM-D-05	section 5 bulk-write prose	165 tokens restating the before* table row, plus query-count and fetch-cost narration	one clause pointing back at that row; the ADR-0058 per-row semantics keep their sentence
FRM-D-04	section 5 abort callout	the pre-protocol-17 logger.warn history and its two opposite-failure examples	the rule only: aborts on before* and after* alike, no onError escape, non-compiling conditions the same
FRM-B-06	top-of-file ADR-0032 callout	ADR-0032 stated 3×, and "Verify your work" cross-referenced the top-of-file note	stated once, in "Verify your work", keeping both halves — build fails with a located did-you-mean, runtime throws
FRM-B-05	## Determinism contract	a section restating the seed pattern's own note	folded into that note
FRM-D-01 / B-07	"Strategic context"	why CEL beat the deleted Salesforce-flavor engine — the first content after the H1	gone
FRM-D-07 / D-02	Core contract tail	"you do not learn three languages" + the roadmap for emitting ast	gone; the envelope rule both carried survives once
FRM-B-03	section 5 previous totality	the has()-on-a-declared-field rule stated once for record, again for previous	one statement covering both, in the has() section
FRM-D-03 / G-03	## Open questions	two bullets citing CelExprSchema	gone — the symbol has 0 hits in the repo outside this file
FRM-G-05	CEL surfaces table, template notes	a visibleOn / visibility deprecated-alias row, titleFormat noted twice	alias row gone; titleFormat deduped to one carrier cell
FRM-B-02	## See also	a pointer at node_modules/@objectstack/formula/	gone — packages/formula/package.json ships ["dist","README.md","CHANGELOG.md"], and this file already says so
FRM-D-09	Core contract	a type Expression block transcribing shared/expression.zod.ts	one sentence and the pointer
FRM-D-08	"No date arithmetic"	157 tokens of prose carrying five prescriptions	a five-row table
FRM-B-04	template surfaces	"no js dialect" restated	one statement, in Core contract
FRM-G-01 / G-02 / G-04 / E-03	throughout	objectstack build 5×; 7.6 / M9.5 / M9.7 / M9.8; "single quotes (always)"; * 100.0	os build; no milestone numbers; both quote styles; * 100

Additions (each paid by deletions in the same file)

id	落点	what it now teaches	source
FRM-F-01	after the CEL surfaces table	a formula field is virtual — no driver materialises a column, so all three query axes refuse one at both doors: where / searchableFields with 400 INVALID_FIELD, orderBy with 400 INVALID_SORT. Remedy is the stored column, in the same words the sort and search axes already use	packages/spec/src/migrations/entries/semantic/17.engine-find-formula-filter-refused.ts; packages/objectql/src/filter-comparand-shape.ts; packages/objectql/src/engine.ts
FRM-F-03	same place	a form-view visibleWhen is CLIENT-SIDE only and faults open (true), so it is never access control — and where the opposite holds: Hook / SharingRule condition and validation predicates abort the write	packages/spec/src/ui/view.zod.ts (FormFieldSchema / FormSectionSchema visibleWhen); packages/metadata-core/src/form-predicate-root-policy.ts
FRM-F-02	CEL syntax cheat-sheet	the two missing roots: parent (line-item cell readonlyWhen / requiredWhen) and data (metadata-editing forms, repeater rows included)	packages/spec/src/data/field.zod.ts; BOUND_FORM_VIEW_PREDICATE_ROOTS
FRM-F-04	translation table + its warning	flow conditions bind bare identifiers — the engine spreads the record's variables to top level. The table's first row implied record. prefixing was universal	packages/services/service-automation/src/engine.ts — "bare identifiers like status / previous.status resolve — the natural authoring style for record-change start conditions"
FRM-A-02	frontmatter description	that this is the companion skill objectstack-data / -ui / -api / -automation each tell you to load alongside them	those four descriptions
FRM-B-01	## See also	a link to references/_index.md — formula was the only domain package that orphaned its own generated index (8 of 9 link theirs)	—
FRM-E-01	Mandatory pattern 3	the predicate block is now type-checked. Both previously marked blocks were the cron and template quick references, so no "Mandatory pattern" was checked at all	see the ablation below
FRM-F-07	view-filter prohibition	names the alternative it was withholding: date macro tokens, pointing at objectstack-query rules/filters.md	skills/objectstack-query/rules/filters.md

Anchor rulings honoured

This package is the CEL anchor; the automation flight (#14467) and the query flight (#14443) deleted their CEL restatements on that ruling. All three anchored constructs survive with their headings addressable:

• ## ObjectStack CEL standard library — the 35-function table, untouched
• ## Mechanical translation table (legacy → CEL) — including the OLD / NEW rows and the warning below it (the warning gained the flow-condition exception; nothing was removed)
• ## Surfaces that take an Expression — the CEL surfaces table, minus the one deprecated alias row

The packages/formula pin tests both pass, quoted below.

Premise adjustments — no finding was forced

• FRM-B-02, half true. The audit reads :548-551 as pointing at an unreadable package. That holds for the @objectstack/formula line. The second pointer, node_modules/@objectstack/spec/src/shared/expression.zod.ts, is readable in an installed app — packages/spec/package.json ships src/**/*.zod.ts. Kept, and the additions lean on it.
• FRM-B-04, 2 instances not 3. The audit lists :81-83, :476-478 and :51. The first two restate "there is no js dialect" and one was deleted. :51 is the Skill Boundaries row routing L2 hook bodies to objectstack-data — a routing row that never states the claim. Realized 2 → 1.
• FRM-D-08 is not ≈0. Measured −7 tokens as a table.
• Everything else held at my base. skills/objectstack-formula/** is byte-identical between the audit ref a59f78d, the dispatch base 18d816a5 and my branch point 93940d49, so every skills/ span was valid unchanged; packages/** citations are re-cited above at the tree in this PR.

Follow-ups (⛔ deliberately not touched here)

• follow-up for objectstack-automation — verified on origin/main and on the delivered branch claude/issue-14308-skills-automation-optimization (PR skills(automation): optimization flight — the authored control-flow trio taught and the BPMN trio demoted, notify given its fence, the eval deduplicated, hooks and ETL pointed away (net −1,278 tokens) #14467), recording only what is still there. The full CEL contract, stdlib (...) callout at :41-43 is gone on that branch. The numbered rule "Conditions are bare CEL — only the stdlib is callable" survives, still enumerating ~14 stdlib names beside a pointer to this package. That enumeration is what remains to cut. (Neither cut has landed on main yet — both restatements are present at the tree in this PR.)
• follow-up for objectstack-data — the seed-context stdlib restatement (now(), today(), daysFromNow(n), daysAgo(n), isBlank(v), coalesce(v, fallback)) is still present beside its pointer here.
• follow-up for skills/README.md — the line "Legacy OLD / NEW evaluate to null since M9.5" is stale twice over: the current truth is a build failure (packages/formula/src/validate.ts, and this package's own stdlib note), and M9.5 is a retired milestone. Generated-region prose, so not editable from this PR.
• FRM-D-06 — the ~10,000-row predicate-write refusal is stated here but belongs in a host package. Left in place; moving it is a cross-package edit.
• FRM-H-01 — the missing evals/. This is the package's sole unexcused omission (8 of 8 other domain packages ship one), and it cannot be added here: scripts/check-skills-token-ratchet.mjs reds a discovered authored file with no ceiling, and no same-file deletion can pay for a new file. Deferred to [Decision] Skills optimization program — batch 1 (4 items): new-file ceilings for splits · planned-eval stubs · react-blocks double rendering · published pm-dispatch scope #14296 item 2, as ruled.
• FRM-I-01 — the ceiling can now be re-locked 6,002 → 5,158. Phase 3, not this PR.
• FRM-C-05 — filed as [finding] The objectstack-formula reference index advertises data/date-macros.zod.ts, a surface the SKILL.md routes to objectstack-query — SKILL_MAP in build-skill-references.ts maps it to both #14562 (unassigned, spec lane) after a dedupe search that returned a known-present control. Nearest neighbours named on it: [finding] The objectstack-ai generated reference index advertises 6 schemas the SKILL.md never teaches and omits the one it names — SKILL_MAP in build-skill-references.ts is unreconciled with the body #14462, [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 #14466, [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 — the same "SKILL_MAP is unreconciled with the body" class in three other packages.

Gates — head sha 291f7bd7

Re-derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands after the round-1 edit and after merging origin/main: 36 commands, whole list run, list identical across all three derivations. Two derivations were refused as STALE and each was answered by merging origin/main rather than by reading the old copies — the first (33 commits behind, 148 family files changed) conflicted only in the two generated files, which were resolved to main's side, committed, and only then regenerated, never in MERGE state; the second (5 commits behind, changing .github/workflows/lint.yml and scripts/role-word-baseline.json, both of which the families read) merged cleanly. The @objectstack/spec + @objectstack/client-react closure was rebuilt after each merge — check:skill-examples and check:docs both refuse a stale dist and said so, by name, rather than answering falsely green.

35 / 36 green. The one non-zero is node scripts/check-test-completeness.mjs → exit 3, which that script defines as a MISSING or UNREADABLE LOG — NOT MEASURED, not red. Exit codes were captured by redirecting each command to its own file before any pipe.

Card-named gates, quoting each gate's own verdict line:

• node scripts/check-skills-token-ratchet.mjs — ✓ check-skills-token-ratchet: skills/objectstack-formula/SKILL.md is 5158 tokens (ceiling 6002; headroom 844). and ✓ check-skills-token-ratchet: 37 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.
• pnpm --filter @objectstack/spec check:skill-examples — ✅ 260 prose examples type-check across 3 surface(s) — every marked block parsed, so tsc ran the SEMANTIC pass on all of them
• pnpm check:skill-compatibility — ✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 78 workspace packages
• pnpm check:skill-identifier-liveness — check-skill-identifier-liveness OK — Leg 1: 477 citation(s) over 47 published file(s) checked against 93135 implementation word tokens (3 ledgered exemption(s)); Leg 2: 8 registered exhaustive section(s), 0 ledgered gap(s). Leg 2 was checked before the first deletion: none of the 8 registered exhaustive sections is in this file.
• pnpm --filter @objectstack/spec check:skill-docs — ✅ Skill docs in sync
• packages/formula pin tests — pnpm --filter @objectstack/formula exec vitest run --maxWorkers=2 src/cel-stdlib-drift.test.ts src/skill-catalog-sync.test.ts → Test Files 2 passed (2) / Tests 5 passed (5). The stdlib anchor is intact.
• pnpm check:role-word — green, no ratchet-DOWN, so scripts/role-word-baseline.json is untouched.

Heavy steps ran under scripts/pm/os-verify-lock.sh with OS_VERIFY_LOCK_SLOT=issue-14316. The pushed remote head equals the tree the gates read (291f7bd7, verified with git ls-remote).

FRM-E-01 ablation — the marker is not a phantom green

The new marker was added only after the gate passed with it, then ablated once. Mutation and restore were both proven on disk rather than by an editor's exit code:

• HEAD blob 21ee6b50; a semantic-only mutation was injected (assigning the P tagged template's Expression result to number), leaving the block syntactically valid so the failure could only come from the semantic pass.
• Mutation proven on disk: injected text grep -c = 1, anchor still 1, git hash-object = 79936c1f ≠ HEAD blob.
• Gate on the mutated tree: exit 1, and it named the block — skills/objectstack-formula/SKILL.md:243:7 error TS2322: Type '{ dialect: ... }' is not assignable to type 'number'. The right file, the right line, my block.
• Restore leg given the same treatment as the mutation leg: git checkout HEAD -- with an absolute path (never the bare form, which restores from a polluted index), inside a trap ... EXIT INT TERM using absolute paths. Proven by git hash-object = 21ee6b50 (equal to the HEAD blob, non-empty) and git diff HEAD empty — not by the restore's exit code.
• No rebuild was needed between legs: the gate reads the markdown directly, and the mutated artifact was that markdown, not a package dist.

Labels

skip-changeset — this PR releases nothing. Verified against the gate's own enumeration rather than assumed: scripts/check-empty-changeset.mjs carries a "GREEN 3: a skills/**-only PR carrying NO changeset (route 2)" case asserting exactly this shape must be green, and no packages/*/package.json ships skills/ in its files[]. Plus needs:contract-review, because FRM-F-01, F-03 and F-04 are contract-semantics claims.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1