@zerwiz/ymir 0.1.16 → 0.1.18

package/assets/reference/skills/project-management/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: project-management
+description: >-
+  Agent-only procedure for Firstmate project management.
+  Use before adding, creating, removing, or initializing a project.
+  Cloning or registering a project is add intake and uses the same trigger.
+  Owns project add, create, clone, remove, initialization, registry, delivery-mode, autonomy, and outward-consent decisions.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# project-management
+
+Use this procedure before adding, creating, removing, or initializing a project.
+Cloning or registering a project is add intake and uses the same trigger.
+This skill is the single owner of Firstmate's project-management procedure.
+It does not replace `secondmate-provisioning`, which owns project clones inside persistent secondmate homes.
+
+## Preconditions and registry
+
+Projects live flat under `projects/`, and `data/projects.md` is the private fleet registry.
+Use the registry format and parser contract owned by the header of `bin/fm-project-mode.sh`.
+Keep each registry description useful for identifying the project, but keep delivery posture, captain-private state, and detailed project knowledge in their existing designated homes.
+Do not turn the registry into project documentation.
+
+Before adding, cloning, creating, or registering any project in the main home, inspect the authoritative `data/secondmates.md` routing table and judge every existing natural-language `scope:` against the proposed project or domain.
+Apply `AGENTS.md` section 7's authoritative secondmate routing rules; if an existing scope owns that domain, route the new-project operation or work there instead of creating or registering a duplicate main-home clone.
+Absence from the main `data/projects.md` registry is never evidence that no second mate owns the domain.
+If the owning second mate cannot accept the route, report that concrete blocker or obtain an explicit captain redirection rather than silently duplicating the project in the main home.
+
+Resolve the project name, destination, delivery posture, and autonomy posture before changing local or remote state.
+Keep a newly added clone and its registry entry consistent, and roll back only artifacts created by the incomplete operation when a later initialization step fails and that rollback is safe.
+Do not overwrite or repurpose an existing path.
+
+## Delivery posture
+
+The registry records the project's standing posture, which is the captain's default for the work rather than any task's answer; `AGENTS.md` section 7 owns how each task's concrete mode and yolo are resolved at intake and passed explicitly to the brief, the spawn, and any promotion.
+Choose that posture when adding or creating the project:
+
+- `no-mistakes` runs the full validation pipeline before a PR.
+- `direct-PR` pushes and opens a PR without the no-mistakes pipeline.
+- `local-only` has no required remote or PR and lands only through the approved local fast-forward path.
+- `no-mistakes-prod-only` is a conditional policy rather than one flat mode: genuinely internal-only tooling, automation, contributor or operator process, and release or submission work ships `direct-PR`, while product-facing, mixed, and uncertain work ships `no-mistakes`.
+
+`no-mistakes-prod-only` is the default for a newly added or created remote-backed project when the captain specifies nothing, and a project with no remote defaults to `local-only`.
+State that resolved default while confirming the source, local name, and posture instead of asking the captain to choose from scratch, and record a flat mode instead whenever they ask for one.
+Existing registry entries keep the meaning they already have and are never migrated or reinterpreted, so a legacy entry with no bracket stays `no-mistakes`.
+Registering a conditional policy is a one-time choice and never requires classifying any change; the per-task surface classification happens at each task's intake, and internal-only is never inferred from file location or project name.
+
+The optional `+yolo` posture changes merge authority only and does not change the delivery mode.
+Default it off for every project and every posture, and enable it only on the captain's explicit instruction.
+`AGENTS.md` section 7 owns the merge-authority contract.
+
+## Add or clone an existing project
+
+Confirm the source URL, local project name, delivery posture, and autonomy posture, stating the resolved default for each rather than asking the captain to invent one.
+Clone into `projects/<name>` and add the registry entry only after the destination is known to be unused.
+A `no-mistakes` or `no-mistakes-prod-only` project must have an `origin` remote and must complete the initialization procedure below, because a conditional policy's product-facing work runs the pipeline while its internal-only work still takes the direct PR.
+A `direct-PR` project needs an `origin` remote but skips no-mistakes initialization.
+A `local-only` project may have no remote and skips no-mistakes initialization.
+
+## Create a project
+
+Creating a GitHub repository is outward-facing.
+Before making that remote change, propose the repository name, owner or organization, visibility, and delivery posture, defaulting visibility to private and the posture to `no-mistakes-prod-only`, then obtain the captain's explicit consent for those exact values; a stated default never replaces that consent.
+Use `gh-axi` for the approved GitHub operation and consult its current help rather than relying on remembered flags.
+After remote creation succeeds, clone it locally, add the registry entry, and initialize it according to its delivery posture.
+
+For a purely `local-only` project, create a local Git repository under its unused `projects/<name>` path, add the registry entry, and make no GitHub call.
+The captain's request to create that local project authorizes this local initialization, but it does not authorize an unmentioned remote repository.
+
+## Initialize
+
+Run no-mistakes initialization only for `no-mistakes` and `no-mistakes-prod-only` projects:
+
+```sh
+cd projects/<name> && no-mistakes init && no-mistakes doctor
+```
+
+Initialization configures the local gate and does not vendor a no-mistakes skill into the project.
+Do not create a commit merely because initialization ran.
+If doctor reports an environment, authentication, or daemon problem, resolve that blocker before dispatching work and never restart the shared daemon from a project operation.
+
+## Remove
+
+Project removal is destructive.
+First obtain the captain's explicit removal decision, then inspect the current digest and authoritative repositories for in-flight or queued work, registered secondmate clones, linked worktrees, dirty files, unpushed commits, and any other unlanded work.
+If any dependency or unlanded work exists, stop and report it before changing anything.
+Never issue a raw removal command from Firstmate.
+Once that preflight confirms none of the above and the captain's approval is concrete, AGENTS.md hard rule 1's captain-approved project operation exception authorizes firstmate to remove the clone directly and update its registry entry to match.
+When a clone has already been removed through an approved removal, or the registry is provably stale because no clone exists, remove its registry line so navigation matches reality.

package/assets/reference/skills/quota-array-dispatch/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: quota-array-dispatch
+description: >-
+  Agent-only decision procedure for resolving a matched crew-dispatch profile
+  array from quota-axi's default TOON, ranking by spendPriority after three
+  orthogonal gates.
+  Load when a dispatch rule or default resolves to more than one profile candidate.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# quota-array-dispatch
+
+This skill is the single owner of the completion-aware profile-array selection procedure.
+`AGENTS.md` section 4 owns the always-loaded intake boundary, load trigger, malformed-config refusal, every-candidate accounting, and strongest-reasoning/tie safety rules.
+`harness-adapters` owns harness verification, model/provider discovery, and effort fallback.
+`quota-axi` remains data-only: it publishes `spendPriority` as a comparable scalar and never recommends, selects, ranks, or infers a route.
+Do not add a daemon, opaque composite score, routing wrapper, hard-coded model-specific policy, or producer-side route recommendation.
+Deterministic shell owns only schema, configuration, and version validation plus concrete spawn safeguards; every model-to-provider, provider-to-credential, and quota-applicability relation is yours to establish transparently and to show your evidence for.
+
+## Worker-side quota helper
+
+The canonical shell helper for a worker that has already performed its model-selection reasoning and now needs to pick the first viable candidate is `bin/fm-quota-choose.sh`.
+Pass it the intake's already-captured default TOON or permitted JSON fallback through stdin or `--snapshot`; it never takes another quota snapshot, so it selects from the same quota state as the intake.
+Pass each candidate as `harness:model`, with earlier candidates preferred.
+The helper maps each harness to its primary provider family and applies the provider-wide scopes plus the exact model or product scopes for the model.
+An `exhausted_now` runway vetoes the candidate.
+The helper selects a candidate only when its applicable quota has a known `effectivePercentRemaining` greater than zero.
+This is an optional narrow helper with a known limitation: it maps each harness to one primary provider family only, so a candidate whose established provider differs from that primary family is checked against the wrong quota row.
+Authoritative multi-provider routing - including provider discovery from the harness catalog and quota matching by that explicit provider - stays owned by this skill's intake procedure above and AGENTS.md section 4, not by the helper.
+Use it only when the brief already fixed the candidate order and every candidate's provider is the harness's primary family.
+It does not replace the reasoning-class, runway-feasibility, or authentication gates above.
+Firstmate can optionally arm `bin/fm-procevent-quota.sh` for a recurring mid-task check that wakes when the tracked provider drops below its configured threshold or its runway becomes `exhausted_now`.
+
+## Read the default TOON
+
+Start each intake by running `quota-axi` once with no `--json`, and reuse that TOON for every candidate.
+Post-consolidation quota-axi (the floor owned by `bin/fm-quota-axi-lib.sh`) puts `spendPriority` in the default `quota[]` block beside `effectivePercentRemaining`, `runway`, `confidence`, `limitedBy`, and `resetsAt`.
+Sparse `exhaustion[]` carries finite-runway seconds only for `projected_exhaustion` and `exhausted_now`.
+Sparse `attention[]` names auth, stale, and unmeasurable facts.
+`spendPriority` is THE quota-perspective ranker.
+It already computes the economics that older instructions reconstructed by hand from headroom, pace, reserve, and window-id lists; do not recompute those.
+Do not read `--json` on the normal path, and do not reach for `--full` to rebuild that economics.
+
+After reading the TOON, fall back to one `quota-axi --json` call only when that TOON is genuinely ambiguous for the decision, or when the installed quota-axi is somehow below the floor so its TOON lacks `spendPriority`.
+Ambiguous means a candidate's `spendPriority` is the literal `unknown` or unmeasurable, a real tie still needs extra evidence, or a candidate's eligibility is unclear from `quota[]` plus `attention[]`.
+The fallback therefore has an explicit TOON-then-JSON call sequence; reuse its JSON result and do not take any further quota snapshots.
+Below-floor is rare: bootstrap enforces `FM_QUOTA_AXI_MIN` and normally reports `MISSING` before dispatch; if an intake somehow reaches an older build whose TOON lacks `spendPriority`, use the defensive `--json` fallback rather than treating the missing scalar as healthy.
+`--json` is a defensive belt, not a habit; never reach for it because it feels more complete.
+Read `quota-axi auth --json` only when a candidate's credential surface is in question.
+
+For each candidate, preserve explicit `harness`, `model`, and `provider`; `harness-adapters` owns identity, and model/provider never infer harness.
+
+## Three gates, then spendPriority
+
+Apply the three cheap orthogonal gates first.
+`spendPriority` ranks only among candidates that pass all three.
+It cannot override a hard-gate failure, and it is never hidden inside a new composite score.
+
+### 1. Eligibility
+
+Deterministic shell must never map a model to a provider, a provider to a credential store, or a name prefix to a family.
+You establish those relations yourself, in the open, from the candidate's own authoritative catalog (`harness-adapters` owns the per-harness discovery surface) plus the one intake snapshot.
+
+Confirm the catalog lists the candidate's model and record the provider family it reports.
+A model the catalog does not list is concrete contradictory evidence: block that candidate and quote the catalog result.
+Apply quota at the granularity the vendor actually supplies.
+A provider-level or `all_models`/`all_products` scope bounds every model you established in that family, including one with no window of its own.
+A named-model or named-product scope is an additional bound for that model alone.
+Match the candidate to its `quota[]` row by that established provider and scope; a stale, auth-required, or unmeasurable scope is named in `attention[]` instead of a fabricated number.
+
+A candidate authenticates through its own tuple's surface; another harness's CLI can never gate it, and `harness=pi` with `model=xai/grok-*` is Pi using xAI rather than the standalone Grok CLI.
+`quota-axi auth --json` lists each provider's credential sources independently, so read the one source the candidate actually uses rather than collapsing a provider to a single status.
+A provider can carry a healthy source beside a missing or expired one; the unused source's state is not the candidate's state.
+A Pi-hosted family may authenticate through the vendor's own store with no `pi:`-prefixed source at all, which is normal and never evidence against the candidate.
+
+Uncertainty and ineligibility are different findings:
+
+- No model-level window, no matching auth source, an unmeasurable or `unknown` scope, or a surface quota-axi does not model at all is disclosed uncertainty.
+  Keep the candidate eligible, state the unknown, and prefer known viable evidence when otherwise comparable.
+- An expired credential is a short-lived session token the owning vendor renews on next use, not a sign-out.
+- Only concrete contradictory evidence blocks: an authoritative catalog proving the model unsupported, or proof that the credential the candidate actually selects is unusable.
+- Reserve login wording for that proven-unusable case, and name the harness, model, surface, and evidence.
+
+When a credential's local classification is the only thing standing between a candidate and a block, get ground truth before blocking.
+`bin/fm-vendor-auth-probe.sh` is the only approved vendor-credential probe; its `--help` owns the registered probes and mechanics.
+It takes no harness, model, or provider and returns a fact, not a route: only `authenticated` and `unauthenticated` are ground truth, while `indeterminate`, `timeout`, and `unavailable` establish nothing and must never be read as either outcome.
+Never launch a vendor CLI yourself, and never probe a credential store the candidate does not use.
+Grok prepaid `credits` are unrelated to paid-window headroom; never read them as exhaustion.
+
+Malformed configuration is an actionable error, not a candidate to rank around.
+
+### 2. Reasoning-class fit
+
+Keep only candidates that meet the required reasoning class for this task (a simple bug fix versus very-difficult design).
+Never use `spendPriority` or remaining quota to silently replace that class.
+When every remaining candidate is tight, dispatch inside the strongest-reasoning class if one of those candidates can proceed, or stop and report that the strongest-class choice cannot proceed rather than downgrading it to spend or conserve quota.
+
+### 3. Runway feasibility floor
+
+Known runway that will not last until the inspectable likely-completion horizon fails this gate, even when that candidate has the highest `spendPriority`.
+Read `runway` from the `quota[]` row: `through_reset` passes this generic feasibility floor because the window reaches its refill without exhausting; never compare its `resetsAt` with the completion horizon as though reset were an exhaustion deadline.
+`exhausted_now` is zero, and `projected_exhaustion` uses the matching `exhaustion[]` row's `usableRunwaySeconds`.
+A high `spendPriority` on a nearly empty window that will exhaust soon must not route into a mid-task stall.
+Unknown or unmeasurable runway stays eligible with disclosed uncertainty and is never assumed to pass.
+Do not invent a generic percentage floor, and honor an explicit captain floor for a candidate when one exists.
+
+## Rank by spendPriority
+
+Among candidates that pass all three gates, pick the highest known `spendPriority`.
+A higher known scalar is better: positive means paid allowance is on track to reach reset unused, `0` is exact utilization, and negative means overdrawn against the reset clock.
+Rank only from comparable known scalars.
+Never treat absent, `unknown`, or unmeasurable `spendPriority` as zero or as healthy; `0` means exact utilization, a different claim from unknown.
+An unknown `spendPriority` keeps the candidate eligible with disclosed uncertainty.
+Prefer known viable evidence when otherwise comparable.
+After the permitted TOON-to-JSON fallback, escalate to Firstmate instead of routing if no candidate can be ranked or runway uncertainty prevents proving the feasibility floor for any candidate that could be selected.
+Never resolve that terminal uncertainty by treating unknown as healthy or by choosing arbitrarily.
+Show the scalar or the literal `unknown` in the rationale; do not hide it in a score.
+
+Do not compare headroom against runway by hand.
+Do not use pace or signed reserve as a later tie-break layer.
+Do not read `aheadWindowIds`, `behindWindowIds`, `onPaceWindowIds`, `limitingWindowIds`, or other window-id lists to reconstruct what `spendPriority` already computed.
+
+Genuine ties: stop and report every tied candidate for captain choice.
+Do not select by array order, harness name, or another arbitrary identity ordering.
+Report duplicate concrete profiles as a configuration error.
+
+Account for every candidate visibly before selecting or escalating, naming its catalog evidence, provider relation, applicable quota and authentication facts, remaining uncertainty, fit and reasoning class, `spendPriority`, and runway-versus-horizon result.
+A blocked credential report must name `harness`, `model`, authentication surface, and concrete failure evidence; never emit a bare `Grok unauthenticated` statement.
+Never conclude with an unexplained "best quota" label.

package/assets/reference/skills/secondmate-provisioning/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: secondmate-provisioning
+description: >-
+  Agent-only reference for persistent secondmate setup and retirement.
+  Use when creating, seeding, validating, launching, recovering, handing backlog to, pushing inherited local material into, or retiring a secondmate home, or when editing data/secondmates.md.
+  Covers local leases, whole-home remote routes, transactional seeding, record intake for an existing or inherited domain, project clone restrictions, secondmate harness pins, inherited local-material push, idle charter, handoff helper, and teardown safety.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# secondmate-provisioning
+
+Use this reference before creating, seeding, validating, launching, handing backlog to, recovering, pushing inherited local material into, or retiring a persistent secondmate, and before editing `data/secondmates.md`.
+
+Keep the always-inline routing rules in `AGENTS.md` authoritative: route by natural-language `scope:`, local-only projects stay with the main firstmate, and secondmates are idle by default.
+
+## Routing table
+
+`data/secondmates.md` has one parser-compatible line per persistent second mate.
+A local route uses:
+
+```markdown
+- <id> - <one-sentence charter summary> (home: <absolute-home-path>; scope: <natural-language responsibility>; projects: <project-a>, <project-b>; added <date>)
+```
+
+A whole-home remote route uses:
+
+```markdown
+- <id> - <one-sentence charter summary> (host: <ssh-alias>; root: <absolute-remote-code-root>; home: <absolute-remote-home>; scope: <natural-language responsibility>; projects: <project-a>, <project-b>; added <date>)
+```
+
+Each registry entry stays concise and single-line: the summary is one sentence naming the durable charter, `scope:` is the natural-language intake responsibility, `projects:` is the non-exclusive clone list, and any extra prose is limited to genuinely domain-specific hard rules that change routing or safety for that secondmate.
+Natural-language summary and `scope:` text may contain parentheses and semicolons; keep the generated `(home: ...; scope: ...; projects: ...; added ...)` suffix intact so operational consumers resolve its explicit field markers.
+The `home:` path points to the seeded home containing `data/charter.md`; no extra registry pointer field is needed.
+For a remote route, `host:` is an OpenSSH config alias and `root:` is that host's separate tracked Firstmate code root.
+A remote second-mate agent always runs on the Herdr backend and every seed, launch, and liveness relaunch first gates its host on `bin/fm-remote-doctor.sh` readiness, so an unready host refuses with that doctor's own gap text rather than half-creating a route; the workers that second mate supervises keep the home's ordinary backend selection.
+This release places whole secondmate homes remotely and never individual workers.
+[`docs/remote-secondmates.md`](../../../docs/remote-secondmates.md) owns current operator setup and transport behavior.
+The home-seeded `data/charter.md` is the sole owner of boilerplate idle-by-default behavior, the normal delegation lifecycle, and standard escalation contracts, so point to that charter rather than restating those contracts in the registry entry.
+The `scope:` field is used during intake.
+The `projects:` field is a non-exclusive clone list, not ownership.
+
+## Charter and seed
+
+Scaffold a secondmate charter with:
+
+```sh
+bin/fm-brief.sh <id> --secondmate {<project>...|--no-projects}
+```
+
+The scaffold writes a charter brief instead of a task brief.
+Set `FM_SECONDMATE_CHARTER='<charter>'` to fill the charter text and `FM_SECONDMATE_SCOPE='<scope>'` when the routing scope differs.
+If you scaffold without `FM_SECONDMATE_CHARTER`, replace the `{TASK}` placeholder before seeding.
+Pass `--no-projects` instead of a project list to scaffold a project-less charter for a domain whose subject is the firstmate repo itself, whose home is a firstmate worktree and whose crews take pooled worktrees of the same repo.
+`--no-projects` is mutually exclusive with a project list, and omitting both still fails loudly, so an accidental omission is never mistaken for a deliberate project-less seed.
+Re-seeding a populated home as project-less is refused non-destructively when the home contains project clones or `data/projects.md` entries.
+Retire or clean that home first, and re-scaffold a stale project-bearing charter with `--no-projects` before seeding.
+Keep custom charter text focused on the persistent responsibility, available project clones, and genuinely domain-specific hard rules.
+The scaffolded charter, later copied to `data/charter.md`, owns the standard lifecycle and escalation wording.
+Preserve the generated charter sections unless the domain genuinely needs a hard rule.
+
+Provision a local persistent home and registry entry after the charter is filled:
+
+```sh
+bin/fm-home-seed.sh <id> <home|-> {<project>...|--no-projects}
+```
+
+Provision a whole remote home through its configured SSH host with:
+
+```sh
+bin/fm-remote-home-seed.sh <id> <ssh-alias> <remote-root> <remote-home> {<project>[=<origin-url>]...|--no-projects}
+```
+
+You resolve each project's origin yourself - from the captain, the project registry, a clone that exists elsewhere, `gh-axi`, or an explicit paste - and name it as `<project>=<origin-url>`; the seed validates and transports what you supply.
+A remote seed therefore creates nothing in this home beyond the route, the charter brief, and a launch record once it is launched: never clone a project into `projects/`, initialize no-mistakes here, or run a fleet sync just to seed a remote secondmate.
+A bare `<project>` remains a convenience for a project this home already has cloned, whose configured origin is read instead.
+[`docs/remote-secondmates.md`](../../../docs/remote-secondmates.md#provision-a-route) owns the rest of the operator contract, and [`bin/fm-project-origin-lib.sh`](../../../bin/fm-project-origin-lib.sh) owns the accepted origin forms.
+Pass `--no-projects` in the project position to seed the project-less home described above; the same mutual-exclusion and fail-loud-on-omission rules apply.
+It may only seed a home with no project clones or project-registry entries, and refuses conversion of populated homes without changing them.
+`-` durably leases a fresh firstmate worktree via `treehouse get --lease` under the secondmate id.
+The lease survives with no live process and is never recycled by later `treehouse get` or `prune`.
+The slot stays reserved across restarts until the lease is released.
+Release happens only on explicit retirement or seed rollback, never on routine restart or recovery.
+
+`bin/fm-home-seed.sh` copies the charter into the secondmate home as `data/charter.md`.
+It also writes the gitignored `.fm-secondmate-parent` durable binding before the required `.fm-secondmate-home` identity marker; the parser header in [`bin/fm-secondmate-parent-lib.sh`](../../../bin/fm-secondmate-parent-lib.sh) owns the record contract, and both files must remain in place.
+`bin/fm-spawn.sh --secondmate` launches it through the secondmate harness path, resolving `config/secondmate-harness` -> `config/crew-harness` -> the primary's own harness unless an explicit per-spawn harness override is passed.
+
+`config/secondmate-harness` may also pin a concrete model and effort for the secondmate agent, in the SAME file rather than a new one: the format is a single whitespace-separated line `<harness> [<model>] [<effort>]`, with only the first non-empty, non-comment line parsed.
+A bare `<harness>` (today's format, e.g. `claude`) behaves exactly as before - harness only, no model/effort flag - so this is fully backward-compatible.
+`bin/fm-harness.sh secondmate-model` and `bin/fm-harness.sh secondmate-effort` print the optional 2nd/3rd tokens (empty when absent, or when the file is absent/`default`/harness-only); they read only `config/secondmate-harness`, never `config/crew-harness`, which stays a bare adapter name.
+For a `--secondmate` spawn, `bin/fm-spawn.sh` populates `MODEL`/`EFFORT` from those tokens only when the harness itself came from the secondmate config path for that spawn.
+For a local route, an explicit per-spawn `--harness` flag, positional harness arg, or raw launch command starts clean on model and effort too, unless the caller also passes explicit `--model` or `--effort`.
+A remote route accepts only a verified harness adapter and refuses a raw launch command at the host boundary.
+When the file's tokens do apply, an explicit per-spawn `--model` or `--effort` flag always wins over the file's token for that axis.
+Because this resolves from the file on every spawn, the pin is durable across every respawn (recovery, `/updatefirstmate`, restart) exactly like the harness axis itself - e.g. `config/secondmate-harness` containing `claude opus` keeps a secondmate pinned to Opus even if the primary's own default model later changes.
+This is secondmate-only: crewmate/scout model resolution is untouched by this file.
+
+This section is the single owner of the secondmate sync and inherited-local-material propagation contract; `AGENTS.md` sections 3 and 4 point here.
+Before a local launch, `fm-spawn.sh --secondmate` locally fast-forwards the home to the primary firstmate checkout's current default-branch commit when it is safe; dirty, diverged, or in-flight homes launch unchanged with a warning.
+The locked session-start deferred network stage runs the same bootstrap sweep for every live local secondmate home, discovered from `state/<id>.meta` records with `kind=secondmate` (`data/secondmates.md` only backfills `home=` for older records).
+That no-fetch path is a purely local fast-forward of tracked files, never an origin fetch, and it never touches the gitignored operational dirs, so a secondmate's backlog, projects, and in-flight work are never disturbed; a linked worktree advances immediately, while a standalone clone that lacks the target receives firstmate updates through `/updatefirstmate`'s origin refresh.
+A remote launch and the deferred bootstrap sweep ask the configured host to fast-forward its persistent home to that host's code-root commit under the same clean and ancestry guards.
+`/updatefirstmate` first updates the remote code root from its own origin, then runs that guarded home sync.
+SSH exit 255 preserves the route and reports unknown completion; it never triggers local respawn or failover.
+The same placement-specific launch and deferred bootstrap sweep also propagate the primary's declared inherited local material: `config/crew-dispatch.json`, `config/crew-harness`, `config/backlog-backend`, `config/backend`, `config/herdr-presentation-spaces`, `config/startup-memory-budget`, and the one shared captain-preference file `data/captain-shared.md`.
+Because these paths are gitignored, that propagation is a separate, primary-authoritative copy independent of the tracked-files fast-forward: it re-converges every live home whether or not its tracked files advanced, and it touches only the declared items.
+Propagation failures warn without blocking secondmate launch or session-start continuation, and the destination keeps whatever safely validated state the helper left behind.
+Inheritance copies the literal `config/crew-harness` file, so a secondmate's own crewmates use the primary's crewmate harness only when it names a concrete adapter such as `codex`; an unset or `default` value has nothing concrete to inherit, and the secondmate's own crewmates fall back to the secondmate's own or detected harness instead.
+Inherited `config/backend` becomes that secondmate home's local runtime-backend default for future spawns only; it never retargets, rewrites, migrates, stops, or restarts an already-live worker endpoint.
+A present primary value always converges byte-exact into validated secondmate homes, and primary absence removes the destination so those homes keep runtime auto-detection.
+Explicit per-spawn `--backend` and `FM_BACKEND` remain stronger than every home's local `config/backend`, including an inherited default.
+`config/secondmate-harness` is not inherited because it is only the primary's knob for launching secondmate agents.
+`data/captain-shared.md` is main-authoritative in the primary home and read-only in secondmate homes.
+Its primary file header must state that the file is main-authoritative, read-only in secondmate homes, must not be edited there, and that new captain-preference discoveries are routed to the main firstmate through marked status or a document pointer.
+Every propagation point converges the secondmate copy to the primary bytes; when the primary file is absent, any existing secondmate copy is quarantined and removed so absence converges too.
+The helper rejects unsafe directories, symlinked or nonordinary source or destination artifacts, and hardlinked destination files.
+Between propagation runs, the secondmate copy is filesystem read-only; the helper may make its owned destination writable only around a guarded update and restores read-only mode on success, unchanged bytes, and recoverable failure paths.
+Before replacing divergent secondmate bytes, the helper hash-compares source and destination, quarantines the secondmate-local version to a collision-safe private dated sibling file, and emits a `SECONDMATE_SYNC:` diagnostic naming the home and quarantine artifact.
+Never copy any secondmate `data/captain-shared.md` back into the primary.
+Keep each home's `data/captain.md` domain-local.
+After first propagation to an existing home, trim that home's local `data/captain.md` by hand to domain-specific content plus pointers to `data/captain-shared.md`; do not automate or silently delete private content.
+Keep every `data/learnings.md` fully local by captain decision; route fleet-general machinery facts into tracked documentation through the normal firstmate repo path rather than inventing shared learnings propagation.
+No AGENTS.md reread nudge is needed at spawn or respawn because the agent reads instructions fresh on launch; only the bootstrap sweep's running-home instruction-surface advance needs that AGENTS.md re-read.
+Bootstrap reports successful AGENTS.md re-read sends as `BOOTSTRAP_INFO:` and only emits `NUDGE_SECONDMATES:` when that send fails and needs retry.
+A separate, literal-content config reread is required whenever inherited `config/*` material changes under an already-running secondmate.
+For a local home, after each successful allowlisted config write, both the locked bootstrap convergence path and mid-session `bin/fm-config-push.sh` use the shared propagation report to build one per-home generation-specific private instruction file from the validated destination post-write bytes for only the allowlisted config items that actually changed for that home (`config/crew-dispatch.json`, `config/crew-harness`, `config/backlog-backend`, `config/backend`, `config/herdr-presentation-spaces`, `config/startup-memory-budget`), in deterministic allowlist order.
+Each changed path is printed with clear begin/end delimiters and the destination file's full exact new bytes unparsed, or the explicit token `ABSENT` when propagation removed the destination copy.
+The instruction uses only minimal framing that these are defaults/rules and do not remove judgment; it never includes SHA values, selected profiles, parsed summaries, or any other generated interpretation.
+`data/captain-shared.md` is not a config file and is never inlined into this instruction file or message.
+Homes whose allowlisted config files were all unchanged receive no config-reread message when no retry is pending.
+Different homes may receive different changed-file sets based on their pre-push destination bytes.
+Delivery uses the existing routed secondmate path (`fm-send`) with only a single-line `CONFIG_REREAD: <absolute generation-specific instruction path>` pointer; a failed instruction publication retains the generated exact bytes in a bounded private retry queue when possible, legacy retry reports remain recoverable, a failed publication or retry-marker write retains the exact generation until it can be delivered, a failed send records a per-generation durable retry marker when possible, and all failures surface a concrete `CONFIG_REREAD:` diagnostic without claiming the live agent already re-read the values.
+The propagation, generation publication, and pointer-delivery sequence holds one per-home inheritance lock, so concurrent mid-session pushes cannot deliver an older generation after a newer one.
+A newly launched or relaunched secondmate already reads its files at launch, so its pending config-reread generations are discarded or quarantined after cleanup failure and it needs no redundant live-agent config nudge unless propagation changes files after launch.
+Quarantined pre-relaunch generations are retained in bounded private history, and cleanup skips creating an empty quarantine generation.
+Successfully delivered generations are retained only within a bounded per-home state history, while pending generations remain until delivery succeeds or a launch supersedes them.
+A remote home receives the same allowlisted bytes through `fm-remote-inherit.sh` and gets one marked re-read instruction after a changed transfer.
+The parent records that nudge before delivery, retains it after a failed send, and retries the exact same route during locked bootstrap convergence.
+It does not receive a pointer to a primary-local generation path that cannot exist on that host.
+These config values remain defaults and rules only; they must not harden `fm-spawn` to reject a deliberate runtime choice that differs from the configured defaults.
+For already-live secondmates, use `bin/fm-config-push.sh` to push a mid-session inherited local-material change without running the tracked-file fast-forward.
+It uses the same live-home discovery and propagation helper as bootstrap, reports each item as `pushed`, `unchanged`, `skipped`, or `error`, and follows the config-reread contract above for changed or pending generations.
+`bin/fm-home-seed.sh` refuses to copy a missing or placeholder charter.
+
+Direct seed without a preexisting brief requires `FM_SECONDMATE_CHARTER`.
+Run `bin/fm-home-seed.sh validate` when checking registry integrity; its header owns the complete validation and refusal mechanics.
+
+Seeding is transactional.
+If validation, cloning, no-mistakes initialization, or registry update fails, generated briefs, new homes, new project clones, and registry edits are rolled back.
+
+Secondmate project lists may include `no-mistakes` and `direct-PR` projects only.
+`local-only` projects stay with the main firstmate.
+For `no-mistakes` projects, seeding initializes only projects newly cloned into a secondmate home and refuses to mutate a preexisting clone that is not already initialized.
+
+## Record intake for an existing or inherited domain
+
+Classify the domain before seeding, because this step applies to only one of the two cases.
+A greenfield domain has no delivered domain work yet: nothing already shipped in its projects, no live deployment, and no predecessor records to import.
+Seed a greenfield domain normally; there is nothing to reconcile and this section adds no work to it.
+An existing or inherited domain is any domain whose product is already in development, and any predecessor's domain a new mate takes over, including a consolidation after a retirement.
+Both of those cases require record intake before the new mate acts on any inherited plan.
+
+For an existing or inherited domain, the creating agent must:
+
+1. Reconcile every inherited plan against the domain's authoritative shipped state, which is `origin/main` for each relevant project plus the live deployment.
+   A fetched clone of each relevant project is a precondition of that reconciliation, so wire the home to its projects before reconciling rather than on first task.
+   The imported backlog, the predecessor's own notes, instruction-surface prose, and an absent or unfetched local view are all inadmissible as shipped-state evidence.
+2. Seed the new home with only genuinely open work plus the domain's durable knowledge, meaning the learnings, decisions, and delivery posture that are still live.
+3. Never inherit a plan backlog blind.
+   A plan row whose work is already shipped is dropped, or recorded as done with the merged evidence that settles it, and is never carried forward as open.
+
+A live backlog keeps only the configured recent Done entries by design, so an inherited queue structurally over-represents plans and under-represents deliveries.
+Treat an inherited queue that carries plans with no matching delivery record as unreconciled rather than as open work, and record whatever could not be reconciled as an explicit residual-uncertainty list in the new home rather than leaving that gap silent.
+
+## Backlog handoff
+
+Apply `AGENTS.md` section 10's work-items-only backlog contract before creation or handoff.
+When a secondmate is created for a domain, existing main-backlog items that fall under its scope should become its work instead of staying stranded in the main backlog.
+Scope-matching is firstmate's judgment against the secondmate's natural-language scope, not a keyword rule.
+Read `data/backlog.md`, pick queued items that fit the new scope, and move them with:
+
+```sh
+bin/fm-backlog-handoff.sh <secondmate-id> <item-key>...
+```
+
+After seeding, run this handoff for the new secondmate's in-scope queued items.
+For an existing or inherited domain, complete record intake first so no already-shipped plan row is handed off as open work.
+For a local route, the helper resolves and validates the secondmate home from `data/secondmates.md`, then delegates the item move to `tasks-axi mv` (the single owner of the backlog format), which moves each named item - and a whole connected set, blocker plus dependents, atomically - from the main `data/backlog.md` into the secondmate home's `data/backlog.md`.
+For a remote route, the same helper first moves the dependency-closed set atomically from the main backlog into `data/handoff/<id>.outbox.md`, then transfers that backlog-format outbox through `fm-on.sh` and lets the remote home's `fm-backlog-receive.sh` move every not-already-present key under the destination lock.
+After a new local placement or a remote outbox receipt becomes durable, the helper sends one marked routed-work instruction through the receiving secondmate's recorded endpoint; missing or failed delivery makes the command fail loudly with the moved work intact, and the same handoff command retries known-undelivered wake intent without moving an already-present item again.
+An unresolved delivery attempt is never blindly resent.
+For a remote route, the outbox remains until both backlog receipt and receiver wake are confirmed; `--resume-pending` retries unfinished outboxes, while the script header owns its stable wake-correlation recovery state.
+There is no two-phase handoff journal and no tasks-axi release beyond the already-required atomic `mv` capability.
+Bootstrap retries pending outboxes when mutation is authorized and emits `SECONDMATE_HANDOFF:` for any that remain.
+This delegated route remains required when `config/backlog-backend=manual`, which controls only routine firstmate backlog edits.
+It moves each queued item's whole block - the `- [ ] <id> ...` header plus every following two-or-more-space-indented body line and blank separator, up to the next item or column-0 section heading - byte-exact under the same section, treating an indented `## ...` line as body rather than a section boundary, so neither the header nor its body is duplicated or orphaned.
+It refuses a selected item with a single-space or tab-indented continuation rather than risk leaving content orphaned in the main backlog.
+It accepts in-scope `## Queued` entries only and refuses `## In flight` and historical `## Done` entries.
+Done records stay with their home for pruning or archiving.
+It is idempotent; an item already in the secondmate backlog is skipped.
+After a successful move it warns for any moved key that still owes a public relay reply bound to `main/<key>`, because that binding no longer names the home owning the work; rebind the commitment to `secondmate:<id>` through the `fmx-respond` promised-final procedure, which owns those commands.
+That same rule governs routing generally: a Relay-linked request whose work goes to a secondmate cannot use the home-local mention link at all and needs a promised-final commitment bound to that secondmate's home.
+It refuses any destination that is not a genuine seeded firstmate home with safe operational directories and a matching `.fm-secondmate-home` marker, so a move can never land in a project.
+Do not hand off `local-only` items.
+
+## Recovery
+
+For local `kind=secondmate` meta with no window, treat the secondmate as a dead persistent direct report and respawn it with:
+
+```sh
+bin/fm-spawn.sh <id> --secondmate
+```
+
+Use the recorded `home=` in meta.
+If meta is missing but `data/secondmates.md` still registers the secondmate, respawn from the registry entry and its persistent home.
+For a remote route, the same command probes and relaunches only on the configured host.
+An SSH transport failure or unreadable remote endpoint remains unknown and must be reconciled on that host; never launch a local replacement.
+`stuck-crewmate-recovery`'s remote-secondmate note owns why the endpoint-dead and send-failed verdicts that seem to justify this are themselves unreliable.
+Respawn re-resolves the secondmate harness from current config, uses the same guarded pre-launch sync, and re-propagates inherited local material, so recovered secondmates converge inherited config items and shared captain preferences whenever their home validates; tracked-file sync remains guarded separately.
+If the secondmate is already running and only inherited local material changed, prefer `bin/fm-config-push.sh` over respawning.
+To move a live LOCAL secondmate onto a newly pinned harness, model, or effort without a full recovery, set `config/secondmate-harness` and then relaunch it with `bin/fm-control.sh <id> relaunch`, which re-resolves that pin, stops the agent, and launches the replacement in the same home ([`.agents/skills/eindri-homes/assets/control-plane.md`](../../../.agents/skills/eindri-homes/assets/control-plane.md)).
+That plane refuses a remotely placed secondmate by name, because its agent runs on another host where none of the plane's postconditions can be read; use the remote route's own relaunch path for those.
+
+Do not reconstruct a secondmate's whole tree from the main home.
+The main firstmate reconciles only direct reports.
+Each secondmate is a firstmate in its own home, so it runs recovery on startup and reconciles its own crewmates.
+A secondmate's recovery reconciles only work that is already its own and then idles.
+It never initiates a survey or audit during recovery.
+
+## Retirement and teardown
+
+A secondmate is persistent by default.
+An empty queue is healthy and does not trigger teardown.
+Run `bin/fm-teardown.sh <id>` for `kind=secondmate` only when the captain or main firstmate explicitly decides to retire that persistent second mate.
+
+The safety check is the secondmate's own home.
+Teardown refuses while its `state/*.meta` contains in-flight work.
+A remote route delegates the same guard to its configured host and additionally refuses while the primary has a pending handoff outbox or unresolved routed reply.
+SSH exit 255 preserves the route and local records because remote completion is unknown.
+When safe, teardown kills the direct endpoint, removes the `data/secondmates.md` route, clears the main home metadata, and removes the retired secondmate home.
+Removing a leased home releases its durable treehouse lease via `treehouse return`, so the pool slot is freed for reuse rather than left leased forever.
+A plain-clone home with no pool slot is simply removed.
+If `treehouse return` fails for a leased home, teardown stops with state intact rather than raw-removing the directory and hiding a held lease.
+Before either return or direct removal, teardown asks the target home's process-event runner to retire its registrations and physically owned machine-wide claims through the safe generation-bound path.
+It refuses retirement while that cleanup is uncertain or unavailable, preserving the home and retirement records for a later retry.
+Raw deletion is unsupported because a blocking process-event child can outlive its home.
+
+With `--force`, teardown is the explicit discard path.
+It kills child windows, discards child work and state inside the secondmate home, removes the route, releases the lease, and removes the retired secondmate home.
+If forced teardown contends with a fresh task publication in any affected home, one command refuses without publishing or removing task state; treat that refusal as terminal and inspect the other operation before retrying.
+Relaunch and non-forced teardown remain outside that serialization.
+Never use `--force` unless the captain explicitly said to discard the work.