Skip to content

Commit 9657318

Browse files
docs: scaffold examples pin exact; verify README names the scheduled-work switch (#25659)
Part of #25510 Clause-②: no Metadata-protocol: none These are two docs fixes the devx lane owed, with no code change. ## What changed - **`content/docs/protocol/kernel/plugin-spec.mdx`** - The plugin `package.json` example now pins `@objectstack/core` and `@objectstack/cli` to exact `18.0.0`. Before, it showed `^17.0.0`. - The paragraph under it now says the scaffolders pin each `@objectstack/*` dependency exactly to the generating CLI's version (`getCliVersion()`), never as a caret range. That is what PR #25539 made them write. - **`content/docs/upgrading.mdx`, step 2:** a project scaffolded since 18.1.0 is exact-pinned. A project on a caret range (`^18.0.0`, what older scaffolds wrote) still moves at the lockfile step. - **`packages/verify/README.md`:** after the `flows.run(…, { system: true })` passage, the README now says three things: - that call works with scheduled work off; - a local stack arms time-triggered flows on their own cadence only with `OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true`; - package-authored scheduled work is off by default in every posture. The #25442 evaluation read "disabled by deployment policy" on a local verify stack with the variable unset. Ruling D on that card asked for this sentence to ride the next docs PR. - **`.changeset/25442-verify-readme-scheduled-work.md`:** a patch for `@objectstack/verify`, because `README.md` ships in its tarball (`files`). Sources were read on `main` at the time of writing: - `packages/cli/src/commands/init.ts:37` (`getCliVersion`) and `:57` (`pkgVersion`); - `packages/cli/src/commands/create.ts:166` (`objectstackDependencySpec`); - `content/docs/deployment/environment-variables.mdx:103`. ## Out of scope The rest of #25510 is the template baseline and `scripts/sync-template-versions.mjs`. That work is in its own card thread, whose PR carries `Fixes #25510`. This PR only says `Part of`, so the Duplicate Fix Guard is not engaged. ## Local verification Run on `origin/main` `baae6ed14e` plus this commit: - `node scripts/pm/dispatch-gates.mjs --ran`: 88 derived families accounted for, 79 run (all exit 0), 9 NOT MEASURED. - The 9 NOT MEASURED families need build artifacts this worktree does not have (`json-schema`, `dist`): - `check:dts-closure`, `check:dual-build-cjs-loads`, `check:lean-entry-closure`, `check:sourcemap-no-sources-content`, `check:docs-transcript-drift`; - the spec `check:docs` and `check:skill-examples`; - the lint `check:doc-formula-expressions` and `check:doc-security-posture`. None of them reads the three edited files. CI runs them. - The docs families ran and passed: `check:doc-authoring`, `check:doc-anchors`, `check:docs-single-h1`, `check:published-readme-links`, `check:docs-redirects`, `check-doc-frontmatter` and `check-issue-citations`. --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01LKHDniRQSWjRJyDtacwpEd Co-authored-by: Claude <noreply@anthropic.com>
1 parent 2c523d0 commit 9657318

4 files changed

Lines changed: 31 additions & 9 deletions

File tree

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/verify': patch
3+
---
4+
5+
docs(verify): the README says how a local stack arms scheduled flows
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
The README's `flows.run(…, { system: true })` passage now says that this call works with scheduled work off. It also says that a local stack only arms time-triggered flows on their own cadence when `OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true` is set; package-authored scheduled work is off by default in every posture.
11+
12+
What to do: nothing. Only the packaged README changes.

‎content/docs/protocol/kernel/plugin-spec.mdx‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -716,11 +716,11 @@ Plugins are distributed as **NPM packages** for easy versioning and distribution
716716
],
717717

718718
"dependencies": {
719-
"@objectstack/core": "^17.0.0"
719+
"@objectstack/core": "18.0.0"
720720
},
721721

722722
"devDependencies": {
723-
"@objectstack/cli": "^17.0.0",
723+
"@objectstack/cli": "18.0.0",
724724
"typescript": "^5.3.0"
725725
},
726726

@@ -739,12 +739,15 @@ Plugins are distributed as **NPM packages** for easy versioning and distribution
739739

740740
The `typescript` floor above mirrors `SCAFFOLD_TYPESCRIPT_RANGE` in
741741
`packages/cli/src/commands/init.ts` — that constant, not this snippet, is the
742-
authority the scaffolders emit from. The two `@objectstack/*` ranges have an
742+
authority the scaffolders emit from. The two `@objectstack/*` versions have an
743743
authority in the same file: every `@objectstack/*` package in this monorepo is
744-
published on one shared release version, and the scaffolders caret-pin each
745-
dependency to the version of the CLI that generated the project
746-
(`getCliVersion()`). A hand-written example cannot carry that live value, so it
747-
carries the **current major's floor** — track it when the major moves.
744+
published on one shared release version, and the scaffolders pin each
745+
dependency **exactly** to the version of the CLI that generated the project
746+
(`getCliVersion()`), never as a caret range. A patch on this line can break a
747+
non-protocol surface, so a range would let the next install move you onto a
748+
release you have not read. A hand-written example cannot carry that live value,
749+
so it carries the **current major's first release**, pinned exactly — track it
750+
when the major moves.
748751

749752
### Publishing to NPM
750753

‎content/docs/upgrading.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,9 @@ command for this move; it is four steps you run yourself.
7878
*previous* release's author-time rules over your metadata.
7979
2. **Regenerate the lockfile, and commit it** (`pnpm install` / `npm install` /
8080
`yarn install`). This is the step that actually moves the code. A project
81-
pinned to exact versions moves because step 1 edited the pins; a project on the
82-
scaffold's default ranges (`^17.0.0`) moves entirely here. Read whatever
81+
pinned to exact versions (what the scaffolders write since 18.1.0) moves
82+
because step 1 edited the pins; a project still on a caret range (`^18.0.0`,
83+
what older scaffolds wrote) moves entirely here. Read whatever
8384
peer-dependency warnings this prints — the `--frozen-lockfile` install your CI
8485
runs skips resolution and will never print them.
8586
3. **Check the two protocol declarations your app ships** — `specVersion` in

‎packages/verify/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -351,6 +351,12 @@ await stack.stop();
351351
true })` starts a flow as the system principal through the `automation`
352352
service's own `execute`, the call the schedule trigger's tick makes, never
353353
through the trigger route, and hands back the engine's result unchanged.
354+
That call does not wait for a schedule, so it works with scheduled work off.
355+
For a local stack to arm time-triggered flows on their own cadence (rather
356+
than list them as disabled by deployment policy), set
357+
`OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true` in its environment:
358+
package-authored scheduled work is off by default in every posture (see
359+
Deployment › Environment variables in the docs).
354360
- A refusal from `flows.*` / `actions.run` is the route's ADR-0112 envelope
355361
(`VerifyRefusal`: `code`, `status`, `details`; `isVerifyRefusal(e)`); a
356362
refusal from `hooks.run` / `hooks.updateWhere` / `validate` / `rows` /

0 commit comments

Comments
 (0)