docs: add safe Lavish repair playbook

.agents/skills/bootstrap-diagnostics/SKILL.md

@@ -2,7 +2,7 @@
 name: bootstrap-diagnostics
 description: >-
   Agent-only handling playbook for session-start bootstrap diagnostics.
-  Use whenever the session-start digest's bootstrap section prints any diagnostic or capability line - MISSING, MISSING_MANUAL, BACKEND_INVALID, NEEDS_GH_AUTH, TANGLE, CREW_HARNESS_OVERRIDE, CREW_DISPATCH, FLEET_SYNC, SECONDMATE_SYNC, SECONDMATE_LIVENESS, TASKS_AXI, NUDGE_SECONDMATES, or FMX - or when a standalone bin/fm-bootstrap.sh run prints one.
+  Use whenever the session-start digest's bootstrap section prints any diagnostic or capability line - MISSING, MISSING_MANUAL, BACKEND_INVALID, ACCOUNT_ROUTING, NEEDS_GH_AUTH, TANGLE, CREW_HARNESS_OVERRIDE, CREW_DISPATCH, FLEET_SYNC, SECONDMATE_SYNC, SECONDMATE_LIVENESS, TASKS_AXI, NUDGE_SECONDMATES, REPORT_RETENTION, or FMX - or when a standalone bin/fm-bootstrap.sh run prints one.
   A silent bootstrap section means all good and needs no skill load.
 user-invocable: false
 metadata:
@@ -22,6 +22,7 @@ The inline rules in `AGENTS.md` section 3 still bind: detect, then consent, then
   For `quota-axi`, bootstrap requires it because crew-dispatch `quota-balanced` may call it; `bin/fm-dispatch-select.sh` still degrades at runtime when quota data is unavailable.
 - `MISSING_MANUAL: <tool> (instructions: <url>)` - tell the captain why the tool is required and give them the printed instructions URL, but do not pass the tool to `bin/fm-bootstrap.sh install`; wait for the captain to complete the manual installation, then rerun session start to confirm the dependency is present.
 - `BACKEND_INVALID: <name> (known: <names>)` - the resolved runtime backend has no verified dependency or lifecycle contract, so do not dispatch work until the invalid `FM_BACKEND` or `config/backend` value is corrected to one of the listed backends.
+- `ACCOUNT_ROUTING: invalid routing policy - <reason>` - the environment or `config/account-routing-mode` cannot resolve to exactly one of `off`, `observe`, or `enforce`; fix the reported source before dispatch because managed spawns will fail closed on the same policy error.
 - `NEEDS_GH_AUTH` - ask the captain to run `! gh auth login` (interactive; you cannot run it for them).
 - `TANGLE: <remediation>` - the primary checkout is stranded on a feature branch instead of its default branch; `AGENTS.md` section 8 explains why this guard exists and what it protects.
   The work is safe on that branch ref; restore the primary to its default branch with the printed `git -C <root> checkout <default>`, then re-validate that branch in a proper worktree.
@@ -36,14 +37,16 @@ The inline rules in `AGENTS.md` section 3 still bind: detect, then consent, then
 - `FLEET_SYNC: <repo>: STUCK: on <state>, N commits behind <base> - needs attention` - the clone is dirty, on a non-default branch, detached with unique commits, or diverged, so the sync left it untouched (never forcing or discarding); it will keep falling behind until you look.
   A loud STUCK, especially a growing N across bootstraps, means that clone needs hands-on attention; dispatch a crewmate or resolve it before it strands work.
 - `SECONDMATE_SYNC: secondmate <id>: skipped: <reason>` - the local-HEAD secondmate sync left a live secondmate home on its existing checkout because the home was dirty, diverged, unsafe, on the wrong branch, missing the primary target commit, or otherwise not fast-forwardable, or because inheritable-config propagation failed; bootstrap continued, but inspect the reason because the secondmate's tracked instructions or inherited settings may be stale after a primary update.
-- `SECONDMATE_LIVENESS: secondmate <id>: already-live|respawned|skipped: <reason>|respawn failed: <reason>` - the session-start liveness sweep checked a live secondmate's recorded endpoint for a real agent process.
-  Treat `already-live` and `respawned` as handled; investigate `skipped` or `respawn failed` because that secondmate is not guaranteed live.
+- `SECONDMATE_LIVENESS: secondmate <id>: <outcome>` - the session-start liveness sweep checked a live secondmate's recorded endpoint for a real agent process.
+  Treat `already-live`, `respawned`, and `rollback reconciled and respawned` as handled; investigate `skipped` or `respawn failed`, and load `secondmate-provisioning` for any `respawn deferred` outcome because its "Recovery" section owns the required routing decision.
 - `TASKS_AXI: available` - a default-backend capability fact, not a problem; record it silently and use `AGENTS.md` section 10 for backlog mutations.
   It prints only when `config/backlog-backend` is absent or set to `tasks-axi` and the shared compatibility probe passes (`docs/configuration.md` "Backlog backend").
   If the backend is not opted out and `tasks-axi` is missing or incompatible, bootstrap reports the `MISSING: tasks-axi` line but firstmate still hand-edits routine backlog updates and never blocks work.
   If `config/backlog-backend=manual`, firstmate hand-edits routine backlog updates and bootstrap does not suggest installing `tasks-axi`.
 - `NUDGE_SECONDMATES: fm-<id>...` - the secondmate sweep fast-forwarded one or more *running* secondmate homes to firstmate's current version and their instruction surface (`AGENTS.md`, `bin/`, or `.agents/skills/`) actually changed; send a one-line re-read nudge with `FM_HOME=<this-firstmate-home> bin/fm-send.sh <id> 'firstmate was updated to the latest - please re-read your AGENTS.md to pick up the new instructions.'` unless `FM_HOME` is already set to the active firstmate home.
   This mirrors `/updatefirstmate`'s `nudge-secondmates:` report: it is a gentle steer, never an interruption, and the fast-forward already landed safely.
   A secondmate that was skipped, already current, or whose advance changed no instructions is not listed and must not be disturbed.
+- `REPORT_RETENTION: unavailable: <reason>` - the machine-global report-retention LaunchAgent is absent, stale, unloaded, or has not reported a recent successful prune, so opportunistic bounded pruning remains available but post-minimum-age cleanup is not guaranteed to run while Firstmate is idle.
+  Surface the failure, wait for the captain's consent, then run `bin/fm-bootstrap.sh install report-retention`; never install or activate it without that consent.
 - `FMX: X mode on ...` / `FMX: X mode off ...` - bootstrap confirmed or removed the local X-mode poll artifacts (`docs/configuration.md` "X mode (.env)").
   Only when a running watcher needs the cadence transition applied immediately, restart the home-scoped watcher through the emitted harness supervision protocol; bootstrap deliberately never restarts the watcher itself.

.agents/skills/crew-steering/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: crew-steering
+description: >-
+  Agent-only practice for holding crewmates to the captain's bar.
+  Use before writing or materially revising a crewmate or secondmate brief and before live-steering a crewmate.
+  Applies ownership, evidence, premise-checking, quality, goal-fidelity, and directness without duplicating their authoritative contracts.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Crewmate steering
+
+Steer every crewmate to the same bar the captain holds firstmate to.
+Apply this skill both while writing the initial brief and while live-steering work already in flight.
+Keep each brief or steer proportional: name the outcome, constraint, evidence, and next action, then stop.
+
+## Apply it in both modes
+
+When writing a brief, make the expected result, authority boundaries, verification, and definition of done unmistakable.
+When live-steering, correct the smallest load-bearing mistake early and require the crewmate to carry the fix through implementation and proof.
+In both modes, preserve the captain's actual goal and use the existing owner for detail instead of copying its contract.
+
+## 1. Demand ownership
+
+Require the crewmate to solve and implement the task: it never stops solely because work is hard or failing, it preserves mandated safety `blocked` stops such as unsafe or non-isolated worktree placement, and it exhausts its capability before following the solve-first escalation bar owned by `AGENTS.md` section 9.
+
+## 2. Reject vague or optimistic claims
+
+Treat `almost there` as unfinished, require real evidence because work is not done until proven, and review adversarially rather than rubber-stamping; `AGENTS.md` section 9 owns truthful outcome reporting and section 7's active delivery gate owns proof.
+
+## 3. Fact-check the load-bearing premise
+
+Cheaply test the crewmate's one load-bearing assumption before it acts, rejecting a shallow-false premise without overcorrecting; `operating-fundamentals` section 7 owns the premise-check rule.
+
+## 4. Prefer quality and robustness
+
+Apply the captain's technical-decision bias and reject preserving a leaky component merely to save development cost or sunk work.
+
+## 5. Preserve goal fidelity
+
+Reject any quiet reframing of the task into a smaller win; prime directive 5 and `AGENTS.md` section 9 own the fixed-goal guardrail.
+
+## 6. Be direct and early
+
+Write specific, un-bloated briefs and steers, and correct a wrong path before it is built; `AGENTS.md` section 11 owns the brief contract.
+
+## Finish the steer
+
+End with the concrete result the crewmate must produce, the evidence that will prove it, and the next action it should take.
+Do not add motivational padding, duplicate background, or a second copy of an existing procedure.

.agents/skills/eks-usage/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: eks-usage
+description: >-
+  Agent-only operating guide for safe Amazon EKS context verification, kubeconfig setup, authentication diagnosis, and connectivity retries.
+  Use before running kubectl or EKS commands, when an EKS IAM, authenticator, Unauthorized, Forbidden, TLS, i/o, or connectivity error appears, or when the active cluster or context is uncertain.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# EKS usage
+
+This skill owns generic EKS client access and diagnosis, not permission to change a cluster or deploy an application.
+Project runbooks and deployment skills remain authoritative for the intended cluster, lane, namespace, and allowed mutations.
+
+## During deployments
+
+Before contacting the cluster control plane during a deploy, read the project's deployment map or runbook and confirm that direct cluster access belongs to the documented lane.
+Most managed production deploys use CI, declarative synchronization, or a platform release lane and do not contact the raw cluster API.
+If transient TLS, i/o, DNS, or network failures repeat after kubeconfig refresh during a deploy, treat them as a likely wrong-path signal, stop direct cluster retries, and switch to the documented deploy lane.
+Reserve the bounded retry procedure below for a confirmed correct direct-access path, because a wrong deploy path is resolved by switching lanes rather than by retrying or escalating it as a connectivity blocker.
+
+## Establish identity and context
+
+1. Run `aws sts get-caller-identity` and confirm the expected AWS account and principal without exposing credentials.
+2. Run `kubectl config current-context` and `kubectl config view --minify` to inspect the active cluster, user, and namespace or its default.
+3. Before any mutating command, state the intended cluster, context, and namespace and stop if they do not match or cannot be proved.
+4. Treat a context change as safety-significant, because `aws eks update-kubeconfig` sets the written file's current context to the selected cluster.
+5. Bind mutations to the verified context and namespace instead of relying on ambient defaults.
+
+## Understand `update-kubeconfig`
+
+`aws eks update-kubeconfig --name <cluster> --region <region>` retrieves the cluster endpoint and certificate authority from the EKS control plane and creates or merges kubeconfig entries for the cluster, context, and AWS-backed user.
+The AWS identity used for that metadata lookup must be allowed to describe the cluster, while any configured authentication role governs later `kubectl` token generation.
+It writes the explicitly selected kubeconfig path, otherwise the first path in `KUBECONFIG`, otherwise the default kubeconfig file.
+It replaces an existing entry for the same EKS cluster in that file and makes the generated context current.
+The user entry invokes AWS to obtain short-lived authentication when `kubectl` runs; the file does not contain a reusable static Kubernetes bearer token.
+Use dry-run when the destination or merge effect is uncertain, and consult `aws eks update-kubeconfig help` for current flags and precedence.
+Refreshing kubeconfig fixes stale endpoint, certificate, or generated-entry state, but it cannot grant IAM, EKS access-entry, Kubernetes RBAC, or network access.
+
+## Classify the exact failure
+
+| Signal | Layer | Response |
+| --- | --- | --- |
+| `AccessDeniedException` from EKS describe or kubeconfig update | AWS IAM before the Kubernetes API | Confirm the AWS identity and intended role, then escalate an actual missing IAM grant instead of debugging the network. |
+| `ExpiredToken`, `InvalidClientTokenId`, or missing credentials | Local AWS credential chain before the Kubernetes request | Refresh or select the intended profile or role, then re-run the identity check without printing a token. |
+| A generic exec-plugin failure | Local exec invocation or a wrapped nested failure | Classify the nested error first; check for a missing AWS executable, malformed exec stanza, or unsupported exec `apiVersion`, and refresh credentials only when the nested error identifies a credential failure. |
+| `Unauthorized` or a server request for credentials from `kubectl` | Kubernetes API authentication after reaching the endpoint | Confirm the generated user role and the cluster's authorized IAM principal or access entry. |
+| `Forbidden` from `kubectl` | Kubernetes authorization after successful authentication | Check the verb, resource, and namespace with `kubectl auth can-i`, then escalate the RBAC change if it is outside authority. |
+| `dial tcp`, `i/o timeout`, `TLS handshake timeout`, `no route`, or `connection refused` | DNS, route, proxy, firewall, or API-endpoint reachability | Follow the bounded connectivity retry path below rather than requesting IAM. |
+| `x509` or certificate validation failure | Kubeconfig CA, clock, or TLS-intercepting proxy | Refresh kubeconfig and inspect clock and proxy state, but never disable certificate verification as a workaround. |
+
+Messages such as `couldn't get current server API group list` are wrappers, so classify the nested final error rather than the wrapper.
+A successful `aws eks describe-cluster` proves AWS control-plane authorization and cluster metadata access, not Kubernetes endpoint reachability or workload authorization.
+A certificate-verified HTTPS response from the cluster endpoint, including HTTP 401, proves DNS, routing, and TLS reached the API server, but it does not prove `kubectl` authentication.
+
+## Troubleshoot in cheapest-first order
+
+1. Capture the exact command and full error, then verify AWS identity, region, `KUBECONFIG`, current context, cluster, and namespace.
+2. For an isolated TLS or transport timeout, retry the same non-mutating probe once after a short pause; a single transient timeout is never a blocker.
+3. Confirm the intended target, refresh kubeconfig, recheck the now-current context, and retry a harmless version or namespace read once more after a short bounded backoff.
+4. Use EKS describe to confirm that the cluster is active and inspect its endpoint-access mode without changing it.
+5. If transport still fails, test DNS and HTTPS reachability to the configured endpoint and inspect VPN, proxy, firewall, private-endpoint routing, and allowed-source requirements.
+6. If the endpoint is reachable, return to the IAM, token, access-entry, and RBAC classification instead of continuing network changes.
+7. Use `aws eks`, `aws sts`, `aws eks get-token`, `kubectl config`, `kubectl auth`, and `kubectl get --help` for current flags rather than copying stale invocations from old incidents.
+
+## Retry and escalation line
+
+Continue when any bounded retry succeeds, and record the transient only when it affects operational evidence or repeats.
+Apply the three-probe budget only to transient connectivity failures such as TLS handshake timeout, i/o timeout, or transient DNS or network errors; escalate when identity and context checks, kubeconfig refresh, and three total non-mutating attempts still fail.
+Correct an expired or misselected local credential or role first, because those caller-controlled authentication failures do not require escalation.
+Escalate immediately when the intended target cannot be proved or classification confirms an owner-controlled AWS IAM, Kubernetes authentication, EKS access-entry, RBAC, or certificate failure, without spending the connectivity retry budget.
+Also escalate persistent evidence of a non-active control plane, private-route or allowlist boundary, or owner-controlled proxy fault.
+Include the redacted exact commands and errors, timestamps and attempt count, current context and namespace, AWS identity and region, cluster status and endpoint-access mode, and DNS or HTTPS observations.
+Never self-grant IAM or RBAC, edit access entries, expose a private endpoint, widen endpoint CIDRs or security groups, disable TLS verification, or mutate an uncertain context merely to get past an access failure.

.agents/skills/firstmate-coding-guidelines/SKILL.md

@@ -12,6 +12,7 @@ metadata:
 # firstmate-coding-guidelines
 
 Load this before changing firstmate's shared, tracked material, as defined by `AGENTS.md` section 1.
+Load `skill-authoring-standard` before authoring or substantially editing a skill; this skill remains the owner of placement and ownership rules specific to firstmate changes.
 It exists because `AGENTS.md` grew from 585 to 958 lines between its last two restructures, entirely from conditional detail added inline instead of routed to its right home.
 Applying the rules below on every change is what keeps that from happening again.
 
@@ -23,6 +24,7 @@ Before writing a new fact anywhere in this repo, ask where it belongs, in this o
    If yes: `AGENTS.md`, inline.
 2. Does the agent need it only in a nameable situation - a spawn, a recovery, a specific wake type, a specific lifecycle step?
    If yes: an agent-only skill under `.agents/skills/`, plus a one-line trigger pointer left inline in `AGENTS.md` (usually section 13).
+   For the load-before-doing versus be-aware boundary, use the tie-break owned by `AGENTS.md` section 6's knowledge-routing table.
 3. Is it human/reference detail - a wire format, a verification record, a mechanism narrative, an incident writeup?
    If yes: `docs/`.
 4. Is it mechanics - exact flags, exact commands, exact paths?