[objectstack-fleet]

Requested by Steedos · project thread
Fixes #337
Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么： 仓根新增两个钉文件 .objectstack-sha（钉在 @objectstack/cli@17.7.0 发布提交）与 .cloud-sha（占位 unpinned），新增 bump-upstream-docs.yml 工作流与其脚本：每次挪一个钉点，开一个 PR，正文列出上游自上次钉点以来的提交与变更路径；AGENTS.md 加一段说明钉点与 bump 节奏。
• 为什么改： 本站与 objectstack、cloud 的对齐此前靠 AI 定期全量重读；钉点把它变成「读一个有界 diff」（Sync cloud's content/docs/ into this site and pin both upstreams (objectstack, cloud) so alignment is a bounded diff review, not a periodic re-read (cloud#3199 ruling D) #337，按 2026-10-27 重新划定的范围：只留钉文件、bump 工作流、AGENTS.md 一段）。
• 风险与回滚： 不碰站点渲染与部署链路；新工作流只在手动或 repository_dispatch 时开 PR，PR 上只跑自检。回滚 = revert 本 PR。
• 先看： .github/workflows/bump-upstream-docs.yml（令牌用法与拒绝条件）、.github/scripts/bump-upstream-pin.mjs 的 bump()（祖先校验、取路径）、AGENTS.md 新增的「Upstream pins」一段。
• 两分钟验证： node .github/scripts/bump-upstream-pin.mjs --self-test && node .github/scripts/bump-upstream-pin.mjs --check，应见自检通过、两个钉文件各一行 ✓。
• 需要你做的： 审批本 PR（AGENTS.md 是受管面，需 GOVERNED_APPROVERS 账户批准后由席位落地）。设 UPSTREAM_BUMP_TOKEN 是合并之后跑 bump 才需要的，见 Acceptance notes。

What changes

• .objectstack-sha = 4e4e881427a8b8b57696ad5bdb12792f2dac6556, the commit tagged @objectstack/cli@17.7.0. The site's own changelog (content/docs/resources/changelog.mdx, since docs: Build, API and operations pages up to ObjectStack 17.7 #333) names 17.7.0 as the current release, so that is the commit the site was last aligned to. npm's latest is now 18.2.0, so the first objectstack bump is a real, non-empty review (measured below: 570 commits, 243 paths).
• .cloud-sha = the placeholder unpinned. objectstack-ai/cloud is private and not reachable from the session that wrote this PR, so no commit could be read or verified. The helper accepts the placeholder in a pin file but never starts a range from it: the first cloud bump records the commit its production deploy serves and lists nothing; the next one is the first bounded diff.
• .github/workflows/bump-upstream-docs.yml — workflow_dispatch (upstream: objectstack or cloud, optional sha) and repository_dispatch of type bump-upstream-docs with client_payload: { upstream, sha }. Moves one pin, opens a PR titled chore(upstream): pin NAME to … whose body lists the upstream commits and changed paths since the previous pin: objectstack content/docs, docs/releases, CHANGELOG.md (paths absent at both pins are named as not read; docs/releases is absent today); cloud CHANGELOG.md, .changeset/. On a PR touching the pins, the helper or the workflow, a pins job runs the self-test and --check.
• One secret, UPSTREAM_BUMP_TOKEN; the bump refuses to start without it (::error title=NOT CONFIGURED::…). GITHUB_TOKEN cannot read cloud, and a PR opened with GITHUB_TOKEN triggers no pull_request workflows, so CI would never run on a bump. Whether this repository lets Actions open PRs at all is NOT MEASURED: the Actions-permissions endpoints answer 403 through this session's proxy, and no PR here has ever been opened by github-actions.
• .github/scripts/bump-upstream-pin.mjs — resolves the target (objectstack with no sha: npm's latest @objectstack/cli, then its tag's peeled commit; cloud: sha required), fetches the upstream blobless, refuses a non-descendant, a malformed pin, a short SHA or a ref name, and writes the pin and the body. The body keeps both lists in text fences, so upstream (#NNNN) references neither link to this repository's issues nor act as closing keywords here, and caps itself under GitHub's 65536-character limit with the omitted count stated. The token reaches git only through GIT_CONFIG_* variables.
• tools/ci-scripts/run-self-tests.mjs — one SELF_TESTED entry plus a header paragraph; its guard fails the build job for an unlisted top-level self-test. File-surface extension confirmed by the seat (card comment 6442760321).
• AGENTS.md — one paragraph, ## Upstream pins: what each pin means, when it moves, "don't edit a pin by hand", what the bump body lists, and the placeholder.

Tests

• --self-test: 17 pin/input cases plus upstream names (including __proto__/toString), tag peeling, plan, body bounds and fencing, token carriage. Proven able to go red by three on-disk mutations, each restored byte-identically (sha256 compared): fence escaping removed, the same-commit no-op removed, the SHA rule widened to 7 characters — each exits 1 naming the check.
• Real runs against objectstack-ai/objectstack (blobless fetch, about 5 s, 65 MB): 17.7.0 to 18.2.0 resolves through npm and the tag, 570 commits, 243 paths, body 59564 characters with 248 commit lines cut and stated.
• Refusal paths, each exit 1 with the reason: missing pin file; non-descendant (--sha older than the pin, pin left unchanged); cloud with no sha; cloud with no token (fetch refused, hint names UPSTREAM_TOKEN); unknown upstream; sha = main; abbreviated pin under --check. Same commit again: exit 0, changed=false, no body.
• The bump job's three run: steps executed locally from the parsed YAML against a local bare origin, with a shim for gh: secret absent exits 1 with NOT CONFIGURED; secret present commits only .objectstack-sha as github-actions[bot], pushes bump-upstream-docs/objectstack-27f38ad, calls gh pr create --base main --head … --title … --body-file …; a rerun with that branch already pushed exits 1 naming it. actionlint is NOT MEASURED (download refused in this container); every run: block passes bash -n and the YAML parses.

Acceptance notes

• Open for the maintainer: set UPSTREAM_BUMP_TOKEN; and set the first .cloud-sha by dispatching a cloud bump with the commit cloud production serves (ideally from cloud's deploy workflow, as a repository_dispatch with { "upstream": "cloud", "sha": "…" }).
• GITHUB_TOKEN may open PRs here stays NOT MEASURED; the design does not depend on it.
• Out of scope, per the re-scope (card comment 6442331663): no sync script, no content/docs/cloud/, no hand-edit gate, no mount point.

Verification

Local gates at 220b106, each exit code captured before any pipe:

Gates

gen-zh-hant --check                          EXIT=0  46 generated file(s) match
npm ci --prefix .github/scripts/doc-samples  EXIT=0
check-doc-samples                            EXIT=0  80 English pages, 102 pass
check-translations                           EXIT=0
tools/ci-scripts/run-self-tests.mjs          EXIT=0  12 self-test(s) passed
bump-upstream-pin --check                    EXIT=0
check-translation-ownership (diff, fleet)    EXIT=0  0 translation artifacts, 6 other files
pnpm turbo run type-check test               EXIT=0  VERDICT command-exit 0
pnpm turbo run build                         EXIT=0  VERDICT command-exit 0, 0 cached
check-locale-surface                         EXIT=0
check-positioning                            EXIT=0
check-search-locales                         EXIT=0  8 locales

The local preview render smoke is not owed: nothing under apps/docs or content/docs changes.

---

Generated by Claude Code

[objectstack-fleet]

维护者速读

• 改了什么： 仓根新增两个钉文件：.objectstack-sha 钉在 @objectstack/cli@17.7.0 的发布提交，.cloud-sha 暂为占位 unpinned。新增 bump-upstream-docs.yml 工作流及其脚本：每次挪一个钉点并开一个 PR，正文列出上游自上次钉点以来的提交和变更路径。AGENTS.md 加一段，说明钉点与 bump 节奏。
• 为什么改： 本站与 objectstack、cloud 的对齐，此前靠 AI 定期全量重读。钉点把它变成审一个有界 diff（Sync cloud's content/docs/ into this site and pin both upstreams (objectstack, cloud) so alignment is a bounded diff review, not a periodic re-read (cloud#3199 ruling D) #337，按 2026-10-27 重划的范围）。
• 风险与回滚： 不碰站点渲染和部署链路。新工作流只在手动触发或 repository_dispatch 时开 PR；PR 上只跑自检和格式检查。回滚 = revert 本 PR。
• 先看： .github/workflows/bump-upstream-docs.yml（令牌用法和拒绝条件），以及 AGENTS.md 新增的「Upstream pins」一段。
• 两分钟验证： node .github/scripts/bump-upstream-pin.mjs --self-test && node .github/scripts/bump-upstream-pin.mjs --check，应看到自检通过，两个钉文件各一行 ✓（席位已在 5e4305e 上复跑，两条都退出 0）。
• 需要你做的： 请 os-zhuang 或 hotlong 批准本 PR（AGENTS.md 是受管面）。批准后由席位落地。

席位意见： 建议批准。范围与 #337 重划后的三项一致，没有多余文件。合并后、第一次 bump 之前，还要在本仓设好 secret UPSTREAM_BUMP_TOKEN：它要能读 cloud，并能在本仓推分支、开 PR。没设时 bump 会直接报 NOT CONFIGURED，不会静默失败。cloud 钉点等 cloud 部署第一次发来 repository_dispatch 才会落下。

席位核对 · ACCEPT · 2026-10-27T13:29Z · session_01QsR2jTaZ2GeyfjANMwstiw · seat repo:docs.objectos.ai#1

1. Shape. Draft PR against main, head 5e4305e, 6 files +699/−0. The body's first card line is Fixes #337, after the attribution block. Clause-②: no and Metadata-protocol: none are copied from claim 6442684968. Two commits, both with model-free and card-free trailers.
2. Premise, measured by the seat. git ls-remote on objectstack: refs/tags/@objectstack/cli@17.7.0^{} = 4e4e881427a8b8b57696ad5bdb12792f2dac6556, the pinned value. The cloud repository is not reachable from this project, so the placeholder is the honest value. The helper refuses to start a range from it.
3. Gates, check-runs at head 5e4305e. build success · Node floor success · Ownership & freshness success · Upstream pins are well-formed success · Deploy docs skipped (PR event) · Bump an upstream pin skipped (dispatch-only). Seat re-ran --self-test (17 cases ✓) and --check (both pins ✓) on that head; both exit 0.
4. Accepted deviations. actionlint is NOT MEASURED (download refused in the dev container); the dev executed the bump job's run: steps against a bare origin with a gh shim instead. Whether GITHUB_TOKEN may open PRs here is NOT MEASURED, and the design does not depend on it. The body's gate block cites 220b106; 5e4305e only renames the bump job, and the dev re-ran the self-test, --check and bash -n there.
5. Diff read. Event values reach the job only as env vars and are validated in the helper (UPSTREAMS allow-list, 40-hex SHA). The branch name and pin path derive from the validated name. The token rides in masked GIT_CONFIG_*, never on a command line. Checkout uses persist-credentials: false. Action versions match the rest of this repository's workflows. tools/ci-scripts/run-self-tests.mjs gains one SELF_TESTED entry, inside the amended surface (6442760321).
6. Out of scope / landing. open_questions (1) the UPSTREAM_BUMP_TOKEN secret and (2) the first cloud pin are the maintainer's, named in 席位意见. Out-of-scope findings: none. Tier H (AGENTS.md): the PR stays draft. needs-user-decision is added and review is requested from GOVERNED_APPROVERS in the same stroke. After an authorized APPROVED review, the seat lands it by squash merge pinned to the approved head, once the previous main run has published and smoke-checked green (#9831 §6).

[objectstack-fleet]

Seat record · landing authorization · 2026-10-28T06:46Z · session_01QsR2jTaZ2GeyfjANMwstiw · seat repo:docs.objectos.ai#1

Tier H. No review from os-zhuang or hotlong arrived. On 2026-10-28 at 06:45:30Z the maintainer (Steedos, zhuangjianguo) chose "两个都合并" in the project thread. The card asked "#348 和 #355 现在直接合并吗?", and that choice is the authorization this landing rests on. GitHub's main ruleset requires 0 approvals.

• Landing head: 5e4305e, the head the seat ACCEPTed in 6443134067. It has not changed since. mergeable_state is clean and the required checks are green.
• Steps: clear needs-user-decision, mark the PR ready, then land it through the merge queue (squash). The landings run one at a time: chore(upstream): pin objectstack and cloud, and a bump-upstream-docs workflow that lists the upstream diff since the last pin #348 first, then docs: the Chinese terms page says ObjectOS Community is open source; links follow the repository rename #355 after chore(upstream): pin objectstack and cloud, and a bump-upstream-docs workflow that lists the upstream diff since the last pin #348's main deploy passes its smoke check.