docs(automation): document ADR-0031 control-flow constructs; fix dangling reference card#1497
Merged
Merged
Conversation
- guide (content/docs/guides/metadata/flow.mdx): document the structured loop container, parallel block (implicit join), and try/catch/retry constructs with config examples and the region/DAG-invariant model; update the Node Types table. - doc generator (packages/spec/scripts/build-docs.ts): only emit index Cards for reference pages that were actually generated. control-flow's schemas embed CEL-expression transforms (like Flow/FlowEdge) so produce no JSON-Schema page; the index previously carded every .zod.ts file, yielding a dangling "Control Flow" 404 link. Cards now match meta.json. https://claude.ai/code/session_012ti8cx3TkdiQdjCnZXZg2Q
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
The docs site build (Vercel apps/docs) was failing on every branch off main:
./content/docs/references/kernel/manifest.mdx
Unexpected character `5` (U+0035) before name (MDX)
A zod `.describe()` carries a SemVer range `">=4.0 <5"`; the generator's
`escapeMdxDescription` only wraps `<`/`{` when it finds a matching `>`/`}`, so
the lone `<5` slipped through raw and MDX parsed it as the start of a JSX tag,
failing `next build` for the whole site.
Escape a lone `<`/`{` (no matching close) as inline code. Verified: the full
`apps/docs` build (gen:schema && gen:docs && next build) now compiles and
prerenders all 1089 pages.
https://claude.ai/code/session_012ti8cx3TkdiQdjCnZXZg2Q
…ontrol-flow # Conflicts: # packages/spec/scripts/build-docs.ts
This was referenced Jun 2, 2026
os-zhuang
added a commit
that referenced
this pull request
Jun 2, 2026
The structured control-flow constructs (loop/parallel/try-catch) and the BPMN interop mapping are implemented and merged (#1482, #1489, #1499, #1500; docs #1497). Flip ADR-0031 from Proposed to Accepted and record the implementing PRs and the deferred follow-ups (#1504 BPMN XML plugin, #1505 region step logs). https://claude.ai/code/session_012ti8cx3TkdiQdjCnZXZg2Q Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to the ADR-0031 work (#1482 loop, #1489 parallel): documentation for the structured control-flow constructs, plus two doc-generator fixes — one of which un-breaks the docs site build on
main.Changes
1. Flow authoring guide —
content/docs/guides/metadata/flow.mdx(hand-written)Adds a "Structured control flow (ADR-0031)" section documenting the
loopcontainer (config.body, iterator/index vars,maxIterations),parallelblock (config.branches[], implicit join), andtry/catch/retry(config.try/catch/retry), with config examples and the region / DAG-invariant model. Updates the Node Types table (loopreframed as a container; newparallelandtry_catchrows).2. Doc generator (
packages/spec/scripts/build-docs.ts) — docs-build fix 🔧The docs site (Vercel
apps/docs) was failing on every branch offmain:A zod
.describe()carries a SemVer range">=4.0 <5";escapeMdxDescriptiononly wrapped</{when it found a matching>/}, so the bare<5slipped through and MDX parsed it as the start of a JSX tag, failingnext buildfor the whole site. Now a lone</{(no matching close) is escaped as inline code.Verified locally: the full
apps/docsbuild (gen:schema && gen:docs && next build) compiles and prerenders all 1089 pages.3. Doc generator — dangling-card fix
The index now cards only reference pages that were actually generated. Control-flow's schemas embed CEL-expression transforms (like
Flow/FlowEdge) → no JSON-Schema page; the index previously carded every.zod.ts, producing a dangling "Control Flow" 404 link. Cards now align withmeta.json.Notes
references/**snapshots are intentionally left untouched (they regenerate at site build); this PR is generator + guide source only.uniquevalidation on sys_user #1492 too — those branches inherit the same brokenmaindocs build. This PR fixes it at the source.https://claude.ai/code/session_012ti8cx3TkdiQdjCnZXZg2Q