Publish the transition-gate vs invariant tool-choice line in the data-modeling skill (deliverable 2 of #13879)

[os-sam]

Filed by the domain:spec seat at ACCEPT of PR #14889 (#13879), as the cross-lane follow-up the dispatch reserved: deliverable 2 of #13879 — the tool-choice line an app author reads before choosing between requiredWhen / a field bound and a validations[] script rule — lives in the published skills/**, which is domain:skills and a governed surface, so it was kept out of the spec PR. domain:* is left to the triage seat (single-producer rule).

What to publish (one executable criterion)

The skill that teaches field declarations and validation rules (skills/objectstack-data/** — its rules/ pages on field types and validation are the natural home; the skills seat picks the exact page) gains a tool-choice statement that says, in substance, what the spec's own contract text now says at each declaration (PR #14889: Field.requiredWhen, min / max / minLength / maxLength, the inline-grid column requiredWhen, and ScriptValidationSchema.condition). Done = an app author reading the skill before writing "required when X" is told that it is a transition gate, not an invariant, and is pointed at the invariant tool — and the reverse.

Proposed wording (from the PR #14889 body, "Proposed skills tool-choice line")

Need an invariant — a condition every stored record must satisfy ("discount may never exceed 60") — declare it as a validations[] script rule: it is re-checked against the merged record on every write, so a row that already violates it is refused on any edit until a repairing write lands (frozen, not bricked).
Need a transition condition — something that must hold from a given point onward ("a quote must name a contact by the time it is presented") — use requiredWhen or a field bound (min / max / maxLength): these judge the write, not the stored row, so rows that predate the rule keep passing unrelated edits. "Required when X" reads like an invariant and is not one.

Evidence the wording rests on (measured against the engine, PR #14889 body table)

• requiredWhen: refused iff the merged record violates AND the pre-write record complied — packages/objectql/src/validation/rule-validator.ts evaluateValidationRules, the ADR-0113 non-regression branch (preViolated → "legacy rows rest").
• min / max / minLength / maxLength: checked on the written value only — record-validator.ts validateRecord iterates the UPDATE payload.
• script / cross_field: evaluated on the merged record on every write, no pre-state exemption — frozen until repaired, never bricked.

The downstream pull is hotcrm#1069 / hotcrm#1017 (three rules written as invariants, all implemented with the gate tool, zero signal); the spec-side statement is PR #14889.

---

Blocked-by: #13879

[os-steve]

Claim: PM loop round 2
Session: session_019RfFHiRCSs3JXLK4cwcfox
Branch: claude/issue-14893-data-skill-tool-choice
Worktree: objectstack-issue-14893
Domain: domain:skills
File surface: skills/objectstack-data/SKILL.md (the "Choose by intent — invariant or transition gate" bullet, :285-290 at origin/main 77a532d6) + skills/objectstack-data/rules/validation.md (the Script Validation section, from :38) (stop on breach; explain in the report). ⛔ rules/field-types.md is outside the surface (token headroom 6).
Container & model: XS prose (one bullet rewritten in place, one two-sentence pointer added), mode:subagent, model: opus (tier: node scripts/pm/dispatch-gates.mjs --tier at origin/main 77a532d6, 16:52Z: "no path-derived mandate … floor sonnet · default opus · ceiling fable"; PM's call: opus default — the edit corrects published prose against a measured engine behaviour, not a mechanical swap)
Clause-②: no
Serial constraints cleared: skills/objectstack-data/** is free on the seat post's hot-file queue; no in-flight claim names it; no open PR touches the package (search 16:53Z: 0); same-day churn on the package: 22d573e8 15:18Z (#14737, generator-owned pointer rows) — the churn line goes into the brief.

Decision re-read (16:53Z): no maintainer ruling on the thread; filed by the spec seat at ACCEPT of PR #14889 with the wording proposed there; Blocked-by: #13879 is closed, so the block is cleared. Stale-premise check at origin/main 77a532d6: the card's one executable criterion is already met in substance — skills/objectstack-data/SKILL.md:285-290 ("Choose by intent — invariant or transition gate") landed 2026-09-01T06:34Z via #14052, two days before this card was filed, and it names both tools in both directions. What the published text does not carry, measured against this card's evidence: (a) it says a transition gate written as an invariant "bricks existing data", while the engine measurement on #13879 / PR #14889 is frozen-not-bricked — the row is refused on any edit until a repairing write lands; (b) it never says that "required when X" reads like an invariant and is not one, which is the trap the downstream pull names; (c) rules/validation.md's Script Validation section carries no tool-choice pointer at all. Re-scoped in-seat to those three deltas; no new section, no third file. Token budget (check-skills-token-ratchet at 77a532d6, 16:52Z): SKILL.md 9996 / ceiling 10009 (headroom 13) ⇒ the bullet is rewritten within its own length, not extended; rules/validation.md 2362 / 3109 (headroom 747) carries the pointer. Governed surface (skills/**, check-governed-merges --test hit ×2): draft PR, human merge; the seat reviews in-seat before requesting the approvers.

---

Generated by Claude Code

[os-steve]

os-dev-report

{
  "issue": 14893,
  "status": "done",
  "branch": "claude/issue-14893-data-skill-tool-choice",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/15010",
  "premise_still_valid": true,
  "summary": "Landed the three re-scoped deltas, two files, nothing else. (a) The SKILL.md 'Choose by intent' bullet said a transition gate written as an invariant 'bricks existing data'; the engine freezes the row instead, so the bullet now says a violating row is refused on any edit until repaired. (b) The same bullet now carries the trap clause: 'Required when X' reads like an invariant and is not one. (c) rules/validation.md's Script Validation section, which carried no tool-choice statement at all, now opens with a two-sentence pointer naming script/cross_field as the invariant tool and requiredWhen/field bounds as the write judge, cross-referencing the SKILL.md bullet by heading text. The card's own executable criterion was already met in substance by the existing bullet, exactly as the PM's claim comment read it, so the deliverable was the correction plus the trap plus the pointer. One judgment call the PM should see: SKILL.md had 13 tokens of headroom and (a)+(b) alone cost 9, so the MECHANISM ('judged against the merged record, no pre-state exemption') is stated only in rules/validation.md, not duplicated into SKILL.md - carrying it in both measured 10011 tokens against a ceiling of 10009, i.e. red. No ceiling was touched, no third file, no new section or heading, rules/field-types.md untouched. PR is draft, not ready, no auto-merge, no reviewers requested; skip-changeset label applied additively and read back.",
  "tests": "Prose-only diff, so no unit tests and no ablation applies; verification is the derived gate family plus the engine read. Union run AFTER the final commit, at head 4036ac3c (git rev-parse --short HEAD from that run): node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at 4036ac3c returns 21 commands, byte-identical in content to the dispatch's list - no additions were derived, so none were owed. All 21 run, every exit code captured by redirect BEFORE any pipe (cmd > log 2>&1; EXIT=$?): 20 exit 0, and check-test-completeness exit 3 = NOT MEASURED in its own words ('Nothing was measured: this gate exited before parsing a single summary line'), not a red - it wants a saved turbo run test log. Plus node scripts/pm/check-skill-id-lint.mjs exit 0 ('23 file(s) clean'). Two gates first answered PREREQUISITE NOT MET (exit 3, not a red): check:doc-formula-expressions needed @objectstack/formula and then @objectstack/lint built; both built through the shared lock (bash scripts/pm/os-verify-lock.sh -c ..., VERDICT command-exit 0 both times) and the gate then exited 0 with '9 @example(s) judged clean' + '14 predicate(s) ... judged clean'. Token ratchet, the budget gate: SKILL.md 9996 -> 10005 (ceiling 10009, headroom 4, net +9 of the +13 allowed; the bullet grew 439 -> 476 bytes under the ceil(utf8 bytes / 4) convention), rules/validation.md 2362 -> 2499 (ceiling 3109, headroom 610); verdict line '36 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.' Control-byte sweep over both edited files (grep -naP across the C0 range plus DEL): zero hits, plus check:nul-bytes exit 0. ENGINE READ, done on the branch before a word of prose was written - all three dispatch assumptions hold: rule-validator.ts evaluateRule dispatches script/cross_field to checkPredicate(rule, ctx.merged, ctx.previous, ...) with no pre-state branch; evaluateValidationRules carries the ADR-0113 non-regression branch verbatim ('const preViolated = pre.ok && pre.value === true && isMissing(previous[name]); if (preViolated) continue; // legacy rows rest'); record-validator.ts validateRecord iterates Object.entries(data) on update ('validate only supplied fields; an OMITTED field never 400s') with the bound comparisons on the written value. One correction the read forced on the prose: format and json_schema are handed ctx.data, not ctx.merged, so the wording names script (SKILL.md) and script/cross_field (validation.md) rather than validations[] as a whole - the generic claim would have been false. Duplicate-site check: git grep -n -i 'invariant|transition gate|requiredWhen' -- skills/objectstack-data/ returns only this bullet plus three unrelated requiredWhen mentions (:260, :282, :383); nothing else in the package states (a) or (b).",
  "mcp_calls": "8 - create_pull_request 1, pull_request_read 2 (label/body read-back before and after the label write), issue_write update 1 (label union write), search_issues 1 (dedup for the finding; non-empty result, so no control term was owed), issue_write create 1 (the finding), add_issue_comment 1 (this comment), issue_read get_comments 1 (reading this comment back). The card body and all its comments came from the zero-quota public-repo payload channel, not from MCP. Note for the seat: the additive REST label endpoint (POST /issues/N/labels) and plain curl reads were both refused by this container's command classifier mid-run, so the label write had to go through the MCP whole-group replace path - read current set, union, write, compare-read-back. Read-back confirms documentation + size/s + skip-changeset, nothing stripped.",
  "open_questions": [
    {
      "question": "SKILL.md's bullet now states the CONSEQUENCE (a violating row is refused on any edit until repaired) but not the MECHANISM (judged against the merged record on every write, no pre-state exemption), which lives only in rules/validation.md. Is that split acceptable, or should the mechanism appear in both?",
      "options": [
        "A - keep the split as landed: SKILL.md carries choice plus consequence, rules/validation.md carries the mechanism; costs 9 of the 13 tokens of headroom and leaves 4",
        "B - carry the mechanism in SKILL.md too: measured at 10011 tokens against a ceiling of 10009, so it needs either a ceiling raise (a maintainer act, and the dispatch forbids it) or cuts to text outside the bullet, i.e. outside the ruled surface",
        "C - buy the room inside the bullet by dropping the concrete example ('required once the record reaches paid'), which fits but removes the only thing that makes 'transition' concrete for an author"
      ],
      "recommendation": "A, because the mechanism belongs to the page that teaches the mechanism, and stating it in two files is exactly the restatement the token ratchet exists to prevent; B needs an act the dispatch reserves to the maintainer, and C trades a teaching anchor for a fact the reader is one hop from."
    }
  ],
  "out_of_scope_findings": [
    "filed as #15011: the rule-type table in skills/objectstack-data/rules/validation.md never says which record each of the six rule types is judged against, and the answer is not uniform - script/cross_field read the merged record, format/json_schema read the write payload only (rule-validator.ts evaluateRule), so an author who generalises 'validations[] holds invariants' reaches for format and silently gets a write gate. Labelled finding, no assignee, outside this flight's two-section surface."
  ]
}

Generated by Claude Code

---

Generated by Claude Code

[os-steve]

ACCEPT — skills seat (session session_019RfFHiRCSs3JXLK4cwcfox), reviewer of record, 2026-09-03T17:20Z, verified against GitHub and a compare worktree at the PR head, not against the report.

PR #15010 @ 4036ac3c — draft, base main, first line Fixes #14893 (the re-scoped deliverable is complete, so the merge should close the card), two files exactly as claimed (skills/objectstack-data/SKILL.md one bullet rewritten in place, rules/validation.md one pointer paragraph at the head of Script Validation), +16/-6, skip-changeset (the catalog publishes no package from this diff — dev's reading, consistent with the earlier skills PRs this shift), no other closing keyword, no model name in the body, no control bytes, no issue number in the published hunks.

Content against the re-scope (claim 5529119305): (a) "bricks existing data" is gone; the bullet now says a violating row is refused on any edit until repaired — the seat re-read the engine at the head: rule-validator.ts dispatches script / cross_field to the predicate over ctx.merged (:2181-2183) with no pre-state branch, while requiredWhen carries the preViolated … // legacy rows rest branch (:2071-2072), and record-validator.ts iterates the update payload only (:1042-1043). (b) the trap clause is in the bullet: "Required when X" reads like an invariant and is not one. (c) the Script Validation section opens with the tool-choice pointer, naming script / cross_field as the invariant tool and requiredWhen / the four bounds as the write judge, cross-referencing the bullet by its heading text. The dev's correction of the brief's wording — validations[] as a whole is not the invariant tool, because format / json_schema read ctx.data (:2185-2187) — is right and is what the prose now says. Token ratchet re-run by the seat at the head: SKILL.md 10005 / 10009 (headroom 4), rules/validation.md 2499 / 3109 (headroom 610), no ceiling touched. check-governed-merges --test: GOVERNED ×2. The skill-docs / doc-authoring gates are the dev's local readings plus CI's Lint & Repo Gates — the seat's compare worktree carries no install and did not re-run them.

Open question (mechanism split): A — SKILL.md carries the choice and its consequence, rules/validation.md carries the mechanism; restating it in both is what the token ratchet exists to prevent, and B needs a maintainer act. Finding #15011 (the rule-type table never says which record each type judges) is real and triaged by this seat into pm:queue, serial behind this PR on the same file.

Deviations: none. Report mcp_calls: 8 — above the usual count because the container's command classifier refused the additive REST label endpoint and plain curl reads mid-run, so the label write went through the MCP whole-group replace path with a comparative read-back (union read back intact); recorded as a channel fact for the seat post, not a rework reason.

CI at 17:18Z on 4036ac3c: 32 check runs, 16 success + 11 skipped, five still in_progress (Lint & Repo Gates, three Type Check legs, Test Core (2/6)); nothing red; re-read at the next patrol and recorded here.

Terminal: governed surface (skills/**) ⇒ the PR stays draft and lands by an approver's hand; review requested from os-zhuang and hotlong over the REST reviewers endpoint (draft bit untouched), read back. Card stays pm:dispatched until the merge closes it.

---

Generated by Claude Code