write down the app-vs-platform boundary: which work belongs in a metadata app and which is a platform gap — into AGENTS.md, and evaluate whether the published skills should carry it too

[hotlong]

Maintainer-requested, 2026-09-04, verbatim: 「原则应该写入 本项目agent 记忆。哪些应该在元数据应用中开发,哪些应该完善平台能力。」 and 「包括评估是否应该更新objectstac官方skills」.

Why now

The boundary has been decided ad hoc, several times, by different seats, on the same day — and each time from scratch. Three worked rulings from 2026-09-04, all with measurements behind them:

• feat(runtime): every top-level collection read gains a packages[] path (#15005) #15261 — a new module was needed by four call sites inside one package. Ruled: do not publish it from @objectstack/core; keep it package-private and decide its home when a second consumer appears.
• 17.3.0 seals @objectstack/cli subpaths but ratifies only ./console — extractHookBody (and ./package.json) have no public entry, and an app's hook-body fidelity harness breaks with no replacement #15325 — an app needs the platform's hook-body lowering pass to test what actually ships; 17.3.0 sealed the subpath. Half the need turned out to be already an os command (os build --strict-body, which turns "bundled instead of lowered" into exit 1). The card had asserted an os lint rule that does not exist anywhere in the tree.
• audit — hotcrm ships 69,419 lines of hand-written test against a 39,734-line metadata app: split them three ways and measure how many lines os verify should have derived #15418 (open) — hotcrm carries 69,419 lines of hand-written test against a 39,734-line metadata app, and a first pass suggests a large share of it asserts only that the metadata is self-consistent — work a platform can derive.

Nothing in AGENTS.md, CLAUDE.md or skills/** states the rule. So every seat re-derives it, and the re-derivations differ.

The rule to write down

Not new policy — the rule those three rulings already followed, stated once so it stops being re-derived.

The question that decides it: could this be written by something that has only the metadata, and no knowledge of this company?

	belongs in	examples measured on hotcrm
No — it encodes a company's own judgement	the metadata app	a discount ceiling, who a case is assigned to, how won/lost is booked; the company's own objects, views, flows
Yes — it only asks whether the metadata is self-consistent	the platform	reference integrity, translation coverage, view rosters, sharing-rule coverage, CRUD round-trips, RLS probes per declared position
the subject is platform behaviour, the cost lands on the app	the platform, and it is a gap until it does	asserting what a hook does inside the platform's own sandbox (#15325)

Second question, for a capability an app wants published: if a second app needed this, would it copy the implementation? Yes ⇒ platform. That is the #15261 test, and it is why one consumer defers rather than publishes: one consumer is a use, two is a contract.

Two anti-patterns, both measured today, both worth naming

• ⛔ An app hand-copying a platform rule. A copy passes while diverging from the rule the build actually applies — the app's tests stay green while the platform refuses. 17.3.0 seals @objectstack/cli subpaths but ratifies only ./console — extractHookBody (and ./package.json) have no public entry, and an app's hook-body fidelity harness breaks with no replacement #15325's harness header states exactly this and refuses to take that route; finding — a gating lint rule shipped claiming "0 findings over the corpus" and names an object that fires it; the corpus copy is not the real app #15357 is the same shape one level up, where a rule shipped claiming "0 findings over the corpus" against a corpus that was not the app it named.
• ⛔ A platform capability that under-delivers silently. os verify on a multi-package app derived zero cases and reported success (record — the option-B reader by-shape sweep: method, derived 37-key collection set, triaged false positives, and the two packages it found #15210). An app that meets that writes its own — and never comes back. So the order is fixed: make the derived half trustworthy first, then take the hand-written half back. Reversing it just deletes protection.

Where it goes

1. AGENTS.md. The source of truth this repo's agents read.

⚠️ Two hazards, both real:

• AGENTS.md is a governed surface (§522). ⛔ Auto-merge is never armed on it; it lands by human review.
• It is under the shrink-only check:pm-skill-ratchet line ceiling, last re-anchored at 1162 lines by PR docs(agents): a PM-dispatched card arrives already assigned — claim comments, not the assignee field, say who owns it (#15287) #15290. Measure the ceiling before writing and make the addition fit — reflow the section you add to rather than pushing the file over. ⛔ Do not raise the ceiling to make room.
• ⚠️ PR docs(agents): a PM-dispatched card arrives already assigned — claim comments, not the assignee field, say who owns it (#15287) #15290 is open right now and touches AGENTS.md and CLAUDE.md. Branch from main, keep the addition in its own section away from docs(agents): a PM-dispatched card arrives already assigned — claim comments, not the assignee field, say who owns it (#15287) #15290's claim paragraph, and check git merge-tree --write-tree --name-only origin/main <your head> before you report — a silent conflict on this file cost five hours today on a different PR.

2. CLAUDE.md gets the condensed mirror only if the rule meets that file's own stated bar ("the rules that must never be missed, because missing one wastes or corrupts other agents' work"). Argue it either way — ⛔ do not assume it qualifies.

3. The published skills/ — evaluate, do not assume. There are 11 published skills (objectstack-ai, api, automation, data, formula, i18n, platform, pm-dispatch, query, ui, upgrade). This rule is aimed at someone building an app on the platform, which is exactly that audience.

Read them and answer, with reasons:

• Does one of them already own this question? objectstack-platform and objectstack-upgrade are the obvious candidates by name — check, don't assume.
• Is the app-facing half ("before you hand-write it, ask whether the platform should derive it") a fit for a published skill, or is it internal contributor guidance that would just be noise to a customer?
• ⛔ If the answer is "no published skill should carry this", say so and why — that is a perfectly good outcome and better than a paragraph nobody reads.

Acceptance

• The rule stated once, in prose an agent can apply without a worked example — the deciding question, the second question for publication, and the two anti-patterns.
• Every claim traceable: cite the ruling or the measurement, ⛔ never "as a rule we prefer…".
• check:pm-skill-ratchet green, with the line count read out.
• A stated verdict on CLAUDE.md and on each candidate published skill, including the "no" verdicts.
• ⛔ No other edits to AGENTS.md. ⛔ Do not tidy neighbouring sections.

⛔ Not in this card

⛔ Do not change any code, any test, or os verify. ⛔ Do not act on #15418's audit — it is running in parallel and its numbers are its own deliverable. This card writes the rule; that card measures the debt.

[hotlong]

Claiming this card.

• session: session_01UHvF5hyiZjnCyExFnfQB8m
• branch: claude/issue-15420-app-vs-platform-boundary (pushed, branched from origin/main at 5f7fa1de0)

Comments were empty before this one, so no earlier claim by another session. Assignee is the maintainer (hotlong) from the dispatch atom; the branch above is the dev identity for this run.

Generated by Claude Code

---

Generated by Claude Code

[hotlong]

os-dev-report

{
  "issue": 15420,
  "status": "needs_decision",
  "branch": "claude/issue-15420-app-vs-platform-boundary",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/15427",
  "premise_still_valid": true,
  "summary": "The AGENTS.md section is written, committed and pushed as draft PR #15427 (32 insertions, 0 deletions, pure insertion between 'Route & surface ownership' and 'Degradation log levels'). It states the deciding question, the second question for publication, and both anti-patterns. It CANNOT LAND without a maintainer ceiling ruling, and the card forbade me from taking one: AGENTS.md is 1161/1162 on main (headroom 1) and the section costs 32 lines, so check:pm-skill-ratchet is red at 1193 vs 1162. The card's proposed funding (reflow to fit) is banned by the ratchet's own 2026-08-17 ruling against re-wrap funding, cited seven times in check-skill-line-ratchet.mjs and refused on precedent even when it was available. Three card sub-premises corrected, all with evidence in the PR body: (1) 'every claim traceable' cannot be spelled with issue numbers in AGENTS.md — check:pm-skill-id-lint went red on 6 citations under the 2026-08-12 ruling that operative text carries lessons self-contained, so every lesson was rewritten and the section now names no issue at all; (2) skills/** is NOT silent on this — skills/objectstack-platform/SKILL.md:229 already has a section titled 'The App / Platform Boundary' and already carries anti-pattern 1 nearly verbatim at :240; (3) os verify's zero-case defect was closed on main two commits before this branch's base, so the lesson is written as landed rather than live. Also: PR #15290 lands at net +1, consuming the last line of headroom, so after it merges the ask becomes 1162 -> 1194. Verdicts delivered in the PR body: CLAUDE.md NO (all four of its rules are cross-agent collisions the victim cannot prevent and each names an enforcing hook or says none exists; this rule costs only your own card and is caught on review — #15261 is the proof); published skills — objectstack-platform already owns the question, objectstack-pm-dispatch NO (it defers to that section by name at :648), objectstack-upgrade NO (different boundary, chain vs hand-edit, at :28), the other eight NO (per-domain authoring skills, eight copies is eight drift sites), and the publication half must never ship to customers at all.",
  "tests": "No code, test or os verify change — documentation only, per the card's exclusions. Gate family derived at the final head, not recalled: `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` -> 1 path (AGENTS.md), 15 runnable families. All 15 run at final commit 660ed00ce under the shared verify lock (OS_VERIFY_LOCK_SLOT=issue-15420; held 87s, waited 0s), each exit code captured before any pipe via `cmd > log 2>&1; EXIT=$?`. 13 GREEN: check:pm-governed-prose, check:pm-governed-merges, check:pm-skill-id-lint, check:nul-bytes, check:agent-test-spelling, check:docs-audit-scope, check:required-contexts, check:driver-memory-census, check:refd-timer-probe, check:watch-hint-literal, check-comment-mask-corpus, and both check-closing-keyword-parity spellings with their self-tests. 1 RED, quoting the gate's own verdict line: 'check-skill-line-ratchet: AGENTS.md is 1193 lines; the ratchet ceiling is 1162. Raising a ceiling requires a maintainer ruling quoted in the PR.' The companion row stayed green and unmoved: 'AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0)' — the row this adds is 219 bytes. 1 NOT MEASURED, not counted as either colour: check-required-contexts.mjs --verify-required-set exits 2 (HTTP 401 without a token, 403 retried with NODE_OPTIONS=--use-env-proxy); its own text says 'NOT VERIFIED is not a pass and not a failure of the tree; exit 2 classifies the ENVIRONMENT'. Conflict check, both clean at exit 0 with a tree OID and no conflicted-path list: `git merge-tree --write-tree --name-only origin/main HEAD` -> 929d18f1, and against the open AGENTS.md PR `git merge-tree --write-tree --name-only origin/pr-15290 HEAD` -> 2fb29e55; structurally the two are ~500 lines apart (#15290 at 457-477, this at 965-996). PR body gates run locally with PR_BODY set: check-partof-closing-keyword green ('carries no Part-of/closing-keyword contradiction'); check-single-claim-paths could not run (network call for a synthetic PR number — environment, not a verdict). Byte discipline: `grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]' AGENTS.md` matches nothing; no non-table line in the new section exceeds the 120-byte wrap limit. Skills budget measured for the follow-up card: check-skills-token-ratchet reports skills/objectstack-platform/SKILL.md at 12868 tokens (ceiling 12984; headroom 116). Claims re-verified against the tree rather than taken from the card: os build --strict-body is real (packages/cli/src/commands/compile.ts:109; build.ts extends Compile), os verify exists (packages/cli/src/commands/verify.ts), and verify.ts already carries the anti-pattern's own sentence. No ablation applies — this diff adds no executable behaviour.",
  "mcp_calls": "10",
  "open_questions": [
    {
      "question": "AGENTS.md is 1161/1162 on main (headroom 1) and the section costs 32 lines. The card forbade raising the ceiling, and the ratchet's own 2026-08-17 ruling bans paying by re-wrap, so there is no route I may take alone. How should the section be funded?",
      "options": [
        "A — raise the ceiling 1162 -> 1193 (1194 after #15290 lands) with the ruling quoted in PR #15427. Precedent-compliant: every prior AGENTS.md raise (958->961, 1149->1150, 1150->1158, 1158->1162) took exactly this route, and on .claude/agents/os-dev.md re-wrap funding was available and was REFUSED in favour of a ruled raise. Cost: +31 over headroom, the largest raise this map has taken.",
        "B — keep a 3-4 line pointer in AGENTS.md, full rule in a non-ratcheted home (a docs/adr page). Still needs a small raise (headroom is 1), and it costs every seat a second read at the moment the rule is needed.",
        "C — pay in place by deleting AGENTS.md content. The card forbids other edits and I found no dead content within scope; auditing 1161 lines for deletable text is a different card.",
        "D — do not put it in AGENTS.md; extend skills/objectstack-platform's existing 'The App / Platform Boundary' section only. Zero line-ratchet cost, but the publication test is contributor-only and would be noise to customers, and this repo's seats do not read the published catalog."
      ],
      "recommendation": "A. Real business need: the pull is measured, not speculative — three seats decided this from scratch on one day and the derivations differed, which is the exact cost a written rule removes; D does not serve it because the seats that re-derived it read AGENTS.md, not the customer catalog. Long-term soundness: A is the route the ratchet itself prescribes ('Raising a ceiling requires a maintainer ruling quoted in the PR') and the one all four prior raises took, so it adds no new mechanism and leaves headroom at 0 by construction; B splits one rule across two files, which is the drift shape the repo's mirror gates exist to catch. Making AI-written code hard to get wrong: A puts the discriminator in the file every seat reads in full before acting, whereas B is read only by the seat that already suspects it needs the rule — the seat that least needs it. Startup scope discipline: this is the axis that argues against A on size, and it is why the section was compressed to 32 lines with a table (rows are exempt from the 120-byte wrap) and why the publication half is deliberately kept out of the customer catalog rather than duplicated; the addition buys back re-derivation hours that are already being spent, so it is not capability expansion. Four-axis conflict is only on size, and pull plus soundness outrank it.",
      "note": "If A is granted, the ratchet entry needs the ruling's date and verbatim text added beside ['AGENTS.md', 1193] in scripts/pm/check-skill-line-ratchet.mjs — that edit is not in PR #15427, since making it myself would be the raise the card forbade."
    },
    {
      "question": "Who applies the skip-changeset label to PR #15427? The dispatch order reserved it ('标签我打'); my standing dev contract says the dev applies it the moment the PR opens and never waits for Check Changeset to go red.",
      "options": [
        "PM applies it, as the dispatch order stated.",
        "I apply it on a later turn via the MCP fallback (read current labels, union, write the whole set, then a comparison read-back)."
      ],
      "recommendation": "PM applies it. I did NOT apply it, and the reason is mechanical rather than deference: the additive REST endpoint this write prefers is unavailable to this session (HTTP 403 on a repo-scoped read, gh absent), leaving only a whole-set PUT that can strip a concurrent label — and pr-automation.yml's own header records the size-labeler doing exactly that to a skip-changeset label within a second, read-back included. Judgement is stated in the PR body as the card asked. Worth noting for whoever applies it: Check Changeset has exactly two exemptions — the label and the changesets release branch — and NO path-based exemption, so an AGENTS.md-only PR is red without it. ⛔ An empty changeset would be wrong and was not written."
    }
  ],
  "out_of_scope_findings": [
    "filed as #15428: skills/objectstack-platform/SKILL.md:229 'The App / Platform Boundary' states which side owns what (:236) and already carries the hand-copying anti-pattern (:240), but not the discriminator that produces the answer — the metadata-only deciding question. Unassigned, no labels, left for PM triage. Budget measured: 116 tokens of headroom against a three-line amendment, so no ceiling raise is needed. Deliberately not folded into PR #15427: skills/** is a separate governed, customer-visible surface."
  ]
}

Generated by Claude Code

---

Generated by Claude Code

[hotlong]

os-dev-report

Supersedes my earlier report on this card. That one reported needs_decision on a ceiling raise; the PM retracted the "no other edits" constraint, which opened a route that keeps 1162 fixed. The rule has landed and every gate is green.

{
  "issue": 15420,
  "status": "done",
  "branch": "claude/issue-15420-app-vs-platform-boundary",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/15427",
  "premise_still_valid": true,
  "summary": "The rule is written down, the AGENTS.md ceiling is untouched at 1162, and check:pm-skill-ratchet is green. Shape: AGENTS.md gains ONE line (1161 -> 1162, exactly the ceiling) as a Context Routing row carrying the deciding question plus a pointer; the rule itself — deciding question, publication test, both anti-patterns with the measurement behind each — lands in a new .claude/skills/pm-dispatch/references/app-platform-boundary.md (66 lines), entered in BOTH ratchet maps at its landed count so it arrives metered rather than as an un-ceilinged file in a ratcheted directory. Whole diff 3 files, 76 insertions, ZERO deletions: nothing was removed, shortened or relocated to make room. Why not the 8-12 line prose version: headroom was 1 line and both author-only funding routes are closed — re-wrap funding is banned by the 2026-08-17 ruling, and a declared cross-file move cannot fund new content because the source decrease cancels (1161 - N + K <= 1162 - N reduces to K <= 1 for any N). Four card sub-premises corrected with evidence, all in the PR body: (1) 'every claim traceable' cannot be spelled with issue numbers in AGENTS.md or under .claude/skills/pm-dispatch/ — check:pm-skill-id-lint went red on 6 citations under the 2026-08-12 ruling, so both files now carry each lesson self-contained and cite SOURCE PATHS instead, which is the more durable anchor; (2) skills/** is not silent — skills/objectstack-platform/SKILL.md:229 already has 'The App / Platform Boundary' and already carries anti-pattern 1 at :240; (3) os verify's zero-case defect was closed on main two commits before this branch's base, so it is written as a landed lesson; (4) main landed the identical new-file-row shape mid-flight (core-rules.md), which caused the one merge conflict and independently confirms the convention. Verdicts: CLAUDE.md NO; objectstack-platform already owns the question; pm-dispatch NO (defers to it by name at :648); upgrade NO (different boundary at :28); the other eight NO; and the publication half must never ship to customers.",
  "tests": "No code, test or os verify change. Gate family re-derived at the final head, not recalled: `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` -> 3 paths, 34 runnable families. All 34 run at final head 087f60a46 under the shared verify lock (OS_VERIFY_LOCK_SLOT=issue-15420), every exit code captured before any pipe. 33 GREEN, including all five scripts that read the ratchet's maps, so the map edit is mirror-checked: check:pm-skill-ratchet, check:pm-skill-id-lint, check:ratchet-remedy-authority, check:skill-frame-sync, check:pm-dispatch-gates, check:pm-governed-prose, check:pm-governed-merges, check:nul-bytes, check:cross-package-test-inputs, check:self-test-wired, check:doc-authoring, check:entry-guard, check:parse-guard, and both check-closing-keyword-parity spellings with their self-tests. Ratchet verdict lines, verbatim at exit 0: 'AGENTS.md is 1162 lines (ceiling 1162; headroom 0)' and 'AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0)' and 'app-platform-boundary.md is 66 lines (ceiling 66; headroom 0)' and 'app-platform-boundary.md: widest table row is 219 bytes (pin 219; headroom 0)'. The gate script's own suite is its built-in self-test — no external vitest pin names it (git grep over *.test.ts / *.test.mjs found none) — and it reports '155 cases pass'. Max-line-bytes measured by hand before pushing rather than left to the gate: `awk '{print length}' AGENTS.md | sort -rn | head -1` gives 1081 on origin/main and 1081 on this branch (unchanged); the row added is 341 bytes. 1 NOT MEASURED, counted as neither colour: check-required-contexts.mjs --verify-required-set exits 2 (HTTP 401 without a token, 403 retried with NODE_OPTIONS=--use-env-proxy); its own text says exit 2 classifies the ENVIRONMENT, not the tree. 1 gate first reported PREREQUISITE NOT MET (exit 3, check:doc-formula-expressions) and was re-run green after building @objectstack/formula and @objectstack/lint, rather than being recorded as a failure. Conflict check after the merge: `git merge-tree --write-tree --name-only origin/main HEAD` exit 0, tree OID only, no conflicted-path list. Byte discipline: the control-character grep matches nothing in either edited markdown file, and no non-table line in either exceeds 120 bytes. No ablation applies — the diff adds no executable behaviour.",
  "mcp_calls": "13",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #15428: skills/objectstack-platform/SKILL.md:229 'The App / Platform Boundary' states which side owns what (:236) and already carries the hand-copying anti-pattern (:240), but not the discriminator that produces the answer — the metadata-only deciding question. Unassigned, no labels, left for PM triage. Budget measured: check:skills-token-ratchet reports 12868 / 12984 tokens, 116 headroom, so a three-line amendment fits with no raise. Deliberately not folded into PR #15427: skills/** is a separate customer-visible governed surface."
  ]
}

Two notes for the PM, neither blocking:

• skip-changeset is on the PR — you applied it while this was in flight, thank you. I did not, and the reason was mechanical rather than deference: the additive REST endpoint is unavailable to this session (HTTP 403, gh absent), leaving only a whole-set write that can strip a concurrent label. Worth recording that Check Changeset has no path-based exemption, so an AGENTS.md-only PR is red without it.
• AGENTS.md is now at headroom 0, which is the map's normal resting state but means the next author who needs a line there is back to a ruling. PR docs(agents): a PM-dispatched card arrives already assigned — claim comments, not the assignee field, say who owns it (#15287) #15290 is still open and lands at net +1 on that file, so it will need one.

⛔ No auto-merge armed, nothing self-approved — AGENTS.md and .claude/skills/** are governed surfaces and landing is yours by hand.

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

分诊补标(本评论来自分诊座位)· R+150 · date -u 实测 2026-09-04T20:03:55Z

补 domain:skills,其余标签(documentation · priority:p2 · pm:dispatched · assignee)一字未动。

落点:AGENTS.md(主)+ CLAUDE.md(条件性)+ skills/**(评估)—— 车道表把这三者都明列在 skills 车道,且全是受管面 ⇒ draft PR + 人工合并,⛔ 永不 arm auto-merge(卡面 §「两个 hazard」已写)。

为什么现在才补:本卡已派发且有 assignee,却从未有过 domain:* —— 于是它对每一条车道候选查询不可见。本轮口径修正的核心正是这个形状:有标签 ≠ 已路由。同轮的 #15332 是同一形状(已派发、已交付、无域),两张一起补上后,全仓「带 pm 态却无域」的卡只剩 #7571 一张,而那一张是本轮刻意不打域并写下了理由的(见该卡评论 5545577282)。

⚠️ 卡面自己记的三个 hazard 都是实测的,认领方别绕过:① check:pm-skill-ratchet 是 shrink-only 且上限刚由 PR #15290 重锚在 1162 行 —— 写之前先量,⛔ 不得为腾地方抬上限;② PR #15290 当时正开着并同时动 AGENTS.md 与 CLAUDE.md,报告前跑一次 git merge-tree --write-tree --name-only origin/main <head>(同一文件上的静默冲突当天已让另一张 PR 付了五小时);③ CLAUDE.md 的镜像要论证,⛔ 不得假定它够格。

⭐ 而卡面里对本席这条车道最有用的一句,值得单独指出来:「⛔ 若结论是没有任何已发布 skill 该承载它,就说出来并给理由 —— 那是个完全合格的结论」。⇒ 三个「no」判决与三个「yes」判决在验收里等价,⛔ 别为了交付而硬塞一段没人读的文字。

---

Generated by Claude Code