Skip to content
12 changes: 7 additions & 5 deletions .agents/skills/cipher-hook/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
---
name: cipher-hook
description: >-
Agent-only playbook for a genuine needs-decision transition, an iinvy checks-green transition, an authenticated cipher-comment notification, or a cipher-retry check notification.
It owns the Cipher authority split, durable GitHub answer fetch, iinvy merge hold, held-delivery retry outcomes, and local receive command that avoids primary-pane ambiguity.
Agent-only playbook for a genuine needs-decision transition, an iinvy checks-green transition, an authenticated cipher-comment notification, or a cipher-retry or cipher-reconcile check notification.
It owns the Cipher authority split, durable GitHub answer fetch, iinvy merge hold, held-delivery retry and reconciliation outcomes, and local receive command that avoids primary-pane ambiguity.
user-invocable: false
metadata:
internal: true
---

# Cipher hook

Load this after current-state reconciliation proves a genuine `needs-decision`, when a checks-green pull request belongs to `morris2spears/iinvy` or `morris2spears/iinvy-storefront`, or on a `cipher-comment` or `cipher-retry` check notification.
Load this after current-state reconciliation proves a genuine `needs-decision`, when a checks-green pull request belongs to a repository listed in [`bin/fm-cipher-hook-repositories`](../../../bin/fm-cipher-hook-repositories), or on a `cipher-comment`, `cipher-retry`, or `cipher-reconcile` check notification.
The local setup and wire schema are owned by [`docs/configuration.md`](../../../docs/configuration.md#cipherhermes-bridge), while the command contracts are owned by the headers of [`bin/fm-cipher-hook.sh`](../../../bin/fm-cipher-hook.sh) and [`bin/fm-cipher-receive.sh`](../../../bin/fm-cipher-receive.sh).

## Genuine needs-decision
Expand Down Expand Up @@ -38,9 +38,11 @@ Never use gateway response prose as the decision ledger because GitHub is author

## Iinvy checks-green boundary

`bin/fm-pr-check.sh` emits the exact-head event automatically after it records a checks-green iinvy PR.
`bin/fm-pr-check.sh` emits the exact-head event automatically after it records a checks-green iinvy PR, and the watcher's `reconcile` sweep re-registers through that same trigger when a recorded gated PR reaches checks-green only later - after a rebase or sync, a repair or recovery, or a manual coordinator reconciliation.
Checks-green is decided by local reconciliation or by GitHub's own answer - open, CLEAN, and a check rollup carrying a real passed check, never mergeability alone - so a wedged local CI monitor never hides a forge-green PR while a PR whose CI has not run is never mistaken for one, and the trigger's `armed:` line confirms only the merge watch, never delivery.
A `cipher-reconcile` check notification reporting `delivered <request-id> iinvy-pr-ready <task-id>` is that checks-green transition reaching Cipher: treat it as the PR-ready milestone, report the PR to the captain with its full URL if not already reported, and keep the merge with Cipher exactly as below.
A missing or disabled route, timeout, unavailable gateway, invalid acknowledgement, or delivery failure keeps the merge held.
Do not invoke the ordinary merge command for either gated repository, even after event delivery succeeds.
Do not invoke the ordinary merge command for any gated repository, even after event delivery succeeds.
Cipher alone invokes `bin/fm-cipher-hook.sh merge <id> <PR-url> <request-id>` after its narrow production-outage inspection, and that command still enters the guarded merge helper with an exact-head condition.
Cipher's inspection is limited to cross-repository provider and consumer contracts, migration or deployment order, runtime install/import/restart behavior, and production-realistic health or smoke gates.
It does not repeat code review, style review, architecture review, or no-mistakes review.
Expand Down
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,8 @@ state/ volatile runtime signals; gitignored
tg-away-digest/ away-mode private 0600 working copies of the escalation lines an accepted Telegram notice carried; read these when a delivery receipt points at them, folded into return catch-up, and retired with the away session (bin/fm-away-ledger-lib.sh)
tg-away-versions/ away-mode immutable batch versions, one complete v.<id>/ copy of the escalation buffer, ledger sidecar, wedge marker, and digests per ledger transition, plus the single active/active.applied pointer and the .owner.lock every transition holds; the live artifacts are that pointer's projection, and retained versions fold into return catch-up and retire whole once it is acknowledged (bin/fm-away-ledger-lib.sh)
pending-replies/ parent-owned secondmate pending-reply records (correlation id, delivery vs reply, recovery, escalation); fm-pending-reply-lib.sh
cipher-hooks/ private request, sent, acknowledgement, hold, diagnostic, and authenticated-return records for the optional Cipher/Hermes bridge; bin/fm-cipher-hook.sh
cipher-hooks/ private request, sent, acknowledgement, hold, announcement, diagnostic, and authenticated-return records for the optional Cipher/Hermes bridge; bin/fm-cipher-hook.sh
.cipher-reconcile-cursor private per-cadence resume point for the Cipher checks-green reconciliation sweep, naming the last gated task it took; never touch (docs/configuration.md "Cipher/Hermes bridge")
cipher-receive.turn-ended append-only content-free monitoring edge for authenticated Cipher return records already in the durable wake queue; bin/fm-cipher-receive.sh
x-inbox/ generated X-mode pending mention payloads; fmx-respond drains it (section 14)
x-context/ generated X-mode durable per-request reply context and one-wake offer markers, keyed by request_id; survives inbox cleanup and expires within seven days (section 14; bin/fm-x-lib.sh)
Expand Down Expand Up @@ -323,7 +324,7 @@ The worker reports the PR when CI first becomes green rather than waiting for me

For PR-based ship tasks, the ready signal depends on mode: `no-mistakes` reports `done: PR <url> checks green` after CI is green, while `direct-PR` reports `done: PR <url>` after opening the PR.
Run `bin/fm-pr-check.sh <id> <PR url>` - it records `pr=` and the forge's `pr_head=` when available in the task's meta and arms the watcher's merge poll.
For a checks-green PR in either canonical iinvy repository, load `cipher-hook`; its exact-head production-outage boundary supersedes routine merge authority.
For a checks-green PR in any canonical Cipher-gated iinvy repository, load `cipher-hook`; its exact-head production-outage boundary supersedes routine merge authority.
Tell the captain the PR's full URL, always the complete `https://...` link rather than a bare `#number`, a concise outcome summary, and the no-mistakes risk level when applicable.
A captain instruction to merge is explicit authority; `yolo` is the only standing routine authority.
The same poll also watches for the captain declining the work by closing the pull request without merging it after commenting on it; load `pr-decline-feedback` on that wake before acting on his comment.
Expand Down Expand Up @@ -491,7 +492,7 @@ These skills are not captain-invocable; load them only at their precise triggers
- `bootstrap-diagnostics` - load whenever the session-start digest's bootstrap section prints an actionable diagnostic line (`MISSING:`, `MISSING_MANUAL:`, `BACKEND_INVALID:`, `NEEDS_GH_AUTH`, `TANGLE:`, `CREW_DISPATCH: invalid`, `FLEET_SYNC:`, `PR_CHECK_MIGRATION:`, `SECONDMATE_SYNC:`, `SECONDMATE_LIVENESS:`, `NUDGE_SECONDMATES:`, `FMX:`, or `FMTG:`); silence and `BOOTSTRAP_INFO:` need no load.
- `diagnostic-reasoning` - load before scoping a reported bug and before acting on a diagnostic report.
- `ask-user-authority` - load before deciding any ask-user finding, regardless of the project's `yolo` posture.
- `cipher-hook` - load after reconciling a genuine `needs-decision`, for a checks-green iinvy or iinvy-storefront PR, on an authenticated `cipher-comment` check notification, or on a `cipher-retry` check notification.
- `cipher-hook` - load after reconciling a genuine `needs-decision`, for a checks-green PR in a Cipher-gated iinvy repository, on an authenticated `cipher-comment` check notification, or on a `cipher-retry` or `cipher-reconcile` check notification.
- `quota-array-dispatch` - load before choosing among a matched crew-dispatch profile array from current quota-axi output.
- `harness-adapters` - load before spawning or recovering a crewmate or secondmate, handling a trust dialog, sending a harness-specific skill invocation, interrupting or exiting an agent, resuming an exited agent, or verifying a new harness adapter.
- `firstmate-orca` - load before switching to Orca, spawning or supervising Orca-backed work, smoke-testing Orca backend behavior, debugging Orca task state, or reconciling Orca-backed task metadata.
Expand Down
1 change: 1 addition & 0 deletions bin/fm-cipher-hook-repositories
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
# Exact lower-case GitHub repositories whose checks-green merge boundary belongs to Cipher.
morris2spears/iinvy
morris2spears/iinvy-storefront
morris2spears/iinvy-control-plane
Loading
Loading