Skip to content

[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

Closed

Description

@objectstack-fleet

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): "Read content/docs/concepts/north-star.mdx before structural changes."
  • ROADMAP.md:4: "Source of truth: content/docs/concepts/north-star.mdx for product direction".
  • CONTRIBUTING.md:69: points to docs/NORTH-STAR.md.
  • AGENTS.md:31: repository artifacts keep their existing language convention, "以英文为主".
  • Prime Directive 14: docs/NORTH-STAR.md and AGENTS.md are 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.mdx and 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

  1. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    ContributorAuthor

    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.

    • A decision card: the options and the filer's recommendation are in the body, and the letter is the maintainer's. Which document outranks AGENTS.md is a rules question, so it is on the floor.

    Generated by Claude Code

  2. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    ContributorAuthor

    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/main cdd4eea9; the card's own analysis is not restated):

    • P1–P3 hold: docs/NORTH-STAR.md 125 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 lists docs/NORTH-STAR.md in the governed register (Tier H).
    • pm-dispatch SKILL.md 「优先级」 (维护者裁决 > 北极星 > AGENTS.md) and seat-lifecycle both use the word; AGENTS.md:7 already states the hierarchy the card's A makes consistent. No ADR names either file.
    • Facets read: same direction; the seat agrees with A (the mdx becomes architecture-overview with 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.
  3. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    ContributorAuthor

    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 「同意」:

    1. content/docs/concepts/north-star.mdx is renamed architecture-overview (a redirects-ledger entry, check:docs-redirects green) 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 in docs/NORTH-STAR.md.
    2. AGENTS.md Prime Directive 8 ("Read content/docs/concepts/north-star.mdx before structural changes … §7 Built, shrink Drift, or unlock Missing") is re-pointed at docs/NORTH-STAR.md's 路上的功能点 ladder; AGENTS.md:7, CONTRIBUTING.md:69 and ROADMAP.md:4 all name docs/NORTH-STAR.md as the one North Star; the five site pages that link the mdx move to the new slug.
    3. docs/NORTH-STAR.md gains 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; plus ROADMAP.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:queue in this act (domain:docs as triage graded, p2); pm:awaiting-maintainer removed in the same stroke. Ruling-ref: names this comment; Clause-②: no, Metadata-protocol: none; the dev greps README, ui/ and the docs redirects for concepts/north-star before renaming (the card's confidence gap).

  4. objectstack-fleet commented on Oct 27, 2026

    @objectstack-fleet
    ContributorAuthor

    Claim: PM loop round 1 · 2026-10-27T22:51Z
    Session: session_01QSeKYmTYfaPbLQD4BJfomW
    Account: os-justin (the seat's linked user as GET /user answers it; the card's assignee)
    Branch: claude/issue-26073-north-star-one-referent
    Worktree: objectstack-issue-26073
    Domain: domain:devx
    Seat: domain:devx#2
    File 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-redirects green); AGENTS.md:7 and Prime Directive 8 (AGENTS.md:197) re-pointed at docs/NORTH-STAR.md's 路上的功能点 ladder; ROADMAP.md:4, CONTRIBUTING.md:114 and the README link (L270) name docs/NORTH-STAR.md as the one North Star; the hand-written site pages that link /docs/concepts/north-star (on origin/main aa00362f: content/docs/concepts/metadata-lifecycle.mdx, content/docs/data-modeling/formulas.mdx) move to the new slug; docs/NORTH-STAR.md gains an English summary section under the Chinese text, the Chinese original unedited. ⛔ Not content/docs/references/** (generated) and not content/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 --tier on the surface: "no path-derived mandate"), effort: high
    Clause-②: no
    Metadata-protocol: none
    Responsibility: n/a — not a defect card
    Ruling-ref: 6417934431
    Thread-read: 6417934431
    Premise: holds at origin/main aa00362f — AGENTS.md:7 and AGENTS.md:197 still name the mdx; ROADMAP.md:4 names the mdx; CONTRIBUTING.md:114 names docs/NORTH-STAR.md; content/docs/concepts/north-star.mdx exists and architecture-overview.mdx does not. The serial blocker #26035 is closed.
    Serial constraints cleared: no open PR touches AGENTS.md, docs/NORTH-STAR.md, ROADMAP.md, CONTRIBUTING.md or content/docs/concepts/north-star.mdx (files of all 37 open PRs read). PR #26920 (draft) edits content/docs/concepts/metadata-lifecycle.mdx, which links the old slug at L174, so whichever lands second merges main. #26080 slice 1 (this round, this seat) folds ui/ docs into root README.md / ROADMAP.md / CONTRIBUTING.md in other regions; whichever lands second merges main. AGENTS.md serial queue on #20163: this card, then #26088's remainder, then #26081 PR 1.


    Generated by Claude Code

  5. objectstack-fleet commented on Oct 27, 2026

    @objectstack-fleet
    ContributorAuthor

    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

  6. objectstack-fleet commented on Oct 27, 2026

    @objectstack-fleet
    ContributorAuthor

    devx seat 2 · PR #26970 state · 2026-10-27T23:53Z


    Generated by Claude Code

  7. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    ContributorAuthor

    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.md and CONTRIBUTING.md are domain:devx. AGENTS.md and docs/NORTH-STAR.md are governed surfaces, which the SKILL.md lane table puts under domain: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:retriage to be relabelled domain:skills.


    Generated by Claude Code

  8. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    ContributorAuthor

    Landed: PR #26970, merged as 25a697ec69 · 2026-10-28T02:10Z

    Ruling A′ (6417934431) is on main:

    • one North Star, docs/NORTH-STAR.md, with an English summary below the unedited Chinese;
    • the architecture page renamed to concepts/architecture-overview, with a redirect from the old slug;
    • AGENTS.md L7 and Prime Directive 8, ROADMAP, CONTRIBUTING and README all pointing at the one file.

    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 by Fixes; pm:dispatched is removed in this act.

    Follow-ups:


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:devpathThe road — create, dev, verify, publish/install, connect an agent, iteratedocumentationImprovements or additions to documentationdomain:devxpriority:p2Medium: important, M3

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions