Warn when a bare flow-condition identifier is shadowed by a declared flow variable

[claude]

Closes#14089

Implements the maintainer's ruling of 2026-09-01 (director batch #23): option C — warn only on the shadowing sub-case. Options A, B and D were excluded, and the PM's earlier three-way ruling was struck.

What changes

A flow node/edge condition is evaluated in a flattened scope, so a bare status normally resolves to the trigger record's field. That form is correct: @objectstack/formula's published contract says so (ExprSchemaHint.scope, cel-engine.ts), AutomationEngine.seedRunVariables flattens the record's fields for exactly that purpose, and two shipped example apps read fields bare. This PR does not judge a bare identifier for being bare, and adds no error.

It names one sub-case that is both genuinely ambiguous and genuinely broken: a bare name that is BOTH a declared flow variable AND a field on the bound object.

constvariables=this.seedDeclaredVariables(flow,context);// (1) variables firstif(context?.record){variables.set('record',context.record);for(const[k,v]ofObject.entries(context.record)){if(!variables.has(k))variables.set(k,v);// (2) guarded flatten}}

The variable wins, the field is unreachable under its own name, and nothing anywhere reports the collision — on the surface where a wrong predicate is least visible, because a flow condition that never fires produces no record, no error and no log line. Severity is warning; the diagnostic names the mechanism and both repairs.

New module packages/lint/src/flow-variable-scope.ts holds the collection surface and the oracle; validate-expressions.ts gains the two emission call sites (flow-node condition, flow-edge condition) and one collection pass.

The collection surface, measured against the executors

Variables are flow-scoped, not graph-scoped — seedRunVariables builds one map per run — so the set is one flat union across every ADR-0031 region collectFlowGraphs yields.

row	declaration point	runtime binder
1	flow.variables[].name	seedDeclaredVariables
2-5	config.iteratorVariable / indexVariable / errorVariable / outputVariable	loop, map, try_catch, crud/screen/subflow nodes
6	assignment targets, wrapper OBJECT shape	logic-nodes.ts
7	assignment targets, wrapper ARRAY shape (variable / name / key)	same
8	assignment targets, no wrapper at all — the config's own keys ARE the names	same, its else branch
9	node ids — a bare CEL root at runtime	evaluateCondition expands a nodeId.outputKey variable into a nested object AT the node id, overwriting whatever scalar was flattened there

Row 8 is gated on the node type, deliberately: it reads every top-level config key, which is correct for an assignment node and catastrophic over-collection for any other. There is a test for that gate.

The rejected itemVariable alias is not read — tolerating a spelling control-flow.zod.ts refuses by name would be consumer-side alias tolerance (Prime Directive 12), and it cannot arrive on the parsed path this rule runs on.

The oracle

firstUndeclaredReference from @objectstack/formula, notcollectCelRootIdentifiers, as the maintainer pinned. The former acts only on cel-js's own unknown-variable fault, so comprehension-macro variables and function names cannot false-positive; the latter reports macro variables as roots, and a macro variable sharing a field's name would then be flagged for a collision that cannot exist. Both are covered by tests.

Its known, deliberate blind spot is pinned rather than left to be discovered: SCOPE_ROOTS members are declared in the strict environment, so a flow variable named result / data / item goes unwarned. That is an under-report, the safe direction for a new warning, and closing it means consulting the AST — which re-opens the macro-variable false positive.

packages/formula is untouched. No new dependency edge: packages/lint already declares @objectstack/formula, and a sibling file in the same package already imports this helper.

Verification — all at d142c49b unless stated

• pnpm --filter @objectstack/lint test — 89 files, 2505 tests passed, exit 0 (captured by redirect before any pipe).
• pnpm --filter @objectstack/lint typecheck — exit 0.
• Both pinned tests pass unchanged.validate-expressions.test.ts "does NOT flag bare references in a flow condition (flattened scope)" (bare amount / bare stage at zero issues) and formula/src/validate.test.ts's flattened-scope pin are untouched by this diff — neither file's pinned assertions were edited, deleted or re-baselined.
• Ablation. With both emission call sites deleted, exactly the 6 positive tests go red and every negative control stays green. Mutation confirmed on disk before the run — HEAD blob hash equal to the pre-mutation hash, call-site count 2 to 0, post-mutation hash different — and the restore leg proved by an empty git diff HEAD. No rebuild leg was needed and none is claimed: the test imports ./validate-expressions.js relatively, so vitest reads this package's source, and nothing resolves it through packages/lint/dist.
• The shipped example apps stay clean, and that is a reading rather than silence.objectstack validate exits 0 on app-todo, app-showcase and app-crm with no shadowing warning. Positive control through the same channel: injecting a status flow variable into app-todo's real task_completion flow (the one whose start condition reads bare status) makes the diagnostic appear, at warning severity with validate still exiting 0. Both legs restored, verified by an empty git diff HEAD.
• Gate families: 33 derived from the actual diff via scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands — not a hand-written list. 30 green. 3 NOT MEASURED, none of them a red: check-test-completeness and check:dual-build-cjs-loads first returned exit 3 (PREREQUISITE NOT MET); the latter was then run on the built closure and passed, while the former has no local turbo test log to grade. scripts/pm/check-half-states.mjs is a network-bound GitHub patrol that does not terminate in this container.
• Ratchets re-run on the final head after the last commit: check:type-check-coverage --re-measure — 27 ledger entries, 1217 raw tsc errors, none above its recorded number, surplus none. Also green at that head: comment-mask-adoption, engine-double-contract, where-matcher, query-options-erasure, type-check-coverage, dual-build-cjs-loads.

Two findings from those gates were repaired rather than routed around, and both are visible in the commit history: the new test file originally carried a private comment-stripper (check:comment-mask-adoption reds on a new one) and now asserts on the module's exported constants instead; and ASSIGNMENT_NODE_TYPE was made module-private after rule-id-barrel-exports correctly read a slug-shaped export const as a rule id owing a barrel line.

Clause 2: no. The accept set does not move in either direction. Nothing that linted clean before this diff lints red after it, and nothing previously rejected is now accepted — the only behavioural change is one additional warning, and a warning never fails the build. The four surfaces the ruling protects are untouched: no contract change, no pinned test deleted or re-baselined, no example app edited, and packages/formula unmodified.

Meta-guard note

validate-expressions.test.ts's #5017 receiver scan gained one PLUMBING entry, scope. It is not a receiver: it is the tail of the './flow-variable-scope.js' import specifier, which the scan cannot tell from a property read — the same artefact as the fields and guards entries already there. No metadata receiver's expected list changed, so the declared-key guard loses no coverage.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 18 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx(via errorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), indexVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), iteratorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))
• content/docs/kernel/runtime-services/examples.mdx(via outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5c539e964928c53fc9b717425818364053cba918 — the merge of head d142c49b9df746f9f39cf500fc6b707cb4e23208 into base e7645078d8680027e1d2b9760dfc686c2cefb8e8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5c539e964928c53fc9b717425818364053cba918 && git checkout 5c539e964928c53fc9b717425818364053cba918
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e7645078d8680027e1d2b9760dfc686c2cefb8e8 d142c49b9df746f9f39cf500fc6b707cb4e23208 && git checkout -B drift-repro e7645078d8680027e1d2b9760dfc686c2cefb8e8 && git merge --no-ff d142c49b9df746f9f39cf500fc6b707cb4e23208
node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e7645078d8680027e1d2b9760dfc686c2cefb8e8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14089

Implements the maintainer's ruling of 2026-09-01 (director batch #23): option C — warn only on the shadowing sub-case. Options A, B and D were excluded, and the PM's earlier three-way ruling was struck.

What changes

A flow node/edge condition is evaluated in a flattened scope, so a bare status normally resolves to the trigger record's field. That form is correct: @objectstack/formula's published contract says so (ExprSchemaHint.scope, cel-engine.ts), AutomationEngine.seedRunVariables flattens the record's fields for exactly that purpose, and two shipped example apps read fields bare. This PR does not judge a bare identifier for being bare, and adds no error.

It names one sub-case that is both genuinely ambiguous and genuinely broken: a bare name that is BOTH a declared flow variable AND a field on the bound object.

constvariables=this.seedDeclaredVariables(flow,context);// (1) variables firstif(context?.record){variables.set('record',context.record);for(const[k,v]ofObject.entries(context.record)){if(!variables.has(k))variables.set(k,v);// (2) guarded flatten}}

The variable wins, the field is unreachable under its own name, and nothing anywhere reports the collision — on the surface where a wrong predicate is least visible, because a flow condition that never fires produces no record, no error and no log line. Severity is warning; the diagnostic names the mechanism and both repairs.

New module packages/lint/src/flow-variable-scope.ts holds the collection surface and the oracle; validate-expressions.ts gains the two emission call sites (flow-node condition, flow-edge condition) and one collection pass.

The collection surface, measured against the executors

Variables are flow-scoped, not graph-scoped — seedRunVariables builds one map per run — so the set is one flat union across every ADR-0031 region collectFlowGraphs yields.

row	declaration point	runtime binder
1	flow.variables[].name	seedDeclaredVariables
2-5	config.iteratorVariable / indexVariable / errorVariable / outputVariable	loop, map, try_catch, crud/screen/subflow nodes
6	assignment targets, wrapper OBJECT shape	logic-nodes.ts
7	assignment targets, wrapper ARRAY shape (variable / name / key)	same
8	assignment targets, no wrapper at all — the config's own keys ARE the names	same, its else branch
9	node ids — a bare CEL root at runtime	evaluateCondition expands a nodeId.outputKey variable into a nested object AT the node id, overwriting whatever scalar was flattened there

Row 8 is gated on the node type, deliberately: it reads every top-level config key, which is correct for an assignment node and catastrophic over-collection for any other. There is a test for that gate.

The rejected itemVariable alias is not read — tolerating a spelling control-flow.zod.ts refuses by name would be consumer-side alias tolerance (Prime Directive 12), and it cannot arrive on the parsed path this rule runs on.

The oracle

firstUndeclaredReference from @objectstack/formula, notcollectCelRootIdentifiers, as the maintainer pinned. The former acts only on cel-js's own unknown-variable fault, so comprehension-macro variables and function names cannot false-positive; the latter reports macro variables as roots, and a macro variable sharing a field's name would then be flagged for a collision that cannot exist. Both are covered by tests.

Its known, deliberate blind spot is pinned rather than left to be discovered: SCOPE_ROOTS members are declared in the strict environment, so a flow variable named result / data / item goes unwarned. That is an under-report, the safe direction for a new warning, and closing it means consulting the AST — which re-opens the macro-variable false positive.

packages/formula is untouched. No new dependency edge: packages/lint already declares @objectstack/formula, and a sibling file in the same package already imports this helper.

Verification — all at d142c49b unless stated

• pnpm --filter @objectstack/lint test — 89 files, 2505 tests passed, exit 0 (captured by redirect before any pipe).
• pnpm --filter @objectstack/lint typecheck — exit 0.
• Both pinned tests pass unchanged.validate-expressions.test.ts "does NOT flag bare references in a flow condition (flattened scope)" (bare amount / bare stage at zero issues) and formula/src/validate.test.ts's flattened-scope pin are untouched by this diff — neither file's pinned assertions were edited, deleted or re-baselined.
• Ablation. With both emission call sites deleted, exactly the 6 positive tests go red and every negative control stays green. Mutation confirmed on disk before the run — HEAD blob hash equal to the pre-mutation hash, call-site count 2 to 0, post-mutation hash different — and the restore leg proved by an empty git diff HEAD. No rebuild leg was needed and none is claimed: the test imports ./validate-expressions.js relatively, so vitest reads this package's source, and nothing resolves it through packages/lint/dist.
• The shipped example apps stay clean, and that is a reading rather than silence.objectstack validate exits 0 on app-todo, app-showcase and app-crm with no shadowing warning. Positive control through the same channel: injecting a status flow variable into app-todo's real task_completion flow (the one whose start condition reads bare status) makes the diagnostic appear, at warning severity with validate still exiting 0. Both legs restored, verified by an empty git diff HEAD.
• Gate families: 33 derived from the actual diff via scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands — not a hand-written list. 30 green. 3 NOT MEASURED, none of them a red: check-test-completeness and check:dual-build-cjs-loads first returned exit 3 (PREREQUISITE NOT MET); the latter was then run on the built closure and passed, while the former has no local turbo test log to grade. scripts/pm/check-half-states.mjs is a network-bound GitHub patrol that does not terminate in this container.
• Ratchets re-run on the final head after the last commit: check:type-check-coverage --re-measure — 27 ledger entries, 1217 raw tsc errors, none above its recorded number, surplus none. Also green at that head: comment-mask-adoption, engine-double-contract, where-matcher, query-options-erasure, type-check-coverage, dual-build-cjs-loads.

Two findings from those gates were repaired rather than routed around, and both are visible in the commit history: the new test file originally carried a private comment-stripper (check:comment-mask-adoption reds on a new one) and now asserts on the module's exported constants instead; and ASSIGNMENT_NODE_TYPE was made module-private after rule-id-barrel-exports correctly read a slug-shaped export const as a rule id owing a barrel line.

Clause 2: no. The accept set does not move in either direction. Nothing that linted clean before this diff lints red after it, and nothing previously rejected is now accepted — the only behavioural change is one additional warning, and a warning never fails the build. The four surfaces the ruling protects are untouched: no contract change, no pinned test deleted or re-baselined, no example app edited, and packages/formula unmodified.

Meta-guard note

validate-expressions.test.ts's #5017 receiver scan gained one PLUMBING entry, scope. It is not a receiver: it is the tail of the './flow-variable-scope.js' import specifier, which the scan cannot tell from a property read — the same artefact as the fields and guards entries already there. No metadata receiver's expected list changed, so the declared-key guard loses no coverage.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 18 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx(via errorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), indexVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), iteratorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))
• content/docs/kernel/runtime-services/examples.mdx(via outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5c539e964928c53fc9b717425818364053cba918 — the merge of head d142c49b9df746f9f39cf500fc6b707cb4e23208 into base e7645078d8680027e1d2b9760dfc686c2cefb8e8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5c539e964928c53fc9b717425818364053cba918 && git checkout 5c539e964928c53fc9b717425818364053cba918
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e7645078d8680027e1d2b9760dfc686c2cefb8e8 d142c49b9df746f9f39cf500fc6b707cb4e23208 && git checkout -B drift-repro e7645078d8680027e1d2b9760dfc686c2cefb8e8 && git merge --no-ff d142c49b9df746f9f39cf500fc6b707cb4e23208
node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e7645078d8680027e1d2b9760dfc686c2cefb8e8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14089

Implements the maintainer's ruling of 2026-09-01 (director batch #23): option C — warn only on the shadowing sub-case. Options A, B and D were excluded, and the PM's earlier three-way ruling was struck.

What changes

A flow node/edge condition is evaluated in a flattened scope, so a bare status normally resolves to the trigger record's field. That form is correct: @objectstack/formula's published contract says so (ExprSchemaHint.scope, cel-engine.ts), AutomationEngine.seedRunVariables flattens the record's fields for exactly that purpose, and two shipped example apps read fields bare. This PR does not judge a bare identifier for being bare, and adds no error.

It names one sub-case that is both genuinely ambiguous and genuinely broken: a bare name that is BOTH a declared flow variable AND a field on the bound object.

constvariables=this.seedDeclaredVariables(flow,context);// (1) variables firstif(context?.record){variables.set('record',context.record);for(const[k,v]ofObject.entries(context.record)){if(!variables.has(k))variables.set(k,v);// (2) guarded flatten}}

The variable wins, the field is unreachable under its own name, and nothing anywhere reports the collision — on the surface where a wrong predicate is least visible, because a flow condition that never fires produces no record, no error and no log line. Severity is warning; the diagnostic names the mechanism and both repairs.

New module packages/lint/src/flow-variable-scope.ts holds the collection surface and the oracle; validate-expressions.ts gains the two emission call sites (flow-node condition, flow-edge condition) and one collection pass.

The collection surface, measured against the executors

Variables are flow-scoped, not graph-scoped — seedRunVariables builds one map per run — so the set is one flat union across every ADR-0031 region collectFlowGraphs yields.

row	declaration point	runtime binder
1	flow.variables[].name	seedDeclaredVariables
2-5	config.iteratorVariable / indexVariable / errorVariable / outputVariable	loop, map, try_catch, crud/screen/subflow nodes
6	assignment targets, wrapper OBJECT shape	logic-nodes.ts
7	assignment targets, wrapper ARRAY shape (variable / name / key)	same
8	assignment targets, no wrapper at all — the config's own keys ARE the names	same, its else branch
9	node ids — a bare CEL root at runtime	evaluateCondition expands a nodeId.outputKey variable into a nested object AT the node id, overwriting whatever scalar was flattened there

Row 8 is gated on the node type, deliberately: it reads every top-level config key, which is correct for an assignment node and catastrophic over-collection for any other. There is a test for that gate.

The rejected itemVariable alias is not read — tolerating a spelling control-flow.zod.ts refuses by name would be consumer-side alias tolerance (Prime Directive 12), and it cannot arrive on the parsed path this rule runs on.

The oracle

firstUndeclaredReference from @objectstack/formula, notcollectCelRootIdentifiers, as the maintainer pinned. The former acts only on cel-js's own unknown-variable fault, so comprehension-macro variables and function names cannot false-positive; the latter reports macro variables as roots, and a macro variable sharing a field's name would then be flagged for a collision that cannot exist. Both are covered by tests.

Its known, deliberate blind spot is pinned rather than left to be discovered: SCOPE_ROOTS members are declared in the strict environment, so a flow variable named result / data / item goes unwarned. That is an under-report, the safe direction for a new warning, and closing it means consulting the AST — which re-opens the macro-variable false positive.

packages/formula is untouched. No new dependency edge: packages/lint already declares @objectstack/formula, and a sibling file in the same package already imports this helper.

Verification — all at d142c49b unless stated

• pnpm --filter @objectstack/lint test — 89 files, 2505 tests passed, exit 0 (captured by redirect before any pipe).
• pnpm --filter @objectstack/lint typecheck — exit 0.
• Both pinned tests pass unchanged.validate-expressions.test.ts "does NOT flag bare references in a flow condition (flattened scope)" (bare amount / bare stage at zero issues) and formula/src/validate.test.ts's flattened-scope pin are untouched by this diff — neither file's pinned assertions were edited, deleted or re-baselined.
• Ablation. With both emission call sites deleted, exactly the 6 positive tests go red and every negative control stays green. Mutation confirmed on disk before the run — HEAD blob hash equal to the pre-mutation hash, call-site count 2 to 0, post-mutation hash different — and the restore leg proved by an empty git diff HEAD. No rebuild leg was needed and none is claimed: the test imports ./validate-expressions.js relatively, so vitest reads this package's source, and nothing resolves it through packages/lint/dist.
• The shipped example apps stay clean, and that is a reading rather than silence.objectstack validate exits 0 on app-todo, app-showcase and app-crm with no shadowing warning. Positive control through the same channel: injecting a status flow variable into app-todo's real task_completion flow (the one whose start condition reads bare status) makes the diagnostic appear, at warning severity with validate still exiting 0. Both legs restored, verified by an empty git diff HEAD.
• Gate families: 33 derived from the actual diff via scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands — not a hand-written list. 30 green. 3 NOT MEASURED, none of them a red: check-test-completeness and check:dual-build-cjs-loads first returned exit 3 (PREREQUISITE NOT MET); the latter was then run on the built closure and passed, while the former has no local turbo test log to grade. scripts/pm/check-half-states.mjs is a network-bound GitHub patrol that does not terminate in this container.
• Ratchets re-run on the final head after the last commit: check:type-check-coverage --re-measure — 27 ledger entries, 1217 raw tsc errors, none above its recorded number, surplus none. Also green at that head: comment-mask-adoption, engine-double-contract, where-matcher, query-options-erasure, type-check-coverage, dual-build-cjs-loads.

Two findings from those gates were repaired rather than routed around, and both are visible in the commit history: the new test file originally carried a private comment-stripper (check:comment-mask-adoption reds on a new one) and now asserts on the module's exported constants instead; and ASSIGNMENT_NODE_TYPE was made module-private after rule-id-barrel-exports correctly read a slug-shaped export const as a rule id owing a barrel line.

Clause 2: no. The accept set does not move in either direction. Nothing that linted clean before this diff lints red after it, and nothing previously rejected is now accepted — the only behavioural change is one additional warning, and a warning never fails the build. The four surfaces the ruling protects are untouched: no contract change, no pinned test deleted or re-baselined, no example app edited, and packages/formula unmodified.

Meta-guard note

validate-expressions.test.ts's #5017 receiver scan gained one PLUMBING entry, scope. It is not a receiver: it is the tail of the './flow-variable-scope.js' import specifier, which the scan cannot tell from a property read — the same artefact as the fields and guards entries already there. No metadata receiver's expected list changed, so the declared-key guard loses no coverage.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 18 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx(via errorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), indexVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), iteratorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))
• content/docs/kernel/runtime-services/examples.mdx(via outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5c539e964928c53fc9b717425818364053cba918 — the merge of head d142c49b9df746f9f39cf500fc6b707cb4e23208 into base e7645078d8680027e1d2b9760dfc686c2cefb8e8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5c539e964928c53fc9b717425818364053cba918 && git checkout 5c539e964928c53fc9b717425818364053cba918
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e7645078d8680027e1d2b9760dfc686c2cefb8e8 d142c49b9df746f9f39cf500fc6b707cb4e23208 && git checkout -B drift-repro e7645078d8680027e1d2b9760dfc686c2cefb8e8 && git merge --no-ff d142c49b9df746f9f39cf500fc6b707cb4e23208
node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e7645078d8680027e1d2b9760dfc686c2cefb8e8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14089

Implements the maintainer's ruling of 2026-09-01 (director batch #23): option C — warn only on the shadowing sub-case. Options A, B and D were excluded, and the PM's earlier three-way ruling was struck.

What changes

A flow node/edge condition is evaluated in a flattened scope, so a bare status normally resolves to the trigger record's field. That form is correct: @objectstack/formula's published contract says so (ExprSchemaHint.scope, cel-engine.ts), AutomationEngine.seedRunVariables flattens the record's fields for exactly that purpose, and two shipped example apps read fields bare. This PR does not judge a bare identifier for being bare, and adds no error.

It names one sub-case that is both genuinely ambiguous and genuinely broken: a bare name that is BOTH a declared flow variable AND a field on the bound object.

constvariables=this.seedDeclaredVariables(flow,context);// (1) variables firstif(context?.record){variables.set('record',context.record);for(const[k,v]ofObject.entries(context.record)){if(!variables.has(k))variables.set(k,v);// (2) guarded flatten}}

The variable wins, the field is unreachable under its own name, and nothing anywhere reports the collision — on the surface where a wrong predicate is least visible, because a flow condition that never fires produces no record, no error and no log line. Severity is warning; the diagnostic names the mechanism and both repairs.

New module packages/lint/src/flow-variable-scope.ts holds the collection surface and the oracle; validate-expressions.ts gains the two emission call sites (flow-node condition, flow-edge condition) and one collection pass.

The collection surface, measured against the executors

Variables are flow-scoped, not graph-scoped — seedRunVariables builds one map per run — so the set is one flat union across every ADR-0031 region collectFlowGraphs yields.

row	declaration point	runtime binder
1	flow.variables[].name	seedDeclaredVariables
2-5	config.iteratorVariable / indexVariable / errorVariable / outputVariable	loop, map, try_catch, crud/screen/subflow nodes
6	assignment targets, wrapper OBJECT shape	logic-nodes.ts
7	assignment targets, wrapper ARRAY shape (variable / name / key)	same
8	assignment targets, no wrapper at all — the config's own keys ARE the names	same, its else branch
9	node ids — a bare CEL root at runtime	evaluateCondition expands a nodeId.outputKey variable into a nested object AT the node id, overwriting whatever scalar was flattened there

Row 8 is gated on the node type, deliberately: it reads every top-level config key, which is correct for an assignment node and catastrophic over-collection for any other. There is a test for that gate.

The rejected itemVariable alias is not read — tolerating a spelling control-flow.zod.ts refuses by name would be consumer-side alias tolerance (Prime Directive 12), and it cannot arrive on the parsed path this rule runs on.

The oracle

firstUndeclaredReference from @objectstack/formula, notcollectCelRootIdentifiers, as the maintainer pinned. The former acts only on cel-js's own unknown-variable fault, so comprehension-macro variables and function names cannot false-positive; the latter reports macro variables as roots, and a macro variable sharing a field's name would then be flagged for a collision that cannot exist. Both are covered by tests.

Its known, deliberate blind spot is pinned rather than left to be discovered: SCOPE_ROOTS members are declared in the strict environment, so a flow variable named result / data / item goes unwarned. That is an under-report, the safe direction for a new warning, and closing it means consulting the AST — which re-opens the macro-variable false positive.

packages/formula is untouched. No new dependency edge: packages/lint already declares @objectstack/formula, and a sibling file in the same package already imports this helper.

Verification — all at d142c49b unless stated

• pnpm --filter @objectstack/lint test — 89 files, 2505 tests passed, exit 0 (captured by redirect before any pipe).
• pnpm --filter @objectstack/lint typecheck — exit 0.
• Both pinned tests pass unchanged.validate-expressions.test.ts "does NOT flag bare references in a flow condition (flattened scope)" (bare amount / bare stage at zero issues) and formula/src/validate.test.ts's flattened-scope pin are untouched by this diff — neither file's pinned assertions were edited, deleted or re-baselined.
• Ablation. With both emission call sites deleted, exactly the 6 positive tests go red and every negative control stays green. Mutation confirmed on disk before the run — HEAD blob hash equal to the pre-mutation hash, call-site count 2 to 0, post-mutation hash different — and the restore leg proved by an empty git diff HEAD. No rebuild leg was needed and none is claimed: the test imports ./validate-expressions.js relatively, so vitest reads this package's source, and nothing resolves it through packages/lint/dist.
• The shipped example apps stay clean, and that is a reading rather than silence.objectstack validate exits 0 on app-todo, app-showcase and app-crm with no shadowing warning. Positive control through the same channel: injecting a status flow variable into app-todo's real task_completion flow (the one whose start condition reads bare status) makes the diagnostic appear, at warning severity with validate still exiting 0. Both legs restored, verified by an empty git diff HEAD.
• Gate families: 33 derived from the actual diff via scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands — not a hand-written list. 30 green. 3 NOT MEASURED, none of them a red: check-test-completeness and check:dual-build-cjs-loads first returned exit 3 (PREREQUISITE NOT MET); the latter was then run on the built closure and passed, while the former has no local turbo test log to grade. scripts/pm/check-half-states.mjs is a network-bound GitHub patrol that does not terminate in this container.
• Ratchets re-run on the final head after the last commit: check:type-check-coverage --re-measure — 27 ledger entries, 1217 raw tsc errors, none above its recorded number, surplus none. Also green at that head: comment-mask-adoption, engine-double-contract, where-matcher, query-options-erasure, type-check-coverage, dual-build-cjs-loads.

Two findings from those gates were repaired rather than routed around, and both are visible in the commit history: the new test file originally carried a private comment-stripper (check:comment-mask-adoption reds on a new one) and now asserts on the module's exported constants instead; and ASSIGNMENT_NODE_TYPE was made module-private after rule-id-barrel-exports correctly read a slug-shaped export const as a rule id owing a barrel line.

Clause 2: no. The accept set does not move in either direction. Nothing that linted clean before this diff lints red after it, and nothing previously rejected is now accepted — the only behavioural change is one additional warning, and a warning never fails the build. The four surfaces the ruling protects are untouched: no contract change, no pinned test deleted or re-baselined, no example app edited, and packages/formula unmodified.

Meta-guard note

validate-expressions.test.ts's #5017 receiver scan gained one PLUMBING entry, scope. It is not a receiver: it is the tail of the './flow-variable-scope.js' import specifier, which the scan cannot tell from a property read — the same artefact as the fields and guards entries already there. No metadata receiver's expected list changed, so the declared-key guard loses no coverage.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 18 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx(via errorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), indexVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), iteratorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))
• content/docs/kernel/runtime-services/examples.mdx(via outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5c539e964928c53fc9b717425818364053cba918 — the merge of head d142c49b9df746f9f39cf500fc6b707cb4e23208 into base e7645078d8680027e1d2b9760dfc686c2cefb8e8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5c539e964928c53fc9b717425818364053cba918 && git checkout 5c539e964928c53fc9b717425818364053cba918
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e7645078d8680027e1d2b9760dfc686c2cefb8e8 d142c49b9df746f9f39cf500fc6b707cb4e23208 && git checkout -B drift-repro e7645078d8680027e1d2b9760dfc686c2cefb8e8 && git merge --no-ff d142c49b9df746f9f39cf500fc6b707cb4e23208
node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e7645078d8680027e1d2b9760dfc686c2cefb8e8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14089

Implements the maintainer's ruling of 2026-09-01 (director batch #23): option C — warn only on the shadowing sub-case. Options A, B and D were excluded, and the PM's earlier three-way ruling was struck.

What changes

A flow node/edge condition is evaluated in a flattened scope, so a bare status normally resolves to the trigger record's field. That form is correct: @objectstack/formula's published contract says so (ExprSchemaHint.scope, cel-engine.ts), AutomationEngine.seedRunVariables flattens the record's fields for exactly that purpose, and two shipped example apps read fields bare. This PR does not judge a bare identifier for being bare, and adds no error.

It names one sub-case that is both genuinely ambiguous and genuinely broken: a bare name that is BOTH a declared flow variable AND a field on the bound object.

constvariables=this.seedDeclaredVariables(flow,context);// (1) variables firstif(context?.record){variables.set('record',context.record);for(const[k,v]ofObject.entries(context.record)){if(!variables.has(k))variables.set(k,v);// (2) guarded flatten}}

The variable wins, the field is unreachable under its own name, and nothing anywhere reports the collision — on the surface where a wrong predicate is least visible, because a flow condition that never fires produces no record, no error and no log line. Severity is warning; the diagnostic names the mechanism and both repairs.

New module packages/lint/src/flow-variable-scope.ts holds the collection surface and the oracle; validate-expressions.ts gains the two emission call sites (flow-node condition, flow-edge condition) and one collection pass.

The collection surface, measured against the executors

Variables are flow-scoped, not graph-scoped — seedRunVariables builds one map per run — so the set is one flat union across every ADR-0031 region collectFlowGraphs yields.

row	declaration point	runtime binder
1	flow.variables[].name	seedDeclaredVariables
2-5	config.iteratorVariable / indexVariable / errorVariable / outputVariable	loop, map, try_catch, crud/screen/subflow nodes
6	assignment targets, wrapper OBJECT shape	logic-nodes.ts
7	assignment targets, wrapper ARRAY shape (variable / name / key)	same
8	assignment targets, no wrapper at all — the config's own keys ARE the names	same, its else branch
9	node ids — a bare CEL root at runtime	evaluateCondition expands a nodeId.outputKey variable into a nested object AT the node id, overwriting whatever scalar was flattened there

Row 8 is gated on the node type, deliberately: it reads every top-level config key, which is correct for an assignment node and catastrophic over-collection for any other. There is a test for that gate.

The rejected itemVariable alias is not read — tolerating a spelling control-flow.zod.ts refuses by name would be consumer-side alias tolerance (Prime Directive 12), and it cannot arrive on the parsed path this rule runs on.

The oracle

firstUndeclaredReference from @objectstack/formula, notcollectCelRootIdentifiers, as the maintainer pinned. The former acts only on cel-js's own unknown-variable fault, so comprehension-macro variables and function names cannot false-positive; the latter reports macro variables as roots, and a macro variable sharing a field's name would then be flagged for a collision that cannot exist. Both are covered by tests.

Its known, deliberate blind spot is pinned rather than left to be discovered: SCOPE_ROOTS members are declared in the strict environment, so a flow variable named result / data / item goes unwarned. That is an under-report, the safe direction for a new warning, and closing it means consulting the AST — which re-opens the macro-variable false positive.

packages/formula is untouched. No new dependency edge: packages/lint already declares @objectstack/formula, and a sibling file in the same package already imports this helper.

Verification — all at d142c49b unless stated

• pnpm --filter @objectstack/lint test — 89 files, 2505 tests passed, exit 0 (captured by redirect before any pipe).
• pnpm --filter @objectstack/lint typecheck — exit 0.
• Both pinned tests pass unchanged.validate-expressions.test.ts "does NOT flag bare references in a flow condition (flattened scope)" (bare amount / bare stage at zero issues) and formula/src/validate.test.ts's flattened-scope pin are untouched by this diff — neither file's pinned assertions were edited, deleted or re-baselined.
• Ablation. With both emission call sites deleted, exactly the 6 positive tests go red and every negative control stays green. Mutation confirmed on disk before the run — HEAD blob hash equal to the pre-mutation hash, call-site count 2 to 0, post-mutation hash different — and the restore leg proved by an empty git diff HEAD. No rebuild leg was needed and none is claimed: the test imports ./validate-expressions.js relatively, so vitest reads this package's source, and nothing resolves it through packages/lint/dist.
• The shipped example apps stay clean, and that is a reading rather than silence.objectstack validate exits 0 on app-todo, app-showcase and app-crm with no shadowing warning. Positive control through the same channel: injecting a status flow variable into app-todo's real task_completion flow (the one whose start condition reads bare status) makes the diagnostic appear, at warning severity with validate still exiting 0. Both legs restored, verified by an empty git diff HEAD.
• Gate families: 33 derived from the actual diff via scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands — not a hand-written list. 30 green. 3 NOT MEASURED, none of them a red: check-test-completeness and check:dual-build-cjs-loads first returned exit 3 (PREREQUISITE NOT MET); the latter was then run on the built closure and passed, while the former has no local turbo test log to grade. scripts/pm/check-half-states.mjs is a network-bound GitHub patrol that does not terminate in this container.
• Ratchets re-run on the final head after the last commit: check:type-check-coverage --re-measure — 27 ledger entries, 1217 raw tsc errors, none above its recorded number, surplus none. Also green at that head: comment-mask-adoption, engine-double-contract, where-matcher, query-options-erasure, type-check-coverage, dual-build-cjs-loads.

Two findings from those gates were repaired rather than routed around, and both are visible in the commit history: the new test file originally carried a private comment-stripper (check:comment-mask-adoption reds on a new one) and now asserts on the module's exported constants instead; and ASSIGNMENT_NODE_TYPE was made module-private after rule-id-barrel-exports correctly read a slug-shaped export const as a rule id owing a barrel line.

Clause 2: no. The accept set does not move in either direction. Nothing that linted clean before this diff lints red after it, and nothing previously rejected is now accepted — the only behavioural change is one additional warning, and a warning never fails the build. The four surfaces the ruling protects are untouched: no contract change, no pinned test deleted or re-baselined, no example app edited, and packages/formula unmodified.

Meta-guard note

validate-expressions.test.ts's #5017 receiver scan gained one PLUMBING entry, scope. It is not a receiver: it is the tail of the './flow-variable-scope.js' import specifier, which the scan cannot tell from a property read — the same artefact as the fields and guards entries already there. No metadata receiver's expected list changed, so the declared-key guard loses no coverage.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 18 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx(via errorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), indexVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), iteratorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))
• content/docs/kernel/runtime-services/examples.mdx(via outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5c539e964928c53fc9b717425818364053cba918 — the merge of head d142c49b9df746f9f39cf500fc6b707cb4e23208 into base e7645078d8680027e1d2b9760dfc686c2cefb8e8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5c539e964928c53fc9b717425818364053cba918 && git checkout 5c539e964928c53fc9b717425818364053cba918
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e7645078d8680027e1d2b9760dfc686c2cefb8e8 d142c49b9df746f9f39cf500fc6b707cb4e23208 && git checkout -B drift-repro e7645078d8680027e1d2b9760dfc686c2cefb8e8 && git merge --no-ff d142c49b9df746f9f39cf500fc6b707cb4e23208
node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e7645078d8680027e1d2b9760dfc686c2cefb8e8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14089

Implements the maintainer's ruling of 2026-09-01 (director batch #23): option C — warn only on the shadowing sub-case. Options A, B and D were excluded, and the PM's earlier three-way ruling was struck.

What changes

A flow node/edge condition is evaluated in a flattened scope, so a bare status normally resolves to the trigger record's field. That form is correct: @objectstack/formula's published contract says so (ExprSchemaHint.scope, cel-engine.ts), AutomationEngine.seedRunVariables flattens the record's fields for exactly that purpose, and two shipped example apps read fields bare. This PR does not judge a bare identifier for being bare, and adds no error.

It names one sub-case that is both genuinely ambiguous and genuinely broken: a bare name that is BOTH a declared flow variable AND a field on the bound object.

constvariables=this.seedDeclaredVariables(flow,context);// (1) variables firstif(context?.record){variables.set('record',context.record);for(const[k,v]ofObject.entries(context.record)){if(!variables.has(k))variables.set(k,v);// (2) guarded flatten}}

The variable wins, the field is unreachable under its own name, and nothing anywhere reports the collision — on the surface where a wrong predicate is least visible, because a flow condition that never fires produces no record, no error and no log line. Severity is warning; the diagnostic names the mechanism and both repairs.

New module packages/lint/src/flow-variable-scope.ts holds the collection surface and the oracle; validate-expressions.ts gains the two emission call sites (flow-node condition, flow-edge condition) and one collection pass.

The collection surface, measured against the executors

Variables are flow-scoped, not graph-scoped — seedRunVariables builds one map per run — so the set is one flat union across every ADR-0031 region collectFlowGraphs yields.

row	declaration point	runtime binder
1	flow.variables[].name	seedDeclaredVariables
2-5	config.iteratorVariable / indexVariable / errorVariable / outputVariable	loop, map, try_catch, crud/screen/subflow nodes
6	assignment targets, wrapper OBJECT shape	logic-nodes.ts
7	assignment targets, wrapper ARRAY shape (variable / name / key)	same
8	assignment targets, no wrapper at all — the config's own keys ARE the names	same, its else branch
9	node ids — a bare CEL root at runtime	evaluateCondition expands a nodeId.outputKey variable into a nested object AT the node id, overwriting whatever scalar was flattened there

Row 8 is gated on the node type, deliberately: it reads every top-level config key, which is correct for an assignment node and catastrophic over-collection for any other. There is a test for that gate.

The rejected itemVariable alias is not read — tolerating a spelling control-flow.zod.ts refuses by name would be consumer-side alias tolerance (Prime Directive 12), and it cannot arrive on the parsed path this rule runs on.

The oracle

firstUndeclaredReference from @objectstack/formula, notcollectCelRootIdentifiers, as the maintainer pinned. The former acts only on cel-js's own unknown-variable fault, so comprehension-macro variables and function names cannot false-positive; the latter reports macro variables as roots, and a macro variable sharing a field's name would then be flagged for a collision that cannot exist. Both are covered by tests.

Its known, deliberate blind spot is pinned rather than left to be discovered: SCOPE_ROOTS members are declared in the strict environment, so a flow variable named result / data / item goes unwarned. That is an under-report, the safe direction for a new warning, and closing it means consulting the AST — which re-opens the macro-variable false positive.

packages/formula is untouched. No new dependency edge: packages/lint already declares @objectstack/formula, and a sibling file in the same package already imports this helper.

Verification — all at d142c49b unless stated

• pnpm --filter @objectstack/lint test — 89 files, 2505 tests passed, exit 0 (captured by redirect before any pipe).
• pnpm --filter @objectstack/lint typecheck — exit 0.
• Both pinned tests pass unchanged.validate-expressions.test.ts "does NOT flag bare references in a flow condition (flattened scope)" (bare amount / bare stage at zero issues) and formula/src/validate.test.ts's flattened-scope pin are untouched by this diff — neither file's pinned assertions were edited, deleted or re-baselined.
• Ablation. With both emission call sites deleted, exactly the 6 positive tests go red and every negative control stays green. Mutation confirmed on disk before the run — HEAD blob hash equal to the pre-mutation hash, call-site count 2 to 0, post-mutation hash different — and the restore leg proved by an empty git diff HEAD. No rebuild leg was needed and none is claimed: the test imports ./validate-expressions.js relatively, so vitest reads this package's source, and nothing resolves it through packages/lint/dist.
• The shipped example apps stay clean, and that is a reading rather than silence.objectstack validate exits 0 on app-todo, app-showcase and app-crm with no shadowing warning. Positive control through the same channel: injecting a status flow variable into app-todo's real task_completion flow (the one whose start condition reads bare status) makes the diagnostic appear, at warning severity with validate still exiting 0. Both legs restored, verified by an empty git diff HEAD.
• Gate families: 33 derived from the actual diff via scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands — not a hand-written list. 30 green. 3 NOT MEASURED, none of them a red: check-test-completeness and check:dual-build-cjs-loads first returned exit 3 (PREREQUISITE NOT MET); the latter was then run on the built closure and passed, while the former has no local turbo test log to grade. scripts/pm/check-half-states.mjs is a network-bound GitHub patrol that does not terminate in this container.
• Ratchets re-run on the final head after the last commit: check:type-check-coverage --re-measure — 27 ledger entries, 1217 raw tsc errors, none above its recorded number, surplus none. Also green at that head: comment-mask-adoption, engine-double-contract, where-matcher, query-options-erasure, type-check-coverage, dual-build-cjs-loads.

Two findings from those gates were repaired rather than routed around, and both are visible in the commit history: the new test file originally carried a private comment-stripper (check:comment-mask-adoption reds on a new one) and now asserts on the module's exported constants instead; and ASSIGNMENT_NODE_TYPE was made module-private after rule-id-barrel-exports correctly read a slug-shaped export const as a rule id owing a barrel line.

Clause 2: no. The accept set does not move in either direction. Nothing that linted clean before this diff lints red after it, and nothing previously rejected is now accepted — the only behavioural change is one additional warning, and a warning never fails the build. The four surfaces the ruling protects are untouched: no contract change, no pinned test deleted or re-baselined, no example app edited, and packages/formula unmodified.

Meta-guard note

validate-expressions.test.ts's #5017 receiver scan gained one PLUMBING entry, scope. It is not a receiver: it is the tail of the './flow-variable-scope.js' import specifier, which the scan cannot tell from a property read — the same artefact as the fields and guards entries already there. No metadata receiver's expected list changed, so the declared-key guard loses no coverage.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 18 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx(via errorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), indexVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), iteratorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))
• content/docs/kernel/runtime-services/examples.mdx(via outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5c539e964928c53fc9b717425818364053cba918 — the merge of head d142c49b9df746f9f39cf500fc6b707cb4e23208 into base e7645078d8680027e1d2b9760dfc686c2cefb8e8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5c539e964928c53fc9b717425818364053cba918 && git checkout 5c539e964928c53fc9b717425818364053cba918
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e7645078d8680027e1d2b9760dfc686c2cefb8e8 d142c49b9df746f9f39cf500fc6b707cb4e23208 && git checkout -B drift-repro e7645078d8680027e1d2b9760dfc686c2cefb8e8 && git merge --no-ff d142c49b9df746f9f39cf500fc6b707cb4e23208
node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e7645078d8680027e1d2b9760dfc686c2cefb8e8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14089

Implements the maintainer's ruling of 2026-09-01 (director batch #23): option C — warn only on the shadowing sub-case. Options A, B and D were excluded, and the PM's earlier three-way ruling was struck.

What changes

A flow node/edge condition is evaluated in a flattened scope, so a bare status normally resolves to the trigger record's field. That form is correct: @objectstack/formula's published contract says so (ExprSchemaHint.scope, cel-engine.ts), AutomationEngine.seedRunVariables flattens the record's fields for exactly that purpose, and two shipped example apps read fields bare. This PR does not judge a bare identifier for being bare, and adds no error.

It names one sub-case that is both genuinely ambiguous and genuinely broken: a bare name that is BOTH a declared flow variable AND a field on the bound object.

constvariables=this.seedDeclaredVariables(flow,context);// (1) variables firstif(context?.record){variables.set('record',context.record);for(const[k,v]ofObject.entries(context.record)){if(!variables.has(k))variables.set(k,v);// (2) guarded flatten}}

The variable wins, the field is unreachable under its own name, and nothing anywhere reports the collision — on the surface where a wrong predicate is least visible, because a flow condition that never fires produces no record, no error and no log line. Severity is warning; the diagnostic names the mechanism and both repairs.

New module packages/lint/src/flow-variable-scope.ts holds the collection surface and the oracle; validate-expressions.ts gains the two emission call sites (flow-node condition, flow-edge condition) and one collection pass.

The collection surface, measured against the executors

Variables are flow-scoped, not graph-scoped — seedRunVariables builds one map per run — so the set is one flat union across every ADR-0031 region collectFlowGraphs yields.

row	declaration point	runtime binder
1	flow.variables[].name	seedDeclaredVariables
2-5	config.iteratorVariable / indexVariable / errorVariable / outputVariable	loop, map, try_catch, crud/screen/subflow nodes
6	assignment targets, wrapper OBJECT shape	logic-nodes.ts
7	assignment targets, wrapper ARRAY shape (variable / name / key)	same
8	assignment targets, no wrapper at all — the config's own keys ARE the names	same, its else branch
9	node ids — a bare CEL root at runtime	evaluateCondition expands a nodeId.outputKey variable into a nested object AT the node id, overwriting whatever scalar was flattened there

Row 8 is gated on the node type, deliberately: it reads every top-level config key, which is correct for an assignment node and catastrophic over-collection for any other. There is a test for that gate.

The rejected itemVariable alias is not read — tolerating a spelling control-flow.zod.ts refuses by name would be consumer-side alias tolerance (Prime Directive 12), and it cannot arrive on the parsed path this rule runs on.

The oracle

firstUndeclaredReference from @objectstack/formula, notcollectCelRootIdentifiers, as the maintainer pinned. The former acts only on cel-js's own unknown-variable fault, so comprehension-macro variables and function names cannot false-positive; the latter reports macro variables as roots, and a macro variable sharing a field's name would then be flagged for a collision that cannot exist. Both are covered by tests.

Its known, deliberate blind spot is pinned rather than left to be discovered: SCOPE_ROOTS members are declared in the strict environment, so a flow variable named result / data / item goes unwarned. That is an under-report, the safe direction for a new warning, and closing it means consulting the AST — which re-opens the macro-variable false positive.

packages/formula is untouched. No new dependency edge: packages/lint already declares @objectstack/formula, and a sibling file in the same package already imports this helper.

Verification — all at d142c49b unless stated

• pnpm --filter @objectstack/lint test — 89 files, 2505 tests passed, exit 0 (captured by redirect before any pipe).
• pnpm --filter @objectstack/lint typecheck — exit 0.
• Both pinned tests pass unchanged.validate-expressions.test.ts "does NOT flag bare references in a flow condition (flattened scope)" (bare amount / bare stage at zero issues) and formula/src/validate.test.ts's flattened-scope pin are untouched by this diff — neither file's pinned assertions were edited, deleted or re-baselined.
• Ablation. With both emission call sites deleted, exactly the 6 positive tests go red and every negative control stays green. Mutation confirmed on disk before the run — HEAD blob hash equal to the pre-mutation hash, call-site count 2 to 0, post-mutation hash different — and the restore leg proved by an empty git diff HEAD. No rebuild leg was needed and none is claimed: the test imports ./validate-expressions.js relatively, so vitest reads this package's source, and nothing resolves it through packages/lint/dist.
• The shipped example apps stay clean, and that is a reading rather than silence.objectstack validate exits 0 on app-todo, app-showcase and app-crm with no shadowing warning. Positive control through the same channel: injecting a status flow variable into app-todo's real task_completion flow (the one whose start condition reads bare status) makes the diagnostic appear, at warning severity with validate still exiting 0. Both legs restored, verified by an empty git diff HEAD.
• Gate families: 33 derived from the actual diff via scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands — not a hand-written list. 30 green. 3 NOT MEASURED, none of them a red: check-test-completeness and check:dual-build-cjs-loads first returned exit 3 (PREREQUISITE NOT MET); the latter was then run on the built closure and passed, while the former has no local turbo test log to grade. scripts/pm/check-half-states.mjs is a network-bound GitHub patrol that does not terminate in this container.
• Ratchets re-run on the final head after the last commit: check:type-check-coverage --re-measure — 27 ledger entries, 1217 raw tsc errors, none above its recorded number, surplus none. Also green at that head: comment-mask-adoption, engine-double-contract, where-matcher, query-options-erasure, type-check-coverage, dual-build-cjs-loads.

Two findings from those gates were repaired rather than routed around, and both are visible in the commit history: the new test file originally carried a private comment-stripper (check:comment-mask-adoption reds on a new one) and now asserts on the module's exported constants instead; and ASSIGNMENT_NODE_TYPE was made module-private after rule-id-barrel-exports correctly read a slug-shaped export const as a rule id owing a barrel line.

Clause 2: no. The accept set does not move in either direction. Nothing that linted clean before this diff lints red after it, and nothing previously rejected is now accepted — the only behavioural change is one additional warning, and a warning never fails the build. The four surfaces the ruling protects are untouched: no contract change, no pinned test deleted or re-baselined, no example app edited, and packages/formula unmodified.

Meta-guard note

validate-expressions.test.ts's #5017 receiver scan gained one PLUMBING entry, scope. It is not a receiver: it is the tail of the './flow-variable-scope.js' import specifier, which the scan cannot tell from a property read — the same artefact as the fields and guards entries already there. No metadata receiver's expected list changed, so the declared-key guard loses no coverage.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 18 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx(via errorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), indexVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), iteratorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))
• content/docs/kernel/runtime-services/examples.mdx(via outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5c539e964928c53fc9b717425818364053cba918 — the merge of head d142c49b9df746f9f39cf500fc6b707cb4e23208 into base e7645078d8680027e1d2b9760dfc686c2cefb8e8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5c539e964928c53fc9b717425818364053cba918 && git checkout 5c539e964928c53fc9b717425818364053cba918
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e7645078d8680027e1d2b9760dfc686c2cefb8e8 d142c49b9df746f9f39cf500fc6b707cb4e23208 && git checkout -B drift-repro e7645078d8680027e1d2b9760dfc686c2cefb8e8 && git merge --no-ff d142c49b9df746f9f39cf500fc6b707cb4e23208
node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e7645078d8680027e1d2b9760dfc686c2cefb8e8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14089

Implements the maintainer's ruling of 2026-09-01 (director batch #23): option C — warn only on the shadowing sub-case. Options A, B and D were excluded, and the PM's earlier three-way ruling was struck.

What changes

A flow node/edge condition is evaluated in a flattened scope, so a bare status normally resolves to the trigger record's field. That form is correct: @objectstack/formula's published contract says so (ExprSchemaHint.scope, cel-engine.ts), AutomationEngine.seedRunVariables flattens the record's fields for exactly that purpose, and two shipped example apps read fields bare. This PR does not judge a bare identifier for being bare, and adds no error.

It names one sub-case that is both genuinely ambiguous and genuinely broken: a bare name that is BOTH a declared flow variable AND a field on the bound object.

constvariables=this.seedDeclaredVariables(flow,context);// (1) variables firstif(context?.record){variables.set('record',context.record);for(const[k,v]ofObject.entries(context.record)){if(!variables.has(k))variables.set(k,v);// (2) guarded flatten}}

The variable wins, the field is unreachable under its own name, and nothing anywhere reports the collision — on the surface where a wrong predicate is least visible, because a flow condition that never fires produces no record, no error and no log line. Severity is warning; the diagnostic names the mechanism and both repairs.

New module packages/lint/src/flow-variable-scope.ts holds the collection surface and the oracle; validate-expressions.ts gains the two emission call sites (flow-node condition, flow-edge condition) and one collection pass.

The collection surface, measured against the executors

Variables are flow-scoped, not graph-scoped — seedRunVariables builds one map per run — so the set is one flat union across every ADR-0031 region collectFlowGraphs yields.

row	declaration point	runtime binder
1	flow.variables[].name	seedDeclaredVariables
2-5	config.iteratorVariable / indexVariable / errorVariable / outputVariable	loop, map, try_catch, crud/screen/subflow nodes
6	assignment targets, wrapper OBJECT shape	logic-nodes.ts
7	assignment targets, wrapper ARRAY shape (variable / name / key)	same
8	assignment targets, no wrapper at all — the config's own keys ARE the names	same, its else branch
9	node ids — a bare CEL root at runtime	evaluateCondition expands a nodeId.outputKey variable into a nested object AT the node id, overwriting whatever scalar was flattened there

Row 8 is gated on the node type, deliberately: it reads every top-level config key, which is correct for an assignment node and catastrophic over-collection for any other. There is a test for that gate.

The rejected itemVariable alias is not read — tolerating a spelling control-flow.zod.ts refuses by name would be consumer-side alias tolerance (Prime Directive 12), and it cannot arrive on the parsed path this rule runs on.

The oracle

firstUndeclaredReference from @objectstack/formula, notcollectCelRootIdentifiers, as the maintainer pinned. The former acts only on cel-js's own unknown-variable fault, so comprehension-macro variables and function names cannot false-positive; the latter reports macro variables as roots, and a macro variable sharing a field's name would then be flagged for a collision that cannot exist. Both are covered by tests.

Its known, deliberate blind spot is pinned rather than left to be discovered: SCOPE_ROOTS members are declared in the strict environment, so a flow variable named result / data / item goes unwarned. That is an under-report, the safe direction for a new warning, and closing it means consulting the AST — which re-opens the macro-variable false positive.

packages/formula is untouched. No new dependency edge: packages/lint already declares @objectstack/formula, and a sibling file in the same package already imports this helper.

Verification — all at d142c49b unless stated

• pnpm --filter @objectstack/lint test — 89 files, 2505 tests passed, exit 0 (captured by redirect before any pipe).
• pnpm --filter @objectstack/lint typecheck — exit 0.
• Both pinned tests pass unchanged.validate-expressions.test.ts "does NOT flag bare references in a flow condition (flattened scope)" (bare amount / bare stage at zero issues) and formula/src/validate.test.ts's flattened-scope pin are untouched by this diff — neither file's pinned assertions were edited, deleted or re-baselined.
• Ablation. With both emission call sites deleted, exactly the 6 positive tests go red and every negative control stays green. Mutation confirmed on disk before the run — HEAD blob hash equal to the pre-mutation hash, call-site count 2 to 0, post-mutation hash different — and the restore leg proved by an empty git diff HEAD. No rebuild leg was needed and none is claimed: the test imports ./validate-expressions.js relatively, so vitest reads this package's source, and nothing resolves it through packages/lint/dist.
• The shipped example apps stay clean, and that is a reading rather than silence.objectstack validate exits 0 on app-todo, app-showcase and app-crm with no shadowing warning. Positive control through the same channel: injecting a status flow variable into app-todo's real task_completion flow (the one whose start condition reads bare status) makes the diagnostic appear, at warning severity with validate still exiting 0. Both legs restored, verified by an empty git diff HEAD.
• Gate families: 33 derived from the actual diff via scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands — not a hand-written list. 30 green. 3 NOT MEASURED, none of them a red: check-test-completeness and check:dual-build-cjs-loads first returned exit 3 (PREREQUISITE NOT MET); the latter was then run on the built closure and passed, while the former has no local turbo test log to grade. scripts/pm/check-half-states.mjs is a network-bound GitHub patrol that does not terminate in this container.
• Ratchets re-run on the final head after the last commit: check:type-check-coverage --re-measure — 27 ledger entries, 1217 raw tsc errors, none above its recorded number, surplus none. Also green at that head: comment-mask-adoption, engine-double-contract, where-matcher, query-options-erasure, type-check-coverage, dual-build-cjs-loads.

Two findings from those gates were repaired rather than routed around, and both are visible in the commit history: the new test file originally carried a private comment-stripper (check:comment-mask-adoption reds on a new one) and now asserts on the module's exported constants instead; and ASSIGNMENT_NODE_TYPE was made module-private after rule-id-barrel-exports correctly read a slug-shaped export const as a rule id owing a barrel line.

Clause 2: no. The accept set does not move in either direction. Nothing that linted clean before this diff lints red after it, and nothing previously rejected is now accepted — the only behavioural change is one additional warning, and a warning never fails the build. The four surfaces the ruling protects are untouched: no contract change, no pinned test deleted or re-baselined, no example app edited, and packages/formula unmodified.

Meta-guard note

validate-expressions.test.ts's #5017 receiver scan gained one PLUMBING entry, scope. It is not a receiver: it is the tail of the './flow-variable-scope.js' import specifier, which the scan cannot tell from a property read — the same artefact as the fields and guards entries already there. No metadata receiver's expected list changed, so the declared-key guard loses no coverage.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 18 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx(via errorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), indexVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), iteratorVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS), outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))
• content/docs/kernel/runtime-services/examples.mdx(via outputVariable (literal, a string literal in VARIABLE_NAME_CONFIG_KEYS))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via validateStackExpressions (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5c539e964928c53fc9b717425818364053cba918 — the merge of head d142c49b9df746f9f39cf500fc6b707cb4e23208 into base e7645078d8680027e1d2b9760dfc686c2cefb8e8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5c539e964928c53fc9b717425818364053cba918 && git checkout 5c539e964928c53fc9b717425818364053cba918
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e7645078d8680027e1d2b9760dfc686c2cefb8e8 d142c49b9df746f9f39cf500fc6b707cb4e23208 && git checkout -B drift-repro e7645078d8680027e1d2b9760dfc686c2cefb8e8 && git merge --no-ff d142c49b9df746f9f39cf500fc6b707cb4e23208
node scripts/docs-audit/affected-docs.mjs --json e7645078d8680027e1d2b9760dfc686c2cefb8e8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e7645078d8680027e1d2b9760dfc686c2cefb8e8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.