Repository navigation
Post-swap docs: correct the branch model, PR policy, and stale AGENTS.md content #1873
Copy link
Copy link
Closed
Description
Sub-task of #1821 (go-live phase 8) — the documentation half of "everything that silently inverts when main becomes v2."
Docs that state the inverse of reality
Two files would send a contributor at the wrong branch:
README.md's "Repo status" callout: "Themainbranch is the legacy v1 implementation (bug fixes only)" —mainnow holds v2.CONTRIBUTORS.md's version table lists v2's base branch asmain, as does its "Label by version" paragraph. v2 PRs targetv2/main.
The branch model needs documenting canonically in one place (AGENTS.md) and correcting everywhere it's restated.
Policy gaps
- Every PR must reference an issue, from anyone, no exceptions. Not stated anywhere today.
- PRs are opened by repo maintainers only. The existing policy reads as being about outside contributors, so an org member with write access reasonably assumes it doesn't apply to them. Permission is not authorization.
- Branch names should carry the target version segment (
v2/ci/…, notci/…) so the two lines stay legible now that v1 and v2 branches coexist. - Version labels: the rule doesn't say exactly one of
v1/v2, and gives no tie-breaker when the target is unclear (should default tov2). - Screenshots proving a UI/TUI change have no documented home.
Stale content in AGENTS.md
- The TUI coverage bullet is wrong. It describes the Ink components /
App.tsx/hooks/as an "interim exclusion pending TUI: extend coverage gate to Ink components (lift interim exclusion) #1501" — TUI: extend coverage gate to Ink components (lift interim exclusion) #1501 closed 2026-06-29, andclients/tui/vitest.config.tsnow hasinclude: ["src/**/*.{ts,tsx}"]with onlysrc/tui-servers.tsexcluded. Anyone following the old text assumes new Ink components are ungated. - The completion checklist contradicts the pre-push gate, claiming
npm run validatecovers "lint, build, unit tests, and e2e tests" — while the gate section saysvalidateis explicitly not acceptable before pushing. - v1's PR base is given as
main; it isv1/main. - Project-tree omissions:
core/client/,docs/,scripts/(AGENTS.md);core/client/,docs/(README).core/clientis under the ≥90 coverage gate and imported by bothApp.tsxtrees. - The "run the tests" list omits the launcher (the only client missing, despite its own ≥90 gate) and
npm run test:scripts, and there's no overview of the test tiers.
Also in scope
- Every new issue must carry a milestone, set at create time and defaulting to the current milestone (the open one with the nearest due date) when unspecified. Today nothing in
AGENTS.mdmentions milestones at all, so they get set by habit rather than by rule — and an unmilestoned issue drops out of release planning as silently as an unlabeled one drops out of version filtering.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
v2Issues and PRs for v2Issues and PRs for v2
Activity
cliffhall commentedon Aug 1, 2026
Closed by #1866, merged to
v2/main. (Closing manually:Closes #Nonly auto-closes for PRs targeting the default branch, and v2 PRs targetv2/main.)