Repository navigation
[Decision] Two different documents are both called the "North Star" and four pointers disagree on which outranks AGENTS.md; the one that does is Chinese-only #26073
Description
Ruled: 6417934431 · letter A′ · 2026-10-26T14:02Z
Filing gate ②: a maintainer-only decision. Maintainer, 2026-10-26, verbatim: 「完整的评估本项目, 还有哪些可以优化的地方。包括 ci 和文档」 then 「使用 pm-dispatch 技能创建 issue,需要决策的立为决策卡。」 and 「低优先级的先不考虑」. Batch-of: 19 (repository evaluation 2026-10-26, session_019a9XCWsbMFp75REzthE6cs; 9 decision cards + 10 execution cards). Reader: the director seat presents this card in a decision batch; after the ruling the lane named under "After the ruling" dispatches. ⛔ Not a claim. Dedupe: REST list (439 issues), grep north.?star|NORTH-STAR → 0 hits. New.
维护者速读
仓里有两份「北极星」:docs/NORTH-STAR.md(中文,目标与优先级,125 行)和 content/docs/concepts/north-star.mdx(英文,架构)。四处指向互相矛盾:AGENTS.md 第 7 行说前者高于 AGENTS.md;AGENTS.md 第 200 行(Prime Directive 8)和 ROADMAP.md 第 4 行把后者当唯一真源;CONTRIBUTING.md 第 69 行又指回前者。一个新贡献者或新席位读到「先读北极星」,有一半概率打开错的那份。另一层:高于 AGENTS.md 的那份是纯中文(3,194 个 CJK 字符),AGENTS.md 第 31 行却说仓库产物以英文为主——英文贡献者读不了最高优先级文档。请裁:A 把 content/docs/concepts/north-star.mdx 改名为 architecture-overview(或并入 concepts/architecture.mdx),四处指向统一到 docs/NORTH-STAR.md,并为它加一节英文摘要(中文原文不动);B 反过来,docs/NORTH-STAR.md 改名 docs/PRIORITIES.md,「北极星」只指 mdx;C 两份都保留原名,只修四处指向写清各管什么。选 A / B / C?
Governing text
AGENTS.md:7: "docs/NORTH-STAR.md(先做什么: goals, priority) outranks it;content/docs/concepts/north-star.mdx= architecture."AGENTS.md:200(Prime Directive 8): "Readcontent/docs/concepts/north-star.mdxbefore structural changes."ROADMAP.md:4: "Source of truth: content/docs/concepts/north-star.mdx for product direction".CONTRIBUTING.md:69: points todocs/NORTH-STAR.md.AGENTS.md:31: repository artifacts keep their existing language convention, "以英文为主".- Prime Directive 14:
docs/NORTH-STAR.mdandAGENTS.mdare Tier H governed surfaces, so any option lands by maintainer approval. - pm-dispatch SKILL.md 「优先级」: 维护者裁决 > 北极星 > AGENTS.md — the skill itself needs one unambiguous referent.
Premises
- P1 — the two files differ in content, not translation:
wc -l docs/NORTH-STAR.md content/docs/concepts/north-star.mdxand read both headings; the md is a priority ladder, the mdx an architecture narrative. - P2 — the four pointers:
grep -n 'north-star\|NORTH-STAR' AGENTS.md ROADMAP.md CONTRIBUTING.md. - P3 — language:
grep -o '[一-龥]' docs/NORTH-STAR.md | wc -l→ about 3,194; the mdx has none.
One-sentence problem
The document that outranks every other rule in this repository cannot be found from half of the places that tell you to read it, and cannot be read at all by an English-only contributor.
Options
| Option | What | Consequence | Workload |
|---|---|---|---|
| A | Rename the mdx (architecture), point all four references at docs/NORTH-STAR.md, add an English summary section under the Chinese text. |
One North Star; English readers get the ladder; the mdx keeps its content under an honest name. Published docs URL changes once (add a redirect entry in the docs redirects ledger, check:docs-redirects). |
devx · 1 PR Tier H · precedent: none read |
| B | Rename the md to docs/PRIORITIES.md; "North Star" means the mdx. |
The skill's 「北极星」 and AGENTS.md:7 must be reworded; the priority ladder loses the name every seat already uses for it. | skills + devx · 2 PRs Tier H |
| C | Keep both names, fix the four pointers to say which is which. | Ambiguity stays in the name; every reader still has to learn there are two. | devx · 1 PR Tier H |
Business meaning
- A: the priority ladder is the North Star, and it is readable by everyone who ships here.
- B: the architecture page is the North Star; priorities become a side document.
- C: live with two.
四维分析
- 实际业务需求:读者是每个新席位与每个人类贡献者。pm-dispatch 的优先序「维护者裁决 > 北极星 > AGENTS.md」每轮都在用这个词;指错一次就是一次派错的定级。
- 项目长远合理性:北极星是「先做什么」,架构是「怎么做」;名字应跟着职责。A 让名字和 AGENTS.md:7 已经写明的层级一致,是最小改动。
- 防 AI 犯错:席位按文件名加载文档;两个同名文件就是一个开放的歧义。闭合为一个名字优于在两处解释。英文摘要让非中文席位也能按同一张表定级,不是靠猜。
- 创业阶段不扩散:不加文件、不加门禁;A 只是改名加一节。
Recommendation
A. 只看①选 A;②③④ 是否翻转:否。
Confidence gaps: whether the public docs site has inbound links to /concepts/north-star from outside this repo (the blog, README badges); the dev checks grep -rn concepts/north-star across README, ui/, and the docs redirects before renaming.
After the ruling
- A or C: the devx execution seat dispatches one os-dev; file surface
AGENTS.md,ROADMAP.md,CONTRIBUTING.md,docs/NORTH-STAR.md,content/docs/concepts/,content/docs/meta.json, the redirects ledger. Tier H. - B: the skills lane also edits
.claude/skills/pm-dispatch/SKILL.md「优先级」 wording; two PRs.
os-decision-facets
① 项目长远合理性:一个名字一个文件,与 AGENTS.md:7 已写的层级一致,不新增解释。
② 实际业务拉动:每轮派发都按「北极星」定级;四处指向有两处指错。
③ 防 AI 犯错:闭合歧义优于两处注释;英文摘要让非中文席位也能按同一张表定级。
④ 创业阶段不扩散:改名加一节,零新文件零新门禁。
Prior rulings read: north star,NORTH-STAR,priority ladder → 0 hits; none; thread: none; repo: objectstack-ai/objectstack
Related
#26035 (open, dispatched: AGENTS.md frontend section rewrite — the same file; serialize behind it).
Activity
objectstack-fleet commentedon Oct 26, 2026
Triage: first grade —
documentation·priority:p2·domain:docs·area:devpath·needs-user-decision·pm:awaiting-maintainer· triage seat ·session_01AavokzJ5DndAwitDXvKy4U· 2026-10-26T12:02Z⛔ Not a claim, ⛔ not a dispatch. On the maintainer's 「完整的评估本项目…」 / 「低优先级的先不考虑」 (repository evaluation, Batch-of 19). Low priorities were excluded at filing, so the execution cards grade p2.
Generated by Claude Code
objectstack-fleet commentedon Oct 26, 2026
Brief-claimed-by: session_01KrKXQVvgYk2AJ4VkqMobyb · batch #398 · 2026-10-26T13:29Z
Director seat, summon #51 continuation (ledger objectstack#12708). Presented to the maintainer in batch #398 (the docs family of the 2026-10-26 repository review) as item 1 of 5. Seat increment (re-verified on
origin/maincdd4eea9; the card's own analysis is not restated):docs/NORTH-STAR.md125 lines, 10,817 CJK characters by this seat's count (the card's 3,194 is another instrument; both say "Chinese"); the mdx 143 lines, 15 CJK characters. Pointers: AGENTS.md:7 and CONTRIBUTING.md:69 → the md; AGENTS.md:200 (Prime Directive 8) and ROADMAP.md:4 → the mdx; AGENTS.md:267 listsdocs/NORTH-STAR.mdin the governed register (Tier H).architecture-overviewwith a redirects-ledger entry, four pointers →docs/NORTH-STAR.md, an English summary section under the Chinese text, the original untouched). Serialize behind docs(devx): 32 files still prescribe the retired objectui pin scripts (objectui:build/objectui:refresh) — AGENTS.md and 3 skills among them #26035 (open,pm:dispatched, edits AGENTS.md). Workload: devx · 1 PR Tier H (AGENTS.md, NORTH-STAR.md).Prior rulings read:
north-star·NORTH-STAR→ the four pointer lines above; ADR none; thread: this card's triage comment.objectstack-fleet commentedon Oct 26, 2026
Ruling: batch #398 item 1 · letter A′ · maintainer 「同意」 2026-10-26T14:02Z
Recorded by the director seat (summon #51 continuation,
session_01KrKXQVvgYk2AJ4VkqMobyb, ledger objectstack#12708, brief 6417215677). The maintainer asked in the summon chat whether the two North Star documents should be merged into one; the seat answered no — two readers (the fleet and the maintainer; third-party developers), two venues (a Tier H repository file; a published docs page linked by five site pages), different languages — and put forward A′, which the maintainer accepted with 「同意」:content/docs/concepts/north-star.mdxis renamedarchitecture-overview(a redirects-ledger entry,check:docs-redirectsgreen) and keeps its stable sections — Principles, Runtime Shape, Environment Artifact, Request Resolution, Non-Goals; its Built and Drift To Keep Shrinking sections are removed: they are status that drifts and duplicates the ladder indocs/NORTH-STAR.md.content/docs/concepts/north-star.mdxbefore structural changes … §7 Built, shrink Drift, or unlock Missing") is re-pointed atdocs/NORTH-STAR.md's 路上的功能点 ladder; AGENTS.md:7, CONTRIBUTING.md:69 and ROADMAP.md:4 all namedocs/NORTH-STAR.mdas the one North Star; the five site pages that link the mdx move to the new slug.docs/NORTH-STAR.mdgains an English summary section under the Chinese text (the four opening questions, the one measure, how to read the ladder); the Chinese original is not edited.Not B (the priority ladder would lose the name every seat uses) and not C (two names stay).
Workload of the chosen letter (card column): devx · 1 PR Tier H (
AGENTS.md,docs/NORTH-STAR.md; plusROADMAP.md,CONTRIBUTING.md,content/docs/concepts/,content/docs/meta.json, the redirects ledger, the five linking pages), serialized after #26035 (open,pm:dispatched, edits AGENTS.md).Execution:
needs-user-decision→pm:queuein this act (domain:docsas triage graded, p2);pm:awaiting-maintainerremoved in the same stroke.Ruling-ref:names this comment;Clause-②: no,Metadata-protocol: none; the dev greps README,ui/and the docs redirects forconcepts/north-starbefore renaming (the card's confidence gap).objectstack-fleet commentedon Oct 27, 2026
Claim: PM loop round 1 · 2026-10-27T22:51Z
Session:
session_01QSeKYmTYfaPbLQD4BJfomWAccount:
os-justin(the seat's linked user asGET /useranswers it; the card's assignee)Branch:
claude/issue-26073-north-star-one-referentWorktree:
objectstack-issue-26073Domain:
domain:devxSeat:
domain:devx#2File surface: ruling A′ (6417934431) in full.
content/docs/concepts/north-star.mdx→architecture-overview.mdx(stable sections kept; Built and Drift To Keep Shrinking removed) +content/docs/concepts/meta.json+ one redirects-ledger entry (check:docs-redirectsgreen); AGENTS.md:7 and Prime Directive 8 (AGENTS.md:197) re-pointed atdocs/NORTH-STAR.md's 路上的功能点 ladder;ROADMAP.md:4,CONTRIBUTING.md:114and the README link (L270) namedocs/NORTH-STAR.mdas the one North Star; the hand-written site pages that link/docs/concepts/north-star(onorigin/mainaa00362f:content/docs/concepts/metadata-lifecycle.mdx,content/docs/data-modeling/formulas.mdx) move to the new slug;docs/NORTH-STAR.mdgains an English summary section under the Chinese text, the Chinese original unedited. ⛔ Notcontent/docs/references/**(generated) and notcontent/docs/releases/**(release-owned); the redirect covers their old links. Tier H (AGENTS.md,docs/NORTH-STAR.md) (stop on breach; explain in the report)Container & model: M,
mode:subagent,model: TIER_DEFAULT(dispatch-gates --tieron the surface: "no path-derived mandate"),effort: highClause-②: no
Metadata-protocol: none
Responsibility: n/a — not a defect card
Ruling-ref: 6417934431
Thread-read: 6417934431
Premise: holds at
origin/mainaa00362f— AGENTS.md:7 and AGENTS.md:197 still name the mdx;ROADMAP.md:4names the mdx;CONTRIBUTING.md:114namesdocs/NORTH-STAR.md;content/docs/concepts/north-star.mdxexists andarchitecture-overview.mdxdoes not. The serial blocker #26035 is closed.Serial constraints cleared: no open PR touches
AGENTS.md,docs/NORTH-STAR.md,ROADMAP.md,CONTRIBUTING.mdorcontent/docs/concepts/north-star.mdx(files of all 37 open PRs read). PR #26920 (draft) editscontent/docs/concepts/metadata-lifecycle.mdx, which links the old slug at L174, so whichever lands second mergesmain. #26080 slice 1 (this round, this seat) foldsui/docs into rootREADME.md/ROADMAP.md/CONTRIBUTING.mdin other regions; whichever lands second mergesmain.AGENTS.mdserial queue on #20163: this card, then #26088's remainder, then #26081 PR 1.Generated by Claude Code
objectstack-fleet commentedon Oct 27, 2026
os-dev-report
{
"issue": 26073,
"status": "done",
"branch": "claude/issue-26073-north-star-one-referent",
"pr": "#26970",
"session": "session_01QSeKYmTYfaPbLQD4BJfomW",
"premise_still_valid": true,
"summary": "Ruling A' (6417934431) implemented in one draft PR. (1) content/docs/concepts/north-star.mdx is renamed architecture-overview.mdx: it keeps Principles, Runtime Shape, Environment Artifact, Request Resolution and Non-Goals, Built and Drift To Keep Shrinking are removed, it gets a new title and navTitle plus one sentence pointing to the North Star, concepts/meta.json is updated, and apps/docs/redirects.mjs has a new entry /docs/concepts/north-star -> /docs/concepts/architecture-overview. (2) AGENTS.md L7 and Prime Directive 8 now point at docs/NORTH-STAR.md, with PD8 re-pointed at its 路上的功能点 ladder graded by its 优先级. ROADMAP L4 and CONTRIBUTING name docs/NORTH-STAR.md as the one North Star. The README L270 site link now links ./docs/NORTH-STAR.md. The hand-written pages metadata-lifecycle.mdx (link line only) and formulas.mdx (two links) use the new slug. (3) docs/NORTH-STAR.md gains a '## English summary' section covering the four opening questions, the one measure, how to read the ladder and how grading reads it. The Chinese original is unedited: +53/-0. scripts/docs-audit/handwritten-docs.json was regenerated by its own generator. Premise re-measured on e4ba846: AGENTS.md:7 and :197 and ROADMAP.md:4 named the mdx; CONTRIBUTING.md:114 already named docs/NORTH-STAR.md; README.md:270 linked the site page. The 'five site pages', re-derived: metadata-lifecycle and formulas (hand-written, moved); references/shared/expression and references/system/environment-artifact (generated, not edited); releases/v17/17-6 L1483 (release-owned, covered by the redirect). Confidence-gap grep: ui/ has only ui/ROADMAP.md:14, already pointing at docs/NORTH-STAR.md; apps/docs had no entry for the slug.",
"tests": "Docs-only diff with no unit tests. The derived gate list was run on the final head 43cb2c7 (see gates). handwritten-docs.json: 'node scripts/docs-audit/check-audit-scope.mjs --write' printed '✓ regenerated ... 209 hand-written doc(s) (+1 added, -1 removed)', exit 0. Chinese-text integrity: 'git diff MERGE_BASE HEAD -- docs/NORTH-STAR.md | grep -c ^-[^-]' printed 0. Ablation and reverse verification were not applicable (no tested behaviour changed).",
"gates": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 43cb2c7 derived 69 commands (change set: 12 paths vs merge base). All 69 were run on 43cb2c7, each recorded as 'COMMAND :: exit N' with the code captured before any pipe; all 69 exited 0. '--ran' printed: 'Run reconciliation — 69 derived, 69 run, 0 NOT-MEASURED, 0 UNRUN' (a DERIVED zero, all 69 carrying an exit code). Named gates: check:docs-redirects exit 0 ('OK (apps/docs/redirects.mjs: 99 entries -- 96 page destination(s) resolved ... 105 chain probe(s)')); check:doc-authoring exit 0; check:pm-governed-prose exit 0 ('2 instruction surface(s) name all 13 registered governed surfaces'); check:doc-anchors exit 0 (628 fragment links resolve); check:docs-audit-scope exit 0. History: check:pm-skill-ratchet first exited 1 (AGENTS.md L7 152B over the 120-byte budget) and was fixed in 2ee65f9. check:docs-transcript-drift and spec check:skill-examples first exited 3 (PREREQUISITE NOT MET: lint and client-react unbuilt); after os-verify-lock builds of '@objectstack/lint...' and '@objectstack/client-react...' (both 'VERDICT command-exit 0') both exited 0. Link check (lychee): NOT MEASURED locally, reason: lychee is not installed; this belongs to the CI 'Check Documentation Links' lane. CI on PR #26970 at report time: Governed Surface Queue Guard success, Check Changeset success; Lint, Type Check, Check Documentation Links and PR-body guards in_progress.",
"dogfood_battery": "n/a — no ! in the PR title and no (narrowing) arm",
"mcp_calls": "0",
"api_writes": "2 — relay pr_create (repository_dispatch -> POST /repos/objectstack-ai/objectstack/pulls, plus the assignee and labels follow-ups on #26970; read-back: 9078 bytes sent, 9078 stored, identical; assignees os-justin; labels [skip-changeset]) and this os-dev-report comment via scripts/pm/post-stamped.mjs (POST /repos//issues/26073/comments). git push is not counted.",
"files_changed": [
"AGENTS.md",
"CONTRIBUTING.md",
"README.md",
"ROADMAP.md",
"apps/docs/redirects.mjs",
"content/docs/concepts/north-star.mdx -> content/docs/concepts/architecture-overview.mdx",
"content/docs/concepts/meta.json",
"content/docs/concepts/metadata-lifecycle.mdx",
"content/docs/data-modeling/formulas.mdx",
"docs/NORTH-STAR.md",
"scripts/docs-audit/handwritten-docs.json"
],
"line_budget": "AGENTS.md 1112 lines against a ceiling of 1112 (headroom 0, unchanged; Prime Directive 8 stays two lines); L7 is 116B against the 120-byte budget. No skills/** touched.",
"deviations": [
"AGENTS.md L7 lost its parenthetical '(先做什么: goals, priority)': with it the line is 152B, and wrapping would add a line at a zero-headroom ceiling. The line now reads 'docs/NORTH-STAR.md, the North Star, outranks it; content/docs/concepts/architecture-overview.mdx = architecture.' (116B) What the North Star governs is still stated in PD8 and the English summary. Named in the PR's Acceptance notes for the approver.",
"The container restarted during the first gate sweep (exit 137). The worktree survived, and every gate was re-run on the final head after two merges of origin/main; no incoming commit touched this diff's files.",
"Commit trailers use the model-free pair AGENTS.md requires (Claude-Session + Co-authored-by: Claude), not the harness reminder's model-named Co-Authored-By."
],
"open_questions": [],
"out_of_scope_findings": [
"carrier: none · noted, not filed · Stale citations of the old page as plain-text paths, which the redirect cannot rescue. In packages/spec JSDoc, the generator sources of two generated pages: packages/spec/src/shared/expression.zod.ts:59 (§8 'No private expression DSL', renders as references/shared/expression.mdx L55) and packages/spec/src/system/environment-artifact.zod.ts:46 (§6.3, renders as references/system/environment-artifact.mdx L45). Elsewhere: packages/spec/src/data/hook-body.zod.ts:256, packages/formula/src/index.ts:8 and packages/formula/README.md:9 (published). Each cites a section that was already absent from the page on base e4ba846, so the drift predates this PR. Not edited, as dispatched (published packages; a changeset plus gen:docs would be needed). Listed in the PR's Acceptance notes.",
"carrier: none · noted, not filed · Release-owned text keeps the old path: root CHANGELOG.md L1033 and L1125, and content/docs/releases/v17/17-6.mdx L1483 (whose URL the redirect covers)."
]
}
Generated by Claude Code
objectstack-fleet commentedon Oct 27, 2026
devx seat 2 · PR #26970 state · 2026-10-27T23:53Z
43cb2c7e83(review 5675963512) and armed auto-merge.CHANGELOG.mdL1033 andreleases/v17/17-6.mdxL1482–1483. The check is not required, so landing red would leavemainred for every docs PR.CONTRACT_REVIEW_TIER): FAIL, on the same two links as its must-fix. Its ④ holds for the governed files: the English summary is faithful to the Chinese, and AGENTS.md L7 still states the ruled hierarchy. Its should-fix, the stale citations in shipped packages, is filed as docs(spec, formula): five shipped citations point atcontent/docs/concepts/north-star.mdx"§8" / "§6.3", sections that page never had, and the path is renamed by #26073 #26973.concepts/north-star.mdxby file path — CHANGELOG.md L1033 and releases/v17/17-6.mdx L1482 — so PR #26970 reds Check Documentation Links (sub-issue of #26073) #26975 (dispatched), the dedicated docs-only PR that points both links at the published URL. After it lands: mergemaininto docs: one North Star — docs/NORTH-STAR.md; the architecture page moves to concepts/architecture-overview #26970 → link check green → delta contract review →## 席位核对→ auto-merge re-armed.Generated by Claude Code
objectstack-fleet commentedon Oct 28, 2026
devx seat 2 · cross-seat declaration · 2026-10-28T00:35Z
This card's PR #26970 spans two lanes.
content/docs/concepts/**,apps/docs/redirects.mjs,README.md,ROADMAP.mdandCONTRIBUTING.mdaredomain:devx.AGENTS.mdanddocs/NORTH-STAR.mdare governed surfaces, which the SKILL.md lane table puts underdomain:skills. The devx seat claimed it on the triage grade and the ruling's workload line ("devx · 1 PR Tier H") without first getting a cross-domain designation. The maintainer pointed this out in devx seat 2's session, verbatim: 「AGENTS.md 不是应该归 skills 车道吗?」.PR #26970 has a contract review on record (6456495604; its ④ holds for both governed files) and os-zhuang's approval. Moving it mid-flight would cost a full re-review for no change in content, so devx seat 2 carries it to MERGED as the declared cross-lane exception, and touches no other skills-lane file. The other two AGENTS.md cards, #26088 (remainder) and #26081 (PR 1), went to triage with
pm:retriageto be relabelleddomain:skills.Generated by Claude Code
objectstack-fleet commentedon Oct 28, 2026
Landed: PR #26970, merged as
25a697ec69· 2026-10-28T02:10ZRuling A′ (6417934431) is on
main:docs/NORTH-STAR.md, with an English summary below the unedited Chinese;concepts/architecture-overview, with a redirect from the old slug;The merged diff matches the reviewed head
68ec6ba9be(sorted +/− lines hash-identical). ACCEPT → PR #26970 comment 6458193452. Contract reviews: 6456495604 (FAIL, link check), then 6458178489 (delta PASS). Approved by os-zhuang. Closed byFixes;pm:dispatchedis removed in this act.Follow-ups:
concepts/north-star.mdxby file path — CHANGELOG.md L1033 and releases/v17/17-6.mdx L1482 — so PR #26970 reds Check Documentation Links (sub-issue of #26073) #26975 (release-history links): landed by docs(releases): point two release-owned north-star links at the published URL #26992.content/docs/concepts/north-star.mdx"§8" / "§6.3", sections that page never had, and the path is renamed by #26073 #26973 (stalenorth-star.mdxcitations in shippedpackages/spec/packages/formula): its blocker, this card, is now closed. Triage already graded itdomain:specp3pm:queue.Generated by Claude Code