Stow

<!-- maintainers: this is the firstmate-internal skill. The public, installer-facing counterpart lives at skills/stow/SKILL.md - deliberately a separate file with no shared code or environment branching. Keep them independent. -->

stow

Sweep this session for durable knowledge and open-work record state that exist only in conversation, then leave the next session with a compact current operating map rather than an accumulating journal. Memory entries are tiered and decay between passes, and stale material retires to a cold archive instead of being deleted. This skill writes only through the existing Firstmate ownership and write boundaries.

Memory tiers and entry markers

Markers are compact trailing HTML comments, deliberately cheap because marker bytes are counted content:

• <!--a:YYYY-MM-DD--> - an aging entry; the embedded date is its last-reinforced date.
• <!--p:YYYY-MM-DD--> - a perishable entry; the embedded date is its last-reinforced date.
• <!--a:YYYY-MM-DD/N--> - only in a home that has opted in to the pass horizon below: either dated marker may carry /N, the number of passes that evaluated the entry without reinforcing it. An absent /N means zero, so an entry the fleet keeps exercising costs no counter bytes at all, and a home that has not opted in never writes one.
• <!--P--> - an explicitly pinned entry in a file whose default tier is not pinned.
• <!--g--> - migration-only: an unconfirmed legacy entry that has consumed its one grace cycle, carrying no date because grace is not reinforcement.

- Treehouse pool slots share one repo, so workers must create their task branch before editing. <!--a:2026-08-03-->
- While state/.afk exists, the away-daemon owns triage (until the afk-wake fix lands; tracked: afk-pi-wake-bypass-r1). <!--p:2026-07-20-->
- Never restart the shared no-mistakes daemon while runs are active. <!--P-->
- Codex writes its trust prompt to stderr, not stdout. <!--a:2026-07-28/6-->

The tier names say what the pass does with an entry:

• pinned - no clock is ever read for it: exempt from decay and from budget eviction, changed only through inspect-then-update when the captain or reality changes it, except that an explicit per-item captain approval may offload it under the flow below.
• aging - it must re-prove itself: an entry whose age is greater than or equal to 30 days since its last-reinforced date is stale, and a stale entry is re-validated (date refreshed) or archived, never kept by inertia alone.
• perishable - it is stored expecting disposal: an entry whose age is greater than or equal to 7 days since its last-reinforced date is stale, and its prose must name a checkable expiry condition, such as a backlog id, a version floor, or a dated expectation. An admitted durable entry that cannot name a checkable expiry condition is not perishable and must be stored as aging. Omission is reserved for non-durable material or facts already owned elsewhere.

Marking rules:

• Tier defaults are file-scoped: entries in data/captain.md and data/captain-shared.md default to pinned because preferences and authority boundaries do not age, and entries in data/learnings.md default to aging because operational facts must re-prove themselves.
• An entry matching its file's pinned default carries no marker at all; every aging and perishable entry always carries its dated marker, whose letter names the tier, so a clock-carrying entry is never ambiguous with unmarked legacy material.
• Marker and header-pointer bytes count toward the startup-memory budget: the pass's own bookkeeping is costed content, never free, which is why the spellings above are as short as they are.
• Each memory file's header carries at most a one-line pointer naming this skill as the scheme owner, such as <!-- memory tiers: see the stow skill -->. This skill text is the single owner of tier semantics, marker spellings, and clocks, and no memory file header may restate them. The one exception is the config/stow-pass-horizon presence flag below, which turns a single extra horizon on for this home and changes nothing else on this page.
• Inspect each editable file's header pointer on every pass and add or correct it; for a read-only data/captain-shared.md, leave the file byte-identical and route a missing or outdated pointer to the primary owner. The required receipt action for that file is routed, not unchanged; name the ownership exception and do not declare the session reset-safe.
• A pre-existing missing or hand-dropped marker is never grounds for destructive treatment: it means the file's default tier; an unmarked entry in a default-pinned file is simply pinned, while an unmarked entry in a file whose default tier carries a clock follows the migration rule below.

Decay advances only when a pass runs, so a home stowed less often than a clock experiences that clock at its stow interval.

Optional pass horizon (config/stow-pass-horizon)

The wall-clock horizons above are this skill's default contract, and a home gets exactly them unless it asks for more. A home may opt in to a second, per-pass horizon by creating the local, gitignored config/stow-pass-horizon presence flag. While that file is absent nothing else in this section applies: no counter is written, no counter already in a file is read, and every entry decays on its date alone.

Opt in where admission and decay are not commensurable. A pass admits the findings that pass produced, so growth is a per-pass quantity, while a wall-clock horizon alone is a per-day one. In a home that stows daily those two rates diverge by the stow cadence, an entry the fleet keeps exercising never sits unreinforced for 30 wall-clock days, and the date horizon is evaluated vacuously every pass while the file only grows. A home stowed monthly already exceeds its date horizon on a single pass and gains nothing from the flag.

While the flag is present:

• An aging entry is stale at whichever horizon it reaches first: 10 passes that evaluated it without reinforcing it, or 30 days since its last-reinforced date.
• A perishable entry is stale at whichever it reaches first: 3 unreinforced passes, or 7 days.
• Reinforcement refreshes the date and clears the counter, and nothing else clears it, so the evidence hard rule in step 4 stays the only way an entry renews its lease.
• An existing dated marker with no /N reads as counter zero, so a home that opts in migrates nothing.
• Removing the flag returns the home to the default contract on its next pass: any /N already written is then neither read nor advanced, and is left in place rather than rewritten.

Required startup-memory pass

Every /stow invocation performs this complete pass, even when the session contains no new finding:

1. Run bin/fm-startup-memory-budget.sh report before considering a write. Record its effective budget and each file's estimated-token total. The budget is per home: this home's three files against this home's own allowance, never a fleet total. The helper's stable estimate is the documented conservative local approximation, not provider-exact accounting. If it rejects the setting or a memory file, do not infer a default or silently continue. Report that concrete exception and do not call the session reset-safe.
2. Read every current memory file completely: data/captain.md, data/captain-shared.md, and data/learnings.md. Treat an absent local file as absent, not as an invitation to manufacture content. In a primary home, all three are curation inputs under their existing ownership rules. In a secondmate home, data/captain-shared.md is a read-only primary-owned input: count it, never edit it, and curate only the editable local files. Every mutation in the rest of this pass, including reinforcement, retiering, decay archival, legacy migration, consolidation, budget archival, and offload, applies only to an editable memory file. When a read-only shared entry appears to require one of those changes, leave it untouched, report the required change as an ownership exception, and route it to the primary owner.
3. Build one whole-file retention plan before editing, ordered by likelihood of informing a future session. Keep in always-loaded memory only current captain preferences, authority and safety boundaries, recurring working style, fleet-wide or frequently relevant operating facts, and concise pointers that are expensive to rediscover. Prefer offloading current but conditional, narrow, project-specific, or context-specific material to a live on-demand owner, and archive stale, superseded, or low-recurrence material to the cold tier. Retain lower-utility material only while budget remains.
4. Reinforce and stamp. Refresh an entry's last-reinforced date to today only when this session actually exercised, confirmed, or re-derived it. Where the optional pass horizon is enabled, refreshing that date also clears the entry's unreinforced-pass counter, and nothing else clears it. Hard rule: reinforcement requires independent evidence from this session that you can name in the receipt; plausibility, importance, prior knowledge, and the entry's own text are not evidence, and any explicit statement that no confirming session evidence exists requires the no-evidence path. For an unmarked data/learnings.md entry with no such evidence, the no-evidence path is always to append <!--g--> and retain it for this entire pass; never stamp or archive it during that same invocation. Stamp each newly written entry with today's date and its tier per the marking rules, and admit a new perishable entry only with its named checkable expiry condition in the prose.
5. Evaluate every dated entry in each editable memory file against its tier clock. Where the optional pass horizon is enabled, first increment the unreinforced-pass counter of every dated entry step 4 did not reinforce - that increment is the pass tick - then judge each dated entry against both of its horizons and treat it as stale at whichever it reaches first. Re-validate a stale aging entry from current evidence and refresh its date, or archive it. Re-confirm a stale perishable entry against its named condition: still open means refresh the date, while resolved, expired, or no longer checkable means archive it in this pass. Promote perishable to aging when its condition keeps proving durable past its expected life, and retier in place when a supersession changes an entry's lifetime. pinned is exempt from this automatic decay step entirely.
6. Consolidate every editable memory file as needed, not only the file apparently related to a new finding. Prefer one concise current rule or authoritative pointer over duplicate prose. Archive completed incident and release chronology, stale versions and paths, transient task state, resolved alternatives, old metrics, and report-sized procedures; merge or remove only superseded claims and duplicates whose facts are preserved elsewhere. Never plainly remove a unique current fact: every such exit must archive it with provenance in the recoverable cold tier or relocate it to a live JIT owner or a consolidation merge that preserves the fact.
7. When the total is still over budget after decay and consolidation, make aggressive reduction the default, using editable files only and in this order: archive every editable stale, superseded, or low-utility entry that is eligible for archival; consolidate tighter; run the over-budget offload sweep below and autonomously relocate every eligible non-pinned conditional entry into an already-existing allowed owner only after that owner holds it; then, only when the convergence precondition below holds, archive eligible aging entries oldest-reinforced-first until within budget. A proposal, a future migration, or an accepted exception is never budget relief in this pass. Budget eviction considers only editable aging entries that carry a last-reinforced date and are not pending offload; a <!--g--> legacy-grace entry is ineligible until its grace cycle resolves, so eviction can neither cancel a promised grace cycle nor prefer just-validated entries over unvalidated ones. Convergence precondition: before evicting anything, total the eligible pool and check that archiving all of it would reach the budget; when even that cannot, skip the eviction rung entirely, archive nothing for budget reasons, and carry the concrete inability to the final step, naming the exempt pinned floor that crowds out the budget. Automatic processes never move a pinned entry: decay clocks, legacy grace cycles, oldest-first budget eviction, immediate budget archiving, and autonomous offload do not apply to it. The sole exception is relocation to a JIT owner after explicit, per-item captain approval under the offload flow below, and that entry remains in memory until its destination is live.
8. Run bin/fm-startup-memory-budget.sh report again after the complete pass. Finish at or below the effective budget, or open a concrete captain decision before ending the pass. A secondmate must explicitly report primary-owned-shared-file-alone-exceeds-budget when the inherited shared file alone exceeds its allowance, because local curation cannot resolve it. Route that constraint to the primary owner and open one concrete captain decision at the primary owning level that names the shortfall, with exactly these options: raise the affected home's effective budget, or explicitly approve the primary owner trimming or offloading each named shared-file entry. When the convergence precondition skipped eviction, report the exempt pinned floor and the remaining shortfall as that concrete inability rather than archiving eligible knowledge that could not close the gap. Only after every safe non-pinned archival, consolidation, offload, and eligible eviction action is exhausted may a remaining excess be attributed to pinned safety, authority, or genuine captain-preference entries. In that last-resort case, create one captain-held decision that names the shortfall and each relevant pinned entry, with exactly these options: raise the effective budget, or explicitly approve offloading or trimming a named pinned entry. Route a read-only ownership constraint to its primary owner, and make every other unresolved excess a concrete captain decision that names the safe action still required. Never end a pass over budget as an accepted exception.

A net increase is allowed only for a genuinely new current fact with no stronger owner. Before allowing it, consolidate enough lower-priority material to remain within budget. Never describe the session as reset-safe while the memory total is over budget or an exception is unresolved.

The cold tier: data/memory-archive.md

Stale never means deleted: pruning an entry from an editable memory file always means moving it to data/memory-archive.md, this home's append-only, never-injected cold tier, gitignored with the rest of data/ and never counted by the budget report. Each archived entry keeps its provenance under a dated pass heading: source file, tier, last-reinforced date, and the reason it left. Include the unreinforced-pass counter only when the optional pass horizon itself made the entry stale, using the exact reason unreinforced <N>p; omit the counter when the wall-clock horizon or any other reason caused archival, even if the active marker carried one. Archive provenance stays verbose rather than compact because the cold tier is never budget-counted.

## 2026-08-08 stow
- (from learnings.md, tier: perishable, reinforced: 2026-06-30) While state/.afk exists, the away-daemon owns triage... [archived: unreinforced 39d]

Reasons include unreinforced <N>d, unreinforced <N>p, budget oldest-first, and legacy-unvalidated. Archiving is a move, not a removal, and recovery is grep plus copy back with no tooling. Each home keeps its own archive, the archive never cascades, and truncating a grown archive is a captain decision, not a mechanism.

Over-budget offload to JIT-loaded owners

Decay handles staleness over time; offload handles scope: knowledge that is current and durable but relevant only in a nameable context, and therefore wrong to pay for in every session of every fleet member. For the offload sweep's evaluation only, each entry has exactly three outcomes decided in this fixed order:

1. Archive, the time outcome, always evaluated first: staleness is judged before scope, and offload never moves a stale fact anywhere.
2. Offload, the scope outcome, asked only of current durable entries: is this needed in nearly every session, or only in a nameable context?
3. Keep, the default outcome for this sweep: current, durable, and either fleet-wide-relevant or safety-relevant even in sessions that never name the topic.

The offload sweep runs whenever the pass is still over budget after decay archiving and consolidation, so routine passes do not move entries speculatively. It is an immediate reduction step for eligible non-pinned conditional material that can be added to an already-existing allowed owner, not a deferred proposal that leaves the pass over budget. Every test must hold for a candidate:

• Editable source: this home owns the memory file and may relocate the entry; a read-only shared entry is routed to its primary owner instead.
• Durable: not perishable, not stale, and expected to remain true for months.
• Eligible by authority: only a non-pinned, dated aging entry that is not pending offload may be autonomously relocated to an already-existing allowed owner, while a pinned entry may be proposed only for explicit, per-item captain-approved relocation and can never be archived or autonomously offloaded for budget relief.
• Conditional: a one-line nameable trigger exists, and a session that never touches that trigger runs no risk from omitting the fact.
• Fat enough to matter: roughly 50 estimated tokens or more, handled largest-first, because consolidation handles smaller entries.
• A destination below fits the entry's privacy and visibility.
• Not already preserved by a stronger owner, which the consolidation counterweight already handles as ordinary curation rather than offload.

Destinations

Hard rule: the stow process never creates or writes a firstmate-repo-tracked skill. Every skill stow's offload produces for a Firstmate home is user-owned and local, excluded through that active home's repository-local exclude file resolved with git -C "$home_root" rev-parse --git-path info/exclude; contributing a lesson to the shared tracked template is a separate deliberate captain action, never automatic. Approved project-level destinations are not produced by stow: they ship normally through that project's own registered delivery path.

• A user-owned local skill: a directory under .agents/skills/<freeform-name>/ whose path is appended to the active home clone's repository-local exclude file, never to a .gitignore. Resolve home_root to $FM_HOME when it is set and otherwise to the Firstmate code root, and anchor every destination index check, exclude-path lookup, and ignore verification to that root with git -C "$home_root". Before approval and again before migration, validate that the chosen freeform destination under home_root is absent from that home's git index and collides with no existing file or directory, and reject the destination if either check fails. The name is freeform with no user-vs-firstmate naming convention, the skill stays per-home and untracked, and the harness still lists and JIT-loads it because skill discovery scans the filesystem and ignores git status (verified in docs/verification/stow-memory.md). Its precise, condition-stated description line is its entire trigger; it gets no AGENTS.md declaration because AGENTS.md is shared tracked material. Because this destination is local and untracked, it is also the JIT home for private conditional knowledge that no committed surface may hold.
• An already-existing user-owned local on-demand note with an established trigger, after confirming it is untracked, private, and able to hold the quoted entry. The pass may add the entry to that existing owner but never creates a new note, skill, or trigger for this purpose.
• A project-level skill in the project's own repository, for situation-conditional knowledge within one project, through a normal ship task and the project's registered delivery mode. A project's committed AGENTS.md is never an offload destination: crewmates correct it but only humans extend it (AGENTS.md section 6).

Forbidden destinations: any firstmate-repo-tracked skill per the hard rule; firstmate's own AGENTS.md, which is always-loaded for every fleet session; docs/ alone, which is never agent-loaded on demand, though a skill body may point into docs for depth; and any committed surface for private content. A local skill exists only in this home, so offloading an entry out of data/captain-shared.md removes it from every inheriting home's always-injected memory: the proposal must say so, and the default for shared entries is keep.