[objectstack-fleet]

Requested by Leehom · project thread

domain:devx#3 · os-project-manager · session_01FEkQ5pZeHgu9hYkeNdBNEA

Fixes #31121

Clause-②: yes — a new gallery-refresh entry point on the published @objectstack/scenarios widens its surface; the PR body carries the reading
Metadata-protocol: none

维护者速读

• 改了什么:@objectstack/scenarios 新增 gallery-refresh --gallery DIR [--cards DIR] [--model M] [--debut]。它读 npm 上 @objectstack/cli 的最新稳定版和画廊 index.json 里每个应用的 framework.version;一致就只打印一行 skip: … 并以 0 退出,什么都不跑。不一致就在这个版本上跑所有可上画廊的卡片(generic + starter/delivery,--debut 只跑第一张),导出到画廊检出目录,在本地分支 export/VERSION 上提交,打印分支名和现成的 PR 正文。⛔ 永不推送、不开 PR。driver.ts 头部写明裁决 D2,README 加了定时任务的运行手册(含任务提示词原文)。
• 为什么改:裁决 D2:每天由云端定时 Claude Code 任务(你的订阅登录)在每次稳定版发布后重跑画廊并在 objectstack-ai/gallery 开 PR,由你一键合并。此前没有任何入口能一步完成「查版本 → 跑 → 导出 → 提交」。
• 风险与回滚:只新增一个入口和若干导出,run-scenarios、export-gallery 行为不变(export-gallery 的截图步骤只是抽成了一个函数)。回滚即还原本 PR。定时任务本身和画廊仓库不在本 PR 内。
• 先看:packages/qa/scenarios/src/export/refresh.ts(跳过规则、拒绝条件、提交步骤)、README.md 新节「Refreshing the gallery」里的任务提示词、src/runner/driver.ts 头部。
• 两分钟验证:pnpm --filter @objectstack/scenarios exec vitest run --maxWorkers=2 test/export/refresh.test.ts,预期 17 个用例全过(含「版本一致只打一行 skip」「永不推送:远端引用不变」「版本不符拒绝提交」)。
• 需要你做的:无,席位落地。之后把 objectstack-ai/gallery 加进本项目环境资源,席位才能按 README 原文创建定时任务。

What changes

• gallery-refresh (src/export/refresh.ts, CLI src/export/refresh-cli.ts, package script gallery-refresh), in order, each step a refusal (exit 1, the reason on stderr) or a quiet skip (one skip: … line, exit 0):
  1. --gallery must be the top of a git checkout with a clean working tree (untracked files count), and its index.json (absent means an empty gallery) must validate as one the exporter wrote.
  2. npm's latest dist-tag of @objectstack/cli (npm view, so the caller's npm config applies). A value that is not a plain MAJOR.MINOR.PATCH is refused.
  3. Skip when the index lists at least one app and every app's framework.version equals it.
  4. Skip when a remote-tracking export/VERSION branch exists (that refresh was pushed and awaits review). A local export/VERSION branch is refused: an earlier run's commit is never overwritten.
  5. The cards: every loaded card GALLERY_GUARD admits (origin generic, tier starter or delivery). With --debut, only the first of them by id, and only into a gallery whose index lists no app.
  6. The run: run-scenarios --only CARDS --modes scratch --packages published --create-version VERSION --out WORK/runs --work WORK/work --record WORK/recording.json [--model M] [--cards DIR] (runnerArgv), then exportGallery into the checkout with real screenshots.
  7. Refused when no app exported, when an exported app's framework.version is not the release, or when anything outside apps/ and index.json changed in the checkout.
  8. git switch -c export/VERSION, git add --all -- apps index.json, git commit under the checkout's own git identity. It prints the export summary, branch:, commit: and the PR body (refreshPrBody: version, previous version, cards run, model, exported / refused / removed apps).
  • ⛔ Nothing in the code path pushes, opens a PR or talks to GitHub.
• --model passes through to run-scenarios --model (PR feat(scenarios): run-scenarios --model / --author-model / --ask-model, with the served model recorded per turn #31204's flag), with the same refusal of an empty or flag-shaped value.
• driver.ts header names ruling D2: a local session on the developer's own login, or a scheduled cloud Claude Code task on the maintainer's subscription login. An API-billed model is still never allowed. ClaudeCodeDriver's API-key refusal is unchanged.
• README: a new section, "Refreshing the gallery — gallery-refresh", and "The scheduled task's runbook": what it runs, what it needs, what it never does, and the task's prompt verbatim (clone the gallery, run gallery-refresh detached and wait in the foreground, push only export/VERSION, open one PR with the printed body, and on any failure comment on or open one Gallery refresh failed issue).
• src/export/cli.ts: the live screenshot wiring moves into liveScreenshots(chromium?), which both CLIs call. No behaviour change.

Public surface (Clause-②: yes)

@objectstack/scenarios/export re-exports refresh.ts. Read with the TypeScript checker (getExportsOfModule) over the built dist/export.d.ts on this head: 84 exports, 49 values. The 15 new names (none of them on origin/main, git grep): values galleryRefresh, runnerArgv, readGalleryVersions, npmLatestVersion, refreshPrBody, galleryBranch, RefreshRefusal, FRAMEWORK_PACKAGE, STABLE_VERSION; types RefreshOptions, RefreshDeps, RefreshOutcome, RunPlan, GalleryVersions, PrBodyInput. No name is removed or retyped, so the subpath only widens (69 → 84). refresh-cli.ts is not an exports key and not a bin command: the card asks for neither, and the scheduled task runs from a checkout. Nothing in packages/spec moves.

Tests

test/export/refresh.test.ts (new, 17 cases). The gallery is a real git checkout (main, a README, optionally an index.json and app directories) with a bare origin. The npm reader is a stub. The run step runs the real crm card through runCard with the fixture's scripted model inside the runner's own RecordingDriver (test/export/fixture.ts), and writes the record and the recording where run-scenarios would. The crm card is a control card, so these cases pass the exporter tests' all-eligible guard double. One case uses the real guard on the repo's cards.

• Skip: every listed app on npm's latest prints one skip: line, calls no run, and leaves HEAD, the working tree and the remote as they were. A mixed index, an empty index and no index do not skip. A remote-tracking origin/export/18.3.0 skips with its own line.
• Commit: the commit sits on export/18.3.0 with main as its parent, touches only index.json and apps/crm_account_with_contacts/, and is authored by the checkout's configured identity. The tree is clean, the index states 18.3.0, and the PR body names the branch, the card and the model. ⛔ Never pushes: the bare remote's refs are byte-identical before and after. A second refresh then skips.
• Run plan: runnerArgv output parsed by the runner's own parseArgs gives exactly that createVersion, packages: published, modes: ['scratch'], the cards, out/work/record and the model, with iterate Run on. No model means no --model. With the real guard on the repo's nine cards, the plan is the six starter ids, and --debut gives the first of them (asset_lifecycle).
• Refusals, each with nothing run or nothing committed: a prerelease, 18.4, empty or v-prefixed latest; an npm read that throws; a plain directory; a subdirectory of a checkout; an untracked file; an index that does not validate; a local export/18.3.0; --debut over a listed app; npm at 18.4.0 while the project pins 18.3.0 (… states framework 18.3.0, not 18.4.0); a run with no iterate Run (no app passes); a .env written into the checkout.
• CLI: flag parsing and its refusals (--gallery missing, bad --model, unknown --push). main prints exactly one line on a skip. On the repo's cards it commits and prints branch: export/18.3.0 and the body. A prerelease exits 1 with gallery-refresh: refused — ….

Ablations (each restored: blob == HEAD, git diff HEAD empty)

All through scripts/ablation-replace.mjs on commit de7c89c5 (anchor x1 → x0, replacement x0 → x1). The suite imports src/ directly, so there is no dist leg. Each ran test/export/refresh.test.ts -t NAME.

• A1, version check disarmed (filter((a) => a.framework.version !== latest) gets && String("ABL1").length < 0): 1 failed | 16 skipped, the "another framework version" case.
• A2, the --debut refusal disarmed: 1 failed | 16 skipped, the "--debut into a gallery that already lists an app" case.
• A3, the skip disarmed (before.versions[0] === latest): 1 failed | 16 skipped, the "every listed app states npm's latest" case.
• A4, the outside-the-exporter-paths check disarmed: 1 failed | 16 skipped, the ".env" case.
• A5, the dirty-checkout refusal disarmed: 1 failed | 16 skipped, the "top of a clean git checkout" case.

Acceptance notes

• index.json carries framework.version per app, not once. The index schema (manifest.ts, strict) is { schemaVersion, apps }, and each app's framework.version is the @objectstack/spec its project pins (create-objectstack pins its own release exactly, and the fixed group versions @objectstack/cli with it). So "the gallery's version" is read as: the index lists an app, and every listed app states that version. No index field was added: that would change the format objectstack-ai/gallery: a read-only check workflow on every PR (index schema, complete app directories, no stray files) and a PR-only main, before the scheduled export writes there #31122's check reads.
• After the debut, the full gallery comes with the next release. A debut leaves one app on version V, so later runs skip until npm's latest moves past V. There is no --force flag: the ruling names none.
• The second skip (a pending export/VERSION on the remote) is an addition. Without it, every daily run while the PR awaits review would rerun every card for hours of subscription quota, and then fail to push an existing branch. It reads only the clone's remote-tracking refs, so no network.
• Scratch mode only. The gallery ships the scratch project, and the exporter's pass rule (pass.ts) owes scratch mode's six halves. Template mode would roughly double each card's time and quota without changing what is exported.
• A card that fails is not a refusal of the refresh. The exporter's own rule applies: it is refused or removed, the commit goes ahead with the rest, and the PR body lists it with its reasons. The refresh is refused only when no app exports.
• --cards DIR keeps the meaning it has in run-scenarios and export-gallery (the card directory, where any directory but the repo's is the private overlay). A flag of the same name taking card ids in the same package would be a trap. --debut therefore picks its card itself: the first exportable id (asset_lifecycle today).
• The task's prompt runs the refresh detached (nohup plus repeated timeout 590 tail --pid). A full refresh runs one starter build after another, longer than the 2-hour cap on a background command in a cloud session. This is written into the runbook; no live run measured it (live runs are paused, cloud#3600).
• Out of scope here: the scheduled task itself, objectstack-ai/gallery, and objectstack-ai/gallery: a read-only check workflow on every PR (index schema, complete app directories, no stray files) and a PR-only main, before the scheduled export writes there #31122's export-gallery --check and the gallery workflow. The maintainer still owes adding the gallery to the environment's resources.

Verification

All on head de7c89c5 (base 7c523aa1, current origin/main when cut), worktree objectstack-issue-31121.

• Package suite, under the verify lock after pnpm --filter @objectstack/scenarios build: pnpm --filter @objectstack/scenarios test gives Test Files 31 passed (31), Tests 608 passed (608), VERDICT command-exit 0. pnpm --filter @objectstack/scenarios typecheck (tsc --noEmit; --listFiles includes test/export/refresh.test.ts) exits 0.
• Lint scoped to the package: eslint packages/qa/scenarios --no-inline-config exits 0.
• Derived gates: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack gives 74 commands, all run on this head, each exit code captured before any pipe. 72 exited 0 on the first pass. Two exited 3, both prerequisites and not reds:
  • check-plugin-teardown-shape --self-test: the clone is shallow. It exits 0 (48 cases) after git fetch --depth=1 of its pinned sha.
  • pnpm check:dual-build-cjs-loads: PREREQUISITE NOT MET. It exits 0 (122 entry points across 72 packages) after the full turbo run build under the lock.
  • --ran: 74 derived famil(ies) accounted for — 74 run, 0 NOT-MEASURED.
• Also run, outside the derivation: pnpm --filter @objectstack/spec run check:error-code-provenance exits 0. check-changeset-no-major --base origin/main against this body exits 0 (LEVEL AXIS … clause-② yes … patch).
• Dogfood battery: n/a. There is no ! in the title and no (narrowing) arm.
• No live model run (paused by the maintainer, cloud#3600). No network in the tests: npm is a stub, git is local with a bare remote, and the run step is the fixture's recorded crm run.
• CI families are read from this PR's check-runs, not re-run here.

The 74 derived gates, as run

node scripts/check-adr-0087-registration.mjs --base origin/main :: exit 0
node scripts/check-adr-0087-registration.mjs --self-test :: exit 0
node scripts/check-changeset-no-major.mjs --base origin/main :: exit 0
node scripts/check-closing-keyword-parity.mjs :: exit 0
node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0
node scripts/check-comment-mask-adoption.mjs :: exit 0
node scripts/check-comment-mask-adoption.mjs --self-test :: exit 0
node scripts/check-comment-mask-corpus.mjs :: exit 0
node scripts/check-console-intercept-disarm.mjs :: exit 0
node scripts/check-console-intercept-disarm.mjs --self-test :: exit 0
node scripts/check-dts-emitted.mjs --self-test :: exit 0
node scripts/check-empty-changeset.mjs --base origin/main :: exit 0
node scripts/check-empty-changeset.mjs --self-test :: exit 0
node scripts/check-issue-citations.mjs :: exit 0
node scripts/check-osv-exemptions.mjs :: exit 0
node scripts/check-osv-exemptions.mjs --self-test :: exit 0
node scripts/check-plugin-teardown-shape.mjs :: exit 0
node scripts/check-plugin-teardown-shape.mjs --self-test :: exit 0
node scripts/ci/assert-turbo-remote-cache.mjs --self-test :: exit 0
node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0
node scripts/ci/prune-turbo-cache.mjs --self-test :: exit 0
node scripts/ci/snapshot-next.mjs --self-test :: exit 0
node scripts/docs-audit/check-affected-docs.mjs :: exit 0
node scripts/docs-audit/check-drift-comment.mjs :: exit 0
node scripts/osv-base-relative.mjs --self-test :: exit 0
node scripts/pm/release-rehearsal-clone.mjs --self-test :: exit 0
node scripts/release-pending-publish.mjs --self-test :: exit 0
pnpm --filter @objectstack/spec run check:duration-unit-keys :: exit 0
pnpm --filter @objectstack/spec run check:llms-txt :: exit 0
pnpm check:changeset-fixed :: exit 0
pnpm check:changeset-gate-self-tests :: exit 0
pnpm check:ci-filter-parity :: exit 0
pnpm check:closed-ceremony-text :: exit 0
pnpm check:cross-package-test-inputs :: exit 0
pnpm check:doc-authoring :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:dts-closure :: exit 0
pnpm check:dual-build-cjs-loads :: exit 0
pnpm check:engine-double-contract :: exit 0
pnpm check:gitlink-declared :: exit 0
pnpm check:issue-citations :: exit 0
pnpm check:keyed-text-bounds :: exit 0
pnpm check:lean-entry-closure :: exit 0
pnpm check:logger-receiver-detach :: exit 0
pnpm check:manifest-repository-directory :: exit 0
pnpm check:merge-driver :: exit 0
pnpm check:nul-bytes :: exit 0
pnpm check:object-def-param-keys :: exit 0
pnpm check:objectql-double-limit :: exit 0
pnpm check:optional-error-sink :: exit 0
pnpm check:org-identifier :: exit 0
pnpm check:override-consistency :: exit 0
pnpm check:page-declaration-shape :: exit 0
pnpm check:platform-object-tenancy-census :: exit 0
pnpm check:pnpm-flag-spellings :: exit 0
pnpm check:published-files :: exit 0
pnpm check:query-options-erasure :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:registry-log-declared :: exit 0
pnpm check:rest-log-spy-declared :: exit 0
pnpm check:slot-lookup :: exit 0
pnpm check:sourcemap-no-sources-content :: exit 0
pnpm check:system-context-census :: exit 0
pnpm check:test-source-alias :: exit 0
pnpm check:tier-file-adoption :: exit 0
pnpm check:turbo-task-graph :: exit 0
pnpm check:type-check-coverage :: exit 0
pnpm check:type-check-debt :: exit 0
pnpm check:undeclared-dep-imports :: exit 0
pnpm check:vendor-export-contract-resolve :: exit 0
pnpm check:vouch-for-reference-callers :: exit 0
pnpm check:watch-hint-literal :: exit 0
pnpm check:where-matcher :: exit 0
pnpm check:workspace-manifest-cycles :: exit 0

patch changeset .changeset/31121-scenarios-gallery-refresh.md (published @objectstack/scenarios; minor is refused by the launch-window guard), with both declaration lines.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/scenarios, touching 32 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/qa/scenarios/README.md, packages/qa/scenarios/src/export/index.ts, packages/qa/scenarios/src/runner/driver.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/frontend/cli.mdx (via index.json (literal, a string literal in exporterPath; a string literal in galleryRefresh; a string literal in readGalleryVersions))

What this run could not see

• 3 changed file(s) yielded no anchor (packages/qa/scenarios/README.md, packages/qa/scenarios/src/export/index.ts, packages/qa/scenarios/src/runner/driver.ts) — pages documenting those are invisible to this run
• 19 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 63 of 226 client-bound route-ledger rows — the other 163 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 163: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 59 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 104 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 — 0 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 0f254f474588916ccd3d61450a35adb531d0416f → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 0f254f474588916ccd3d61450a35adb531d0416f

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

[objectstack-fleet]

domain:devx#3 · os-project-manager · session_01FEkQ5njkh3xbcDN6EtSfw7

Contract review

Served-tier: TIER_DEFAULT
Head-sha: de7c89c59fdbf78cd6421ea0e33309997baa5a40
Local-runs: none
Scope: .changeset/31121-scenarios-gallery-refresh.md, packages/qa/scenarios/README.md, packages/qa/scenarios/package.json, packages/qa/scenarios/src/export/cli.ts, packages/qa/scenarios/src/export/index.ts, packages/qa/scenarios/src/export/refresh-cli.ts, packages/qa/scenarios/src/export/refresh.ts, packages/qa/scenarios/src/runner/driver.ts, packages/qa/scenarios/test/export/refresh.test.ts + packages/qa/scenarios/src/export/exporter.ts, packages/qa/scenarios/src/export/manifest.ts, packages/qa/scenarios/src/export/generic.ts, packages/qa/scenarios/src/export/screenshots.ts, packages/qa/scenarios/src/export/source.ts, packages/qa/scenarios/src/runner/cli.ts, packages/qa/scenarios/tsup.config.ts, packages/create-objectstack/src/pkg-utils.ts, .changeset/config.json

Face: declaration. record-recognisers --template --paths on the nine files says the paths decide no face and the committed changeset's Clause-②: line decides; readClause2Line (clause2-line.mjs) reads that line as declared, value yes, no arm, so the review is owed by the Clause-②: yes line alone and stands at TIER_DEFAULT. @objectstack/scenarios is published (PR #31221); its ./export entry (src/export/index.ts, tsup entry export) now re-exports refresh.ts. Read against main: base 7c523aa1; origin/main is three commits past it (0f254f47, 007fdb1a, 7fe019f4), none under packages/qa/scenarios.

① Derived judgments

• Entry point, as the order rules it (refresh-cli.ts, package.json) — right. pnpm --filter @objectstack/scenarios gallery-refresh --gallery DIR [--cards DIR] [--model M] [--debut] [--work DIR] [--chromium PATH], one package script over tsx src/export/refresh-cli.ts. It is not a bin and not an exports key; files stays dist, README.md, CHANGELOG.md, so refresh-cli.ts is not packed and the command runs from a checkout only, which is where D2's scheduled task runs it. --gallery required, --model refuses an empty or flag-shaped value exactly as run-scenarios --model does (PR feat(scenarios): run-scenarios --model / --author-model / --ask-model, with the served model recorded per turn #31204), an unknown flag is refused (--push is the pinned example). The library half (galleryRefresh) is exported through ./export, the CLI half is not.
• The version check (refresh.ts steps 2–3) — right, and the equality it relies on holds by construction. npm's latest dist-tag of @objectstack/cli is read through npm view behind an injectable latestVersion (the only network call in the module); a value that is not MAJOR.MINOR.PATCH is refused before anything runs. The skip reads the per-app framework.version of every listed app (the GalleryIndexSchema is strictObject and carries no top-level version), and fires only when the index lists at least one app and every app states latest. The per-app value is the raw @objectstack/spec dependency string of the scaffolded project (projectFrameworkVersion, source.ts), which create-objectstack rewrites to the exact version with no range (syncObjectStackDeps, pkg-utils.ts), and @objectstack/cli, @objectstack/spec and create-objectstack are all in the one fixed group of .changeset/config.json (110 packages), so npm's latest cli version IS the spec version the run installs. The post-export refusal "an exported app states another framework version" can therefore fire only on a broken release, which is when it should.
• Run, export, commit (refresh.ts steps 5–8) — right. runnerArgv emits --only CARDS --modes scratch --packages published --create-version V --out --work --record [--model] [--cards], pinned by parsing it with the runner's own parseArgs (createVersion, packages: 'published', modes: ['scratch'], iterateRun: true). The export goes into DIR through exportGallery with the same guard and recordings the export-gallery CLI uses. Then three refusals before any git write: no app exported (naming the exporter's reasons), a listed app on another version, any changed path outside apps/ and index.json. Then git switch -c export/V, git add --all -- apps index.json, a diff --cached --quiet guard, git commit under the checkout's own identity. The commit's parent is the checkout's HEAD when the refresh started, pinned (HEAD^ equals the base).
• Never pushes, never talks to GitHub — read, not taken on trust. Every git invocation in refresh.ts is rev-parse --show-toplevel, status --porcelain, rev-parse --verify refs/heads/..., for-each-ref refs/remotes/*/..., switch -c, add, diff --cached, commit, rev-parse HEAD. No push, fetch, remote, checkout, reset or clean; refresh-cli.ts adds only mkdtempSync, mkdirSync and the rmSync of its own temp directory on a skip. The only process outside git is npm view. The test pins the bare remote's refs byte-identical before and after a commit and a skip.
• Writes only inside DIR, and never over the caller's work. The exporter writes under outDir = DIR (its own apps/ID directories, staged and renamed, and index.json); the run writes under --work (the caller's directory or a fresh temp dir), which is outside DIR by design and holds records, projects and the recording, never gallery files. A dirty checkout, untracked files included, is refused before the npm read; a local export/V branch is refused, never reused or reset; a refusal after the export leaves the tree dirty on the caller's branch, uncommitted, and the README says exactly that. Nothing is checked out over, reset or deleted other than app directories the previous index listed, which is the exporter's rule on main (PR feat(scenarios): a gallery exporter writes verified, generic scenario apps to a local directory in the layout of objectstack-ai/gallery #30930), not this PR's.
• --debut — right. One card, the first eligible id (today asset_lifecycle, the first of the six starter cards; the three control cards are refused by GALLERY_GUARD), only into a gallery whose index lists no app; the refusal into a listed gallery is an addition the card does not forbid and is pinned (ablation A2).
• driver.ts — a comment-only hunk. All eleven changed lines are inside the header comment: "a LOCAL Claude Code session …, never a cloud agent" becomes the D2 reading (a local session on the developer's login, or a scheduled Claude Code task in the project's cloud environment on the maintainer's subscription login; an API-billed model still never). ClaudeCodeDriver's refusal of ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN and the strip from spawned children are untouched.
• cli.ts — no behaviour change. The live screenshot wiring moves into liveScreenshots(chromium?); main(argv, deps) keeps its signature and its deps.screenshots ?? live order. The one observable difference is that playwrightBrowser(...) is no longer constructed when screenshots are off or a test double is given; playwrightBrowser does all its work inside open() (the playwright-core import and the launch), so constructing it did nothing. liveScreenshots is a new export of cli.ts, which is on no tsup entry: internal.
• Tests (refresh.test.ts, 17 cases) — no network, no live model, no browser, as the order rules. Every galleryRefresh / main call hands a latestVersion stub (npmLatestVersion is never reached), screenshots: false, and a run that drives the real crm card through runCard with the fixture's scripted model inside RecordingDriver (fixture.ts). Git is a real local repository with a bare origin. The five ablations named in the PR body each remove one refusal and are the right five (version, debut, skip, stray path, dirty tree).
• README — the three asks are there. The gallery-refresh section, the runbook's "what it runs / what it needs / what it never does", and the task's prompt verbatim (clone, run detached, push only export/V, one PR, one deduplicated Gallery refresh failed issue). Runbook step 2 builds '@objectstack/scenarios^...' (the dependencies, not the package), which is enough because gallery-refresh runs tsx over src/.

② Semver level

patch is correct. Ruling A in check-changeset-no-major.mjs grades by the protocol line alone: Metadata-protocol: none means patch, and a minor beside none is refused (the launch-window guard). Clause-②: yes with no arm is the right spelling: the ./export subpath widens from 69 to 84 names (counted as export declarations over the barrel's eight files on main and nine on the head; refresh.ts contributes exactly the 15 the PR body lists, nine values and six types), nothing is removed, renamed or retyped on ./export, ., ./runner or ./score*, cli.ts's main keeps its signature, no bin is added and package.json adds one script. No (narrowing) arm and no BREAKING banner is owed; the face stays declaration and the tier TIER_DEFAULT. The changeset carries both declaration lines; the em-dash prose after yes reads as declared / yes / no arm through the fleet's reader. Check Changeset is green on this head.

③ Boundary flags

• Premise deviation: no top-level framework.version in index.json — faithful. The card's "when they are equal → skip" presumes one version; the exporter's strict schema carries it per app, and the dev added no index field (which would change the format objectstack-ai/gallery: a read-only check workflow on every PR (index schema, complete app directories, no stray files) and a PR-only main, before the scheduled export writes there #31122's check reads). "Equal" is read as ALL listed apps equal, with at least one listed. That is the right reading for a daily refresh: ANY would freeze a straggler app forever, while ALL is safe because a full run rewrites every passing app at latest and removes every failing one (the exporter's kept arm exists only for screenshots: false, which the refresh never passes in production), so one successful run ends with every listed app at latest. Edge cases, each read: an empty or absent index runs (an empty gallery is on no release); a mixed index runs, and after the run every app is at latest or removed; a prerelease on npm latest is a refusal (exit 1), so the scheduled task comments on the one Gallery refresh failed issue each day until the dist-tag is corrected, which is the right surfacing of a release incident rather than a quiet skip.
• The remote-tracking export/V skip is an addition — sound, one wording should-fix. Without it every daily run while the gallery PR awaits review would spend hours of subscription quota and then fail to push an existing branch. It reads only the clone's remote-tracking refs (refs/remotes/*/export/V, one component for the remote name, pinned as origin/export/18.3.0), no network. Edge: a gallery PR closed unmerged whose branch survives holds the skip for that version until the branch is deleted; the skip line says "awaits review" and does not name that remedy. Should-fix (wording): have the line say the branch must be deleted to run again.
• After the debut the gallery skips until the next stable release; the README does not say so. The PR body's acceptance note states it; the runbook the maintainer reads does not. Should-fix (one sentence in the README's gallery-refresh section). The design question itself is in ④.
• Report status done with an open question, where the order asks needs_decision for a decision outside the rulings. The dev implemented the rulings exactly as written (no force flag is named) and raised whether to add scope; done is defensible, the question is the seat's, no escalation.
• Deviations 1 and 2 in the report (no labels, no assignees on pr_create). Not a contract matter; the seat labels at landing, as on feat(scenarios)!: cards declare user-handle fields and persona records; seed dependence is decided per turn #31275.
• Check-runs on this head at the time of this read: 33 success, among them Lint & Repo Gates, TypeScript Type Check, Build Core, Test Core shards 3–8, Governed Surface Queue Guard, Check Changeset, Type Check · workspace, the PR-body guards and Check PR Size; 13 skipped (UI, docs, dogfood shards and the opt-in harnesses, none owed by this diff); Test Core (1/8) and (2/8) still in progress. Landing waits for those two.
• Overlap with fix(scenarios): the seed owns a row only by a person the row names, and fills each persona record’s user #31309 (claude/project-thread-zbvjqe) on packages/qa/scenarios/README.md: no textual conflict. fix(scenarios): the seed owns a row only by a person the row names, and fills each persona record’s user #31309 rewrites the persona-contract bullet at lines 253–262; this PR inserts a new section after line 266. git merge-tree --write-tree of the two heads writes a tree and exits 0. fix(scenarios): the seed owns a row only by a person the row names, and fills each persona record’s user #31309's other files (test/runner/*.test.ts and runner sources) are untouched here. Whichever lands second rebases without a hunk to resolve.
• Live model run not measured (maintainer pause, cloud#3600): the chain is proved on the fixture's recorded crm run; the first real debut is the scheduled task's first run, by design.
• No security findings, no out-of-scope findings in the report.

④ Design judgment

The declaration face owes no ④; this is the lane seat's judgment offered on the points the brief asked for.

• The chain is deterministic and loud. Every exit is one of three: a one-line skip (exit 0, nothing run), a commit on a fresh local branch, or a refusal that names its reason and leaves no half-state the next run cannot see (a dirty tree or a local branch, both refused on the next run with the remedy in the message). The order of checks spends nothing before it has to: checkout and index first, then one npm view, then the two skips, then the cards, and only then hours of model time. The post-export refusals compare the result to what was asked for (the release, the owned paths) rather than trusting the run.
• The open question — keep as is (A), along the four axes.
  • Real need: the only scenario B serves is "the maintainer wants the full gallery at the debut's version before the next stable release". Releases in this fixed group are frequent (the whole group moves together on every publish), so the wait is short and measured in days, and the need is one-off by definition.
  • Long-term soundness: the skip rule is the contract that makes a daily task safe to run unattended; a flag that disables it turns the task's idempotence into a parameter. The need is already met without any new surface: run-scenarios and export-gallery have no skip and are the two steps gallery-refresh composes, so a maintainer who wants the full gallery at V today runs them by hand and commits, exactly as before this PR. The escape hatch exists; a second one adds nothing but a way to misuse the first.
  • Making AI mistakes structurally harder: the scheduled task is an AI following a prompt. Today the prompt has no spelling that can run every card twice at one version; with --force in the vocabulary, one misread of "the gallery looks stale" spends hours of the maintainer's subscription quota and opens a duplicate PR. The absence of the flag is the guard.
  • Startup-stage scope: a new flag defaults to no, the ruling names none, and no maintainer sentence asks for one. The stateless debut (the prompt adds --debut whenever the index lists no app) is the right companion: it needs no memory and no second mode.
    So A, with the one README sentence in ③ so the day-after skip is expected rather than puzzling. If the maintainer does want the full gallery before the next release, the answer is the two manual commands, not a flag.
• The remote-branch skip is the right kind of addition. It is a cheaper, quieter outcome on a state the card did not enumerate (a pushed branch awaiting review), it reads only local refs, and it refuses rather than overwrites when the branch is local. The one gap is the wording named in ③.
• Nothing speculative. --work and --chromium mirror the existing CLIs; --cards DIR keeps the meaning it has in both sibling commands rather than acquiring a second one (card ids), which the PR body rightly calls a trap; scratch mode only is what the exporter's pass rule already owes. The library exports are the pieces a caller would need to drive the same chain from code (the plan, the body, the skip reading), none is a hook for another mode.

Implemented-by: claude/project-thread-3d8sgq
Reviewed-by: session_01FEkQ5njkh3xbcDN6EtSfw7

VERDICT: PASS

[objectstack-fleet]

domain:devx#3 · os-project-manager · session_01FEkQ5njkh3xbcDN6EtSfw7

席位核对

Verdict: ACCEPT · head de7c89c59fdbf78cd6421ea0e33309997baa5a40 · card #31121 · report 6715227221 · contract review 6715336052 (PASS, declaration face, TIER_DEFAULT).

• Shape: draft → main, 9 files, +911/-10, all inside packages/qa/scenarios/** plus one changeset. NOT governed. main is 3 commits past the base, and none touch packages/qa/scenarios. fix(scenarios): the seed owns a row only by a person the row names, and fills each persona record’s user #31309 shares only the package README, on different hunks, and git merge-tree shows no conflict.
• Order, read in the diff: this is the repo half only. The entry is gallery-refresh --gallery DIR [--cards …] [--model ALIAS] [--debut]. It reads the npm latest-stable version through an injectable reader, stubbed in every test.
  • Skip rule: it skips quietly only when every listed app is at that version.
  • Otherwise: it runs, exports and commits on a local export/<version> branch.
  • Never pushes: the reviewer read every git call, and there is no push, fetch, remote, reset or checkout. A dirty tree and an existing export/<version> are both refused.
  • Debut: --debut exports one card.
  • Also delivered: the driver.ts header names D2, and the README carries the runbook.
• Premise deviation (no top-level framework.version in index.json, so the skip reads every app's version): faithful. ALL-equal is the safe reading, because ANY-equal would freeze a straggler. An empty index runs, and a prerelease on latest is refused loudly.
• Open question (--force after a debut): seat ruling, keep as is, no flag. A new flag defaults to no. The escape hatch already exists with no new surface: run-scenarios plus export-gallery run by hand. The flag's absence keeps an unattended task from spending quota on a misread.
• Clause-②: yes. ./export gains 15 names (69 → 84), all from refresh.ts. No existing export changes: cli.ts extracts a helper and keeps main's signature, and the driver.ts hunk is comments only. No bin, and files is unchanged. patch with Metadata-protocol: none is correct.
• Gates: local, 74/74 derived gates exit 0, and 5 ablations went red and were restored. Automerge waits for the required check-runs on this head.
• Wording nits, not blocking, for the next PR that touches the README:
  • Say in the runbook that after --debut the gallery skips until the next stable release.
  • Say that a gallery PR closed unmerged with its export/<version> branch kept holds the skip until that branch is deleted.
• Landing: under 「按照 pm-dispatch 规则复核过的都授权」 (2026-10-25T11:35Z) and 「你应该使用 pm-dispatch 技能审核和落地pr」 (2026-11-07T16:59Z): pr_ready + automerge_enable now.