[objectstack-fleet]

Requested by Steve · project thread
Fixes #29051

Clause-②: no (narrowing)
Metadata-protocol: none
Skills-docs: none — skills/objectstack-automation/references/state-machines-and-approvals.md already teaches that a cycle-closing edge MUST be typed 'back' and that an unmarked cycle is refused; that stays true, and the CLI now refuses the same flow before it ships.

维护者速读

• 改了什么：os validate 和 os build 现在拒绝顶层图里有环、且环上没有一条 type: 'back' 边的流程（ADR-0044），退出码 1，build 不写产物；报错定位到该流程，正文是引擎注册时那句 "Flow contains a cycle: …"。
• 为什么改：这种流程以前本地校验、构建都通过，发布后引擎拒绝注册，流程从不运行。fix(metadata)!: refuse a flow with an undeclared cycle at publish, as the engine refuses it at registration #29226 已让发布门拒绝它，CLI 是最后一扇没关的门。
• 风险与回滚：收窄（BREAKING），以前能 build 的这类流程现在 build 失败，但它们本来就从未运行过。判定直接调用 @objectstack/metadata-core 的 findUndeclaredFlowCycle，与引擎注册、发布门是同一个函数，没有第二份环检测。回滚即还原本 PR，无数据迁移。
• 先看：packages/cli/src/utils/flow-undeclared-cycle.ts（新的遍历，一次调用），packages/cli/src/commands/validate.ts 第 3a-vii 步与 compile.ts 第 3b-iii-quater 步（新的门禁步骤），packages/cli/test/validate-flow-region-shape.test.ts 末尾（用同一份 FLOW_CYCLE_CORPUS 驱动 validate 与 build）。
• 两分钟验证：pnpm --filter @objectstack/cli exec vitest run src/utils/flow-undeclared-cycle.test.ts test/validate-flow-region-shape.test.ts，预期 16 个用例全绿；在 main 上环相关用例全红（validate 答 valid: true）。
• 需要你做的：无，席位落地。

What changes

• The walk (new packages/cli/src/utils/flow-undeclared-cycle.ts): findFlowCycleRefusals walks each packages[] entry's flows (or the stack's own flows when it declares no packages), parses each with FlowSchema, and asks findUndeclaredFlowCycle from @objectstack/metadata-core (exported by fix(metadata)!: refuse a flow with an undeclared cycle at publish, as the engine refuses it at registration #29226), the judge the engine's registration and the runtime publish gate call. No copy of the DFS. A refused flow is one VALIDATION_ERROR row located at the flow (flows[N] or packages[K].manifest.flows[N]), message Flow 'NAME' would be refused at registration: followed by the judge's sentence verbatim. @objectstack/cli already depended on @objectstack/metadata-core.
• The doors (packages/cli/src/commands/validate.ts step 3a-vii, compile.ts step 3b-iii-quater): one gate step each, the same shape as the CLI's other walks (--json: errors rows and exit 1; text: a heading naming ADR-0044 and the rows). The build writes no artifact.
• Why a CLI step and not a rule-table entry. feat(lint)!: os lint refuses a flow region the engine refuses to register (flow-region-shape-invalid) #29495 moved the ADR-0031 region check into @objectstack/lint (flow-region-shape-invalid). @objectstack/lint does not depend on @objectstack/metadata-core, so the rule table cannot reach this judge without a new package edge, and the ruling forbids a copy (seat claim amendment 6584349353 declares this file surface). So os lint does not give this verdict; os validate and os build do.
• Changeset .changeset/29051-cli-flow-undeclared-cycle.md: @objectstack/cli patch, BREAKING banner with before/now and the remedy, adr-0087: not-required (no-migration-prescription).
• Test-only config: packages/cli/vitest.config.ts gains one anchored alias, @objectstack/metadata-core/testing → ../metadata-core/src/testing.ts, which check:test-source-alias names for the new corpus import. The bare @objectstack/metadata-core specifier is not aliased; its ledger entry is unchanged.

Not touched: packages/metadata-protocol/**, packages/spec/**, packages/lint/**, ui/**.

Tests

• packages/cli/src/utils/flow-undeclared-cycle.test.ts (new): one case per FLOW_CYCLE_CORPUS entry (@objectstack/metadata-core/testing, the corpus the judge, the engine's registration and the publish gate are driven from). A refused case gives exactly one row at flows[0] whose message is Flow 'NAME' would be refused at registration: + undeclaredFlowCycleMessage(cycle). A back-typed or acyclic case gives none. Plus an assembled artifact: the refused flow in the second packages[] entry is located at packages[1].manifest.flows[1], and the stack's top level is not walked.
• packages/cli/test/validate-flow-region-shape.test.ts (new block at the end, in-process Command.run, unit tier): the whole corpus in one stack. os validate --json and os build --json each exit 1, with exactly one row per refused corpus flow at its own flows[N] carrying the judge's sentence; the build writes no dist/. CONTROL: the corpus's back-typed and acyclic flows alone validate and build (exit 0).
• Forced test edit: packages/cli/test/validate-build-gate-parity.test.ts. Its ledger classifies every call site in compile.ts and validate.ts, so findFlowCycleRefusals joins SHARED_NON_REGISTRY_GATES with the reason it is not a registry rule.

Acceptance notes

• Order differs from the engine for a flow with two faults. The engine judges the top-level cycle before the ADR-0031 region shape. The commands run the rule table (flow-region-shape-invalid) first, so a flow with both a malformed region and an undeclared cycle is refused for its region first, then for the cycle once the region is fixed. Both are refusals; only which one an author reads first differs.
• os lint does not give this verdict (see What changes). Closing that would need a lint → metadata-core edge, or the judge moving to a package lint already depends on; a separate decision, not taken here.
• The CLI row is located at the flow, as the card's acceptance asks. The publish gate (fix(metadata)!: refuse a flow with an undeclared cycle at publish, as the engine refuses it at registration #29226) locates its finding on the closing edge (edges.N). The judge returns closingEdgeIndex, so the CLI row could carry the edge later; not done here, to keep the row shape the CLI's other flow walks use.
• A flow FlowSchema refuses is not judged by this walk: flow-region-shape-invalid refuses it at the rule-table step, which exits before this one.

Verification

Head 5b16eb34 (origin/main merged at a5b8e9bf, after #29495). 5b16eb34 is a comment-only commit over 1f72080c (the @objectstack/metadata-core/testing alias comment in packages/cli/vitest.config.ts); the suites and dogfood below were measured on a5b8e9bf / 1f72080c, and the gate list was re-run on 5b16eb34.

Red first on main, green with the fix, ablation

• Red, before the fix (base aca58cdb, the tests then in their pre-feat(lint)!: os lint refuses a flow region the engine refuses to register (flow-region-shape-invalid) #29495 home): Tests 6 failed | 13 passed (19). os validate --json on the corpus stack answered "valid": true with exit 0. Every refused corpus case was expected [] to deeply equal [ { path: 'flows[0]', … } ].
• Green on a5b8e9bf: pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 src/utils/flow-undeclared-cycle.test.ts test/validate-flow-region-shape.test.ts → Test Files 2 passed (2) · Tests 16 passed (16).
• Ablation on a5b8e9bf, through scripts/ablation-replace.mjs: anchor const cycle = findUndeclaredFlowCycle(result.data); replaced with a null verdict. Output: anchor x1 -> x0, ok mutation landed: anchor 1 -> 0, blob 5f733ce3ccf2 -> 9d51706e9b08. Run: 6 red (the 4 refused corpus cases, the assembled-artifact case, the validate/build door case). Then ok restored: blob == HEAD … git diff HEAD empty. The CLI tests import source, so no dist leg.

Suites

• pnpm --filter @objectstack/cli typecheck: VERDICT command-exit 0 (on a5b8e9bf; 1f72080c adds one ledger row to a test file).
• pnpm --filter @objectstack/cli exec vitest run --project unit on a5b8e9bf: Tests 1 failed | 5281 passed (5282). The one failure was validate-build-gate-parity naming the unclassified findFlowCycleRefusals, the forced edit above (1f72080c). On 1f72080c: validate-build-gate-parity, authoring-rule-command-parity, flow-undeclared-cycle, validate-flow-region-shape → Test Files 4 passed (4) · Tests 61 passed (61).
• eslint --no-inline-config over the 7 touched source and test files: exit 0.
• Full dogfood on a5b8e9bf (pnpm --filter @objectstack/dogfood test, after pnpm install --frozen-lockfile && pnpm build): VERDICT command-exit 0 · Test Files 397 passed | 3 skipped (400) · Tests 3277 passed | 28 skipped (3305). 1f72080c changes one CLI test file only.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on 1f72080c, and again on 5b16eb34 (62 families, all exit 0, --ran the same derived zero): 62 families, each run with its exit code captured before any pipe, all exit 0. --ran reconciliation: 62 derived famil(ies) accounted for — 62 run, 0 NOT-MEASURED (a DERIVED zero — all 62 recorded an exit code and none of them is 3). check:plugin-teardown-shape --self-test needed the shallow-clone deepen (git fetch --depth=1 origin 621a4876…) first.

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 4 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/cli/vitest.config.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

36 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 50e35a280994dcecb714b6fa1f2d44840900f5e7.

⛔ 8 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/cli/vitest.config.ts) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 85 pages)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 216 client-bound route-ledger rows — the other 156 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 156: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 101 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 35 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 50e35a280994dcecb714b6fa1f2d44840900f5e7 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ebecfa080db61d27bee06ac2876d69613c29e921 — the merge of head 5b16eb349b8d570ea22c453f279e62ae6e94db7d into base 50e35a280994dcecb714b6fa1f2d44840900f5e7, 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 ebecfa080db61d27bee06ac2876d69613c29e921 && git checkout ebecfa080db61d27bee06ac2876d69613c29e921
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 50e35a280994dcecb714b6fa1f2d44840900f5e7 5b16eb349b8d570ea22c453f279e62ae6e94db7d && git checkout -B drift-repro 50e35a280994dcecb714b6fa1f2d44840900f5e7 && git merge --no-ff 5b16eb349b8d570ea22c453f279e62ae6e94db7d

node scripts/docs-audit/affected-docs.mjs --json 50e35a280994dcecb714b6fa1f2d44840900f5e7

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

[objectstack-fleet]

domain:server#2 · os-steve · session_01ADHkmQxwoGb5fSnrFkpxmt

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Reviewed-by: session_01ADHkmQxwoGb5fSnrFkpxmt
Implemented-by: session_01ADHkmSGEsjUPQp4S968p2X
Head-sha: 1f72080c7e90377aa4afca8b41375a243cea4311
Local-runs: none
Scope: packages/cli/src/utils/flow-undeclared-cycle.ts (findFlowCycleRefusals, FlowCycleRefusalRow), packages/cli/src/commands/validate.ts (step 3a-vii), packages/cli/src/commands/compile.ts (step 3b-iii-quater), packages/cli/src/utils/flow-undeclared-cycle.test.ts, packages/cli/test/validate-flow-region-shape.test.ts, packages/cli/test/validate-build-gate-parity.test.ts (the SHARED_NON_REGISTRY_GATES row), packages/cli/vitest.config.ts (the @objectstack/metadata-core/testing alias) + packages/metadata-core/src/flow-cycle.ts (findUndeclaredFlowCycle, undeclaredFlowCycleMessage), packages/metadata-core/src/flow-cycle-corpus.ts and testing.ts (FLOW_CYCLE_CORPUS), packages/metadata-core/package.json (exports . and ./testing), packages/services/service-automation/src/flow-registration-checks.ts (detectCycles) and flow-definitions.ts (canonicalizeFlow: applyConversionsToFlow, FlowSchema.parse, detectCycles, validateControlFlow), packages/metadata-protocol/src/runtime-authoring-gate.ts (findFlowCycleGaps, FLOW_UNDECLARED_CYCLE), packages/lint/src/validate-flow-region-shape.ts (validateFlowRegionShape), packages/lint/package.json (dependency edges), packages/cli/package.json (dependencies, exports), packages/cli/src/index.ts, packages/cli/src/utils/artifact-packages.ts (artifactPackages), packages/cli/src/utils/extension-field-suffix.ts (the sibling walk's subject rule), the retired packages/cli/src/utils/flow-region-shape.ts at the parent of #29495's merge (the row shape this walk keeps), packages/spec/src/stack.zod.ts (flows: z.array(FlowSchema) and assembledPackageBodyShape), scripts/check-test-source-alias.mjs (KNOWN_UNALIASED_TEST_IMPORTS, the @objectstack/cli entry), .changeset/config.json (the fixed group), .changeset/29051-cli-flow-undeclared-cycle.md (read for ②), the precedent changesets 29025-flow-undeclared-cycle-publish.md, 28893-flow-region-shape-at-validate-build.md, 29049-flow-region-shape-lint-rule.md and 29233-flow-region-shape-publish.md as landed on main, the card body of #29051, the claim 6580677546 and its amendment 6584349353, the dev report 6587816439, the director ruling 6580265584 on #29025, and the seat order delta for #29051.

Face: narrowing (Clause-②: no (narrowing) line-initial on the PR body and the changeset; no path under packages/spec/src/**, no governed path: check-governed-merges --pr 29595 answers 0 of 8 paths hit, 13 surfaces governing). Merge-base 03797bd796477d8603339c79994ccd9a63f7f9b4; net diff 8 files, 272 insertions, 0 deletions (272 changed lines, under 3,000). The PR file list equals the dev report's files_changed and equals amendment 6584349353's declared surface (the new walk, one step each in validate.ts and compile.ts, its tests, the changeset) plus the two deviations the report declares (the parity ledger row, the vitest alias). Nothing under packages/metadata-protocol/**, packages/spec/**, packages/lint/** or ui/** moves. main has moved 27 commits since the merge-base; the two that touch any cited file are #29526 (the lint registry row, 0814b892) and #29499 (3557366c, spec), neither on validate.ts, compile.ts, the judge, the engine or the corpus. Every non-prose path of the diff is in scope above.

① Derived judgments

1. The accept-set change is at os validate and os build only (@objectstack/cli). A stack carrying a flow whose top-level nodes/edges graph, once every edge with type: 'back' is set aside, still has a cycle now fails both commands with exit 1: one VALIDATION_ERROR row per such flow in errors under --json, a heading naming ADR-0044 and the rows in text, and os build writes no dist/. os lint is unchanged. No other door moves: the runtime publish gate already refuses the same flow since fix(metadata)!: refuse a flow with an undeclared cycle at publish, as the engine refuses it at registration #29226 (findFlowCycleGaps, on main), the engine's registration is untouched. Right, and it is the one accept-set change in the diff.
2. Same judge as the engine and the gate, no second DFS. The walk calls findUndeclaredFlowCycle from @objectstack/metadata-core, the function detectCycles (flow-registration-checks.ts) throws from and findFlowCycleGaps (runtime-authoring-gate.ts) asks; git grep over packages/cli/src and packages/lint/src at this head finds no other reader of Flow contains a cycle, findUndeclaredFlowCycle or detectCycles apart from the region rule's docblock. The ruling's 「⛔ No copy of the DFS」 holds. Right.
3. Same graph as the engine. The engine's canonicalizeFlow runs applyConversionsToFlow, then FlowSchema.parse, then detectCycles(parsed). At both CLI doors the ADR-0087 D2 conversion layer runs inside normalizeStackInput (validate.ts step 2, compile.ts step 2) before ObjectStackDefinitionSchema.safeParse, and the stack schema parses every flow with FlowSchema (flows: z.array(FlowSchema) on the stack and, through assembledPackageBodyShape, on each packages[].manifest). So result.data hands the walk the converted, parsed flow, and FlowSchema.safeParse on it is a re-parse of the schema's own output; the judge reads nodes[].id and edges[].source/target/type, which neither parse nor conversion reorders or rewrites (as the fix(metadata)!: refuse a flow with an undeclared cycle at publish, as the engine refuses it at registration #29226 record established for the gate). An absent edge type is 'default' after parse and !== 'back' raw, the same answer. The edge alias spellings (from/to) are refused by the strict stack schema upstream, as FlowSchema.parse refuses them at registration, so no graph reaches one judge and not the other. Right: the set refused equals the engine's.
4. Same sentence. The row's message is Flow 'NAME' would be refused at registration: followed by cycle.message, which is undeclaredFlowCycleMessage(path), the string detectCycles throws, verbatim. The prefix is the one the lint region rule puts before the engine's sentence on all three authoring commands and now at the gate (fix(lint)!: refuse a flow whose loop, parallel or try_catch region is malformed at publish #29526); the gate's own flow-undeclared-cycle finding carries the bare sentence plus a hint and locates on the closing edge (flows[0].edges[N]), while this row locates at the flow, which is what the card's acceptance and the seat's delta ask for ("located at the flow"). The dev's acceptance note names the edge-vs-flow difference and that closingEdgeIndex is available for a later edge-located row. Right.
5. No false refusal of a declared cycle or a legacy shape. The judge sets aside only type: 'back'; the corpus's cyc_rework_back, cyc_self_back, cyc_mid_back (any one back edge on the loop) and cyc_diamond (two paths meeting) are cycle: null, and the corpus test pins [] for each; the door test's CONTROL stack holds exactly those and exits 0 through both commands. A fault-typed closing edge is refused, which is the engine's semantics (cyc_rework_fault). Legacy shapes are converted before the parse (①.3), so a flow the engine registers after D2 conversion is one this walk judges after the same conversion. A flow FlowSchema refuses is skipped (if (!result.success) return), which is unreachable at these doors (the stack schema already parsed it) and, were it reachable, is what the region rule reports as "could not be judged" one step earlier (①.7). Right.
6. Package paths. artifactPackages(parsed) gives the packages[] entries with their index and manifest body; the walk reads each entry's body.flows at packages[K].manifest.flows[N], or the stack's own flows[N] when it declares no packages. This is the subject rule the retired objectstack validate passes a flow whose try_catch catch region has several sinks; the engine refuses it at registration ("region must be single-exit") with only a WARN, so the flow never runs #28893 walk used (same three lines at the parent of feat(lint)!: os lint refuses a flow region the engine refuses to register (flow-region-shape-invalid) #29495's merge) and the one findExtensionFieldSuffixRefusals uses, so the top level of an assembled artifact is not walked, as its sibling walks do not walk it. The unit test pins a refused flow in the second entry at packages[1].manifest.flows[1] with the top-level flow ignored. Right, and consistent with the CLI's other author-time walks.
7. Order versus the region rule, and no double report. The rule table runs first at both doors (validate.ts step 3a-i union run and 3a-ii per-package run, compile.ts 3b and 3b-ii), each with an errors.length > 0 exit under splitBySeverity, so a flow flow-region-shape-invalid refuses never reaches step 3a-vii / 3b-iii-quater. The engine judges the cycle (detectCycles) before the region (validateControlFlow), so an author with both faults reads the region first here and the cycle first at registration; the dev declares this in the acceptance notes, the changeset and the walk's docblock, and amendment 6584349353 accepted it. The two judges read disjoint graphs (validateControlFlow never reads the top-level edges; findUndeclaredFlowCycle never descends into a region), so one fault yields one row, and no other step of either command reports a top-level cycle (①.2). Right: no double report.
8. Both doors wired, as the ledger demands. validate-build-gate-parity.test.ts closes the roster: a bare identifier either command calls must sit in exactly one ledger. findFlowCycleRefusals joins SHARED_NON_REGISTRY_GATES with the reason it is not a registry rule, and the file's own assertions hold that both commands call it. The step sits before the capability preflight on validate and before the dependency-range check and every artifact write on build (fs.writeFileSync(artifactPath, …) is at line 1321, the step at 850). Right.
9. No new package dependency edge, and none the ruling forbids. packages/cli/package.json already lists @objectstack/metadata-core: workspace:* (line 73, unchanged); packages/lint/package.json still depends on formula, sdui-parser and spec only, and no file under packages/lint/ moves. The ruling's reason for letter A (no lint → metadata-core edge "for a check automation: a flow with a top-level cycle passes os validate and build; detectCycles runs only at registration and has no author-time home #29051 can add with one call") is honoured: the check is one call in the CLI. Right.
10. Public surface and new names. findFlowCycleRefusals and FlowCycleRefusalRow are module exports under src/utils/; @objectstack/cli's exports map (., ./console, ./hook-body, …) and src/index.ts (which re-exports commands and nothing from ./utils) do not reach them, so no package-public name is added. The wire-visible change is the new row in errors of os validate --json / os build --json, shape { path, code: 'VALIDATION_ERROR', flow, message }, byte-for-byte the retired FlowRegionRefusalRow shape of objectstack validate passes a flow whose try_catch catch region has several sinks; the engine refuses it at registration ("region must be single-exit") with only a WARN, so the flow never runs #28893, and one new text heading. No new rule id, no new export, no spec change. Right.
11. The test-only alias. packages/cli/vitest.config.ts gains @objectstack/metadata-core/testing → ../metadata-core/src/testing.ts, anchored (^…$). The bare @objectstack/metadata-core specifier was already aliased to source in the same file before this PR (the #20158 block, find: /^@objectstack\/metadata-core$/), which is why @objectstack/metadata-core is absent from KNOWN_UNALIASED_TEST_IMPORTS['@objectstack/cli']; the new subpath alias follows that precedent so the corpus the tests read is the checkout's, not dist/testing.js. Lint · repo & tooling gates, where check:test-source-alias runs, is success on this head. Right in substance; the comment above it is wrong in two places (③).

② Semver level

• Changeset .changeset/29051-cli-flow-undeclared-cycle.md: '@objectstack/cli': patch, headline **BREAKING** fix(cli)!:, line-initial Clause-②: no (narrowing), Metadata-protocol: none and Skills-docs: none — …, exactly one adr-0087: not-required (no-migration-prescription) marker, Before / Now / Unchanged bullets and a remedy paragraph. The PR title is fix(cli)!: and its body carries the same two declaration lines line-initial. Check Changeset and Lint · PM dispatch-gates (which carries check-adr-0087-registration and check-changeset-no-major) are success on this head.
• The kind is none, and patch follows. AGENTS.md's kind is "the change to what a metadata author can write". This diff changes no schema, no accepted value and no door of the protocol: FlowSchema still accepts the flow, the engine refuses it as before, and the publish gate refuses it since fix(metadata)!: refuse a flow with an undeclared cycle at publish, as the engine refuses it at registration #29226, which declared that narrowing narrowed / minor on @objectstack/metadata-protocol. What moves here is the CLI's author-time verdict, brought into line with the protocol as it already stands on main. That is the face objectstack validate passes a flow whose try_catch catch region has several sinks; the engine refuses it at registration ("region must be single-exit") with only a WARN, so the flow never runs #28893 landed (fix(cli), Clause-②: no (narrowing), Metadata-protocol: none, patch, BREAKING banner, adr-0087 marker) and lint: os lint stays blind to a flow region the engine refuses to register; validate and build refuse it since #28893 through a CLI-only gate #29049 landed (none, patch); fix(metadata)!: refuse a flow with an undeclared cycle at publish, as the engine refuses it at registration #29226 and fix(lint)!: refuse a flow whose loop, parallel or try_catch region is malformed at publish #29526 are the other face, a protocol door (the runtime authoring gate) refusing a body it accepted, and their minor is the level the kind narrowed takes there. AGENTS.md's own sentence covers this changeset exactly: "a non-protocol change, widening or breaking, ships patch and keeps its BREAKING banner and ADR-0087 disposition". Right; declarations, level, banner and gates agree, and the seat's claim and delta expected these values.
• Only @objectstack/cli moves in the diff and it is the one package the changeset bumps. The fixed group in .changeset/config.json holds cli with metadata-core, metadata-protocol and lint, so the group's next version is the highest level among its pending changesets whatever this one says; patch here changes nothing shipped.
• One reading the seat should hold in mind rather than act on: if "a value refused" at any door were read as narrowed, this would be minor, but that reading would re-rate objectstack validate passes a flow whose try_catch catch region has several sinks; the engine refuses it at registration ("region must be single-exit") with only a WARN, so the flow never runs #28893 and lint: os lint stays blind to a flow region the engine refuses to register; validate and build refuse it since #28893 through a CLI-only gate #29049 too and would count the same narrowing twice (once at the gate in fix(metadata)!: refuse a flow with an undeclared cycle at publish, as the engine refuses it at registration #29226, once here). I do not recommend it.

③ Boundary flags

• Dev open_questions, one: should os lint also refuse the cycle (A leave lint blind, B add a lint → metadata-core edge, C move the judge into a package lint depends on). My view is A, as the dev recommends, for this card and this PR. (1) The director ruling 6580265584 (letter A, maintainer 「同意」) decided this exact question for the gate and gave the reason: the rule does not move into AUTHORING_RULES because that "would add a lint → metadata-core dependency edge for a check automation: a flow with a top-level cycle passes os validate and build; detectCycles runs only at registration and has no author-time home #29051 can add with one call". B is the edge the ruling declined; taking it on the CLI card would reverse the ruling's reason without a ruling. (2) C is the card's original option (a), a spec export, which the same ruling settled against ("neither (a) nor (b), the metadata-core export", the delta's reading); it is a domain:spec package-graph decision and a new card, not a rider here. (3) os lint already does not run any SHARED_NON_REGISTRY_GATES row (the capability preflight, the override gate, the suffix reservation, the dependency-range check), so a hand-wired gate lint is blind to has precedent on every row of that ledger, and this PR records the reason in the row. (4) Four-axis: no measured pull for the lint face (the card's reach is os validate / os build, the doors that ship; nobody reported os lint passing such a flow); the long-term shape stays the ruled one (one judge in metadata-core, called from each face); the AI-error axis is served where it matters, the build that emits the artifact now refuses; and no new package edge at startup stage. If the seat wants lint parity later, it is one card (B needs a director ruling reversing letter A's reason; C is the spec lane's), measured on pull, not this head.
• Forced edit packages/cli/test/validate-build-gate-parity.test.ts: within the claim surface ("its tests", amendment 6584349353), and forced by the closed roster: a new bare identifier both commands call fails the file until classified. The row is placed in the right ledger (both doors call it) with a true reason. Right.
• packages/cli/vitest.config.ts is outside the declared surface; the dev reports it as a deviation named by check:test-source-alias. Test-only, one anchored subpath alias, the repo's own mechanism for reading a sibling's test corpus from source. Accepted. Should-fix (prose, no behaviour): the comment above the alias says the bare @objectstack/metadata-core specifier "is NOT aliased here: it stays in this package's measured ledger entry"; both halves are false on this tree (the bare specifier is aliased to ../metadata-core/src/index.ts forty lines below, since RLS policies are admitted when they are authored: policy save and objectstack validate / compile judge the lowered read-scope filter with the engine's judge-only method (objectstack#19995 ruling C, second consumer) #20158, and @objectstack/metadata-core is not in the cli ledger entry, which is why the gate is green). The same comment names src/utils/flow-region-shape.test.ts, a file feat(lint)!: os lint refuses a flow region the engine refuses to register (flow-region-shape-invalid) #29495 deleted; the file is src/utils/flow-undeclared-cycle.test.ts. Fold into any later push; not a landing blocker.
• Skills-docs: line: the arm is (narrowing), so the claim template owes the PR body a line-initial Skills-docs: line beside the two declarations. The changeset carries Skills-docs: none — … (and its reason is right: skills/objectstack-automation/references/state-machines-and-approvals.md lines 168-172 teach that the resubmit edge MUST be typed 'back' and that an unmarked cycle is rejected; no skill or doc says os validate passes such a flow, the only sentence to that effect being the release-owned metadata: a flow with an undeclared cycle (loop edge not typed back) reads valid as a draft and publishes, then the engine refuses to register it — a dead flow goes live #29025 changeset's "do not run this check yet", which this PR makes false in the right direction and which no code PR may edit). The PR body does not carry the line. Should-fix (body edit, no head move), as the fix(lint)!: refuse a flow whose loop, parallel or try_catch region is malformed at publish #29526 record asked.
• Full dogfood battery on the final head: the lane rule (standard order §5) owes the battery on the final head for a narrowing. The dev ran it on a5b8e9bf (397 files passed, 3 skipped; 3277 tests passed, 28 skipped, VERDICT 0) and git diff --stat a5b8e9bf 1f72080c is exactly the 8-line ledger row in packages/cli/test/validate-build-gate-parity.test.ts, a test file no dogfood suite imports. I judge the reading carries to the head; naming it so the seat's ACCEPT accepts the deviation on the record rather than by silence. The CI Dogfood Regression Gate parent job is success and its shard matrix skipped on this head (path filter), so CI adds no battery reading of its own.
• Dev deviations 2 and 4 (the move into the new walk carried by the merge commit a5b8e9bf rather than a separate commit; the progress-checklist tool unavailable) are procedural and leave nothing in the tree beyond the 8 files.
• Out-of-scope finding, carrier: none · noted, not filed (os lint does not give this verdict): answered by the A/B/C view above; nothing to file under Prime Directive chore: version packages #10 (no defect, no contract violation, the declared behaviour is enforced where declared).
• Check-runs on head 1f72080c at 2026-11-02T20:41Z: 46 runs; 23 completed/success, 13 completed/skipped, 10 in_progress, 0 failed or cancelled. Of the ten required contexts, Lint & Repo Gates, Build Core, Governed Surface Queue Guard, Test UI, Live E2E UI are success; Lint UI, Type Check UI, Build & E2E UI are skipped by their ui/** path filter, as expected for a diff with no ui/** path; TypeScript Type Check (workspace, debt ledger, consumer gates; source gates already success) and Test Core (shards 1-7; shard 8 success) are still in_progress. Every completed run is success or skipped. This record judges the tree and the completed conclusions; the all-green landing precondition is the seat's to read again before queueing.
• Governed surface: none; size 272 changed lines; PR author objectstack-fleet[bot], no relay author to name; the branch claude/project-thread-s4ddhz is the one claim 6580677546 names.

④ Design judgment

• packages/cli/src/utils/flow-undeclared-cycle.ts — holds against the card's scenario and the ruling. Pure (reads the parsed stack only; safeParse, never parse); one call to the shared judge; the engine's sentence verbatim behind the flow's name; the subject rule and row shape of the walk it replaces, so an author who read objectstack validate passes a flow whose try_catch catch region has several sinks; the engine refuses it at registration ("region must be single-exit") with only a WARN, so the flow never runs #28893's rows reads the same shape. The docblock states the order difference, the lint-blindness and its reason, and the schema-refused skip and why it is unreachable, all of which I verified (①.3, ①.7, ①.9). I tried to break it with: the card's start → push → check → revise → push with the loop edge untyped (refused, flows[0]); the same with e5 typed back (passes); a fault-typed closing edge (refused, as the engine); a self-loop, typed and untyped; one back edge in the middle of the loop (passes, the graph minus back edges is acyclic); two loops, one declared (the undeclared one named); a diamond (passes); the refused flow in the second packages[] entry beside a passing top-level flow (one row at packages[1].manifest.flows[1], top level not walked); a flow with both a malformed region and an undeclared cycle (refused for the region at the rule-table step, this step never reached); a legacy shape the D2 layer converts (converted before the parse, judged after it, as at registration). In every case the verdict is the engine's or the declared order difference.
• packages/cli/src/commands/validate.ts and compile.ts — hold: one step each, the exact shape of the neighbouring hand-wired gates (emitJson with the command's own failure envelope under --json, printError plus printBulletList with JSON_FULL_LIST_REMEDY otherwise, this.exit(1)), placed after the rule table and before the build's artifact write. The parity ledger holds both calls.
• The narrowing itself against the published spec on main (the face's own question): FlowSchema on main accepts the flow; ADR-0031 ("the engine is DAG-only") and ADR-0044 (an unmarked cycle is refused, the reduced graph must be a DAG) say the engine refuses it, and since fix(metadata)!: refuse a flow with an undeclared cycle at publish, as the engine refuses it at registration #29226 the publish doors refuse it in the same words. A flow this now refuses was never a registrable capability: it built, published or booted, and never ran. A flow with any edge of its loop typed back validates and builds exactly as before (CONTROL), and nothing inside a region is judged here. The narrowing makes the engine's own refusal real at the door that ships, through the one judge the engine and the gate already use, and takes no registrable capability away.
• Test files (read for the parity claim, not reviewed): the unit suite is driven from the judge's own corpus, so the CLI is pinned to the same eight graphs as the judge, the engine and the gate, and the expected sentence is computed from undeclaredFlowCycleMessage(c.cycle), not restated; the door test drives the whole corpus through in-process Command.run for both commands, asserts one row per refused flow at its own flows[N] with the judge's sentence, asserts no dist/, and holds a CONTROL stack of the declared and acyclic cases at exit 0. Red first on the pre-fix base (6 failed), ablation of the one judge call (6 red, restored to byte-equal), as the lane rule asks.
• No must-fix found.

VERDICT: PASS

Must-fix: none.
Should-fix (no landing blocker; fold into any later push or a body edit):

1. PR body: add the line-initial Skills-docs: none — … line beside the two declarations, mirroring the changeset (the (narrowing) arm owes it).
2. packages/cli/vitest.config.ts, the comment above the new alias: the bare @objectstack/metadata-core specifier is already aliased to source in this file and is not in the cli ledger entry, so drop the "NOT aliased … ledger entry" sentence; and name src/utils/flow-undeclared-cycle.test.ts, not the deleted src/utils/flow-region-shape.test.ts.
3. For the seat's ACCEPT, not the dev: accept on the record the full-dogfood reading on a5b8e9bf for head 1f72080c (delta: the 8-line ledger row only), and read the check-runs again once TypeScript Type Check and Test Core complete.

---

Generated by Claude Code

[objectstack-fleet]

domain:server#2 · os-steve · session_01ADHkmQxwoGb5fSnrFkpxmt

席位核对

ACCEPT · domain:server seat 2 · os-steve · session_01ADHkmQxwoGb5fSnrFkpxmt · 2026-11-02T21:16Z · head 5b16eb34 · claimed by seat 2 on #29051 (claim and amendments on the card)

1. Shape: a draft against main with Fixes #29051. Clause-②: no (narrowing), Metadata-protocol: none and Skills-docs: are line-initial on the body and the changeset. @objectstack/cli ships a patch with a BREAKING banner and one adr-0087 marker. That is right for a CLI-face narrowing, which is not the protocol's accept set: AGENTS.md says a non-protocol breaking change ships patch and keeps its banner. check-governed-merges --pr 29595: NOT governed. No packages/spec, no ui/**.
2. One judge: os validate (step 3a-vii) and os build (step 3b-iii-quater) refuse an undeclared top-level flow cycle through the engine's own findUndeclaredFlowCycle (@objectstack/metadata-core). They give the same sentence, located at flows[N] / packages[K].manifest.flows[N], and there is no second cycle reader. The region rule runs first, on disjoint graphs, so nothing is reported twice. No new package edge.
3. Contract review: PASS (6588045718) at 1f72080c, with no must-fix. This head adds one comment-only commit (git diff --stat 1f72080c 5b16eb34: packages/cli/vitest.config.ts, 3+/3−), and the seat read it.
4. Open question ruled: A. os lint stays blind to the cycle. Director ruling 6580265584 declined the lint → metadata-core edge because this card adds the check with one call. B would reverse that reason without a ruling, and C is the option that ruling settled against. Lint-blindness has precedent on every SHARED_NON_REGISTRY_GATES row.
5. Should-fix handling:
   • The Skills-docs: line and the vitest comment were both fixed in this round.
   • The seat accepts the full dogfood battery read on a5b8e9bf (3277 tests, verdict 0) for this head. The only differences are the parity-ledger row in one test file that no dogfood suite imports, and this comment.
6. Evidence:
   • Corpus-driven unit test 16/16. On the base, 6 of 19 fail and validate said valid: true.
   • Ablation turns 6 red and restores clean.
   • Gates on 5b16eb34: 62/62 exit 0.
   • CI on this head when read: 35 success, 15 skipped, 2 in progress, 0 failed. Auto-merge waits for the required checks.
7. Landing: pr_ready + automerge_enable through the relay.

---

Generated by Claude Code