docs(agents): 把 Schema Validation 清单第 3 条指向真实存在的 schema (#852)

.changeset/agents-md-schema-list.md

@@ -0,0 +1,30 @@
+---
+'hotcrm': patch
+---
+
+Point `AGENTS.md`'s Schema Validation Requirements list at a schema that exists.
+Item 3 told every agent to validate "Workflows" with
+`WorkflowRuleSchema.parse()` from `@objectstack/spec/automation`. That export is
+not there: `WorkflowRule` matches **0 files** across all 52 installed
+`@objectstack/*` packages on 17.0.0-rc.2, while the same grep finds
+`FlowSchema` in 63, `JobSchema` in 46, `StateMachineSchema` in 40 and
+`ApprovalNode` in 30 — the probe works, the symbol is gone (ADR-0019/0020
+retired the `workflow` metadata type; `ObjectSchema` now rejects `workflows:`
+and `workflow:` by name). An agent following the instruction hits an import
+failure and then improvises: hand-rolls a schema, drops validation, or worse
+concludes it should author a `workflows[]` key the platform refuses.
+
+Item 3 is now **Flows** — `FlowSchema.parse()` from
+`@objectstack/spec/automation`, which is exactly what `defineFlow()` runs —
+because the list had no Flows entry at all despite `src/flows/` holding 21
+`*.flow.ts` files. A short note under the list routes the three things people
+call a "workflow" to their real carriers: field updates to `*.hook.ts`, status
+flips and notifications to a `record_change` / `schedule` flow, approvals to an
+`approval` node inside a flow. It also separates them from item 4, since a
+record lifecycle constraint is a `validations[]` entry with
+`type: 'state_machine'` on the object — validated by `ObjectSchema.parse()`,
+not by `StateMachineSchema`, whose shape (`initial` / `states` / `on`) is a
+different thing.
+
+Instruction-file wording only; no `src/**` or `content/**` change. Refs #852,
+#833.

AGENTS.md

@@ -117,12 +117,21 @@ All metadata files MUST be validated against their corresponding `@objectstack/s
 
 1. **Objects**: Use `ObjectSchema.parse()` from `@objectstack/spec/data`
 2. **Pages/Views/Dashboards/Forms**: Use schemas from `@objectstack/spec/ui`
-3. **Workflows**: Use `WorkflowRuleSchema.parse()` from `@objectstack/spec/automation`
+3. **Flows**: Use `FlowSchema.parse()` from `@objectstack/spec/automation` (`defineFlow()` is that call)
 4. **State Machines**: Use `StateMachineSchema.parse()` from `@objectstack/spec/automation`
 5. **Plugins**: Use `PluginSchema.parse()` from `@objectstack/spec/kernel` (remove `: any` annotations)
 6. **Permissions**: Use `PermissionSetSchema.parse()` from `@objectstack/spec/security`
 7. **AI Agents**: Use `AgentSchema.parse()` from `@objectstack/spec/ai`
 
+> **There is no `workflow` metadata type** (ADR-0019/0020): `WorkflowRuleSchema` is not
+> exported by any installed `@objectstack/*` package, and `ObjectSchema` rejects
+> `workflows:` / `workflow:` by name. Field updates belong in `*.hook.ts`; status flips and
+> notifications in a `record_change` / `schedule` flow (item 3); approvals in an `approval`
+> node inside a flow. A record **lifecycle** constraint is not item 4 either — it is a
+> `validations[]` entry with `type: 'state_machine'` on the object, validated by
+> `ObjectSchema.parse()` (item 1); item 4's `StateMachineSchema` is a different shape
+> (`initial` / `states` / `on`) and does not validate that entry.
+
 ## 🏷️ Field Type Guidance
 
 Use the most specific `Field` type available from `@objectstack/spec/data`: