diff --git a/.agents/skills/refit/SKILL.md b/.agents/skills/refit/SKILL.md new file mode 100644 index 00000000000..1ecad4f07f8 --- /dev/null +++ b/.agents/skills/refit/SKILL.md @@ -0,0 +1,165 @@ +--- +name: refit +description: >- + Run firstmate's four-legged periodic self-maintenance pass covering upstream currency, ecosystem fit, startup-memory curation, and integrity rot. + Use when the captain invokes /refit (e.g. "/refit", "run the refit", "weekly firstmate maintenance") or the legacy /syncfirstmate alias. + The default pass reports all four legs; full-sync mode adds the captain-approved upstream integration without absorbing /updatefirstmate. +user-invocable: true +metadata: + internal: true +--- + +# refit + +Run firstmate's four-legged periodic self-maintenance pass. +Upstream sync is now ONE LEG of this maintenance pass rather than the whole thing. +Every pass runs and reports all four legs. +Detection is read-only by default, except that the MEMORY leg delegates its owned mutation to `/stow`. +The pass never updates tooling, pushes, restarts daemons, or merges on its own. + +## The four legs + +### 1. CURRENCY + +Run `bin/fm-upstream-check.sh` for the upstream gap. +Run `bin/fm-external-tooling-check.sh` for version drift and its `safe-anytime` versus `needs-quiet-fleet` coordination. +Preserve those helpers' existing behavior exactly. +Report what new capabilities landed upstream, how far behind this fork is, and any external-tooling drift with its coordination tag. + +### 2. FIT + +Judge capabilities newly available in the firstmate ecosystem against how this fleet actually works. +Consider the existing flow, safety boundaries, supported tools, coordination constraints, and captain preferences before considering novelty. +Record every material capability considered, the fleet need it would address, the evidence used, and a verdict of adopt, keep the current approach, monitor, or reject. +"None of these are better than what we run" is a complete and valuable verdict when the comparison supports it. +Do not recommend adoption merely because a capability is newer, more fashionable, or available upstream. +This leg is read-only and must leave an explicit recorded verdict even when no change is recommended. + +### 3. MEMORY + +Invoke `/stow` and report stow's completion receipt as this leg's result. +`/stow` is the sole owner of startup-memory measurement, tiered pruning, knowledge routing, archival, budget decisions, and its receipt. +Do not restate, summarize, inline, or fork stow's protocol here. +Do not run the startup-memory helper separately as a substitute for invoking `/stow`. + +### 4. INTEGRITY + +Detect rot that version checks cannot see and report each finding with its source and consequence. + +Check memory-index completeness in both directions against the startup-memory index actually consumed by `bin/fm-session-start.sh`. +Enumerate the loader-owned startup-memory namespace from the current home before comparing it with the loader's explicit index. +Verify that every indexed startup-memory entry resolves to an ordinary file and that every file in the startup-memory set is indexed. +Do not count task reports, archives, or other `data/` material that the startup-memory loader does not own as startup-memory entries. +Report missing indexed files and unindexed files separately. + +Check for dangling `data/` pointers by resolving path references in maintained instructions and startup-memory files against the relevant repository or home root. +Report every missing target with the referring file and line, while distinguishing an intentionally historical archive reference from an actionable dangling pointer. + +Review loaded skill instructions and startup-memory entries for obvious semantic corruption, including stray-keystroke prose such as `lqun a /grilling session` and captain/product identity conflation such as `Address the captain as Oulow`. +Report the exact source line and consequence without repairing it. + +Check the agent-skills repository for uncommitted or corrupted material. +Inspect `git status --short -- .agents/skills`, `git diff --check -- .agents/skills`, every tracked skill directory, and every skill's frontmatter and path/name pairing. +Report uncommitted files, unreadable files, malformed frontmatter, duplicate skill names, and path/name mismatches. +This leg detects and reports by default; it never repairs the finding. + +## Two modes + +### 1. Check mode (default) + +Run all four legs and report all four results to the captain. +This is the weekly heartbeat pass. +The pass is read-only except for the `/stow` invocation owned by the MEMORY leg. + +In CURRENCY, run `bin/fm-upstream-check.sh` and `bin/fm-external-tooling-check.sh`. +In FIT, compare newly available capabilities with the existing fleet flow and record the verdict even when it is to keep the current approach. +In MEMORY, invoke `/stow` and relay its completion receipt. +In INTEGRITY, perform both-direction memory-index checks, dangling-`data/`-pointer checks, and agent-skills repository checks. + +Report the upstream gap, notable upstream capabilities, external-tooling drift and coordination tags, the fit verdict, stow's receipt, and every integrity finding in plain outcomes language. +Stop after the report. +The captain decides whether to proceed to full-sync mode. + +## Remotes + +- `origin` - this fork (`DereKk8/firstmate`); the PR target. +- `upstream` - canonical (`kunchenguid/firstmate`); the source of new features. +- `no-mistakes` - local gate remote; not used in this workflow. + +### 2. Full-sync mode (captain-initiated) + +**Never enter full-sync mode without the captain's explicit go-ahead.** +**Before triggering any validation, ask the captain for approval AND which model to use.** +These are prime directive #2 and the captain's standing rule; they are not waivable. + +Full-sync mode adds the existing upstream integration after the four-leg pass. +It does not absorb `/updatefirstmate`, which remains the separate faster operation that propagates this fork's main branch into running instances. + +#### Dispatch a crewmate + +Dispatch ONE capable crewmate on this repo with the integration brief below. +The crewmate is a ship task; its deliverable is a committed branch ready for the no-mistakes gate and a PR. + +**Integration brief (encode verbatim-in-spirit in the generated brief; do not re-derive):** + +--- + +You are integrating new upstream advances from `upstream/main` into this fork. + +1. **Assess integration shape.** + Run `git fetch upstream` then `git log --oneline $(git merge-base main upstream/main)..upstream/main` to see what is new. + Default to a full `git merge upstream/main` unless a narrower topic sync is genuinely and cleanly separable, because upstream features thread through shared groundwork. + +2. **Preserve our custom features - but on the merits, not blindly.** + List our custom commits with `git log --oneline upstream/main..main`. + Every custom feature survives by default. + Where upstream independently solved the same underlying problem one of ours addresses, compare both solutions on correctness, coverage, robustness, and fit, then adopt whichever is genuinely better, or reconcile them into one. + Record every such call (feature, upstream alternative, reasoning) in your report. + Escalate `needs-decision:` only for genuine policy or behavior tradeoffs, not engineering-quality judgments. + +3. **AGENTS.md reconciliation.** + Reconcile our slimmed tiered AGENTS.md with any upstream AGENTS.md structural changes. + Do not clobber either; merge the structure. + +4. **Never add any agent as co-author.** + +5. After producing the actual merge commit on the integration branch, run `bin/fm-merge-content-check.sh ` against that commit. + The check must pass before reporting `done:`. + If it flags paths, every path must be individually justified with `--allow `. + Each `--allow` needs a one-line justification in the report or PR description for a deliberate, already-approved removal - never for something you cannot explain. + +6. Ask firstmate for validation approval and model choice before running anything. + +--- + +#### Validate the seam, not the history + +Every commit that reaches `main` on either side - this fork and canonical upstream - already passed the no-mistakes gate at its origin. +A sync is therefore mostly a fast-forward of pre-validated history; re-running a full pipeline over that history re-validates already-validated commits - overkill. + +The genuinely new, never-gated surface of a sync is exactly two things: +1. **The merge seam** - the conflict resolutions and adaptation edits where custom features absorbed incoming upstream changes. +2. **Net-new code** written on the integration branch (new skills, helpers, AGENTS.md hooks). + +Validation must target that surface, not the fast-forwarded history. + +**Required gates:** a focused code review of the seam (the reconciliation/conflict diff) plus all net-new code, and a passing `bin/fm-merge-content-check.sh ` run against the actual merge commit produced on the integration branch. +The mechanical check must pass before the worker appends `done:`. +Every flagged path must instead be individually justified with `--allow `. +Each justification must be one line in the worker's report or PR description and cover a deliberate, already-approved removal - never something the worker cannot explain. +The mechanical check is in addition to the seam code review, not a replacement for it, because the human/LLM review still covers judgment calls the script cannot catch. + +**Optional judgment:** run the test suite over the integrated whole to catch cross-feature interaction bugs between independently validated features. +Treat pre-existing, environment-caused failures that reproduce on the untouched upstream tree as noise and record them in the report. + +Ask the captain for validation approval + model before running anything. +Never merge without the captain's explicit word. + +After the crewmate reports `done:`, follow the normal delivery-mode gate -> PR -> captain-merge flow. + +## Safety + +- **Never merge without the captain's explicit word** (prime directive #2; `yolo` does not waive it for this skill because a real merge into `origin/main` is irreversible). +- **Never skip the pipeline-run approval ask** - the captain owns that decision. +- The crewmate must not force, stash, or discard any unlanded work. +- The helpers `bin/fm-upstream-check.sh` and `bin/fm-external-tooling-check.sh` are read-only; they never write to tracked files, update tooling, restart daemons, or push. diff --git a/.agents/skills/syncfirstmate/SKILL.md b/.agents/skills/syncfirstmate/SKILL.md deleted file mode 100644 index 1697b83b5cf..00000000000 --- a/.agents/skills/syncfirstmate/SKILL.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -name: syncfirstmate -description: >- - Pull canonical upstream firstmate advances into this fork, reconcile custom features on the merits, and land via PR + captain merge. - Use when the captain invokes /syncfirstmate (e.g. "/syncfirstmate", "sync firstmate from upstream", "pull upstream firstmate changes"). - Default (check mode): fetches upstream and reports the gap with notable new features - no writes, no crewmate. - Full sync: dispatches a crewmate to merge, reconcile, and gate through no-mistakes, then waits for captain merge. -user-invocable: true -metadata: - internal: true ---- - -# syncfirstmate - -Pull new features from the canonical firstmate repo into this fork. -This is a real merge with conflict resolution and custom-feature reconciliation, not a fast-forward. - -## Two-layer mental model - -``` -upstream (canonical) → [/syncfirstmate: merge into fork, PR, captain merge] - → origin/main - → [/updatefirstmate: fast-forward running instances] -``` - -Keep these layers separate: -- `/syncfirstmate` (this skill) - pulls the canonical upstream INTO this fork; real merge work; lands on `origin/main` via PR + captain merge. -- `/updatefirstmate` (separate skill) - fast-forwards this fork's `main` into the running firstmate and secondmate homes; never touches canonical upstream. - -Running `/updatefirstmate` after a `/syncfirstmate` sync propagates the merged advances to live instances. - -## Remotes - -- `origin` - this fork (`DereKk8/firstmate`); the PR target. -- `upstream` - canonical (`kunchenguid/firstmate`); the source of new features. -- `no-mistakes` - local gate remote; not used in this workflow. - -## Two modes - -### 1. Check mode (default) - -No crewmate, no writes to tracked files. -This is also what the weekly heartbeat runs non-interactively. - -Run `bin/fm-upstream-check.sh`, `bin/fm-external-tooling-check.sh`, and `bin/fm-startup-memory-budget.sh report`. -The external-tooling report identifies npm drift for `gh-axi`, `lavish-axi`, and `chrome-devtools-axi` as `safe-anytime`, while `no-mistakes` drift is `needs-quiet-fleet` because its update resets the shared daemon. -The startup-memory report is read-only and its advisory review status makes the weekly check a recurring curation prompt. -When it recommends review, recommend `/stow` before the next reset. -Do not perform tooling updates or memory curation during check mode because those are deliberate separate actions owned by firstmate and `/stow`, respectively. - -Report to the captain in plain outcomes language: what new capabilities landed upstream, how far behind this fork is, any external-tooling drift with its coordination tag, and any startup-memory curation recommendation. -Stop here. -The captain decides whether to proceed to full sync. - -### 2. Full-sync mode (captain-initiated) - -**Never enter full-sync mode without the captain's explicit go-ahead.** -**Before triggering any validation, ask the captain for approval AND which model to use.** -These are prime directive #2 and the captain's standing rule; they are not waivable. - -#### Dispatch a crewmate - -Dispatch ONE capable crewmate on this repo with the integration brief below. -The crewmate is a ship task; its deliverable is a committed branch ready for the no-mistakes gate and a PR. - -**Integration brief (encode verbatim-in-spirit in the generated brief; do not re-derive):** - ---- - -You are integrating new upstream advances from `upstream/main` into this fork. - -1. **Assess integration shape.** - Run `git fetch upstream` then `git log --oneline $(git merge-base main upstream/main)..upstream/main` to see what is new. - Default to a full `git merge upstream/main` unless a narrower topic sync is genuinely and cleanly separable, because upstream features thread through shared groundwork. - -2. **Preserve our custom features - but on the merits, not blindly.** - List our custom commits with `git log --oneline upstream/main..main`. - Every custom feature survives by default. - Where upstream independently solved the same underlying problem one of ours addresses, compare both solutions on correctness, coverage, robustness, and fit, then adopt whichever is genuinely better, or reconcile them into one. - Record every such call (feature, upstream alternative, reasoning) in your report. - Escalate `needs-decision:` only for genuine policy or behavior tradeoffs, not engineering-quality judgments. - -3. **AGENTS.md reconciliation.** - Reconcile our slimmed tiered AGENTS.md with any upstream AGENTS.md structural changes. - Do not clobber either; merge the structure. - -4. **Never add any agent as co-author.** - -5. After producing the actual merge commit on the integration branch, run `bin/fm-merge-content-check.sh ` against that commit. - The check must pass before reporting `done:`. - If it flags paths, every path must be individually justified with `--allow `. - Each `--allow` needs a one-line justification in the report or PR description for a deliberate, already-approved removal - never for something you cannot explain. - -6. Ask firstmate for validation approval and model choice before running anything. - ---- - -#### Validate the seam, not the history - -Every commit that reaches `main` on either side — this fork and canonical upstream — already passed the no-mistakes gate at its origin. -A sync is therefore mostly a fast-forward of pre-validated history; re-running a full pipeline over that history re-validates already-validated commits — overkill. - -The genuinely new, never-gated surface of a sync is exactly two things: -1. **The merge seam** — the conflict resolutions and adaptation edits where custom features absorbed incoming upstream changes. -2. **Net-new code** written on the integration branch (new skills, helpers, AGENTS.md hooks). - -Validation must target that surface, not the fast-forwarded history. - -**Required gates:** a focused code review of the seam (the reconciliation/conflict diff) plus all net-new code, and a passing `bin/fm-merge-content-check.sh ` run against the actual merge commit produced on the integration branch. -The mechanical check must pass before the worker appends `done:`. -Every flagged path must instead be individually justified with `--allow `. -Each justification must be one line in the worker's report or PR description and cover a deliberate, already-approved removal - never something the worker cannot explain. -The mechanical check is in addition to the seam code review, not a replacement for it, because the human/LLM review still covers judgment calls the script cannot catch. - -**Optional judgment:** run the test suite over the integrated whole to catch cross-feature interaction bugs between independently validated features. Treat pre-existing, environment-caused failures that reproduce on the untouched upstream tree (e.g. a CI runner auto-installing a missing dev package and polluting a test's expected output) as noise — record them in the report; they do not block the merge. - -Ask the captain for validation approval + model before running anything. Never merge without the captain's explicit word. - -After the crewmate reports `done:`, follow the normal delivery-mode gate → PR → captain-merge flow. - -## Weekly heartbeat - -Check mode runs three read-only commands: -`bin/fm-upstream-check.sh` (git gap), `bin/fm-external-tooling-check.sh` (external-tooling drift and `safe-anytime` versus `needs-quiet-fleet` coordination), and `bin/fm-startup-memory-budget.sh report` (startup-memory curation recommendation). -All three are designed to run non-interactively as a weekly heartbeat job. -None writes to tracked files, updates tooling, restarts daemons, or pushes. -All three output to stdout so the scheduler can surface them. -The weekly schedule is wired by firstmate separately; this skill does not set it up. - -## Safety - -- **Never merge without the captain's explicit word** (prime directive #2; `yolo` does not waive it for this skill because a real merge into `origin/main` is irreversible). -- **Never skip the pipeline-run approval ask** - the captain owns that decision. -- The crewmate must not force, stash, or discard any unlanded work. -- The helpers `bin/fm-upstream-check.sh` and `bin/fm-external-tooling-check.sh` are read-only; they never write to tracked files, update tooling, restart daemons, or push. diff --git a/AGENTS.md b/AGENTS.md index e44b0c277d1..116a14aa690 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -555,13 +555,16 @@ Two distinct update layers exist; keep them separate. When the captain invokes `/updatefirstmate` or asks to update firstmate, load the `/updatefirstmate` skill. It performs guarded fast-forward updates of firstmate and registered secondmate homes, refreshes instructions, and never touches anything under `projects/`. -**`/syncfirstmate`** - pulls new features from the canonical upstream (`kunchenguid/firstmate`) into this fork via a real merge, reconciles custom features on the merits, gates through no-mistakes, and lands via PR plus captain merge. -When the captain invokes `/syncfirstmate` or asks to sync from upstream, load the `/syncfirstmate` skill. -Check mode only fetches and reports the gap; full sync dispatches a worker. +**`/refit`** - runs the four-legged periodic maintenance pass: upstream currency, ecosystem fit, startup-memory curation through `/stow`, and integrity checks. +Upstream sync is one leg of `/refit`, not its whole purpose. +When the captain invokes `/refit`, or uses the legacy `/syncfirstmate` alias, load the `/refit` skill. +The default pass reports all four legs; full-sync mode retains the captain-approved real upstream merge, reconciliation, no-mistakes gate, and PR flow. +The pass is read-only by default except for the MEMORY leg's delegation to `/stow`. Never merge the resulting PR without the captain's explicit word. Never trigger no-mistakes validation without asking the captain for pipeline-run approval and model choice first. -Mental model: `upstream (canonical) -> [/syncfirstmate] -> origin/main -> [/updatefirstmate] -> running instances`. +Mental model: `upstream (canonical) -> [/refit: currency and, when explicitly approved, full sync] -> origin/main -> [/updatefirstmate] -> running instances`. +`/updatefirstmate` remains the separate faster operation that propagates this fork's main branch into running instances and is never absorbed by `/refit`. A full sync is complete only after the real merge commit passes `bin/fm-merge-content-check.sh`; every intentional named-content removal is recorded with its path-specific justification in the sync report. ## 13. Agent-only reference skills diff --git a/bin/fm-external-tooling-check.sh b/bin/fm-external-tooling-check.sh index b7b4a25e42c..68749f35c14 100755 --- a/bin/fm-external-tooling-check.sh +++ b/bin/fm-external-tooling-check.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Check versions of the external tools that /syncfirstmate owns reporting. +# Check versions of the external tools that /refit owns reporting. # # READ-ONLY: never installs packages, updates tools, restarts daemons, writes # tracked files, or changes any fleet state. diff --git a/bin/fm-upstream-check.sh b/bin/fm-upstream-check.sh index 7cc84ce78e0..1f1320dc01c 100755 --- a/bin/fm-upstream-check.sh +++ b/bin/fm-upstream-check.sh @@ -6,7 +6,7 @@ # - a grouped summary of notable new upstream commits since the merge-base # # READ-ONLY: never writes to tracked files, never pushes. -# Used by /syncfirstmate check mode and the weekly heartbeat job. +# Used by /refit check mode and the weekly heartbeat job. # # Upstream remote expected: kunchenguid/firstmate at remote name "upstream". # If the remote is absent or unreachable, exits non-zero with a clear message. diff --git a/docs/documentation-audiences.json b/docs/documentation-audiences.json index fefd508a9fc..3dd7f2bfc60 100644 --- a/docs/documentation-audiences.json +++ b/docs/documentation-audiences.json @@ -209,7 +209,7 @@ "audience": "agent-runtime" }, { - "path": ".agents/skills/syncfirstmate/SKILL.md", + "path": ".agents/skills/refit/SKILL.md", "audience": "agent-runtime" }, { diff --git a/tests/fm-stow-contract.test.sh b/tests/fm-stow-contract.test.sh index 216321c62cf..ec878d26cc7 100755 --- a/tests/fm-stow-contract.test.sh +++ b/tests/fm-stow-contract.test.sh @@ -19,7 +19,7 @@ test_stow_skill_task_note_contract() { test_recurring_startup_memory_curation_contract() { local stow="$ROOT/.agents/skills/stow/SKILL.md" local reset="$ROOT/.agents/skills/reset-window/SKILL.md" - local sync="$ROOT/.agents/skills/syncfirstmate/SKILL.md" + local refit="$ROOT/.agents/skills/refit/SKILL.md" assert_grep 'Read every current memory file completely' "$stow" \ "stow no longer reads all memory before curation" @@ -34,11 +34,11 @@ test_recurring_startup_memory_curation_contract() { "reset no longer requires startup-memory curation" assert_grep 'Do not perform its routing steps separately here' "$reset" \ "reset can route durable findings twice" - assert_grep 'bin/fm-startup-memory-budget.sh report' "$sync" \ - "weekly sync no longer checks whether startup-memory curation is due" # shellcheck disable=SC2016 # The literal backticks are part of the skill contract. - assert_grep 'recommend `/stow` before the next reset' "$sync" \ - "weekly sync no longer recommends the curation owner" + assert_grep 'Invoke `/stow`' "$refit" \ + "refit no longer delegates startup-memory curation to stow" + assert_no_grep 'bin/fm-startup-memory-budget.sh report' "$refit" \ + "refit duplicates stow's startup-memory measurement protocol" pass "startup-memory curation plans, archives, and resolves budget state before reset and weekly review" }