Repository navigation
Conversation
…he Handoff's Writes (#1596) ## The defect A downstream fleet repository that hits a hub defect files an issue against the hub and moves on. The record then lives only where the fix will happen, and nothing in the repository that is waiting says it is waiting. Two costs follow, one at each end. The next session in the blocked repository meets the same wall, investigates it again, and files it again, because nothing local told it the wait was already known. And from the hub side a growing issue backlog carries no indication of which repositories any given issue is holding up, so the dependencies are unreadable from either direction. `AUDIT.md` section 8 already tells a downstream repository to file hub findings as issues. It says nothing about the local half, and that silence is the rule as far as any session reads it. ## What this changes **`GOVERNANCE.md` "Durable Knowledge and Self-Improvement" gains two bullets.** The first states the record. The binding moment is the one where the upstream issue is filed or, where it already exists, found. The waiting repository owes a local issue naming the upstream one as its blocker, stating what this repository cannot do and why in its own terms rather than as a pointer to read elsewhere, carrying the `blocked` label beside whatever its own work would carry. A comment on the upstream issue then names the local one in return, a comment rather than a body edit because a second repository may join the same blocker later. The order is upstream issue, local issue, backlink comment, so a partial failure leaves a record naming its blocker rather than a blocker naming a record nobody wrote. A handoff does not do this job, since it belongs to one track and closes with its successor while the wait outlives every session that met it. The second states what binds those writes and the label's lifecycle. The writes are ordinary writes under "Repository Boundaries and Write Safety", with no standing authorization of any kind. A repository not carrying the `blocked` label cannot host the record until the fleet label set is applied there, the same position `AGENTS.md` "Session Scope" takes on `handoff`. The label comes off when the blocker clears, and the session closing the upstream issue is best placed to do it because the backlink comments naming every waiting repository are on the issue it is closing, while any later session finding it cleared takes it off instead. A fix can land well before either, so the label lags the fix, which is why a reader reads the named issue's state rather than the label. **`repo-config/labels.json` declares `blocked`**, described as "Blocked on an issue in another repository, named in the body", and `repo-config/README.md` places it in the taxonomy as a marker that never stands alone, beside `decision` and `handoff`, and states that it stays in every backlog count and leaves only the ranking. **`agent-conduct` gains the moment**, so the rule surfaces where it is violated rather than needing to have been read recently. Its two governance bullets are pointed at rather than restated. **`backlog-burndown` places the label in the run's own machinery.** A `blocked` issue is counted and is not ranked while its blocker stands, takes no group, worker, or claim, and spends none of the round's four worker slots. Whether the blocker stands is read from the issue its body names rather than from the label, an unreadable blocker stands rather than being assumed cleared, and the round's report names what it held back and on which blocker. **`AGENTS.md` "Session Scope" no longer pre-authorizes the handoff's writes.** Separate from the above and made on the maintainer's instruction during review. The deleted clause read that filing a handoff link "is authorized standing rather than per session", justified by a session ending unattended being otherwise unable to comply. That justification does not hold: the same bullet already gives such a session a compliant path, reporting that it could not hand off and leaving the previous link open. What the grant bought was a filed link rather than a reported failure, a convenience rather than a compliance necessity, and it read as a cross-repository carve-out on a skim even though it never was one. The ordinary permission rules decide each write now, the fallback was widened to match, and `session-handoff`, which cited the grant at its now-deleted source, was rewritten. ## Rollout Declaring the label creates it nowhere. Every active repository needs `repo-config/configure.sh apply owner/repo release|operational` run against it from a hub checkout at `main` once this merges. That is the maintainer's call and is deliberately not part of this change. Until then a session finding the label missing reports that, per the rule. ## Verification Full local gate set green: `build_dist.py --check`, `canonical_review.py check`, `repo_gate.py`, the nine-check `prose_lint.py` invocation, `jq` over every payload, `spec/validate.py`, `docker_lint.py` across all seven linters, `ruff`, `mypy`, and the unittest suite with `audit.py --selftest`. Ten carried canonical units are covered by recorded passes, and a local review receipt covers the branch's whole diff. **On the round count.** This took ten review rounds, which is worth stating rather than hiding. Nearly every finding was the same shape: a justifying or summarizing clause added beside an instruction that was already correct. The instructions have been stable since the second round. What kept failing was the sentence next to them, and each attempt to make one more precise produced a new falsifiable claim. Every fix that held was a deletion. Two rounds removed work rather than adding it, dropping a sweep sentence in `AUDIT.md` and its echo in `audit-a-repo` that both placed a write inside a phase both documents declare read-only. Pre-existing findings surfaced along the way are filed rather than carried here: #1592, #1593, #1594, #1595, plus five lines gathered onto the trackers #1335, #1337 and #1357. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01AYoF5QrrkhEWt7F7G8RDvB <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Added support for tracking work blocked by fixes in another repository. - Added a `blocked` label with guidance for cross-repository dependencies, backlog counting, and triage. - **Documentation** - Clarified write-safety requirements for handoffs and blocker records. - Documented how blocked work is held back, reported, and resumed when blockers clear. - Updated review records to reflect the latest documentation content. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Advanced Run ID: Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The promotion cleanly applies the documented governance/label/skill updates with consistent regenerated outputs and no correctness issues found in the changed files.
Pull request overview
Promotes the develop branch to main for the change set that formalizes how downstream repos record work blocked on upstream hub issues, introduces the fleet blocked label, and removes any standing pre-authorization language around session-handoff writes.
Changes:
- Added governance rules requiring a local
blockedrecord (issue + backlink) whenever work is blocked by an upstream repo issue. - Declared and documented the new
blockedlabel in fleet repo-config, and taught backlog-burndown how to treatblockedissues during ranking. - Removed/updated handoff guidance so handoff writes are governed strictly by the ordinary write-safety rules (no standing authorization).
File summaries
| File | Description |
|---|---|
| reports/canonical-review.json | Updates canonical review ledger digests/stamps and records coverage of the new agent-conduct unit. |
| repo-config/README.md | Documents blocked as a marker label and links its lifecycle back to governance. |
| repo-config/labels.json | Adds the blocked label definition to the fleet label set. |
| GOVERNANCE.md | Adds two new bullets defining the upstream-blocker recording rule and blocked label lifecycle. |
| AGENTS.md | Removes standing authorization language for handoff writes; expands routing row to include upstream-blocked work. |
| .github/skills/session-handoff/SKILL.md | Generated copy updated to remove standing-authorization wording and align with write-safety rules. |
| .github/skills/backlog-burndown/SKILL.md | Generated copy updated to treat blocked issues as counted-but-not-ranked while blockers stand; reporting updated. |
| .github/skills/agent-conduct/SKILL.md | Generated copy updated to add the new decision moment and include text for upstream-blocked work. |
| .claude-plugin/fleet-skills/skills/session-handoff/SKILL.md | Generated plugin copy updated in sync with session-handoff wording change. |
| .claude-plugin/fleet-skills/skills/backlog-burndown/SKILL.md | Generated plugin copy updated in sync with backlog-burndown blocked handling. |
| .claude-plugin/fleet-skills/skills/agent-conduct/SKILL.md | Generated plugin copy updated in sync with agent-conduct new decision moment. |
| .claude-plugin/fleet-skills/.source-digests/session-handoff | Updates digest to reflect regenerated session-handoff source. |
| .claude-plugin/fleet-skills/.source-digests/backlog-burndown | Updates digest to reflect regenerated backlog-burndown source. |
| .claude-plugin/fleet-skills/.source-digests/agent-conduct | Updates digest to reflect regenerated agent-conduct source. |
| .agents/skills/session-handoff/SKILL.md | Source skill updated to remove standing-authorization wording and restate binding under write-safety rules. |
| .agents/skills/backlog-burndown/SKILL.md | Source skill updated to define ranking/counting behavior for blocked issues and to report held-back work. |
| .agents/skills/agent-conduct/SKILL.md | Source skill updated to add the new decision moment and route to governance bullets without duplicating them. |
Review details
- Files reviewed: 17/17 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Promotes one commit from
developtomain.55c2485Record a Hub Blocker Where the Work Waits, and Stop Pre-Authorizing the Handoff's Writes (Record a Hub Blocker Where the Work Waits, and Stop Pre-Authorizing the Handoff's Writes #1596)A downstream fleet repository that hits a hub defect files an issue against the hub and moves on, leaving the record only where the fix will happen. The next session in the waiting repository then meets the same wall, investigates it again, and files it again, while the hub's own backlog carries no indication of which repositories any given issue is holding up.
AUDIT.mdsection 8 already told a downstream repository to file hub findings as issues and said nothing about the local half, so the dependencies were unreadable from either end.GOVERNANCE.md"Durable Knowledge and Self-Improvement" gains two bullets. The record binds when the upstream issue is filed or, where it already exists, found. The waiting repository owes a local issue naming the upstream one as its blocker, stating what it cannot do and why in its own terms, carrying the newblockedlabel, and a comment on the upstream issue names the local one in return. The order is upstream issue, local issue, backlink comment, so a partial failure leaves a record naming its blocker rather than a blocker naming a record nobody wrote. The second bullet keeps the writes under the ordinary write rules with no standing authorization, requires the fleet label set before a repository can host the record, and fixes the label's removal to the blocker clearing rather than to the label being trusted, since a fix can land well before the upstream issue closes.repo-config/labels.jsondeclaresblocked,agent-conductsurfaces the moment so the rule fires where it is violated, andbacklog-burndownplaces the label in the run's own machinery: counted, not ranked while its blocker stands, no group, worker, claim, or worker slot, and the round's report names what it held back and on which blocker.Separately, on the maintainer's instruction during review,
AGENTS.md"Session Scope" no longer pre-authorizes the handoff's three outward-facing writes. The deleted clause justified itself by an unattended session being otherwise unable to comply, which the same bullet already answers by having such a session report that it could not hand off. The ordinary permission rules decide each write now, andsession-handoff, which cited the grant at its now-deleted source, was rewritten.Rollout, not done by this promotion. Declaring the label creates it nowhere. Every active repository needs
repo-config/configure.sh apply owner/repo release|operationalrun against it from a hub checkout atmain. Until then a session finding the label missing reports that, per the rule.Copilot reviewed the feature pull request at its merged head, full coverage, no unresolved threads. Three review rounds ran, raising two findings from Copilot and one from CodeRabbit, each fixed and its thread resolved, plus one suppressed low-confidence finding answered in the conversation with a measurement showing this change does not alter what skill-description truncation loses. Ten local adversarial rounds preceded the pull request, and nearly every finding in them was a justifying clause beside an instruction that was already correct, each settled by deleting the clause rather than sharpening it.
Pre-existing defects the rounds surfaced were filed rather than grown into the change: #1592, #1593, #1594 and #1595, with five further findings gathered onto the unit trackers #1335, #1337 and #1357.
🤖 Generated with Claude Code
https://claude.ai/code/session_01AYoF5QrrkhEWt7F7G8RDvB