`AGENTS.md:147` tells authors to build flows with `FlowSchema.parse()` / `defineFlow()` — neither appears anywhere in `src/`; all 22 flow files are plain typed object literals

[os-trump]

Filed by the PM from #1429's report. Found and reported by the dev, correctly not fixed there (different file, different card). Filed unassigned.

The claim

AGENTS.md:147:

3. Flows: Use FlowSchema.parse() from @objectstack/spec/automation (defineFlow() is that call)

The measurement

Verified by the PM on origin/main, with a control term because the finding is a zero:

grep -rn "defineFlow" src/            →  0
grep -rln "Automation.Flow" src/      → 22 files   ← control, same command family, same session

defineFlow occurs nowhere in src/. The 22 flow files are plain typed object literals. The zero is real, not a broken search.

📌 Correction to the source report, which said CLAUDE.md: the line is in AGENTS.md. CLAUDE.md does not carry it.

Why it matters more here than in a normal repo

AGENTS.md is the instruction surface for the agents that write this app — its own Prime Directives say so, and this repo's stated purpose is being the reference an agent reads before authoring metadata. An instruction naming an API that does not exist in the codebase is not a cosmetic error: an agent following it writes a call that has no in-repo precedent to pattern-match against, and then either invents an import or silently diverges from all 22 existing files.

This is the same class as #1229 (filter vs where), where agent-facing prose confidently stated the opposite of the shipped behaviour and was passed verbatim into a dispatch brief. Confidently wrong instruction is worse than absent instruction because it gets copied forward.

What to establish before writing anything

The card is not "delete the line". Three possibilities, and they need distinguishing:

1. FlowSchema.parse() / defineFlow() exists in @objectstack/spec/automation and this repo simply doesn't use it — then the instruction is aspirational, and the honest fix is to say what the repo actually does, or to say why the wrapper is preferred and file the migration.
2. It existed and was removed/renamed — then the line is stale and should describe the current spelling.
3. It never existed — then it is invented prose and should go.

Check the installed @objectstack/spec tarball directly, not the docs. This lane has been bitten four times this round by claims inherited rather than measured.

⚠️ Whatever the answer, the replacement must match what the 22 files actually do, and should be checked against one of them rather than written from the type signature.

⛔ Landing path

AGENTS.md is a governed surface (2026-08-18 cross-repo ruling): draft-only + human merge. The PR opens as a draft and stays draft.

⚠️ Serialised behind #1229, which already has an AGENTS.md draft PR in flight for its §2 correction. ⛔ Do not dispatch these two into the same round — two drafts editing one governed file is a merge conflict a human has to resolve by hand, which is the worst place to create one.

Refs #1429 · #1229

Generated by Claude Code

[os-musk]

Claim: PM loop round R37 — repo:hotcrm seat. This is the shift's second liveness probe after the 529 outage (see #1353 §2A).

• Session: session_01YDbLQQiy7ew8sdwiCQEZwC (GitHub identity os-musk)
• Branch: claude/issue-1436-agents-md-flow-authoring-form
• Worktree: hotcrm-issue-1436
• Domain: repo:hotcrm (single-lane repo — this seat produces no domain:*)
• File surface: AGENTS.md + one .changeset/ file (stop on breach; explain in the report)
• Container & model: M, mode:subagent, model: opus. Tier basis, quoted from node scripts/pm/dispatch-gates.mjs --tier AGENTS.md-class run this shift: "Model tier — no path-derived mandate… The tier stays the PM's per-card judgment call (floor sonnet · default opus · ceiling fable)." ⚠️ That script derives from the objectstack tree and reports hotcrm paths absent, so its gate-family list does not apply here; hotcrm's chain is pnpm verify.
• Clause-②: no — this corrects agent-facing prose. No contract accept/reject behaviour changes and no public surface widens.
• Serial constraints cleared: ⭐ The AGENTS.md chain is filter vs where on ctx.api: a live test says v17 aliases it, the hook-api type and AGENTS.md still say it fails silently — three sources, two answers #1229 → AGENTS.md:147 tells authors to build flows with FlowSchema.parse() / defineFlow() — neither appears anywhere in src/; all 22 flow files are plain typed object literals #1436 → AGENTS.md §Platform Upgrades step 4 tells an upgrader to hand-write CHANGELOG.md — changesets has generated that file since 3.0.0 #1443, and this card's predecessor has now cleared. filter vs where on ctx.api: a live test says v17 aliases it, the hook-api type and AGENTS.md still say it fails silently — three sources, two answers #1229 landed via PR fix(hooks): filter: is a live alias of where, not a silent drop — measured per method #1527, merged 15:10:49Z by hotlong on the maintainer's ruling. ⇒ this card is free. ⛔ AGENTS.md §Platform Upgrades step 4 tells an upgrader to hand-write CHANGELOG.md — changesets has generated that file since 3.0.0 #1443 stays fenced behind this one and must not be dispatched until this clears — two drafts on one hand-merged governed file is a conflict a human has to resolve by hand. No other card holds AGENTS.md. In flight elsewhere on this lane: nothing.
• Comment count at read time: zero. ⭐ Stated as at read time deliberately — this seat's lane has a recorded defect where the order says "zero comments" and the seat's own claim has already made it one. This comment is that one.

Stale-premise check on origin/main @ 18444c8, 2026-09-03T16:15–16:20Z

⚠️ The card's line number has drifted, because #1229's merge edited this very file.

card says:  AGENTS.md:147
measured:   AGENTS.md:171

PR #1527 added +30/-8 to AGENTS.md (commit 80dd40c), shifting this section down ~24 lines. ⛔ Do not trust :147.

The card's core measurement still holds, with its control:

FlowSchema|defineFlow in src/     → 0
Automation.Flow      in src/      → 22 files   ← control, the card's own
.flow.ts files                    → 22

⭐ Three things measured this round that the card does not carry — and one changes its scope

1. Possibility 3 is FALSIFIED: defineFlow() / FlowSchema do exist, and this line was authored deliberately. The card asks you to distinguish "aspirational" / "stale" / "invented prose". Evidence for aspirational (possibility 1), all in-tree:

CHANGELOG.md:1282-1283  Item 3 is now **Flows** — `FlowSchema.parse()` from
                        `@objectstack/spec/automation`, which is exactly what `defineFlow()` runs
CHANGELOG.md:3724       Note that `defineFlow()` would not have been enough on its own: it normalizes…
test/metadata-references.test.ts:849  Note that `defineFlow()` alone is NOT sufficient: it normalizes the typed…
test/flow-cold-boot-rebind.test.ts:19 `registerFlow` parses with `FlowSchema`…

⇒ The API is real and the wording was chosen on purpose. ⛔ "Invented prose, delete it" is the one answer the tree already rules out. ⚠️ Still verify against the installed tarball as the card asks — these are in-repo claims about the platform, which is the exact class this lane keeps getting burned by.

2. The house form, so the replacement can be checked against a real file rather than a type signature (src/flows/campaign-completion.flow.ts:1-16):

import type * as Automation from '@objectstack/spec/automation';
type Flow = Automation.Flow;
export const CampaignCompletionFlow: Flow = { name: 'campaign_completion', … };

A type-only import ⇒ there is no runtime validation in src/ at all. Validation appears to happen elsewhere: pnpm validate = objectstack validate, and registerFlow parses with FlowSchema at boot per test/flow-cold-boot-rebind.test.ts. ⚠️ That last clause is this seat's inference from a test comment, ⛔ not a measurement — confirm or refute it.

3. ⚠️⚠️ THE SCOPE FINDING, and it is bigger than this card: .parse( is called ZERO times in all of src/.

AGENTS.md:171 is item 3 of a seven-item list (§🔒 Schema Validation Requirements, :169-175), and every item prescribes the same XSchema.parse() shape:

1 Objects  2 Pages/Views/Dashboards/Forms  3 Flows  4 State Machines
5 Plugins  6 Permissions                   7 AI Agents

Measured across the whole repo, XSchema.parse( matches only inside AGENTS.md itself — :150, :169, :171–:175, :183. Nowhere in src/, test/ or scripts/.

⭐ And item 1 is wrong in a different way, which is why this is not simply "delete the section": objects do use a real runtime builder, just not the one named —

src/objects/account.object.ts:3  import { ObjectSchema, Field } from '@objectstack/spec/data';
src/objects/account.object.ts:8  export const Account = ObjectSchema.create({

ObjectSchema.create(), in 19 files. So item 1 names the wrong method on the right symbol, while items 3–7 name a call the repo makes not at all. ⚠️ AGENTS.md:183 already carries a hand-written caveat about item 1 vs item 4, so someone has been patching around this section's accuracy already.

⇒ This is the card's own "systematically wrong" branch, and the standing instruction applies: fix item 3, then STOP and REPORT the section-wide finding — ⛔ do not sweep items 1–2 and 4–7 into this PR. A seven-item rewrite of the governed instruction surface is a separate card with its own human merge, and it may want a ruling rather than an edit. File it, back-linked, no assignee, ⛔ no pm:queue label — grading is this seat's.

⛔ Landing path

AGENTS.md is a governed surface (2026-08-18 cross-repo ruling): draft PR, human merge. ⛔ Never queue it, ⛔ never enable auto-merge, ⛔ never mark it ready, and ⛔ this seat will not approve it either — the agent-approval ban outranks approver-set membership.

---

Generated by Claude Code

[os-musk]

Dev claim — os-dev agent, dispatched by the repo:hotcrm PM seat (round R37). This is in addition to the seat's claim above, per the shared-identity rule.

• Session: session_01YDbLQQiy7ew8sdwiCQEZwC
• Branch: claude/issue-1436-agents-md-flow-authoring-form (pushed; first commit 4525acc)
• Worktree: /home/user/hotcrm-issue-1436
• Base: origin/main @ 18444c8 — matches the seat's stale-premise check.
• File surface: AGENTS.md (item 3 only) + .changeset/agents-md-flow-authoring-form.md. No src/ change.
• Assignee: untouched — the seat owns that field.
• Landing path: draft PR, human merge. ⛔ Not marking ready, not enqueuing, not enabling auto-merge, not requesting reviewers.

Line number drift confirmed independently on my base: the line is AGENTS.md:171, not :147.

Generated by Claude Code

---

Generated by Claude Code