Skip to content

Add a Branch-Selection Rule for Negative Existence Claims - #716

Closed
ptr727 wants to merge 3 commits into
developfrom
fix-714-branch-verification
Closed

Add a Branch-Selection Rule for Negative Existence Claims#716
ptr727 wants to merge 3 commits into
developfrom
fix-714-branch-verification

Conversation

@ptr727

@ptr727 ptr727 commented Aug 14, 2026

Copy link
Copy Markdown
Owner

What

GOVERNANCE.md "Verification Discipline" already carries "A local clone is not the
branch 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.

  • A "does not exist" claim now has to name the branch it was checked against.
  • Where the repo's branching model designates a different branch as current for the
    kind of content being searched for (develop, per "Branching Model," for a
    release-model repo's in-flight content), that branch gets checked before asserting
    absence repo-wide.
  • The agent-conduct skill's "Before Claiming Done" excerpt picks up the same
    addition, since it already surfaces the sibling bullet at its decision moment.

Why

A worktree based on main (this fleet's default branch) hid develop-only skill
files 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

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>
Copilot AI lite review requested due to automatic review settings August 14, 2026 22:56

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-conduct skill'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>
Copilot AI review requested due to automatic review settings August 14, 2026 22:59

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
Copilot AI review requested due to automatic review settings August 14, 2026 23:05

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@ptr727

ptr727 commented Aug 14, 2026

Copy link
Copy Markdown
Owner Author

Superseded by #717, which folds this branch (through 6263752) plus the pending wording nit-fix into a combined update with #711. Closing in its favor.

@ptr727 ptr727 closed this Aug 14, 2026
ptr727 added a commit that referenced this pull request Aug 15, 2026
…-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>
@ptr727
ptr727 deleted the fix-714-branch-verification branch August 15, 2026 00:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants