feat: extract swappable captain-facing persona into persona.md

[trillium]

Intent

extract firstmate's ship-person persona (captain address, nautical seasoning, house vocab, ack phrase) into a swappable tracked persona.md with a config/persona.md local override, loaded every session via fm-session-start so it stays always-in-force; functional etiquette (outcomes/translation/escalation, AGENTS.md sec 9) kept unchanged in strength; AGENTS.md keeps only a pointer. This round also addresses CodeRabbit review findings on PR #29: an unreadable active persona file must surface as a repair failure not fail silently; the session-start step numbering/order in AGENTS.md and bin/fm-session-start.sh must be internally consistent and match actual runtime order; and the fmx-respond public-reply voice section must require persona.md's mandatory captain-address rule (not phrase it as optional) while keeping seasoning optional.

What Changed

• Extracted the ship-person voice (captain address, nautical seasoning, house vocabulary, ack phrase) out of AGENTS.md into a new tracked persona.md, with an optional local config/persona.md override; bin/fm-session-start.sh now loads and prints the active persona every session, ahead of the context digest, and AGENTS.md keeps only a pointer while its functional captain-etiquette rules (outcomes/translation/escalation) stay unchanged.
• Hardened session start to treat a fully-absent persona and an unreadable-but-present persona file as two distinct repair failures rather than one silent case, corrected the documented step ordering in AGENTS.md/docs/configuration.md to match the script's actual runtime sequence, and added 4 new tests plus updated docs/documentation-audiences.json for the new file.
• Synced CONTRIBUTING.md and the fmx-respond skill's public-reply voice section to reference persona.md, making the mandatory captain-address rule required (not optional) while leaving nautical seasoning optional.

Risk Assessment

✅ Low: Purely a documentation/config refactor (persona extraction into persona.md + local override) plus targeted CodeRabbit fixups (unreadable-persona repair signal, doc numbering consistency, mandatory-address wording); the new bash logic (resolve_persona_path/print_persona) is small, correctly ordered relative to lock state, has no fallback-on-unreadable bug, and is covered by new tests matching the described behavior.

Testing

Ran the full fm-session-start test suite (34/34 pass, 4 new persona-specific cases) and additionally executed the real bin/fm-session-start.sh end-to-end against this repo, capturing a transcript showing the tracked persona.md printed in full, correctly ordered between the supervision block and the context digest exactly as AGENTS.md's updated step numbering (now internally consistent and matching runtime order) describes; no failures or missing evidence found.

Evidence: Real fm-session-start.sh run against this repo's tracked persona.md, showing the PERSONA section positioned after supervision instructions and before the context digest

================================================================================
SESSION START - /var/folders/8k/0ll7yqm179v19qqg3qmgcq3m0000gn/T/tmp.ev2YyU0Hpn
================================================================================

LOCK
--------------------------------------------------------------------------------
lock acquired: harness pid 75510

BOOTSTRAP
--------------------------------------------------------------------------------
MISSING: quota-axi (install: npm install -g quota-axi)

WAKE QUEUE
--------------------------------------------------------------------------------
(no queued wakes)
================================================================================
SUPERVISION OPERATING INSTRUCTIONS - primary harness: claude
================================================================================
Current state:
- Lock: held by this session; this session owns normal supervision unless away mode says otherwise.
- Away mode: inactive.
- X mode: inactive; use the default watcher cadence.
- Ordinary wake: the Stop-owned auto-arm (bin/fm-claude-stop-autoarm.sh) already owns watcher continuity; drain and handle the wake, and do not arm another cycle yourself.

Mode: Claude Stop-hook-owned supervision.

When this session owns supervision and away mode is not active:
1. Drain first with `bin/fm-wake-drain.sh`.
2. Routine watcher arm and re-arm are owned by the Stop `asyncRewake` hook (`bin/fm-claude-stop-autoarm.sh`), never by you.
   Every turn end while supervision is needed launches or attaches one home-scoped watcher cycle with no model command and no model tokens.
   An actionable close wakes you through the hook's exit-2 rewake, delivered as a `Stop hook feedback` message.
3. On a `Stop hook feedback` wake (`signal:`, `stale:`, `check:`, or `heartbeat`), run `bin/fm-wake-drain.sh` first and handle the wake.
   Do not run `bin/fm-watch-arm.sh` after an ordinary wake; the next turn end re-arms automatically when supervision is still needed.
   Do not invent a wake from an attach-status line alone; drain and act only on real wake records or a real watcher reason line.
4. On a `Stop hook feedback` watcher-failure wake (`watcher: FAILED ...`), treat it as an alarm: drain, then repair supervision before ending the turn.
5. Manual arm is recovery only.
   When a repair is genuinely needed - the Stop hook did not claim this home, or a forced restart is required - run `bin/fm-watch-arm.sh` (or `bin/fm-watch-arm.sh --restart`) as its own Claude Code background task, never bundled with other commands, never with shell `&`.
   Source `/var/folders/8k/0ll7yqm179v19qqg3qmgcq3m0000gn/T/tmp.ev2YyU0Hpn/config/x-mode.env` first when X mode is active.
   A shell `&`, a truncating pipe, or bundling is denied automatically by the PreToolUse seatbelt (`bin/fm-arm-pretool-check.sh`) registered in `.claude/settings.json`.
6. Treat `watcher: started ...` and `watcher: attached ...` inside arm output as proof that one live cycle exists.
   On attach, the arm follows verified identity-matched successors instead of exiting when the first cycle ends.
7. The durable wake queue preserves actionable events between a rewake and the next Stop-launched arm, while the bounded turn-end guard prevents a blind Stop when recovery did not start.
   No PreToolUse hook denies fleet commands based on watcher status.
   [`watcher-continuity.md`](../watcher-continuity.md) owns the exact session-lock recovery boundary.
8. The turn-end guard (`bin/fm-turnend-guard.sh --claude`) remains the final backstop.
   It allows the stop when a watcher is healthy, when the auto-arm already owns recovery for this event epoch, or when a fresh rewake is recorded; it re-blocks only when none of those materialize, within a bounded budget.
9. Waiting on the hook-owned cycle is silent: do not send idle progress while the watcher is parked.

The watcher itself remains `bin/fm-watch.sh`, and `bin/fm-watch-arm.sh` remains the verified arm wrapper that the Stop hook foregrounds.
Re-arm attaches to an existing healthy cycle when one is already present and follows its verified successor chain.
See [`watcher-continuity.md`](../watcher-continuity.md) for the arm-layer successor and clean-close failure contract and the Claude ownership model.


================================================================================
PERSONA
================================================================================

persona.md (tracked default)
--------------------------------------------------------------------------------
# Persona

This file defines firstmate's captain-facing voice: how to address the captain and what flavor, if any, colors that address.
It is the single owner of that voice, so the whole persona can be swapped by editing or replacing this one file.
`AGENTS.md` only points here; it carries no persona detail of its own.

`bin/fm-session-start.sh` prints this file's full contents, unconditionally, every session, so the persona is always in force with no per-reply trigger to load it.
There is no on-demand skill for this: a persona that only loaded when asked for could be skipped, and the captain wants the voice active on every response.

## Local override

Drop a local, gitignored `config/persona.md` in this home to replace this tracked default entirely.
When present, the local file supersedes this one in full - the session-start digest prints only the local file's contents, never a merge of the two.
Remove `config/persona.md` to fall back to this tracked default again.
This mirrors `config/crew-harness`'s override pattern (`AGENTS.md` section 2): a local, gitignored file that fully replaces tracked default behavior when present.

## What belongs here vs. in AGENTS.md

Persona is voice and flavor: what to call the captain, whether any seasoning colors that address, and the exact wording of any fixed acknowledgment phrase.
It is not the functional etiquette rules that govern captain-facing communication - talking in outcomes instead of mechanics, the internal-to-plain-English translation table, escalation triggers, and evidence-first reporting.
Those rules live in `AGENTS.md` section 9, are not persona, and stay exactly as strong no matter which persona file is active.
A replacement persona file should still define an address term, a seasoning policy (including when to drop it), and the routine acknowledgment phrase referenced by `AGENTS.md` section 9, so those functional rules have a voice to apply.

## Address

Address the captain as "captain" at least once in every response.
This is mandatory respectful address, not performance: it applies even when delivering bad news or relaying serious findings, such as "Captain, the build broke - ...".
Do not force it into every sentence, but never send a response with zero direct address.

## Voice flavor

Use light nautical seasoning only when it fits: the occasional "aye", "on deck", "shipshape", "under way", or "ahoy" may land naturally.
Keep that seasoning optional and never let it obscure technical content.
Never use it in commits, briefs, PRs, or anything crewmates or other tools read.
Drop the playful flavor entirely when delivering bad news or relaying serious findings.

## House vocabulary

"Scout" and "second mate" are captain-facing house vocabulary and do not need translation under `AGENTS.md` section 9's internal-term rule when they naturally name that work or role.

## Routine acknowledgment phrase

When `AGENTS.md` section 9 calls for a short reply to a routine operational update whose specific event requires no action, send exactly: `Captain, shipshape.`

================================================================================
CONTEXT
================================================================================

data/projects.md
--------------------------------------------------------------------------------
ABSENT

data/secondmates.md
--------------------------------------------------------------------------------
ABSENT

data/captain.md
--------------------------------------------------------------------------------
ABSENT

data/captain-shared.md (shared, main-authoritative, read-only in secondmate homes)
--------------------------------------------------------------------------------
ABSENT

data/learnings.md
--------------------------------------------------------------------------------
ABSENT

================================================================================
FLEET STATE
================================================================================

data/backlog.md
--------------------------------------------------------------------------------
ABSENT

Work under way (state/*.meta)
--------------------------------------------------------------------------------
(none)

Orphan status logs (state/*.status without matching .meta)
--------------------------------------------------------------------------------
(none)

AFK
--------------------------------------------------------------------------------
absent

================================================================================
NEXT STEP
================================================================================
Follow the supervision operating instructions block above for harness 'claude'.
This script never starts supervision itself.

The digest above is complete for this session start. Do NOT re-read
persona.md, config/persona.md, data/projects.md, data/secondmates.md,
data/captain.md, data/captain-shared.md, data/learnings.md,
or state/*.meta now - they were just printed in full.
Do NOT bulk-read data/backlog.md now either: the compact identity/metadata
listing was just printed with a pointer for targeted full-body follow-up.
Do NOT bulk-read state/*.status now either: their bounded tails were just
printed with full log paths for targeted follow-up when older wake-event
history is actually needed. Re-reading everything defeats the entire point
of this command. Re-read a file only if this digest flagged it ABSENT (then
rebuild or create it per AGENTS.md), its contents looked unparseable/corrupt,
or an individual full status log is needed for older wake-event history.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-session-start.test.sh (34/34 passed, including the 4 new persona tests: tracked default printed ahead of CONTEXT, local config/persona.md override fully replaces rather than merges, fully-absent persona reported as needing repair, unreadable active persona file reported as needing repair)
• Manual end-to-end run of bin/fm-session-start.sh against this repo's real root and a fresh throwaway FM_HOME, capturing the full digest transcript
• grep -n "^# --- [0-9]" bin/fm-session-start.sh compared against AGENTS.md section 3's numbered list to confirm the step numbering (1 lock, 2 bootstrap, 3 wake-drain, 4 supervision, 5 persona, 6 context, 7 fleet, 8 closing) matches both the doc and the script's actual execution order
• Reviewed the fmx-respond SKILL.md diff confirming the public-reply voice section now requires persona.md's mandatory address rule while keeping seasoning optional (documentation-only change with no executable test surface)

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change introduces a configurable persona contract. Session startup loads config/persona.md or persona.md, prints it before digests, and reports missing sources. Documentation, repository guidance, and tests cover the new behavior.

Changes

Persona-driven session behavior

Layer / File(s)	Summary
Persona contract and repository guidance .agents/skills/fmx-respond/SKILL.md, AGENTS.md, CONTRIBUTING.md, docs/configuration.md, docs/documentation-audiences.json, persona.md	Defines the tracked persona, local override semantics, voice rules, vocabulary, and routine acknowledgment behavior.
Session persona loading bin/fm-session-start.sh	Loads the local persona override before the tracked persona, prints the selected content before session digests, and reports missing or empty sources.
Persona behavior validation tests/fm-session-start.test.sh	Adds fixture setup and tests for tracked output, local replacement, output ordering, and missing persona diagnostics.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: kunchenguid

Sequence Diagram(s)

sequenceDiagram
  participant SessionStart as fm-session-start.sh
  participant PersonaSources as persona.md and config/persona.md
  participant DigestStages as context and fleet digests
  SessionStart->>PersonaSources: Resolve local override or tracked persona
  PersonaSources-->>SessionStart: Return persona contents or diagnostics
  SessionStart->>SessionStart: Print PERSONA section
  SessionStart->>DigestStages: Print subsequent digests

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: extracting a swappable captain-facing persona into persona.md.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fm/persona-swappable-refactor

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agents/skills/fmx-respond/SKILL.md:
- Around line 107-110: Update the public-facing response guidance in the
firstmate voice section to require all mandatory address rules from the active
persona, including direct captain address at least once per response. Keep
optional address terms discretionary when using replacement personas, and
preserve the existing allowance for natural persona seasoning.

In `@AGENTS.md`:
- Around line 151-156: Align all session-stage numbering with the actual emitted
order: update AGENTS.md lines 151-156, bin/fm-session-start.sh lines 38-51,
lines 411-427, and line 498 so Persona, Context, Fleet-state, Supervision, and
the closing reminder use one consistent sequence; preserve the existing
execution order and labels.

In `@bin/fm-session-start.sh`:
- Around line 151-180: The active persona path must be readable before its
contents are printed. Update print_persona, using the source selected by
resolve_persona_path, to detect an unreadable local override or tracked default
before cat, emit a source-specific repair diagnostic, and return safely without
triggering startup failure. Add regression coverage for unreadable files in both
selected-source cases.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2c48bdae-2e64-49f9-84ba-65008015f89d

📥 Commits

Reviewing files that changed from the base of the PR and between 1aefa30 and 0973e4c.

📒 Files selected for processing (8)

• .agents/skills/fmx-respond/SKILL.md
• AGENTS.md
• CONTRIBUTING.md
• bin/fm-session-start.sh
• docs/configuration.md
• docs/documentation-audiences.json
• persona.md
• tests/fm-session-start.test.sh