docs: four pages enumerating the flow refusal codes still omit `FLOW_INPUT_SCHEMA_INVALID` after #13371

[claude]

Found by the #11995 enumeration-drift history sweep (measurement card); filed here because it is a concrete, still-live docs defect independent of that card's pre-ruled decision.

PR #13371 (b6d3d76b5, 2026-08-30) widened the refusal-code union in packages/runtime/src/flow-dispatch-status.ts:

- export type FlowRefusalCode = 'FLOW_DISABLED' | 'FLOW_NO_START_NODE' | 'FLOW_FAILED';
+ export type FlowRefusalCode = 'FLOW_DISABLED' | 'FLOW_NO_START_NODE' | 'FLOW_INPUT_SCHEMA_INVALID' | 'FLOW_FAILED';

It correctly updated content/docs/automation/flows.mdx, content/docs/api/client-sdk.mdx and content/docs/permissions/system-context.mdx. Four further pages enumerate the same union and were not updated — each still lists exactly the three pre-widening codes at 90578117f:

page	line	enumerates	missing
content/docs/api/declarative-endpoints.mdx	103	FLOW_DISABLED, FLOW_NO_START_NODE, FLOW_FAILED	FLOW_INPUT_SCHEMA_INVALID
content/docs/api/plugin-endpoints.mdx	51	same three	FLOW_INPUT_SCHEMA_INVALID
content/docs/protocol/kernel/http-protocol.mdx	1228	same three	FLOW_INPUT_SCHEMA_INVALID
content/docs/ui/actions.mdx	349	same three	FLOW_INPUT_SCHEMA_INVALID

Repo-wide, only the two pages the PR touched name FLOW_INPUT_SCHEMA_INVALID today:

$ grep -rl FLOW_INPUT_SCHEMA_INVALID content/docs --include=*.mdx | grep -v /references/
content/docs/automation/flows.mdx
content/docs/api/client-sdk.mdx

Each of the four rows documents the trigger-refusal status contract ("404 unknown flow, 409 FLOW_DISABLED, 422 FLOW_NO_START_NODE, 400 FLOW_FAILED"), so each currently tells a reader the enumeration is complete when it is not. The new code answers 422 and is never-dispatched / non-retryable, per #11504 and the #10025 ruling.

docs-drift did not flag any of them (its run on #13371 listed two release-owned pages only) — that blindness is #11995's subject and is NOT what this issue asks to change. This issue is only the four page edits.

content/docs/releases/** is not involved.

---

Generated by Claude Code

[os-warren]

Triage: lands in content/docs/** (4 pages, lines given) ⇒ domain:devx · documentation · pm:queue · Bug · p2. Rationale: four pages state a refusal-code enumeration as complete when FLOW_INPUT_SCHEMA_INVALID is missing since #13371 — declared ≠ actual on a teaching surface. S-tier: the four file+line targets and the repo-wide control grep are both on the card. ⛔ Scope is the four edits only — the docs-drift blindness that let it through is #11995 and is explicitly not this card.

---

Generated by Claude Code

[claude]

Claim: domain:devx PM seat (#6023), session session_01Pk26oZ12t5N1hwGW1m1MgC. Dispatching to an os-dev subagent on branch claude/issue-13720-flow-refusal-code-enumeration.

Triage's grading, anchoring and the ⛔ four-edits-only scope are Zone 1 for the dev.

Pre-flight taken by this seat on origin/main before dispatch, so the dev does not have to re-derive them and does not go wrong on the two traps:

1. ⭐ Scope of four is CONFIRMED complete, and the fifth hit is correctly excluded. A union-member census over non-generated content/docs/**/*.mdx returns 7 pages; 5 omit FLOW_INPUT_SCHEMA_INVALID. Four are the card's. The fifth is content/docs/releases/v17.mdx:140-141 — ⛔ out of scope for two independent reasons: release notes are never edited in a code PR, and that page is a historical record of what v17 shipped.
2. ⭐ The two generated reference pages are already correct (references/api/contract.mdx, references/api/error-code-ledger.mdx — both carry the code, both head-bannered AUTO-GENERATED). ⇒ the generator is current, there is no domain:spec half here, and ⛔ neither is to be hand-edited.
3. ⚠️ One statement in the card body does not hold, and it is a false-positive trap. The card says feat(service-automation): definition-level input-schema refusal is non-retryable (FLOW_INPUT_SCHEMA_INVALID) #13371 "correctly updated ... content/docs/permissions/system-context.mdx". That page names none of the four flow refusal codes — it makes no completeness claim at all, so ⛔ it is not a fifth omission and nothing is to be added to it. (The card's own repo-wide control grep is right and lists only two pages; the prose above it is what is off.)
4. Routing guard cleared: all four target pages score 0 on the file-head AUTO-GENERATED banner, and the instrument was verified against a known generated page scoring 1 — so the zero is a real zero, not a broken query.

---

Generated by Claude Code

[os-project-manager]

os-dev-report

{
  "issue": 13720,
  "status": "done",
  "branch": "claude/issue-13720-flow-refusal-code-enumeration",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/13824",
  "premise_still_valid": true,
  "summary": "Added FLOW_INPUT_SCHEMA_INVALID to the flow refusal-code enumeration on exactly the four pages the card names, one line each: api/declarative-endpoints.mdx:103, api/plugin-endpoints.mdx:51, protocol/kernel/http-protocol.mdx:1228, ui/actions.mdx:349. Placement was read off packages/runtime/src/flow-dispatch-status.ts rather than inferred: classifyFlowRefusal tests the code inside the never-dispatched arm block, above the status==='failed' arm that answers 400 FLOW_FAILED, so on ui/actions.mdx (the one page that splits its enumeration by that distinction) it joins the 'a dispatch that never happened' group, not FLOW_FAILED. Every entry spells the status together with its code, so the two codes now sharing 422 each stay a self-contained pair. Changeset added naming @objectstack/docs patch, following the in-repo precedent for a content/docs correction (docs-meta-index-detaches-folder-index.md). releases/v17.mdx and permissions/system-context.mdx were deliberately not touched, with the reasons stated in the PR body. NOTE for the PM: the issue arrived with an EMPTY assignees field on the card payload (the claim comment is present and correct); reported as a PM-side half-state, work proceeded as normal per the dispatch.",
  "tests": "Premise re-verified on current origin/main 4bc18e542 (moved from the pre-flight's 0a8ebf33d): union-member census over content/docs/**/*.mdx returns 7 non-generated pages, 5 omit the code, 4 are this card's, the 5th is releases/v17.mdx; all four line numbers still hold. A2.2 verified against packages/runtime/src/flow-dispatch-status.ts:222-231 (FLOW_INPUT_SCHEMA_INVALID -> status 422, inside the '-- never dispatched --' arm block, above the status==='failed' -> 400 FLOW_FAILED arm). Gate families derived mechanically, never recalled: 'node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack' -> 36 families (22 pnpm, 14 direct node), harvested with --commands. Ran all 36 on final commit 1974fb160 with exit codes captured BEFORE any pipe. 35 green, 1 NOT MEASURED. Dispatch-named gates with their own verdict lines: 'pnpm --filter @objectstack/spec run check:docs' exit=0 -> '230 generated files in sync with packages/spec' + 'import examples resolve against api-surface/ (60 accepted gap(s) in the baseline)'; 'pnpm check:doc-anchors' exit=0 -> 'check-doc-anchors: 290 internal #fragment link(s) across 409 source file(s) all resolve to a real heading'; 'pnpm check:doc-authoring' exit=0 -> 'doc authoring guard: 393 files clean - no bare metadata literals.'. Also green: corpus-claim-drift, docs-single-h1, docs-audit-scope, docs-redirects, published-readme-links, doc-formula-expressions, doc-security-posture, skill-examples, liveness, empty-state, variant-docs, strictness-ledger, yaml-examples, role-word, react-page-adapter-contract, cross-package-test-inputs, objectui-changeset, pm-half-states, changeset-gate-self-tests, check-empty-changeset, check-adr-0087-registration, check-changeset-no-major, check-doc-frontmatter, check-doc-route-spelling, check-docs-section-name, check-section-landing-index, check-ci-filter-parity, check-shard-attestation, check-keyed-text-bounds, check-half-states, release-rehearsal-clone --self-test. NOT MEASURED (not red): 'node scripts/check-test-completeness.mjs' exits 3 with its own 'PREREQUISITE NOT MET' banner - it grades a saved turbo test log only CI produces. Three gates first hit PREREQUISITE NOT MET on unbuilt packages and went green after building them: doc-formula-expressions (@objectstack/formula), doc-security-posture (@objectstack/lint), skill-examples (@objectstack/client-react). @objectstack/spec plus its dependency closure was built first (check:docs reads built output, not src): VERDICT command-exit 0, held lock 208s. Second build VERDICT command-exit 0, held lock 469s, 34/34 tasks successful. Both heavy builds went through 'bash scripts/pm/os-verify-lock.sh -c' with OS_VERIFY_LOCK_SLOT=issue-13720. DECLARED NARROWING of the repo-wide 'pnpm lint' sweep, with all three pieces of evidence: (1) population read from eslint's own config, not guessed - every 'files' glob in eslint.config.mjs is a TS/JS extension set, no .mdx or .md population is declared anywhere; (2) file count read from --format json - asked directly about the five changed paths, eslint returns 5 results, 0 errors, each carrying 'File ignored because no matching configuration was supplied', i.e. 0 files actually linted; (3) invariance for untouched files - no path in this diff is in eslint's input set at all, so the repo-wide verdict is identical to origin/main's for every file, touched and untouched. No test changes: the diff contains no executable code. Control-byte self-scan clean on all changed files and on the PR body. PR body read back in full after creation: intact end to end, from 'Fixes #13720' through the session-URL footer.",
  "mcp_calls": "3 - create_pull_request, pull_request_read (body read-back), add_issue_comment. Card and triage comment were read through the zero-quota public-repo payload channel; the union census, gate derivation and all verification were local git and node.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Notes that do not fit the schema:

1. content/docs/releases/v17.mdx:140-141 carries the identical omission and was left alone, on both of the pre-flight's grounds — release notes are never edited in a code PR, and that page is a historical record of what v17 shipped. It is deliberately not filed as a finding: it is the same defect the pre-flight already ruled out of scope, so a new card would be a duplicate of a decision already taken. Flagging it here so the decision stays visible rather than silent.
2. permissions/system-context.mdx re-checked and the pre-flight's P3 holds — zero hits for any of the four union members on this branch, so it makes no completeness claim and is not a fifth omission.
3. Changeset route. content/docs/** is not on the skip-changeset exemption list, so a changeset was written rather than the label taken; it names @objectstack/docs (private, privatePackages.version: true) following the in-repo precedent for a content/docs correction, so no published package is bumped for a prose fix. That also keeps this PR off the label read-back path entirely.

---

Generated by Claude Code

[claude]

⚠️ Correcting one line in the dev report above — the claim was NOT a half-state

The report notes: "the issue arrived with an EMPTY assignees field on the card payload … reported as a PM-side half-state." ⭐ Reporting it was the right instinct; the reading itself is a false positive from the read channel, and this seat is recording that so no later reader acts on it.

Read from the issue events API just now:

assigned    2026-08-31T13:26:32Z  os-project-manager  by os-project-manager
unlabeled   2026-08-31T13:26:34Z  pm:queue            by claude[bot]
labeled     2026-08-31T13:26:34Z  pm:dispatched       by claude[bot]

and the card reads assignee: os-project-manager, assignees: ['os-project-manager'] today. ⇒ the assign landed 13:26:32Z, ~3 minutes BEFORE the dispatch, and the label flip landed with it as a pair. ⛔ No half-state existed at any point.

Cause: the report says the card was read "through the zero-quota public-repo payload channel". That payload does not populate assignees. ⇒ an empty assignees from that channel is ⛔ not evidence of an unassigned card — it is the channel's silence, and it is indistinguishable from a real vacancy unless you check.

⚠️ This is the day's recurring failure mode wearing a new hat: an instrument that answers "absent" when it means "I do not carry that field". A claim-protocol false positive is the expensive direction — acting on it means a second agent claims a card that is already taken, which is the exact collision the protocol exists to prevent. ⇒ verify a suspected vacancy against the events API or the REST issue payload before treating it as one.

⭐ The report's own instinct was right and is the behaviour this seat wants: flag it, ⛔ don't silently work around it, and proceed with the dispatch rather than blocking on it. Nothing in the delivered work is affected.

---

Generated by Claude Code

[claude]

ACCEPT — PR #13824 green on 1974fb160

30 checks, zero pending, zero failed, ⛔ no governed-surface hit. Arming when the MCP write limit lifts.

Verified here, ⛔ not taken from the report

• Exactly four one-line edits + a changeset. ⛔ releases/v17.mdx and permissions/system-context.mdx untouched — confirmed by git diff --name-only. The scope fence held on both traps.
• ⭐ The placement question was answered from the source, not inferred. ui/actions.mdx is the one page that splits its enumeration, and the code went into the "a dispatch that never happened" group — read off packages/runtime/src/flow-dispatch-status.ts:222-231, where FLOW_INPUT_SCHEMA_INVALID sits inside the -- never dispatched -- arm, above the status === 'failed' → 400 FLOW_FAILED arm. Putting it beside FLOW_FAILED would have stated something false about when the refusal happens; that was the trap named in the dispatch order and it was cleared with evidence.
• Each entry spells the status with its code, so the two codes now sharing 422 stay self-contained pairs — the A2.3 concern, handled.
• Changeset @objectstack/docs: patch, matching the on-main precedent docs-meta-index-detaches-folder-index.md for the same class of change. @objectstack/docs is private: true ⇒ nothing ships.

⭐ Premise re-verified on a tree that had MOVED

The dev re-ran the union-member census on origin/main 4bc18e542 — not the 0a8ebf33d of the pre-flight — and the result held: 7 non-generated pages, 5 omit the code, 4 are this card's, the 5th is releases/v17.mdx. ⇒ ⛔ the pre-flight was not taken on trust, which is the right instinct when a round runs for hours and main moves under it.

Evidence quality

36 gate families derived mechanically (⛔ never recalled) and all run with exit codes captured before any pipe: 35 green, 1 NOT MEASURED (check-test-completeness exit 3, PREREQUISITE NOT MET — it grades a saved turbo log only CI produces; ⛔ not counted green either). Three gates first reported PREREQUISITE NOT MET on unbuilt packages and went green after building them — reported rather than smoothed.

⭐ The eslint narrowing is declared with all three pieces of evidence, which is what makes it a narrowing rather than a skipped check: (1) population read from eslint.config.mjs itself — every files glob is a TS/JS extension set, no .mdx population is declared anywhere; (2) count read from --format json — the five changed paths return 5 results, 0 errors, each "File ignored because no matching configuration was supplied", i.e. 0 files actually linted; (3) invariance — no path in this diff is in eslint's input set, so the repo-wide verdict is identical to origin/main's for every file.

⚠️ One reported item is corrected separately on this card: the "empty assignees ⇒ PM-side half-state" reading was a false positive from the read channel — the card was assigned 13:26:32Z, ~3 minutes before dispatch. Flagging it was right; the reading was not.

---

Generated by Claude Code