diff --git a/.agents/skills/agent-conduct/SKILL.md b/.agents/skills/agent-conduct/SKILL.md index d02e4e04..c2284fac 100644 --- a/.agents/skills/agent-conduct/SKILL.md +++ b/.agents/skills/agent-conduct/SKILL.md @@ -39,7 +39,7 @@ Claims about a pull request being reviewed, clean, or mergeable are owned by the - **Durable knowledge lands in the committed docs, not in agent memory**, as part of the change that surfaced it, per `GOVERNANCE.md` "Durable Knowledge and Self-Improvement". Memory does not survive a new session or machine, so it holds only environment nuance and in-flight state. - **Where the governing doc is carried from the hub, file the finding against `ptr727/ProjectTemplate`.** Patching the local copy leaves every sibling repo with the same trap. Search open and closed issues first, then update the matching issue or file a new one. -- **A review flags an instance, so fix the class**: sweep for the siblings before replying, because reviewers sample rather than enumerate. +- **A review flags an instance, so a fix covers the class, bounded to what this change touched or broke**: when fixing a finding, sweep for its siblings before replying, because reviewers sample rather than enumerate, fix each one that sits in a file the diff touches or that the change itself put wrong, and file the rest rather than folding them in, per `GOVERNANCE.md` "Verification Discipline". - **A rule that keeps needing restating** is usually a stale or missing skills install, so run `python3 scripts/skills_install.py --report` from a hub checkout (the `fleet-conformance-check` skill) before concluding the rule does not exist. ## Delegation, in One Paragraph diff --git a/.agents/skills/pr-review-conduct/SKILL.md b/.agents/skills/pr-review-conduct/SKILL.md index ece467d3..b8b0644f 100644 --- a/.agents/skills/pr-review-conduct/SKILL.md +++ b/.agents/skills/pr-review-conduct/SKILL.md @@ -41,11 +41,14 @@ visible comments, routinely still carries a finding nobody has answered. Treatin 2. A review is confirmed on the **current head SHA**, matched by commit SHA rather than assumed from a green merge-state. A push makes checks go green *before* the re-review lands, and the matched review is **read**, not just counted. A review can carry the head SHA and still decline - the PR outright, or say it read only part of the changed files. `pr_review.py`'s - `review_on_head` names Copilot's own coverage specifically, the currently required reviewer, - not "no review of any kind covers this head": a trialed advisory reviewer (CodeRabbit, - Qodo) carrying the exact head under `other_reviewed`, with an empty review body and no new - threads, is its own ordinary "reviewed, nothing to flag" shape, not a missing review (#1066). + the PR outright, or say it read only part of the changed files. The coverage this item + requires is Copilot's, and CodeRabbit and Qodo are advisory, since the hub's + `docs/pr-reviewer-evaluation.md` "Status" names Copilot the incumbent and says no candidate is + a required reviewer: an advisory reviewer's absence blocks nothing, while its findings owe + item 3 exactly as Copilot's do. `pr_review.py`'s `review_on_head` names Copilot's own coverage + specifically, not "no review of any kind covers this head": an advisory reviewer carrying the + exact head under `other_reviewed`, with an empty review body and no new threads, is its own + ordinary "reviewed, nothing to flag" shape, not a missing review (#1066). 3. **Every** finding on that head SHA is closed: threads resolved, issue-level comments (which have no resolve action) triaged and replied to, **and** the low-confidence findings collapsed in the review body investigated and answered. Those appear in no thread, so polling threads @@ -55,6 +58,22 @@ visible comments, routinely still carries a finding nobody has answered. Treatin give each one the same triage the low-confidence findings above already get (#1058). Qodo's own `Resolved`/`Dismissed` self-tracked badge is a fast pre-triage signal, not a substitute for reading the finding, spot-verify against `gh pr diff` rather than trusting it outright. + What closing a finding owes turns on whether it is `pre-existing`. A finding on text inside a + canonical Markdown unit, one the hub's `scripts/canonical_review.py list` names, classed + `pre-existing` by the classes `local-strict-review` "Disposing of Findings" defines for a + local pass, applied here to a PR-hosted finding, is outcome 4 of "Every finding ends in one + of five outcomes" below applied once per unit rather than once per finding: the round gathers + that unit's such findings onto the unit's tracker, an open hub issue whose title carries the + unit key, retitled by the change that moves the key and filed by whichever round first needs + it, and answers each finding with that issue's link, resolving a thread on that reply, so a + `pre-existing` remark on a sentence the change never touched costs one link rather than a + decline or an issue per finding. The batch runs in the hub, which authors the text of every + verbatim unit. A carrying repository routes a finding on a verbatim unit by fidelity rather + than by class, since a resync writes the whole text there: it declines the finding under + that section's outcome 2, ownership sitting elsewhere, and files it on the same tracker, + while a finding on an intent unit is filed there too, the carrier adapting its own copy + meanwhile, since the defect is still fixed at the source. Every other finding, a `style` + remark on untouched text included, takes its own outcome in that section. 4. Nothing in the review was a shape the tooling could not read (an unrecognized heading, a moved section, an unfamiliar coverage wording). An unrecognized shape blocks the gate on its own. File an issue naming it and quoting the body, rather than guessing what the new wording diff --git a/.claude-plugin/fleet-skills/.source-digests/agent-conduct b/.claude-plugin/fleet-skills/.source-digests/agent-conduct index 92052dc4..59ae2a2a 100644 --- a/.claude-plugin/fleet-skills/.source-digests/agent-conduct +++ b/.claude-plugin/fleet-skills/.source-digests/agent-conduct @@ -1 +1 @@ -be7d43fc59180c19 +c159c9d53085e97d diff --git a/.claude-plugin/fleet-skills/.source-digests/pr-review-conduct b/.claude-plugin/fleet-skills/.source-digests/pr-review-conduct index 521d59e3..9dfe0191 100644 --- a/.claude-plugin/fleet-skills/.source-digests/pr-review-conduct +++ b/.claude-plugin/fleet-skills/.source-digests/pr-review-conduct @@ -1 +1 @@ -96806c16138e5c6a +b72736e1747ad6bc diff --git a/.claude-plugin/fleet-skills/skills/agent-conduct/SKILL.md b/.claude-plugin/fleet-skills/skills/agent-conduct/SKILL.md index d02e4e04..c2284fac 100644 --- a/.claude-plugin/fleet-skills/skills/agent-conduct/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/agent-conduct/SKILL.md @@ -39,7 +39,7 @@ Claims about a pull request being reviewed, clean, or mergeable are owned by the - **Durable knowledge lands in the committed docs, not in agent memory**, as part of the change that surfaced it, per `GOVERNANCE.md` "Durable Knowledge and Self-Improvement". Memory does not survive a new session or machine, so it holds only environment nuance and in-flight state. - **Where the governing doc is carried from the hub, file the finding against `ptr727/ProjectTemplate`.** Patching the local copy leaves every sibling repo with the same trap. Search open and closed issues first, then update the matching issue or file a new one. -- **A review flags an instance, so fix the class**: sweep for the siblings before replying, because reviewers sample rather than enumerate. +- **A review flags an instance, so a fix covers the class, bounded to what this change touched or broke**: when fixing a finding, sweep for its siblings before replying, because reviewers sample rather than enumerate, fix each one that sits in a file the diff touches or that the change itself put wrong, and file the rest rather than folding them in, per `GOVERNANCE.md` "Verification Discipline". - **A rule that keeps needing restating** is usually a stale or missing skills install, so run `python3 scripts/skills_install.py --report` from a hub checkout (the `fleet-conformance-check` skill) before concluding the rule does not exist. ## Delegation, in One Paragraph diff --git a/.claude-plugin/fleet-skills/skills/pr-review-conduct/SKILL.md b/.claude-plugin/fleet-skills/skills/pr-review-conduct/SKILL.md index ece467d3..b8b0644f 100644 --- a/.claude-plugin/fleet-skills/skills/pr-review-conduct/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/pr-review-conduct/SKILL.md @@ -41,11 +41,14 @@ visible comments, routinely still carries a finding nobody has answered. Treatin 2. A review is confirmed on the **current head SHA**, matched by commit SHA rather than assumed from a green merge-state. A push makes checks go green *before* the re-review lands, and the matched review is **read**, not just counted. A review can carry the head SHA and still decline - the PR outright, or say it read only part of the changed files. `pr_review.py`'s - `review_on_head` names Copilot's own coverage specifically, the currently required reviewer, - not "no review of any kind covers this head": a trialed advisory reviewer (CodeRabbit, - Qodo) carrying the exact head under `other_reviewed`, with an empty review body and no new - threads, is its own ordinary "reviewed, nothing to flag" shape, not a missing review (#1066). + the PR outright, or say it read only part of the changed files. The coverage this item + requires is Copilot's, and CodeRabbit and Qodo are advisory, since the hub's + `docs/pr-reviewer-evaluation.md` "Status" names Copilot the incumbent and says no candidate is + a required reviewer: an advisory reviewer's absence blocks nothing, while its findings owe + item 3 exactly as Copilot's do. `pr_review.py`'s `review_on_head` names Copilot's own coverage + specifically, not "no review of any kind covers this head": an advisory reviewer carrying the + exact head under `other_reviewed`, with an empty review body and no new threads, is its own + ordinary "reviewed, nothing to flag" shape, not a missing review (#1066). 3. **Every** finding on that head SHA is closed: threads resolved, issue-level comments (which have no resolve action) triaged and replied to, **and** the low-confidence findings collapsed in the review body investigated and answered. Those appear in no thread, so polling threads @@ -55,6 +58,22 @@ visible comments, routinely still carries a finding nobody has answered. Treatin give each one the same triage the low-confidence findings above already get (#1058). Qodo's own `Resolved`/`Dismissed` self-tracked badge is a fast pre-triage signal, not a substitute for reading the finding, spot-verify against `gh pr diff` rather than trusting it outright. + What closing a finding owes turns on whether it is `pre-existing`. A finding on text inside a + canonical Markdown unit, one the hub's `scripts/canonical_review.py list` names, classed + `pre-existing` by the classes `local-strict-review` "Disposing of Findings" defines for a + local pass, applied here to a PR-hosted finding, is outcome 4 of "Every finding ends in one + of five outcomes" below applied once per unit rather than once per finding: the round gathers + that unit's such findings onto the unit's tracker, an open hub issue whose title carries the + unit key, retitled by the change that moves the key and filed by whichever round first needs + it, and answers each finding with that issue's link, resolving a thread on that reply, so a + `pre-existing` remark on a sentence the change never touched costs one link rather than a + decline or an issue per finding. The batch runs in the hub, which authors the text of every + verbatim unit. A carrying repository routes a finding on a verbatim unit by fidelity rather + than by class, since a resync writes the whole text there: it declines the finding under + that section's outcome 2, ownership sitting elsewhere, and files it on the same tracker, + while a finding on an intent unit is filed there too, the carrier adapting its own copy + meanwhile, since the defect is still fixed at the source. Every other finding, a `style` + remark on untouched text included, takes its own outcome in that section. 4. Nothing in the review was a shape the tooling could not read (an unrecognized heading, a moved section, an unfamiliar coverage wording). An unrecognized shape blocks the gate on its own. File an issue naming it and quoting the body, rather than guessing what the new wording diff --git a/.github/skills/agent-conduct/SKILL.md b/.github/skills/agent-conduct/SKILL.md index d02e4e04..c2284fac 100644 --- a/.github/skills/agent-conduct/SKILL.md +++ b/.github/skills/agent-conduct/SKILL.md @@ -39,7 +39,7 @@ Claims about a pull request being reviewed, clean, or mergeable are owned by the - **Durable knowledge lands in the committed docs, not in agent memory**, as part of the change that surfaced it, per `GOVERNANCE.md` "Durable Knowledge and Self-Improvement". Memory does not survive a new session or machine, so it holds only environment nuance and in-flight state. - **Where the governing doc is carried from the hub, file the finding against `ptr727/ProjectTemplate`.** Patching the local copy leaves every sibling repo with the same trap. Search open and closed issues first, then update the matching issue or file a new one. -- **A review flags an instance, so fix the class**: sweep for the siblings before replying, because reviewers sample rather than enumerate. +- **A review flags an instance, so a fix covers the class, bounded to what this change touched or broke**: when fixing a finding, sweep for its siblings before replying, because reviewers sample rather than enumerate, fix each one that sits in a file the diff touches or that the change itself put wrong, and file the rest rather than folding them in, per `GOVERNANCE.md` "Verification Discipline". - **A rule that keeps needing restating** is usually a stale or missing skills install, so run `python3 scripts/skills_install.py --report` from a hub checkout (the `fleet-conformance-check` skill) before concluding the rule does not exist. ## Delegation, in One Paragraph diff --git a/.github/skills/pr-review-conduct/SKILL.md b/.github/skills/pr-review-conduct/SKILL.md index ece467d3..b8b0644f 100644 --- a/.github/skills/pr-review-conduct/SKILL.md +++ b/.github/skills/pr-review-conduct/SKILL.md @@ -41,11 +41,14 @@ visible comments, routinely still carries a finding nobody has answered. Treatin 2. A review is confirmed on the **current head SHA**, matched by commit SHA rather than assumed from a green merge-state. A push makes checks go green *before* the re-review lands, and the matched review is **read**, not just counted. A review can carry the head SHA and still decline - the PR outright, or say it read only part of the changed files. `pr_review.py`'s - `review_on_head` names Copilot's own coverage specifically, the currently required reviewer, - not "no review of any kind covers this head": a trialed advisory reviewer (CodeRabbit, - Qodo) carrying the exact head under `other_reviewed`, with an empty review body and no new - threads, is its own ordinary "reviewed, nothing to flag" shape, not a missing review (#1066). + the PR outright, or say it read only part of the changed files. The coverage this item + requires is Copilot's, and CodeRabbit and Qodo are advisory, since the hub's + `docs/pr-reviewer-evaluation.md` "Status" names Copilot the incumbent and says no candidate is + a required reviewer: an advisory reviewer's absence blocks nothing, while its findings owe + item 3 exactly as Copilot's do. `pr_review.py`'s `review_on_head` names Copilot's own coverage + specifically, not "no review of any kind covers this head": an advisory reviewer carrying the + exact head under `other_reviewed`, with an empty review body and no new threads, is its own + ordinary "reviewed, nothing to flag" shape, not a missing review (#1066). 3. **Every** finding on that head SHA is closed: threads resolved, issue-level comments (which have no resolve action) triaged and replied to, **and** the low-confidence findings collapsed in the review body investigated and answered. Those appear in no thread, so polling threads @@ -55,6 +58,22 @@ visible comments, routinely still carries a finding nobody has answered. Treatin give each one the same triage the low-confidence findings above already get (#1058). Qodo's own `Resolved`/`Dismissed` self-tracked badge is a fast pre-triage signal, not a substitute for reading the finding, spot-verify against `gh pr diff` rather than trusting it outright. + What closing a finding owes turns on whether it is `pre-existing`. A finding on text inside a + canonical Markdown unit, one the hub's `scripts/canonical_review.py list` names, classed + `pre-existing` by the classes `local-strict-review` "Disposing of Findings" defines for a + local pass, applied here to a PR-hosted finding, is outcome 4 of "Every finding ends in one + of five outcomes" below applied once per unit rather than once per finding: the round gathers + that unit's such findings onto the unit's tracker, an open hub issue whose title carries the + unit key, retitled by the change that moves the key and filed by whichever round first needs + it, and answers each finding with that issue's link, resolving a thread on that reply, so a + `pre-existing` remark on a sentence the change never touched costs one link rather than a + decline or an issue per finding. The batch runs in the hub, which authors the text of every + verbatim unit. A carrying repository routes a finding on a verbatim unit by fidelity rather + than by class, since a resync writes the whole text there: it declines the finding under + that section's outcome 2, ownership sitting elsewhere, and files it on the same tracker, + while a finding on an intent unit is filed there too, the carrier adapting its own copy + meanwhile, since the defect is still fixed at the source. Every other finding, a `style` + remark on untouched text included, takes its own outcome in that section. 4. Nothing in the review was a shape the tooling could not read (an unrecognized heading, a moved section, an unfamiliar coverage wording). An unrecognized shape blocks the gate on its own. File an issue naming it and quoting the body, rather than guessing what the new wording diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 68515de1..c6300b38 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -197,7 +197,7 @@ The checks that separate work actually done from work that merely reports succes - **A launched process is not a result, and a cause nobody observed is not a diagnosis.** "The watcher is armed" names a process rather than a finding, so what gets reported is the output that process produced, and where it produced none, that absence is the report. The failure it prevents is an agent standing still on a condition that was met half an hour earlier, having announced the wait and never read it. Naming an external cause for such a stall afterwards, a throttle or a quota that appears nowhere in the record, turns a local defect into a story about someone else and closes the investigation on the wrong party, so read the record for the cause before naming one, and where the record does not carry it, report the cause as unknown. - **A workflow change is only fully exercised by CI.** Extracting a `run:` block and executing it locally validates the script and nothing else, because `secrets: inherit`, `permissions:`, `needs:` wiring, and reusable-workflow inputs resolve only in a real run. - **Platform-specific code is "verified" only on the platform it runs on.** PowerShell on Windows, a macOS-only `mktemp`/`ssh-agent` behavior, a WSL-specific path quirk: an agent reasoning about such code from a different host, however carefully, has not executed it, and reasoning by structural analogy to an already-tested equivalent on another platform ("the POSIX version works, so the PowerShell version should too") is a plausible first pass, not verification. State it as exactly that, an unverified structural match, and never in the same words used for a tested fact. When no agent in the loop has access to the target platform, say so, and either defer the platform-specific portion to a human or an agent that has that access, or ship it clearly labeled unverified. -- **A review flags an instance, so fix the class.** When a reviewer cites one stale claim, one silent-narrowing pattern, or one mis-worded contract, sweep for its siblings before replying. Reviewers sample rather than enumerate. +- **A review flags an instance, so a fix covers the class, bounded to what this change touched or broke.** When a reviewer cites one stale claim, one silent-narrowing pattern, or one mis-worded contract, and the finding is being fixed, sweep for its siblings before replying, since reviewers sample rather than enumerate, and fix each sibling that sits in a file the diff already touches. A sibling the change itself put in disagreement is this change's to fix wherever it sits, because the change made it wrong. A sibling that was wrong before the change and sits in a file the diff does not touch is filed rather than folded in, because every file the diff grows into is one more that each round reads again, so a sweep that widens the diff widens the loop it was meant to close. This section keeps the full rules and is surfaced at its decision moment by the `agent-conduct` Skill at `.agents/skills/agent-conduct/SKILL.md` in the hub, not a repo-relative link since that path is hub-local and not carried into every fleet repo. diff --git a/reports/canonical-review.json b/reports/canonical-review.json index 59b577cb..1ff4f613 100644 --- a/reports/canonical-review.json +++ b/reports/canonical-review.json @@ -11,11 +11,11 @@ }, { "unit": ".agents/skills/agent-conduct/SKILL.md > When a Failure Surfaces a Lesson", - "digest": "sha256:7bb4825e38c44c74366d2f0051d521968d87df765144bb080ca059a417e2cd75", + "digest": "sha256:08efb1b536d3965b8e224c7b0c951a4549714fad9dbe69280444b37e3b74789f", "reviewer": "agent-skill", - "findings": 6, - "hubCommit": "52b0c550ab07ab58b940a353a83247d7451e76e5", - "stamp": "2026-09-02T01:11:56Z" + "findings": 1, + "hubCommit": "4ee4669af5930d842c07ff5daabda6ee0ef621bd", + "stamp": "2026-09-05T00:32:38Z" }, { "unit": ".agents/skills/backlog-burndown/SKILL.md > (preamble)", @@ -361,6 +361,14 @@ "hubCommit": "b03a838ad24e3ff23ae6eeedb89571130a285ce6", "stamp": "2026-09-01T17:49:26Z" }, + { + "unit": ".agents/skills/pr-review-conduct/SKILL.md > Merge Gate, check this before merging or enabling auto-merge", + "digest": "sha256:9fec3aa6f4a0c13134d0c41183b4ada8dcb70a544e6796e7f558996969edae73", + "reviewer": "agent-skill", + "findings": 10, + "hubCommit": "4ee4669af5930d842c07ff5daabda6ee0ef621bd", + "stamp": "2026-09-05T00:57:49Z" + }, { "unit": ".agents/skills/python-codestyle/SKILL.md > Local development loop", "digest": "sha256:64911d87dea3c5c46bbe2abccab0bed590ee65a3e93e9083b403ceee77bde450", @@ -627,11 +635,11 @@ }, { "unit": "GOVERNANCE.md > Verification Discipline", - "digest": "sha256:8bc599f8aea61158ba0772069e9540cf66bae568460aef72fec19b720931d055", + "digest": "sha256:449e5d3262d38895b2eaedc7275a52fb3b0b9c25fc37598d63c5e455d011bd56", "reviewer": "agent-skill", - "findings": 1, - "hubCommit": "28872b4ab08d10d48e8dc0eecd94cdf257633e7d", - "stamp": "2026-09-04T21:38:25Z" + "findings": 5, + "hubCommit": "4ee4669af5930d842c07ff5daabda6ee0ef621bd", + "stamp": "2026-09-05T00:33:49Z" }, { "unit": "GOVERNANCE.md > Workflow YAML Conventions",