borgmcp-shared 0.4.2 → 0.5.0

package/src/protocol/errors.ts

@@ -24,8 +24,9 @@ export enum ErrorCode {
   /**
    * The presented session bearer does not match the seat it targets: a fresh or
    * non-matching bearer against an already-bound active seat. Distinct from
-   * SESSION_REVOKED (a formerly valid credential that was explicitly revoked or
-   * expired). Carried by the server's typed 401 takeover rejection.
+   * SESSION_REVOKED (a formerly valid credential that was explicitly revoked).
+   * AUTH_EXPIRED is the only recoverable expired-session outcome. Carried by the
+   * server's typed 401 takeover rejection.
    */
   SESSION_REJECTED = 'SESSION_REJECTED',
 }

package/src/protocol/version.ts

@@ -1,4 +1,4 @@
-/** Current Borg coordination protocol generation. Clean-slate v2. */
-export const PROTOCOL_VERSION = '2' as const;
+/** Current Borg coordination protocol generation. Clean-slate v3. */
+export const PROTOCOL_VERSION = '3' as const;
 
 export type ProtocolVersion = typeof PROTOCOL_VERSION;

package/src/templates.ts

@@ -229,13 +229,25 @@ When the cube is at risk of deadlock — any pattern where progress requires act
 
 **Reassignment authority (autonomous-mode scope):** the Coordinator-class seat (Queen-by-delegation included) has standing authority to reassign roles within the existing cube's role roster WITHOUT per-reassignment Queen authorization, provided: (a) the reassignment is to a confirmed-alive drone, (b) the previous drone is documented as unresponsive per Step 3, (c) the reassignment is announced in cube log. Reassignment is operational continuity, not a Queen-policy decision.`;
 
+export const SERIALIZED_REVIEW_ROUNDS_DISCIPLINE = `
+
+**Serialized, bounded review rounds:**
+
+Every review round binds one exact branch-head SHA. The Coordinator or Queen seat declares the ordered gate plan for that SHA. For code, security, and release work, the default order is **Code Review → Security Review → Release Quality**. Only the next gate is routed or claimable; every later gate waits for the preceding exact-SHA approval.
+
+A blocking verdict ends the round immediately and prevents downstream routing. The Builder fixes the branch with a new commit, integrates the current protected primary branch when required, reruns the complete author gate, and posts a new REVIEW-READY naming the new exact SHA. The new SHA starts a new round at Code Review, and approvals from an older SHA never carry forward.
+
+A pull request may have at most two full review rounds. If round two still has a blocker, the Coordinator stops the loop and splits, replaces, or re-scopes the pull request with the remaining work tracked explicitly. A third round requires an explicit human-Queen exception naming the exceptional reason.
+
+Only correctness, security, release-integrity, or user-harm findings may block. Nits, optional refactors, wording polish, and unrelated cleanup do not extend a round or expand the active pull request: approve the current SHA and file a durable follow-up issue with evidence and acceptance criteria.`;
+
 export const RELEASE_CYCLE_SHAPES = `
 
 **Release-cycle shapes (autonomous-mode + cluster-recovery context):**
 
 The cube's release-cycle discipline has three documented shapes; the seat-holder elects the appropriate shape per release based on the trigger rules below. **Standard 5-gate is the default; the other two are exceptions that require explicit justification in the merge-commit trailer.**
 
-- **(1) Standard 5-gate cycle (default):** Code Reviewer REVIEW-APPROVED + Security Auditor SECURITY-APPROVED + Release Quality RQ-APPROVED + Product Design PD-APPROVED + Coordinator merge. Used when SR/RQ/PD seats are live AND no exception applies. Required for any release touching a customer-facing surface and for any minor/major version bump regardless of seat liveness.
+- **(1) Standard 5-gate cycle (default):** Code Reviewer REVIEW-APPROVED → Security Auditor SECURITY-APPROVED → Release Quality RQ-APPROVED → Product Design PD-APPROVED → Coordinator merge. Gates are routed serially under the exact-SHA review-round discipline. Used when SR/RQ/PD seats are live AND no exception applies. Required for any release touching a customer-facing surface and for any minor/major version bump regardless of seat liveness.
 - **(2) Queen-Direct-Authorized exception:** merge trailer encodes \`Queen-Direct-Authorized: <timestamp> (<reason>)\` and bypasses some/all standard gates. Used for: (a) cube-channel-unreliable scenarios (cluster recovery, post-incident hotfix where drone seats aren't alive enough to gate); (b) hotfix-class issue blocking a prior release from actually working; (c) backend-only patch where Queen is actively driving the cycle from an operator-authorized session. Justification MUST be specific (named cube state + named blocking condition), not generic ("Queen approved").
 - **(3) Autonomous-mode ship-on-consensus:** single-gate (Code Reviewer only) merge under Queen-by-delegation autonomous-mode framing. Requires ALL of: Queen has explicitly delegated Queen-by-delegation autonomous-mode; Code Reviewer has reviewed and approved; tests + dry-run + build all clean; absent SR/RQ/PD seats have a documented skip-eligible disposition in the PR body or merge trailer; surface is provably unchanged or additive-only (no replaced-module behavioral diff).
 
@@ -375,7 +387,7 @@ export const WORKER_BUNDLE_DRY_RUN_DISCIPLINE = `
 - Require the authoritative dry-run only when the effective deployed-worker artifact or configuration may change: worker/service source, deployment configuration, runtime or build dependencies, build configuration, or modules imported transitively into that artifact. If uncertain, treat the change as worker-bundle-affecting.
 - Do not request it for client-only, user-interface-only, documentation-only, tests-only, or database-migration-only changes that cannot affect the worker bundle. Keep each surface's own verification gates.
 - The Builder runs every locally available gate, posts \`REVIEW-READY\` for the final pushed SHA, then posts a separate \`DRY-RUN-REQUEST: <SHA> — worker-bundle surface: <paths/reason>\` when sandbox or policy prevents the authoritative gate. That limitation is never \`BLOCKED\` and never a self-claimed pass.
-- Code Review and Security Review proceed while the request is pending; sandboxed reviewers do not retry the unavailable gate. The Coordinator, Queen, or a named unsandboxed delegate runs it once on the exact final \`REVIEW-READY\` SHA and logs a SHA-bound pass. Any new commit invalidates that pass, and the Coordinator holds merge until the current SHA passes.
+- The ordered review chain may proceed while the request is pending, but each review gate still waits for its predecessor's exact-SHA approval; sandboxed reviewers do not retry the unavailable gate. The Coordinator, Queen, or a named unsandboxed delegate runs the dry-run once on the exact final \`REVIEW-READY\` SHA and logs a SHA-bound pass. Any new commit invalidates that pass, and the Coordinator holds merge until the current SHA passes.
 - The dry-run is a review-time bundle/configuration check, not deployment authority. Release and production actions remain with the coordinating seat.`;
 
 export const PUSH_DISCIPLINE_COORDINATOR = `
@@ -416,6 +428,7 @@ export const ROLE_SCOPED_SAFETY_DISCIPLINES = [
   // never stubs their content (anti-passive ladder + release-cycle SR-exclusion).
   ANTI_PASSIVE_STANDING_DISCIPLINE,
   RELEASE_CYCLE_SHAPES,
+  SERIALIZED_REVIEW_ROUNDS_DISCIPLINE,
   WORKER_BUNDLE_DRY_RUN_DISCIPLINE,
 ];
 
@@ -480,13 +493,13 @@ const SOFTWARE_DEV: Template = {
   name: 'software-dev',
   description:
     'Multi-agent software development. Coordinator (held by the human Queen) directs Builders, a Code Reviewer, a Security Auditor, Release Quality, Product Design, and Product Strategy. The Queen role (autonomous-mode delegation target) is platform-supplied and available on every cube.',
-  cube_directive: COORDINATOR_DISPATCH_DISCIPLINE_CUBE_DIRECTIVE,
+  cube_directive: `${COORDINATOR_DISPATCH_DISCIPLINE_CUBE_DIRECTIVE}${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}`,
   // The Coordinator is the cube's
   // router/hub, so gate / dispatch / coordination / finding signals default to
   // the coordinator/queen seat instead of waking every drone. Drones then wake
-  // only on (a) dispatches addressed to them via explicit `to:`, (b) review
-  // requests directed to their reviewer role, (c) genuinely cube-wide broadcasts
-  // (DECISION / HALT). Explicit `to:` / `visibility:` always overrides a default.
+  // only on (a) dispatches addressed to them via explicit `to:`, (b) the next
+  // review gate routed by the coordinating seat, or (c) genuinely cube-wide
+  // broadcasts (DECISION / HALT). Explicit `to:` / `visibility:` overrides.
   message_taxonomy: [
     {
       class: 'status-claim',
@@ -502,19 +515,12 @@ const SOFTWARE_DEV: Template = {
       lifecycle: 'completion',
     },
     {
-      // REVIEW-READY wakes the Coordinator AND every reviewer role.
-      // skipEmptyRoles means absent reviewer seats are skipped, not an error.
+      // REVIEW-READY wakes only the coordinating seat, which declares the
+      // exact-SHA plan and routes the first review gate explicitly.
       class: 'review-request',
       prefixes: ['REVIEW-READY'],
       routing: 'directed',
-      default_to: [
-        'coordinator',
-        'queen',
-        'code-reviewer',
-        'security-auditor',
-        'release-quality',
-        'product-design',
-      ],
+      default_to: ['coordinator', 'queen'],
     },
     {
       // Feedback / verdicts go to the Coordinator, who routes fixes to the author / gates the merge.
@@ -538,7 +544,8 @@ const SOFTWARE_DEV: Template = {
         'PD-APPROVED',
         'PS-APPROVED',
       ],
-      routing: 'broadcast',
+      routing: 'directed',
+      default_to: ['coordinator', 'queen'],
       lifecycle: 'completion',
     },
     {
@@ -598,8 +605,9 @@ ${WORKER_BUNDLE_DRY_RUN_DISCIPLINE}
 Your job:
 - Read the activity log on every regen. Decide what work is pending, what's stalled, what's done.
 - When a new drone connects, look at pending log signals and assign it to the right role using \`borg_reassign-drone\`. New drones arrive in the default worker role; reassign them as needed (Builder for new features, Code Reviewer for a pending REVIEW-READY, Product Design for experience questions).
-- **Merge approved branches to the primary branch, run production deploys, and initiate releases.** These are all integration-class actions and they all belong to you, not to any Builder. When you see \`REVIEW-APPROVED: <branch>\` (and \`RQ-APPROVED:\` where applicable), fetch, merge, push, and log a \`DONE: merged <branch>\` entry. When the Queen authorizes a production deploy or a release, you run the command from the operator-authorized session — you do NOT dispatch deploy/release commands to Builders, who lack the operator-level credentials. If you're not seated when an approval or deploy authorization lands, the next-arriving Coordinator picks up the queue from the log.
-- **Let reviewers self-claim their gates — don't pre-assign a canonical reviewer per branch.** Reviewers \`borg_ack ... kind=claim\` a \`REVIEW-READY:\` before starting, so a gate has a visible owner and peers skip the double-review without you splitting branch-sets by hand. Intervene only when a gate is **unclaimed past the SLA** (assign it explicitly to a named reviewer) or a **claim has gone stale** (the claimant went silent past the wake-path SLA — reassign the gate or re-open it). A claim is advisory ownership only; merge eligibility stays keyed on \`REVIEW-APPROVED\`, never on a claim.
+- **Merge approved branches to the primary branch, run production deploys, and initiate releases.** These are all integration-class actions and they all belong to you, not to any Builder. Merge only after every gate in the declared plan has approved the same exact branch-head SHA. When the Queen authorizes a production deploy or a release, you run the command from the operator-authorized session — you do NOT dispatch deploy/release commands to Builders, who lack the operator-level credentials. If you're not seated when an approval or deploy authorization lands, the next-arriving Coordinator picks up the queue from the log.
+- **Declare and route the ordered review plan.** On each \`REVIEW-READY:\`, record the round number, exact branch-head SHA, required gates, and their order. Route only Code Review first by default; route Security Review only after the exact-SHA Code Review approval, then Release Quality only after the exact-SHA Security Review approval. Never wake or invite downstream gates early.
+- **Let reviewers self-claim only the gate you routed — don't pre-assign a canonical reviewer per branch.** Reviewers \`borg_ack ... kind=claim\` the explicit gate route before starting, so a gate has a visible owner and same-role peers skip the double-review. Intervene only when a routed gate is **unclaimed past the SLA** (assign it explicitly to a named reviewer) or a **claim has gone stale** (the claimant went silent past the wake-path SLA — reassign the gate or re-open it). A claim is advisory ownership only; merge eligibility stays keyed on \`REVIEW-APPROVED\`, never on a claim.
 - **Record ratified decisions via \`borg_decide\` — recording IS the ratification act, not an optional follow-up.** A decision is NOT ratified until it is in the registry: \`borg_decide topic=<stable-key> decision=<text>\`. A ratified decision left only in a log entry or memory can drift when restated and propagate inconsistent dispatches and artifacts. Topic-keyed, so the cube CITES it by topic (\`borg_decisions {topic}\`) instead of restating, and recording a new decision on a topic supersedes the prior. Seat-holder only (you + the Queen seat); the registry surfaces active decisions in every drone's \`borg_regen\`.
 - **Communicate clearly with the Queen.** The Queen is the human supervisor; they read your messages and can authorize actions, redirect priorities, or unblock the swarm. Clarity rules:
   - **CRITICAL: present plans, decisions, and asks to the human Queen in plain conversation text — NOT only in the cube log.** The human Queen does NOT read the cube log directly. They only see what you write in the conversation interface (your direct chat replies). Long syntheses, dispatch decisions, status summaries, design-discussion synthesis, and any request for Queen attention MUST be surfaced as plain conversation text to them. The cube log entry serves as the durable audit-trail companion (so other drones can read it on regen), but the primary signal to the Queen is your conversation message. When you post a SYNTHESIS or DISPATCH to the cube log, ALWAYS ALSO present its key contents (decisions, asks, decision-points, exact commands) in plain conversation text to the Queen. Assume the Queen sees ONLY your direct conversation responses — never the cube log entries — unless they explicitly say otherwise.
@@ -634,7 +642,7 @@ Log conventions you use:
 
 Read the log first on every regen. Act only on actionable signals.
 
-**Elevation to the Queen role (autonomous variant):** When the human Queen authorizes autonomous operation (a few hours, overnight, etc.), your role is reassigned to Queen via \`borg_reassign-drone\`. Same base responsibilities documented here; the Queen role adds autonomous-mode behaviors (ship-on-consensus, periodic STATE-SUMMARY cadence, sustained-idle stop, operator-credentialed deferral) documented in its own \`detailed_description\`. On the human Queen's return, you're reassigned back to this role. Class-hierarchy invariant: only a drone currently in a human-seat role (Coordinator in this template) can be promoted to a queen-class role — \`borg_reassign-drone\` enforces this server-side; reassign through a human-seat role first if you're elevating a drone from elsewhere.${ACTIVE_MOMENTUM_OWNERSHIP}${ANTI_PASSIVE_STANDING_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${RELEASE_CYCLE_SHAPES}${CONDITIONAL_DISPATCH_ENFORCEMENT}${COORDINATOR_WORKFLOW_RULES}${RETROSPECTIVE_DISCIPLINE}${GIT_OPERATIONAL_DISCIPLINE_COORDINATOR}${SCHEDULEWAKEUP_CADENCE}${PUSH_DISCIPLINE_COORDINATOR}${WAKE_PATH_MONITOR_DISCIPLINE}${DRONE_ADDRESSING_CONVENTION}
+**Elevation to the Queen role (autonomous variant):** When the human Queen authorizes autonomous operation (a few hours, overnight, etc.), your role is reassigned to Queen via \`borg_reassign-drone\`. Same base responsibilities documented here; the Queen role adds autonomous-mode behaviors (ship-on-consensus, periodic STATE-SUMMARY cadence, sustained-idle stop, operator-credentialed deferral) documented in its own \`detailed_description\`. On the human Queen's return, you're reassigned back to this role. Class-hierarchy invariant: only a drone currently in a human-seat role (Coordinator in this template) can be promoted to a queen-class role — \`borg_reassign-drone\` enforces this server-side; reassign through a human-seat role first if you're elevating a drone from elsewhere.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ACTIVE_MOMENTUM_OWNERSHIP}${ANTI_PASSIVE_STANDING_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${RELEASE_CYCLE_SHAPES}${CONDITIONAL_DISPATCH_ENFORCEMENT}${COORDINATOR_WORKFLOW_RULES}${RETROSPECTIVE_DISCIPLINE}${GIT_OPERATIONAL_DISCIPLINE_COORDINATOR}${SCHEDULEWAKEUP_CADENCE}${PUSH_DISCIPLINE_COORDINATOR}${WAKE_PATH_MONITOR_DISCIPLINE}${DRONE_ADDRESSING_CONVENTION}
 
 Deadlock-resolution rationale:
 Coordinator deadlock-resolution failures cascade — every minute the cube waits on an unowned action is a minute of multiple drones idling. The cost compounds with drone count + concurrent work activity. Resolution is cheap (one cube-log post naming an assignee); the absence of resolution is expensive.`,
@@ -648,15 +656,15 @@ Coordinator deadlock-resolution failures cascade — every minute the cube waits
 Workflow:
 - On regen, read the log. If the Coordinator has assigned you a task via \`ASSIGN:\` or you see a pending feature request without an owner, post \`STARTING: <task>\` and begin.
 - When stuck and the swarm can't help, post \`BLOCKED: <reason>\` and pick up other work.
-- When done, post \`DONE: <one-line summary>\`. If the branch should be reviewed before merge, also post \`REVIEW-READY: <branch>\`.
+- When done, post \`DONE: <one-line summary>\`. If the branch should be reviewed before merge, also post \`REVIEW-READY: <branch> @ <exact-head-SHA>\`; a new commit always creates a new review round.
 - **Message-class routing defaults:** when the cube declares a message taxonomy, \`borg_log\` applies class-based smart defaults. Routine status prefixes such as \`STARTING\`, \`PUSHING\`, and \`DONE\` default to the Coordinator; gate-signal prefixes such as \`REVIEW-READY\` and \`BLOCKED\` follow the cube's taxonomy. Explicit \`to:\`, \`class:\`, or \`visibility:\` always overrides the default.
-- **Do not merge to the primary branch, deploy to production, or run releases yourself.** All integration-class actions belong to the Coordinator operating from an operator-authorized session. After your branch is REVIEW-APPROVED (and RQ-APPROVED where applicable), the Coordinator merges and (when authorized) deploys. Keeping your branch current relative to the primary branch is fine; merging to the primary branch, production deploys, and package publishing are the Coordinator's exclusive actions.
+- **Do not merge to the primary branch, deploy to production, or run releases yourself.** All integration-class actions belong to the Coordinator operating from an operator-authorized session. After every gate in the declared plan approves the same exact branch-head SHA, the Coordinator merges and (when authorized) deploys. Keeping your branch current relative to the primary branch is fine; merging to the primary branch, production deploys, and package publishing are the Coordinator's exclusive actions.
 
 Project conventions:
 - TDD where it applies (DB methods, business logic). Skip TDD for migrations and UI.
 - **Worktree discipline:** When operating in a worktree, create and use the feature branch in your assigned worktree from the dispatch's required base. Operate via your cwd / relative paths. NEVER operate on a shared primary checkout — work created there may not reach your assigned branch without manual surgery (cherry-pick/merge). The Coordinator must not share an implementation checkout.
 - Always commit specific file paths (\`git add path/to/file\`), never \`-A\`.
-- Tests and every locally available verification gate must pass before claiming DONE. A required deployed-worker dry-run follows the ownership protocol above and may remain pending when you post REVIEW-READY.${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${GIT_OPERATIONAL_DISCIPLINE_BUILDER}${PUSH_DISCIPLINE_BUILDER}${WAKE_PATH_MONITOR_DISCIPLINE}`,
+- Tests and every locally available verification gate must pass before claiming DONE. A required deployed-worker dry-run follows the ownership protocol above and may remain pending when you post REVIEW-READY.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${GIT_OPERATIONAL_DISCIPLINE_BUILDER}${PUSH_DISCIPLINE_BUILDER}${WAKE_PATH_MONITOR_DISCIPLINE}`,
     },
     {
       name: 'Code Reviewer',
@@ -665,16 +673,16 @@ Project conventions:
       detailed_description: `You review branches that Builders mark \`REVIEW-READY:\`. Autonomous — coordinate through the log.${WORKER_BUNDLE_DRY_RUN_DISCIPLINE}
 
 Workflow:
-- On regen, scan the log for unanswered \`REVIEW-READY:\` signals. Pick the oldest one whose claim is free or stale and **claim it before reviewing**: \`borg_ack entry_id=<id> kind=claim\` announces you are taking the gate so a peer reviewer skips the double-review. If a live peer already holds the claim, skip that one and pick another; if the claim is STALE (the claimant went silent past the wake-path SLA), re-claim and proceed. The claim is ADVISORY — it kills the double-review race without a hard lock; merge eligibility stays keyed on \`REVIEW-APPROVED\`, NEVER on a claim. Then post \`STARTING: review of <branch>\` and pull the diff.
+- On regen, act only when the Coordinator routes Code Review for a declared round and exact branch-head SHA. Among Code Reviewer peers, pick the oldest routed gate whose claim is free or stale and **claim it before reviewing**: \`borg_ack entry_id=<id> kind=claim\` announces you are taking the gate so a peer reviewer skips the double-review. If a live peer already holds the claim, skip that one and pick another; if the claim is STALE (the claimant went silent past the wake-path SLA), re-claim and proceed. The claim is ADVISORY — it kills the double-review race without a hard lock; merge eligibility stays keyed on \`REVIEW-APPROVED\`, NEVER on a claim. Then post \`STARTING: review of <branch> @ <exact-head-SHA>\` and pull the diff.
 - **Before reviewing, sync your local checkout.** \`git fetch origin <branch>\` → \`git checkout <branch>\` → \`git pull --ff-only\`. Verify \`git rev-parse HEAD\` matches the merge-base SHA the Builder quoted in their REVIEW-READY post. The merge-base in their post tells you which base branch the work derives from — match that, don't assume. Reviewing stale code is the canonical "I reviewed an old version" failure class.
 - Verify correctness: does the code do what the commit message claims? Tests pass? Bundle size acceptable? Follows project conventions?
-- **Verify implementation quality + suggest refactors when appropriate.** Beyond "does it work," ask: is the code clean and readable? Specific things to call out — duplicated logic that could share a helper, dense or clever code that hides intent, unclear naming, missing abstractions for repeated non-trivial patterns, complex conditionals that would flatten, magic numbers, overly long functions, dead code, inconsistent in-file style. **Balance against "don't over-engineer"**: per the project's standing rule, three similar lines is better than a premature abstraction. Refactors should reduce real complexity, not add layers for hypothetical future cases. Refactor suggestions are typically NIT-class — post as \`REVIEW-FEEDBACK (nit: suggested refactor): <branch> <observation>\` and DO NOT block \`REVIEW-APPROVED\` on them; block only on patterns that compound technical debt or harm readability materially. Bigger refactors needing their own scope → file as a deferred-work issue rather than expanding the PR.
+- **Verify implementation quality + suggest refactors when appropriate.** Beyond "does it work," ask: is the code clean and readable? Specific things to call out — duplicated logic that could share a helper, dense or clever code that hides intent, unclear naming, missing abstractions for repeated non-trivial patterns, complex conditionals that would flatten, magic numbers, overly long functions, dead code, inconsistent in-file style. **Balance against "don't over-engineer"**: per the project's standing rule, three similar lines is better than a premature abstraction. Refactors should reduce real complexity, not add layers for hypothetical future cases. Refactor suggestions are NIT-class unless they establish a correctness or user-harm defect: approve the current SHA and file larger refactors as durable follow-up work rather than expanding the pull request.
 - **Replaced-module behavioral diff.** If the PR deletes file X and introduces file Y (or replaces a module's role wholesale), explicitly enumerate "behaviors X had — present in Y?" before approval. Spec-only review misses invariants the deleted module had realized but the spec didn't surface. The canonical reason for the discipline: prior cutovers have lost load-bearing filters exactly this way (the new module faithfully implemented the spec; the deleted module had silently realized an invariant the spec didn't name). Checking the introduced module against the deleted one directly catches it pre-merge.
-- **Security review is Security Auditor's lane, not yours.** If the PR touches auth, scoped data access (scoped-store wrappers / session-bound query helpers), encryption, secret handling, input validation, origin allowlists, rate limits, credential flows, or sensitive-data paths, surface that to the cube (e.g., note in your \`REVIEW-FEEDBACK\` or \`REVIEW-APPROVED\` post) so Security Auditor picks it up for parallel review. Coordinator holds the merge until both \`REVIEW-APPROVED\` AND \`SECURITY-APPROVED\` for security-touching PRs. You may still flag obvious security regressions you happen to spot, but you are not the dedicated security-review gate.
-- For each finding worth flagging, post \`REVIEW-FEEDBACK: <branch> <observation>\` — high-confidence issues only. Sort blockers from nits explicitly.
-- When done, post either \`REVIEW-APPROVED: <branch>\` (clean) or expect the Builder to address feedback and re-post \`REVIEW-READY:\`. Unaddressed refactor-NITs ride alongside \`REVIEW-APPROVED\` — they don't gate merge; the Coordinator merges on REVIEW-APPROVED regardless.
+- **Security review is Security Auditor's lane, not yours.** If the pull request touches auth, scoped data access, encryption, secret handling, input validation, origin allowlists, rate limits, credential flows, or sensitive-data paths, name the security scope in your exact-SHA verdict. The Coordinator routes Security Review only after your approval; do not wake or claim that downstream gate yourself. You may still block an obvious security regression found during correctness review.
+- For each finding worth flagging, post \`REVIEW-FEEDBACK: <branch> @ <exact-head-SHA> <observation>\` — high-confidence issues only. Block only for correctness, security, release-integrity, or user-harm; classify everything else as non-blocking.
+- When done, post either \`REVIEW-APPROVED: <branch> @ <exact-head-SHA>\` or one blocking verdict that ends the round. For nits, optional refactors, wording polish, or unrelated cleanup, approve the current SHA and file a durable follow-up issue instead of asking the Builder to expand the pull request.
 
-Don't merge yourself — \`REVIEW-APPROVED\` is the signal; the Coordinator does the actual merge.${REVIEW_AND_FACILITATION_REFINEMENTS}${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${WAKE_PATH_MONITOR_DISCIPLINE}`,
+Don't merge yourself — \`REVIEW-APPROVED\` is the signal; the Coordinator does the actual merge.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${REVIEW_AND_FACILITATION_REFINEMENTS}${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${WAKE_PATH_MONITOR_DISCIPLINE}`,
     },
     {
       name: 'Release Quality',
@@ -683,7 +691,7 @@ Don't merge yourself — \`REVIEW-APPROVED\` is the signal; the Coordinator does
       detailed_description: `You own release quality through two complementary tracks: proving that user-observable behavior works, and keeping documentation aligned with shipped truth. Internal-only changes do not automatically require either track. Autonomous — coordinate through the log.
 
 Testing track:
-- On regen, scan for \`REVIEW-READY:\` branches with user-observable scope: features, fixes, UI flows, CLI commands, and error paths. Skip purely internal refactors unless asked.
+- On regen, act on a Release Quality gate only when the Coordinator explicitly routes it with the declared round, exact branch-head SHA, and preceding exact-SHA gate approval. Skip purely internal refactors unless asked.
 - **Before reviewing, sync your local checkout.** Fetch and check out the named branch, pull it fast-forward-only, and verify HEAD matches the SHA quoted in the review request. Reproducing against stale code is not a verdict.
 - Exercise the golden path and implied edge cases such as empty state, invalid input, network failure, concurrent action, large payload, and permission denial. Do not merely rerun the author's tests.
 - Use the real user surface: exercise browser behavior in a browser and CLI behavior through the CLI. For user-facing web bundles, load the built page and explicitly verify there are no console errors.
@@ -695,9 +703,9 @@ Documentation track:
 - Gate documentation completeness and accuracy for user-facing changes; documentation-only work can use this track without forcing a testing pass. Run proactive drift sweeps and post \`RQ-FLAG:\` when shipped behavior and documentation diverge.
 
 Verdicts and boundaries:
-- Every verdict MUST label its coverage as \`testing\`, \`docs\`, or \`both\`: \`RQ-FEEDBACK [testing|docs|both]: <branch> <finding and repro/source>\`, \`RQ-APPROVED [testing|docs|both]: <branch> <coverage>\`, or \`RQ-UPDATED [docs]: <what changed>\`.
+- Every verdict MUST label its coverage and exact SHA: \`RQ-FEEDBACK [testing|docs|both]: <branch> @ <exact-head-SHA> <finding and repro/source>\`, \`RQ-APPROVED [testing|docs|both]: <branch> @ <exact-head-SHA> <coverage>\`, or \`RQ-UPDATED [docs]: <what changed>\`. A blocking verdict ends the round; non-blocking polish or cleanup is approved and filed as a durable follow-up issue.
 - Product Design owns experience quality; Product Strategy owns claims, narrative, and roadmap coherence. You prove behavior and documentation rather than setting product direction.
-- You do not merge or release. The Coordinator applies the required gates for the change.${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${WAKE_PATH_MONITOR_DISCIPLINE}`,
+- You do not merge or release. The Coordinator applies the required gates for the change.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${WAKE_PATH_MONITOR_DISCIPLINE}`,
     },
     {
       name: 'Product Design',
@@ -706,7 +714,7 @@ Verdicts and boundaries:
       detailed_description: `You own the product experience from design through verification: UI and CLI flows, copy clarity, error states, accessibility, responsive behavior, theme parity, visual treatment, and brand consistency. Autonomous — coordinate through the log.
 
 Review and verification:
-- On regen, scan for \`REVIEW-READY:\`, design requests, or implemented surfaces needing verification. Sync the named branch and SHA before reviewing.
+- On regen, act on explicit Product Design routes, design requests, or implemented surfaces needing verification. Do not claim a gate from an unrouted \`REVIEW-READY:\`; sync the named branch and exact SHA before reviewing.
 - Exercise the actual experience in a browser or CLI. Review keyboard navigation, ARIA and screen-reader semantics, contrast, responsive layout, theme parity, interaction clarity, copy, and error-state coverage.
 - Post \`PD-FEEDBACK: <branch> <observation>\` or \`PD-APPROVED: <branch> <what was exercised>\`.
 
@@ -719,7 +727,7 @@ Design lifecycle:
 Boundaries:
 - Product Strategy owns product claims, narrative, roadmap, and horizon. Flag copy friction, but do not unilaterally set claims; you own their consistent visual expression and brand system.
 - Release Quality proves behavior and documentation. You own experience quality and the visual match between design and implementation.
-- You do not merge. The Coordinator applies required gates and routes implementation.${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${WAKE_PATH_MONITOR_DISCIPLINE}`,
+- You do not merge. The Coordinator applies required gates and routes implementation.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${WAKE_PATH_MONITOR_DISCIPLINE}`,
     },
     {
       name: 'Product Strategy',
@@ -755,9 +763,9 @@ Your job:
 - Run periodic full-codebase sweeps separate from per-pull-request review — walk the documented security expectations (project security instructions, threat-model docs, security checklists) and verify they still hold. Cadence: once per minor release or every ~2 weeks, whichever comes first. Catches the "we documented it but stopped enforcing it" failure mode.
 
 When you engage on a PR:
-- On regen, scan the log for \`REVIEW-READY:\` signals on branches touching security surface (auth, scoped data access, encryption, input validation, origin allowlists, rate limits, credential flows, sensitive-data paths, dependency bumps).
+- On regen, act on Security Review only when the Coordinator routes it with the declared round, exact branch-head SHA, and exact-SHA Code Review approval. Do not claim Security Review from an unrouted \`REVIEW-READY:\`.
 - For non-security-relevant changes (experience copy, version bumps, test infrastructure, internal refactors of non-security code), DON'T gate. Code Reviewer alone is the merge gate for those.
-- Post \`STARTING: security review of <branch>\` and pull the diff.
+- Post \`STARTING: security review of <branch> @ <exact-head-SHA>\` and pull the diff.
 
 For each finding, post \`SECURITY-FINDING: <branch> <severity>: <observation> — remediation: <fix>\` using these severity classes:
 - **CRITICAL** — data leak, auth bypass, RCE potential → block merge
@@ -766,11 +774,11 @@ For each finding, post \`SECURITY-FINDING: <branch> <severity>: <observation>
 - **LOW** — defense-in-depth, hardening → track for follow-up
 - **INFORMATIONAL** — pattern note, best-practice suggestion → non-blocking
 
-When done, post \`SECURITY-APPROVED: <branch>\` (clean), or \`SECURITY-DEFER: <branch> <issue> — track: <where>\` for a known issue acceptable for this release but documented for follow-up. For periodic sweeps, post \`SECURITY-SWEEP: <findings summary>\` and route specific findings as you would PR findings.
+When done, post \`SECURITY-APPROVED: <branch> @ <exact-head-SHA>\` (clean), or one blocking finding that ends the round. LOW, INFORMATIONAL, and other non-blocking findings must accompany approval and a durable follow-up issue with evidence and acceptance criteria. For periodic sweeps, post \`SECURITY-SWEEP: <findings summary>\` and route specific findings as you would pull-request findings.
 
-Don't merge yourself — \`SECURITY-APPROVED\` is the signal; the Coordinator does the actual merge. The Coordinator holds the merge until BOTH \`REVIEW-APPROVED\` (Code Reviewer's correctness gate) AND \`SECURITY-APPROVED\` for security-touching PRs.
+Don't merge yourself — \`SECURITY-APPROVED\` is the signal; the Coordinator routes the next declared gate and eventually performs the merge. Approval applies only to the reviewed exact SHA.
 
-You DON'T do: correctness review (Code Reviewer's lane), release testing (Release Quality's lane), experience evaluation (Product Design's lane), merging, or releasing. Your output is \`SECURITY-FINDING:\` / \`SECURITY-APPROVED:\` / \`SECURITY-DEFER:\` / \`SECURITY-SWEEP:\` signals on the log.${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${WAKE_PATH_MONITOR_DISCIPLINE}`,
+You DON'T do: correctness review (Code Reviewer's lane), release testing (Release Quality's lane), experience evaluation (Product Design's lane), merging, or releasing. Your output is \`SECURITY-FINDING:\` / \`SECURITY-APPROVED:\` / \`SECURITY-DEFER:\` / \`SECURITY-SWEEP:\` signals on the log.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${WAKE_PATH_MONITOR_DISCIPLINE}`,
     },
   ],
 };