From abaf5775736af7f74e2629ccc3fbf4070185f405 Mon Sep 17 00:00:00 2001 From: twilwa Date: Tue, 22 Sep 2026 07:13:36 +0200 Subject: [PATCH 1/6] docs: audit AGENTS.md size and ownership --- docs/agents-md-audit.md | 137 ++++++++++++++++++++++++++++++ docs/documentation-audiences.json | 4 + 2 files changed, 141 insertions(+) create mode 100644 docs/agents-md-audit.md diff --git a/docs/agents-md-audit.md b/docs/agents-md-audit.md new file mode 100644 index 00000000000..b77d85eb6c7 --- /dev/null +++ b/docs/agents-md-audit.md @@ -0,0 +1,137 @@ +# AGENTS.md size audit + +This audit inventories the blank-line-delimited paragraphs and contiguous list groups in the 85,533-byte `AGENTS.md` baseline reviewed on 2026-09-22. +The byte column counts each group's content including its terminating newline but excludes the blank separator between groups, so the rows do not sum to the file total. +Headings are listed separately so every baseline group has a stable identifier. +The planned replacement is approximately 33,000 bytes, a reduction of about 61 percent; the implementation should report the measured result rather than treating that projection as a quota. + +Disposition meanings are exact: keep always-loaded, prune as derivable from code or docs, prune as duplicated elsewhere, or transpose to a named skill. +When a group mixes always-loaded safety with conditional procedure, the disposition names the destination and the evidence column identifies the safety stub that remains in `AGENTS.md`. + +| ID | Baseline group | Bytes | Disposition | Skill trigger | Existing owner or safety evidence | +|---:|---|---:|---|---|---| +| 1 | `# Firstmate` | 12 | keep always-loaded | Always loaded. | Supervisor contract root. | +| 2 | Supervisor and worker-role boundary | 466 | keep always-loaded | Always loaded. | `bin/fm-dod-lib.sh` emits the worker-role override, but the supervisor must always know its own role boundary. | +| 3 | First mate and captain identity | 91 | keep always-loaded | Always loaded. | Supervisor identity has no conditional owner. | +| 4 | Captain-address and chat-only rule | 1,057 | keep always-loaded | Every chat message. | Required safety boundary; section 9 owns captain-facing style. | +| 5 | Section 1 heading | 36 | keep always-loaded | Always loaded. | Prime-directive navigation. | +| 6 | Delegation and secondmate identity | 515 | keep always-loaded | Every project request. | Core supervisor role boundary. | +| 7 | Hard-rule introduction | 31 | keep always-loaded | Always loaded. | Core safety contract. | +| 8 | Hard rules 1-5 | 2,188 | keep always-loaded | Always loaded. | Required verbatim safety boundaries; `bin/fm-teardown.sh` owns the landed-work test and guarded skills own named exceptions. | +| 9 | Firstmate-repo private and shared material | 719 | keep always-loaded | Every repository mutation. | `firstmate-coding-guidelines` supplements this shared-material boundary. | +| 10 | Section 2 heading | 23 | keep always-loaded | Always loaded. | Compact home-layout navigation. | +| 11 | Operational-home ownership and `FM_HOME` | 579 | keep always-loaded | Always loaded. | `docs/configuration.md` "Operational home layout and state" and `bin/fm-send.sh` header. | +| 12 | Directory-purpose summary | 346 | prune as duplicated elsewhere | None. | `docs/configuration.md` "Operational home layout and state" already states the same top-level purposes. | +| 13 | Exhaustive tracked, config, data, project, and state tree | 19,603 | prune as derivable from code or docs | None. | `docs/configuration.md` owns the top-level layout; producer headers and help own child fields and mutation mechanics. | +| 14 | Status-event truth and captain-memory files | 408 | keep always-loaded | Every state interpretation. | `bin/fm-classify-lib.sh`, `bin/fm-crew-state.sh`, and `docs/configuration.md` own mechanics; the event-versus-current-state warning remains inline. | +| 15 | Section 3 heading | 54 | keep always-loaded | Every session start. | Session-start navigation. | +| 16 | Run session start exactly once | 639 | keep always-loaded | Every session start. | `bin/fm-session-start.sh` header and `docs/sessionstart-nudge.md`; run-once rule remains inline. | +| 17 | Read and trust the complete digest once | 700 | keep always-loaded | Every session start. | `bin/fm-session-start.sh` header; read-once and absent-source meanings remain inline. | +| 18 | Lock-refused read-only posture | 305 | keep always-loaded | Any lock refusal. | Required safety boundary; `bin/fm-lock.sh` and session-start digest supply the diagnostic. | +| 19 | Deferred startup-network mechanics | 846 | prune as derivable from code or docs | None. | `bin/fm-startup-network.sh` header and `docs/configuration.md` own the stage and its result states. | +| 20 | Seven-part digest enumeration | 5,160 | prune as derivable from code or docs | None. | `bin/fm-session-start.sh` header owns ordering and contents; wake acknowledgement remains in the always-loaded supervision section. | +| 21 | Bootstrap consent, tool, and diagnostic rules | 825 | transpose to `bootstrap-diagnostics` | Load on any actionable bootstrap or network-check diagnostic listed in section 13. | Existing `bootstrap-diagnostics` owns responses; install consent and essential-tool boundary remain inline. | +| 22 | Section 4 heading | 35 | keep always-loaded | Always loaded. | Replaced by a concise dispatch trigger stub. | +| 23 | Harness trigger and verified-adapter boundary | 546 | transpose to `harness-adapters` | Load before spawn, recovery, trust, harness skill invocation, lifecycle control, or adapter verification. | Existing `harness-adapters` non-negotiable safety and routing matrix. | +| 24 | Dispatch profiles, quota selection, typed resolution, and effort | 3,538 | transpose to `task-intake` and `quota-array-dispatch` | Load `task-intake` for a new task; additionally load `quota-array-dispatch` for a matched profile array. | `docs/configuration.md` "Dispatch profiles", `bin/fm-dispatch-resolve.sh` header, and existing `quota-array-dispatch`. | +| 25 | Secondmate pins and runtime-backend refusal | 556 | transpose to `harness-adapters` | Load before spawn or recovery. | Existing `harness-adapters`, `secondmate-provisioning`, `bin/fm-spawn.sh`, and `docs/configuration.md` "Runtime backend". | +| 26 | Section 5 heading | 15 | keep always-loaded | Every recovery pass. | Replaced by a concise direct-report recovery boundary. | +| 27 | Reconcile reality after startup | 287 | keep always-loaded | Every session start. | `bin/fm-session-start.sh` digest contract; event-versus-current-state warning remains inline. | +| 28 | Ordinary-worker and secondmate recovery procedures | 639 | transpose to `stuck-crewmate-recovery` and `secondmate-provisioning` | Load for the direct-report conditions listed in section 13. | Existing recovery skills; this-home-only recovery boundary remains inline. | +| 29 | Away recovery behavior | 601 | prune as duplicated elsewhere | None beyond the existing away/quiet triggers. | Section 8's away-mode stub plus the `afk` and `quiet` skills own this behavior. | +| 30 | Section 6 heading | 39 | keep always-loaded | Always loaded. | Compact project and knowledge routing remains inline. | +| 31 | Project add/remove procedure | 571 | prune as duplicated elsewhere | Load `project-management` before add, create, clone, register, initialize, or remove. | Existing `project-management` owns the complete policy. | +| 32 | Secondmate provisioning procedure | 368 | prune as duplicated elsewhere | Load `secondmate-provisioning` for its section 13 triggers. | Existing `secondmate-provisioning`. | +| 33 | Secondmate idle-by-default rule | 320 | prune as duplicated elsewhere | Load `secondmate-provisioning` before secondmate lifecycle work. | Existing `secondmate-provisioning`; the core secondmate identity remains in section 1. | +| 34 | Knowledge-routing introduction | 52 | keep always-loaded | Whenever durable knowledge is captured. | Core memory-placement boundary. | +| 35 | Six-way knowledge-routing list | 652 | keep always-loaded | Whenever durable knowledge is captured. | `docs/architecture.md` "Operational memory routing" and `stow` provide procedures; concise destinations remain inline. | +| 36 | Project memory creation and `/stow` | 626 | transpose to `stow` | Load when `/stow` is invoked. | Existing `stow`, `bin/fm-ensure-agents-md.sh`, and hard rule 1; only the project-memory boundary remains inline. | +| 37 | Section 7 heading | 21 | keep always-loaded | Always loaded. | Replaced by concise task-safety and skill triggers. | +| 38 | Always-loaded lifecycle declaration | 131 | prune as duplicated elsewhere | None. | Exact mechanics are owned by scripts and the new lifecycle skills; core safety remains inline. | +| 39 | Intake heading | 25 | transpose to `task-intake` | Load before classifying, briefing, or dispatching a new task. | New skill becomes the conditional policy owner. | +| 40 | Project resolution | 364 | transpose to `task-intake` | Before task classification. | `data/projects.md` is the registry and the new skill owns judgment. | +| 41 | Secondmate routing and avoid-premature-automation rules | 756 | transpose to `task-intake` | Before task classification or routing. | `secondmate-provisioning` owns secondmate mechanics; new skill owns intake judgment. | +| 42 | Existing-evidence preflight | 116 | transpose to `task-intake` | Before commissioning an investigation. | New skill owns task-shape classification. | +| 43 | Ship and scout definitions | 585 | transpose to `task-intake` | Before choosing ship or scout. | `bin/fm-brief.sh`, `bin/fm-spawn.sh`, and `bin/fm-scout.sh` headers own mechanics. | +| 44 | Informational, diagnostic, and implementation-authority boundary | 598 | transpose to `task-intake` | Before scoping informational, diagnostic, or implementation work. | Existing `diagnostic-reasoning`; the new skill owns ship/scout choice. | +| 45 | Delivery mode and yolo intake | 989 | transpose to `task-intake` | Before every ship dispatch. | `bin/fm-project-mode.sh`, `docs/configuration.md`, and task spawn headers own mechanics. | +| 46 | Concurrency, dependency, and brief requirement | 687 | transpose to `task-intake` | Before dispatching or serializing work. | New skill owns intake judgment; `bin/fm-brief.sh` owns scaffold mechanics. | +| 47 | Dispatch heading | 37 | transpose to `task-intake` | Before spawn. | New skill route. | +| 48 | Spawn isolation and backlog transition | 770 | transpose to `task-intake` | Before spawn. | `bin/fm-spawn.sh` header and generated brief own the isolation checks and transition. | +| 49 | Steering, control, remote correlation, and supervision handoff | 1,737 | transpose to `harness-adapters` and `task-intake` | Load before steering or worker lifecycle control. | `bin/fm-send.sh`, `bin/fm-control.sh`, `bin/fm-pending-reply-lib.sh`, and existing `harness-adapters`. | +| 50 | Delivery-path heading | 47 | transpose to `task-delivery` | Load when implementation starts or a delivery milestone arrives. | New skill route. | +| 51 | Selected-path rigor | 539 | transpose to `task-delivery` | Before starting validation or delivery. | No-mistakes, `pr-review-policy`, and the selected-mode scripts own their mechanics. | +| 52 | Three delivery-mode definitions | 402 | transpose to `task-delivery` | Before starting validation or delivery. | `bin/fm-dod-lib.sh` and `bin/fm-project-mode.sh` own generated mode semantics. | +| 53 | Merge authority, red-check waiver, ask-user, and guarded merge commands | 1,671 | transpose to `task-delivery` with always-loaded safety stub | Before any merge or local landing. | Hard rules 1-3 remain verbatim; `pr-review-policy`, `bin/fm-pr-merge.sh`, and `bin/fm-merge-local.sh` own guarded decisions. | +| 54 | Validate heading | 13 | transpose to `task-delivery` | Before validation. | New skill route. | +| 55 | No-mistakes ownership and mid-task scope changes | 1,284 | transpose to `task-delivery` | Before starting or steering validation. | `bin/fm-dod-lib.sh`, no-mistakes, and new skill policy. | +| 56 | Validation invalidation and custody recovery | 1,255 | transpose to `task-delivery` | When a captain instruction invalidates active validation. | No-mistakes structured status and new skill policy. | +| 57 | Ask-user return flow | 599 | transpose to `task-delivery` | On any no-mistakes ask-user finding. | Existing `ask-user-authority`, `bin/fm-send.sh --resolve-key`, and new skill policy. | +| 58 | Validation-state interpretation | 884 | transpose to `task-delivery` | On validation status or wake. | `bin/fm-crew-state.sh` and no-mistakes structured status. | +| 59 | PR ready, landing, and teardown heading | 36 | transpose to `task-delivery` | On ready, merged, or teardown milestones. | New skill route. | +| 60 | PR registration, review ledger, custom checks, and merge signal | 1,389 | transpose to `task-delivery` and `pr-review-policy` | On a PR-ready line or before a GitHub merge. | `bin/fm-pr-check.sh`, existing `pr-review-policy`, `bin/fm-check-register.sh`, and `bin/fm-check-unregister.sh`. | +| 61 | Landed-only teardown | 393 | transpose to `task-delivery` with always-loaded safety stub | Before teardown. | Hard rule 3 remains verbatim; `bin/fm-teardown.sh` owns the complete landed-work test. | +| 62 | Secondmate retirement | 269 | prune as duplicated elsewhere | Load `secondmate-provisioning` before retirement. | Existing `secondmate-provisioning` and hard rule 3. | +| 63 | Scout heading | 32 | transpose to `task-delivery` | On scout completion or promotion. | New skill route. | +| 64 | Scout completion, captain-call gate, visual loop, and promotion | 1,145 | transpose to `task-delivery` and `captain-hold-lifecycle` | Load on scout completion, visual-review completion, or promotion. | Existing `captain-hold-lifecycle`, `bin/fm-promote.sh`, and new skill policy. | +| 65 | Section 8 heading | 27 | keep always-loaded | Always loaded. | Supervision navigation. | +| 66 | Always-loaded supervision declaration | 203 | keep always-loaded | Whenever supervision is required. | Emitted session-start protocol and named docs own harness recipes. | +| 67 | Exactly one live supervision cycle | 555 | keep always-loaded | Whenever work or Relay requires supervision. | Required no-turn-ends-blind contract; `docs/turnend-guard.md`. | +| 68 | Drain-first and generation-bound wake acknowledgement | 1,409 | keep always-loaded | Every wake-handling turn. | Required wake acknowledgement boundary; `bin/fm-wake-lib.sh` prints the exact command. | +| 69 | Wake-handler introduction | 36 | keep always-loaded | Every actionable wake. | Core routing table. | +| 70 | Four wake-type handlers | 819 | keep always-loaded | Every actionable wake. | `bin/fm-classify-lib.sh` and emitted supervision protocol own mechanics. | +| 71 | Bearings contribution trigger | 176 | transpose to `bearings` | Load on contributions wake or upstream-issue filing. | Existing `bearings`. | +| 72 | Merged-clone refresh and Relay terminal behavior | 414 | transpose to `fmx-respond` except clone-refresh stub | Load `fmx-respond` on Relay-linked milestones or terminal wakes. | Guarded fleet sync owns refresh; existing `fmx-respond` owns public follow-up. | +| 73 | Secondmate idleness, silent waits, and scoped watcher repair | 478 | keep always-loaded | Every supervision wait or repair. | `secondmate-provisioning` and emitted supervision protocol; no-broad-kill safety remains inline. | +| 74 | Guard backstop and worktree isolation | 523 | keep always-loaded | Every supervision cycle. | `docs/turnend-guard.md`, `bin/fm-spawn.sh`, and generated ship brief. | +| 75 | Away/quiet heading | 34 | keep always-loaded | When away or quiet markers or commands appear. | Trigger stub must be visible before skill load. | +| 76 | Away and quiet triggers | 512 | keep always-loaded | On `/afk`, `/quiet`, marked injections, or away-state markers. | Existing `afk`, `quiet`, and `bin/fm-wake-lib.sh`. | +| 77 | Away and quiet safety list | 1,610 | keep always-loaded | Whenever away or quiet mode is active. | Required inline safety facts from the `firstmate-coding-guidelines` model stub. | +| 78 | Stuck-worker heading | 25 | prune as duplicated elsewhere | None. | Section 13 already carries the complete skill trigger. | +| 79 | Stuck-worker pointer | 161 | prune as duplicated elsewhere | Load `stuck-crewmate-recovery` for its section 13 trigger. | Existing section 13 row. | +| 80 | Section 9 heading | 39 | keep always-loaded | Every captain-facing message. | Captain communication navigation. | +| 81 | Outcome-first, standalone-final, and vocabulary rules | 1,936 | keep always-loaded | Every captain-facing message. | Core visibility and translation contract. | +| 82 | Internal-to-captain vocabulary map | 1,286 | keep always-loaded | Every captain-facing message. | Core translation table. | +| 83 | Never relay raw internal evidence | 439 | keep always-loaded | Every captain-facing message. | Core confidentiality and translation boundary. | +| 84 | Escalation structure | 269 | keep always-loaded | Every escalation. | Core captain-facing contract. | +| 85 | Immediate-escalation introduction | 35 | keep always-loaded | Every escalation decision. | Core escalation list. | +| 86 | Immediate-escalation list | 368 | keep always-loaded | Every escalation decision. | Core authority and safety boundary. | +| 87 | Parent channel, no-op response, decision asks, PR URLs, and cost | 1,809 | keep always-loaded | Every captain-facing result. | `docs/secondmate-parent-channel.md` owns routing mechanics; response rules remain inline. | +| 88 | Section 10 heading | 24 | keep always-loaded | Always loaded. | Replaced by a concise backlog trigger stub. | +| 89 | Queue, captain-call, transition, and reevaluation policy | 1,494 | transpose to `backlog-management` | Load before filing, holding, handing off, updating, or closing backlog work and on backlog review. | `bin/fm-tasks-axi.sh`, `bin/fm-captain-hold.sh`, spawn/teardown transitions, and existing `captain-hold-lifecycle`. | +| 90 | Backend syntax and cross-home handoff | 490 | transpose to `backlog-management` | Before any backlog command or cross-home handoff. | `.tasks.toml`, `docs/configuration.md`, `tasks-axi --help`, and `bin/fm-backlog-handoff.sh`. | +| 91 | Task-note hygiene | 596 | transpose to `backlog-management` | Before replacing a task note. | New skill becomes the policy owner; tasks-axi owns command syntax. | +| 92 | Section 11 heading | 23 | prune as duplicated elsewhere | None. | Briefing becomes part of `task-intake`. | +| 93 | Captain intent, Firstmate spec, and scaffold ownership | 1,201 | transpose to `task-intake` | Before writing or changing a task brief. | `bin/fm-brief.sh` and `bin/fm-dod-lib.sh` own syntax and intent provenance. | +| 94 | Ship isolation, Firstmate skill, and Herdr lab | 540 | transpose to `task-intake` | Before writing a ship brief; additionally load `firstmate-coding-guidelines` for Firstmate shared material. | `bin/fm-brief.sh` generated safety contract and `firstmate-coding-guidelines`. | +| 95 | Charter brief and status semantics | 338 | transpose to `task-intake` and `secondmate-provisioning` | Before charter briefing or status-protocol customization. | Existing `secondmate-provisioning`, `bin/fm-classify-lib.sh`, and scaffold. | +| 96 | Section 12 heading | 19 | keep always-loaded | Always loaded. | Compact self-update trigger remains inline. | +| 97 | Self-update propagation and skill trigger | 481 | prune as duplicated elsewhere | Load `updatefirstmate` when invoked or requested. | Existing `updatefirstmate` owns the guarded procedure and surface scope. | +| 98 | Section 13 heading | 35 | keep always-loaded | Always loaded. | Central trigger index. | +| 99 | Trigger-index introduction | 82 | keep always-loaded | Always loaded. | Trigger semantics must be visible without loading a skill. | +| 100 | Existing agent-only skill trigger list | 3,820 | keep always-loaded | At each listed condition. | Existing internal skill descriptions; add rows for every new skill. | +| 101 | Section 14 heading | 13 | keep always-loaded | Always loaded. | Replaced by a concise Relay trigger and authority stub. | +| 102 | Relay activation and public authority boundary | 620 | transpose to `fmx-respond` with always-loaded safety stub | Load on Relay wakes or before a promised public reply. | Existing `fmx-respond` owns public-channel authority; `docs/configuration.md` owns activation. | +| 103 | Relay supervision and terminal follow-up | 489 | prune as duplicated elsewhere | Load `fmx-respond` on Relay wakes and linked milestones. | Existing section 13 trigger and `fmx-respond`. | +| 104 | Promised-final durability and owning-home rule | 478 | transpose to `fmx-respond` | Before promising a public final or on public-followup/startup commitment input. | Existing `fmx-respond` and `bin/fm-public-followup.sh`. | +| 105 | Captain precedence heading | 34 | keep always-loaded | Always loaded. | Core authority navigation. | +| 106 | Current explicit captain instruction precedence | 874 | keep always-loaded | Every authority decision. | Core authority and destructive-action boundary. | +| 107 | Maintenance heading | 25 | keep always-loaded | Always loaded. | Compact maintenance trigger remains inline. | +| 108 | File-maintenance discipline | 365 | transpose to `firstmate-coding-guidelines` | Load before changing shared tracked material. | Existing `firstmate-coding-guidelines` owns placement, one-owner, size, trigger, and prose rules. | + +## Planned conditional owners + +- `task-intake` will own project resolution, ship/scout choice, delivery-mode selection, dispatch-profile intake, concurrency judgment, brief authoring, spawn handoff, and steering boundaries. +- `task-delivery` will own selected-path validation, validation supersession, ask-user return flow, ready-state registration, guarded landing mechanics, landed-only cleanup procedure, and scout promotion. +- `backlog-management` will own backlog backend use, captain-call filing, automatic-transition expectations, cross-home handoff routing, reevaluation, and task-note hygiene. +- Existing `harness-adapters`, `quota-array-dispatch`, `bootstrap-diagnostics`, `stuck-crewmate-recovery`, `secondmate-provisioning`, `captain-hold-lifecycle`, `pr-review-policy`, `fmx-respond`, `stow`, and `updatefirstmate` retain their current precise procedures rather than receiving duplicate prose. + +## Safety retention checklist + +- Hard rules 1-5 remain verbatim. +- The captain-address rule remains always loaded. +- The lock-refused posture remains always loaded and read-only. +- The generation-bound wake acknowledgement remains always loaded. +- Merge authority remains protected by hard rule 2, the captain-precedence boundary, a concise task-lifecycle stub, `task-delivery`, and the exact guarded merge owners. +- Unlanded-work protection remains protected by hard rule 3, the captain-precedence boundary, a concise task-lifecycle stub, `task-delivery`, and `bin/fm-teardown.sh`. +- The full supervision cycle and away/quiet safety stub remain always loaded. diff --git a/docs/documentation-audiences.json b/docs/documentation-audiences.json index d70e9bcaa64..947f48a402e 100644 --- a/docs/documentation-audiences.json +++ b/docs/documentation-audiences.json @@ -292,6 +292,10 @@ "path": "docs/agent-control.md", "audience": "maintainer-architecture" }, + { + "path": "docs/agents-md-audit.md", + "audience": "maintainer-architecture" + }, { "path": "docs/architecture.md", "audience": "maintainer-architecture" From b48edd81bf587348d1da57ba4297cb731d30976e Mon Sep 17 00:00:00 2001 From: twilwa Date: Tue, 22 Sep 2026 07:56:57 +0200 Subject: [PATCH 2/6] docs: slim always-loaded Firstmate contract --- .agents/skills/ask-user-authority/SKILL.md | 2 +- .agents/skills/backlog-management/SKILL.md | 37 ++ .../skills/captain-hold-lifecycle/SKILL.md | 2 +- .agents/skills/project-management/SKILL.md | 4 +- .agents/skills/quota-array-dispatch/SKILL.md | 4 +- .../skills/secondmate-provisioning/SKILL.md | 2 +- .agents/skills/task-delivery/SKILL.md | 106 +++++ .agents/skills/task-intake/SKILL.md | 117 +++++ AGENTS.md | 435 +++--------------- docs/agents-md-audit.md | 1 + docs/architecture.md | 4 +- docs/configuration.md | 6 +- docs/documentation-audiences.json | 12 + 13 files changed, 343 insertions(+), 389 deletions(-) create mode 100644 .agents/skills/backlog-management/SKILL.md create mode 100644 .agents/skills/task-delivery/SKILL.md create mode 100644 .agents/skills/task-intake/SKILL.md diff --git a/.agents/skills/ask-user-authority/SKILL.md b/.agents/skills/ask-user-authority/SKILL.md index 19bf0be8ee9..2aa551dab6c 100644 --- a/.agents/skills/ask-user-authority/SKILL.md +++ b/.agents/skills/ask-user-authority/SKILL.md @@ -13,7 +13,7 @@ metadata: # ask-user-authority This skill is the single owner of the decision policy for no-mistakes ask-user findings. -`AGENTS.md` section 7 points here and does not restate this procedure. +`task-delivery` and `AGENTS.md` section 13 point here and do not restate this procedure. Finding authority is determined by the criteria below, not by `yolo`. Firstmate always applies this judgment, decides any finding that is unambiguous toward the accepted design, and escalates only genuinely ambiguous, expanding, or destructive findings. diff --git a/.agents/skills/backlog-management/SKILL.md b/.agents/skills/backlog-management/SKILL.md new file mode 100644 index 00000000000..31419cac86d --- /dev/null +++ b/.agents/skills/backlog-management/SKILL.md @@ -0,0 +1,37 @@ +--- +name: backlog-management +description: >- + Agent-only policy for filing, holding, handing off, updating, reviewing, and closing work in a Firstmate backlog. + Load before any backlog mutation, captain-call filing, cross-home backlog handoff, task-note replacement, or queue review after teardown or heartbeat. +user-invocable: false +metadata: + internal: true +--- + +# Backlog management + +The configured `tasks-axi` backend is the durable queue; the tracked default is `data/backlog.md`. +It tracks work items only, never agents; persistent secondmates never appear as backlog items. +Work routed to a secondmate is recorded in that secondmate home's own backlog, not the main backlog. + +A decision is simply a task held for the captain. +Create the task with `bin/fm-tasks-axi.sh add` when needed, then always hold it through `bin/fm-captain-hold.sh hold --reason ""`. +Add `--until ` only when the call itself should stay gated until that date; a captain's own "later" is a recorded answer, never a bare re-hold. +When a main-side thread such as a pending captain decision or Relay reminder is worth durable tracking, file it as its own work item and hold it through that wrapper. +Captain calls discovered by investigations or visual reviews follow `captain-hold-lifecycle`, which owns their completion gate and recorded-answer rules. + +When the automatic transition gate applies, dispatch and completion move the item themselves. +[`bin/fm-spawn.sh`](../../../bin/fm-spawn.sh) and [`bin/fm-teardown.sh`](../../../bin/fm-teardown.sh) own those transitions and refuse rather than report success without them. +What remains yours is filing the item before dispatch, recording decisions, and keeping notes current. +[`docs/configuration.md`](../../../docs/configuration.md) owns gate applicability and the manual-backend exception. +Re-evaluate queued work after every teardown and heartbeat, dispatching items only when dependencies and time gates have cleared. + +`.tasks.toml`, `docs/configuration.md`, and current `tasks-axi --help` own the backlog schema, compatibility, retention, and routine command syntax. +Use compatible `tasks-axi` when the configured backend selects it, always through `bin/fm-tasks-axi.sh` so the call reaches this home's backlog from any directory. +Use the documented manual path otherwise and keep only the configured recent Done entries. +`secondmate-provisioning` and `bin/fm-backlog-handoff.sh` own cross-home handoff safety. + +Keep free-form notes free of temporary paths, moving versions, ephemeral identifiers, and copied state that will rot. +Inspect the current task note before replacing its considered body, and archive the superseded body when recoverability matters rather than appending by default. +Verify volatile details against their authoritative config, live system, or API before acting, and correct or delete stale prose immediately. +Preserve durable structured identifiers, dependencies, and completion artifact links, and route reusable knowledge through `AGENTS.md`'s project and knowledge management contract rather than scattering it through task notes. diff --git a/.agents/skills/captain-hold-lifecycle/SKILL.md b/.agents/skills/captain-hold-lifecycle/SKILL.md index a0bec8fd301..329083b51ca 100644 --- a/.agents/skills/captain-hold-lifecycle/SKILL.md +++ b/.agents/skills/captain-hold-lifecycle/SKILL.md @@ -30,7 +30,7 @@ Only `answer` with the captain's words or an evidence-backed `reconcile close` m Never close anything the captain owns without recording what he actually said: `bin/fm-captain-hold.sh answer` writes his exact words into the task and closes a question-shaped call, while `--release` frees a captain-gated work item to proceed. A merge approval uses that existing release path because approval permits the merge to proceed; cleanup closes the work only after it lands and records what shipped. Closing a held row at merge approval instead records completion before landing, so the backlog claims completion before the work actually ships. -When the answer changes what a task must build, follow `AGENTS.md` section 7's Validate contract to preserve the captain's words in the brief and steer the worker. +When the answer changes what a task must build, load `task-delivery` and follow its Validate contract to preserve the captain's words in the brief and steer the worker. When the captain says "later", that is an answer too: give the keyed-answer intake its `defer` close mode and a YYYY-MM-DD date, or use `answer --defer-until ` for a direct answer, so the captain's exact words are recorded before the existing `tasks-axi hold --until` gate leaves the item dated and held on the same call, with its original age basis intact. A recorded-answer defer date must be strictly later than today's UTC date; past and same-day dates are refused before the captain's words are recorded, while bare `hold --until` remains the calendar-only scheduling primitive. A defer without a date is refused rather than assigned a default. diff --git a/.agents/skills/project-management/SKILL.md b/.agents/skills/project-management/SKILL.md index 86e37422d17..d58637a4971 100644 --- a/.agents/skills/project-management/SKILL.md +++ b/.agents/skills/project-management/SKILL.md @@ -25,7 +25,7 @@ Keep each registry description useful for identifying the project, but keep deli 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. +Apply `task-intake`'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. @@ -35,7 +35,7 @@ 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. +The registry records the project's standing posture, which is the captain's default for the work rather than any task's answer; `task-intake` owns how each task's concrete mode and yolo are resolved at intake and passed explicitly to the brief and spawn, while `task-delivery` owns promotion. Choose that posture when adding or creating the project: - `no-mistakes` runs the full validation pipeline before a PR. diff --git a/.agents/skills/quota-array-dispatch/SKILL.md b/.agents/skills/quota-array-dispatch/SKILL.md index 4b988f1baab..ec96d7eb92a 100644 --- a/.agents/skills/quota-array-dispatch/SKILL.md +++ b/.agents/skills/quota-array-dispatch/SKILL.md @@ -13,7 +13,7 @@ metadata: # 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. +`task-intake` owns the intake boundary, load trigger, and malformed-config refusal; this skill owns every-candidate accounting and strongest-reasoning and 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. @@ -29,7 +29,7 @@ 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. omp has no primary family, so the helper keys an `omp:` candidate on its model prefix, mapping only `openai-codex/` and `claude-bridge/` and refusing every other prefix; the helper's header owns that mapping. -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. +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, 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`. diff --git a/.agents/skills/secondmate-provisioning/SKILL.md b/.agents/skills/secondmate-provisioning/SKILL.md index f716d5e960c..c232922d09b 100644 --- a/.agents/skills/secondmate-provisioning/SKILL.md +++ b/.agents/skills/secondmate-provisioning/SKILL.md @@ -181,7 +181,7 @@ Treat an inherited queue that carries plans with no matching delivery record as ## Backlog handoff -Apply `AGENTS.md` section 10's work-items-only backlog contract before creation or handoff. +Load `backlog-management` and apply its 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: diff --git a/.agents/skills/task-delivery/SKILL.md b/.agents/skills/task-delivery/SKILL.md new file mode 100644 index 00000000000..46f747ee495 --- /dev/null +++ b/.agents/skills/task-delivery/SKILL.md @@ -0,0 +1,106 @@ +--- +name: task-delivery +description: >- + Agent-only procedure for validating, reviewing, landing, cleaning up, and promoting Firstmate ship and scout work. + Load before starting or steering validation, on validation or delivery milestones, after a ship or scout reports done, before any merge or local landing, before teardown, and before scout promotion. +user-invocable: false +metadata: + internal: true +--- + +# Task delivery + +This skill owns the conditional path from implementation through a landed ship or completed scout. +The hard rules, captain instruction precedence, unlanded-work protection, and captain-facing communication contract remain always loaded from [`AGENTS.md`](../../../AGENTS.md). +Referenced tools and script headers own exact commands, flags, formats, and data mechanics. + +## Selected delivery path and merge authority + +The selected delivery path owns its own rigor. +When no-mistakes is selected, no-mistakes owns fixes, tests, documentation, push, PR, and CI. +Every GitHub PR also follows the captain-approved low/high-stakes review ledger owned by `pr-review-policy`; its independent PR review for high-stakes work is the one deliberate addition to the selected delivery path. +Do not stack any other serial manual review or infer one from security, architecture, or risk alone. +The path's worker, automated gates, and captain approval remain authoritative: + +- **no-mistakes** runs the full pipeline through a PR, then waits for the configured merge authority. +- **direct-PR** has the worker push and open a PR without the no-mistakes pipeline, then waits for the configured merge authority. +- **local-only** has the worker stop with a clean ready branch, then waits for the configured merge authority before firstmate uses the guarded fast-forward merge path. + +Delivery mode and `yolo` are orthogonal. +`yolo` governs ordinary merge authority: with it off, the captain approves every GitLab merge and every local-only landing; with it on, firstmate merges green, in-scope work itself. +The captain-approved GitHub review policy separately authorizes firstmate to merge a PR whose current ledger generation passes every low- or high-stakes gate, while unresolved product, rights, spend, destructive, security-sensitive, or other human decisions still hold it. +Never merge a red PR under either setting unless a current explicit captain instruction names the single GitHub check waived through `fm-pr-merge.sh --allow-red`; that attended-only waiver still requires every other check green. +Destructive, irreversible, and security-sensitive merges still escalate. +Without a current explicit captain instruction that states the concrete merge, the green default stands, and standing `yolo` cannot authorize a red merge. +`AGENTS.md` owns when a current explicit captain instruction overrides a Firstmate-written standing rule within its exact scope. +Load `ask-user-authority` before deciding any ask-user finding; the implementation worker never answers its own finding. +Use `bin/fm-pr-review.sh merge` for every GitHub task PR merge, `bin/fm-pr-merge.sh` directly for GitLab, and `bin/fm-merge-local.sh` for approved local-only landing. +Never call a lower-level merge command around their guards. +After an autonomous merge, give the captain a one-line full-URL or local-main outcome. +Before applying Ready for QA after a GitHub merge or deploy, load `pr-review-policy` and satisfy its head-keyed post-merge gate without weakening any pre-merge browser check. + +## Validate + +For a no-mistakes ship, trigger validation on the same worker after its implementation commit, using the harness invocation owned by `harness-adapters`. +The task worker that starts a no-mistakes run drives the pipeline and owns every `no-mistakes axi run` and `no-mistakes axi respond` call through the next gate or outcome. +Firstmate never invokes `no-mistakes axi respond` for a crew-owned run. +When the captain adds or changes an ask mid-task, append the captain's words without added speaker labels or direct address to that brief's `## Captain's intent` and relay those words to the worker. +Firstmate build constraints stay in `## Firstmate spec` or the steer. +[`bin/fm-dod-lib.sh`](../../../bin/fm-dod-lib.sh) owns the worker-side `--intent` contract. +Once validation starts, prefer routing new requirements to follow-up work rather than expanding the current task, unless a new requirement completely invalidates the work being validated. +The smallest downstream changes needed to keep already accepted product or engineering behavior correct, add behavioral tests where an executable contract exists, or keep documentation accurate remain within the current task even when they touch files not named at intake. +Corrections required to satisfy already accepted intent are not new requirements. + +Only a current, explicit captain instruction that completely invalidates the work being validated keeps the task with the same worker instead of routing it to follow-up work or handing it to a replacement. +That worker cancels the active run through no-mistakes axi's supported abort command and confirms through axi status that the run has stopped before changing any code. +The worker then follows `branch_sync.next_action` from structured axi status. +Use axi sync's supported guarded recovery only when its code is `recover_custody`, and otherwise proceed only when structured status confirms that branch ownership is already returned and no recovery is required. +Custody recovery settles branch ownership, not content. +The worker must replace the obsolete work from the correct pre-invalidation base rather than building on top of the recovered-but-obsolete head, keeping the obsolete run's own pipeline-fix commits out of what gets validated and shipped. +Apart from that single supported abort, do not hand-edit, commit, restart, or start a second validation run while the obsolete run still owns the branch. +Once ownership is settled, validate exactly once against that final head so no obsolete or intermediate head is ever treated as authoritative. + +An ask-user finding returns as `needs-decision`. +Firstmate loads `ask-user-authority` and either decides or escalates per that skill. +Send the same worker one exact decision naming the decision key, step, action, affected finding IDs, instructions where needed, and exact response command. +Pass `--resolve-key` so the worker's open decision record closes at answer time. +Require the matching `resolved` event, forbid `--yes`, and require the worker to process every synchronous return until completion or a genuinely new escalation. +Resume fleet supervision immediately after the decision lands. + +Judge validation by the currently attributed run step through `bin/fm-crew-state.sh`, not by shell liveness or the last status event. +Running, fixing, or CI states remain working; parked approval or fix-review states require the worker to follow the active gate help; passed or checks-passed is done; failed or cancelled is failed exactly as `bin/fm-crew-state.sh` prints it. +Only that state line reclassifies an orphaned CI monitor after green checks as held-for-merge done, or a run record the `daemon status` probe leaves unverified as unknown, never the raw run record. +A worker hand-editing, committing, aborting, or restarting during an active validation run duplicates pipeline ownership outside the supersession sequence above; steer it back to the gate response flow. +The worker reports the PR when CI first becomes green rather than waiting for merge monitoring to finish. + +## Ready, landing, and teardown + +For PR-based ship tasks, the ready signal depends on mode: `no-mistakes` reports `done [at=]: PR checks green` after CI is green, while `direct-PR` reports `done [at=]: PR ` after opening the PR. +Run `bin/fm-pr-check.sh ` with the URL copied from that ready signal. +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 GitHub PR, load `pr-review-policy`, initialize its durable head-keyed ledger, and arm its delayed checkpoint in the existing watcher. +Tell the captain the PR's full `https://...` URL copied from the worker's ready line or the task's `pr=` metadata, a concise outcome summary, and the no-mistakes risk level when applicable. +A captain instruction to merge is explicit authority; `yolo` and a passing current GitHub review-ledger generation are the only standing routine merge authorities. + +For any custom `state/.check.sh` you write yourself, keep it an ordinary single-link mode-`0700` file, print one line only when firstmate should wake, print nothing otherwise, finish before `FM_CHECK_TIMEOUT`, then bind its current bytes with `bin/fm-check-register.sh ` before the watcher may execute it. +Retire a custom check only through `bin/fm-check-unregister.sh ` or `bin/fm-teardown.sh` for a spawned task. +Never hand-compose an `rm` with `$STATE` or `$ID`. + +Tear down a ship task only after landing is confirmed. +A teardown refusal for uncommitted or unlanded work is a stop-and-investigate result, never an obstacle to bypass. +Never force teardown without explicit discard authority. +After successful teardown, record completion, retain only the configured recent Done history, and re-evaluate queued work whose blockers and time gates have cleared. + +A secondmate is persistent and an empty queue is healthy. +Retire one only on an explicit captain or main-firstmate decision, after loading `secondmate-provisioning`. +Its home must contain no work under way, and forced discard still requires explicit captain authority. + +## Scout outcome and promotion + +A completed scout must leave a self-contained report before its scratch worktree can be discarded. +Read and relay its findings, record the report as the Done artifact, and re-evaluate the queue. +A report may recommend implementation but does not authorize it. +Before treating the investigation or any visual review as complete, load `captain-hold-lifecycle`; teardown enforces that shared completion gate. +When a scout's deliverable is a visual artifact the captain will iterate on, prefer keeping that scout alive to host its own Lavish loop rather than tearing it down and mediating from firstmate. +When implementation is separately authorized, promote the existing scout through `bin/fm-promote.sh` rather than creating a duplicate task. +The promoted worker must inventory scratch state, return to a clean default-branch base, carry over only intended fix changes, create the ship branch, and follow the project's selected delivery path while leaving scratch commits and debug edits behind and turning a reproduced bug into the regression test. diff --git a/.agents/skills/task-intake/SKILL.md b/.agents/skills/task-intake/SKILL.md new file mode 100644 index 00000000000..882bdc55210 --- /dev/null +++ b/.agents/skills/task-intake/SKILL.md @@ -0,0 +1,117 @@ +--- +name: task-intake +description: >- + Agent-only procedure for resolving, classifying, briefing, dispatching, and steering Firstmate ship and scout work. + Load before classifying a new project request, choosing ship or scout, selecting delivery mode or dispatch profile, writing or changing a task brief, spawning a ship or scout, or steering its worker. +user-invocable: false +metadata: + internal: true +--- + +# Task intake + +This skill owns the judgment from a new request through a verified supervision handoff. +The hard rules, captain instruction precedence, and captain-facing communication contract remain always loaded from [`AGENTS.md`](../../../AGENTS.md). +Referenced scripts own exact commands, flags, generated text, and data mechanics. + +## Resolve and classify + +Resolve the project independently for every request. +An explicit project wins, a clear follow-up inherits its referent, and otherwise match the request against the registry, work under way, and project code or README. +Proceed on one confident match while naming the project in plain language; ask one concise question when multiple or no projects plausibly match. + +Route by the nature of the work against each registered secondmate scope, not by a non-exclusive clone list. +Keep `local-only` work in the main home. +Send in-scope work to the fitting secondmate unless it is blocked or the captain explicitly redirects it; do not read the secondmate's chat because marked routed replies return through its status or referenced document. +If no secondmate scope fits, use the main home or discuss creating an appropriate persistent secondmate. +For one-off or infrequent operational work, start with the simplest direct end-to-end path. +Do not build wrappers, control planes, policy layers, custom verifiers, or automation unless the direct path exposes a concrete blocker or repeated need that justifies the added machinery. + +Before commissioning an investigation, consult existing reports and established evidence. +Classify the deliverable: + +- **Ship** is the default and produces a project change through the selected delivery mode; once implementation is authorized, dispatch a ship and keep any remaining bounded research inside it unless unresolved uncertainty could materially change whether or what to build. +- **Scout** produces knowledge in `data//report.md`, never a PR, and is appropriate for investigation, diagnosis, planning, reproduction, or audit work when the captain explicitly requests a separate knowledge or design deliverable or unresolved uncertainty could materially change whether or what to build. + +If established evidence already answers an informational question, relay it without a design-only scout; when implementation intent is unclear, answer and ask one concise implementation question when useful rather than dispatching speculative design work. +Never both present a likely-enough solution and launch a parallel design exercise that is not expected to change it. +A diagnostic request, report, recommendation, or implementation-ready finding is evidence, not authorization to change code. +Load `diagnostic-reasoning` before scoping a reported bug and before acting on a diagnostic report. + +## Delivery mode and concurrency + +Resolve every ship task's concrete delivery mode and `yolo` merge posture at intake. +Pass the mode explicitly to the brief, and pass both values explicitly to the spawn and any scout promotion; each command refuses to guess the values it consumes. +A current explicit captain instruction wins; otherwise the project's registry entry is the captain's standing posture, and dropping below its rigor needs a reason you can state. +On a `no-mistakes-prod-only` project, classify the task's surface: 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`; never infer internal-only from file location or project name. +An unregistered project or absent registry resolves to `no-mistakes` with yolo off, and the registration gap goes to the captain. +Record the resulting mode, `yolo` merge posture, and the one-line reason for any deviation in the backlog item note. + +Treat file or subsystem overlap as a risk signal rather than an automatic reason to wait, and dispatch isolated work immediately with no concurrency cap when each change can be independently implemented and validated and the selected delivery path can reconcile ordinary rebases or conflicts. +Serialize only for a true semantic dependency, shared mutable external state, incompatible concurrent migration, or another concrete condition that makes independent progress or reconciliation unsafe; same-file editing alone is insufficient, and genuine blockers remain durable. + +## Resolve the worker profile + +Load `harness-adapters` before every spawn or recovery and before trust handling, skill invocation, interrupt, exit, resume, or adapter verification. +Never dispatch on an unverified adapter. +If static `config/crew-harness` or `config/secondmate-harness` names an unverified adapter, follow that skill's fallback and reporting policy. + +[`docs/configuration.md`](../../../docs/configuration.md) owns dispatch-profile and runtime-backend schemas, [`bin/fm-harness.sh`](../../../bin/fm-harness.sh) owns static resolution, and [`bin/fm-spawn.sh`](../../../bin/fm-spawn.sh) owns launch flags and fail-closed validation. +When dispatch profiles exist, consult them at every crewmate or scout intake and pass the resolved concrete profile required by `fm-spawn`. +Routing precedence is an explicit per-task captain override, then the best-fit configured rule, then the configured default, then the static crewmate harness. + +Firstmate alone resolves a matched profile array. +Load `quota-array-dispatch` before choosing among one; that skill is the single owner of the current-quota, eligibility, reasoning-class, runway-feasibility, and `spendPriority` procedure. +Preserve malformed profile configuration as an actionable error rather than selecting around it. + +Run `bin/fm-dispatch-resolve.sh` directly on the written brief in the same turn, with no preflight. +On `clear`, pass its `profile:` line to `fm-spawn` unless you state a reason to override, then rerun the same script with `--record-dispatch` for the profile you actually dispatched. +`ambiguous`, `escalate`, `error`, and off all mean the judgment-based intake above, unchanged, and record no dispatch; [`docs/configuration.md`](../../../docs/configuration.md) "Typed dispatch resolution" owns the contract. +The generic effort fallback and its precedence are owned by `harness-adapters`; do not add model-specific versions of that policy. + +`secondmate-provisioning` owns secondmate harness pins and inherited local material, while `harness-adapters` owns the harness consequences. +Dispatch only on a backend that `fm-spawn` validates as spawn-capable. +Pass an explicit per-spawn `--backend` only under that exact task's own authority, never as later-task precedent. +A missing dependency, authentication failure, unsupported backend, or version refusal is a blocker; never silently retry on another backend. + +## Write the brief + +[`bin/fm-brief.sh`](../../../bin/fm-brief.sh) and its help own scaffold syntax, generated variants, status protocol, delivery-mode definitions of done, and exact safety mechanics. +Use its scaffold as the contract, then fill `## Captain's intent` (`{TASK}`) with the captain's own ask and any boundary the captain stated, plus the context needed to read it, including the substance of any report, decision, or PR the ask refers to. +Never widen the ask there into a general goal or an enumerated coverage list, because the reviewer treats that subsection as acceptance criteria. +Fill `## Firstmate spec` (`{FIRSTMATE_SPEC}`) with only the build instructions that ask requires, naming what stays out of scope when the ask is narrow. +A generalization, consistency sweep, or extra hardening the captain did not ask for is follow-up work to note, not scope to add. +[`bin/fm-dod-lib.sh`](../../../bin/fm-dod-lib.sh) owns intent authoring without added speaker labels or direct address, its provenance markers, what a no-mistakes worker may pass as `--intent`, and the string's self-sufficiency rule. +Keep additions task-specific rather than repeating lifecycle instructions, and alter generated sections only when the task genuinely differs from the standard shape. + +Every ship brief must retain the worktree-isolation assertion and stop if launched in the primary checkout. +If a ship task touches Firstmate's shared tracked material, explicitly require `firstmate-coding-guidelines` before editing. +If a task will drive Herdr lifecycle behavior, scaffold with `--herdr-lab`; if that need appears after an unguarded scaffold, stop and regenerate rather than adding commands by hand. +The generated Herdr contract must use a named non-`default` isolated lab and its guarded helper for every lifecycle action. + +Load `secondmate-provisioning` before creating or using a charter brief and preserve its idle-by-default and marked-return-channel contracts. +Status appends are sparse supervisor-actionable events, not routine progress; [`bin/fm-classify-lib.sh`](../../../bin/fm-classify-lib.sh) owns keyed open and resolved semantics. +The scaffold is a safety contract, not a suggestion. + +## Spawn and hand off supervision + +Spawn only through `bin/fm-spawn.sh` after the profile and backend checks above. +The spawn must resolve a genuine isolated task worktree distinct from the primary checkout; a failed isolation assertion stops the task. +When the configured tasks-axi backlog gate applies, the spawn itself moves the work item to In flight and refuses rather than dispatching work this home has no item for. +A manual-backend home retains the hand-editing contract in `docs/configuration.md`. +After spawning, confirm the worker is processing the brief and handle any trust dialog through `harness-adapters`. +A persistent secondmate is recorded in the secondmate registry and runtime state, never as a backlog work item. + +Steer a worker with ordinary text through fail-closed `fm-send`. +The message becomes a durable record in the task's steering inbox, and the worker's terminal receives only a constant doorbell line. +[`bin/fm-task-inbox-lib.sh`](../../../bin/fm-task-inbox-lib.sh) and [`bin/fm-send.sh`](../../../bin/fm-send.sh) own inbox and typed-plane mechanics. +A remote secondmate steer uses the same durable-inbox model. +After an unconfirmed delivery, only the exact `FM_PENDING_REPLY_EXISTING_CORR=` resend command printed by `fm-send` is safe because it preserves the request body for remote enqueue deduplication. +When a steer answers an open keyed decision or blocker, pass `fm-send`'s `--resolve-key` so the answer itself closes that decision record at answer time. + +`fm-send` is the data plane for text the worker should read. +Never use its key or text paths for interrupt, exit, or other lifecycle control, because routing-marked lifecycle text becomes chat the worker reasons about instead of executing. +Drive a worker's lifecycle through `bin/fm-control.sh interrupt|exit|relaunch`, which owns the per-runtime mechanics, verifies each action, and never tears down or discards anything. +A secondmate's routed reply returns through status or a document pointer, not by firstmate peeking into its chat. +[`bin/fm-pending-reply-lib.sh`](../../../bin/fm-pending-reply-lib.sh) owns parent-side correlation, recovery, and escalation for marked secondmate requests. +After the handoff, follow the always-loaded supervision contract in `AGENTS.md`. diff --git a/AGENTS.md b/AGENTS.md index a790c78b03e..fd115a74c4f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,225 +50,59 @@ Never add an agent name as a commit co-author. ## 2. Layout and state -`docs/configuration.md` is the single owner of the top-level operational-home layout and configuration schemas; each producing script's header and help own exact child fields and mutation mechanics. +[`docs/configuration.md`](docs/configuration.md) is the single owner of the top-level operational-home layout and configuration schemas; each producing script's header and help own exact child fields and mutation mechanics. `FM_HOME` selects an instance's private `data/`, `state/`, `config/`, and `projects/`, while scripts continue to come from their tracked code root. Each secondmate has a persistent isolated `FM_HOME`, including its own state, backlog, projects, and session lock. `bin/fm-send.sh` fails closed unless `FM_HOME` is explicit, so a steer cannot silently resolve against another home. -Tracked files hold shared instructions and tooling; `data/` holds durable private fleet records; `state/` holds runtime records and append-only status events; `config/` holds local operating choices; and `projects/` contains clones that are read-only to firstmate except under hard rule 1's concrete captain-approved project operation exception. - -``` -AGENTS.md this file (CLAUDE.md is a real @AGENTS.md pointer to it) -CONTRIBUTING.md contributor workflow and repo conventions -README.md public overview and development notes -.github/workflows/ shared CI and PR enforcement, committed -.tasks.toml tracked tasks-axi markdown backend config for the default backlog backend (section 10) -.agents/skills/ firstmate-loaded internal skills, committed; each carries metadata.internal=true for installers -.claude/skills symlink to .agents/skills for claude compatibility -.claude/mods/ Claude Code mods (function-hooks plugins), committed; Calm's module may load through CLAUDE_CODE_ENABLE_FUNCTION_HOOKS or tengu_plugin_hooks_modules, but activates only when CLAUDE_CODE_ENABLE_FUNCTION_HOOKS is exactly "1" and is otherwise a complete no-op (docs/calm.md) -skills/ standalone public installer-facing skills, committed; not loaded by firstmate -bin/ helper scripts, committed; read each script's header before first use -.env optional Relay pairing token (presence-gates section 14), mail-plane credentials (schema: docs/configuration.md "Mail plane"), and typed dispatch resolution key TYPESAFE_API_KEY (presence-gates bin/fm-dispatch-resolve.sh; docs/configuration.md "Typed dispatch resolution"); LOCAL, gitignored -config/crew-harness crewmate harness override; LOCAL, gitignored; absent or "default" = same as firstmate. Inherited as the literal file: a concrete primary adapter value also controls a secondmate home's own crewmates (section 4) -config/claude-permission-mode optional one-token permission posture for every Claude worker launch: absent or "bypass" keeps --dangerously-skip-permissions, "auto" launches with --permission-mode auto; LOCAL, gitignored; inherited by secondmate homes; see docs/configuration.md "Claude permission mode" -config/crew-dispatch.json optional crewmate dispatch profiles; LOCAL, gitignored; firstmate-maintained but human-editable natural-language rules that choose a per-task harness/model/effort profile (section 4). Inherited by secondmate homes -config/secondmate-harness harness the PRIMARY uses to launch SECONDMATE agents, optionally followed by a model and effort token on the same line (" [] []"; section 4); LOCAL, gitignored; absent or "default" harness falls back to config/crew-harness then firstmate's own. The primary's own setting; NOT inherited into secondmate homes (secondmates do not spawn secondmates) -config/backlog-backend backlog backend override; LOCAL, gitignored; absent or "tasks-axi" = the configured tasks-axi backend, "manual" = force routine backlog updates to hand-editing; inherited by secondmate homes (section 10) -config/backend runtime session-provider backend override for new tasks; LOCAL, gitignored; absent = falls through to runtime auto-detection (the runtime firstmate itself is executing inside), then tmux; tmux is the verified reference backend (docs/tmux-backend.md), herdr has its own required CI lane (docs/herdr-backend.md), while zellij, orca, and cmux remain experimental with no dedicated real-backend CI lane (docs/zellij-backend.md, docs/orca-backend.md, docs/cmux-backend.md) - herdr and cmux can also be selected by runtime auto-detection, zellij and orca never are (always explicit), and codex-app is not accepted; see docs/codex-app-backend.md; inherited by secondmate homes under the primary-authoritative contract in secondmate-provisioning -config/calm Calm presentation preference shared by the Pi extension and the Claude Code mod; LOCAL, gitignored, and not inherited; see docs/configuration.md "Calm preference" -config/supervision-branch-model config/supervision-branch-effort Pi supervision-branch model and reasoning-effort pins written by /supervision-model; LOCAL, gitignored, independently settable, and not inherited; see docs/configuration.md "Pi supervision branch model and effort" -config/startup-memory-budget primary-authoritative per-home startup-memory budget; LOCAL, gitignored, materialized as 7,500 estimated tokens by locked primary bootstrap and inherited into secondmate homes; see docs/configuration.md "Startup memory budget" -config/stow-pass-horizon optional presence flag opting this home in to /stow's default-off pass-count decay horizon; LOCAL, gitignored, and not inherited; see docs/configuration.md "Stow pass horizon" -config/herdr-presentation-spaces optional "off" opt-out from, or "on" opt-in to, Herdr's default-on disposable single-task visual projection, which is unconfigured-default-on only at or above a Herdr version floor; LOCAL, gitignored; inherited by secondmate homes; see docs/herdr-backend.md "Presentation spaces" -config/trace-context optional presence flag enabling default-off native W3C trace-context propagation to spawned agents; LOCAL, gitignored; inherited by secondmate homes; see docs/configuration.md "Trace context propagation" and docs/trace-context.md -config/turnend-churn-absorb optional presence flag opting this home into the default-off absorb of bare turn-end wakes on pane churn; LOCAL, gitignored, and not inherited; see docs/configuration.md "Turn-end pane-churn absorb" -config/wedge-defer-parked-gate optional presence flag opting this home into the default-off deferral of a wedge escalation for a lane parked at a validation gate awaiting the supervisor's own still-open decision; LOCAL, gitignored, and not inherited; see docs/configuration.md "Parked-gate wait deferral" -config/cmux-socket-password optional cmux control-socket password; LOCAL, gitignored; read fresh on every cmux CLI call and passed through without ever overriding an operator's own ambient CMUX_SOCKET_PASSWORD when absent (docs/cmux-backend.md "Setup") -config/wedge-alarm optional away-mode wedge-alarm active-alert directives; LOCAL, gitignored; absent means auto (macOS Notification Center when available); see docs/wedge-alarm.md -config/watched-tools.json optional list of the tools this home depends on, read by the update check armed with bin/fm-tool-update-check.sh; LOCAL, gitignored, firstmate-maintained but human-editable, and NOT inherited by secondmate homes; see docs/configuration.md "Watched tool updates" -config/x-mode.env generated Relay watcher cadence; LOCAL, gitignored; source before arming watcher when present -data/ personal fleet records; LOCAL, gitignored as a whole - backlog.md task queue, dependencies, history - captain.md this home's domain-local captain preferences and working style; LOCAL, gitignored, canonical even if harness memory mirrors it, and updated with inspect-then-update - captain-shared.md main-authoritative shared captain preferences propagated read-only to secondmate homes; LOCAL, gitignored, owned by secondmate-provisioning - learnings.md fleet-local operational facts and gotchas; LOCAL, gitignored; dated, evidence-backed, curated, and updated with inspect-then-update - rewrite and prune rather than append forever, the same contract as captain.md; created lazily, absent until this home has a learning to store - pr-review-ledger/ default configured location for durable per-PR, per-head review ledgers; .github/firstmate-review-policy.json selects the data-relative directory and bin/fm-pr-review.sh owns the format and lifecycle - projects.md thin fleet navigation registry recording each project's standing delivery posture; firstmate-private, parsed for mechanical sync and seeding by fm-project-mode.sh (section 6) - secondmates.md local and remote secondmate routing table; firstmate-private, maintained by the secondmate seed helpers (section 6) - /brief.md per-task crewmate brief, or per-secondmate charter brief when kind=secondmate - /report.md scout task deliverable, written by the crewmate; survives teardown -projects/ cloned repos; gitignored; read-only except under hard rule 1's concrete captain-approved project operation exception -state/ runtime records and signals; gitignored - .status append-only wake events, not current-state truth; bin/fm-classify-lib.sh owns their syntax - .turn-ended touched by turn-end hooks - .progress touched for observed native-harness activity inside one Pi turn; bin/fm-busy-event.sh owns its generation binding and bin/fm-watch.sh reads it beside turn-ended for the busy-age bound only, never as a completed turn - .busy-state .busy-gen semantic busy-state record (one line, atomically replaced) and its per-incarnation gen sidecar; bin/fm-busy-event.sh is the only writer and bin/fm-busy-lib.sh owns the record format and classification; arming again replaces the previous incarnation so late events carrying its gen are rejected as stale; removed by retire and teardown - .grok-turnend-token firstmate-owned grok hook registry token for the task; removed by teardown - .kimi-turnend-token firstmate-owned Kimi hook registry token for the task; removed by teardown - .gemini-settings.json firstmate-owned per-task Gemini settings carrying the busy-state and turn-end hooks, reached through GEMINI_CLI_SYSTEM_SETTINGS_PATH so nothing is written into the project's own .gemini/; removed by teardown - .muse-session muse busy-source binding (sessions root plus task worktree) written by fm-spawn; removed by teardown - .cursor-session cursor busy-source binding (projects root, task worktree, prior conversations) written by fm-spawn; removed by teardown - .reconcile-nudged epoch second of the last inventory-reconcile nudge sent to this secondmate; bin/fm-secondmate-reconcile.sh owns its per-home cooldown window - .backlog-close the exact backlog transition a teardown recorded before removing the task's record, so an interrupted cleanup can still be finished at the next session start; bin/fm-backlog-transition-lib.sh owns its format and replay, and a landed transition removes it - .inbox/ durable steering inbox: sequenced firstmate instruction records the worker acknowledges by moving them into its handled/ subdirectory; written by fm-send, with ordinary records re-rung and escalated by the watcher while explicit fire-and-forget records are excluded from that ladder, and removed by teardown (bin/fm-task-inbox-lib.sh) - .meta task metadata; each producer script's header owns its exact fields and mutation contract, with docs/configuration.md routing operator-facing backend and trace-context details - .herdr-presentation quarantinable attempt and restart-binding journal for Herdr's optional visual projection; never task or endpoint authority; see docs/herdr-backend.md "Presentation spaces" - .check.sh authenticated slow poll; the watcher dispatches validated PR data and the byte-identified Relay shim through trusted repository scripts, runs registered custom checks from hash-validated private snapshots, and rejects every other state check without execution - .check-trust private content binding created by fm-check-register.sh for an intentional custom check - review-policy.check.sh review-checkpoint shim registered inside the existing watcher by bin/fm-pr-review.sh; never a second monitor - .pr-poll private validated data sidecar for the byte-static PR merge poll - .pr-poll-registration private transactional provenance record binding the task, canonical metadata identity, sidecar, and static poll publication - .pr-poll-retirement private identity-bound crash-recovery receipt for one exact validated merged result; removed after its poll artifacts retire - .merge-authority private canonical-PR-bound authority persisted after firstmate's forge merge request is accepted and consumed by a later merged poll; bin/fm-merge-authority-lib.sh owns its format and lifecycle - .pr-poll-merge-notified canonical PR identity of the last merge outcome delivered for this task; bin/fm-pr-lib.sh owns the marker format and identity mechanics, while bin/fm-merge-outcome-lib.sh owns locked publication, duplicate suppression, and replacement - branch-outcomes.jsonl .branch-outcomes-cursor .branch-outcomes-processed ..branch-outcome-index .branch-outcome-index-ready Pi supervision-branch durable outcome store, its read cursor, main's processed marker, bounded latest per-task status-coverage caches, and their recovery marker; bin/fm-branch-outcome.sh owns the formats - branch-session/ .branch-session .branch-mirror-cursor the branch's per-main-session conversations, the pointer to the current one, and the dialog-mirror cursor; extension-owned (docs/pi-supervision-branch.md) - .branch-eligible-rows .branch-eligible-owner .main-eligible-rows per-actor wake-row claims and branch-owner evidence; docs/watcher-continuity.md owns the acknowledgement contract - .lease- per-task supervision lease naming which actor (main or branch) may change that task; bin/fm-lease-lib.sh owns the contract the guarded scripts enforce - x-watch.check.sh generated Relay poll shim; present only when opted in (section 14) - tool-updates.check.sh generated watched-tool update poll shim and its .check-trust binding; present only after bin/fm-tool-update-check.sh arm; its report record .tool-updates is what keeps one pending update from being reported on every poll - mail.check.sh generated received-mail poll shim and its .check-trust binding; present only after bin/fm-mail-check.sh arm; report record .mail-check (mail schema: docs/configuration.md "Mail plane") - .mail-seen .mail-woken .mail-retry .mail-retry-pos .mail-turn .mail-seen.lock mail-plane poll cursor, emission journal, transient-fetch retry set, retry-scan position, contended-slot turn flag, and overlapping-poll lock; written only by bin/fm-mail.sh (mail schema: docs/configuration.md "Mail plane") - pending-replies/ parent-owned secondmate pending-reply records (correlation id, delivery vs reply, recovery, escalation); fm-pending-reply-lib.sh - procevent/ registered process-to-event sources, one private record per canonical source id; written only by bin/fm-procevent.sh, and their presence alone keeps supervision required (section 13) - procevent-inbox/ private captured results and their durable handled-acknowledgement markers; source output lives here and never in an event line - decision-bindings/ private records marking a captured-answer source as feeding the keyed-answer intake, with a legacy origin on pre-collapse records; written only by bin/fm-captain-hold.sh bind, dropped by unbind and by source retirement (section 13; docs/captain-hold-lifecycle.md) - reconcile-requests/ private open obligations to re-check a captain call whose board selection was `reconcile`; written only by bin/fm-captain-hold.sh, retired by its verify-then-decide outcomes or a normal answer that settles the call (section 13; docs/captain-hold-lifecycle.md) - when/ private condition->action watch specs, their trust bindings, and single-fire markers; written only by bin/fm-procevent-when.sh (section 13's process-event-sources trigger) - inbox/ captain notes captured out of band by bin/fm-inbox.sh, including the voice handover's queued requests; each note appends one `check` wake and stays pending until acknowledged with `bin/fm-inbox.sh drain --ack `, which moves it to inbox/handled/ (docs/voice-relay.md) - x-inbox/ generated Relay pending mention payloads; fmx-respond drains it (section 14) - x-context/ generated Relay 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) - x-outbox/ generated Relay dry-run reply and dismiss previews; inspect it when FMX_DRY_RUN is set (section 14) - public-followup/ generated private transport for promised public replies: retained open-loop registrations, typed terminal-result inbox, results staged for an owning home on another machine, accepted/rejected ledgers, and retirement receipts (section 14; bin/fm-public-followup.sh) - x-poll.error x-poll.claim-error generated Relay and offer-claim diagnostic dedupe markers - .startup-network.* status, report, per-step elapsed timings, inline-print claim, and lock for the deferred startup stage that runs network checks and the inactive-outcome scan off the digest's blocking path; bin/fm-startup-network.sh - .wake-queue durable queued wakes retained until post-handling acknowledgement: epochseqkindkeypayload - .watcher-down private generation-bound recovery state coupling watcher downtime, durable wake presentation, and post-handling acknowledgement; never touch - ..open-decisions-cursor per-task byte cursor and folded open-decision set bounding the OPEN DECISIONS scan's cost to new status-log appends; written only by fm-classify-lib.sh's status_open_decisions_incremental, removed by teardown, safe to delete (forces one full re-fold) - .status-presentation-cursor .status-presentation-lock fleet-wide per-task status identity plus independent annotation and outcome-backstop byte offsets, with a serialization lock preventing already-presented lines from replaying while preserving delayed signal annotations; owned by fm-classify-lib.sh, with each task's row retired by teardown - .afk-contract the away-posture record: the captain's verbatim away words, expected return, reach profile, spend cap, and structured mandate clauses; written only by bin/fm-afk-contract.sh after the captain confirms the read-back, archived under afk-contracts/ at return; its presence IS the away posture in every harness; its sibling .afk-contract.lock serializes actions authorized by the live record (contract: bin/fm-afk-contract.sh) - afk-contracts/ archived away-posture records: one final record per away window keyed by entry time, plus any superseded mandates from that window - .afk durable away/quiet-mode daemon flag on the harnesses that still launch the daemon (never on Pi); present = sub-supervisor may inject escalations, first line `away` (default, set by /afk, cleared on user return) or `quiet` (set by /quiet, cleared only on explicit /quiet off) per the single owner fm_afk_mode() in bin/fm-wake-lib.sh - .lock-session trusted Claude session-lock sidecar; written only by bin/fm-lock.sh; never touch - .watch.lock .wake-queue.lock watcher singleton and queue serialization locks - .claude-autoarm.lock .claude-autoarm-epoch .claude-autoarm-failure-notified .claude-autoarm-failure-alarmed .turnend-claude-blocks .turnend-claude-blocks.lock Claude Stop auto-arm single-flight, epoch, failure-episode, attended-alarm, guard-budget, and budget-lock records; never touch - .cursor-park-owner .cursor-park-owner.lock .turnend-cursor-blocks Cursor stop-hook owner record, publication and commit lock, and bounded repair-nag budget; never touch - .hash-* .count-* .stale-* .stale-since-* .churn-since-* .paused-* .wedge-escalations-* .dead-reported-* .writing-* .waiting-* .seen-* .hb-surfaced-* .last-* .heartbeat-streak watcher internals; never touch - .watch-triage.log watcher's absorbed-wake debug log (size-capped); never relied on, safe to delete - .last-watcher-beat watcher liveness beacon, touched every poll (including while absorbing benign wakes); guard scripts read it - .subsuper-* .supervise-daemon.* sub-supervisor internals; never touch -.no-mistakes/ local validation state and evidence; gitignored -``` - A `state/.status` line is a wake event, not current-state truth; `bin/fm-crew-state.sh` owns current-state reconciliation. Treat `data/captain.md` as the domain-local record of captain preferences, optional `data/captain-shared.md` as the main-authoritative shared captain-preference file for secondmate inheritance, and `data/learnings.md` as curated home-local knowledge, regardless of harness memory. ## 3. Session start (run once at every session start) Run `bin/fm-session-start.sh` exactly once at session start. -Its header is the single owner of composed commands, ordering, and digest contents. -`bin/fm-supervision-instructions.sh` renders the emitted supervision block from `docs/supervision-protocols/`. -Do not reimplement it by separately running its lock, bootstrap, initial wake-drain, or deferred-network components. -Run-tier harness surfaces run this command for you at session open while the rest only nudge it, so confirm the digest is present in this session and run it yourself when it is not; `docs/sessionstart-nudge.md` owns adapter tiers, source routing, and compatibility. +Its header owns composed commands, ordering, digest contents, and the deferred network stage; `docs/sessionstart-nudge.md` owns which harness surfaces run or nudge it. +Confirm the digest is present in this session and run it yourself only when it is not. +Do not separately run its lock, bootstrap, wake-drain, or deferred-network components. Read the complete digest once and trust it as this turn's startup and recovery input. -If the harness shows only a preview and persists the full output to a file, read that file before acting. -Do not separately re-read the context, backlog, metadata, or bulk status inputs it just printed unless a source was reported absent or corrupt, older history is specifically needed, or a targeted workflow must inspect before writing. -An `ABSENT` captain, shared-captain, secondmate, or learnings file means the firstmate repo's built-in defaults, no shared captain preferences, no registered secondmates, or no captured learnings; rebuild an absent or stale project registry from the clones before dispatch. +If the harness persists the full output to a file, read that file before acting. +Do not re-read the context, backlog, metadata, or bulk status it just printed unless a source was absent or corrupt, older history is specifically needed, or a targeted workflow must inspect before writing. +An `ABSENT` captain, shared-captain, secondmate, or learnings file means the built-in defaults, no shared preferences, no registered secondmates, or no captured learnings; rebuild an absent or stale project registry from the clones before dispatch. If the session lock cannot be acquired and verified, report its exact diagnostic and remain read-only; another active session is only one possible cause. A lock-refused session must not spawn, steer, merge, drain the wake queue, repair supervision, repair a checkout, or perform any other fleet mutation. -The digest itself makes no external-network call and never waits for one. -Every network check a session start owes - GitHub auth, dead-secondmate relaunch, secondmate convergence, pending handoff delivery, and project clone refresh - runs off the digest's blocking path in a bounded worker owned by `bin/fm-startup-network.sh` and is reported in the digest's own `NETWORK CHECKS` section. -The locked startup inactive-outcome scan joins that worker so a slow local current-state read cannot block the digest; its findings use the ordinary durable wake queue. -When that section reports its checks still in progress it names exactly what is unconfirmed; treat none of those as passed until `bin/fm-startup-network.sh report` returns the finished result, while a failed or otherwise actionable result also arrives as a `check: startup-network` wake. - -1. **Lock** - acquires the per-home session lock first, before anything mutates shared state, then starts the deferred startup stage above. -2. **Bootstrap** - detect-only checks (tool/version problems, the worktree-tangle check, harness override, dispatch-profile validation, backlog-backend status) always run, but routine confirmations stay silent by default. - When the lock could not be acquired, the worktree-tangle check uses read-only advisory wording without a checkout repair command. - Home-local stale Herdr projection cleanup and the six bootstrap MUTATING sweeps - same-home backlog reconciliation, fleet sync, secondmate convergence, secondmate liveness, pending remote handoff retry, and Relay artifact writes - run only when this session actually holds the lock from step 1; the four network ones among them run in the deferred stage rather than in this section. - The secondmate liveness sweep deterministically accounts for every registered secondmate: it relaunches only from the recovery-grade `dead` or `missing` states, preserves ambiguous, unreadable, or unreachable remote targets, and reports skipped or failed guarantees as `SECONDMATE_LIVENESS:` lines (`bin/fm-bootstrap.sh`; `bin/fm-backend.sh`'s `fm_backend_agent_state`; `docs/remote-secondmates.md`). -3. **Wake queue** - when locked, drains and presents the durable wake queue without running the inactive-outcome scan inline, and prints the raw records prominently as this turn's first work queue; a clearly labeled status-event annotation may follow a valid `signal` record and includes every status line still unread at the presentation cursor, but never replaces the raw record or current-state reconciliation, and a lapsed watcher chain still surfaces here via the same guard alarm. - Presented records remain durable until the handling turn runs the generation-bound acknowledgement printed by the drain. - Every locked drain also prints a bounded fleet-wide `OPEN DECISIONS` section when durable decision records remain open, including when the queue itself is empty; reconcile those entries before continuing. - A main drain may also print a bounded, one-shot `STATUS OUTCOME BACKSTOP` when a task's newest captain-facing status event has no covering supervision-branch outcome; handle it as a recovered wake even when no queue row remains. - The same drain prints every still-unread `note:` line and pending-reply resolution since the last presentation in an unbounded `UNREAD STATUS` section, so an answer buried under a later routine line is not dropped; those lines are not re-printed after that presentation. - It also prints a bounded `RECORD DIVERGENCE` section naming every captain call the status log reads as resolved while its backlog task is still held; nothing is closed for you, and `captain-hold-lifecycle` owns the reconciliation. - When the lock could not be acquired and verified, the queue is left untouched because no session mutation is authorized, and the guard's tangle/watcher-liveness alarms still print in read-only advisory mode without drain, supervision repair, or checkout repair commands. -4. **Supervision operating instructions** - after the wake queue and before both digests, the digest emits exactly one operating block for the detected primary harness, followed by the read-once contract that governs them. - The script itself never starts supervision; the emitted harness protocol owns the exact wait or wake mechanism. -5. **Fleet-state digest** - after that read-once contract and ahead of the context digest, the compact backlog listing owned by `bin/fm-session-start.sh`; every `state/.meta`; a bounded tail of each task's `state/.status` (labeled as wake-EVENT history, not current state, with the full log path printed for a deeper read); the away posture (`state/.afk-contract`, plus the `state/.afk` daemon flag where a daemon runs); and one cheap alive/dead read of each task's recorded backend endpoint. - That liveness line is a fast presence check only, not a full state read - when you need a crew's actual current state (a run-step, not just "is the pane there"), read it with `bin/fm-crew-state.sh ` as before; the digest deliberately skips that deeper, slower read for every task so it stays fast and bounded. -6. **Network checks** - after the fleet-state digest, the deferred stage's result, or an explicit statement of what it has not confirmed yet. - A read-only session runs no network checks at all and says so. -7. **Context digest and next step** - last of the bulk sections, the full contents of `data/projects.md`, `data/secondmates.md`, `data/captain.md`, `data/captain-shared.md`, and `data/learnings.md`, each clearly delimited, followed by the closing reminder. - A file that does not exist prints an explicit `ABSENT` marker, never confused with an empty-but-present file: absence is meaningful (`captain.md` absent means use the firstmate repo's built-in defaults, `projects.md` absent means rebuild it from the clones under `projects/`, etc.). - The closing reminder points back to the emitted supervision block and preserves only the lock, afk, Relay, and read-once reminders. - Bootstrap detects first, asks for consent, and installs only after the captain approves in the current session. Do not dispatch until the essential launch tools are present and GitHub authentication is good; presentation availability follows `bootstrap-diagnostics` and does not block nonvisual work. Use `gh-axi` for GitHub, `chrome-devtools-axi` for browser work, and compatible `lavish-axi` for visual decisions or reports; consult current help rather than memorizing flags. -A silent bootstrap section needs no action; for any printed actionable diagnostic line, load `bootstrap-diagnostics` and follow its owner procedure. -`BOOTSTRAP_INFO:` lines are completed no-action facts and do not require loading a skill. -`secondmate-provisioning` owns startup secondmate sync, liveness, and inherited local-material convergence. +A silent bootstrap section and ordinary `BOOTSTRAP_INFO:` facts need no action. +Load `bootstrap-diagnostics` for every actionable bootstrap or network-check diagnostic named in section 13 and for its interrupted-cleanup condition. ## 4. Harness and runtime dispatch -Load `harness-adapters` before every spawn or recovery and before trust handling, skill invocation, interrupt, exit, resume, or adapter verification. -The verified harnesses are `claude`, `codex`, `opencode`, `pi`, `pi-signed`, `grok`, `kimi`, `cursor`, and `omp`, plus `muse`, `gemini`, `rovo`, and `agy` for crewmates and scouts only; never dispatch on an unverified adapter. -If static `config/crew-harness` or `config/secondmate-harness` names an unverified adapter, report it and fall back only to a verified adapter rather than launching it. - -`docs/configuration.md` owns dispatch-profile and runtime-backend schemas, `bin/fm-harness.sh` owns static resolution, and `bin/fm-spawn.sh` owns launch flags and fail-closed validation. -When dispatch profiles exist, consult them at every crewmate or scout intake and pass the resolved concrete profile required by `fm-spawn`. -Routing precedence is an explicit per-task captain override, then the best-fit configured rule, then the configured default, then the static crewmate harness. -Firstmate alone resolves a matched profile array: begin with `quota-axi`'s default TOON at that intake, using the skill's narrow TOON-then-`--json` fallback only for genuine ambiguity, evaluate every configured candidate against that current output, and choose with inspectable `spendPriority` as the one quota-perspective ranker after the skill's eligibility, reasoning-class, and runway-feasibility gates. -Account for every candidate with the catalog evidence, provider relationship, applicable quota and authentication facts, remaining uncertainty, fit and reasoning class, and the spendPriority and runway evidence used in selection; never omit a candidate, guess, fall back silently, or call the result quota-informed without them. -Establish model support and provider family from that harness's own authoritative catalog, then read `quota-axi` at the granularity the vendor actually supplies: provider-level or all-model evidence applies to every model established in that family, and a named-model window bounds only that model. -Missing model-level quota, a missing authentication source, unmeasurable headroom, or unmodeled authentication is disclosed uncertainty that keeps a candidate eligible, never a credential or login escalation. -Only concrete contradictory evidence blocks a candidate, such as an authoritative catalog proving the model unsupported or proof that the credential selected for that surface is unusable; never infer a credential store, provider family, or quota mapping from a harness, model, or source name, and never launch another harness's CLI to judge a candidate. -Preserve malformed profile configuration as an actionable error rather than selecting around it. -When every candidate is tight, preserve the captain's strongest-reasoning class rather than silently downgrading it solely to conserve quota; stop and report the tight choice if that class cannot proceed. -Break genuine evidence ties without array-order or harness bias. -`quota-axi` owns how model or product windows relate to bounding account windows and remains data-only. -Load `quota-array-dispatch` before choosing among a matched profile array; that skill is the single owner of the TOON-first spendPriority selection procedure. -Run `bin/fm-dispatch-resolve.sh` directly on the written brief in the same turn, with no preflight, and on `clear` pass its `profile:` line to `fm-spawn` unless you state a reason to override, then rerun the same script with `--record-dispatch` for the profile you actually dispatched; `ambiguous`, `escalate`, `error`, and off all mean the intake above, unchanged, and record no dispatch (contract: `docs/configuration.md` "Typed dispatch resolution"). -The generic effort fallback and its precedence are owned by `harness-adapters`: explicit captain and standing configured effort win; otherwise use low for well-understood explicit work, xhigh for ambiguous investigation or design, intermediate levels proportionally, and never max without explicit captain preference. -Do not add model-specific versions of that policy. - -`secondmate-provisioning` owns secondmate harness pins and inherited local material, while `harness-adapters` owns the harness consequences. -Dispatch only on a backend that `fm-spawn` validates as spawn-capable; pass an explicit per-spawn `--backend` only under that exact task's own authority, never as later-task precedent (selection contract: [`docs/configuration.md`](docs/configuration.md) "Runtime backend"). -A missing dependency, authentication failure, unsupported backend, or version refusal is a blocker; never silently retry on another backend. +Load `task-intake` before classifying, briefing, or dispatching any new ship or scout. +Load `harness-adapters` before every spawn or recovery and before trust handling, harness-specific skill invocation, interrupt, exit, resume, or adapter verification. +Load `quota-array-dispatch` before choosing among a matched dispatch-profile array. +Load `secondmate-provisioning` for every secondmate dispatch or recovery condition named in section 13. +The skills and `docs/configuration.md` own selection policy; `bin/fm-harness.sh`, `bin/fm-dispatch-resolve.sh`, and `bin/fm-spawn.sh` own exact resolution and validation mechanics. +Never dispatch on an unverified adapter or silently retry a missing dependency, authentication failure, unsupported backend, or version refusal on another backend. ## 5. Recovery After the one session-start digest, reconcile reality with durable records before taking new work. Honor lock-refused read-only mode exactly as section 3 requires. -Treat digest status tails as wake-event history and use targeted current-state reconciliation when the live state matters. +Treat digest status tails as wake-event history and use targeted current-state reconciliation when live state matters. Reconcile only this home's recorded direct reports and their recorded backend inventory; never sweep a shared endpoint namespace for matching names or claim another home's work. -For an ordinary direct report whose endpoint is dead or metadata has no window, load `stuck-crewmate-recovery` and preserve the recorded worktree and unlanded work while reconciling ownership. -For a dead secondmate direct report, load `secondmate-provisioning` and reconcile only that secondmate, never its whole child tree from the main home. -Each secondmate reconciles work already in its own home and then idles; recovery never authorizes it to invent work. - -If `state/.afk` is present, load `/afk` in away mode or `/quiet` in quiet mode (`bin/fm-wake-lib.sh`'s `fm_afk_mode`); where its daemon runs, let the daemon own supervision rather than arming another cycle, and on Pi keep the ordinary supervision session, which runs in both postures with main parked while the record exists. -Surface only captain-relevant decisions, review-ready PRs, failures, and credential needs; otherwise resume the emitted supervision protocol silently. +Load `stuck-crewmate-recovery` for an ordinary direct report under its section 13 conditions, preserving its recorded worktree and unlanded work. +Load `secondmate-provisioning` for a dead or missing secondmate and reconcile only that secondmate, never its child tree from the main home. A restart must be a non-event because durable state and live backend inventory, not conversation memory, are authoritative. ## 6. Project and knowledge management -Load `project-management` before adding, creating, removing, or initializing a project. -Cloning or registering a project is add intake and uses the same trigger. -That skill owns registry syntax, delivery-mode selection, outward-facing consent, clone and initialization procedure, safe rollback, and removal preflight. -Project creation never authorizes an unmentioned remote, and project removal never bypasses that preflight or unlanded-work checks; hard rule 1's concrete captain-approved project operation exception remains available when its exact conditions are met. - -Load `secondmate-provisioning` before creating, seeding, validating, launching, handing backlog to, recovering, pushing inherited local material into, or retiring a secondmate home, and before editing `data/secondmates.md`. -Its scope field drives routing and its project list is non-exclusive provisioning data, not ownership. -Keep `local-only` work in the main home. - -A secondmate is idle by default and acts only on work routed by the main firstmate. -It reconciles its own work under way after restart, then waits silently; an empty queue never authorizes a survey, audit, or self-directed improvement sweep. -Do not reconstruct or supervise a secondmate's child tree from the main home. +Load `project-management` before adding, creating, cloning, registering, initializing, or removing a project. +Load `secondmate-provisioning` before any secondmate-home lifecycle or registry work named in section 13. Route durable knowledge to its most specific owner: @@ -280,142 +114,25 @@ Route durable knowledge to its most specific owner: - Knowledge general to every firstmate user belongs in this repo's shared tracked surface. Firstmate never writes a project's `AGENTS.md` directly. -A crewmate creates or updates it lazily through the project's selected delivery path, using `bin/fm-ensure-agents-md.sh` and preferring pointers to authoritative sources over copied detail. +A crewmate creates or updates it through the project's selected delivery path with `bin/fm-ensure-agents-md.sh`, preferring pointers to authoritative sources over copied detail. Keep fleet delivery posture and captain-private strategy out of project memory. -When the captain invokes `/stow`, load the `stow` skill for its memory curation, knowledge routing, and persistence of the open work records this session is holding; it files and corrects only the open work that session is holding, and never reconciles the backlog against repository or PR reality. - -## 7. Task lifecycle - -The delivery lifecycle is an always-loaded operational contract; referenced scripts own exact commands, flags, and data mechanics. - -### Intake and authority - -Resolve the project independently for every request. -An explicit project wins, a clear follow-up inherits its referent, and otherwise match the request against the registry, work under way, and project code or README. -Proceed on one confident match while naming the project in plain language; ask one concise question when multiple or no projects plausibly match. - -Route by the nature of the work against each registered secondmate scope, not by a non-exclusive clone list. -Keep `local-only` work in the main home. -Send in-scope work to the fitting secondmate unless it is blocked or the captain explicitly redirects it; do not read the secondmate's chat because marked routed replies return through its status or referenced document. -If no secondmate scope fits, use the main home or discuss creating an appropriate persistent secondmate. -For one-off or infrequent operational work, start with the simplest direct end-to-end path. -Do not build wrappers, control planes, policy layers, custom verifiers, or automation unless the direct path exposes a concrete blocker or repeated need that justifies the added machinery. - -Before commissioning an investigation, consult existing reports and established evidence. -Classify the deliverable: - -- **Ship** is the default and produces a project change through the selected delivery mode; once implementation is authorized, dispatch a ship and keep any remaining bounded research inside it unless unresolved uncertainty could materially change whether or what to build. -- **Scout** produces knowledge in `data//report.md`, never a PR, and is appropriate for investigation, diagnosis, planning, reproduction, or audit work when the captain explicitly requests a separate knowledge or design deliverable or unresolved uncertainty could materially change whether or what to build. - -If established evidence already answers an informational question, relay it without a design-only scout; when implementation intent is unclear, answer and ask one concise implementation question when useful rather than dispatching speculative design work. -Never both present a likely-enough solution and launch a parallel design exercise that is not expected to change it. -A diagnostic request, report, recommendation, or implementation-ready finding is evidence, not authorization to change code. -Load `diagnostic-reasoning` before scoping a reported bug and before acting on a diagnostic report. - -Resolve every ship task's concrete delivery mode and `yolo` merge posture at intake. -Pass the mode explicitly to the brief, and pass both values explicitly to the spawn and any scout promotion; each command refuses to guess the values it consumes. -A current explicit captain instruction wins; otherwise the project's registry entry is the captain's standing posture, and dropping below its rigor needs a reason you can state. -On a `no-mistakes-prod-only` project, classify the task's surface: 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`; never infer internal-only from file location or project name. -An unregistered project or absent registry resolves to `no-mistakes` with yolo off, and the registration gap goes to the captain. -Record the resulting mode, `yolo` merge posture, and the one-line reason for any deviation in the backlog item note. - -Treat file or subsystem overlap as a risk signal rather than an automatic reason to wait, and dispatch isolated work immediately with no concurrency cap when each change can be independently implemented and validated and the selected delivery path can reconcile ordinary rebases or conflicts. -Serialize only for a true semantic dependency, shared mutable external state, incompatible concurrent migration, or another concrete condition that makes independent progress or reconciliation unsafe; same-file editing alone is insufficient, and genuine blockers remain durable. -Write the task-specific brief under section 11 before spawning. -Fill the task subsections according to section 11. - -### Dispatch and supervision handoff - -Spawn only through `bin/fm-spawn.sh` after the profile and backend checks in section 4. -The spawn must resolve a genuine isolated task worktree distinct from the primary checkout; a failed isolation assertion stops the task. -When the configured tasks-axi backlog gate applies, the spawn itself moves the work item to In flight and refuses rather than dispatching work this home has no item for, so recording the dispatch is never a separate step to remember; a manual-backend home retains the hand-editing contract in `docs/configuration.md`. -After spawning, confirm the worker is processing the brief and handle any trust dialog through `harness-adapters`. -A persistent secondmate is recorded in the secondmate registry and runtime state, never as a backlog work item. - -Steer a worker with ordinary text through fail-closed `fm-send`: the message becomes a durable record in the task's steering inbox (multi-line text is legal, local and remote alike) and the worker's terminal receives only a constant doorbell line, with the watcher re-ringing an unacknowledged local message and escalating a stuck one (`bin/fm-task-inbox-lib.sh`; `bin/fm-send.sh` owns the typed-plane carve-outs). -A remote secondmate steer rides the same durable-inbox model through the remote transport; after an unconfirmed delivery, only the exact `FM_PENDING_REPLY_EXISTING_CORR=` resend command printed by `fm-send` is safe because it preserves the request body for remote enqueue deduplication (`bin/fm-send.sh` header). -When a steer answers an open keyed decision or blocker, pass `fm-send`'s `--resolve-key` so the answer itself closes that decision record at answer time, identically for local and remote workers (contract: `bin/fm-send.sh` header). -`fm-send` is the data plane for text the worker should read; never use its key or text paths for interrupt, exit, or other lifecycle control, because routing-marked lifecycle text becomes chat the worker reasons about instead of executing. -Drive a worker's lifecycle through `bin/fm-control.sh interrupt|exit|relaunch`, which owns the per-runtime mechanics, verifies each action, and never tears down or discards anything ([`docs/agent-control.md`](docs/agent-control.md)). -A secondmate's routed reply returns through status or a document pointer, not by firstmate peeking into its chat. -For the parent-owned correlation, recovery, and escalation contract on marked secondmate requests, see `bin/fm-pending-reply-lib.sh`. -Supervise all live work under section 8. - -### Selected delivery path and merge authority - -The selected delivery path owns its own rigor. -When no-mistakes is selected, no-mistakes owns fixes, tests, documentation, push, PR, and CI. -Every GitHub PR also follows the captain-approved low/high-stakes review ledger owned by `pr-review-policy`; its independent PR review for high-stakes work is the one deliberate addition to the selected delivery path. -Do not stack any other serial manual review or infer one from security, architecture, or risk alone. -The path's worker, automated gates, and captain approval remain authoritative: - -- **no-mistakes** runs the full pipeline through a PR, then waits for the configured merge authority. -- **direct-PR** has the worker push and open a PR without the no-mistakes pipeline, then waits for the configured merge authority. -- **local-only** has the worker stop with a clean ready branch, then waits for the configured merge authority before firstmate uses the guarded fast-forward merge path. - -Delivery mode and `yolo` are orthogonal. -`yolo` governs ordinary merge authority: with it off, the captain approves every GitLab merge and every local-only landing; with it on, firstmate merges green, in-scope work itself. -The captain-approved GitHub review policy separately authorizes firstmate to merge a PR whose current ledger generation passes every low- or high-stakes gate, while unresolved product, rights, spend, destructive, security-sensitive, or other human decisions still hold it. -Never merge a red PR under either setting unless a current explicit captain instruction names the single GitHub check waived through `fm-pr-merge.sh --allow-red`; that attended-only waiver still requires every other check green. -Destructive, irreversible, and security-sensitive merges still escalate. -Without a current explicit captain instruction that states the concrete merge, the green default stands, and standing `yolo` cannot authorize a red merge; section 1 owns when such an instruction overrides a Firstmate-written standing rule within its exact scope. -Load `ask-user-authority` before deciding any ask-user finding; the implementation worker never answers its own finding. -Use `bin/fm-pr-review.sh merge` for every GitHub task PR merge, `bin/fm-pr-merge.sh` directly for GitLab, and `bin/fm-merge-local.sh` for approved local-only landing; never call a lower-level merge command around their guards. -After an autonomous merge, give the captain a one-line full-URL or local-main outcome. -Before applying Ready for QA after a GitHub merge or deploy, load `pr-review-policy` and satisfy its head-keyed post-merge gate without weakening any pre-merge browser check. - -### Validate - -For a no-mistakes ship, trigger validation on the same worker after its implementation commit, using the harness invocation owned by `harness-adapters`. -The task worker that starts a no-mistakes run drives the pipeline and owns every `no-mistakes axi run` and `no-mistakes axi respond` call through the next gate or outcome. -Firstmate never invokes `no-mistakes axi respond` for a crew-owned run. -When the captain adds or changes an ask mid-task, append the captain's words without added speaker labels or direct address to that brief's `## Captain's intent` and relay those words to the worker; Firstmate build constraints stay in `## Firstmate spec` or the steer. -`bin/fm-dod-lib.sh` owns the worker-side `--intent` contract. -Once validation starts, prefer routing new requirements to follow-up work rather than expanding the current task, unless a new requirement completely invalidates the work being validated; however, the smallest downstream changes needed to keep already accepted product or engineering behavior correct, add behavioral tests where an executable contract exists, or keep documentation accurate remain within the current task even when they touch files not named at intake, and corrections required to satisfy already accepted intent are not new requirements. - -Only a current, explicit captain instruction that completely invalidates the work being validated keeps the task with the same worker instead of routing it to follow-up work or handing it to a replacement. -That worker cancels the active run through no-mistakes axi's supported abort command and confirms through axi status that the run has stopped before changing any code. -The worker then follows `branch_sync.next_action` from structured axi status: use axi sync's supported guarded recovery only when its code is `recover_custody`, and otherwise proceed only when structured status confirms that branch ownership is already returned and no recovery is required. -Custody recovery settles branch ownership, not content: the worker must replace the obsolete work from the correct pre-invalidation base rather than building on top of the recovered-but-obsolete head, keeping the obsolete run's own pipeline-fix commits out of what gets validated and shipped. -Apart from that single supported abort, do not hand-edit, commit, restart, or start a second validation run while the obsolete run still owns the branch. -Once ownership is settled, validate exactly once against that final head so no obsolete or intermediate head is ever treated as authoritative. - -An ask-user finding returns as `needs-decision`; firstmate loads `ask-user-authority` and either decides or escalates per that skill. -Send the same worker one exact decision naming the decision key, step, action, affected finding IDs, instructions where needed, and exact response command, passing `--resolve-key` so the worker's open decision record closes at answer time. -Require the matching `resolved` event, forbid `--yes`, and require the worker to process every synchronous return until completion or a genuinely new escalation. -Resume fleet supervision immediately after the decision lands. - -Judge validation by the currently attributed run step through `bin/fm-crew-state.sh`, not by shell liveness or the last status event. -Running, fixing, or CI states remain working; parked approval or fix-review states require the worker to follow the active gate help; passed or checks-passed is done; failed or cancelled is failed exactly as `bin/fm-crew-state.sh` prints it - only that state line reclassifies an orphaned ci monitor after green checks as held-for-merge done, or a run record the `daemon status` probe leaves unverified as unknown, never the raw run record. -A worker hand-editing, committing, aborting, or restarting during an active validation run duplicates pipeline ownership outside the supersession sequence above; steer it back to the gate response flow. -The worker reports the PR when CI first becomes green rather than waiting for merge monitoring to finish. - -### PR ready, landing, and teardown - -For PR-based ship tasks, the ready signal depends on mode: `no-mistakes` reports `done [at=]: PR checks green` after CI is green, while `direct-PR` reports `done [at=]: PR ` after opening the PR. -Run `bin/fm-pr-check.sh ` with the URL copied from that ready signal - 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 GitHub PR, load `pr-review-policy`, initialize its durable head-keyed ledger, and arm its delayed checkpoint in the existing watcher. -Tell the captain the PR's full `https://...` URL copied from the worker's ready line or the task's `pr=` metadata, a concise outcome summary, and the no-mistakes risk level when applicable. -A captain instruction to merge is explicit authority; `yolo` and a passing current GitHub review-ledger generation are the only standing routine merge authorities. -For any custom `state/.check.sh` you write yourself, keep it an ordinary single-link mode-`0700` file, print one line only when firstmate should wake, print nothing otherwise, finish before `FM_CHECK_TIMEOUT`, then bind its current bytes with `bin/fm-check-register.sh ` before the watcher may execute it. -Retire a custom check only through `bin/fm-check-unregister.sh ` (or `bin/fm-teardown.sh` for a spawned task); never hand-compose an `rm` with `$STATE`/`$ID`. - -Tear down a ship task only after landing is confirmed. -A teardown refusal for uncommitted or unlanded work is a stop-and-investigate result, never an obstacle to bypass. -Never force teardown without explicit discard authority. -After successful teardown, record completion, retain only the configured recent Done history, and re-evaluate queued work whose blockers and time gates have cleared. - -A secondmate is persistent and an empty queue is healthy. -Retire one only on an explicit captain or main-firstmate decision, after loading `secondmate-provisioning`; its home must contain no work under way, and forced discard still requires explicit captain authority. - -### Scout outcome and promotion - -A completed scout must leave a self-contained report before its scratch worktree can be discarded; read and relay its findings, record the report as the Done artifact, and re-evaluate the queue. -A report may recommend implementation but does not authorize it. -Before treating the investigation or any visual review as complete, load `captain-hold-lifecycle`; teardown enforces that shared completion gate. -When a scout's deliverable is a visual artifact the captain will iterate on, prefer keeping that scout alive to host its own Lavish loop rather than tearing it down and mediating from firstmate, so the scout keeps its investigation context and the captain iterates in one continuous session. -When implementation is separately authorized, promote the existing scout through `bin/fm-promote.sh` rather than creating a duplicate task. -The promoted worker must inventory scratch state, return to a clean default-branch base, carry over only intended fix changes, create the ship branch, and follow the project's selected delivery path while leaving scratch commits and debug edits behind and turning a reproduced bug into the regression test. +When the captain invokes `/stow`, load the `stow` skill. + +## 7. Task lifecycle and merge authority + +Load `task-intake` before classifying, briefing, dispatching, or steering a new ship or scout. +Load `task-delivery` before starting or steering validation, on validation or delivery milestones, after a ship or scout reports done, before any merge or local landing, before teardown, and before scout promotion. +Load `backlog-management` before any backlog mutation or queue review. +The selected task's delivery mode and `yolo` posture must be explicit; the new task's brief and spawn record both values and never infer them later. + +Hard rule 2 governs every merge. +The captain's current explicit merge instruction, a project's standing `yolo` posture, and the captain-approved GitHub review policy are the only merge-authority sources, each within the exact scope owned by `task-delivery` and `pr-review-policy`. +Never merge a red PR unless a current explicit captain instruction names the single GitHub check waived through `bin/fm-pr-merge.sh --allow-red`; every other check must be green. +Use `bin/fm-pr-review.sh merge` for GitHub, `bin/fm-pr-merge.sh` for GitLab, and `bin/fm-merge-local.sh` for approved local-only landing; never call a lower-level merge command around their guards. + +Hard rule 3 governs every teardown and scout discard. +Load `task-delivery` before cleanup, and treat any refusal from `bin/fm-teardown.sh` as a stop-and-investigate result. +Never force cleanup without explicit discard authority. ## 8. Supervision protocol @@ -441,12 +158,12 @@ Handle actionable wakes as follows: 1. For `signal:`, read the listed event lines first, then reconcile current state only where action depends on it. 2. For `stale:`, inspect the recorded endpoint and load `stuck-crewmate-recovery` for a stopped, looping, confused, or unresponsive worker; a deep-inspection reason also requires current-state and validation-log inspection. 3. For `check:`, act on the named poll result, including merges, contribution signals, Relay events, process-to-event source results, and captain inbox notes; a handled inbox note is also acknowledged with `bin/fm-inbox.sh drain --ack `, or it stays counted as still waiting for firstmate. -4. For `heartbeat:`, review the whole fleet from the structured fleet view, reconcile suspicious tasks and PR state, update the backlog, and never report an unchanged fleet as progress. +4. For `heartbeat:`, review the whole fleet from the structured fleet view, reconcile suspicious tasks and PR state, load `backlog-management` to review the queue, and never report an unchanged fleet as progress. Load `bearings` on a contributions check wake or when filing work linked to an upstream issue; its contribution-follow-up section owns triage and exact signal acknowledgement. When any wake reports a merged PR for a project cloned in this home, refresh that clone through the guarded fleet-sync path. -When Relay-linked work reaches a milestone or terminal state, load `fmx-respond`; before terminal teardown, use its promised-final reconciliation when a typed public commitment exists, otherwise post the final completion follow-up so the link clears even if earlier follow-ups were spent. +When Relay-linked work reaches a milestone or terminal state, load `fmx-respond` before acting or tearing down. A secondmate's idle endpoint is healthy, and parent supervision relies on its routed status rather than treating a quiet pane as stale. Waiting on a healthy supervision cycle is silent; empty polls, elapsed time, and no-change updates are not captain-facing progress. @@ -474,10 +191,6 @@ Each skill owns its own daemon procedure, which is otherwise identical; these sa - Away and quiet mode never expand approval authority for merges, ask-user findings, destructive actions, irreversible actions, or security-sensitive choices. - Bias ambiguous input toward exit because a present captain takes precedence. -### Stuck-worker trigger - -For the full `stuck-crewmate-recovery` trigger, including a live worker claiming its no-mistakes pipeline is dead, unreachable, or timed out, follow section 13. - ## 9. Escalation and captain etiquette **Talk in outcomes, not mechanics.** @@ -532,47 +245,22 @@ Mention cost as a courtesy when unusually much work is running, but never block ## 10. Backlog contract -The configured `tasks-axi` backend is the durable queue; the tracked default is `data/backlog.md`. -It tracks work items only, never agents; persistent secondmates never appear as backlog items. -Work routed to a secondmate is recorded in that secondmate home's own backlog, not the main backlog. -A decision is simply a task held for the captain: create the task with `bin/fm-tasks-axi.sh add` when needed, then always hold it through `bin/fm-captain-hold.sh hold --reason ""`, adding `--until ` only when the call itself should stay gated until that date; a captain's own "later" is a recorded answer, never a bare re-hold. -When a main-side thread such as a pending captain decision or relay reminder is worth durable tracking, file it as its own work item and hold it through that wrapper. -Captain calls discovered by investigations or visual reviews follow `captain-hold-lifecycle`, which owns their completion gate and recorded-answer rules. -When the automatic transition gate applies, dispatch and completion move the item themselves - `bin/fm-spawn.sh` and `bin/fm-teardown.sh` own those transitions and refuse rather than report success without them - so what remains yours is filing the item before dispatch, recording decisions, and keeping notes current; `docs/configuration.md` owns gate applicability and the manual-backend exception. -Re-evaluate queued work after every teardown and heartbeat, dispatching items only when dependencies and time gates have cleared. - -`.tasks.toml`, `docs/configuration.md`, and current `tasks-axi --help` own the backlog schema, compatibility, retention, and routine command syntax. -Use compatible `tasks-axi` when the configured backend selects it, always through `bin/fm-tasks-axi.sh` so the call reaches this home's backlog from any directory, and the documented manual path otherwise; keep only the configured recent Done entries. -`secondmate-provisioning` and `bin/fm-backlog-handoff.sh` own cross-home handoff safety. - -Keep free-form notes free of temporary paths, moving versions, ephemeral identifiers, and copied state that will rot. -Inspect the current task note before replacing its considered body, and archive the superseded body when recoverability matters rather than appending by default. -Verify volatile details against their authoritative config, live system, or API before acting, and correct or delete stale prose immediately. -Preserve durable structured identifiers, dependencies, and completion artifact links, and route reusable knowledge to section 6 rather than scattering it through task notes. +Load `backlog-management` before filing, holding, handing off, updating, reviewing, or closing backlog work and before replacing a task note. +Load `captain-hold-lifecycle` for captain calls discovered by investigations or visual reviews and whenever recording or routing the captain's answer. +Use `bin/fm-tasks-axi.sh` for configured tasks-axi operations so they reach this home's backlog from any directory; `docs/configuration.md` owns the manual-backend exception. +Persistent secondmates are agents, never backlog items, and work routed to one belongs in that home's own backlog. ## 11. Crewmate briefs -`bin/fm-brief.sh` and its help own scaffold syntax, generated variants, status protocol, delivery-mode definitions of done, and exact safety mechanics. -Use its scaffold as the contract, then fill `## Captain's intent` (`{TASK}`) with the captain's own ask and any boundary the captain stated, plus the context needed to read it, including the substance of any report, decision, or PR the ask refers to; never widen the ask there into a general goal or an enumerated coverage list, because the reviewer treats that subsection as acceptance criteria. -Fill `## Firstmate spec` (`{FIRSTMATE_SPEC}`) with only the build instructions that ask requires, naming what stays out of scope when the ask is narrow; a generalization, consistency sweep, or extra hardening the captain did not ask for is follow-up work to note, not scope to add. -`bin/fm-dod-lib.sh` owns intent authoring without added speaker labels or direct address, its provenance markers, what a no-mistakes worker may pass as `--intent`, and the string's self-sufficiency rule. -Keep additions task-specific rather than repeating lifecycle instructions, and alter generated sections only when the task genuinely differs from the standard shape. - -Every ship brief must retain the worktree-isolation assertion and stop if launched in the primary checkout. -If a ship task touches firstmate's shared tracked material, explicitly require `firstmate-coding-guidelines` before editing. -If a task will drive Herdr lifecycle behavior, scaffold with `--herdr-lab`; if that need appears after an unguarded scaffold, stop and regenerate rather than adding commands by hand. -The generated Herdr contract must use a named non-`default` isolated lab and its guarded helper for every lifecycle action. - -Load `secondmate-provisioning` before creating or using a charter brief and preserve its idle-by-default and marked-return-channel contracts. -Status appends are sparse supervisor-actionable events, not routine progress; `bin/fm-classify-lib.sh` owns keyed open and resolved semantics. +Load `task-intake` before writing or changing any ship or scout brief. +Load `secondmate-provisioning` before creating or using a charter brief. +`bin/fm-brief.sh` and `bin/fm-dod-lib.sh` own scaffold syntax, generated safety text, intent provenance, and delivery definitions of done. The scaffold is a safety contract, not a suggestion. ## 12. Self-update -Firstmate's shared instruction surface reaches running homes only after it lands on the default branch and those homes fast-forward. -Only `AGENTS.md`, `bin/`, and `.agents/skills/` are loaded by a running firstmate; public `skills/` is an installer-facing surface. -When the captain invokes `/updatefirstmate` or asks to update firstmate, load the `/updatefirstmate` skill. -The skill owns the guarded fleet update and restart procedure; it never touches anything under `projects/`. +When the captain invokes `/updatefirstmate` or asks to update firstmate, load the `updatefirstmate` skill. +It owns the guarded fleet update and restart procedure and never touches anything under `projects/`. ## 13. Agent-only reference skills @@ -581,6 +269,9 @@ These skills are not captain-invocable; load them only at their precise triggers - `bootstrap-diagnostics` - load whenever the session-start digest's bootstrap or network-checks section prints an actionable diagnostic line (`MISSING:`, `MISSING_MANUAL:`, `PRESENTATION_UNAVAILABLE:`, `BACKEND_INVALID:`, `NEEDS_GH_AUTH`, `TANGLE:`, `STARTUP_MEMORY_BUDGET:`, `CREW_DISPATCH: invalid`, `FLEET_SYNC:`, `NETWORK_CHECKS:`, `HOME_SUMMARY:`, `BACKLOG_RECONCILE:`, `SECONDMATE_SYNC:`, `SECONDMATE_LIVENESS:`, `SECONDMATE_HANDOFF:`, `NUDGE_SECONDMATES:`, or `FMX:`), or when `BOOTSTRAP_INFO:` says an interrupted backlog cleanup may have left an endpoint or local copy; silence and other `BOOTSTRAP_INFO:` facts 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. +- `task-intake` - load before classifying a new project request, choosing ship or scout, selecting delivery mode or dispatch profile, writing or changing a task brief, spawning a ship or scout, or steering its worker. +- `task-delivery` - load before starting or steering validation, on validation or delivery milestones, after a ship or scout reports done, before any merge or local landing, before teardown, and before scout promotion. +- `backlog-management` - load before filing, holding, handing off, updating, reviewing, or closing backlog work, before replacing a task note, and on queue review after teardown or heartbeat. - `quota-array-dispatch` - load before choosing among a matched crew-dispatch profile array from current quota-axi default TOON. - `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. @@ -598,18 +289,10 @@ These skills are not captain-invocable; load them only at their precise triggers ## 14. Relay -Relay is the public-mention integration older docs and some emitted lines still call "X mode"; its identifiers keep the `FMX_`, `x-`, and `fm-x-` spellings. -Relay ships inert and causes no behavior change until the home opts in by placing `FMX_PAIRING_TOKEN` in its gitignored `.env`. -That token is consent for public replies and normal reversible lifecycle actions from eligible mentions, not authority for destructive, irreversible, or security-sensitive action; those still require trusted-channel confirmation. -`docs/configuration.md` owns activation, generated state, cadence, wire protocol, and opt-out mechanics. - -A Relay-only home still requires the live supervision cycle so mentions can wake it without fleet work. -On an `x-mention ` or `x-mode-error ...` check wake, load `fmx-respond`, which owns classification, public-safety policy, reply or dismissal, task linking, and follow-ups. -For every Relay-linked terminal outcome, load that owner and use the promised-final reconciliation when a typed public commitment exists, otherwise post the final completion follow-up before teardown. - -A promised final public reply is durable state, never conversation memory. -Load `fmx-respond` before promising one, on a `public-followup ...` check wake, and whenever the session-start digest lists a public commitment awaiting delivery or an open public loop. -Only the home holding the relay consent and thread binding ever posts it, so never ask a secondmate or crewmate to find the thread or send the reply, and never recover a terminal result by reading a `done:` sentence. +Relay ships inert until the home opts in with `FMX_PAIRING_TOKEN`; `docs/configuration.md` owns activation and generated state. +That token authorizes public replies and normal reversible lifecycle actions from eligible mentions, not destructive, irreversible, or security-sensitive action, which still requires trusted-channel confirmation. +A Relay-only home still requires the live supervision cycle. +Load `fmx-respond` on every Relay trigger in section 13 and before promising a public final; that skill owns classification, public-safety policy, task linking, follow-ups, promised-final durability, and the owning-home boundary. ## Captain instruction precedence @@ -622,7 +305,5 @@ Standing `yolo` merge authority is not a substitute for a current explicit capta ## Maintaining this file -Keep this file for knowledge useful to almost every future agent session in this project. -Do not repeat what the codebase already shows; point to the authoritative file, skill, command, or doc. -Prefer rewriting or pruning existing entries over appending new ones. -When updating this file, preserve every safety boundary and keep the always-loaded contract concise. +Load `firstmate-coding-guidelines` before changing this file or any other shared tracked material. +It owns knowledge placement, one-owner pointers, conditional skill extraction, size discipline, trigger hygiene, and repository prose style. diff --git a/docs/agents-md-audit.md b/docs/agents-md-audit.md index b77d85eb6c7..007eef77c1f 100644 --- a/docs/agents-md-audit.md +++ b/docs/agents-md-audit.md @@ -4,6 +4,7 @@ This audit inventories the blank-line-delimited paragraphs and contiguous list g The byte column counts each group's content including its terminating newline but excludes the blank separator between groups, so the rows do not sum to the file total. Headings are listed separately so every baseline group has a stable identifier. The planned replacement is approximately 33,000 bytes, a reduction of about 61 percent; the implementation should report the measured result rather than treating that projection as a quota. +Stage 2 measured 33,212 bytes, 52,321 bytes and 61.2 percent below the baseline. Disposition meanings are exact: keep always-loaded, prune as derivable from code or docs, prune as duplicated elsewhere, or transpose to a named skill. When a group mixes always-loaded safety with conditional procedure, the disposition names the destination and the evidence column identifies the safety stub that remains in `AGENTS.md`. diff --git a/docs/architecture.md b/docs/architecture.md index 13d054934f0..e9fd774cbfa 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -284,12 +284,12 @@ The helper's header owns the exact signal detection, relocated-home limitation, ## Two task shapes Ship tasks change projects and ship by project mode (`no-mistakes`, `direct-PR`, or `local-only`); scout tasks leave standalone investigation reports at `data//report.md` and never push. -The intake and authority contract in `AGENTS.md` owns when separate scout research is warranted. +The agent-only `task-intake` skill owns when separate scout research is warranted. ## Dispatch profiles Crewmate and scout dispatch can stay on the static crewmate harness resolved by `config/crew-harness`, or it can use local dispatch profiles in `config/crew-dispatch.json`. -The dispatch file is intentionally judgment-based: firstmate reads the natural-language rules at intake, chooses the best matching rule, resolves profile arrays itself from current quota output under the `AGENTS.md` section 4 intake boundary and the `quota-array-dispatch` selection procedure, and passes only concrete `--harness`, `--model`, and `--effort` axes to `fm-spawn.sh`. +The dispatch file is intentionally judgment-based: firstmate reads the natural-language rules at intake, chooses the best matching rule, resolves profile arrays itself under the `task-intake` and `quota-array-dispatch` procedures, and passes only concrete `--harness`, `--model`, and `--effort` axes to `fm-spawn.sh`. The shell scripts validate the JSON shape and verified harness/effort combinations, but they do not parse task intent, match natural-language rules, or own array selection. The session-start bootstrap step keeps valid dispatch configuration silent unless verbose facts are enabled and surfaces a concise invalid-config line when validation fails. When the file exists, `fm-spawn.sh` refuses crewmate and scout launches without an explicit harness, so `config/crew-harness` is only automatic when no dispatch profile file is active. diff --git a/docs/configuration.md b/docs/configuration.md index a85e7372215..af097ae6bb2 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -47,7 +47,7 @@ A broken branch still falls back to today's wake-to-main path in both postures, While the away-posture record `state/.afk-contract` exists the branch takes every actionable row, no processing turn opens on the parked main, and main's standing authority relocates to the branch through the guarded scripts, each keeping its own gate; [docs/pi-supervision-branch.md](pi-supervision-branch.md#postures) owns that posture. While attended the branch's role stays bounded exactly as the captain-approved architecture set it: it cannot merge a PR, land local work, freshly spawn, or answer a decision, and every existing captain gate remains unchanged in either posture. Homes on any other primary harness never load this feature and are entirely unaffected. -`AGENTS.md`'s `state/` inventory routes the branch's runtime files to their format and lifecycle owners. +The producing script headers and the references above route the branch's runtime files to their format and lifecycle owners. While attended, a captain-facing (verdict `captain`) branch outcome persists as one exact, sequence-keyed visible transcript entry and then opens one sequence-keyed processing turn on main, which stays open until main acknowledges that sequence through its `fm_branch_processed` tool; while away, the entry persists but processing waits until the record is archived. The branch prompt's "Verdict: routine or captain" section owns the distinction between captain-facing, unsolicited routine, and unchanged-review outcomes. The generated [Pi supervision protocol](supervision-protocols/pi.md) owns main's event ownership, acknowledgement duty, and conversational treatment for merged outcomes, while the persisted entry itself owns captain visibility. @@ -447,7 +447,7 @@ When the file exists, `fm-spawn.sh` enforces that contract by refusing crewmate Batch spawns satisfy the same requirement with a shared `--harness`. Secondmate spawns are exempt and still resolve through `config/secondmate-harness` and its optional model and effort tokens. This section is the single owner of the canonical schema and its per-field semantics. -`AGENTS.md` section 4 owns the always-loaded dispatch intake boundary, and `quota-array-dispatch` owns the completion-aware profile-array selection procedure. +The agent-only `task-intake` skill owns dispatch intake, and `quota-array-dispatch` owns the completion-aware profile-array selection procedure. ```json { @@ -479,7 +479,7 @@ A rule `floor` names the quota-axi `provider` and `scope` whose `effectivePercen A known percentage below it makes the tool resolve among `default` instead; an absent or unknown row or unmeasured provider makes the floor unverifiable and escalates without authorizing default routing. A profile `provider` optionally names the quota-axi provider family whose rows apply to that profile; when present, profile and rule-floor provider IDs must match the strict whole-string pattern `^[a-z0-9]+(-[a-z0-9]+)*\z`. Bootstrap validates resolver-only `approval`, `floor`, and present `provider` values only while typed resolution is active; without the key those inert fields and the pre-existing verified-harness baseline preserve bootstrap behavior. -Typed resolution additively recognizes `gemini` because AGENTS.md section 4 verifies it for crewmate and scout dispatch. +Typed resolution additively recognizes `gemini` because `harness-adapters` verifies it for crewmate and scout dispatch. The opted-in resolver has authoritative single-provider mappings for `claude`, `codex`, `grok`, `kimi`, `cursor`, `agy`, and `muse`; every other verified harness must declare `provider` explicitly, including multi-provider `pi`, `pi-signed`, `omp`, and `opencode` and unmapped `gemini` and `rovo`. Its single-provider table is separate from the frozen legacy mapping used by `fm-quota-choose.sh`, so additions cannot alter no-key routing. The resolver returns an actionable configuration error before any request when such a profile omits it. diff --git a/docs/documentation-audiences.json b/docs/documentation-audiences.json index 947f48a402e..63b76b9d25e 100644 --- a/docs/documentation-audiences.json +++ b/docs/documentation-audiences.json @@ -124,6 +124,10 @@ "path": ".agents/skills/bearings/SKILL.md", "audience": "agent-runtime" }, + { + "path": ".agents/skills/backlog-management/SKILL.md", + "audience": "agent-runtime" + }, { "path": ".agents/skills/bootstrap-diagnostics/SKILL.md", "audience": "agent-runtime" @@ -256,6 +260,14 @@ "path": ".agents/skills/stuck-crewmate-recovery/SKILL.md", "audience": "agent-runtime" }, + { + "path": ".agents/skills/task-delivery/SKILL.md", + "audience": "agent-runtime" + }, + { + "path": ".agents/skills/task-intake/SKILL.md", + "audience": "agent-runtime" + }, { "path": ".agents/skills/updatefirstmate/SKILL.md", "audience": "agent-runtime" From cdd013f77ed98ce860a62768c8cf8fc41cecae89 Mon Sep 17 00:00:00 2001 From: twilwa Date: Tue, 22 Sep 2026 08:30:24 +0200 Subject: [PATCH 3/6] no-mistakes(review): drop audit doc, dedupe skill triggers, fix stale pointers --- .../skills/secondmate-provisioning/SKILL.md | 5 +- AGENTS.md | 8 +- bin/fm-bootstrap.sh | 3 +- bin/fm-quota-choose.sh | 4 +- bin/fm-spawn.sh | 2 +- docs/agents-md-audit.md | 138 ------------------ docs/configuration.md | 4 +- docs/documentation-audiences.json | 4 - 8 files changed, 10 insertions(+), 158 deletions(-) delete mode 100644 docs/agents-md-audit.md diff --git a/.agents/skills/secondmate-provisioning/SKILL.md b/.agents/skills/secondmate-provisioning/SKILL.md index c232922d09b..6d083d49dff 100644 --- a/.agents/skills/secondmate-provisioning/SKILL.md +++ b/.agents/skills/secondmate-provisioning/SKILL.md @@ -13,7 +13,8 @@ metadata: 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. +Keep `task-intake`'s routing rules authoritative: route by natural-language `scope:`, and local-only projects stay with the main firstmate. +The charter `bin/fm-brief.sh` seeds into the secondmate's own `data/charter.md` owns idle-by-default. ## Routing table @@ -97,7 +98,7 @@ When the file's tokens do apply, an explicit per-spawn `--model` or `--effort` f 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. +This section is the single owner of the secondmate sync and inherited-local-material propagation contract; `AGENTS.md` section 13 points 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, or reconciles a clean divergence whose complete local result is already present there (e.g. after a squash merge) with `reset --keep`; dirty, uniquely diverged, or in-flight homes launch unchanged with a warning, and a genuine divergence gets the same durable reconciliation record `bin/fm-ff-lib.sh` writes for `/updatefirstmate`. The locked session-start deferred network stage runs the same bootstrap sweep for every live local secondmate home, discovered from `state/.meta` records with `kind=secondmate` (`data/secondmates.md` only backfills `home=` for older records). That no-fetch path is a purely local fast-forward or redundant-divergence reconcile 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. diff --git a/AGENTS.md b/AGENTS.md index fd115a74c4f..04fd7670b5b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,7 +81,6 @@ Load `bootstrap-diagnostics` for every actionable bootstrap or network-check dia ## 4. Harness and runtime dispatch -Load `task-intake` before classifying, briefing, or dispatching any new ship or scout. Load `harness-adapters` before every spawn or recovery and before trust handling, harness-specific skill invocation, interrupt, exit, resume, or adapter verification. Load `quota-array-dispatch` before choosing among a matched dispatch-profile array. Load `secondmate-provisioning` for every secondmate dispatch or recovery condition named in section 13. @@ -120,9 +119,6 @@ When the captain invokes `/stow`, load the `stow` skill. ## 7. Task lifecycle and merge authority -Load `task-intake` before classifying, briefing, dispatching, or steering a new ship or scout. -Load `task-delivery` before starting or steering validation, on validation or delivery milestones, after a ship or scout reports done, before any merge or local landing, before teardown, and before scout promotion. -Load `backlog-management` before any backlog mutation or queue review. The selected task's delivery mode and `yolo` posture must be explicit; the new task's brief and spawn record both values and never infer them later. Hard rule 2 governs every merge. @@ -158,7 +154,7 @@ Handle actionable wakes as follows: 1. For `signal:`, read the listed event lines first, then reconcile current state only where action depends on it. 2. For `stale:`, inspect the recorded endpoint and load `stuck-crewmate-recovery` for a stopped, looping, confused, or unresponsive worker; a deep-inspection reason also requires current-state and validation-log inspection. 3. For `check:`, act on the named poll result, including merges, contribution signals, Relay events, process-to-event source results, and captain inbox notes; a handled inbox note is also acknowledged with `bin/fm-inbox.sh drain --ack `, or it stays counted as still waiting for firstmate. -4. For `heartbeat:`, review the whole fleet from the structured fleet view, reconcile suspicious tasks and PR state, load `backlog-management` to review the queue, and never report an unchanged fleet as progress. +4. For `heartbeat:`, review the whole fleet from the structured fleet view, reconcile suspicious tasks and PR state, review the backlog queue, and never report an unchanged fleet as progress. Load `bearings` on a contributions check wake or when filing work linked to an upstream issue; its contribution-follow-up section owns triage and exact signal acknowledgement. @@ -245,14 +241,12 @@ Mention cost as a courtesy when unusually much work is running, but never block ## 10. Backlog contract -Load `backlog-management` before filing, holding, handing off, updating, reviewing, or closing backlog work and before replacing a task note. Load `captain-hold-lifecycle` for captain calls discovered by investigations or visual reviews and whenever recording or routing the captain's answer. Use `bin/fm-tasks-axi.sh` for configured tasks-axi operations so they reach this home's backlog from any directory; `docs/configuration.md` owns the manual-backend exception. Persistent secondmates are agents, never backlog items, and work routed to one belongs in that home's own backlog. ## 11. Crewmate briefs -Load `task-intake` before writing or changing any ship or scout brief. Load `secondmate-provisioning` before creating or using a charter brief. `bin/fm-brief.sh` and `bin/fm-dod-lib.sh` own scaffold syntax, generated safety text, intent provenance, and delivery definitions of done. The scaffold is a safety contract, not a suggestion. diff --git a/bin/fm-bootstrap.sh b/bin/fm-bootstrap.sh index 31792fa37ba..d6bd099883e 100755 --- a/bin/fm-bootstrap.sh +++ b/bin/fm-bootstrap.sh @@ -67,8 +67,7 @@ # tasks-axi and quota-axi are essential bootstrap tools. # A compatible tasks-axi default backend is silent. # quota-axi is required for the agent-owned dispatch-profile array -# procedure in AGENTS.md section 4 and -# .agents/skills/quota-array-dispatch/SKILL.md. +# procedure in .agents/skills/quota-array-dispatch/SKILL.md. # On a primary home, the locked mutable path materializes the visible # default config/startup-memory-budget=7500 when absent. It never # guesses at malformed or unsafe existing files, and secondmate homes diff --git a/bin/fm-quota-choose.sh b/bin/fm-quota-choose.sh index 4bfe89247bf..eafaa94c5ad 100755 --- a/bin/fm-quota-choose.sh +++ b/bin/fm-quota-choose.sh @@ -32,8 +32,8 @@ # is checked against the wrong quota row. This is an accepted limitation of the # optional helper. Authoritative multi-provider routing - including provider # discovery from the harness catalog and quota matching by that explicit -# provider - is owned by AGENTS.md section 4 and the quota-array-dispatch skill, -# not by this helper. Use this helper only when the brief already fixed the +# provider - is owned by the task-intake and quota-array-dispatch skills, not by +# this helper. Use this helper only when the brief already fixed the # candidate order and every candidate's provider is the harness's primary family. # # omp (Oh My Pi) has no single primary family, so its candidate model prefix diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh index b1b8608531d..465ad572405 100755 --- a/bin/fm-spawn.sh +++ b/bin/fm-spawn.sh @@ -2381,7 +2381,7 @@ effort_flag_for_harness() { # high|xhigh|ultra and defaults to high, so low..xhigh map straight across. # ultra is muse's max-CLASS level, so firstmate's max maps onto it - but # only ever as an EXPLICIT captain choice, never as a fallback, because - # AGENTS.md section 4 forbids selecting max without captain preference and + # harness-adapters forbids selecting max without captain preference and # the omitted effort here leaves muse on its own high default. muse's extra # none/minimal levels sit below firstmate's shared vocabulary and are # deliberately unreachable rather than remapped onto low. diff --git a/docs/agents-md-audit.md b/docs/agents-md-audit.md deleted file mode 100644 index 007eef77c1f..00000000000 --- a/docs/agents-md-audit.md +++ /dev/null @@ -1,138 +0,0 @@ -# AGENTS.md size audit - -This audit inventories the blank-line-delimited paragraphs and contiguous list groups in the 85,533-byte `AGENTS.md` baseline reviewed on 2026-09-22. -The byte column counts each group's content including its terminating newline but excludes the blank separator between groups, so the rows do not sum to the file total. -Headings are listed separately so every baseline group has a stable identifier. -The planned replacement is approximately 33,000 bytes, a reduction of about 61 percent; the implementation should report the measured result rather than treating that projection as a quota. -Stage 2 measured 33,212 bytes, 52,321 bytes and 61.2 percent below the baseline. - -Disposition meanings are exact: keep always-loaded, prune as derivable from code or docs, prune as duplicated elsewhere, or transpose to a named skill. -When a group mixes always-loaded safety with conditional procedure, the disposition names the destination and the evidence column identifies the safety stub that remains in `AGENTS.md`. - -| ID | Baseline group | Bytes | Disposition | Skill trigger | Existing owner or safety evidence | -|---:|---|---:|---|---|---| -| 1 | `# Firstmate` | 12 | keep always-loaded | Always loaded. | Supervisor contract root. | -| 2 | Supervisor and worker-role boundary | 466 | keep always-loaded | Always loaded. | `bin/fm-dod-lib.sh` emits the worker-role override, but the supervisor must always know its own role boundary. | -| 3 | First mate and captain identity | 91 | keep always-loaded | Always loaded. | Supervisor identity has no conditional owner. | -| 4 | Captain-address and chat-only rule | 1,057 | keep always-loaded | Every chat message. | Required safety boundary; section 9 owns captain-facing style. | -| 5 | Section 1 heading | 36 | keep always-loaded | Always loaded. | Prime-directive navigation. | -| 6 | Delegation and secondmate identity | 515 | keep always-loaded | Every project request. | Core supervisor role boundary. | -| 7 | Hard-rule introduction | 31 | keep always-loaded | Always loaded. | Core safety contract. | -| 8 | Hard rules 1-5 | 2,188 | keep always-loaded | Always loaded. | Required verbatim safety boundaries; `bin/fm-teardown.sh` owns the landed-work test and guarded skills own named exceptions. | -| 9 | Firstmate-repo private and shared material | 719 | keep always-loaded | Every repository mutation. | `firstmate-coding-guidelines` supplements this shared-material boundary. | -| 10 | Section 2 heading | 23 | keep always-loaded | Always loaded. | Compact home-layout navigation. | -| 11 | Operational-home ownership and `FM_HOME` | 579 | keep always-loaded | Always loaded. | `docs/configuration.md` "Operational home layout and state" and `bin/fm-send.sh` header. | -| 12 | Directory-purpose summary | 346 | prune as duplicated elsewhere | None. | `docs/configuration.md` "Operational home layout and state" already states the same top-level purposes. | -| 13 | Exhaustive tracked, config, data, project, and state tree | 19,603 | prune as derivable from code or docs | None. | `docs/configuration.md` owns the top-level layout; producer headers and help own child fields and mutation mechanics. | -| 14 | Status-event truth and captain-memory files | 408 | keep always-loaded | Every state interpretation. | `bin/fm-classify-lib.sh`, `bin/fm-crew-state.sh`, and `docs/configuration.md` own mechanics; the event-versus-current-state warning remains inline. | -| 15 | Section 3 heading | 54 | keep always-loaded | Every session start. | Session-start navigation. | -| 16 | Run session start exactly once | 639 | keep always-loaded | Every session start. | `bin/fm-session-start.sh` header and `docs/sessionstart-nudge.md`; run-once rule remains inline. | -| 17 | Read and trust the complete digest once | 700 | keep always-loaded | Every session start. | `bin/fm-session-start.sh` header; read-once and absent-source meanings remain inline. | -| 18 | Lock-refused read-only posture | 305 | keep always-loaded | Any lock refusal. | Required safety boundary; `bin/fm-lock.sh` and session-start digest supply the diagnostic. | -| 19 | Deferred startup-network mechanics | 846 | prune as derivable from code or docs | None. | `bin/fm-startup-network.sh` header and `docs/configuration.md` own the stage and its result states. | -| 20 | Seven-part digest enumeration | 5,160 | prune as derivable from code or docs | None. | `bin/fm-session-start.sh` header owns ordering and contents; wake acknowledgement remains in the always-loaded supervision section. | -| 21 | Bootstrap consent, tool, and diagnostic rules | 825 | transpose to `bootstrap-diagnostics` | Load on any actionable bootstrap or network-check diagnostic listed in section 13. | Existing `bootstrap-diagnostics` owns responses; install consent and essential-tool boundary remain inline. | -| 22 | Section 4 heading | 35 | keep always-loaded | Always loaded. | Replaced by a concise dispatch trigger stub. | -| 23 | Harness trigger and verified-adapter boundary | 546 | transpose to `harness-adapters` | Load before spawn, recovery, trust, harness skill invocation, lifecycle control, or adapter verification. | Existing `harness-adapters` non-negotiable safety and routing matrix. | -| 24 | Dispatch profiles, quota selection, typed resolution, and effort | 3,538 | transpose to `task-intake` and `quota-array-dispatch` | Load `task-intake` for a new task; additionally load `quota-array-dispatch` for a matched profile array. | `docs/configuration.md` "Dispatch profiles", `bin/fm-dispatch-resolve.sh` header, and existing `quota-array-dispatch`. | -| 25 | Secondmate pins and runtime-backend refusal | 556 | transpose to `harness-adapters` | Load before spawn or recovery. | Existing `harness-adapters`, `secondmate-provisioning`, `bin/fm-spawn.sh`, and `docs/configuration.md` "Runtime backend". | -| 26 | Section 5 heading | 15 | keep always-loaded | Every recovery pass. | Replaced by a concise direct-report recovery boundary. | -| 27 | Reconcile reality after startup | 287 | keep always-loaded | Every session start. | `bin/fm-session-start.sh` digest contract; event-versus-current-state warning remains inline. | -| 28 | Ordinary-worker and secondmate recovery procedures | 639 | transpose to `stuck-crewmate-recovery` and `secondmate-provisioning` | Load for the direct-report conditions listed in section 13. | Existing recovery skills; this-home-only recovery boundary remains inline. | -| 29 | Away recovery behavior | 601 | prune as duplicated elsewhere | None beyond the existing away/quiet triggers. | Section 8's away-mode stub plus the `afk` and `quiet` skills own this behavior. | -| 30 | Section 6 heading | 39 | keep always-loaded | Always loaded. | Compact project and knowledge routing remains inline. | -| 31 | Project add/remove procedure | 571 | prune as duplicated elsewhere | Load `project-management` before add, create, clone, register, initialize, or remove. | Existing `project-management` owns the complete policy. | -| 32 | Secondmate provisioning procedure | 368 | prune as duplicated elsewhere | Load `secondmate-provisioning` for its section 13 triggers. | Existing `secondmate-provisioning`. | -| 33 | Secondmate idle-by-default rule | 320 | prune as duplicated elsewhere | Load `secondmate-provisioning` before secondmate lifecycle work. | Existing `secondmate-provisioning`; the core secondmate identity remains in section 1. | -| 34 | Knowledge-routing introduction | 52 | keep always-loaded | Whenever durable knowledge is captured. | Core memory-placement boundary. | -| 35 | Six-way knowledge-routing list | 652 | keep always-loaded | Whenever durable knowledge is captured. | `docs/architecture.md` "Operational memory routing" and `stow` provide procedures; concise destinations remain inline. | -| 36 | Project memory creation and `/stow` | 626 | transpose to `stow` | Load when `/stow` is invoked. | Existing `stow`, `bin/fm-ensure-agents-md.sh`, and hard rule 1; only the project-memory boundary remains inline. | -| 37 | Section 7 heading | 21 | keep always-loaded | Always loaded. | Replaced by concise task-safety and skill triggers. | -| 38 | Always-loaded lifecycle declaration | 131 | prune as duplicated elsewhere | None. | Exact mechanics are owned by scripts and the new lifecycle skills; core safety remains inline. | -| 39 | Intake heading | 25 | transpose to `task-intake` | Load before classifying, briefing, or dispatching a new task. | New skill becomes the conditional policy owner. | -| 40 | Project resolution | 364 | transpose to `task-intake` | Before task classification. | `data/projects.md` is the registry and the new skill owns judgment. | -| 41 | Secondmate routing and avoid-premature-automation rules | 756 | transpose to `task-intake` | Before task classification or routing. | `secondmate-provisioning` owns secondmate mechanics; new skill owns intake judgment. | -| 42 | Existing-evidence preflight | 116 | transpose to `task-intake` | Before commissioning an investigation. | New skill owns task-shape classification. | -| 43 | Ship and scout definitions | 585 | transpose to `task-intake` | Before choosing ship or scout. | `bin/fm-brief.sh`, `bin/fm-spawn.sh`, and `bin/fm-scout.sh` headers own mechanics. | -| 44 | Informational, diagnostic, and implementation-authority boundary | 598 | transpose to `task-intake` | Before scoping informational, diagnostic, or implementation work. | Existing `diagnostic-reasoning`; the new skill owns ship/scout choice. | -| 45 | Delivery mode and yolo intake | 989 | transpose to `task-intake` | Before every ship dispatch. | `bin/fm-project-mode.sh`, `docs/configuration.md`, and task spawn headers own mechanics. | -| 46 | Concurrency, dependency, and brief requirement | 687 | transpose to `task-intake` | Before dispatching or serializing work. | New skill owns intake judgment; `bin/fm-brief.sh` owns scaffold mechanics. | -| 47 | Dispatch heading | 37 | transpose to `task-intake` | Before spawn. | New skill route. | -| 48 | Spawn isolation and backlog transition | 770 | transpose to `task-intake` | Before spawn. | `bin/fm-spawn.sh` header and generated brief own the isolation checks and transition. | -| 49 | Steering, control, remote correlation, and supervision handoff | 1,737 | transpose to `harness-adapters` and `task-intake` | Load before steering or worker lifecycle control. | `bin/fm-send.sh`, `bin/fm-control.sh`, `bin/fm-pending-reply-lib.sh`, and existing `harness-adapters`. | -| 50 | Delivery-path heading | 47 | transpose to `task-delivery` | Load when implementation starts or a delivery milestone arrives. | New skill route. | -| 51 | Selected-path rigor | 539 | transpose to `task-delivery` | Before starting validation or delivery. | No-mistakes, `pr-review-policy`, and the selected-mode scripts own their mechanics. | -| 52 | Three delivery-mode definitions | 402 | transpose to `task-delivery` | Before starting validation or delivery. | `bin/fm-dod-lib.sh` and `bin/fm-project-mode.sh` own generated mode semantics. | -| 53 | Merge authority, red-check waiver, ask-user, and guarded merge commands | 1,671 | transpose to `task-delivery` with always-loaded safety stub | Before any merge or local landing. | Hard rules 1-3 remain verbatim; `pr-review-policy`, `bin/fm-pr-merge.sh`, and `bin/fm-merge-local.sh` own guarded decisions. | -| 54 | Validate heading | 13 | transpose to `task-delivery` | Before validation. | New skill route. | -| 55 | No-mistakes ownership and mid-task scope changes | 1,284 | transpose to `task-delivery` | Before starting or steering validation. | `bin/fm-dod-lib.sh`, no-mistakes, and new skill policy. | -| 56 | Validation invalidation and custody recovery | 1,255 | transpose to `task-delivery` | When a captain instruction invalidates active validation. | No-mistakes structured status and new skill policy. | -| 57 | Ask-user return flow | 599 | transpose to `task-delivery` | On any no-mistakes ask-user finding. | Existing `ask-user-authority`, `bin/fm-send.sh --resolve-key`, and new skill policy. | -| 58 | Validation-state interpretation | 884 | transpose to `task-delivery` | On validation status or wake. | `bin/fm-crew-state.sh` and no-mistakes structured status. | -| 59 | PR ready, landing, and teardown heading | 36 | transpose to `task-delivery` | On ready, merged, or teardown milestones. | New skill route. | -| 60 | PR registration, review ledger, custom checks, and merge signal | 1,389 | transpose to `task-delivery` and `pr-review-policy` | On a PR-ready line or before a GitHub merge. | `bin/fm-pr-check.sh`, existing `pr-review-policy`, `bin/fm-check-register.sh`, and `bin/fm-check-unregister.sh`. | -| 61 | Landed-only teardown | 393 | transpose to `task-delivery` with always-loaded safety stub | Before teardown. | Hard rule 3 remains verbatim; `bin/fm-teardown.sh` owns the complete landed-work test. | -| 62 | Secondmate retirement | 269 | prune as duplicated elsewhere | Load `secondmate-provisioning` before retirement. | Existing `secondmate-provisioning` and hard rule 3. | -| 63 | Scout heading | 32 | transpose to `task-delivery` | On scout completion or promotion. | New skill route. | -| 64 | Scout completion, captain-call gate, visual loop, and promotion | 1,145 | transpose to `task-delivery` and `captain-hold-lifecycle` | Load on scout completion, visual-review completion, or promotion. | Existing `captain-hold-lifecycle`, `bin/fm-promote.sh`, and new skill policy. | -| 65 | Section 8 heading | 27 | keep always-loaded | Always loaded. | Supervision navigation. | -| 66 | Always-loaded supervision declaration | 203 | keep always-loaded | Whenever supervision is required. | Emitted session-start protocol and named docs own harness recipes. | -| 67 | Exactly one live supervision cycle | 555 | keep always-loaded | Whenever work or Relay requires supervision. | Required no-turn-ends-blind contract; `docs/turnend-guard.md`. | -| 68 | Drain-first and generation-bound wake acknowledgement | 1,409 | keep always-loaded | Every wake-handling turn. | Required wake acknowledgement boundary; `bin/fm-wake-lib.sh` prints the exact command. | -| 69 | Wake-handler introduction | 36 | keep always-loaded | Every actionable wake. | Core routing table. | -| 70 | Four wake-type handlers | 819 | keep always-loaded | Every actionable wake. | `bin/fm-classify-lib.sh` and emitted supervision protocol own mechanics. | -| 71 | Bearings contribution trigger | 176 | transpose to `bearings` | Load on contributions wake or upstream-issue filing. | Existing `bearings`. | -| 72 | Merged-clone refresh and Relay terminal behavior | 414 | transpose to `fmx-respond` except clone-refresh stub | Load `fmx-respond` on Relay-linked milestones or terminal wakes. | Guarded fleet sync owns refresh; existing `fmx-respond` owns public follow-up. | -| 73 | Secondmate idleness, silent waits, and scoped watcher repair | 478 | keep always-loaded | Every supervision wait or repair. | `secondmate-provisioning` and emitted supervision protocol; no-broad-kill safety remains inline. | -| 74 | Guard backstop and worktree isolation | 523 | keep always-loaded | Every supervision cycle. | `docs/turnend-guard.md`, `bin/fm-spawn.sh`, and generated ship brief. | -| 75 | Away/quiet heading | 34 | keep always-loaded | When away or quiet markers or commands appear. | Trigger stub must be visible before skill load. | -| 76 | Away and quiet triggers | 512 | keep always-loaded | On `/afk`, `/quiet`, marked injections, or away-state markers. | Existing `afk`, `quiet`, and `bin/fm-wake-lib.sh`. | -| 77 | Away and quiet safety list | 1,610 | keep always-loaded | Whenever away or quiet mode is active. | Required inline safety facts from the `firstmate-coding-guidelines` model stub. | -| 78 | Stuck-worker heading | 25 | prune as duplicated elsewhere | None. | Section 13 already carries the complete skill trigger. | -| 79 | Stuck-worker pointer | 161 | prune as duplicated elsewhere | Load `stuck-crewmate-recovery` for its section 13 trigger. | Existing section 13 row. | -| 80 | Section 9 heading | 39 | keep always-loaded | Every captain-facing message. | Captain communication navigation. | -| 81 | Outcome-first, standalone-final, and vocabulary rules | 1,936 | keep always-loaded | Every captain-facing message. | Core visibility and translation contract. | -| 82 | Internal-to-captain vocabulary map | 1,286 | keep always-loaded | Every captain-facing message. | Core translation table. | -| 83 | Never relay raw internal evidence | 439 | keep always-loaded | Every captain-facing message. | Core confidentiality and translation boundary. | -| 84 | Escalation structure | 269 | keep always-loaded | Every escalation. | Core captain-facing contract. | -| 85 | Immediate-escalation introduction | 35 | keep always-loaded | Every escalation decision. | Core escalation list. | -| 86 | Immediate-escalation list | 368 | keep always-loaded | Every escalation decision. | Core authority and safety boundary. | -| 87 | Parent channel, no-op response, decision asks, PR URLs, and cost | 1,809 | keep always-loaded | Every captain-facing result. | `docs/secondmate-parent-channel.md` owns routing mechanics; response rules remain inline. | -| 88 | Section 10 heading | 24 | keep always-loaded | Always loaded. | Replaced by a concise backlog trigger stub. | -| 89 | Queue, captain-call, transition, and reevaluation policy | 1,494 | transpose to `backlog-management` | Load before filing, holding, handing off, updating, or closing backlog work and on backlog review. | `bin/fm-tasks-axi.sh`, `bin/fm-captain-hold.sh`, spawn/teardown transitions, and existing `captain-hold-lifecycle`. | -| 90 | Backend syntax and cross-home handoff | 490 | transpose to `backlog-management` | Before any backlog command or cross-home handoff. | `.tasks.toml`, `docs/configuration.md`, `tasks-axi --help`, and `bin/fm-backlog-handoff.sh`. | -| 91 | Task-note hygiene | 596 | transpose to `backlog-management` | Before replacing a task note. | New skill becomes the policy owner; tasks-axi owns command syntax. | -| 92 | Section 11 heading | 23 | prune as duplicated elsewhere | None. | Briefing becomes part of `task-intake`. | -| 93 | Captain intent, Firstmate spec, and scaffold ownership | 1,201 | transpose to `task-intake` | Before writing or changing a task brief. | `bin/fm-brief.sh` and `bin/fm-dod-lib.sh` own syntax and intent provenance. | -| 94 | Ship isolation, Firstmate skill, and Herdr lab | 540 | transpose to `task-intake` | Before writing a ship brief; additionally load `firstmate-coding-guidelines` for Firstmate shared material. | `bin/fm-brief.sh` generated safety contract and `firstmate-coding-guidelines`. | -| 95 | Charter brief and status semantics | 338 | transpose to `task-intake` and `secondmate-provisioning` | Before charter briefing or status-protocol customization. | Existing `secondmate-provisioning`, `bin/fm-classify-lib.sh`, and scaffold. | -| 96 | Section 12 heading | 19 | keep always-loaded | Always loaded. | Compact self-update trigger remains inline. | -| 97 | Self-update propagation and skill trigger | 481 | prune as duplicated elsewhere | Load `updatefirstmate` when invoked or requested. | Existing `updatefirstmate` owns the guarded procedure and surface scope. | -| 98 | Section 13 heading | 35 | keep always-loaded | Always loaded. | Central trigger index. | -| 99 | Trigger-index introduction | 82 | keep always-loaded | Always loaded. | Trigger semantics must be visible without loading a skill. | -| 100 | Existing agent-only skill trigger list | 3,820 | keep always-loaded | At each listed condition. | Existing internal skill descriptions; add rows for every new skill. | -| 101 | Section 14 heading | 13 | keep always-loaded | Always loaded. | Replaced by a concise Relay trigger and authority stub. | -| 102 | Relay activation and public authority boundary | 620 | transpose to `fmx-respond` with always-loaded safety stub | Load on Relay wakes or before a promised public reply. | Existing `fmx-respond` owns public-channel authority; `docs/configuration.md` owns activation. | -| 103 | Relay supervision and terminal follow-up | 489 | prune as duplicated elsewhere | Load `fmx-respond` on Relay wakes and linked milestones. | Existing section 13 trigger and `fmx-respond`. | -| 104 | Promised-final durability and owning-home rule | 478 | transpose to `fmx-respond` | Before promising a public final or on public-followup/startup commitment input. | Existing `fmx-respond` and `bin/fm-public-followup.sh`. | -| 105 | Captain precedence heading | 34 | keep always-loaded | Always loaded. | Core authority navigation. | -| 106 | Current explicit captain instruction precedence | 874 | keep always-loaded | Every authority decision. | Core authority and destructive-action boundary. | -| 107 | Maintenance heading | 25 | keep always-loaded | Always loaded. | Compact maintenance trigger remains inline. | -| 108 | File-maintenance discipline | 365 | transpose to `firstmate-coding-guidelines` | Load before changing shared tracked material. | Existing `firstmate-coding-guidelines` owns placement, one-owner, size, trigger, and prose rules. | - -## Planned conditional owners - -- `task-intake` will own project resolution, ship/scout choice, delivery-mode selection, dispatch-profile intake, concurrency judgment, brief authoring, spawn handoff, and steering boundaries. -- `task-delivery` will own selected-path validation, validation supersession, ask-user return flow, ready-state registration, guarded landing mechanics, landed-only cleanup procedure, and scout promotion. -- `backlog-management` will own backlog backend use, captain-call filing, automatic-transition expectations, cross-home handoff routing, reevaluation, and task-note hygiene. -- Existing `harness-adapters`, `quota-array-dispatch`, `bootstrap-diagnostics`, `stuck-crewmate-recovery`, `secondmate-provisioning`, `captain-hold-lifecycle`, `pr-review-policy`, `fmx-respond`, `stow`, and `updatefirstmate` retain their current precise procedures rather than receiving duplicate prose. - -## Safety retention checklist - -- Hard rules 1-5 remain verbatim. -- The captain-address rule remains always loaded. -- The lock-refused posture remains always loaded and read-only. -- The generation-bound wake acknowledgement remains always loaded. -- Merge authority remains protected by hard rule 2, the captain-precedence boundary, a concise task-lifecycle stub, `task-delivery`, and the exact guarded merge owners. -- Unlanded-work protection remains protected by hard rule 3, the captain-precedence boundary, a concise task-lifecycle stub, `task-delivery`, and `bin/fm-teardown.sh`. -- The full supervision cycle and away/quiet safety stub remain always loaded. diff --git a/docs/configuration.md b/docs/configuration.md index af097ae6bb2..0379443989a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -442,7 +442,7 @@ Every claude launch's inline `--settings` JSON also carries `"attribution":{"com ## Crew dispatch profiles (config/crew-dispatch.json) `config/crew-dispatch.json` is an optional local, gitignored file containing natural-language rules that firstmate reads before dispatching a crewmate or scout. -The shell scripts do not match those rules; firstmate chooses the best matching rule with judgment, resolves its profile object or array under the operating contract in `AGENTS.md` section 4 and `quota-array-dispatch`, and passes only concrete `--harness`, `--model`, and `--effort` flags to `fm-spawn.sh`. +The shell scripts do not match those rules; firstmate chooses the best matching rule with judgment, resolves its profile object or array under the operating contract in the agent-only `task-intake` skill and `quota-array-dispatch`, and passes only concrete `--harness`, `--model`, and `--effort` flags to `fm-spawn.sh`. When the file exists, `fm-spawn.sh` enforces that contract by refusing crewmate and scout spawns that lack an explicit harness (`--harness`, a positional adapter, or a raw launch command). Batch spawns satisfy the same requirement with a shared `--harness`. Secondmate spawns are exempt and still resolve through `config/secondmate-harness` and its optional model and effort tokens. @@ -527,7 +527,7 @@ Response probabilities must contain exactly every offered choice, use numeric va Only a usage or configuration error exits 2: an unreadable brief, an existing but unreadable or malformed canonical rules file, or missing `jq` once a rules file exists to match against, each reported and never selected around. With no rules file at all, the `no rules to match` block and exit 0 hold whether or not `jq` is installed, because that path asks nothing of the model or the rules; the run's own receipt is the only casualty, and it says so on its one stderr line. Missing `curl` is a normal structured `error` outcome with exit 0 so firstmate uses today's routing. -The tool never replaces firstmate's judgment, `quota-array-dispatch`, the captain-approval gate, or `fm-spawn.sh` validation; `AGENTS.md` section 4 owns what firstmate does with each outcome. +The tool never replaces firstmate's judgment, `quota-array-dispatch`, the captain-approval gate, or `fm-spawn.sh` validation; the agent-only `task-intake` skill owns what firstmate does with each outcome. By accepted design, a `clear` result does not enforce catalog/authentication, reasoning-class, or completion-runway gates. Firstmate passes its profile line unless it states a reason to override, such as the brief's reasoning class or an eligible-unranked-candidate note; every non-clear result returns to the full existing intake. diff --git a/docs/documentation-audiences.json b/docs/documentation-audiences.json index 63b76b9d25e..71bbbd135bf 100644 --- a/docs/documentation-audiences.json +++ b/docs/documentation-audiences.json @@ -304,10 +304,6 @@ "path": "docs/agent-control.md", "audience": "maintainer-architecture" }, - { - "path": "docs/agents-md-audit.md", - "audience": "maintainer-architecture" - }, { "path": "docs/architecture.md", "audience": "maintainer-architecture" From 037b1b73f599288c36efd0addb53924b8bd56a8b Mon Sep 17 00:00:00 2001 From: twilwa Date: Tue, 22 Sep 2026 08:59:11 +0200 Subject: [PATCH 4/6] no-mistakes(review): fix yolo brief split, state guard, and stale pointers --- AGENTS.md | 3 ++- bin/fm-project-mode.sh | 2 +- bin/fm-promote.sh | 2 +- bin/fm-subagent-pretool-check.sh | 4 ++-- docs/configuration.md | 2 +- tests/fm-subagent-pretool-check.test.sh | 4 ++-- 6 files changed, 9 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 04fd7670b5b..5579914a463 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,6 +56,7 @@ Each secondmate has a persistent isolated `FM_HOME`, including its own state, ba `bin/fm-send.sh` fails closed unless `FM_HOME` is explicit, so a steer cannot silently resolve against another home. A `state/.status` line is a wake event, not current-state truth; `bin/fm-crew-state.sh` owns current-state reconciliation. +Every `state/` file a producer script names as its own internal record (watcher, wake queue, session lock, auto-arm, sub-supervisor, and Relay markers) is never hand-edited or deleted; repair goes only through the emitted owner path. Treat `data/captain.md` as the domain-local record of captain preferences, optional `data/captain-shared.md` as the main-authoritative shared captain-preference file for secondmate inheritance, and `data/learnings.md` as curated home-local knowledge, regardless of harness memory. ## 3. Session start (run once at every session start) @@ -119,7 +120,7 @@ When the captain invokes `/stow`, load the `stow` skill. ## 7. Task lifecycle and merge authority -The selected task's delivery mode and `yolo` posture must be explicit; the new task's brief and spawn record both values and never infer them later. +The selected task's delivery mode and `yolo` posture must be explicit and never inferred later; pass the mode explicitly to the brief, and both values explicitly to the spawn and any scout promotion. Hard rule 2 governs every merge. The captain's current explicit merge instruction, a project's standing `yolo` posture, and the captain-approved GitHub review policy are the only merge-authority sources, each within the exact scope owned by `task-delivery` and `pr-review-policy`. diff --git a/bin/fm-project-mode.sh b/bin/fm-project-mode.sh index 3046202f23f..f953b3870af 100755 --- a/bin/fm-project-mode.sh +++ b/bin/fm-project-mode.sh @@ -27,7 +27,7 @@ # no-mistakes, so sync, seeding, and init treat such a # project as the remote-backed pipeline project it is. # yolo (orthogonal) = merge authority only: when on, firstmate merges green, -# in-scope work itself (AGENTS.md section 7). +# in-scope work itself (the task-delivery skill). # # --raw prints the registered annotation unmapped, so a caller that must tell a # conditional policy apart from a flat mode sees "no-mistakes-prod-only" itself. diff --git a/bin/fm-promote.sh b/bin/fm-promote.sh index 1f53b8a50d3..a08440dc80e 100755 --- a/bin/fm-promote.sh +++ b/bin/fm-promote.sh @@ -21,7 +21,7 @@ # A scout records no delivery posture, so promotion is where this task's delivery # contract is decided: --mode and --yolo are REQUIRED and written into the meta # alongside the kind= flip. Firstmate resolves both at promotion time, having just -# read the scout's report (AGENTS.md section 7); data/projects.md holds the +# read the scout's report (the task-intake skill); data/projects.md holds the # captain's standing posture as context, and this script never looks it up. # no-mistakes-prod-only is a registry policy rather than a task mode and is refused. # Usage: fm-promote.sh --mode --yolo diff --git a/bin/fm-subagent-pretool-check.sh b/bin/fm-subagent-pretool-check.sh index 8edb507218b..a62cf960020 100755 --- a/bin/fm-subagent-pretool-check.sh +++ b/bin/fm-subagent-pretool-check.sh @@ -190,9 +190,9 @@ fm_primary_scope_matches "$FM_ROOT" "$STATE" || exit 0 # to the two-step brief-then-spawn path when it does not, rather than naming a # script that is not there. if [ -f "$FM_ROOT/bin/fm-scout.sh" ]; then - ROUTE='first classify the work under the AGENTS.md intake contract: work already classified as a scout goes to bin/fm-scout.sh "" [project], while authorized ship work and its bounded research go to bin/fm-brief.sh then bin/fm-spawn.sh' + ROUTE='first classify the work under the task-intake skill: work already classified as a scout goes to bin/fm-scout.sh "" [project], while authorized ship work and its bounded research go to bin/fm-brief.sh then bin/fm-spawn.sh' else - ROUTE='first classify the work under the AGENTS.md intake contract, then use bin/fm-brief.sh followed by bin/fm-spawn.sh for dispatched work' + ROUTE='first classify the work under the task-intake skill, then use bin/fm-brief.sh followed by bin/fm-spawn.sh for dispatched work' fi REASON="[subagent-dispatch] the firstmate primary dispatches through the fleet, not the harness's own delegation tools: work started that way has no durable fleet record, leaves every firstmate guard inert, and dies with this session. Instead, $ROUTE (blocked tool: $TOOL, delegation-shaped on \"$MATCHED\"). Launch the session with FM_ALLOW_SUBAGENT=1 for a deliberate exception." diff --git a/docs/configuration.md b/docs/configuration.md index 0379443989a..edae7589206 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -19,7 +19,7 @@ Untracked files and directories whose names begin with `scratchpad` are also git `bin/fm-contributions.sh` owns durable published-contribution records under each task, observation bounds, equivalent triage-label configuration, and the authenticated contribution check. The producing PR and Relay helpers own the fields they append, [`bin/fm-classify-lib.sh`](../bin/fm-classify-lib.sh) owns status-event vocabulary, optional emission-time syntax, and legacy unknown-time handling, and `bin/fm-crew-state.sh` owns current-state reconciliation. The [`bin/fm-fleet-snapshot.sh` header](../bin/fm-fleet-snapshot.sh) owns the snapshot's event-time and age fields, including secondmate parent-event projections. -Wake, watcher, away-mode, and Relay-specific state mechanics remain with their named scripts and reference sections rather than being duplicated into one exhaustive state tree here. +Wake, watcher, away-mode, and Relay-specific state mechanics remain with their named scripts and reference sections rather than being duplicated into one exhaustive state tree here; `AGENTS.md` section 2 owns the never-hand-edit rule those producer-owned records share. `bin/fm-session-start.sh`'s header is the single owner of session-start ordering, composed commands, digest contents, and the digest's startup mechanism. `bin/fm-startup-network.sh`'s header owns the deferred startup stage that keeps every external-network call and the potentially slow inactive-outcome scan off that digest's blocking path, including its state files and the safety argument for running them later. diff --git a/tests/fm-subagent-pretool-check.test.sh b/tests/fm-subagent-pretool-check.test.sh index c1a2115897a..7721c4101d2 100755 --- a/tests/fm-subagent-pretool-check.test.sh +++ b/tests/fm-subagent-pretool-check.test.sh @@ -17,8 +17,8 @@ mkdir -p "$PRIMARY/bin" "$STATE" printf '# fixture\n' > "$PRIMARY/AGENTS.md" git -C "$PRIMARY" init -q -BRIEF_ONLY_ROUTE='first classify the work under the AGENTS.md intake contract, then use bin/fm-brief.sh followed by bin/fm-spawn.sh for dispatched work' -SCOUT_ROUTE='first classify the work under the AGENTS.md intake contract: work already classified as a scout goes to bin/fm-scout.sh "" [project], while authorized ship work and its bounded research go to bin/fm-brief.sh then bin/fm-spawn.sh' +BRIEF_ONLY_ROUTE='first classify the work under the task-intake skill, then use bin/fm-brief.sh followed by bin/fm-spawn.sh for dispatched work' +SCOUT_ROUTE='first classify the work under the task-intake skill: work already classified as a scout goes to bin/fm-scout.sh "" [project], while authorized ship work and its bounded research go to bin/fm-brief.sh then bin/fm-spawn.sh' # Every delegation, scheduling, worktree, and task-tracking tool Claude Code # 2.1.217 offered a primary session in the observed baseline. From a2a4fafd19c0a12136eb7ec51f7a47eeff06343b Mon Sep 17 00:00:00 2001 From: twilwa Date: Tue, 22 Sep 2026 09:17:58 +0200 Subject: [PATCH 5/6] no-mistakes(review): restore backstop wake duty, dedupe trigger, repoint pointers --- .agents/skills/task-intake/SKILL.md | 4 +--- AGENTS.md | 3 ++- bin/fm-brief.sh | 2 +- bin/fm-control-lib.sh | 6 +++--- bin/fm-project-mode.sh | 2 +- bin/fm-spawn.sh | 2 +- 6 files changed, 9 insertions(+), 10 deletions(-) diff --git a/.agents/skills/task-intake/SKILL.md b/.agents/skills/task-intake/SKILL.md index 882bdc55210..c0d6492f335 100644 --- a/.agents/skills/task-intake/SKILL.md +++ b/.agents/skills/task-intake/SKILL.md @@ -52,9 +52,7 @@ Serialize only for a true semantic dependency, shared mutable external state, in ## Resolve the worker profile -Load `harness-adapters` before every spawn or recovery and before trust handling, skill invocation, interrupt, exit, resume, or adapter verification. -Never dispatch on an unverified adapter. -If static `config/crew-harness` or `config/secondmate-harness` names an unverified adapter, follow that skill's fallback and reporting policy. +[`AGENTS.md`](../../../AGENTS.md) section 4 owns the `harness-adapters` load trigger and the unverified-adapter rule; that skill owns static-config fallback and reporting. [`docs/configuration.md`](../../../docs/configuration.md) owns dispatch-profile and runtime-backend schemas, [`bin/fm-harness.sh`](../../../bin/fm-harness.sh) owns static resolution, and [`bin/fm-spawn.sh`](../../../bin/fm-spawn.sh) owns launch flags and fail-closed validation. When dispatch profiles exist, consult them at every crewmate or scout intake and pass the resolved concrete profile required by `fm-spawn`. diff --git a/AGENTS.md b/AGENTS.md index 5579914a463..8ca6326b10e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -145,8 +145,9 @@ At the start of every wake-handling turn, drain the durable wake queue before pe Session start is the only exception because its one-shot digest already presented the queue while locked or deliberately left it untouched in lock-refused read-only mode. Treat any `OPEN DECISIONS` section from the drain as actionable reconciliation input even when no wake record was queued. Treat any `UNREAD STATUS` section as newly surfaced status that must be read this turn; those lines are not re-printed after this presentation. +Treat any `STATUS OUTCOME BACKSTOP` section as a recovered wake that must be handled this turn, even when its original queue row was already acknowledged and no wake record remains. Treat any `RECORD DIVERGENCE` section as a contradiction between two records of one captain call, never as proof the captain ruled; load `captain-hold-lifecycle` and reconcile it in whichever direction the evidence supports. -After handling all emitted wakes and reconciling the OPEN DECISIONS and UNREAD STATUS sections, run the exact generation-bound `--ack-through` command printed as `WAKE_ACK_REQUIRED`; interruption before that acknowledgement deliberately leaves the work durable for idempotent re-handling. +After handling all emitted wakes and reconciling the OPEN DECISIONS, UNREAD STATUS, and STATUS OUTCOME BACKSTOP sections, run the exact generation-bound `--ack-through` command printed as `WAKE_ACK_REQUIRED`; interruption before that acknowledgement deliberately leaves the work durable for idempotent re-handling. A status line is a wake event, not current state; use `bin/fm-crew-state.sh` when current state matters, especially before re-escalating an old decision, blocker, or pause. A declared `paused:` event means a bounded external wait expected to clear on its own, while `blocked:` means firstmate action is needed. diff --git a/bin/fm-brief.sh b/bin/fm-brief.sh index 75d6717442c..786e70d267f 100755 --- a/bin/fm-brief.sh +++ b/bin/fm-brief.sh @@ -39,7 +39,7 @@ # identify this repo. Briefs made without it carry a loud declaration so an # omitted contract cannot be silent. # For ship tasks, --mode is REQUIRED and shapes the definition of done. Firstmate -# resolves it per task at intake (AGENTS.md section 7); data/projects.md holds the +# resolves it per task at intake (the task-intake skill); data/projects.md holds the # captain's standing posture as context, and this script never reads it: # no-mistakes implement -> /no-mistakes pipeline -> PR -> configured merge authority # direct-PR implement -> push + open PR via gh-axi (no pipeline) -> configured merge authority diff --git a/bin/fm-control-lib.sh b/bin/fm-control-lib.sh index 6e6be0d5c3a..fa79f7d155e 100644 --- a/bin/fm-control-lib.sh +++ b/bin/fm-control-lib.sh @@ -61,9 +61,9 @@ fm_control_verb_allowed() { # return 1 } -# The harnesses whose control mechanics are verified. Mirrors AGENTS.md -# section 4's verified-adapter list; an unverified adapter is refused rather -# than guessed at, exactly as a spawn on it would be. +# The harnesses whose control mechanics are verified. Mirrors the +# harness-adapters skill's verified-adapter list; an unverified adapter is +# refused rather than guessed at, exactly as a spawn on it would be. fm_control_harnesses() { printf '%s\n' claude codex opencode pi pi-signed grok kimi cursor gemini muse rovo omp agy } diff --git a/bin/fm-project-mode.sh b/bin/fm-project-mode.sh index f953b3870af..2552b2db82d 100755 --- a/bin/fm-project-mode.sh +++ b/bin/fm-project-mode.sh @@ -6,7 +6,7 @@ # MECHANICAL CONSUMERS ONLY. This answers "what posture did the captain register # for this project", never "how does this task ship". A task's delivery mode and # yolo are resolved by firstmate at intake and passed explicitly to -# bin/fm-brief.sh, bin/fm-spawn.sh, and bin/fm-promote.sh (AGENTS.md section 7). +# bin/fm-brief.sh, bin/fm-spawn.sh, and bin/fm-promote.sh (the task-intake skill). # The consumers are bin/fm-fleet-sync.sh (skip local-only clones), # bin/fm-home-seed.sh (refuse local-only seeding, run no-mistakes init), and # bin/fm-spawn.sh's advisory registry-deviation notice. diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh index 465ad572405..4caf2548c7a 100755 --- a/bin/fm-spawn.sh +++ b/bin/fm-spawn.sh @@ -6,7 +6,7 @@ # fm-spawn.sh [] [--harness |harness|launch-command] [--model ] [--effort ] [--backend ] --secondmate # --mode and --yolo are this task's delivery contract, REQUIRED for every ship # spawn and refused on --scout and --secondmate spawns. Firstmate resolves both -# per task at intake (AGENTS.md section 7); data/projects.md holds the captain's +# per task at intake (the task-intake skill); data/projects.md holds the captain's # standing posture as context, not as this task's answer, so a spawn never looks # the mode up. A ship spawn additionally reads the brief's recorded # "Delivery contract: mode=" line and REFUSES a mismatch, so the worker's From 56f0d1d889fb176de4ae6dcfab0a1cce33abaee1 Mon Sep 17 00:00:00 2001 From: twilwa Date: Tue, 22 Sep 2026 23:11:59 +0200 Subject: [PATCH 6/6] no-mistakes(document): Repoint stale brief guidance comment --- tests/fm-brief.test.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/fm-brief.test.sh b/tests/fm-brief.test.sh index cbaa4c451cc..6948f9be395 100755 --- a/tests/fm-brief.test.sh +++ b/tests/fm-brief.test.sh @@ -515,7 +515,7 @@ test_herdr_lab_omission_is_loud_for_ship_and_scout() { pass "fm-brief.sh: ship and scout scaffolds make omitted Herdr intent fail-visible" } -# Regression (issue #2575): AGENTS.md section 11 and this script's own help tell +# Regression (issue #2575): the task-intake skill and this script's own help tell # firstmate to fill `{TASK}` and `{FIRSTMATE_SPEC}`. The unguarded Herdr gate used # to quote `{TASK}` in its own prose, so that documented global replace spliced # the whole task body into the middle of the gate's sentence - silently