fix(cli): os generate flow scaffolds a flow os validate accepts, and a test that keeps it that way

[os-trump]

Fixes#14087

The defect, reproduced before anything was edited

os g flow my_flow wrote a file os validate refused. Measured on origin/maind63c8a2, scaffolded for the name probe_thing and put through the same steps Validate.run() performs — four refusals in one parse, verbatim:

flows.0.nodes.0.label: Invalid input: expected string, received undefined
flows.0.nodes.0: Unrecognized key(s) on this flow node: `name`, `next`.
flows.0.edges: Invalid input: expected array, received undefined
flows.0: Unrecognized key(s) on this flow: `trigger`. Did you mean `trigger` → `type`?

Both halves of the card hold, and the measurement adds a third the card did not name: edges is a REQUIRED key on FlowSchema and the template emitted none. The scaffold also declared one node and pointed its next at a node it never wrote.

The fix

packages/cli/src/commands/generate.ts, the flow template only. The trigger binding moves to where AutomationEngine.resolveTriggerBinding actually reads it — the START node's config:

type: 'record_change',status: 'draft',nodes: [{id: 'start',type: 'start',label: 'Start',config: {objectName: 'probe_thing',triggerType: 'record-after-write'}},{id: 'end',type: 'end',label: 'End'},],edges: [{id: 'e1',source: 'start',target: 'end',type: 'default'}],

The card's spelling of the vocabulary was checked rather than copied: record-after-write is real (it is VALID_RECORD_TRIGGER's grammar in packages/lint/src/validate-flow-trigger-readiness.ts, and 'write' is the create-OR-update token from #3427), while events: ['after_insert', …] exists nowhere on the current surface. type moves from 'autolaunched' to 'record_change' because that is what the retired trigger.type block declared this flow to be, and it is the declaration rule 1f gates.

status deliberately stays 'draft'. Arming is the author's decision and os validate says so in an advisory; changing it would move the runtime behaviour of every generated app, which is outside what this card claims.

Measured on the fixed scaffold: 0 error-severity findings, 2 advisories — flow-trigger-unknown-object (the objectName placeholder is not an object the fresh stack defines — the prompt to replace it) and flow-draft-status-ambiguous (the status decision above). os validate exits 0.

The scaffold-validates test

packages/cli/test/generate-scaffold-validates.test.ts. It loads each scaffold the way os validate loads authored TypeScript — through bundle-require with BUNDLE_REQUIRE_EXTERNALS, the same call loadConfig makes — and then re-runs the two steps Validate.run() performs on the result: normalizeStackInput + the unknown-key lints + ObjectStackDefinitionSchema.safeParse, then runAuthoringRules('validate') gating on the error half.

Both layers are load-bearing, and the second is the half a schema-only assertion would miss: a flow node's config is an OPEN slot by design (ADR-0018), so FlowSchema cannot judge the trigger vocabulary at all. A start node carrying triggerType: 'record_change' parses green and is caught one layer later by validate-flow-trigger-readiness. Asserting the schema alone would let this scaffold's own trigger token drift back to a spelling that never fires.

Nothing in the file is restated: the roster comes from GENERATOR_SCAFFOLD_TARGETS (built from GENERATORS itself, now carrying each entry's generate), and the stack collection each artifact lands in comes from singularToPlural — the map defineStack and the metadata registry already share. A generator added tomorrow is measured on the day it lands.

Red-first, then ablated

• RED — the test at its final content, against the unmodified template: Tests 2 failed | 12 passed (14), failing with exactly the four refusals quoted above.
• GREEN after the template fix: Tests 14 passed (14).
• ABLATION, from the committed state: the START node's label: 'Start' mutated to name: 'Start'. Mutation confirmed on disk in both directions (injected 1, original 0) and by blob hash (3dae1933 → fbd28caf); the mutated tree fails 2/14. Restored with git checkout HEAD -- ABSOLUTE_PATH, proven by git diff HEAD empty plus the blob hash back at 3dae1933; restored tree 14/14. No rebuild leg is owed on either side: the test resolves the template through a relative ../src/… path vitest transforms from source, so the dist/ staleness hazard does not apply to this pair. The script carried a trap … EXIT INT TERM restore throughout.

Out of scope, filed rather than fixed

Running the derived roster is how it emerged that flow is not the only refused scaffold. Same harness, same commit: object parses and then fails security-owd-unset; view, action and app fail the parse for reasons of their own; dashboard and skill are clean. Triage fenced that census out of this card, so it is #14336 and is not touched here.

The four are recorded in the new test's KNOWN_UNVALIDATED_SCAFFOLDS — shrink-only, in the shape this repo uses elsewhere, with an anti-staleness assertion: a kind IN the ledger must still FAIL, so whoever repairs one turns this test red and deletes its entry in the same PR. It can never grow to cover a regression, because a newly-broken kind is not in it and simply fails. flow is additionally asserted absent from the ledger, so this card's own defect cannot be re-admitted by adding a line to a table.

#14337 is the other finding: FlowSchema's trigger alias prescribes a rename to type, and taking that advice cannot work. That is the diagnostic a hand-writing author still meets; it lands in packages/spec and is not addressed here.

The hot-file fence held — the migration codegen field-type switch region of generate.ts is untouched.

Verification

• pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/generate-scaffold-validates.test.ts → 14/14, on c19eb73310.
• The full derived gate family union for this change set (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, 36 families) ran on that head. See the report comment on objectstack generate scaffolds a flow that objectstack validate rejects — the trigger key and the events vocabulary do not exist on protocol 17 #14087 for the per-gate exit codes, including the two that report NOT MEASURED by their own exit-3 prerequisite branch rather than a verdict.
• pnpm lint (repo-wide eslint . --no-inline-config, no narrowing) → exit 0 in 1m54s.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/data-flow.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/api/plugin-endpoints.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/approvals.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/flows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/hooks.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/workflows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/concepts/architecture.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/deployment/cli.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/getting-started/common-patterns.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/kernel/services-checklist.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/protocol/kernel/lifecycle.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/objectql/schema.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• content/docs/releases/v12.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/releases/v17.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• 4 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 — 23 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ced9a1ea7804a217c60bb29584d4759426ab060e — the merge of head c19eb733102eae66df9b6630e330631caebd3c5b into base e854a531abc9ee81264a17d0e0b1f41b38f6f03e, 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 ced9a1ea7804a217c60bb29584d4759426ab060e && git checkout ced9a1ea7804a217c60bb29584d4759426ab060e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e854a531abc9ee81264a17d0e0b1f41b38f6f03e c19eb733102eae66df9b6630e330631caebd3c5b && git checkout -B drift-repro e854a531abc9ee81264a17d0e0b1f41b38f6f03e && git merge --no-ff c19eb733102eae66df9b6630e330631caebd3c5b
node scripts/docs-audit/affected-docs.mjs --json e854a531abc9ee81264a17d0e0b1f41b38f6f03e

⚠️ 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-trump]

Fixes#14087

The defect, reproduced before anything was edited

os g flow my_flow wrote a file os validate refused. Measured on origin/maind63c8a2, scaffolded for the name probe_thing and put through the same steps Validate.run() performs — four refusals in one parse, verbatim:

flows.0.nodes.0.label: Invalid input: expected string, received undefined
flows.0.nodes.0: Unrecognized key(s) on this flow node: `name`, `next`.
flows.0.edges: Invalid input: expected array, received undefined
flows.0: Unrecognized key(s) on this flow: `trigger`. Did you mean `trigger` → `type`?

Both halves of the card hold, and the measurement adds a third the card did not name: edges is a REQUIRED key on FlowSchema and the template emitted none. The scaffold also declared one node and pointed its next at a node it never wrote.

The fix

packages/cli/src/commands/generate.ts, the flow template only. The trigger binding moves to where AutomationEngine.resolveTriggerBinding actually reads it — the START node's config:

type: 'record_change',status: 'draft',nodes: [{id: 'start',type: 'start',label: 'Start',config: {objectName: 'probe_thing',triggerType: 'record-after-write'}},{id: 'end',type: 'end',label: 'End'},],edges: [{id: 'e1',source: 'start',target: 'end',type: 'default'}],

The card's spelling of the vocabulary was checked rather than copied: record-after-write is real (it is VALID_RECORD_TRIGGER's grammar in packages/lint/src/validate-flow-trigger-readiness.ts, and 'write' is the create-OR-update token from #3427), while events: ['after_insert', …] exists nowhere on the current surface. type moves from 'autolaunched' to 'record_change' because that is what the retired trigger.type block declared this flow to be, and it is the declaration rule 1f gates.

status deliberately stays 'draft'. Arming is the author's decision and os validate says so in an advisory; changing it would move the runtime behaviour of every generated app, which is outside what this card claims.

Measured on the fixed scaffold: 0 error-severity findings, 2 advisories — flow-trigger-unknown-object (the objectName placeholder is not an object the fresh stack defines — the prompt to replace it) and flow-draft-status-ambiguous (the status decision above). os validate exits 0.

The scaffold-validates test

packages/cli/test/generate-scaffold-validates.test.ts. It loads each scaffold the way os validate loads authored TypeScript — through bundle-require with BUNDLE_REQUIRE_EXTERNALS, the same call loadConfig makes — and then re-runs the two steps Validate.run() performs on the result: normalizeStackInput + the unknown-key lints + ObjectStackDefinitionSchema.safeParse, then runAuthoringRules('validate') gating on the error half.

Both layers are load-bearing, and the second is the half a schema-only assertion would miss: a flow node's config is an OPEN slot by design (ADR-0018), so FlowSchema cannot judge the trigger vocabulary at all. A start node carrying triggerType: 'record_change' parses green and is caught one layer later by validate-flow-trigger-readiness. Asserting the schema alone would let this scaffold's own trigger token drift back to a spelling that never fires.

Nothing in the file is restated: the roster comes from GENERATOR_SCAFFOLD_TARGETS (built from GENERATORS itself, now carrying each entry's generate), and the stack collection each artifact lands in comes from singularToPlural — the map defineStack and the metadata registry already share. A generator added tomorrow is measured on the day it lands.

Red-first, then ablated

• RED — the test at its final content, against the unmodified template: Tests 2 failed | 12 passed (14), failing with exactly the four refusals quoted above.
• GREEN after the template fix: Tests 14 passed (14).
• ABLATION, from the committed state: the START node's label: 'Start' mutated to name: 'Start'. Mutation confirmed on disk in both directions (injected 1, original 0) and by blob hash (3dae1933 → fbd28caf); the mutated tree fails 2/14. Restored with git checkout HEAD -- ABSOLUTE_PATH, proven by git diff HEAD empty plus the blob hash back at 3dae1933; restored tree 14/14. No rebuild leg is owed on either side: the test resolves the template through a relative ../src/… path vitest transforms from source, so the dist/ staleness hazard does not apply to this pair. The script carried a trap … EXIT INT TERM restore throughout.

Out of scope, filed rather than fixed

Running the derived roster is how it emerged that flow is not the only refused scaffold. Same harness, same commit: object parses and then fails security-owd-unset; view, action and app fail the parse for reasons of their own; dashboard and skill are clean. Triage fenced that census out of this card, so it is #14336 and is not touched here.

The four are recorded in the new test's KNOWN_UNVALIDATED_SCAFFOLDS — shrink-only, in the shape this repo uses elsewhere, with an anti-staleness assertion: a kind IN the ledger must still FAIL, so whoever repairs one turns this test red and deletes its entry in the same PR. It can never grow to cover a regression, because a newly-broken kind is not in it and simply fails. flow is additionally asserted absent from the ledger, so this card's own defect cannot be re-admitted by adding a line to a table.

#14337 is the other finding: FlowSchema's trigger alias prescribes a rename to type, and taking that advice cannot work. That is the diagnostic a hand-writing author still meets; it lands in packages/spec and is not addressed here.

The hot-file fence held — the migration codegen field-type switch region of generate.ts is untouched.

Verification

• pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/generate-scaffold-validates.test.ts → 14/14, on c19eb73310.
• The full derived gate family union for this change set (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, 36 families) ran on that head. See the report comment on objectstack generate scaffolds a flow that objectstack validate rejects — the trigger key and the events vocabulary do not exist on protocol 17 #14087 for the per-gate exit codes, including the two that report NOT MEASURED by their own exit-3 prerequisite branch rather than a verdict.
• pnpm lint (repo-wide eslint . --no-inline-config, no narrowing) → exit 0 in 1m54s.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/data-flow.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/api/plugin-endpoints.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/approvals.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/flows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/hooks.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/workflows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/concepts/architecture.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/deployment/cli.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/getting-started/common-patterns.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/kernel/services-checklist.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/protocol/kernel/lifecycle.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/objectql/schema.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• content/docs/releases/v12.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/releases/v17.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• 4 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 — 23 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ced9a1ea7804a217c60bb29584d4759426ab060e — the merge of head c19eb733102eae66df9b6630e330631caebd3c5b into base e854a531abc9ee81264a17d0e0b1f41b38f6f03e, 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 ced9a1ea7804a217c60bb29584d4759426ab060e && git checkout ced9a1ea7804a217c60bb29584d4759426ab060e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e854a531abc9ee81264a17d0e0b1f41b38f6f03e c19eb733102eae66df9b6630e330631caebd3c5b && git checkout -B drift-repro e854a531abc9ee81264a17d0e0b1f41b38f6f03e && git merge --no-ff c19eb733102eae66df9b6630e330631caebd3c5b
node scripts/docs-audit/affected-docs.mjs --json e854a531abc9ee81264a17d0e0b1f41b38f6f03e

⚠️ 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-trump]

Fixes#14087

The defect, reproduced before anything was edited

os g flow my_flow wrote a file os validate refused. Measured on origin/maind63c8a2, scaffolded for the name probe_thing and put through the same steps Validate.run() performs — four refusals in one parse, verbatim:

flows.0.nodes.0.label: Invalid input: expected string, received undefined
flows.0.nodes.0: Unrecognized key(s) on this flow node: `name`, `next`.
flows.0.edges: Invalid input: expected array, received undefined
flows.0: Unrecognized key(s) on this flow: `trigger`. Did you mean `trigger` → `type`?

Both halves of the card hold, and the measurement adds a third the card did not name: edges is a REQUIRED key on FlowSchema and the template emitted none. The scaffold also declared one node and pointed its next at a node it never wrote.

The fix

packages/cli/src/commands/generate.ts, the flow template only. The trigger binding moves to where AutomationEngine.resolveTriggerBinding actually reads it — the START node's config:

type: 'record_change',status: 'draft',nodes: [{id: 'start',type: 'start',label: 'Start',config: {objectName: 'probe_thing',triggerType: 'record-after-write'}},{id: 'end',type: 'end',label: 'End'},],edges: [{id: 'e1',source: 'start',target: 'end',type: 'default'}],

The card's spelling of the vocabulary was checked rather than copied: record-after-write is real (it is VALID_RECORD_TRIGGER's grammar in packages/lint/src/validate-flow-trigger-readiness.ts, and 'write' is the create-OR-update token from #3427), while events: ['after_insert', …] exists nowhere on the current surface. type moves from 'autolaunched' to 'record_change' because that is what the retired trigger.type block declared this flow to be, and it is the declaration rule 1f gates.

status deliberately stays 'draft'. Arming is the author's decision and os validate says so in an advisory; changing it would move the runtime behaviour of every generated app, which is outside what this card claims.

Measured on the fixed scaffold: 0 error-severity findings, 2 advisories — flow-trigger-unknown-object (the objectName placeholder is not an object the fresh stack defines — the prompt to replace it) and flow-draft-status-ambiguous (the status decision above). os validate exits 0.

The scaffold-validates test

packages/cli/test/generate-scaffold-validates.test.ts. It loads each scaffold the way os validate loads authored TypeScript — through bundle-require with BUNDLE_REQUIRE_EXTERNALS, the same call loadConfig makes — and then re-runs the two steps Validate.run() performs on the result: normalizeStackInput + the unknown-key lints + ObjectStackDefinitionSchema.safeParse, then runAuthoringRules('validate') gating on the error half.

Both layers are load-bearing, and the second is the half a schema-only assertion would miss: a flow node's config is an OPEN slot by design (ADR-0018), so FlowSchema cannot judge the trigger vocabulary at all. A start node carrying triggerType: 'record_change' parses green and is caught one layer later by validate-flow-trigger-readiness. Asserting the schema alone would let this scaffold's own trigger token drift back to a spelling that never fires.

Nothing in the file is restated: the roster comes from GENERATOR_SCAFFOLD_TARGETS (built from GENERATORS itself, now carrying each entry's generate), and the stack collection each artifact lands in comes from singularToPlural — the map defineStack and the metadata registry already share. A generator added tomorrow is measured on the day it lands.

Red-first, then ablated

• RED — the test at its final content, against the unmodified template: Tests 2 failed | 12 passed (14), failing with exactly the four refusals quoted above.
• GREEN after the template fix: Tests 14 passed (14).
• ABLATION, from the committed state: the START node's label: 'Start' mutated to name: 'Start'. Mutation confirmed on disk in both directions (injected 1, original 0) and by blob hash (3dae1933 → fbd28caf); the mutated tree fails 2/14. Restored with git checkout HEAD -- ABSOLUTE_PATH, proven by git diff HEAD empty plus the blob hash back at 3dae1933; restored tree 14/14. No rebuild leg is owed on either side: the test resolves the template through a relative ../src/… path vitest transforms from source, so the dist/ staleness hazard does not apply to this pair. The script carried a trap … EXIT INT TERM restore throughout.

Out of scope, filed rather than fixed

Running the derived roster is how it emerged that flow is not the only refused scaffold. Same harness, same commit: object parses and then fails security-owd-unset; view, action and app fail the parse for reasons of their own; dashboard and skill are clean. Triage fenced that census out of this card, so it is #14336 and is not touched here.

The four are recorded in the new test's KNOWN_UNVALIDATED_SCAFFOLDS — shrink-only, in the shape this repo uses elsewhere, with an anti-staleness assertion: a kind IN the ledger must still FAIL, so whoever repairs one turns this test red and deletes its entry in the same PR. It can never grow to cover a regression, because a newly-broken kind is not in it and simply fails. flow is additionally asserted absent from the ledger, so this card's own defect cannot be re-admitted by adding a line to a table.

#14337 is the other finding: FlowSchema's trigger alias prescribes a rename to type, and taking that advice cannot work. That is the diagnostic a hand-writing author still meets; it lands in packages/spec and is not addressed here.

The hot-file fence held — the migration codegen field-type switch region of generate.ts is untouched.

Verification

• pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/generate-scaffold-validates.test.ts → 14/14, on c19eb73310.
• The full derived gate family union for this change set (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, 36 families) ran on that head. See the report comment on objectstack generate scaffolds a flow that objectstack validate rejects — the trigger key and the events vocabulary do not exist on protocol 17 #14087 for the per-gate exit codes, including the two that report NOT MEASURED by their own exit-3 prerequisite branch rather than a verdict.
• pnpm lint (repo-wide eslint . --no-inline-config, no narrowing) → exit 0 in 1m54s.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/data-flow.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/api/plugin-endpoints.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/approvals.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/flows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/hooks.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/workflows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/concepts/architecture.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/deployment/cli.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/getting-started/common-patterns.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/kernel/services-checklist.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/protocol/kernel/lifecycle.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/objectql/schema.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• content/docs/releases/v12.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/releases/v17.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• 4 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 — 23 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ced9a1ea7804a217c60bb29584d4759426ab060e — the merge of head c19eb733102eae66df9b6630e330631caebd3c5b into base e854a531abc9ee81264a17d0e0b1f41b38f6f03e, 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 ced9a1ea7804a217c60bb29584d4759426ab060e && git checkout ced9a1ea7804a217c60bb29584d4759426ab060e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e854a531abc9ee81264a17d0e0b1f41b38f6f03e c19eb733102eae66df9b6630e330631caebd3c5b && git checkout -B drift-repro e854a531abc9ee81264a17d0e0b1f41b38f6f03e && git merge --no-ff c19eb733102eae66df9b6630e330631caebd3c5b
node scripts/docs-audit/affected-docs.mjs --json e854a531abc9ee81264a17d0e0b1f41b38f6f03e

⚠️ 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-trump]

Fixes#14087

The defect, reproduced before anything was edited

os g flow my_flow wrote a file os validate refused. Measured on origin/maind63c8a2, scaffolded for the name probe_thing and put through the same steps Validate.run() performs — four refusals in one parse, verbatim:

flows.0.nodes.0.label: Invalid input: expected string, received undefined
flows.0.nodes.0: Unrecognized key(s) on this flow node: `name`, `next`.
flows.0.edges: Invalid input: expected array, received undefined
flows.0: Unrecognized key(s) on this flow: `trigger`. Did you mean `trigger` → `type`?

Both halves of the card hold, and the measurement adds a third the card did not name: edges is a REQUIRED key on FlowSchema and the template emitted none. The scaffold also declared one node and pointed its next at a node it never wrote.

The fix

packages/cli/src/commands/generate.ts, the flow template only. The trigger binding moves to where AutomationEngine.resolveTriggerBinding actually reads it — the START node's config:

type: 'record_change',status: 'draft',nodes: [{id: 'start',type: 'start',label: 'Start',config: {objectName: 'probe_thing',triggerType: 'record-after-write'}},{id: 'end',type: 'end',label: 'End'},],edges: [{id: 'e1',source: 'start',target: 'end',type: 'default'}],

The card's spelling of the vocabulary was checked rather than copied: record-after-write is real (it is VALID_RECORD_TRIGGER's grammar in packages/lint/src/validate-flow-trigger-readiness.ts, and 'write' is the create-OR-update token from #3427), while events: ['after_insert', …] exists nowhere on the current surface. type moves from 'autolaunched' to 'record_change' because that is what the retired trigger.type block declared this flow to be, and it is the declaration rule 1f gates.

status deliberately stays 'draft'. Arming is the author's decision and os validate says so in an advisory; changing it would move the runtime behaviour of every generated app, which is outside what this card claims.

Measured on the fixed scaffold: 0 error-severity findings, 2 advisories — flow-trigger-unknown-object (the objectName placeholder is not an object the fresh stack defines — the prompt to replace it) and flow-draft-status-ambiguous (the status decision above). os validate exits 0.

The scaffold-validates test

packages/cli/test/generate-scaffold-validates.test.ts. It loads each scaffold the way os validate loads authored TypeScript — through bundle-require with BUNDLE_REQUIRE_EXTERNALS, the same call loadConfig makes — and then re-runs the two steps Validate.run() performs on the result: normalizeStackInput + the unknown-key lints + ObjectStackDefinitionSchema.safeParse, then runAuthoringRules('validate') gating on the error half.

Both layers are load-bearing, and the second is the half a schema-only assertion would miss: a flow node's config is an OPEN slot by design (ADR-0018), so FlowSchema cannot judge the trigger vocabulary at all. A start node carrying triggerType: 'record_change' parses green and is caught one layer later by validate-flow-trigger-readiness. Asserting the schema alone would let this scaffold's own trigger token drift back to a spelling that never fires.

Nothing in the file is restated: the roster comes from GENERATOR_SCAFFOLD_TARGETS (built from GENERATORS itself, now carrying each entry's generate), and the stack collection each artifact lands in comes from singularToPlural — the map defineStack and the metadata registry already share. A generator added tomorrow is measured on the day it lands.

Red-first, then ablated

• RED — the test at its final content, against the unmodified template: Tests 2 failed | 12 passed (14), failing with exactly the four refusals quoted above.
• GREEN after the template fix: Tests 14 passed (14).
• ABLATION, from the committed state: the START node's label: 'Start' mutated to name: 'Start'. Mutation confirmed on disk in both directions (injected 1, original 0) and by blob hash (3dae1933 → fbd28caf); the mutated tree fails 2/14. Restored with git checkout HEAD -- ABSOLUTE_PATH, proven by git diff HEAD empty plus the blob hash back at 3dae1933; restored tree 14/14. No rebuild leg is owed on either side: the test resolves the template through a relative ../src/… path vitest transforms from source, so the dist/ staleness hazard does not apply to this pair. The script carried a trap … EXIT INT TERM restore throughout.

Out of scope, filed rather than fixed

Running the derived roster is how it emerged that flow is not the only refused scaffold. Same harness, same commit: object parses and then fails security-owd-unset; view, action and app fail the parse for reasons of their own; dashboard and skill are clean. Triage fenced that census out of this card, so it is #14336 and is not touched here.

The four are recorded in the new test's KNOWN_UNVALIDATED_SCAFFOLDS — shrink-only, in the shape this repo uses elsewhere, with an anti-staleness assertion: a kind IN the ledger must still FAIL, so whoever repairs one turns this test red and deletes its entry in the same PR. It can never grow to cover a regression, because a newly-broken kind is not in it and simply fails. flow is additionally asserted absent from the ledger, so this card's own defect cannot be re-admitted by adding a line to a table.

#14337 is the other finding: FlowSchema's trigger alias prescribes a rename to type, and taking that advice cannot work. That is the diagnostic a hand-writing author still meets; it lands in packages/spec and is not addressed here.

The hot-file fence held — the migration codegen field-type switch region of generate.ts is untouched.

Verification

• pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/generate-scaffold-validates.test.ts → 14/14, on c19eb73310.
• The full derived gate family union for this change set (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, 36 families) ran on that head. See the report comment on objectstack generate scaffolds a flow that objectstack validate rejects — the trigger key and the events vocabulary do not exist on protocol 17 #14087 for the per-gate exit codes, including the two that report NOT MEASURED by their own exit-3 prerequisite branch rather than a verdict.
• pnpm lint (repo-wide eslint . --no-inline-config, no narrowing) → exit 0 in 1m54s.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/data-flow.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/api/plugin-endpoints.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/approvals.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/flows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/hooks.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/workflows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/concepts/architecture.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/deployment/cli.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/getting-started/common-patterns.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/kernel/services-checklist.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/protocol/kernel/lifecycle.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/objectql/schema.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• content/docs/releases/v12.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/releases/v17.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• 4 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 — 23 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ced9a1ea7804a217c60bb29584d4759426ab060e — the merge of head c19eb733102eae66df9b6630e330631caebd3c5b into base e854a531abc9ee81264a17d0e0b1f41b38f6f03e, 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 ced9a1ea7804a217c60bb29584d4759426ab060e && git checkout ced9a1ea7804a217c60bb29584d4759426ab060e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e854a531abc9ee81264a17d0e0b1f41b38f6f03e c19eb733102eae66df9b6630e330631caebd3c5b && git checkout -B drift-repro e854a531abc9ee81264a17d0e0b1f41b38f6f03e && git merge --no-ff c19eb733102eae66df9b6630e330631caebd3c5b
node scripts/docs-audit/affected-docs.mjs --json e854a531abc9ee81264a17d0e0b1f41b38f6f03e

⚠️ 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-trump]

Fixes#14087

The defect, reproduced before anything was edited

os g flow my_flow wrote a file os validate refused. Measured on origin/maind63c8a2, scaffolded for the name probe_thing and put through the same steps Validate.run() performs — four refusals in one parse, verbatim:

flows.0.nodes.0.label: Invalid input: expected string, received undefined
flows.0.nodes.0: Unrecognized key(s) on this flow node: `name`, `next`.
flows.0.edges: Invalid input: expected array, received undefined
flows.0: Unrecognized key(s) on this flow: `trigger`. Did you mean `trigger` → `type`?

Both halves of the card hold, and the measurement adds a third the card did not name: edges is a REQUIRED key on FlowSchema and the template emitted none. The scaffold also declared one node and pointed its next at a node it never wrote.

The fix

packages/cli/src/commands/generate.ts, the flow template only. The trigger binding moves to where AutomationEngine.resolveTriggerBinding actually reads it — the START node's config:

type: 'record_change',status: 'draft',nodes: [{id: 'start',type: 'start',label: 'Start',config: {objectName: 'probe_thing',triggerType: 'record-after-write'}},{id: 'end',type: 'end',label: 'End'},],edges: [{id: 'e1',source: 'start',target: 'end',type: 'default'}],

The card's spelling of the vocabulary was checked rather than copied: record-after-write is real (it is VALID_RECORD_TRIGGER's grammar in packages/lint/src/validate-flow-trigger-readiness.ts, and 'write' is the create-OR-update token from #3427), while events: ['after_insert', …] exists nowhere on the current surface. type moves from 'autolaunched' to 'record_change' because that is what the retired trigger.type block declared this flow to be, and it is the declaration rule 1f gates.

status deliberately stays 'draft'. Arming is the author's decision and os validate says so in an advisory; changing it would move the runtime behaviour of every generated app, which is outside what this card claims.

Measured on the fixed scaffold: 0 error-severity findings, 2 advisories — flow-trigger-unknown-object (the objectName placeholder is not an object the fresh stack defines — the prompt to replace it) and flow-draft-status-ambiguous (the status decision above). os validate exits 0.

The scaffold-validates test

packages/cli/test/generate-scaffold-validates.test.ts. It loads each scaffold the way os validate loads authored TypeScript — through bundle-require with BUNDLE_REQUIRE_EXTERNALS, the same call loadConfig makes — and then re-runs the two steps Validate.run() performs on the result: normalizeStackInput + the unknown-key lints + ObjectStackDefinitionSchema.safeParse, then runAuthoringRules('validate') gating on the error half.

Both layers are load-bearing, and the second is the half a schema-only assertion would miss: a flow node's config is an OPEN slot by design (ADR-0018), so FlowSchema cannot judge the trigger vocabulary at all. A start node carrying triggerType: 'record_change' parses green and is caught one layer later by validate-flow-trigger-readiness. Asserting the schema alone would let this scaffold's own trigger token drift back to a spelling that never fires.

Nothing in the file is restated: the roster comes from GENERATOR_SCAFFOLD_TARGETS (built from GENERATORS itself, now carrying each entry's generate), and the stack collection each artifact lands in comes from singularToPlural — the map defineStack and the metadata registry already share. A generator added tomorrow is measured on the day it lands.

Red-first, then ablated

• RED — the test at its final content, against the unmodified template: Tests 2 failed | 12 passed (14), failing with exactly the four refusals quoted above.
• GREEN after the template fix: Tests 14 passed (14).
• ABLATION, from the committed state: the START node's label: 'Start' mutated to name: 'Start'. Mutation confirmed on disk in both directions (injected 1, original 0) and by blob hash (3dae1933 → fbd28caf); the mutated tree fails 2/14. Restored with git checkout HEAD -- ABSOLUTE_PATH, proven by git diff HEAD empty plus the blob hash back at 3dae1933; restored tree 14/14. No rebuild leg is owed on either side: the test resolves the template through a relative ../src/… path vitest transforms from source, so the dist/ staleness hazard does not apply to this pair. The script carried a trap … EXIT INT TERM restore throughout.

Out of scope, filed rather than fixed

Running the derived roster is how it emerged that flow is not the only refused scaffold. Same harness, same commit: object parses and then fails security-owd-unset; view, action and app fail the parse for reasons of their own; dashboard and skill are clean. Triage fenced that census out of this card, so it is #14336 and is not touched here.

The four are recorded in the new test's KNOWN_UNVALIDATED_SCAFFOLDS — shrink-only, in the shape this repo uses elsewhere, with an anti-staleness assertion: a kind IN the ledger must still FAIL, so whoever repairs one turns this test red and deletes its entry in the same PR. It can never grow to cover a regression, because a newly-broken kind is not in it and simply fails. flow is additionally asserted absent from the ledger, so this card's own defect cannot be re-admitted by adding a line to a table.

#14337 is the other finding: FlowSchema's trigger alias prescribes a rename to type, and taking that advice cannot work. That is the diagnostic a hand-writing author still meets; it lands in packages/spec and is not addressed here.

The hot-file fence held — the migration codegen field-type switch region of generate.ts is untouched.

Verification

• pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/generate-scaffold-validates.test.ts → 14/14, on c19eb73310.
• The full derived gate family union for this change set (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, 36 families) ran on that head. See the report comment on objectstack generate scaffolds a flow that objectstack validate rejects — the trigger key and the events vocabulary do not exist on protocol 17 #14087 for the per-gate exit codes, including the two that report NOT MEASURED by their own exit-3 prerequisite branch rather than a verdict.
• pnpm lint (repo-wide eslint . --no-inline-config, no narrowing) → exit 0 in 1m54s.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/data-flow.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/api/plugin-endpoints.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/approvals.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/flows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/hooks.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/workflows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/concepts/architecture.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/deployment/cli.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/getting-started/common-patterns.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/kernel/services-checklist.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/protocol/kernel/lifecycle.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/objectql/schema.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• content/docs/releases/v12.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/releases/v17.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• 4 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 — 23 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ced9a1ea7804a217c60bb29584d4759426ab060e — the merge of head c19eb733102eae66df9b6630e330631caebd3c5b into base e854a531abc9ee81264a17d0e0b1f41b38f6f03e, 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 ced9a1ea7804a217c60bb29584d4759426ab060e && git checkout ced9a1ea7804a217c60bb29584d4759426ab060e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e854a531abc9ee81264a17d0e0b1f41b38f6f03e c19eb733102eae66df9b6630e330631caebd3c5b && git checkout -B drift-repro e854a531abc9ee81264a17d0e0b1f41b38f6f03e && git merge --no-ff c19eb733102eae66df9b6630e330631caebd3c5b
node scripts/docs-audit/affected-docs.mjs --json e854a531abc9ee81264a17d0e0b1f41b38f6f03e

⚠️ 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-trump]

Fixes#14087

The defect, reproduced before anything was edited

os g flow my_flow wrote a file os validate refused. Measured on origin/maind63c8a2, scaffolded for the name probe_thing and put through the same steps Validate.run() performs — four refusals in one parse, verbatim:

flows.0.nodes.0.label: Invalid input: expected string, received undefined
flows.0.nodes.0: Unrecognized key(s) on this flow node: `name`, `next`.
flows.0.edges: Invalid input: expected array, received undefined
flows.0: Unrecognized key(s) on this flow: `trigger`. Did you mean `trigger` → `type`?

Both halves of the card hold, and the measurement adds a third the card did not name: edges is a REQUIRED key on FlowSchema and the template emitted none. The scaffold also declared one node and pointed its next at a node it never wrote.

The fix

packages/cli/src/commands/generate.ts, the flow template only. The trigger binding moves to where AutomationEngine.resolveTriggerBinding actually reads it — the START node's config:

type: 'record_change',status: 'draft',nodes: [{id: 'start',type: 'start',label: 'Start',config: {objectName: 'probe_thing',triggerType: 'record-after-write'}},{id: 'end',type: 'end',label: 'End'},],edges: [{id: 'e1',source: 'start',target: 'end',type: 'default'}],

The card's spelling of the vocabulary was checked rather than copied: record-after-write is real (it is VALID_RECORD_TRIGGER's grammar in packages/lint/src/validate-flow-trigger-readiness.ts, and 'write' is the create-OR-update token from #3427), while events: ['after_insert', …] exists nowhere on the current surface. type moves from 'autolaunched' to 'record_change' because that is what the retired trigger.type block declared this flow to be, and it is the declaration rule 1f gates.

status deliberately stays 'draft'. Arming is the author's decision and os validate says so in an advisory; changing it would move the runtime behaviour of every generated app, which is outside what this card claims.

Measured on the fixed scaffold: 0 error-severity findings, 2 advisories — flow-trigger-unknown-object (the objectName placeholder is not an object the fresh stack defines — the prompt to replace it) and flow-draft-status-ambiguous (the status decision above). os validate exits 0.

The scaffold-validates test

packages/cli/test/generate-scaffold-validates.test.ts. It loads each scaffold the way os validate loads authored TypeScript — through bundle-require with BUNDLE_REQUIRE_EXTERNALS, the same call loadConfig makes — and then re-runs the two steps Validate.run() performs on the result: normalizeStackInput + the unknown-key lints + ObjectStackDefinitionSchema.safeParse, then runAuthoringRules('validate') gating on the error half.

Both layers are load-bearing, and the second is the half a schema-only assertion would miss: a flow node's config is an OPEN slot by design (ADR-0018), so FlowSchema cannot judge the trigger vocabulary at all. A start node carrying triggerType: 'record_change' parses green and is caught one layer later by validate-flow-trigger-readiness. Asserting the schema alone would let this scaffold's own trigger token drift back to a spelling that never fires.

Nothing in the file is restated: the roster comes from GENERATOR_SCAFFOLD_TARGETS (built from GENERATORS itself, now carrying each entry's generate), and the stack collection each artifact lands in comes from singularToPlural — the map defineStack and the metadata registry already share. A generator added tomorrow is measured on the day it lands.

Red-first, then ablated

• RED — the test at its final content, against the unmodified template: Tests 2 failed | 12 passed (14), failing with exactly the four refusals quoted above.
• GREEN after the template fix: Tests 14 passed (14).
• ABLATION, from the committed state: the START node's label: 'Start' mutated to name: 'Start'. Mutation confirmed on disk in both directions (injected 1, original 0) and by blob hash (3dae1933 → fbd28caf); the mutated tree fails 2/14. Restored with git checkout HEAD -- ABSOLUTE_PATH, proven by git diff HEAD empty plus the blob hash back at 3dae1933; restored tree 14/14. No rebuild leg is owed on either side: the test resolves the template through a relative ../src/… path vitest transforms from source, so the dist/ staleness hazard does not apply to this pair. The script carried a trap … EXIT INT TERM restore throughout.

Out of scope, filed rather than fixed

Running the derived roster is how it emerged that flow is not the only refused scaffold. Same harness, same commit: object parses and then fails security-owd-unset; view, action and app fail the parse for reasons of their own; dashboard and skill are clean. Triage fenced that census out of this card, so it is #14336 and is not touched here.

The four are recorded in the new test's KNOWN_UNVALIDATED_SCAFFOLDS — shrink-only, in the shape this repo uses elsewhere, with an anti-staleness assertion: a kind IN the ledger must still FAIL, so whoever repairs one turns this test red and deletes its entry in the same PR. It can never grow to cover a regression, because a newly-broken kind is not in it and simply fails. flow is additionally asserted absent from the ledger, so this card's own defect cannot be re-admitted by adding a line to a table.

#14337 is the other finding: FlowSchema's trigger alias prescribes a rename to type, and taking that advice cannot work. That is the diagnostic a hand-writing author still meets; it lands in packages/spec and is not addressed here.

The hot-file fence held — the migration codegen field-type switch region of generate.ts is untouched.

Verification

• pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/generate-scaffold-validates.test.ts → 14/14, on c19eb73310.
• The full derived gate family union for this change set (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, 36 families) ran on that head. See the report comment on objectstack generate scaffolds a flow that objectstack validate rejects — the trigger key and the events vocabulary do not exist on protocol 17 #14087 for the per-gate exit codes, including the two that report NOT MEASURED by their own exit-3 prerequisite branch rather than a verdict.
• pnpm lint (repo-wide eslint . --no-inline-config, no narrowing) → exit 0 in 1m54s.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/data-flow.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/api/plugin-endpoints.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/approvals.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/flows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/hooks.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/workflows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/concepts/architecture.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/deployment/cli.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/getting-started/common-patterns.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/kernel/services-checklist.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/protocol/kernel/lifecycle.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/objectql/schema.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• content/docs/releases/v12.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/releases/v17.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• 4 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 — 23 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ced9a1ea7804a217c60bb29584d4759426ab060e — the merge of head c19eb733102eae66df9b6630e330631caebd3c5b into base e854a531abc9ee81264a17d0e0b1f41b38f6f03e, 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 ced9a1ea7804a217c60bb29584d4759426ab060e && git checkout ced9a1ea7804a217c60bb29584d4759426ab060e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e854a531abc9ee81264a17d0e0b1f41b38f6f03e c19eb733102eae66df9b6630e330631caebd3c5b && git checkout -B drift-repro e854a531abc9ee81264a17d0e0b1f41b38f6f03e && git merge --no-ff c19eb733102eae66df9b6630e330631caebd3c5b
node scripts/docs-audit/affected-docs.mjs --json e854a531abc9ee81264a17d0e0b1f41b38f6f03e

⚠️ 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-trump]

Fixes#14087

The defect, reproduced before anything was edited

os g flow my_flow wrote a file os validate refused. Measured on origin/maind63c8a2, scaffolded for the name probe_thing and put through the same steps Validate.run() performs — four refusals in one parse, verbatim:

flows.0.nodes.0.label: Invalid input: expected string, received undefined
flows.0.nodes.0: Unrecognized key(s) on this flow node: `name`, `next`.
flows.0.edges: Invalid input: expected array, received undefined
flows.0: Unrecognized key(s) on this flow: `trigger`. Did you mean `trigger` → `type`?

Both halves of the card hold, and the measurement adds a third the card did not name: edges is a REQUIRED key on FlowSchema and the template emitted none. The scaffold also declared one node and pointed its next at a node it never wrote.

The fix

packages/cli/src/commands/generate.ts, the flow template only. The trigger binding moves to where AutomationEngine.resolveTriggerBinding actually reads it — the START node's config:

type: 'record_change',status: 'draft',nodes: [{id: 'start',type: 'start',label: 'Start',config: {objectName: 'probe_thing',triggerType: 'record-after-write'}},{id: 'end',type: 'end',label: 'End'},],edges: [{id: 'e1',source: 'start',target: 'end',type: 'default'}],

The card's spelling of the vocabulary was checked rather than copied: record-after-write is real (it is VALID_RECORD_TRIGGER's grammar in packages/lint/src/validate-flow-trigger-readiness.ts, and 'write' is the create-OR-update token from #3427), while events: ['after_insert', …] exists nowhere on the current surface. type moves from 'autolaunched' to 'record_change' because that is what the retired trigger.type block declared this flow to be, and it is the declaration rule 1f gates.

status deliberately stays 'draft'. Arming is the author's decision and os validate says so in an advisory; changing it would move the runtime behaviour of every generated app, which is outside what this card claims.

Measured on the fixed scaffold: 0 error-severity findings, 2 advisories — flow-trigger-unknown-object (the objectName placeholder is not an object the fresh stack defines — the prompt to replace it) and flow-draft-status-ambiguous (the status decision above). os validate exits 0.

The scaffold-validates test

packages/cli/test/generate-scaffold-validates.test.ts. It loads each scaffold the way os validate loads authored TypeScript — through bundle-require with BUNDLE_REQUIRE_EXTERNALS, the same call loadConfig makes — and then re-runs the two steps Validate.run() performs on the result: normalizeStackInput + the unknown-key lints + ObjectStackDefinitionSchema.safeParse, then runAuthoringRules('validate') gating on the error half.

Both layers are load-bearing, and the second is the half a schema-only assertion would miss: a flow node's config is an OPEN slot by design (ADR-0018), so FlowSchema cannot judge the trigger vocabulary at all. A start node carrying triggerType: 'record_change' parses green and is caught one layer later by validate-flow-trigger-readiness. Asserting the schema alone would let this scaffold's own trigger token drift back to a spelling that never fires.

Nothing in the file is restated: the roster comes from GENERATOR_SCAFFOLD_TARGETS (built from GENERATORS itself, now carrying each entry's generate), and the stack collection each artifact lands in comes from singularToPlural — the map defineStack and the metadata registry already share. A generator added tomorrow is measured on the day it lands.

Red-first, then ablated

• RED — the test at its final content, against the unmodified template: Tests 2 failed | 12 passed (14), failing with exactly the four refusals quoted above.
• GREEN after the template fix: Tests 14 passed (14).
• ABLATION, from the committed state: the START node's label: 'Start' mutated to name: 'Start'. Mutation confirmed on disk in both directions (injected 1, original 0) and by blob hash (3dae1933 → fbd28caf); the mutated tree fails 2/14. Restored with git checkout HEAD -- ABSOLUTE_PATH, proven by git diff HEAD empty plus the blob hash back at 3dae1933; restored tree 14/14. No rebuild leg is owed on either side: the test resolves the template through a relative ../src/… path vitest transforms from source, so the dist/ staleness hazard does not apply to this pair. The script carried a trap … EXIT INT TERM restore throughout.

Out of scope, filed rather than fixed

Running the derived roster is how it emerged that flow is not the only refused scaffold. Same harness, same commit: object parses and then fails security-owd-unset; view, action and app fail the parse for reasons of their own; dashboard and skill are clean. Triage fenced that census out of this card, so it is #14336 and is not touched here.

The four are recorded in the new test's KNOWN_UNVALIDATED_SCAFFOLDS — shrink-only, in the shape this repo uses elsewhere, with an anti-staleness assertion: a kind IN the ledger must still FAIL, so whoever repairs one turns this test red and deletes its entry in the same PR. It can never grow to cover a regression, because a newly-broken kind is not in it and simply fails. flow is additionally asserted absent from the ledger, so this card's own defect cannot be re-admitted by adding a line to a table.

#14337 is the other finding: FlowSchema's trigger alias prescribes a rename to type, and taking that advice cannot work. That is the diagnostic a hand-writing author still meets; it lands in packages/spec and is not addressed here.

The hot-file fence held — the migration codegen field-type switch region of generate.ts is untouched.

Verification

• pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/generate-scaffold-validates.test.ts → 14/14, on c19eb73310.
• The full derived gate family union for this change set (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, 36 families) ran on that head. See the report comment on objectstack generate scaffolds a flow that objectstack validate rejects — the trigger key and the events vocabulary do not exist on protocol 17 #14087 for the per-gate exit codes, including the two that report NOT MEASURED by their own exit-3 prerequisite branch rather than a verdict.
• pnpm lint (repo-wide eslint . --no-inline-config, no narrowing) → exit 0 in 1m54s.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/data-flow.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/api/plugin-endpoints.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/approvals.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/flows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/hooks.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/workflows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/concepts/architecture.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/deployment/cli.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/getting-started/common-patterns.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/kernel/services-checklist.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/protocol/kernel/lifecycle.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/objectql/schema.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• content/docs/releases/v12.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/releases/v17.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• 4 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 — 23 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ced9a1ea7804a217c60bb29584d4759426ab060e — the merge of head c19eb733102eae66df9b6630e330631caebd3c5b into base e854a531abc9ee81264a17d0e0b1f41b38f6f03e, 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 ced9a1ea7804a217c60bb29584d4759426ab060e && git checkout ced9a1ea7804a217c60bb29584d4759426ab060e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e854a531abc9ee81264a17d0e0b1f41b38f6f03e c19eb733102eae66df9b6630e330631caebd3c5b && git checkout -B drift-repro e854a531abc9ee81264a17d0e0b1f41b38f6f03e && git merge --no-ff c19eb733102eae66df9b6630e330631caebd3c5b
node scripts/docs-audit/affected-docs.mjs --json e854a531abc9ee81264a17d0e0b1f41b38f6f03e

⚠️ 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-trump]

Fixes#14087

The defect, reproduced before anything was edited

os g flow my_flow wrote a file os validate refused. Measured on origin/maind63c8a2, scaffolded for the name probe_thing and put through the same steps Validate.run() performs — four refusals in one parse, verbatim:

flows.0.nodes.0.label: Invalid input: expected string, received undefined
flows.0.nodes.0: Unrecognized key(s) on this flow node: `name`, `next`.
flows.0.edges: Invalid input: expected array, received undefined
flows.0: Unrecognized key(s) on this flow: `trigger`. Did you mean `trigger` → `type`?

Both halves of the card hold, and the measurement adds a third the card did not name: edges is a REQUIRED key on FlowSchema and the template emitted none. The scaffold also declared one node and pointed its next at a node it never wrote.

The fix

packages/cli/src/commands/generate.ts, the flow template only. The trigger binding moves to where AutomationEngine.resolveTriggerBinding actually reads it — the START node's config:

type: 'record_change',status: 'draft',nodes: [{id: 'start',type: 'start',label: 'Start',config: {objectName: 'probe_thing',triggerType: 'record-after-write'}},{id: 'end',type: 'end',label: 'End'},],edges: [{id: 'e1',source: 'start',target: 'end',type: 'default'}],

The card's spelling of the vocabulary was checked rather than copied: record-after-write is real (it is VALID_RECORD_TRIGGER's grammar in packages/lint/src/validate-flow-trigger-readiness.ts, and 'write' is the create-OR-update token from #3427), while events: ['after_insert', …] exists nowhere on the current surface. type moves from 'autolaunched' to 'record_change' because that is what the retired trigger.type block declared this flow to be, and it is the declaration rule 1f gates.

status deliberately stays 'draft'. Arming is the author's decision and os validate says so in an advisory; changing it would move the runtime behaviour of every generated app, which is outside what this card claims.

Measured on the fixed scaffold: 0 error-severity findings, 2 advisories — flow-trigger-unknown-object (the objectName placeholder is not an object the fresh stack defines — the prompt to replace it) and flow-draft-status-ambiguous (the status decision above). os validate exits 0.

The scaffold-validates test

packages/cli/test/generate-scaffold-validates.test.ts. It loads each scaffold the way os validate loads authored TypeScript — through bundle-require with BUNDLE_REQUIRE_EXTERNALS, the same call loadConfig makes — and then re-runs the two steps Validate.run() performs on the result: normalizeStackInput + the unknown-key lints + ObjectStackDefinitionSchema.safeParse, then runAuthoringRules('validate') gating on the error half.

Both layers are load-bearing, and the second is the half a schema-only assertion would miss: a flow node's config is an OPEN slot by design (ADR-0018), so FlowSchema cannot judge the trigger vocabulary at all. A start node carrying triggerType: 'record_change' parses green and is caught one layer later by validate-flow-trigger-readiness. Asserting the schema alone would let this scaffold's own trigger token drift back to a spelling that never fires.

Nothing in the file is restated: the roster comes from GENERATOR_SCAFFOLD_TARGETS (built from GENERATORS itself, now carrying each entry's generate), and the stack collection each artifact lands in comes from singularToPlural — the map defineStack and the metadata registry already share. A generator added tomorrow is measured on the day it lands.

Red-first, then ablated

• RED — the test at its final content, against the unmodified template: Tests 2 failed | 12 passed (14), failing with exactly the four refusals quoted above.
• GREEN after the template fix: Tests 14 passed (14).
• ABLATION, from the committed state: the START node's label: 'Start' mutated to name: 'Start'. Mutation confirmed on disk in both directions (injected 1, original 0) and by blob hash (3dae1933 → fbd28caf); the mutated tree fails 2/14. Restored with git checkout HEAD -- ABSOLUTE_PATH, proven by git diff HEAD empty plus the blob hash back at 3dae1933; restored tree 14/14. No rebuild leg is owed on either side: the test resolves the template through a relative ../src/… path vitest transforms from source, so the dist/ staleness hazard does not apply to this pair. The script carried a trap … EXIT INT TERM restore throughout.

Out of scope, filed rather than fixed

Running the derived roster is how it emerged that flow is not the only refused scaffold. Same harness, same commit: object parses and then fails security-owd-unset; view, action and app fail the parse for reasons of their own; dashboard and skill are clean. Triage fenced that census out of this card, so it is #14336 and is not touched here.

The four are recorded in the new test's KNOWN_UNVALIDATED_SCAFFOLDS — shrink-only, in the shape this repo uses elsewhere, with an anti-staleness assertion: a kind IN the ledger must still FAIL, so whoever repairs one turns this test red and deletes its entry in the same PR. It can never grow to cover a regression, because a newly-broken kind is not in it and simply fails. flow is additionally asserted absent from the ledger, so this card's own defect cannot be re-admitted by adding a line to a table.

#14337 is the other finding: FlowSchema's trigger alias prescribes a rename to type, and taking that advice cannot work. That is the diagnostic a hand-writing author still meets; it lands in packages/spec and is not addressed here.

The hot-file fence held — the migration codegen field-type switch region of generate.ts is untouched.

Verification

• pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/generate-scaffold-validates.test.ts → 14/14, on c19eb73310.
• The full derived gate family union for this change set (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, 36 families) ran on that head. See the report comment on objectstack generate scaffolds a flow that objectstack validate rejects — the trigger key and the events vocabulary do not exist on protocol 17 #14087 for the per-gate exit codes, including the two that report NOT MEASURED by their own exit-3 prerequisite branch rather than a verdict.
• pnpm lint (repo-wide eslint . --no-inline-config, no narrowing) → exit 0 in 1m54s.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/data-flow.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/api/plugin-endpoints.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/approvals.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/flows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/hooks.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/automation/workflows.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/concepts/architecture.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/deployment/cli.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/getting-started/common-patterns.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/kernel/services-checklist.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/protocol/kernel/lifecycle.mdx(via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/objectql/schema.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• content/docs/releases/v12.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))
• content/docs/releases/v17.mdx(via record_change (literal, a string literal in trigger; a string literal on a changed line))

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

• 4 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 — 23 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ced9a1ea7804a217c60bb29584d4759426ab060e — the merge of head c19eb733102eae66df9b6630e330631caebd3c5b into base e854a531abc9ee81264a17d0e0b1f41b38f6f03e, 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 ced9a1ea7804a217c60bb29584d4759426ab060e && git checkout ced9a1ea7804a217c60bb29584d4759426ab060e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e854a531abc9ee81264a17d0e0b1f41b38f6f03e c19eb733102eae66df9b6630e330631caebd3c5b && git checkout -B drift-repro e854a531abc9ee81264a17d0e0b1f41b38f6f03e && git merge --no-ff c19eb733102eae66df9b6630e330631caebd3c5b
node scripts/docs-audit/affected-docs.mjs --json e854a531abc9ee81264a17d0e0b1f41b38f6f03e

⚠️ 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 e854a531abc9ee81264a17d0e0b1f41b38f6f03e → pass the list as
args.docs, on the commit named under Which tree this was computed on.