Skip to content

tvproductions/gzkit / .agents/skills/gz-mx

Use to open or exit the MX hangar or safe mode, or to check which mode is open.

FileKindSize
AGENTS.mdmarkdown12.2 KB
SKILL.mdskill md11.4 KB
<!-- Generated by gzkit — do not edit manually -->
# .gzkit/skills/gz-mx Agent Instructions

> Shared subtree rules. See root `AGENTS.md` for project-wide governance.

<!-- Generated by gz agent sync — do not edit -->

<!-- rule-version: 1.17.0 -->

# MX Mode (Maintenance Hangar) (gzkit)

> **Rule version:** `1.17.0` — § Do Not's exit clause follows the ratified doctrine: exit waits on lines graded *blocks return to service*, and the handback transfers the rest (RP-7 held ruling H8, operator, 2026-11-13: *"A: Reword to doctrine"*); version narrative in [Rule Version History](../../docs/governance/rule-version-history.md#mx-modemd).

## Non-negotiable rules

### Honor the marker

- Honor the marker: when the condition is on, most guards drop to advisory

**The condition is on only when `.gzkit/mx.json` is present, parses, is bound to a still-open
`mx_session_opened` and is not `exiting`** (`gzkit.mx.marker.condition`; operator ruling
2026-10-27, *"A"*). Anything else is normal operation at full strength: an unreadable or
hand-made marker lowers nothing, the banner names its cause, and `gz mx repair`, through the
`gz-mx` skill, is the recovery. Readers that raise protection keep the file's presence, so a
corrupted marker still refuses a second entry and a release (ruling 2026-10-31, *"a"*). The marker
is committed: the condition belongs to the repository, every clone and CI (2026-10-27, *"A"*). CI's
`full-strength-report` job sets `GZKIT_MX_FULL_STRENGTH` and reports without failing the run
(2026-10-26, *"report only, decide within #1273"*).

Before every action in a session where `.gzkit/mx.json` exists, confirm the
hangar is open. While the condition is on:

- `gate5_invariants` remain **fail-closed**. Gate 5 is never advisory.
- **Both enforcement surfaces honor the marker (GHI #843).** Governance is enforced on two
  surfaces, and the hangar reaches both: `gz validate` scopes plus the `gz check` step layer,
  and the pre-commit guards (`gzkit.hooks.guards`). A demoted pre-commit finding is still
  printed, followed by an `[MX advisory]` line — advisory means non-grounding, never discarded.
- **Demotion never reaches an integrity guard, on either surface.** `ledger` and
  `gate5-attestation` are `GATE5_INVARIANTS` members, so a hand-edit of `.gzkit/ledger.jsonl`
  and an unattested OBPI-completion commit are refused *inside* the hangar exactly as outside
  it. The hangar is therefore not the route out of a mis-ordered ledger; that route is the
  append-only corrective-action primitive, `gz ledger correct` (GHI #611), never a demoted guard.
- The MX awareness hook fires every turn to remind the agent of the open state.

### Opting a guard into the floor — two mechanisms, not interchangeable

A guard inherits demotion by default. There are exactly **two** ways to survive an open hangar, and `gzkit.mx.checkpoint.resolve` is the whole decision:

- **By NAME** — membership in `GATE5_INVARIANTS` (`src/gzkit/mx/invariants.py`). Pins CRITICAL in and out of the hangar (Boundary Invariant #3). This is a **one-way door**, and it is **forbidden when the guard is a narrower proxy for the floor concern** — ADR-0.0.74 § Consequences/Negative #7: *"it MUST NEVER bind a narrower proxy entrypoint and call the claim proved."*
- **By LEVEL** — emit `CRITICAL`. Reversible, leaves `GATE5_INVARIANTS` untouched. This is the route for a guard that must never demote but is not itself a Gate-5 invariant.

**Default to LEVEL.** Reach for NAME only when the guard enforces the floor concern *in full*, not a checkable slice of it. Worked precedent: `84519da5` (GHI #852) pinned the authorship guard by LEVEL rather than registering it as `operator-pii`, because an email-suffix check on the git identity does not cover the whole operator-PII prohibition — which also spans trailers, file content, attestation text, and the ledger.

Floor-pinned by LEVEL today: `post-authoring-src-commits` (the Stage-2 production-code fence), `enforcement-floor`, the `authorship` scope and `Authorship policy` step (the `84519da5` precedent above), and `forbid-pytest` (operator ruling 2026-10-25, verbatim: *"never, ever, ever turn this off: "the pytest ban""*; the safe-mode alarm switch never wraps its hook), and the fast static checks — the `Lint` and `Complexity ceiling` steps and the `complexity_ceiling`, `bullet_retention`, `surface_weight` and `pointer_anchors` scopes (operator, 2026-10-27, *"somebody sweeps up the shop floor every night"*; the alarm switch never wraps their hooks, and a whole-tree `gz lint` runs at every push). The Stage-2 fence's pin was ruled permanent by the operator 2026-08-22 — an open hangar never demotes it (GHI #855).

**On the validate surface, an unregistered scope name resolves CRITICAL, not advisory** — a name nothing declares is a name nothing vouched for (`84519da5`). `checkpoint.resolve` keeps no registry and routes the level its caller emits; on the pre-commit surface a guard with no `_GUARD_META` entry never runs.

**This clause carries a mechanical witness — it is not authoring discipline.**
Demotion is decided in `gzkit.mx.checkpoint.resolve` / `gzkit.mx.disposition`,
and asserted by `tests/mx/test_checkpoint.py`, `test_disposition.py`,
`test_gate5_invariants.py`, `test_check_step_checkpoint_seam.py`, plus the live
un-forced negative controls in `test_gate5_invariants_live_nc.py`
(OBPI-0.0.74-17, REQ-0.0.74-20-03). Both directions are pinned: every
`gate5_invariants` member stays fatal *under* the marker, and stays fatal
*outside* it, so the carve-out cannot silently invert. A new guard inherits
demotion by default and must opt into the floor explicitly.

### Out of service: one state, the alarm test, a return to service package

Ruled 2026-11-03 (`docs/governance/safe-mode-doctrine.md` § Out of service and the four levels):
the condition on is **out of service**, one state; hangar and drydock are synonyms. Work done with
every alarm on is line work, a direct GHI fix included; work that must lower an alarm, or changes
a control or its standard, is out of service. Every opening has a return to service package, and
**return to service** is the operator's act at its close, apart from each order's Gate 5. With the
governors off the work still takes care: running past a disabled limit is a deliberate act of
diagnosis or test, noted as such. **(Advisory until GHI #1303 and #1304 land:** `gz mx enter`
still takes `--level` and asks for no package.**)**

### Safe mode: ceremony suspended under a contract

`gz mx enter --level drydock --contract <path>` opens the same marker in safe mode (GHI #1244).
The marker's `level` (hangar or drydock; an older marker's `mode` reads as its alias) and `contract` fields, and the `mx_session_opened` event that binds them,
say which mode is open; the awareness banner names it every turn.

- **What safe mode suspends:** the operator-only initiation of OBPI work and the brief
  ceremony, as the named contract declares. The operator's word at entry is the initiation.
- **What still binds:** `gate5_invariants`, the ledger written only through `gz` verbs,
  operator PII, the secret scan, no removal of a control, and the PRIME DIRECTIVE's
  trackability (below), and lint with the fast static checks. Every other guard drops to
  advisory, and every slow alarm hook is off, while the condition is on, as in the hangar: `gzkit.mx.checkpoint.hangar_demotes`
  is true under either mode, and the pipeline gate honors the marker (R6, 2026-10-17);
  `gz mx exit` re-runs every guard at full strength.
- **What it records:** every act is one commit with its `Task:` trailer, no long check per
  act (the slow alarms are off, `gzkit.mx.alarms`; ruling 2026-10-25), lint debt swept by the act that lints it (2026-10-27), what it leaves broken on the
  contract's list of discrepancies, and the contract's passage log carries bytes or counts before
  and after.
- **The contract is pinned** (operator ruling 2026-10-18, *"Hash at entry + amend event"*):
  `mx_session_opened` carries the contract's SHA-256 and the bodies of its § What is
  suspended and § Exit sections, and each commit that changes the contract while the session
  is open books `mx_contract_amended` with the new hash. Edits stay allowed; an edit never
  committed is not booked.
- **Who restores:** each repair order reattaches and reconfigures every safeguard it disconnected,
  rerouted or changed, to the prior or to the new stable state, before it closes; its list-of-discrepancies
  lines name it (ruling 2026-10-25).
- **How it ends:** `gz mx exit`, the same hard gate, then the contract's exit conditions.
- **Doctrine and template:** `docs/governance/safe-mode-doctrine.md` (the drydock and the
  repair order; safe mode is an occasional flip inside the standing maintenance mode) and
  `.gzkit/templates/safe_mode_contract.md` (the contract the skill reads before entry).

Witness: `tests/mx/test_checkpoint.py::TestSafeMode`, `tests/commands/test_mx_enter.py::TestMxEnterSafeMode`,
`tests/hooks/test_mx_awareness.py`, `tests/mx/test_contract_pin.py`.

### The lease: expiry is booked and announced, never evicted

- The hangar runs the token block's lifecycle; its lease is the `mx-session` lock's TTL
  (`lock_manager.DEFAULT_LOCK_TTL_MINUTES`), one definition for both.
- Past the lease nothing is evicted (operator ruling 2026-10-18, verbatim *"at worst, we book
  a status at least expiry and notify"*): session start books one `mx_session_lease_expired`
  and announces it, and the lock reaper leaves an open hangar's lock in place.
- Advisory debt ages per contract (operator ruling 2026-10-18, *"Per contract (Rec.)"*, GHI #1258):
  from the first safe-mode `mx_session_opened` under the open session's contract, so closing and
  reopening under one contract renews the lease but carries the debt on until handback. A
  session without a contract ages alone.
- Renew the lease in place with `gz mx renew` (operator ruling 2026-10-20, verbatim *"Make renewal
  lease-only, as the 10-18 ruling already implies."*, GHI #1261): it claims the `mx-session` lock
  afresh and books `mx_session_lease_renewed`; no guard runs, the marker stays, debt keeps aging.
  The lease guard measures from the last renewal. Exit is for the drydock's end, never a renewal.
- Neither the lease nor the advisory debt blocks `gz mx exit`. Exit holds the marker, marked
  `exiting`, through its full-strength re-run, so the session it closes is never dangling.
- What grounds: a dangling session (ledger open, marker missing) outside the hangar, and more
  than one open session.

Witness: `gz validate --mx-hardening` (a `gz check` step, `NC:mx-hardening`),
`tests/mx/test_lease.py`, `tests/governance/test_mx_hardening_audit.py`.

### PRIME DIRECTIVE binds the entire session

**Safe mode differs (ruling 2026-10-25):** a remodel leaves things partially broken, so *fix
immediately* waits for the exit and *every defect trackable* binds through the contract's punch
list. The exception is lint and fast-static debt, which each act sweeps (operator, 2026-10-27,
*"somebody sweeps up the shop floor every night"*). The hangar below is unchanged.

Guards dropping to advisory means the operator can repair the surfaces the
guards protect — it does NOT mean ownership relaxes. In the hangar:

- Fix what you know **AND** what you find.
- "Not my work" / "out of scope" stays **forbidden in the bay**.
- Defects visible in flight are still defects; advisory guards are not a
  license to defer them.

### Operate the skill, not the shell

The operator uses the `gz-mx` skill; the skill invokes `gz mx`; agents do not
shell out to `gz mx enter` or `gz mx exit` directly.

## Do Not

- Do not invoke `gz mx enter` or `gz mx exit` directly in a shell step — use the `gz-mx` skill
- Do not treat advisory guards as license to defer visible defects
- Do not conflate "guard dropped to advisory" with "PRIME DIRECTIVE suspended"
- Do not exit the hangar while any line graded *blocks return to service* stays open; every other open discrepancy, accepted departure and deferred action passes to its holder in the handback (`docs/governance/safe-mode-doctrine.md`, the handback's transfer of custody)

## Related

- `gz-mx` skill — the operator's interface (`.gzkit/skills/gz-mx/SKILL.md`)
- MX awareness hook — per-turn reminder (`.claude/hooks/mx-awareness.py`)
- Parent ADR — `docs/design/adr/foundation/ADR-0.0.74-mx-mode-maintenance-hangar/`
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall