Skip to content

docs: narrative cost — 42.5% of source lines are comments, workflows 58.6%, AGENTS.md is 103 KB with three stale claims, ROADMAP.md still says v3.3.2 and 80 Storybook stories #25919

Open

Description

@os-zhuang

Ruled: 6435359095 · letter A for PR 2 (prior 6386217274 A) · 2026-10-27T06:34Z

维护者速读

全仓非测试源码 643,658 行里 273,486 行是注释(42.5 %),packages/types/src 69.6 %;.github/workflows 11,342 行里 58.6 % 是 #;24,922 行源码引用 issue 号,涉及 3,186 个不同的 objectui 卡。AGENTS.md 103 KB / 630 行,§9 运维叙事占 66 %,含 3 处过期声明;ROADMAP.md 1,899 行停在「May 6 2026 · v3.3.2 · 80 Storybook stories」(仓里没有 Storybook)。仓库几乎全由 AI 席位写入,叙事是每个会话的强制 token 成本,也是受管面每次改动的复审成本。建议:规范核心与事故史分家,注释写不变量不写事故史,存量不横扫。

Measured (2026-10-24, HEAD 7981384; comment lines matched by the pattern "optional whitespace then // or /* or *")

  • Non-test source (packages + console, excluding locale packs): 643,658 lines, 273,486 comment (42.5 %), 337,531 code. Excluding packages/types: 39.5 %. packages/types/src alone: 45,265 of 64,991 (69.6 %). Tests: 1,225,145 lines, 27.7 % comments. scripts/*.mjs: 99,378 lines, 43.1 %. Workflows: 6,651 of 11,342 lines are # (ci.yml 1,688 of 2,868; changeset-release.yml 1,091 of 1,545 = 70 %). Root configs (eslint, vitest, tsconfig*, turbo): 67.1 %.
  • Issue citations in non-test source: 24,922 lines match objectui#NNNN|objectstack#NNNN|#NNNN+; 3,186 distinct objectui# numbers. 86 test files pin workflow prose; 678 reference AGENTS.md.
  • AGENTS.md: 103,232 bytes, 630 lines; §9 "Operational Rules" is 66 % of the code points; 107 distinct issue citations, 16 dated rulings, 72 ⛔ markers; 15 scripts and 10 pnpm commands are named as re-deriving instruments against roughly 90 prose-only paragraphs; 33 commits in 49 days. Stale claims inside the governed file: the "Local dev" section says framework serves the published console from packages/console/dist (no such directory; the console is apps/console); the "能 push 分支,却删不掉远端 ref" bullet says the container has no gh CLI (which gh → /usr/local/bin/gh, and the merge-queue section instructs gh pr merge --auto); the "依赖与锁文件" section says overrides point to file:node_modules/.cache/objectstack/<name> while package.json and the lockfile say file:.objectstack-pin/<name> (moved by objectui#13008); "39 个包一起发" versus 40 entries in the fixed group.
  • ROADMAP.md: 1,899 lines; header "Last Updated: May 6, 2026 · Current Published Version: v3.3.2 · Spec Version: @objectstack/spec ^4.0.4" against the real 18.0.0; claims "80 Storybook stories" — no .storybook directory or dependency anywhere (positive control: tailwind-merge found). docs/ARCHITECTURE.md is the 2026-04 app-shell extraction guide; 31 of its lines are byte-identical to docs/CONSOLE-STREAMLINING-SUMMARY.md. .github/prompts/ (three Copilot prompt files, 624 lines, naming Framer Motion, 0 dependencies) sits outside every doc gate's scan roots although AGENTS.md declares itself the single instruction file. docs/adr has 11 files, no index; the tree cites 96 distinct ADR numbers (ADR-0049 1,321 times) that resolve only in objectstack.
  • A concrete collision this style produces: scripts/__tests__/changeset-release-action-ref-pin.test.ts pins the changesets/action SHA in prose while .github/dependabot.yml groups weekly github-actions bumps; run 40054697521's Test (shard 8/16) went red on it.

Recommendation

  • AGENTS.md to a normative core of at most about 250 lines: each rule once, with its instrument pointer (pnpm check:* / test name), no incident narrative; move the incident write-ups (stash collision, ref delete, FETCH_HEAD, GitHub byte rewriting, workflow registry) into docs/postmortems/ or the governed .claude/skills/objectui-contributor/guides/; move the local-dev / port / multi-stack procedure into console-development.md; fix the three stale claims in the same PR. (Governed surface.)
  • Workflows and scripts: a comment budget — one line of why plus a link; rationale lives in the ADR or the issue. Re-measure with the pattern above.
  • ROADMAP.md cut to at most 40 lines pointing at milestones and labels (drop its SCAN_ROOTS row in check-doc-links.mjs); delete docs/CONSOLE-STREAMLINING-SUMMARY.md and .github/prompts/; rename docs/ARCHITECTURE.md to what it is or fold it into content/docs/guide/architecture-overview.md; add a 20-line docs/adr/README.md saying numbers are allocated in objectstack.
  • Exempt changesets/action from the Dependabot group or have the pin test read the SHA from the one place both share.
  • Code comments going forward: invariants, not incident history (the history stays on the PR / issue). Existing comments are not swept — this is a rule for new writing, and it argues against part of the current 完善设计器的每一个细节 objectui#9 / [WIP] Update documentation for project objectui#11 practice, so it is the maintainer's call.

Benefit: roughly 20k fewer tokens of mandatory context per agent session (token count is 未实测 — a tokenizer over AGENTS.md settles it); thousands fewer governed lines to re-approve per workflow change; the pin-versus-prose class of red disappears.

Refs: objectui#7833, objectui#7800, objectui#12255, objectui#13008.

Filed by the read-only whole-repo review session https://claude.ai/code/session_01BDtwYUWhLGyWLzYQjZ95Cf on 2026-10-24; the maintainer approved filing (「同意,创建任务」). Full evidence files sit in that session's scratchpad (objectui-review-report.md, findings-*.md). ⛔ Not a claim; for triage to grade and route. Ruled; see the first line.


Generated by Claude Code

Activity

  1. objectstack-fleet commented on Oct 24, 2026

    @objectstack-fleet
    Contributor

    Triage: first grade — documentation · priority:p3 · domain:devx · area:devpath · needs-user-decision · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-24T14:57Z

    ⛔ Not a claim, ⛔ not a dispatch. finding comes off.

    • For the maintainer: cut AGENTS.md to a normative core of about 250 lines, move the incident narrative out, and set a comment budget for workflows and scripts. These are rules-and-process changes on a governed surface. This is the same question as objectstack-ai/cloud#3194 for cloud.
    • Triage leaning: yes, on condition that every ⛔/"never" rule stays in the core file, moved verbatim. Fixing the three stale claims and cutting ROADMAP.md need no ruling and can go first.

    Generated by Claude Code

  2. objectstack-fleet commented on Oct 24, 2026

    @objectstack-fleet
    Contributor

    Director increment · batch objectstack-ai/objectui#390 item 2 · 2026-10-24T15:35Z

    Director seat, summon objectstack-ai/objectui#49 (session session_0162wFwDdLFGhaSvDdSnZ9Sx, account os-zhuang, in GOVERNED_APPROVERS — this seat submits no review and clicks nothing; written as objectstack-fleet[bot] through the relay; ledger #12708). ⛔ Not a ruling. The card carries no four-facet block; the block below is the seat's.

    Premise re-check (objectui origin/main 0984c77e1915): AGENTS.md 103,232 bytes, 630 lines; 53 lines carry ⛔ and 24 say "never" — the census a restructure must leave unchanged. ROADMAP.md 1,899 lines; header "Last Updated: May 6, 2026 · v3.3.2"; line 37 claims "80 Storybook stories" while .storybook is absent from the tree (control: AGENTS.md present). packages/console/dist is absent while AGENTS.md:587 names it. .github/prompts/ and docs/CONSOLE-STREAMLINING-SUMMARY.md are present; docs/postmortems/ and docs/adr/README.md are absent; package.json:204–205 pins file:.objectstack-pin/…. The gh CLI claim and the Dependabot group were not re-measured by this seat; the filer's readings stand as the filer's.

    Sibling ruling, inherited. cloud#3194 → A (ruling 6385321890, summon objectstack-ai/objectui#50 batch objectstack-ai/objectui#389 item 5, 2026-10-24): AGENTS.md becomes a core-rules file of at most 10 KB; every other section moves verbatim to topic pages (byte-preserving moves shown with git diff --color-moved, no sentence reworded); CLAUDE.md says the core plus its linked pages are the one instruction set. Under the skill's rule that a new branch of a ruled family reuses the mother ruling with its reasoning, the AGENTS.md half of this card takes those parameters as written. The objectui particulars — where the incident write-ups go (docs/postmortems/ or the governed .claude/skills/objectui-contributor/guides/) and the ≤250-line figure — are execution parameters of the same letter, not a semantic difference. The triage condition rides along: every ⛔ / "never" rule stays in the core verbatim, and the PR shows the 53 / 24 census unchanged.

    Needs no ruling (triage and seat agree): fixing the three stale claims; cutting ROADMAP.md to a short pointer file and dropping its SCAN_ROOTS row in check-doc-links.mjs; deleting docs/CONSOLE-STREAMLINING-SUMMARY.md and .github/prompts/; renaming or folding docs/ARCHITECTURE.md; a 20-line docs/adr/README.md; exempting changesets/action from the Dependabot group or reading the pinned SHA from one shared place. These ride the first PR; the AGENTS.md lines among them are Tier H and wait for the maintainer's approval as every governed change does.

    Left for the maintainer — two writing rules the mother ruling does not cover:

    Option What Cost
    A (recommended) Adopt both as prose rules in the new core: (i) in workflows and scripts a comment is one line of why plus a link, and the rationale lives in the ADR or the issue; (ii) code comments state invariants, not incident history — the history stays on the PR or the issue. No numeric budget, no new gate; the re-measure is the card's grep pattern, run by hand. Existing comments are not swept two lines in the core; 0 code
    B Restructure only; the writing rules stay as they are (the current objectstack-ai/objectui#9 / objectstack-ai/objectui#11 practice) 0

    Seat's recommendation: A. On ① both rules are what the mother ruling already does for AGENTS.md, applied one file down: a rule once, with its instrument pointer, and the story elsewhere. On ② every session pays the read (103 KB in full; the token count is unmeasured, the byte count is not), and the pin-versus-prose class already turned a test shard red (run 40054697521). On ③ an invariant in a comment is checkable and an incident narrative is not; A's risk is losing a regression's context, which is why the history stays on the PR and the pin tests read their SHA from one shared place. On ④ A adds no gate and no number — a comment budget as a gate would be a new gate, which the skill defaults to no, and the seat does not recommend one. Confidence gap: whether objectui's objectstack-ai/objectui#9 / objectstack-ai/objectui#11 comment practice is itself a maintainer ruling rather than current practice is unverified; if it is, B is the safer reading until the maintainer says otherwise.

    Workload: domain:devx lane · 2 PRs — PR 1 housekeeping and the stale claims (S; Tier H for the AGENTS.md lines); PR 2 the AGENTS.md restructure (M; Tier H; byte-preserving moves; ⛔ census before and after). Precedent: none landed (cloud#3194's PR is not yet open).

    os-decision-facets

    维护者速读

    AGENTS.md 拆成核心规则加主题页这一半,cloud 今天已经裁过 A(cloud#3194),objectui 这张直接继承、不用再裁,条件是所有 ⛔ 规则原文留在核心里(现在 53 行,拆完还得是 53 行)。剩下要您定的只有两条写法规则:工作流和脚本的注释只写一句为什么加一个链接;代码注释写不变量、不写事故史。席位意见 A(两条都采纳,写成规则,不加门禁、不定数字)。回 13455 A 或 B 即可。


    Generated by Claude Code

  3. objectstack-fleet commented on Oct 24, 2026

    @objectstack-fleet
    Contributor

    Ruling: batch objectstack-ai/objectui#390 item 2 · letter A · maintainer 「13455 A」 2026-10-24T15:47Z

    Director seat, summon objectstack-ai/objectui#49 (session session_0162wFwDdLFGhaSvDdSnZ9Sx, account os-zhuang, in GOVERNED_APPROVERS — this seat submits no review and clicks nothing; written as objectstack-fleet[bot] through the relay; ledger #12708, opening mark 6377506702). The maintainer answered in the summon chat, verbatim: 「13455 A」, on the seat increment 6386101274 and the triage grade 6385702437.

    Governing text: cloud#3194 ruling 6385321890 (letter A: a core-rules AGENTS.md of at most 10 KB, every other section moved verbatim to topic pages, CLAUDE.md naming core plus linked pages as the one instruction set); objectui AGENTS.md:563 (a seat never submits an approving review on a governed-surface pull request); objectui CLAUDE.md ("AGENTS.md is the source of truth").

    What the ruling binds (letter A):

    1. The AGENTS.md half inherits cloud#3194 A as written. AGENTS.md (today 103,232 bytes, 630 lines at objectui origin/main 0984c77e1915) becomes a core-rules file of at most 10 KB — each rule once, with its instrument pointer (pnpm check:* / test name), one line per topic page — and every other section moves verbatim: incident write-ups to docs/postmortems/ or the governed .claude/skills/objectui-contributor/guides/, the local-dev / port / multi-stack procedure to console-development.md. Byte-preserving moves shown with git diff --color-moved; no sentence reworded. CLAUDE.md says the core plus its linked pages are the one instruction set. Condition (triage 6385702437, kept): every ⛔ and "never" rule stays in the core verbatim — the census is 53 ⛔ lines and 24 "never" lines today and must read the same after the move.
    2. Two writing rules enter the new core as prose, with no gate and no numeric budget: (i) in workflows and scripts a comment is one line of why plus a link; the rationale lives in the ADR or the issue; (ii) code comments state invariants, not incident history — the history stays on the PR or the issue. Existing comments are not swept; the re-measure is the card's grep pattern, run by hand. Not taken: B (restructure only, writing rules unchanged); a comment budget enforced as a gate (a new gate; not recommended, not ruled).
    3. Housekeeping, no ruling owed, rides the first PR: fix the three stale claims (packages/console/dist at AGENTS.md:587 — absent in the tree; the gh CLI claim; the pin path, package.json:204–205 reads file:.objectstack-pin/…); cut ROADMAP.md (1,899 lines, header May 6 2026, "80 Storybook stories" with no .storybook) to a pointer file of at most about 40 lines and drop its SCAN_ROOTS row in scripts/check-doc-links.mjs; delete docs/CONSOLE-STREAMLINING-SUMMARY.md and .github/prompts/; rename or fold docs/ARCHITECTURE.md; add a 20-line docs/adr/README.md saying numbers are allocated in objectstack; exempt changesets/action from the Dependabot group or have the pin test read the SHA from the one shared place.

    Workload of the letter: domain:devx lane · 2 PRs — PR 1 housekeeping and stale claims (S; Tier H for the AGENTS.md lines); PR 2 the AGENTS.md restructure (M; Tier H; byte-preserving moves; ⛔ / never census before and after). No landed precedent (cloud#3194's PR is not yet open). Both PRs wait for the maintainer's approval as governed changes.

    Execution: needs-user-decision → pm:queue in this act; priority:p3, domain:devx, area:devpath stay as triage set them. The lane dispatches PR 1 first, then PR 2.

    os-decision-facets

    • ① 项目长远合理性:规则一次、带仪器指针、事故史另放,与 cloud#3194 同形;两条写法规则把同一原则推到工作流、脚本和代码注释。
    • ② 实际业务拉动:每个会话强制读 103 KB;pin 与散文冲突已让一个测试分片变红。
    • ③ 防 AI 犯错:不变量可检查、事故叙事不可检查;历史留在 PR / issue 上,⛔ 规则逐字保留并数数。
    • ④ 创业阶段不扩散:不加门禁、不定数字预算;受管行数变少。

    Generated by Claude Code

  4. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    Contributor

    Transferred 2026-10-26T03:59Z from objectstack-ai/objectui#13455, with its comments and timeline; the old URL redirects here. objectui moved into this repository as the ui/ workspace (epic #25677) and is being archived (#25854). The body is left exactly as filed.

    Paths. Read every repository path in the body with a ui/ prefix: packages/types/src is now ui/packages/types/src; .github/workflows is now ui/.github/workflows; packages/types is now ui/packages/types; apps/console is now ui/apps/console; docs/ARCHITECTURE.md is now ui/docs/ARCHITECTURE.md; docs/CONSOLE-STREAMLINING-SUMMARY.md is now ui/docs/CONSOLE-STREAMLINING-SUMMARY.md; .github/prompts is now ui/.github/prompts; docs/adr is now ui/docs/adr; and 3 more the same way.

    Not found under ui/ or at the root on main e167956e3f: packages/console/dist, scripts/__tests__/changeset-release-action-ref-pin.test.ts, docs/postmortems, docs/adr/README.md; re-check that premise before work starts.

    References. The bare issue numbers in the body were written in objectui and now resolve against this repository by mistake; read them as objectstack-ai/objectui#11.

    No stale pm:dispatched or assignee to strip.


    Generated by Claude Code

  5. 14 remaining items

  6. objectstack-fleet commented on Oct 27, 2026

    @objectstack-fleet
    Contributor

    Claim: PM loop round 10 · 2026-10-27T22:41Z
    Session: session_01JQwxbWNcDLYDRCTDktq8qQ (card thread cmsg_01U5RdnAAmkSQmZbqh6FtqZ8HMciW2CZaNxHWzy1o9Q6t9, dispatched by seat session session_01JQwxbaFpnMwgpCgneKe2qS)
    Account: os-warren (the seat's linked user; the card's assignee)
    Branch: claude/project-thread-huzn0l (the harness-pinned branch of the card thread; it names no issue, so this claim is the identity record)
    Worktree: the card thread's own container
    Domain: domain:devx
    Seat: domain:devx#1
    File surface: PR 2 of ruling 6435359095 (letter A), under the standing ruling 6407900763 items 1–2. ui/AGENTS.md becomes a core-rules file of at most 10 KB, each rule once with its instrument pointer. Every other section moves verbatim (git diff --color-moved, no moved sentence reworded) to topic pages: the guides under ui/.claude/skills/objectui-contributor/guides/ or docs/postmortems/ for incident narrative, console-development.md for the dev procedure. ui/CLAUDE.md names the core plus its pages as the one instruction set. Every ⛔ and "never" line stays in the core verbatim (counted before and after). Stale claims are fixed, ui/AGENTS.md:222's packages/console/dist among them. Existing code comments are not swept (6411838306). ⛔ Tier H: push to the thread branch and open NO PR. The seat routes the contract review first (#26617)
    Container & model: M, mode:thread (Warren's 「opus 很多,并发5」, 2026-10-27), model: default (opus), effort: high
    Clause-②: no
    Metadata-protocol: none
    Responsibility: maintainer ruling 6435359095 (「批 #408 同意」: dispatch now; the yes is the review spend)
    Thread-read: 6435359095
    Premise: holds on origin/main 5ec398dccb: ui/AGENTS.md is 36,089 bytes, so the 10 KB core is not yet met, and 27 lines carry ⛔ or "never" (read by the seat)
    Serial constraints cleared: #25712 (owner of ui/AGENTS.md nesting) closed; its PR 2 #26343 merged. #26080 slice 1 (claimed now) does not touch ui/AGENTS.md. No other devx seat is seated

  7. objectstack-fleet commented on Oct 27, 2026

    @objectstack-fleet
    Contributor

    Claim released · domain:devx#1 · session_01JQwxbaFpnMwgpCgneKe2qS · 2026-10-27T22:45Z · ⛔ not a claim

    Claim 6455395017 is withdrawn before any edit. The maintainer told the devx seat to finish the work already in flight and stop (「当前任务处理完,合并后就下班」), and devx seat 2 takes the queue next. Back to pm:queue with no assignee. Ruling 6435359095 (PR 2, ui/AGENTS.md, Tier H) stands. As read today, ui/AGENTS.md is 36,089 bytes against the 10 KB core, and 27 lines carry ⛔ or "never". Tier H work is pushed with no PR until the director contract review (#26617).

  8. objectstack-fleet commented on Oct 27, 2026

    @objectstack-fleet
    Contributor

    Measurements for the next seat · domain:devx#1 · 2026-10-27T22:47Z · ⛔ not a claim. Read-only reading by the released card thread at origin/main beb09fb2.

    1. Needs a ruling before dispatch. ui/AGENTS.md is 36,089 bytes over 261 lines. 18 lines carry ⛔ and 15 carry "never" (20 case-insensitive), 27 lines in all, totalling 16,789 bytes. The ⛔/never sentences on their own come to about 9.0 KB. Ruling 6407900763 asks for a core of at most 10 KB with every ⛔/never line verbatim in it, and both cannot hold. Whole lines give a core of about 20 KB. Lifting only the sentences gives about 13 KB, still over. The maintainer's options are:
      • whole lines, with the cap lifted;
      • sentences only, with the cap lifted;
      • a larger cap.
    2. The ruling's line-222 premise is false. Root packages/console/dist is real (@objectstack/console ships files: ["dist"], pnpm console:build builds it, and serve.ts mounts it). The stale part is :3001: the backend serves /_console on its own port.
    3. Other stale claims:
      • §7 names @objectstack/plugin-msw, but no such package exists and there is no msw dependency.
      • §2: skills/objectui/rules/styling.md sits at the repo root, not under ui/.
      • §5 Convert to monorepo with scoped packages #8 should read packages/app-shell/src/urlParams.ts.
      • §6: packages/core/src/registry.ts does not exist. The real file is packages/core/src/registry/Registry.ts, and the snippet's functions do not exist either.
    4. A dependent reader: scripts/check-agent-test-spelling.mjs COUNTER_EXAMPLE_FILES names ui/AGENTS.md ("trap two"). Moving that bullet means editing the script.
    5. Targets: guides/console-development.md exists (30.6 KB). docs/postmortems/ does not.
  9. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    Contributor

    domain:devx#1 · sunhaolin · session_017xRBcVyH9FzSkzAGmz8LNE

    State: pm:queue → pm:blocked · 2026-10-28T15:23Z · ⛔ not a claim. Thread-read: 6455483141.

    Blocked-by: #27297

    Reading 6455483141 item 1 found that ruling 6407900763 item 1's two parameters cannot both hold for PR 2: the 10 KB core, and every ⛔/never line verbatim in it. Re-measured at origin/main 6dbff8e20a: ui/AGENTS.md is 36,089 B, and its 27 ⛔/never lines alone are 16,789 B. Under the protocol, a question born while executing a ruling goes on a new card and this ruled card is not re-boxed. #27297 carries the question, options A/B/C, the four-axis analysis and the seat's recommendation (A). Rulings 6407900763 and 6435359095 stand unchanged. When #27297 is ruled, the devx seat returns this card to pm:queue and dispatches PR 2 with that letter on a Ruling-ref: line.

  10. objectstack-fleet commented on Oct 29, 2026

    @objectstack-fleet
    Contributor

    director#1 · os-bill · session_01Utp6CbQLcy8yg6vhJVXXi8

    State: pm:blocked → pm:queue · 2026-10-29T02:09Z · ⛔ not a claim. Thread-read: 6473067846.

    Ruling-ref: 6485892110 (#27297, letter A, maintainer 「27297 27286 同意,pr已审核」). The Blocked-by: #27297 of 6473067846 is released: the question born while executing 6435359095 is answered. For PR 2 the cap parameter of 6407900763 item 1 is replaced by that ruling — every ⛔ / never line stays whole and verbatim in the core, the 10 KB figure is dropped, the core's size is measured by the dev and reported in the PR. Everything else in 6407900763 items 1–2 and 6435359095 stands. The domain:devx seat dispatches PR 2 from here with Ruling-ref: 6485892110 beside 6435359095.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:devpathThe road — create, dev, verify, publish/install, connect an agent, iteratedocumentationImprovements or additions to documentationdomain:devxpm:queuepriority:p3

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions