axstack 0.9.1 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks Orca capabilities.",
   "keywords": [
     "claude-code",

package/skills/axstack/references/automations.md

@@ -12,8 +12,14 @@ own prompt; never assume.
 - **Pair A/B** — driver Automation A (`*/30`) and watchdog Automation B, run id
   `20260916-pr-automations`, allowlist `axatbhardwaj/axstack`.
 - **Pair C/D** — driver Automation C (hourly) and watchdog Automation D, run id
-  `20260916-defi-automations`, allowlist
-  `defi-com/monorepo, defi-com/mobile, defi-com/azure-next-hybrid`.
+  `20260916-defi-automations`, carrying **two** lists rather than one:
+  - review allowlist `defi-com/monorepo, defi-com/mobile,
+    defi-com/azure-next-hybrid`;
+  - repair allowlist `defi-com/monorepo, defi-com/mobile`.
+
+  `defi-com/azure-next-hybrid` is therefore review-only: its own PRs are
+  discovered and recorded but never repaired and never pushed to, and they are
+  not review candidates either, since a PR authored by self is not a peer PR.
 
 The two pairs share no state: each has its own run id, run directory,
 `progress.md` and sidecars, and no sidecar is shared between them. A clause
@@ -43,9 +49,13 @@ owns policy, the run record, and evidence.
   deduplicated canonically by PR URL across the three searches with own-PR
   precedence.
 - **Mutation allowlist:** stated verbatim in the automation prompt, per
-  automation rather than as one global list. One allowlist gates both own-PR
-  repair and peer review for its own automation; there is no separate
-  review-only list. Outside the
+  automation. Pair A/B carries one list gating both own-PR repair and peer
+  review. Pair C/D carries two, a review allowlist and a repair allowlist, and
+  each action reads its own list: a repository on the review list but not the
+  repair list is reviewed and never repaired. Where a clause says "allowlisted"
+  without naming an action — including the precheck's "hash only allowlisted
+  PRs" — it means the union of the applicable lists for discovery and the wake
+  fingerprint, and the action-specific list for the action itself. Outside the
   allowlist the automation discovers and records only. The precheck writes the
   full discovery list to `pending.json`; no review, watch, gate, or other model
   work is launched for an external PR. External changes do not enter the wake
@@ -53,8 +63,11 @@ owns policy, the run record, and evidence.
   never produce an escalation. This is a deliberate coverage reduction, not an
   implied clean review; discovery errors themselves remain automation-health
   findings.
-- **Prohibited everywhere:** force-push, rebase, merge, close, `APPROVE`,
-  `REQUEST_CHANGES`. A need for any of these becomes a recorded hold.
+- **Prohibited everywhere:** force-push, rebase, merge, close. A need for any of
+  these becomes a recorded hold, for all four automations, with no exception.
+- **`APPROVE` and `REQUEST_CHANGES`** are prohibited for Automations A, B and D.
+  Automation C may submit them under "Binding review verdicts (pair C)" below
+  and nowhere else; a need for either outside that section is a recorded hold.
 
 ## Roles per mode
 
@@ -135,9 +148,15 @@ digest is not already recorded against that PR at that head SHA. Review-ID dedup
 insufficient: a bot that re-posts the identical finding under a new review ID
 would otherwise re-trigger a repair on every tick.
 
-Caps: at most one repair per PR per 24 hours, counted regardless of trigger; and
-a per-tick push budget across all allowlisted repositories combined, configured
-per pair and six for pair C/D. Reaching either cap records a hold naming the cap
+Caps: at most one repair per PR per 24 hours, counted regardless of trigger; a
+per-tick push budget across all allowlisted repositories combined, configured
+per pair and six for pair C/D; and, for pair C, a per-tick **review** budget
+limiting how many binding verdicts may be submitted in one tick, configured per
+pair and **one** for pair C. The review budget exists because C has no `COMMENT`
+path, so an unbudgeted first tick over a backlog would place binding verdicts on
+every discovered peer PR at once, unattended and on other people's work. Reviews
+beyond the budget are left for the next tick, oldest `updatedAt` first so the
+backlog drains in a stable order rather than by chance. Reaching any of the three caps records a hold naming the cap
 and the value reached, rather than silently dropping the work. A budget hold
 names the budget as its owner and is exempt from the hold with no owner
 threshold. When a per-PR cap has expired the precheck wakes the driver even
@@ -186,6 +205,69 @@ repository's workflow files, recorded, and re-verified before enabling and on
 any later allowlist change. It is never hardcoded to one branch name, because a
 repository may deploy from more than one branch and may add another at any time.
 
+## Binding review verdicts (pair C)
+
+Automation C submits a real review verdict where pair A/B publishes a `COMMENT`.
+The authority is narrow and every bound below is load-bearing.
+
+Every review Automation C publishes is a binding verdict. C has no `COMMENT`
+path: a peer PR reached through the qualifying mention trigger gets a verdict
+exactly as an officially-requested one does. The only restriction is authorship
+— GitHub rejects a verdict from a PR's own author, so an authored-mode review of
+C's own repair stays internal and gates only the push. Automation D never writes
+to GitHub at all.
+
+`APPROVE` requires a complete mode-required review at the exact head SHA with a
+current base, the gate's `proceed`, and zero unresolved validated blocking
+findings. `REQUEST_CHANGES` requires the same completeness and gate token and at
+least one validated blocking finding carrying its evidence and consequence; it
+is the verdict that reports blockers and is not gated on their absence.
+`INCOMPLETE`, unresolved material disagreement, an unavailable required
+reviewer, or a gate `escalate` submits nothing and records a hold.
+
+### Blocking obligations
+
+A submitted `REQUEST_CHANGES` blocks the PR and a teammate's later push does not
+clear it. Submitting a review also removes self from GitHub's `review-requested`
+results, so a PR C has just blocked can leave discovery on the next tick and C
+would never see it again to clear its own block.
+
+C therefore records every unresolved blocking review in `cursor.json` as an open
+obligation holding the PR URL, the review id, the head SHA it was bound to, and
+the submission timestamp, and polls those PRs directly by URL every tick
+regardless of discovery eligibility. An obligation is discharged only by
+observing the PR merged, closed, or its blocking review resolved or superseded.
+A failed poll retries next tick; three consecutive unpollable ticks is a health
+finding routed to the gate.
+
+While C holds any unresolved blocking review, every scheduled tick wakes it: an
+outstanding obligation is due control work in the precheck's list, alongside a
+watch deadline, a pending failed-relay retry, and an expired repair cap.
+
+An obligation carries a narrow authority to resolve itself: C may submit exactly one superseding verdict on that PR,
+including a clearing `APPROVE`, without a fresh review request. It follows the
+obligation chain — an obligation opened by a verdict submitted under this
+authority inherits it — so the authority persists on that one PR until it
+merges, closes, or its block is resolved, and the deadlock does not reappear one
+head later when a teammate pushes without fixing. It extends to nothing else: not
+another PR, not a discharged obligation, and never more than one superseding
+verdict per head SHA. A supersede whose head and base are both unchanged
+additionally requires a recorded finding-level reason naming what changed about
+the finding; without it C holds and submits nothing.
+
+### Local review file
+
+Every review C publishes, verdict or `COMMENT`, is also written to the
+workspace review directory `~/defi/misc/reviews/`, carrying the same findings
+and evidence as the submitted review plus the reviewed SHA. The naming is the
+workspace convention and the prefix rules are load-bearing, because PR numbers
+collide across repositories: `review-PR-<num>.html` with no prefix means
+`defi-com/monorepo` by definition, and every other repository takes its prefix,
+`review-azure-next-hybrid-PR-<num>.html` and `review-mobile-PR-<num>.html`. A
+failure to write the file is a recorded hold; a review is never withheld or
+retracted because the file could not be written, so the mismatch stays visible
+rather than silent.
+
 ## Escalation gate
 
 After every mode-required reviewer settles, the driver spawns `axstack-auditor`
@@ -198,13 +280,18 @@ escalation gate. It returns exactly one literal token, `escalate` or `proceed`.
   [axstack-relay](../../axstack-relay/SKILL.md) naming the PR, the criterion,
   every reviewer's reason, where the user acts (Orca conversation, worktree, or
   PR), and the hold; it publishes nothing.
-- `proceed` → no notification; a push or `COMMENT` publication then
-  additionally requires no unresolved validated blocking finding, because
-  `proceed` never overrides a validated blocking finding. A reviewer security
+- `proceed` → no notification; a push, a `COMMENT` publication, or an
+  `APPROVE` then additionally requires no unresolved validated blocking finding,
+  because `proceed` never overrides a validated blocking finding. A
+  `REQUEST_CHANGES` is the exception and the only one: it is the publication
+  that reports validated blocking findings, so it requires at least one and is
+  never gated on their absence. A reviewer security
   "yes" that the gate does not escalate is recorded as rejected-with-evidence
   or returned to the author before any mutation.
-- Only `proceed` plus no unresolved validated blocking finding permits a push
-  or publication; a push before the gate settles is forbidden.
+- Only `proceed` plus no unresolved validated blocking finding permits a push,
+  a `COMMENT` publication or an `APPROVE`; a `REQUEST_CHANGES` needs `proceed`
+  plus at least one such finding. A push or publication before the gate settles
+  is forbidden either way.
 - Precedence: credible serious risk found by a reviewer still produces the
   standing internal prompt and dependent-action hold immediately, and the gate
   governs only external notification. That hold is the serious-risk rule of
@@ -231,8 +318,9 @@ to the hashed fingerprint, so a draft becoming ready wakes the driver on its
 own; pair A/B's queried fields and fingerprint are unchanged. Hash
 only allowlisted PRs. Read `cursor.json` for the last processed fingerprint and
 for due control work: a watch deadline at or before now (pair A/B only, since
-pair C/D stores no deadlines), a pending failed-relay retry, or a per-PR repair
-cap that has expired (pair C/D only, since pair A/B has no caps). Exit 0 when the hash differs or control work is due;
+pair C/D stores no deadlines), a pending failed-relay retry, a per-PR repair cap
+that has expired, or an outstanding blocking-review obligation (both pair C/D
+only, since pair A/B has neither caps nor binding verdicts). Exit 0 when the hash differs or control work is due;
 otherwise exit non-zero. Exit non-zero without running when the previous driver
 run is still active, or on `error`. Append one line
 `<ts> <changed|due|unchanged|error|busy>` to `precheck.log`.
@@ -265,15 +353,20 @@ repair and publication for that run and is a health finding.
 
 For each changed PR:
 
-- Own PR → [axstack-watch](../../axstack-watch/SKILL.md) on the exact head
+- Own PR, and only when its repository is on the acting automation's repair
+  allowlist → [axstack-watch](../../axstack-watch/SKILL.md) on the exact head
   SHA in a per-PR child worktree; the driver worktree never checks out a PR
-  branch. Follow its repair-publication reference: candidate committed locally,
+  branch, and an own PR in a review-only repository is recorded and nothing
+  else, with no repair, no worktree and no push. Follow its repair-publication reference: candidate committed locally,
   authored review at the local SHA, gate, then fast-forward push with the
   publication readback immediately before it.
 - Peer PR → two isolated `axstack-review` passes on the exact head SHA, then
-  the gate, then one owner-synthesized `COMMENT` review under the review skill's
-  COMMENT branch. `INCOMPLETE` or an unavailable required reviewer records a
-  hold and publishes nothing.
+  the gate, then one owner-synthesized review bound to the reviewed commit. For
+  pair A/B that is a `COMMENT` under the review skill's COMMENT branch; for
+  every pair C peer PR it is a binding verdict under "Binding review verdicts
+  (pair C)" above, whether the PR was reached by an official review request or
+  by the qualifying mention trigger. `INCOMPLETE` or an
+  unavailable required reviewer records a hold and publishes nothing.
 
 Watch window, pair A/B only: 24 hours per own PR from first observation, ending
 early on merge or close. The deadline is stored in `cursor.json`; a due deadline
@@ -344,8 +437,10 @@ hermes send, target telegram (home), host VPS, gate-authorized escalations only
 Machine-readable sidecars in the same directory: `pending.json` (observed
 fingerprint plus full discovery list, written by the precheck), `cursor.json`
 (last processed fingerprint promoted verbatim from `pending.json`, expired PR
-list and per-PR watch deadlines for pair A/B only, pending failed-relay
-retries; written by the driver after each processed tick), `precheck.log` (precheck only), and
+list and per-PR watch deadlines for pair A/B only, outstanding blocking-review
+obligations for pair C only — each holding PR URL, review id, bound head SHA,
+submission timestamp and whether its one supersede is still available — pending
+failed-relay retries; written by the driver after each processed tick), `precheck.log` (precheck only), and
 `watchdog.json` (watchdog only). Orca run history remains the authoritative
 log; the record is derived progress, never authority.
 

package/skills/axstack-review/SKILL.md

@@ -16,10 +16,12 @@ to select the mode and scope identity, and apply the shared
 [PR-shape policy](../axstack/references/pr-shape.md). For an owned candidate,
 load and verify the
 [candidate-publication boundary](../axstack/references/candidate-publication.md).
-When the caller is the Orca driver automation, load
-[Automation sessions](../axstack/references/automations.md): its reviewer
-briefs carry the required escalation field and its publication is `COMMENT`
-only.
+When the caller is an Orca driver automation, load
+[Automation sessions](../axstack/references/automations.md): its reviewer briefs
+carry the required escalation field, and its publication is `COMMENT` only for
+the pair A/B driver. Every peer PR the pair C driver publishes on takes the
+actual verdict instead, under "Binding review verdicts (pair C)" in that
+reference and the authorized-submission branch below.
 
 ## Peer mode (colleague PR)
 
@@ -306,20 +308,26 @@ for a complete `APPROVE` or `REQUEST_CHANGES` verdict:
 Submission is complete only when the remote receipt confirms the review bound
 to the intended commit.
 
-Automation exception — Authorized submission: the `COMMENT` branch below, with
-the existing remote head/base readback and ambiguity handling, is the only
-submission the Orca driver automation makes. The prohibition on `APPROVE` and
-`REQUEST_CHANGES` is a ban on those GitHub actions; the review skill's internal
-verdict vocabulary is unchanged.
+Automation exception — Authorized submission, pair-scoped: for the pair A/B
+driver automation the `COMMENT` branch below, with the existing remote head/base
+readback and ambiguity handling, is the only submission it makes, and for it the
+prohibition on `APPROVE` and `REQUEST_CHANGES` remains a ban on those GitHub
+actions while the review skill's internal verdict vocabulary is unchanged. The
+pair C driver automation instead uses this authorized-submission
+branch and submits the actual verdict on an officially-requested peer PR, under
+"Binding review verdicts (pair C)" in
+[Automation sessions](../axstack/references/automations.md); a peer PR it
+reached through the qualifying mention trigger still takes the `COMMENT` branch.
 
 ## Automation publication (`COMMENT`)
 
-Only the Orca driver automation, as owner for a peer PR under
+The pair A/B driver automation, as owner for a peer PR under
 [Automation sessions](../axstack/references/automations.md), uses this branch:
-one `COMMENT` review, owner-synthesized and bound to the reviewed commit. It
-never submits `APPROVE` or `REQUEST_CHANGES`; a need for either is a
-recorded hold. The peer-review submission rule above is unchanged for every
-other caller.
+one `COMMENT` review, owner-synthesized and bound to the reviewed commit. On
+this branch the automation never submits `APPROVE` or `REQUEST_CHANGES`; a need
+for either is a recorded hold. The pair C driver does not use this branch at
+all; its peer PRs take the authorized-submission branch above. The peer-review submission rule above is unchanged for every other
+caller.
 
 1. Complete the mode-required review: every mode-required receipt is current
    for the head SHA and current base, and each carries its escalation field.