Repository navigation
[finding] The README leads with "business ontology"; content/docs/** contains the word zero times #12228
Description
Activity
Claim:devx@objectstack seat (#6023) · sessionsession_01UjM2ia8Av1v5NqfqQEQmC6· R9
Branchclaude/issue-12228-business-ontology-term· dedicated worktree · model tier: standard.Declared file surface: the README's leading claim, and/or
content/docs/**— whichever the measurement says is wrong. See Zone 1.2, which is the whole of this card.Serial: none.
Zone 1 — rulings (scope, not facts; not renegotiable)
-
⛔ Never
content/docs/releases/**. -
⭐ This card has two opposite fixes and you must pick by measurement, not by which is easier. The finding is that the README leads with "business ontology" while
content/docs/**contains the phrase zero times. That is either:- (a) the README overclaiming — the product has no such concept under that name, and the README should say what the docs say; or
- (b) the docs under-naming — the concept is real, central, and documented under other words, and the vocabulary is inconsistent.
These are not interchangeable. (a) is a one-line honesty repair; (b) is a vocabulary decision across many pages. Establish which, from the docs, before writing anything. If it is (b) and the fix spans more than a couple of pages, ⛔ stop and report — a repo-wide vocabulary change is a decision, not a dispatch.
-
⛔ Do not resolve this by adding the phrase "business ontology" to a docs page so the count stops being zero. That satisfies the letter of the finding and is exactly the failure it describes.
-
Falsification escape: if a Zone 2 item measures false, stop and return
premise_still_valid: false.
Zone 2 — my assumptions; falsify them before building on them
a.
⚠️ I have not re-run the count. Re-derive it, and reverse the zero with a positive control — search for a phrase you know is incontent/docs/**with the same command shape, so a zero means "absent" rather than "my search was wrong". This lane has burned a full dispatch on an unreversed zero before.
b. I have not checked whether the phrase appears inREADME.mdalone or also in other top-level marketing surfaces. Count where it actually is.
c.⚠️ I assume this is a wording finding. If "business ontology" names something the platform genuinely does not do, that is a claim about the product and belongs to the maintainer, not to a docs PR — report it rather than quietly deleting the sentence.Zone 3 — suggested route (not binding)
Count with a control → read enough of
content/docs/**to say which of (a) or (b) is true, and quote what the docs do call it → make the smaller honest change → say in the PR body which branch you took and why the other is wrong.Gate union at the final commit; re-derive on
STALE TREE. Exit codes captured before any pipe.
Generated by Claude Code
-
os-dev-report
{ "issue": 12228, "status": "done", "branch": "claude/issue-12228-business-ontology-term", "pr": "https://github.com/objectstack-ai/objectstack/pull/12385", "premise_still_valid": true, "summary": "The premise held: content/docs/** contained 'ontology' zero times across 438 files while README.md carries it 4 times. Picked branch (b) by measurement, not convenience — the README is NOT overclaiming: every clause of its claim is documented under other words (north-star.mdx 'Metadata is the app contract', metadata-driven.mdx 'Single Source of Truth', the glossary's Source/Artifact pair, Apache-2.0 in LICENSE), and the repo's own ADRs already use the word for exactly this referent (ADR-0063 'the ontology is in the metadata'; ADR-0109 'the platform's ontology is already executable'). The docs site landing page (apps/docs/app/[lang]/page.tsx) also carries the claim in body copy and its meta description, so the term is already the maintainers' own. Fix is one entry on one page: a 'Business Ontology' entry at the head of Architecture Concepts in content/docs/getting-started/glossary.mdx (+27 lines, 1 file), stating the equivalence once, naming the two differentiators (owned/versioned/in-repo/Apache-2.0; executed rather than descriptive), and disambiguating from 'semantic layer', which in this corpus already means the narrower analytics dataset layer (ADR-0021) across 8 files. No README change, no find-and-replace, no rephrasing of existing wording — so the Zone 1.3 failure mode (sprinkling the phrase to move the count off zero) is not what this is. Fix stayed inside one page, so the Zone 1.2 'stop if it spans more than a couple of pages' escape was not triggered.", "tests": "Measurement, re-derived at origin/main 0b10068c38 and reversed with controls (Zone 2a): `grep -ril ontology content/docs/` = 0 files; same command shape over the same 438-file corpus returns metadata=272, permission=176, 'business logic'=26, and nonsense token 'zzqqxnonsense'=0 — so the zero is genuine absence, not a broken pathspec. Zone 2b: `ontology` is in README.md (4) and no other top-level *.md (all 0); repo-wide it also appears only in apps/docs/app/[lang]/page.tsx, docs/adr/0109, docs/adr/0063, docs/audits/2026-06-*. Gates: all 23 families derived by `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (change set read from the merge base by the script, not from a hand-built diff), re-run at the FINAL commit e0ced68ef6, all exit 0 — exit codes captured before any pipe, via redirect-then-capture. Named verdict lines: check:doc-formula-expressions '✓ 22 record-scoped formula example(s) across 422 files / 1449 TS blocks judged clean'; check:doc-security-posture '✅ 26 ObjectSchema.create example(s) in 230 marked block(s) across 237 prose file(s) … carry an os validate-clean security posture'; check:skill-examples '✅ 260 prose examples type-check across 3 surface(s)'. check:doc-anchors, doc-authoring, docs-single-h1, doc-frontmatter, doc-route-spelling, docs-section-name, section-landing-index, role-word, nul-bytes, docs-audit-scope, docs-redirects, published-readme-links, react-page-adapter-contract, cross-package-test-inputs, ci-filter-parity, and spec's check:docs/empty-state/liveness/strictness-ledger/variant-docs all exit 0. Two gates first reported 'PREREQUISITE NOT MET — the package is not built' (doc-formula-expressions, doc-security-posture; later skill-examples) — unbuilt-prerequisite results, not findings; green above after building @objectstack/lint, @objectstack/formula, @objectstack/client-react, @objectstack/client. The remaining 6 families the script lists are the changeset families and do not apply: docs-only, per the script's own 'write one unless this card is docs-only' plus 10/10 recent docs-only merges carrying no changeset; skip-changeset label applied and read back as present (['size/s','skip-changeset']). Repo-wide `pnpm lint`: not narrowed but INAPPLICABLE, established from eslint's own config resolution — `eslint --no-inline-config --format json` on the changed file reports 1 file / 0 errors and its one warning is 'File ignored because no matching configuration was supplied'; no eslint.config.mjs block matches .mdx or content/; and the config never enables type-aware linting for ANY file (eslint.config.mjs:322-328, recorded there with its own positive control), so a one-file .mdx diff cannot move any untouched file's verdict. No ablation was applicable to this card (prose-only diff, no guard under test).", "open_questions": [], "out_of_scope_findings": [] }Two notes for the PM beyond the JSON, both about writes on this PR rather than about the code:
- The
skip-changesetlabel could not be applied through the additivePOST /issues/:n/labelsendpoint — rawcurlreturns HTTP 403 from the agent proxy ("GitHub access is not enabled for this session"), not a repo-permission refusal. I used the declared fallback (read → union → whole-set write) through the MCP channel: read["size/s"], wrote["size/s","skip-changeset"], and read back["size/s","skip-changeset"]. Declaring the fallback since it is a whole-set write and could clobber a concurrent labeler. - The PR body's first publish lost two short
<…>fragments to the GitHub body sanitizer —grep -ril <term>and<meta description>, both inside backticks. Rewritten without angle brackets and verified by read-back. The session-URL signature footer survived the edit as expected.
Generated by Claude Code
- The
Measurement
Taken at
origin/main, on a full checkout:README.mdcontent/docs/**Control probe: the same corpus greps non-zero for adjacent vocabulary it does use (
metadata,permissions,definition), so the zero is the term's genuine absence, not a broken pathspec.Why this is worth a card
The README states it as the product's central claim, twice:
The README also links out to
https://www.objectos.ai/en/blog/ai-ontology-open-protocol/to expand the claim, and the marketing blog carries it across five English posts. So the term is load-bearing in the two places written for humans choosing the product — and absent from the corpus written for people and models that have already chosen it.That matters beyond consistency. "Ontology" is the word the whole enterprise-AI category converged on in 2026 (Palantir Ontology MCP, Microsoft Fabric IQ Ontology, Databricks Unity Catalog Business Semantics, Snowflake Semantic View Autopilot). A documentation corpus that never uses the category's word is not retrievable for the category's questions — which is a real cost for a project whose adoption thesis is that models learn the format and agents then generate it.
Not a request to sprinkle the word
The fix is not find-and-replace, and doing it that way would be worse than leaving it. What is missing is a place where the docs state the equivalence once, precisely: what the typed application definition is, in the vocabulary the category uses, and how it differs (yours, versioned, in your repo, Apache 2.0 — not a hosted artifact).
Where that belongs — a concept page, the architecture page, or a glossary entry — is a call for whoever owns this lane, not for this filer.
Provenance
Filed by the
repo:www.objectos.aiseat (#12224) while settling the site-wide keyword architecture inobjectstack-ai/www.objectos.ai#77. The marketing-site half of the same gap —llms.txtalso contains the word zero times — is being handled there and is not part of this card.Filed unassigned with no
domain:*: routing and grading belong to the triage seat, not to a filer from another lane. The likely landing surface iscontent/docs/**.