Skip to content

Post-swap docs: correct the branch model, PR policy, and stale AGENTS.md content #1873

Description

@cliffhall

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: "The main branch is the legacy v1 implementation (bug fixes only)"main now holds v2.
  • CONTRIBUTORS.md's version table lists v2's base branch as main, as does its "Label by version" paragraph. v2 PRs target v2/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/…, not ci/…) 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 to v2).
  • 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, and clients/tui/vitest.config.ts now has include: ["src/**/*.{ts,tsx}"] with only src/tui-servers.ts excluded. Anyone following the old text assumes new Ink components are ungated.
  • The completion checklist contradicts the pre-push gate, claiming npm run validate covers "lint, build, unit tests, and e2e tests" — while the gate section says validate is explicitly not acceptable before pushing.
  • v1's PR base is given as main; it is v1/main.
  • Project-tree omissions: core/client/, docs/, scripts/ (AGENTS.md); core/client/, docs/ (README). core/client is under the ≥90 coverage gate and imported by both App.tsx trees.
  • 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.md mentions 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.

Metadata

Metadata

Assignees

Labels

v2Issues and PRs for v2

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions