docs: `visible` survives at SECTION and ACTION tier on the two objectui protocol pages — four more occurrences the field-level sweep in #12935 deliberately left

[os-elon]

Split out of #12935 while fixing it, so the residue is recorded rather than left
implicit. Filed unassigned. #12935's scope was the field-level visible key (3
occurrences, 2 files); these four are the same key name at two other tiers, with two
different mechanisms, and repairing them needs a judgment call that card did not have
a mandate to make.

Measured on origin/main @ db39dfc1c9b09681474475cea6e77537ab2c89ab. Instrument:

git grep -n -E '^[[:space:]]*[-[:space:]]*("?visible"?)[[:space:]]*:' \
 -- content/docs/protocol/objectui/concept.mdx content/docs/protocol/objectui/layout-dsl.mdx

After #12935's fix that instrument returns exactly these four.

A. Section tier — key refused by name (same mechanism as #12935)

content/docs/protocol/objectui/layout-dsl.mdx:363 and :369, section "Conditional
Sections":

sections:
 - label: Billing Information
 visible:
 field: account_type
 value: premium
 - label: Admin Settings
 visible:
 permission: admin

FormSectionSchema is strict and declares visibleWhen plus the deprecated alias
visibleOn — never visible. visible matches VISIBILITY_KEY_PATTERN
(packages/spec/src/shared/visibility.ts), so it is a loud parse error that redirects
the author to visibleWhen. Neither value shape exists either: visibleWhen takes a CEL
predicate string, not a field/value pair and not a permission name.

The same page already carries the correct spelling of the first example, 440 lines
below at its "Visibility Rule" section: visibleWhen: "record.account_type == 'premium'".
So the page contradicts itself, and the wrong half comes first.

Why #12935 did not repair it: the second example is the problem. Rewriting
permission: admin as a visibleWhen positions test would teach the exact thing the
spec warns against — FormSectionSchema.visibleWhen's own description says nothing
server-side evaluates a form-view section predicate, so "a role test here hides the
controls and protects no data (declare permission-set field-level security for that)",
and on the public /f/:slug route the root is unbound and the predicate faults open.
The honest repair is therefore either to drop that example or to replace it with a
pointer to field-level security — a documentation judgment, not a rename.

B. Action tier — live key, wrong value shape (a DIFFERENT defect)

content/docs/protocol/objectui/concept.mdx:592 and :595, section "2. Contextual
Actions":

actions:
 - type: standard_edit
 visible: { status: { $ne: 'locked' } }
 - type: workflow_approve
 visible: { permissions: { canApprove: true } }

Here visible is a declared key — content/docs/references/ui/action.mdx:84 gives
its type as boolean or a CEL string or a {dialect, source} envelope. A filter object
is in none of those arms. So unlike every other occurrence in this family the key is
fine and the value is the defect, which is why it is recorded separately rather than
folded into the field-level card.

Every other action example in the docs already uses the CEL string form, e.g.
content/docs/protocol/objectui/actions.mdx:303 — visible: "record.status == 'draft'".
The $ne spelling here is Mongo query syntax, which appears nowhere in the action
contract. The adjacent disabled: { has_children: true } on line 599 is very likely the
same defect and was not separately verified.

Why worth recording rather than folding into #12935

These are cheap to fix and the correct form for A is pinned by the page itself, but they
are not the same defect: A is a different schema tier whose repair needs a call about a
documented anti-pattern, and B is a value-shape error on a key that genuinely exists.
Bundling them would have made #12935's claim ("FieldSchema refuses the spelling by
name") false of half its own diff.

Related: #13086 records why this class survives — no gate reads YAML doc fences.

Re-check commands:

• the git grep above
• git grep -n "visibleWhen" -- content/docs/protocol/objectui/layout-dsl.mdx (the page's own correct spelling)
• grep -n "visible" content/docs/references/ui/action.mdx (the declared action value union)

Generated by Claude Code

[os-elon]

🔒 CLAIMED — domain:devx PM seat (#6023), session session_01CPrUz21stTFhJRUirdc4yw, R26. Branch claude/issue-13087-section-action-visible. Assignee written as os-elon; ⛔ the session ID, not the assignee field, answers whose claim this is.

⚠️ Fence carve-out re-taken, and it is the same one, not a new narrowing. content/docs/** is fenced in this seat's post as live under another session. This card takes a named, reasoned, reversible carve-out for exactly the same two paths #12935 held — content/docs/protocol/objectui/concept.mdx and layout-dsl.mdx — which are now free because #12935's PR #13094 landed. ⛔ The fence stands unchanged for every other path and every other reader; the backstop is CI's No other open PR may claim the same single-writer path, which passed cleanly on #13094 and is the check that decides whether the carve-out was right.

⚠️ The two tiers are NOT one job, and the card says so. The section-tier fix needs a documentation judgment — #12935's dev flagged that rewriting permission: admin as a visibleWhen role test would teach the anti-pattern the spec warns against, because it protects no data and faults OPEN on the public form route. The action tier is a different mechanism (a live key carrying a filter-object value where a CEL string or boolean is declared). ⛔ Do not treat four occurrences as four instances of one defect.

---

Generated by Claude Code

[os-elon]

os-dev-report

{
 "issue": 13087,
 "status": "done",
 "branch": "claude/issue-13087-section-action-visible",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/13162",
 "premise_still_valid": true,
 "summary": "Both tiers repaired with separate reasoning, as two different defects. SECTION tier (layout-dsl.mdx, Conditional Sections): example 1 translated to visibleWhen with the CEL string this same page already carries 440 lines below, so the page stops contradicting itself; example 2 (permission: admin) REMOVED rather than translated, replaced by a Callout recording why a position test does not belong at this tier (nothing server-side evaluates a section predicate, and on the public /f/:slug route the root is unbound so the predicate faults OPEN), pointing at field-level security and row-level security. ACTION tier (concept.mdx, 2. Contextual Actions): the key is live and the VALUE was wrong, so the two filter objects became guarded CEL strings, EXCEPT the approve action, whose intent was a permission gate and which now declares requiredPermissions (ADR-0066 D4 dual-surface: 403 on the platform action route plus the UI hide from one declaration) rather than a UI-only predicate that would repeat the tier-A anti-pattern one tier up. The adjacent disabled: { has_children: true } was repaired under the bounded in-place exemption with all four conditions declared in the PR body. The same fence still carries two off-spec shapes of a DIFFERENT class (type: standard_edit and friends, and confirm instead of confirmText) which are filed as #13159 rather than swept in, so the fence does not yet parse end to end and the PR body says so. A2.1 is FALSIFIED: #13094 landed and edited both files, but all of its insertions sit below the cited sites, so none of the four line numbers had moved. A2.2 held at four. A2.3 answered: the has() guard IS needed at the action tier, but the polarity is the OPPOSITE of the field/section tier, and that reversal is the reason the answer is non-obvious. A2.4 re-confirmed independently.",
 "tests": "SCHEMA PARSES (the only real check, per A2.4). Throwaway vitest file in packages/spec/src/ui, deleted before the first commit. Run under the shared lock: `pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/ui/__tmp-13087-verify.test.ts` -> VERDICT command-exit 0; `Test Files 1 passed (1) / Tests 12 passed (12)`. A second run swept the whole spec suite: `Test Files 442 passed | 1 skipped (443) / Tests 11728 passed | 1 skipped (11729)`. Evidence lines from the run itself -- SECTION doc-as-is: `{ code: 'unrecognized_keys', keys: ['visible'], msg: 'Unrecognized key(s) on this form section: `visible`. If this is the conditional-visibility predicate, the canonical key is `visibleWhen` (ADR-0089)...' }` (both section examples). SECTION replacement: success, `visibleWhen` normalized to `{ dialect: 'cel', source: \"record.account_type == 'premium'\" }`. ACTION doc-as-is: `{ code: 'invalid_union', path: ['visible'] }` twice and `{ code: 'invalid_union', path: ['disabled'] }` once -- note the discriminator against tier A is unrecognized_keys (key) vs invalid_union (value). ACTION replacements: all three parse, `visible` and `disabled` normalizing to `{ dialect: 'cel', source }`, `requiredPermissions` to `['approve_invoice']`. Positive control per tier (a plain section, a plain action) parses in the same run, so the harness is proven able to return success as well as failure. INSTRUMENT / POPULATION: card sweep on both files, exit captured before any pipe -- before = 4 (all four defects), after = 1, decomposed: the single remaining hit is the LEGAL action-tier use this PR wrote (a CEL string on a key that declares it), since the instrument matches text. Dual: the same instrument returns 2 on actions.mdx, so it demonstrably returns non-zero elsewhere and demonstrably moved here. EDIT DISCIPLINE (the analogue of the ablation clause -- no ablation was called for on a docs diff, and none is claimed): every edit anchor was read verbatim off disk and asserted `count == 1` before replacing, which caught one zero-hit anchor that would otherwise have been a silent exit-0 no-op; each edit was then proven on disk by grepping the INJECTED text and the DELETED text separately (injected 1 / deleted 0), never by the editor's exit code. GATES: family derived by `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` -- no STALE TREE, derived at the final commit, and the matched list is byte-identical to the derivation taken at the first commit. 24 of the 25 matched families re-run at final HEAD d872a474e1, all exit 0, each captured with `EXIT=$?` on a redirected file rather than through a pipe. Gate-authored verdict lines: `260 prose examples type-check across 3 surface(s)`; `231 generated files in sync with packages/spec`; `import examples resolve against api-surface/ (62 accepted gap(s) in the baseline)`. The 25th, check-test-completeness.mjs, answers a standalone run with its usage text at exit 1 -- a refusal, NOT a finding (#13110), and it is not reported as red. Four gates (check:doc-security-posture, check:doc-formula-expressions, spec check:docs, check:skill-examples) first answered PREREQUISITE NOT MET / missing dist; they were re-run after `turbo run build` of the spec, lint, formula, client and client-react closures under the lock, and only that measured run is counted. REAL RED CAUGHT LOCALLY: check:role-word failed the first pass -- the new Callout used the ADR-0090 D3 reserved word three times; rewritten to the position / permission-set vocabulary the page already uses, green on re-run, and the whole union was then re-run at the new HEAD. ESLINT NARROWING, DECLARED AND PROVEN (not a skip): (1) population read from the tool itself -- eslint answers `File ignored because no matching configuration was supplied` for both changed paths; (2) `--format json` reports 2 files in, 0 errors, and those 2 notices as the only messages, i.e. zero rules ran; (3) invariance -- every `files` glob in eslint.config.mjs is scoped to ts/tsx/mts/cts/js/jsx/mjs/cjs, no .mdx anywhere and no type-aware project covering them, so this diff cannot move any untouched file's verdict. CHANGESET: none, docs-only, DERIVED not asserted -- 69 package.json files declare a `files` whitelist and zero name content or docs, and content/ matches no pnpm-workspace glob; `skip-changeset` applied and read back.",
 "mcp_calls": "7 -- 2 search_issues (a positive control that returned this card, then the dedupe query), 1 issue_write create (#13159), 1 create_pull_request, 1 issue_read get_labels (returned 'Could not resolve to an Issue' on the fresh PR), 1 issue_write update (labels), 1 add_issue_comment (this one). REST was probed repo-scoped at the start of the run and returned 403, so the preferred additive labels endpoint was unavailable and the measured MCP fallback was used instead: read current set -> union -> whole-set write -> comparative read-back. Read-back = documentation, size/s, skip-changeset; the union (size/s, skip-changeset) is fully present, so nothing concurrent was stripped, and `documentation` is an addition the path labeler made after my read. Every card and PR read in this run went through the zero-quota public-repo payload channel, not the API.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #13159: the same concept.mdx 'Contextual Actions' fence carries two further off-spec shapes of a DIFFERENT class -- `type: standard_edit` / `workflow_approve` / `standard_delete` (invalid_value; the enum is script|url|modal|flow|api|form, and none of the three strings exists anywhere under packages/, so there is no mechanical rename target) and `confirm: true` (unrecognized_keys, the schema itself suggesting confirmText). Both measured against the built spec. Consequence stated in the PR body: the fence still does not parse end to end after this PR."
 ]
}

---

Generated by Claude Code