[objectstack-fleet]

Fixes #26088
Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:AGENTS.md 三处贡献者说明改成与代码一致 —— 开发服务端口是默认 3000、不是写死的;pnpm run setup 只装依赖并构建 spec,不是首次完整准备;前端快速迭代段改用文档名 OS_PORT。
• 为什么改:照 AGENTS.md 操作的贡献者或 agent 会以为端口必须是 3000、改不了,并把 pnpm run setup 当作首次准备,随后 pnpm dev 因未构建被拒;README / CONTRIBUTING / getting-started 已在先前一单改好,这一单收尾 AGENTS.md。
• 风险与回滚:纯文档,不发布任何包;行数不变(1112),无新增行;回滚即 revert 这一个 commit。
• 先看:AGENTS.md L138(开发服务表格那一行,改动最大的 hunk);其次 L40 与 L170–171。
• 两分钟验证:grep -n 'hard-wired\|PORT=3000\|pnpm run setup' AGENTS.md,预期只见 L40 新说明、L138 的「not hard-wired」与 OS_PORT=3000、L170 的 OS_PORT=3000,不再出现「must be 3000」。
• 需要你做的:作为 GOVERNED_APPROVERS 审阅并批准(AGENTS.md 属 Tier H 受管面)。

What changes

Three contributor lines in AGENTS.md, each edited in place; no line added or removed (1112 lines before and after).

Line	Before	After	Bytes before → after
L40 (fenced)	pnpm run setup # first-time: install + build spec (...)	pnpm run setup # install + build spec only; pnpm dev needs pnpm build (...)	99 → 123 (fenced line: exempt from the 120-byte prose rule)
L138 (table row)	PORT=3000 pnpm dev · "Port must be 3000 (UI hard-wired)" · PORT=3000 pnpm dev:crm	OS_PORT=3000 pnpm dev · "Port 3000 is the default, not hard-wired: the Console dev proxy targets it unless DEV_PROXY_TARGET says otherwise, and a busy port shifts to the next free one, so read the port it prints (PORT is the legacy alias of OS_PORT)" · OS_PORT=3000 pnpm dev:crm	307 → 506 (widest-row pin is 768, held by L709; unchanged)
L170	... on :3000** (PORT=3000 pnpm dev for	... on :3000** (OS_PORT=3000 pnpm dev	117 → 116
L171	showcase) and browse :5180 ...	for showcase) and browse :5180 ...	114 → 118

The code line that decided each fact:

• Setup. Root package.json:18: "setup": "pnpm install && pnpm --filter @objectstack/spec build", so the line's "install + build spec" was accurate; "first-time" was not. pnpm dev runs scripts/check-dev-prereqs.mjs, which requires every workspace package's dist entry and prescribes pnpm install && pnpm build (scripts/check-dev-prereqs.mjs:579), the same sequence README.md, CONTRIBUTING.md and getting-started give. The line now says what setup does and that pnpm dev needs pnpm build.
• Port. packages/cli/src/commands/dev.ts:481 reads flags.port ?? readEnvWithDeprecation('OS_PORT', 'PORT', { silent: true }), :537 defaults it to '3000', and :562 runs getAvailablePort over the requested port: dev shifts off a busy port even when the port was asked for explicitly (serve.ts:2307, dev mode only). The Console dev server proxies /api to process.env.DEV_PROXY_TARGET || 'http://localhost:3000' (ui/apps/console/vite.config.ts:1509). Nothing is hard-wired; 3000 is the default on both sides.
• Spelling. OS_PORT is the documented name (--port flag help: "overrides $OS_PORT; $PORT is the legacy alias"; content/docs/getting-started/index.mdx:211-212; CONTRIBUTING.md:70-71), so both AGENTS.md command spellings now use it.

Left as is, on purpose: L145 "never run two backends on port 3000". It does not repeat the "hard-wired" claim. With auto-shift it still gives sound advice: a second backend would silently land on 3001 while the proxy keeps hitting the first.

Tests

Docs-only diff to one governed instruction file. No package code changed, so no package test or typecheck is owed and no ablation applies (no tested behaviour moved). Card acceptance grep at 596cd15e: grep -n 'PORT=3000\|OS_PORT\|npx create-objectstack\|npm create objectstack\|pnpm run setup' AGENTS.md matches only L40 (pnpm run setup, now described accurately), L138 and L170 (both OS_PORT=3000); no bare PORT=3000 remains.

Acceptance notes

• examples/README.md:42 carries the same pnpm run setup # first-time: install + build spec label. It is outside this card's file surface (AGENTS.md only) and outside the card's acceptance grep. Noted here, not filed.
• ui/AGENTS.md:221 (Tier H, outside this surface) still spells the legacy PORT=3000 pnpm dev / PORT=3000 pnpm dev:crm. The legacy alias still works (readEnvWithDeprecation), so this is a spelling drift, not a defect. Noted here, not filed.

Verification

All local readings were taken at head 596cd15e (the final commit).

Derived gates came from node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, with no paths and a change set of 1 path vs merge base fbc16563a. It derived 15 gates, and every one exited 0. I also ran three named gates outside the derivation: check:doc-authoring, check-published-list-mirrors and its --self-test.

The --ran reconciliation reports: 15 derived, 15 run, 0 NOT-MEASURED, 0 UNRUN. That zero is derived from recorded exit codes.

pnpm check:pm-skill-ratchet exits 0. Its reading for AGENTS.md: "1112 lines (ceiling 1112; headroom 0)", "widest table row is 768 bytes (pin 768; headroom 0)", and every prose line is within the 120-byte budget.

The CI families on this PR are not awaited by the author.

Gate exit codes (head 596cd15)

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-corpus.mjs :: exit 0
pnpm check:agent-test-spelling :: exit 0
pnpm check:docs-audit-scope :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:gitlink-declared :: exit 0
pnpm check:nul-bytes :: exit 0
pnpm check:pm-governed-merges :: exit 0
pnpm check:pm-governed-prose :: exit 0
pnpm check:pm-skill-id-lint :: exit 0
pnpm check:pm-skill-ratchet :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:required-contexts :: exit 0
pnpm check:watch-hint-literal :: exit 0
pnpm check:doc-authoring :: exit 0
node scripts/check-published-list-mirrors.mjs --self-test :: exit 0
node scripts/check-published-list-mirrors.mjs :: exit 0

Session: session_01QSeKYmhU5KEj1nukYhp1Tg (os-dev subagent, mode:subagent).

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 596cd15e35f1560ec0c7f0e8ff99197df1191a58
Local-runs: none
Scope: AGENTS.md + packages/cli/src/commands/dev.ts (L481, L537, L560–565), packages/cli/src/commands/serve.ts (L2307), ui/apps/console/vite.config.ts (L1509), scripts/check-dev-prereqs.mjs (L579), package.json (setup) — the code the three sentences now describe, read on origin/main 69df290e, not reviewed

Read at 2026-10-28T05:34Z by the domain:skills#2 seat on the fetched head (merge-base fbc16563): one file, +4/−4, three hunks. Tier H by path (AGENTS.md); the approvers hotlong and os-zhuang are requested by the relay. This record is the surface-owed review (governed rules text).

① Derived judgments

• No accept set, no public surface, no runtime moves: instruction prose only; skip-changeset is the right declaration; PD 14's surface list and the cross-package-test-inputs block are untouched (check:pm-governed-prose, check-published-list-mirrors green locally and in CI's lint lanes).
• L40: 「first-time: install + build spec」 → 「install + build spec only; pnpm dev needs pnpm build」. Against the code: root package.json setup = pnpm install && pnpm --filter @objectstack/spec build (spec only), and scripts/check-dev-prereqs.mjs L579 prescribes pnpm install && pnpm build / pnpm build when pnpm dev finds a stale or missing build. The old 「first-time」 label was the false part (a first-time contributor who ran only setup was refused by pnpm dev). Correct. Inside the bash fence (123 B, fence class exempt from the 120-byte prose rule).
• L138 (dev-server table row): 「Port must be 3000 (UI hard-wired)」 → 3000 is the default the Console dev proxy targets unless DEV_PROXY_TARGET moves it; a busy port shifts, read the printed port; PORT is the legacy alias of OS_PORT; both commands spell OS_PORT=3000. Against the code: dev.ts L481 flags.port ?? readEnvWithDeprecation('OS_PORT', 'PORT', { silent: true }), L537 requestedPort = port ?? '3000', L560–565 getAvailablePort(askedFor) under serve.ts L2307 portAutoShiftAllowed = flags.dev || NODE_ENV === 'development'; vite.config.ts L1509 target: process.env.DEV_PROXY_TARGET || 'http://localhost:3000'. Every clause of the new sentence has a line. Correct. 506 B, under the 768-byte widest-row pin (L709, untouched).
• L170–171: PORT=3000 pnpm dev → OS_PORT=3000 pnpm dev, re-wrapped inside the paragraph's own six lines (116 B / 118 B, under 120); meaning unchanged (run the backend the proxy targets; browse :5180). Correct — the documented name first, the alias where the table row now says it.
• Line ratchet: 1112 / 1112 (headroom 0), widest row 768 / 768 — measured on the fetched head.

② Semver level

• None owed: AGENTS.md ships in no package; Clause-②: no, Metadata-protocol: none on the PR body match the claim; no Skills-docs: line owed.

③ Boundary flags

• Dev flags: examples/README.md L42 carries the same 「first-time」 label (outside this card's AGENTS.md-only surface and acceptance grep — doc wording, noted, not a card); ui/AGENTS.md L221 spells the legacy PORT=3000 (Tier H, alias still works — spelling drift, noted). The seat carries both to the round report as Acceptance notes, ⛔ no card.
• Hypothesis 1 half-falsified by the dev (the description was true, the 「first-time」 label was the disagreement) — recorded; the seat's claim stands corrected on that half.
• L145 「never run two backends on port 3000」 left as is — judged sound under auto-shift (the rule is about the port the proxy targets). Agreed.
• Author objectstack-fleet[bot] through the relay; mcp_calls: 0; the dispatch named a non-existent pnpm alias (check:published-list-mirrors) — the dev ran the real gate as lint.yml does; the seat's error, not the dev's.

④ Design judgment

• The three sentences against the scenario the card names (a contributor following AGENTS.md believes the port is fixed and setup is the first-time step): each false clause is replaced by a clause with a code line behind it; nothing is added that the code does not do; the row stays one row. Holds.

Implemented-by: claude/issue-26088-agents-md-contributor-instructions
Reviewed-by: session_01QSeKYmhU5KEj1nukYhp1Tg

VERDICT: PASS

[objectstack-fleet]

维护者速读 — 席位终稿 · PR #27094 · head 596cd15e · domain:skills#2 · 2026-10-28T05:35Z

• 改了什么:AGENTS.md 三处贡献者说明就地改(1112 行不变):L40 pnpm run setup 的注释去掉「first-time」——它只装依赖、只建 spec,pnpm dev 还要 pnpm build;L138 开发服务表格那行,「端口必须 3000(UI 写死)」改为「3000 是默认、不是写死:Console 代理默认指向它(DEV_PROXY_TARGET 可改),忙端口自动后移、看打印出来的端口,PORT 是 OS_PORT 的旧别名」,命令改拼 OS_PORT=3000;L170–171 快速迭代段同改 OS_PORT=3000。
• 为什么改:照旧文操作的人或 agent 会以为端口改不了、以为跑过 setup 就能 pnpm dev(实际被 prereq 门拒)。README / CONTRIBUTING / getting-started 已由 docs: one scaffold spelling and one dev-port sentence for contributors #26248 改好,这是最后一处。
• 风险与回滚:纯说明文字,不发布;每句背后都有代码行(席位逐行核过:dev.ts 481/537/560、serve.ts 2307、vite.config.ts 1509、check-dev-prereqs.mjs 579)。回滚 = revert 一个 commit。
• 先看:L138 那一行(最大 hunk);再 L40、L170–171。
• 两分钟验证:grep -n 'hard-wired\|PORT=3000\|pnpm run setup' AGENTS.md,预期只见 L40 新注释、L138 的「not hard-wired」与 OS_PORT=3000、L170 的 OS_PORT=3000,不再有「must be 3000」。
• 需要你做的:Tier H(AGENTS.md)——请 Approve(中继已请审 hotlong、os-zhuang);批准后席位落地。
• 席位意见:ACCEPT。两处同类拼写留在卡外(examples/README.md L42 的「first-time」、ui/AGENTS.md L221 的 PORT=3000),进轮报,不立卡。

席位核对 — ACCEPT · domain:skills#2 · session_01QSeKYmhU5KEj1nukYhp1Tg · 2026-10-28T05:35Z

1. 形态:draft → main,首行 Fixes #26088(非 AGENTS 半边已由 docs: one scaffold spelling and one dev-port sentence for contributors #26248 落地,本 PR 收尾),Clause-②: no、Metadata-protocol: none 行首在;一个文件 +4/−4,与认领申报面相同;assignee os-justin;skip-changeset 正确。
2. 前提实测:席位在取回的 head 上重量——1112 行;L40 123 B(fence 类)、L138 506 B(最宽行 pin 768 在 L709 未动)、L170 116 B、L171 118 B;被引代码六行在 origin/main 69df290e 上逐条成立(见契约复核 6461532559 ①)。假设 1 被 dev 半证伪(描述真、「first-time」假),记录在案。
3. 门禁 check-runs(head 596cd15e,本笔读数 2026-10-28T05:35Z):16 success · 20 skipped · 5 in progress;dev 本地并集 15/15 exit 0 + 派生外 3 条(check:doc-authoring、check-published-list-mirrors 自测与扫描)exit 0,钉同 head。等人批期间席位继续读。
4. 接受的偏差:① 派发令点名的 pnpm check:published-list-mirrors 不存在(exit 254 = 脚本名未知),dev 按 lint.yml 的真实调用跑了门禁——席位之误;② L145「不要在 3000 跑两个后端」未改,判断成立;③ test:repo 留 CI。
5. 范围外去向:examples/README.md L42、ui/AGENTS.md L221 → Acceptance notes / 轮报(拼写漂移,非三类);Skills-docs: 不欠(kind none)。
6. 落地条款:Tier H ⇒ 等 GOVERNED_APPROVERS 批准;席位 ⛔ 不 ready / 不 arm / 不入队;契约复核 PASS 评论 6461532559 钉 head;批准在案后席位跑 check-governed-merges.mjs --pr 27094、核全绿与 mergeable_state,再经中继落地(若分类器再拦,照 pm-dispatch: governed is an approval tier, the lane follows the subject — rule text to skills, workflow wiring to devx #27082 的记录停手报维护者)。