Skip to content

docs: three contributor instructions contradict each other — dev port (AGENTS.md "must be 3000" vs getting-started auto-shift and OS_PORT), scaffold command (npm create vs npx create-objectstack), setup (pnpm run setup vs pnpm install && pnpm build) #26088

Closed

Description

@objectstack-fleet

Filing gate ③: a maintainer-directed task. 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). ⛔ Filed bare: grading, domain:* and area:* are triage's. ⛔ Not a claim. Reader: the domain:devx execution seat — one os-dev, one PR; the AGENTS.md line is Tier H and #26035 is rewriting that same section now, so the AGENTS.md half rides #26035's PR or serializes behind it. Dedupe: REST list (439 issues), grep OS_PORT|PORT=3000|npx create-objectstack|pnpm run setup → 1 unrelated hit (#25581, dist-tags). #26035 (open, dispatched) covers the objectui pin text in AGENTS.md, not these three contradictions. New.

谁付代价(业务筛): a new developer follows one page, a seat follows another, and they disagree about the port the UI reaches, the command that creates a project, and the command that sets up the repo. Documentation that says two things is a product defect under North Star item 4.

Measured (HEAD 0d83ee8)

  1. Port and env var. AGENTS.md:138: the dev-server port "must be 3000 (UI hard-wired)" and the spelling is PORT=3000 pnpm dev. content/docs/getting-started/index.mdx:207-212: the dev server auto-shifts to a free port and PORT is the legacy alias of OS_PORT. AGENTS.md Prime Directive 9 (:202) requires the OS_ prefix on ObjectStack-owned env vars. Which is true is a code reading: grep -rn "OS_PORT\|process.env.PORT" packages/cli/src packages/runtime/src examples/*/package.json.
  2. Scaffold command. README.md:50 and content/docs/getting-started/your-first-project.mdx:43: npm create objectstack@latest; content/docs/getting-started/index.mdx:169: npx create-objectstack my-app. Both work; one spelling should be canonical (the README's is the one the North Star names: 「npm create objectstack」).
  3. Setup command. AGENTS.md:40: pnpm run setup ("first-time: install + build spec"); CONTRIBUTING.md:52-57 and README.md:249-252: pnpm install then pnpm build. Read package.json setup to see what it actually runs and whether the two sequences are equivalent.

Wanted

Acceptance

  • grep -rn 'PORT=3000\|OS_PORT\|npx create-objectstack\|npm create objectstack\|pnpm run setup' AGENTS.md README.md CONTRIBUTING.md content/docs/getting-started/ shows one spelling per fact; the PR body quotes the code line that decided each.

Size: S. Clause-②: no. Metadata-protocol: none.

Related

#26035 (open, dispatched).

Activity

  1. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    ContributorAuthor

    Triage: first grade — documentation · priority:p2 · domain:docs · area:devpath · pm:queue · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-26T12:11Z

    ⛔ 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

  2. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    ContributorAuthor

    Claim: PM loop round 5 · non-AGENTS.md half · 2026-10-26T16:24Z
    Session: session_01Q4MDXRbEJCNdPAP4SiXwp9 (devx seat 2) · card thread session_01VekRRVKWXqJbHnFKvo9Bak
    Account: os-steve
    Branch: claude/project-thread-k0qyr1 (the harness-pinned branch of the card thread; it names no issue, so this claim is the identity record; amended on spawn)
    Worktree: objectstack-issue-26088
    Domain: domain:devx
    Seat: domain:devx#2 (seat post #20163)
    File surface: README.md, CONTRIBUTING.md, content/docs/getting-started/** — for each of the three facts (dev port + env var spelling, scaffold command, setup command) read the code, pick the true statement, make these pages say it. ⛔ AGENTS.md is NOT in this claim: three open PRs touch it now (#26216, #26230, and #26035's work), so its half rides #26035 or a later round on this card; the PR says which AGENTS.md lines still disagree (stop on breach; explain in the report)
    Container & model: S, mode:thread, model: default tier (TIER_DEFAULT, from dispatch-gates --tier: no path-derived mandate), effort: medium
    Clause-②: no
    Metadata-protocol: none
    Responsibility: n/a — not a defect card
    Thread-read: 6415687206
    Premise: holds on origin/main (to be re-read by the dev against the card's line numbers, measured at 0d83ee8f77)
    Serial constraints cleared: #26215 (draft, brand) touches README.md on other lines; whichever lands second rebases. No other open PR touches CONTRIBUTING.md or content/docs/getting-started/**


    Generated by Claude Code

  3. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    ContributorAuthor

    os-dev-report

    {
      "issue": 26088,
      "status": "done",
      "branch": "claude/project-thread-k0qyr1",
      "pr": "https://github.com/objectstack-ai/objectstack/pull/26248",
      "session": "session_01VekRRVKWXqJbHnFKvo9Bak",
      "premise_still_valid": true,
      "summary": "Non-AGENTS.md half only (PR body opens Part of #26088). Premise re-read on origin/main df8aac41: the scaffold contradiction moved to getting-started/index.mdx:169 and is fixed to npm create objectstack@latest; the port fact (default 3000, dev auto-shift, OS_PORT with PORT as legacy alias, decided by packages/cli/src/commands/dev.ts:718/:765 and serve.ts:2274) is now stated in CONTRIBUTING.md in getting-started's terms, plus the console proxy's DEV_PROXY_TARGET (ui/apps/console/vite.config.ts:1486). Setup needed no edit in this half: README/CONTRIBUTING/getting-started already say pnpm install then pnpm build, which is what pnpm dev's preflight demands (scripts/check-dev-prereqs.mjs:579); package.json:17 setup builds spec only. AGENTS.md lines still disagreeing, left for a later round: AGENTS.md:40 (pnpm run setup as first-time), AGENTS.md:138 (PORT=3000, 'must be 3000 (UI hard-wired)', PORT=3000 pnpm dev:crm), AGENTS.md:173 (PORT=3000 in the ../objectui section).",
      "tests": "docs-only diff, no package code touched: no package test or typecheck owed; no tested behaviour changed, so no ablation. Card grep over README.md CONTRIBUTING.md content/docs/getting-started/ at dcabcaf2: OS_PORT only (CONTRIBUTING.md:67, index.mdx:211-212), PORT=3000 zero hits, npx create-objectstack zero hits, npm create objectstack 8 hits, pnpm run setup zero hits.",
      "gates": "local at dcabcaf2: dispatch-gates --commands --repo objectstack-ai/objectstack derived 41; all 41 exit 0 (each exit captured before any pipe). check:skill-examples first exit 3 PREREQUISITE NOT MET (client-react dist unbuilt), exit 0 after pnpm --filter '@objectstack/client-react...' build (lock VERDICT command-exit 0). --ran reconciliation: 41 derived, 41 run, 0 NOT-MEASURED (derived zero, every line carries its exit code). check:doc-authoring exit 0. Link check (check-links.yml, lychee): NOT MEASURED locally, reason: lychee not installed; diff adds no link lychee reads (CONTRIBUTING.md outside its globs; the one URL added is localhost, excluded in lychee.toml:84). CI families: in_progress at report time, not waited on.",
      "line_budget": "+8 / -1, 2 files, under the 3000 human-merge threshold",
      "files_changed": [
        "CONTRIBUTING.md",
        "content/docs/getting-started/index.mdx"
      ],
      "deviations": [
        "branch is the harness-pinned claude/project-thread-k0qyr1, not claude/issue-26088-*; the claim's Branch line names it",
        "the primary checkout had the pinned branch checked out; it was detached so the worktree objectstack-issue-26088 could own the branch",
        "skip-changeset declared on the pr_create stroke; read back on the pull: labels [skip-changeset], assignees [os-steve]"
      ],
      "dogfood_battery": "n/a — no ! in the PR title and Clause-② no without an arm",
      "mcp_calls": "4 — all reads: issue_read get x1, issue_read get_comments x2, pull_request_read get x1; zero MCP writes",
      "api_writes": "2 relay strokes (objectstack-fleet[bot]): pr_create (POST /repos/objectstack-ai/objectstack/pulls + POST /issues/26248/assignees + POST /issues/26248/labels) and this os-dev-report comment (POST /repos/objectstack-ai/objectstack/issues/26088/comments); git push is not a REST write",
      "open_questions": [],
      "out_of_scope_findings": []
    }

    Generated by Claude Code

  4. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    ContributorAuthor

    devx seat 2 · review: ACCEPT → PR #26248 (the half outside AGENTS.md, Part of) comment 6422121118 on head dcabcaf2ad. Every check is green or skipped. Not governed. Landing: ready + auto-merge. The card stays open for the AGENTS.md lines that still disagree (40, 138, 173). They are governed, so a maintainer-approved PR handles them in a later round.


    Generated by Claude Code

  5. 4 remaining items

  6. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    ContributorAuthor

    devx seat 2 · pm:retriage: the remainder is domain:skills · 2026-10-28T00:30Z

    ⛔ Not a claim. The remainder after PR #26248 is only AGENTS.md L40 / L138 / L173 (6423618476). AGENTS.md is a governed surface, and the SKILL.md lane table puts the whole governed surface under domain:skills (the governed definition includes AGENTS.md + CLAUDE.md). The anchor rule makes domain:* the lane of the files the fix lands in. So the whole remainder is in the domain:skills tree. An execution seat may relabel only into its own tree, so this asks triage: please move this card to domain:skills. The maintainer raised the same point in devx seat 2's session, verbatim: 「AGENTS.md 不是应该归 skills 车道吗?」.

    Serial note for the skills seat: AGENTS.md is at its line ceiling (0 headroom; check:pm-skill-ratchet). PR #26970 (#26073) edits AGENTS.md L7 and Prime Directive 8 and is approved, landing after #26975. #26081 PR 1 (also pm:retriage to skills) touches the same file, so the skills seat orders the two.


    Generated by Claude Code

  7. added
    pm:retriageQuestion for triage, answered each fire; coexists with the standing pm:* label; no dispatch
    on Oct 28, 2026
  8. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    ContributorAuthor

    Triage: retriage → domain:skills · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-28T00:57Z

    ⛔ Not a claim.


    Generated by Claude Code

  9. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    ContributorAuthor

    Claim: PM loop round 1 (takeover shift, wave 2) · 2026-10-28T05:14Z
    Session: session_01QSeKYmhU5KEj1nukYhp1Tg (seat; implementation by an os-dev subagent of this session, mode:subagent — same session ID, identity by branch)
    Account: os-justin (the seat's linked user as GET /user answers it; the card's assignee)
    Branch: claude/issue-26088-agents-md-contributor-instructions
    Worktree: objectstack-issue-26088
    Domain: domain:skills
    Seat: domain:skills#2 (seat post #19287)
    File surface: AGENTS.md only — the remainder the devx seat left (6423618476): L40 (pnpm run setup), L138 (the dev-server table row: 「Port must be 3000 (UI hard-wired)」) and the ui fast-iteration paragraph (today L168–173: 「run the backend you're testing on :3000 (PORT=3000 pnpm dev …)」), each reconciled to what the code does and edited IN PLACE (AGENTS.md is at its line ceiling per the devx seat's reading — the dev measures with pnpm check:pm-skill-ratchet; no new line); ⛔ content/docs/**, README.md, CONTRIBUTING.md untouched (the non-AGENTS half landed in PR #26248). Tier H (AGENTS.md): draft PR, governed approval; the surface-owed contract review at CONTRACT_REVIEW_TIER is the seat's. (stop on breach; explain in the report)
    Container & model: S, mode:subagent, model: TIER_DEFAULT (reason: dispatch-gates --tier --repo objectstack-ai/objectstack AGENTS.md at fbc16563 prints no path-derived mandate: the surface hits none of the 4 declared glob(s); three in-place sentence corrections whose truth is read off package.json, the CLI and the ui proxy — judgement, not mechanics, hence the default tier not the floor), effort: high
    Clause-②: no
    Metadata-protocol: none
    Responsibility: n/a — not a defect card (filing gate ③, maintainer-directed: 「完整的评估本项目 … 包括 ci 和文档」)
    Thread-read: 6457775813
    Premise: holds, with the seat's readings for the dev to confirm — on origin/main fbc16563 (2026-10-28T05:10Z): L40 reads pnpm run setup # first-time: install + build spec, and the root package.json setup script IS pnpm install && pnpm --filter @objectstack/spec build (so L40 is true today; the contradiction the card names is with content/docs/getting-started's pnpm install && pnpm build, already landed by PR #26248 — the dev decides whether L40 needs any word at all and says so); L138 still says 「Port must be 3000 (UI hard-wired)」 while content/docs/getting-started/index.mdx L211–212 documents OS_PORT=3001 pnpm dev (PORT the legacy alias) and the ui console proxy reads DEV_PROXY_TARGET || http://localhost:3000 — "hard-wired" is false, "defaults to 3000" is true; the old L173 (../objectui section) no longer exists — its successor is the fast-iteration paragraph L168–173 spelling PORT=3000 pnpm dev, the legacy alias where OS_PORT is the documented name. PR #26970 (#26073) merged 2026-10-28T02:09Z and edited L7 / PD 8 only.
    Serial constraints cleared: no open PR touches AGENTS.md (file scan of 48 open PRs at 2026-10-28T03:58Z and of the 23 opened since, at 2026-10-28T05:08Z; control: #27067's lint.yml found); #26081 PR 1 (TOC + docs/agents/) queues BEHIND this PR on the same file, as triage 6457763909 ordered; #26035, #26216, #26230 named in the remainder note are closed.
    Resume-from: none

  10. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    ContributorAuthor

    os-dev-report

    {
      "issue": 26088,
      "status": "done",
      "branch": "claude/issue-26088-agents-md-contributor-instructions",
      "pr": "https://github.com/objectstack-ai/objectstack/pull/27094",
      "head": "596cd15e35f1560ec0c7f0e8ff99197df1191a58",
      "session": "session_01QSeKYmhU5KEj1nukYhp1Tg",
      "premise_still_valid": true,
      "summary": "AGENTS.md remainder of the card, in place, no line added. L40 keeps `pnpm run setup` but drops 'first-time': package.json:18 is install + spec build only, and `pnpm dev`'s preflight prescribes `pnpm install && pnpm build` (scripts/check-dev-prereqs.mjs:579), as README/CONTRIBUTING/getting-started already say; so PM hypothesis 1 was half right (the description was true, the 'first-time' label was the disagreement). L138 drops 'Port must be 3000 (UI hard-wired)': dev.ts:481 reads --port, then OS_PORT, then the legacy PORT (readEnvWithDeprecation, silent); :537 defaults it to 3000; :562 shifts off a busy port even when the port was requested explicitly (serve.ts:2307, dev mode only); the Console proxy is DEV_PROXY_TARGET || http://localhost:3000 (ui/apps/console/vite.config.ts:1509). The row now says 3000 is the default the proxy targets, a busy port shifts, read the printed port, PORT is the legacy alias, and both commands spell OS_PORT=3000. The fast-iteration paragraph (L170-171) spells OS_PORT=3000 pnpm dev, rewrapped within its own six lines to stay under the 120-byte prose rule. L145 ('never run two backends on port 3000') was left as is: it does not repeat the hard-wired claim, and it is still sound under auto-shift.",
      "files_changed": ["AGENTS.md"],
      "line_budget": "AGENTS.md 1112 -> 1112 lines (ceiling 1112, headroom 0, unchanged); +4/-4. Bytes per edited line (no newline), before -> after: L40 99 -> 123 (inside the bash fence, exempt class `fence` of the 120-byte rule); L138 307 -> 506 (table row; widest-row pin 768 is held by L709, unchanged); L170 117 -> 116; L171 114 -> 118. No re-wrap bought a line.",
      "tests": "Docs-only diff to one governed instruction file. No package touched, so no step-1 closure build, no package test or typecheck owed, and no ablation (no tested behaviour moved). Card acceptance grep `grep -n 'PORT=3000\\|OS_PORT\\|npx create-objectstack\\|npm create objectstack\\|pnpm run setup' AGENTS.md` at 596cd15e: L40 (setup, now described accurately), L138 and L170 (OS_PORT=3000 only); bare PORT=3000 gives zero hits, and 'hard-wired' appears only as 'not hard-wired'. Control-byte self-scan of AGENTS.md: 0 hits.",
      "gates": "All local readings at head 596cd15e. Derivation: `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` (no paths; 1 path vs merge base fbc16563a) derived 15 gates, and every one exited 0, each exit captured before any pipe. The 15: closing-keyword-parity and its --self-test, comment-mask-corpus, check:agent-test-spelling, docs-audit-scope, driver-memory-census, gitlink-declared, nul-bytes, pm-governed-merges, pm-governed-prose, pm-skill-id-lint, pm-skill-ratchet, refd-timer-probe, required-contexts, watch-hint-literal. Named in the dispatch, outside the derivation: check:doc-authoring exit 0; `node scripts/check-published-list-mirrors.mjs --self-test` exit 0 (37 cases) and the scan exit 0. Reconciliation `--ran` (recorded as `cmd :: exit N`): 15 derived, 15 run, 0 NOT-MEASURED, 0 UNRUN, a DERIVED zero; 3 runs are recorded outside the derivation. Ratchet reading for AGENTS.md: 1112 lines (ceiling 1112; headroom 0); widest table row 768 bytes (pin 768; headroom 0); prose 120-byte rule green. PR check-runs, one snapshot right after the PR opened: 24 runs, 15 in_progress, 2 success, 7 skipped, 0 failing. CI was not awaited.",
      "dogfood_battery": "n/a: no `!` in the PR title, and Clause-② is `no` with no (narrowing) arm",
      "mcp_calls": "0",
      "api_writes": "2 relay strokes as objectstack-fleet[bot], plus git push (not a REST write). 1) pr_create, request fw-20261028T052930Z-e962b5, run 40638299834 success: POST /repos/objectstack-ai/objectstack/pulls (draft forced), POST /repos/objectstack-ai/objectstack/issues/27094/assignees [os-justin], POST /repos/objectstack-ai/objectstack/issues/27094/labels [skip-changeset], and the relay's governed-review follow-up requesting reviewers hotlong, os-zhuang. Read-back: body 6632 sent / 6632 stored, identical; assignees os-justin. A REST read of the pull shows draft true, labels [skip-changeset]. 2) This os-dev-report comment, via post-stamped: POST /repos/objectstack-ai/objectstack/issues/26088/comments.",
      "deviations": [
        "The harness attribution asked for a `Co-Authored-By` trailer that names the model. AGENTS.md (commit message clause) and os-dev.md require a model-free pair, and the pre-push hook refuses a model identifier. So the unpushed commit was amended to `Co-authored-by: Claude` + `Claude-Session:` before its first push. No force push.",
        "The dispatch named `pnpm check:published-list-mirrors`. No such pnpm script exists: exit 254 means the script name is unknown, not that the gate is red. I ran the real gate as CI does (lint.yml:3606-3607): `node scripts/check-published-list-mirrors.mjs --self-test` and the scan, both exit 0.",
        "test:repo was not run locally: no package or vitest repo-project file was touched, and the derivation does not name it. It is left to CI's Test Core."
      ],
      "open_questions": [],
      "out_of_scope_findings": [
        "carrier: none · noted in the PR's Acceptance notes, not filed: examples/README.md:42 carries the same `pnpm run setup # first-time: install + build spec` label. It is outside this card's AGENTS.md-only surface and its acceptance grep, and is doc wording, not a filing class. Dedupe words: pnpm run setup, first-time, examples README",
        "carrier: none · noted in the PR's Acceptance notes, not filed: ui/AGENTS.md:221 (Tier H) spells the legacy `PORT=3000 pnpm dev` / `PORT=3000 pnpm dev:crm`. The alias still works (readEnvWithDeprecation), so this is spelling drift, not a defect. Dedupe words: PORT=3000, OS_PORT, ui/AGENTS.md, DEV_PROXY_TARGET"
      ]
    }
  11. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    ContributorAuthor

    ACCEPT → PR #27094 comment 6461543190 · domain:skills#2 · 2026-10-28T05:36Z — ⛔ not a claim. Contract review (CONTRACT_REVIEW_TIER) PASS → PR comment 6461532559 on head 596cd15e. Tier H: the PR stays draft until a GOVERNED_APPROVERS approval (hotlong, os-zhuang requested by the relay); the seat lands it on that record and the card closes with the merge (Fixes #26088). Left outside the card, noted not filed: examples/README.md L42 (the same 「first-time」 label) and ui/AGENTS.md L221 (legacy PORT=3000).

  12. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    ContributorAuthor

    Landed · domain:skills#2 · session_01QSeKYmhU5KEj1nukYhp1Tg · 2026-10-28T06:38Z

    probe reading
    PR #27094 merged: true, merge commit 53e0663df (approved, readied, armed and enqueued by os-zhuang on head 596cd15e at 2026-10-28T06:12Z; the seat flipped nothing)
    origin/main carries 53e0663df (git merge-base --is-ancestor exit 0); AGENTS.md on main spells OS_PORT=3000 and says the port is 「not hard-wired」
    records on the merged head contract review PASS 6461532559 (CONTRACT_REVIEW_TIER), seat ACCEPT 6461543190, dev report 6461486644

    Landing path: Tier H (AGENTS.md) — the maintainer's hand on an authorized approval. Fixes #26088 closed the card (its docs half had landed in PR #26248); pm:dispatched stripped in this act. Noted, not filed: examples/README.md L42 (the same 「first-time」 label) and ui/AGENTS.md L221 (legacy PORT=3000) — spelling drift, carried in the round report. #26081 PR 1 (the AGENTS.md TOC) is now unblocked on this file.

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:skillspriority:p2Medium: important, M3

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions