Add a Branch-Selection Rule for Negative Existence Claims - #716
Conversation
GOVERNANCE.md "Verification Discipline" already covers a clone that fetched stale content, but not a clone that fetched correctly from the wrong ref. Add a sibling bullet requiring a "does not exist" claim to name the branch it was checked against and to check the branch the repo's own model designates as current before asserting absence repo-wide. Mirror the same rule in the agent-conduct skill's "Before Claiming Done" excerpt. Fixes #714 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds an explicit verification rule to prevent incorrect "does not exist" claims caused by searching the wrong branch (e.g., checking main when in-flight content is on develop), and mirrors that rule into the agent-conduct skill so it surfaces at the "Before Claiming Done" decision point.
Changes:
- Add a new "Verification Discipline" bullet requiring negative existence claims to name the branch checked and to verify against the model-designated branch (e.g.,
develop) before asserting repo-wide absence. - Update the
agent-conductskill's "Before Claiming Done" excerpt to include the same branch-selection requirement.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| GOVERNANCE.md | Adds a sibling verification bullet requiring negative existence claims to state and validate the branch used (and to check the model-designated branch). |
| .agents/skills/agent-conduct/SKILL.md | Mirrors the new governance rule into the skill's "Before Claiming Done" checklist so it is surfaced at the relevant decision moment. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Both GOVERNANCE.md "Branching Model" and the operational-vs-release-workflow skill described the develop -> main flow without ever stating the specific trap that caused #714: GitHub's own 'default branch' repository setting reads main, but develop is where work starts and where in-flight content lives. A tool that branches from 'the default branch' lands on main and can silently miss content already merged to develop. State that explicitly in both places. Refs #714 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.
Suppressed comments (2)
GOVERNANCE.md:62
- The parenthetical "(a fresh worktree, a new clone)" reads like any newly created worktree lands on the repo's default branch. A git worktree can be created from the current HEAD or an explicit branch; the issue here is specifically tools/workflows that default to the repo's default branch. Tighten the wording to avoid an over-broad (and potentially inaccurate) claim.
(a fresh worktree, a new clone) lands on `main` and can silently miss content already merged to
.agents/skills/operational-vs-release-workflow/SKILL.md:46
- "(a fresh worktree, a new clone's initial checkout)" can be read as claiming that any newly created worktree lands on the repo's default branch. The actual pitfall is worktrees/clones created from (or defaulting to) the default branch. Adjust the wording to keep this bullet factually tight.
(a fresh worktree, a new clone's initial checkout) lands on `main` and can silently miss
Address Copilot review feedback on PR #716: 'a fresh worktree, a new clone' overclaimed that any newly created worktree lands on the default branch, when the actual pitfall is one that defaults to it. Rephrase both spots as 'a worktree or clone that defaults to the default branch'. Also run scripts/build_dist.py, which the prior two commits left stale (the CI 'Lint sources job' check caught this) since .agents/skills content is mirrored into .claude-plugin/fleet-skills. Refs #714 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.
Suppressed comments (3)
GOVERNANCE.md:63
- The bolded sentence is split across a line break, which is inconsistent with the surrounding Markdown style and can be brittle for renderers/linters. Keep the full strong-emphasis span on a single line, then wrap after the closing **.
**GitHub's own "default branch" repository setting reads `main`, but `develop` is where work
starts and where in-flight content lives**, so a worktree or clone that defaults to "the default
branch" lands on `main` and can silently miss content already merged to `develop` but not yet
promoted. Branch from `develop` for a `release`-model repo unless the task is explicitly about
.agents/skills/operational-vs-release-workflow/SKILL.md:49
- This list item's bold emphasis spans a hard line break. To keep formatting robust and consistent, close the ** on the same line as the opening, then wrap after it. While touching the sentence, consider removing the awkward "cloning for" phrasing.
- **GitHub's repository setting for "default branch" reads `main`, but `develop` is where work
starts and where in-flight content lives.** A worktree or clone that defaults to "the default
branch" lands on `main` and can silently miss content that has merged to `develop` but not yet
been promoted. Before branching off, cloning for, or asserting something absent from this repo,
check `develop`, not just whichever branch a tool defaulted to. See GOVERNANCE.md "Verification
.claude-plugin/fleet-skills/skills/operational-vs-release-workflow/SKILL.md:49
- This list item's bold emphasis spans a hard line break. To keep formatting robust and consistent, close the ** on the same line as the opening, then wrap after it. While touching the sentence, consider removing the awkward "cloning for" phrasing.
- **GitHub's repository setting for "default branch" reads `main`, but `develop` is where work
starts and where in-flight content lives.** A worktree or clone that defaults to "the default
branch" lands on `main` and can silently miss content that has merged to `develop` but not yet
been promoted. Before branching off, cloning for, or asserting something absent from this repo,
check `develop`, not just whichever branch a tool defaulted to. See GOVERNANCE.md "Verification
…-worktree Skill (#717) ## What this does One consolidated update covering #711 and #714, per the maintainer's direction that the two land together rather than as scattered rules. It includes the `fix-714-branch-verification` branch (all of PR #716 plus its unpushed Copilot nit-fix commit), so **this PR supersedes #716**, which can be closed unmerged. ### The worktree mandate (#711) - **GOVERNANCE.md "Repository Boundaries and Write Safety"** gains the affirmative task-start rule: every task, a continuation of a prior session's task included, isolates into its own git worktree before its first file edit, based on the branch work starts on per "Branching Model". The primary checkout is the maintainer's own surface. - **New `repo-worktree` skill** (kept-authority shape: GOVERNANCE keeps the law, the skill is the task-start surface) carrying the mandate's trigger moments plus the mechanics as its own content: base-branch choice, the #699 layout convention (`~/repos/<Repo>`, `~/repos/worktrees/<Repo>-<task-slug>`), the `git worktree add` + `EnterWorktree path:` sequence, listing, and post-merge cleanup. The physical migration of existing checkouts stays tracked in #699. - **`git-commit-conventions` tightened**: stage by explicit path, never `git add -A` or `git add .`, and the pre-commit `git status` check generalizes from "the maintainer's own uncommitted edits" to "any change this session did not make", with ask-or-stop as the response, never bundling. The GOVERNANCE "Git and Commit Rules" summary matches. - **Host-wide agent-safety block** (`host-setup/agent-safety/claude-md-safety.md`) gains the same task-start bullet, naming "worktree" in so many words so Claude Code's `EnterWorktree` tool is armed even in sessions no `AGENTS.md` reaches. Machines pick it up on their next installer re-run (#365 cadence). - **AGENTS.md map** annotates the boundaries row with the new skill and updates the no-skill-by-decision paragraph and the closing skill inventory. ### The base-branch rule (#714, from PR #716) Carried in unchanged apart from consolidation cross-links: GitHub's default-branch setting reads `main` but work starts on `develop`, so a worktree defaulted to "the default branch" silently misses in-flight content, and a "does not exist" claim names the branch it was checked against. ## Verification - `build_dist.py --check` clean (both skill trees regenerated and committed together) - `prose_lint.py`, `repo_gate.py`, `host_gate.py` all pass - `test_build_dist.py` (19), `test_prose_lint.py` (244), `test_repo_gate.py` (70), `test_host_gate.py` (72), `test_skills_install.py` (29), `host-setup/agent-safety/test_install.py` (45), `spec/validate.py` all pass - Signed-commit probe run before committing (sig=G, noreply identity on author and committer) Closes #711. Closes #714. Supersedes #716. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
What
GOVERNANCE.md"Verification Discipline" already carries "A local clone is not thebranch it names," but that bullet is phrased around staleness (a clone that has not
fetched recently). This adds a sibling bullet for the same failure mode with a
different trigger: a clone that fetched correctly but from the wrong ref for the task.
kind of content being searched for (
develop, per "Branching Model," for arelease-model repo's in-flight content), that branch gets checked before assertingabsence repo-wide.
agent-conductskill's "Before Claiming Done" excerpt picks up the sameaddition, since it already surfaces the sibling bullet at its decision moment.
Why
A worktree based on
main(this fleet's default branch) hiddevelop-only skillfiles during a prior task, and the agent reported them as nonexistent anywhere in the
repo instead of naming the branch the negative claim was checked against.
Fixes #714
🤖 Generated with Claude Code