Promote develop to main: Record a Hub Blocker Where the Work Waits

.agents/skills/agent-conduct/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: agent-conduct
 description: >-
-  Surfaces the ptr727/ProjectTemplate fleet's conduct rules at the four decision moments they are violated: about to claim work is done, verified, green, or fixed, about to proceed on an assumption the user could cheaply confirm, a failure or review finding just surfaced a durable lesson, and about to write a handoff, which owes an account of every question parked rather than asked. Use this whenever about to report success or completion of any task, whenever about to pick a default, guess an intent, or resolve an ambiguity without asking, whenever work is blocked on a decision or authorization only the user can give, whenever about to file a question as an issue instead of asking it, whenever writing a handoff, and whenever an incident, a wrong answer, or a repeated correction just taught something a future session must honor. Deliberately narrow: the carried AGENTS.md "Context and Delegation Discipline" section is the always-on layer, and this skill fires at the moments rather than duplicating that section, so do not load this skill as general background. Where a sibling skill owns the moment, it wins: git-commit-conventions for committing, pr-review-conduct for review and merge claims, local-strict-review for the review passes a push owes, comment-and-doc-style for prose. The GOVERNANCE.md sections this skill surfaces keep the full rules, and the skill carries each of them whole as a generated include rather than as a summary.
+  Surfaces the ptr727/ProjectTemplate fleet's conduct rules at the five decision moments they are violated: about to claim work is done, verified, green, or fixed, about to proceed on an assumption the user could cheaply confirm, a failure or review finding just surfaced a durable lesson, about to write a handoff, which owes an account of every question parked rather than asked, and work here waiting on a fix in another repository. Use this whenever about to report success or completion of any task, whenever about to pick a default, guess an intent, or resolve an ambiguity without asking, whenever work is blocked on a decision or authorization only the user can give, whenever about to file a question as an issue instead of asking it, whenever writing a handoff, whenever work here waits on a fix in another repository, and whenever an incident, a wrong answer, or a repeated correction just taught something a future session must honor. Deliberately narrow: the carried AGENTS.md "Context and Delegation Discipline" section is the always-on layer, and this skill fires at the moments rather than duplicating that section, so do not load this skill as general background. Where a sibling skill owns the moment, it wins: git-commit-conventions for committing, pr-review-conduct for review and merge claims, local-strict-review for the review passes a push owes, comment-and-doc-style for prose. The GOVERNANCE.md sections this skill surfaces keep the full rules, and the skill carries each of them whole as a generated include rather than as a summary.
 ---
 
 # Agent Conduct
 
 ## Why This Exists
 
-The fleet's conduct rules (verification before claiming done, asking instead of assuming, recording lessons, accounting at handoff for what was parked rather than asked) lived only in doc sections nothing surfaced at the moment of violation, so they were honored by whoever happened to have read them recently. This skill is the decision-moment surface. The full rules stay in `GOVERNANCE.md` ("Verification Discipline", "Communicating with the User", "Durable Knowledge and Self-Improvement"), which keeps authority, and each of those three sections is carried here whole, as a generated include that `scripts/build_dist.py` fills from the section and holds to it, so the text that surfaces at the moment is the rule's own rather than a shorter list of it. The carried `AGENTS.md` "Context and Delegation Discipline" section is the always-on layer and is not carried here. A defect in included text is fixed in `GOVERNANCE.md` and regenerated, never edited in this file, per the `skill-lifecycle` Skill.
+The fleet's conduct rules (verification before claiming done, asking instead of assuming, recording lessons, accounting at handoff for what was parked rather than asked, recording a blocker that lives in another repository) lived only in doc sections nothing surfaced at the moment of violation, so they were honored by whoever happened to have read them recently. This skill is the decision-moment surface. The full rules stay in `GOVERNANCE.md` ("Verification Discipline", "Communicating with the User", "Durable Knowledge and Self-Improvement"), which keeps authority, and each of those three sections is carried here whole, as a generated include that `scripts/build_dist.py` fills from the section and holds to it, so the text that surfaces at the moment is the rule's own rather than a shorter list of it. The carried `AGENTS.md` "Context and Delegation Discipline" section is the always-on layer and is not carried here. A defect in included text is fixed in `GOVERNANCE.md` and regenerated, never edited in this file, per the `skill-lifecycle` Skill.
 
 ## Before Claiming Done
 
@@ -73,20 +73,26 @@ Three sources govern this moment, and the first two are rules in the `GOVERNANCE
 
 ## When a Failure Surfaces a Lesson
 
-Where a lesson lands, and when it earns a mechanical hook, is `GOVERNANCE.md` "Durable Knowledge and Self-Improvement", whole.
+Where a lesson lands, when it earns a mechanical hook, and where work blocked on another repository is recorded are all `GOVERNANCE.md` "Durable Knowledge and Self-Improvement", whole.
 
 <!-- include: GOVERNANCE.md > Durable Knowledge and Self-Improvement -->
 
 - **Durable knowledge lives in the committed docs, not in agent memory.** Anything a future agent must honor (a rule, a contract, a hard-won gotcha, a pattern worth repeating or one to avoid) belongs in a committed governance file (`GOVERNANCE.md` for a cross-cutting rule, `AGENTS.md`, `CODESTYLE.md`, `WORKFLOW.md`, or a committed backlog the repository already keeps). Agent memory does not survive a new session, a new machine, or a new environment, so it holds only environment-specific nuance and in-flight session state, never anything whose loss on reset would matter. A durable lesson left only in memory is lost to the next agent.
 - **Keep the governance current as you work.** When work surfaces something durable (a rule worth enforcing, a recurring gotcha, a positive pattern to repeat, a negative one to design out), record it in the governance docs as part of that change, rather than leaving it in a local note or routing around it with a one-off workaround. Where the governing doc is carried from a template this repo cannot edit directly, propose the change upstream rather than patching the local copy. A local patch leaves every sibling repo with the same trap. Governance is not static: it improves by agents folding good patterns in and designing bad ones out.
+- **A blocker filed in another repository is recorded in the repository whose work it blocks.** The binding moment is the one where the upstream issue is filed or, where it already exists, found, because that session is the one that knows what stopped and why. It owes a second issue in the repository that is waiting rather than only the first, and where the upstream issue already exists the local issue names that one and no second upstream issue is filed. The local issue states what this repository cannot do and why, in its own terms rather than as a pointer to read elsewhere, since a reader who has to open the upstream issue to learn whether it affects them opens every one of them. The local issue names the upstream one as its blocker, carries the `blocked` label, and carries whatever labels its own work would carry anyway. A comment on the upstream issue then names the local one in return, a comment rather than an edit to the body because a second repository may join the same blocker later and because the body is often not this session's to rewrite. That order, the upstream issue and then the local issue and then the backlink comment, leaves a partial failure as a record naming its blocker rather than as a blocker naming a record nobody wrote. **A handoff does not do this job.** It carries the blockers a round met, and it belongs to one track and closes with its successor, where the wait outlives every session that met it and belongs in the backlog the whole repository reads.
+- **The blocker record is written under the ordinary write rules, and the label on it is taken off deliberately.** Filing an issue and commenting on another are state-changing calls, so "Repository Boundaries and Write Safety" binds each of them exactly as it binds any other write, which keeps the upstream issue inside this owner and makes a blocker under a different owner a matter of explicit permission rather than of this rule. The `blocked` label is what every reader of this record selects on, so a repository not carrying it cannot host one until the fleet label set is applied there, which is a change to that repository's configuration rather than anything this rule writes, and a session that finds it missing reports that. The label comes off when the blocker clears, and the session closing the upstream issue is best placed to take it off, since the backlink comments naming every waiting repository are on the issue it is closing, while any later session that finds it cleared takes it off instead. A fix can land well before either of those, so the label lags the fix rather than tracking it, which is why a session meeting a `blocked` issue reads the state of the issue that issue's body names rather than the label. The local issue stays open when the label comes off, because the work it records still has to be done and is ordinary backlog from that moment on.
 - **A durable rule earns a mechanical hook only where a hook can actually decide it, otherwise it stays prose.** Three conditions together, not any one alone. The failure recurs even after the governing prose was demonstrably read and understood, so it is not a discovery or loading problem a structural fix (getting the rule into context at all) would already solve. The triggering shape is decidable from the tool call's own text, arguments, and working directory alone, with no semantic or contextual judgment required. And the failure is destructive or hard to reverse rather than a quality miss. A worktree-isolation lapse met all three (it recurred under prose the agent had already read, "is this command's target a primary checkout" is a plain directory comparison, and the harm is another task's swept or reverted work), so it was promoted to a `gh-write-guard` hook rule. A skill's own trigger going unread by the session at all, by contrast, is a loading problem, fixed by getting the rule into context (the `CLAUDE.md` importing `AGENTS.md`), not by a hook. And "was this review finding actually evidence-backed" fails the second condition outright: a hook sees only the command text, never the judgment call itself, so it can only ever nag, not decide, and that class of rule stays prose and a chained Skill trigger. Those three conditions gate promotion to a **host** hook, the involuntary layer that fires in every session under the maintainer's own credentials and that only the maintainer can grant an exemption from, which is why the bar there is destructive harm. A **committed** hook in the repository's own tree is a third layer between prose and that one, and it is earned on weaker grounds: it is opt-in per clone, visible in the tree, bypassable by design, and it therefore fits a rule whose harm is a quality miss rather than a destruction. The second condition still binds it, since a hook that cannot decide its own trigger is a hook that nags, so what earns the layer is finding the decidable half of a rule whose other half is judgment. The local-review rule under `GOVERNANCE.md` "Verification Discipline" is the worked example: whether a review's findings were rightly disposed of is judgment no hook can decide and stays prose, while whether a review pass ran over exactly the content being pushed is a receipt comparison, which the hub's own `.husky/pre-push` decides.
 
-`GOVERNANCE.md` "Durable Knowledge and Self-Improvement" keeps the full rules, and 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, carries it whole as a generated include and surfaces it at its decision moment.
+`GOVERNANCE.md` "Durable Knowledge and Self-Improvement" keeps the full rules, and 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, carries it whole as a generated include and surfaces it at its decision moments.
 
 <!-- /include -->
 
 Two rules that bind at this moment have their homes elsewhere. A review flags an instance, so a fix covers the class, bounded to what the change touched or broke, stated under "Before Claiming Done" above. And a rule that keeps needing to be restated is a stale or missing skills install before it is a missing rule, per `AGENTS.md` "Where the Rules Live", with the `fleet-conformance-check` Skill as the check.
 
+## When Work Stops on Another Repository
+
+The rules for this moment are two bullets in the `GOVERNANCE.md` "Durable Knowledge and Self-Improvement" include under "When a Failure Surfaces a Lesson" above. The first, opening "A blocker filed in another repository is recorded in the repository whose work it blocks", states what the two issues are, what the local one says, the `blocked` label it carries, and the backlink the upstream issue takes in return. The second, opening "The blocker record is written under the ordinary write rules", states which write rules bind those writes, what a repository not carrying the `blocked` label owes before it can host the record, and when the label comes off. Read both there, since a restatement here would be a second copy and nothing would hold it to the first.
+
 ## Delegation, in One Paragraph
 
 The always-on rules live in `AGENTS.md` "Context and Delegation Discipline", loaded in every session, and are not restated here. The two that bind at a conduct moment are its rule on briefing a subagent and its rule on never tiering down the seat holding the judgment.

.agents/skills/backlog-burndown/SKILL.md

@@ -114,6 +114,18 @@ inflates the number this run reports as the backlog by one for every lane in use
 count this fleet reports wrong is a failure with its own history, so filter the label out of the
 ranking and out of every count of the open backlog rather than out of the ranking alone.
 
+An issue carrying the `blocked` label is counted and is not ranked while its blocker stands. It
+records real work this repository owes, which is why it stays in the count, and the label says the
+work cannot start yet, per `GOVERNANCE.md` "Durable Knowledge and Self-Improvement". So until the
+blocker clears it has no group, no worker, and no claim, and spends none of the round's four worker
+slots. Whether the blocker still stands is read from what its body names rather than from the label,
+since the label comes off by hand and lags the fix, and a fix merged into `develop` leaves the issue
+it fixes open, per "Grouping and File Claims" below on closing keywords. Where that read cannot be
+made, from a private or deleted repository or a reference nothing can be read from, the blocker
+stands rather than being assumed cleared. The round's report names every issue it held back this way
+and the blocker each one waits on, since the maintainer reads the report rather than the issue
+bodies, and a stuck issue nobody names reads as ordinary backlog that simply never moves.
+
 An issue that asks a question rather than states a defect is not ranked and is never guessed at.
 It has no group, no worker, and no claim, so nothing in "Raising a Blocked Question" applies to it
 except how the question travels. It goes to the maintainer at the end of ranking, per
@@ -486,17 +498,17 @@ body when it lands rather than leaving the issue to be closed by hand.
 The run ends at either of two points, and they are different endings.
 
 - **The backlog is worked out**, meaning a full re-rank finds no open issue this skill can act on.
-  That is not the same as zero open issues, since a backlog of nothing but maintainer questions is
-  a finished run. Report it as finished, with the questions put to the maintainer.
+  That is not the same as zero open issues, since a backlog of nothing but maintainer questions and
+  issues whose blockers still stand is a finished run. Report it as finished, with the questions put to the maintainer.
 - **The session ends**, for a context limit or because the maintainer stops it. The run ends with
   it, since the merge authorization was bounded to that session. What the rounds already landed
   stands on its own in GitHub, and the branches, claim comments, and questions left behind are
   what a later run reads to pick the work up. That later run is a new run, named again, not this
   one continuing.
 
-Report at every round boundary and at either ending: what merged to develop, what the promotion
-pull request carries, what was newly filed, what is stopped and on which question, and what the
-next round would pick.
+Report at every round boundary and at either ending: what merged to develop, what the promotion pull
+request carries, what was newly filed, what is stopped and on which question, what was held back and
+on which blocker, and what the next round would pick.
 
 ## Mechanics Live Elsewhere
 

.agents/skills/session-handoff/SKILL.md

@@ -238,19 +238,13 @@ names the command that applies the fleet label set except where the label read f
 which is the one case where the label's absence is unproven rather than established.
 
 Creating an issue, commenting on one, closing one, and editing a body are each outward-facing
-writes. `new` creates, comments, and closes, the label riding inside the one create call rather
-than being a write of its own. `link` edits a body, comments, and closes. Filing a handoff link is authorized standing by `AGENTS.md` "Session Scope", which
-requires one at every session close and allows no substitute that records the round, so a session
-ending unattended can comply with it. **That authorization reaches the filing and nothing else**,
-meaning the three writes that rule enumerates and the two of them `link` makes where it completes
-a filing that stopped part way. It covers the repository `AGENTS.md` "Session Scope" sends the link to, the one holding the work
-the next session resumes, and no other, and reading it wider is the self-grant `GOVERNANCE.md`
-"Repository Boundaries and Write Safety" forbids. `link`'s body edit is outside it, since that
-rule has the new link name its predecessor at create time and so describes no after-the-fact edit,
-which makes the repair its own act needing its own go-ahead. `link` also reaches an issue this
-chain never created, since the caller names both numbers and its refusals ask for a block and a
-label to be added by hand first, so the two issues it is given are chosen deliberately rather than
-swept up.
+writes. `new` creates, comments, and closes, the label riding inside the one create call rather than
+being a write of its own. `link` edits a body, comments, and closes. Each of them is bound by
+`GOVERNANCE.md` "Repository Boundaries and Write Safety" exactly as any other write is. Point them
+at the repository `AGENTS.md` "Session Scope" sends the link to, the one holding the work the next
+session resumes, and at no other. `link` also reaches an issue this chain never created, since the
+caller names both numbers and its refusals ask for a block and a label to be added by hand first, so
+the two issues it is given are chosen deliberately rather than swept up.
 
 Where the caller names an issue, which is `link` alone, it reads both live before writing and
 writes only what those reads returned. Every other identifier a write targets is captured from a

.claude-plugin/fleet-skills/.source-digests/agent-conduct

@@ -1 +1 @@
-8ff57be4c1d97c87
+004d1370299af4bb

.claude-plugin/fleet-skills/.source-digests/backlog-burndown

@@ -1 +1 @@
-bad68bee45278a84
+e4e8113f005b2357

.claude-plugin/fleet-skills/.source-digests/session-handoff

@@ -1 +1 @@
-3827a0c235b373f8
+7f31b40adb6c237b