fix(bin): prevent apostrophes from breaking fm-brief parsing

[mertnesvat]

Intent

The developer wanted the existing fm-brief Bash parser regression fix completed and shipped as a pull request to kunchenguid/firstmate, with the branch pushed through the approved mertnesvat/firstmate fork and without changing origin authority or merging. The intended change removes the apostrophe-sensitive wording inside the nested no-mistakes Definition-of-done heredoc, updates the related authority assertion, adds direct parser and brief regression coverage, and preserves the prior edit-site durability documentation and established Firstmate contracts. They required carrying forward the preserved commits non-destructively, validating Bash syntax, targeted and standard tests, and lint where the pinned ShellCheck is available, while documenting any ShellCheck limitation. After validation configuration issues were resolved, they explicitly asked to rerun no-mistakes with Codex gpt-5.6-sol, drive every gate without --yes through a checks-green upstream PR, and include the user-visible impact, root cause, exact fix, coverage, and test evidence in the PR explanation.

What Changed

• Reword the no-mistakes authority guidance to prevent an apostrophe from breaking fm-brief Bash parsing inside the nested Definition-of-done heredoc.
• Document the apostrophe-safe heredoc invariant and extend brief and authority regression assertions for the generated wording.

Risk Assessment

✅ Low: Captain, the change is narrowly scoped, preserves authority semantics, and adds appropriate parser and generated-brief regression coverage with no material source risks found.

Testing

Diff and guidance inspection, both focused canonical test scripts, Bash parsing, and an end-to-end no-mistakes brief scaffold succeeded; the artifact confirms apostrophe-safe wording, preserved backticks, and no heredoc leakage.

Evidence: End-to-end fm-brief CLI transcript

$ bash -n bin/fm-brief.sh
exit=0

$ FM_HOME=<evidence-home> bin/fm-brief.sh parser-fix-demo demo-project
scaffolded: /var/folders/3j/dm3hpyb937ncdkrn10tc37c40000gn/T/no-mistakes-evidence/01KYJXHHYDPKSGAATQP1M1S7A7/fm-brief-e2e-home.OkaeLi/data/parser-fix-demo/brief.md (ship, mode=no-mistakes; replace {TASK})
exit=0

Generated Definition-of-done excerpt:
# Definition of done
The task is complete only when committed on your branch.
When you believe it is complete, append `done: {summary}` to the status file and stop.
Firstmate will then instruct you to run /no-mistakes to validate and ship a PR.

You drive no-mistakes by responding to its gates, not by implementing fixes.
Follow the guidance no-mistakes itself provides for the mechanics: it loads when you invoke /no-mistakes, and `no-mistakes axi run --help` plus the `help` lines in each `axi` response are authoritative and version-matched to the installed binary.
Do not hand-edit, commit, or fix findings yourself while a run is active - the pipeline applies every fix.

Two firstmate-specific rules layer on top of that guidance:
- ask-user findings are never yours to answer: escalate to firstmate (rule 6) and stop.
  Firstmate applies the authority contract in its `AGENTS.md` and obtains any required captain decision.
  When the decision comes back, feed it to the gate with `no-mistakes axi respond` and let the pipeline apply it - do not route the question to "the user" or implement the fix yourself.
- Avoid `--yes`: it would silently bypass the authority check applied by firstmate and any required captain escalation.

After /no-mistakes reports CI green (the CI-ready return point - do not wait for it to keep monitoring in the background until merge), append `done: PR {url} checks green` and stop. You are finished.

Verification:
apostrophe-safe guidance wording present: yes
apostrophe-safe authority wording present: yes
literal backticks preserved: yes
legacy apostrophe wording absent: yes
heredoc marker leakage absent: yes

Generated brief: /var/folders/3j/dm3hpyb937ncdkrn10tc37c40000gn/T/no-mistakes-evidence/01KYJXHHYDPKSGAATQP1M1S7A7/fm-brief-e2e-home.OkaeLi/data/parser-fix-demo/brief.md

Evidence: Generated no-mistakes implementation brief

You are a crewmate: an autonomous worker agent managed by firstmate. Work on your own; do not wait for a human.

# Task
{TASK}

# Herdr lifecycle declaration - NOT ENABLED
**HARD SAFETY GATE:** this scaffold cannot inspect the task text that replaces `{TASK}` later.
If the task will start, stop, delete, restart, profile, or otherwise drive Herdr lifecycle behavior, stop and regenerate the brief with `--herdr-lab` before dispatch.
Do not add Herdr lifecycle commands to this unguarded brief by hand.

# Setup
You are in a disposable git worktree of demo-project, at a detached HEAD on a clean default branch.

**Verify isolation before anything else.** Run `pwd -P` and `git rev-parse --show-toplevel`; both must resolve to the disposable task worktree you were launched in, such as a treehouse pool path or an Orca-managed worktree, not the primary checkout firstmate operates from.
The path check is authoritative: `git rev-parse --git-dir` and `git rev-parse --git-common-dir` can help inspect the repo, but they do not prove you are outside the primary checkout.
If the top-level path is the primary checkout or not the worktree you were launched in, STOP - do not branch or commit here - append `blocked: launched in primary checkout, not an isolated worktree` to the status file and stop.

1. First action: create your branch: `git checkout -b fm/parser-fix-demo`
2. Run `no-mistakes doctor`; if it reports the repo is not initialized here, run `no-mistakes init`.

# Rules
1. Never push to the default branch. Never merge a PR.
2. Stay inside this worktree; modify nothing outside it.
3. Use gh-axi for GitHub operations and chrome-devtools-axi for browser operations.
4. Report status by appending one line:
   `echo "{state}: {one short line}" >> '/var/folders/3j/dm3hpyb937ncdkrn10tc37c40000gn/T/no-mistakes-evidence/01KYJXHHYDPKSGAATQP1M1S7A7/fm-brief-e2e-home.OkaeLi/state/parser-fix-demo.status'`
   States: working, needs-decision, blocked, paused, done, failed.
   Each append wakes firstmate, so report sparingly: only phase changes a supervisor
   would act on (setup done, bug reproduced, fix implemented, validation passed) and the
   needs-decision/blocked/paused/done/failed states. No step-by-step FYI progress lines;
   firstmate reads your pane for that.
   A mid-task `working:` line (including setup complete) is nonterminal: do not end the
   turn after it; continue the same stage until a defined `done:` gate under Definition of done.
   Use `paused: {why}` - distinct from `blocked:` - ONLY when you are deliberately idling on a
   known external wait you expect to clear on its own (an upstream release, a rate-limit reset,
   a scheduled window): firstmate then leaves your idle pane alone and rechecks it on a long
   cadence instead of treating it as a possible wedge. Use `blocked:` when you are stuck and need help.
5. If you hit the same obstacle twice, append `blocked: {why}` and stop; firstmate will help.
6. If a decision belongs above the implementation worker (product choices, destructive actions, ask-user findings),
   append `needs-decision: {summary of options}` and stop. Firstmate will apply the configured authority and reply with the decision.
   When firstmate replies or a blocker clears and you resume, append `resolved: {how it was decided or unblocked}` (add the same `[key=<slug>]` if you opened it with one) so the decision or blocker is durably closed and does not keep resurfacing.
7. Never stop, restart, or update the shared `no-mistakes` daemon - it is one instance serving
   every lane/home, so restarting it kills other lanes' in-flight pipeline runs. On ANY no-mistakes
   daemon error, append `blocked: {the daemon error}` and stop; only firstmate manages the daemon.

# Project memory
If `AGENTS.md` or `CLAUDE.md` already exists, or if this task produced durable project-intrinsic knowledge, run `/Users/mert/.no-mistakes/worktrees/9e247034af7a/01KYJXHHYDPKSGAATQP1M1S7A7/bin/fm-ensure-agents-md.sh .` in the worktree.
Record only project knowledge useful to almost every future session.
For anything the codebase already shows, prefer a pointer to the authoritative file, command, or doc over copying the detail.
If you touch a project `AGENTS.md` that lacks `## Maintaining this file`, add that short self-governance section from `/Users/mert/.no-mistakes/worktrees/9e247034af7a/01KYJXHHYDPKSGAATQP1M1S7A7/bin/fm-ensure-agents-md.sh` in the same pass.
Keep it proportionate: skip `AGENTS.md` edits for trivial tasks that produced no durable project knowledge.

# Definition of done
The task is complete only when committed on your branch.
When you believe it is complete, append `done: {summary}` to the status file and stop.
Firstmate will then instruct you to run /no-mistakes to validate and ship a PR.

You drive no-mistakes by responding to its gates, not by implementing fixes.
Follow the guidance no-mistakes itself provides for the mechanics: it loads when you invoke /no-mistakes, and `no-mistakes axi run --help` plus the `help` lines in each `axi` response are authoritative and version-matched to the installed binary.
Do not hand-edit, commit, or fix findings yourself while a run is active - the pipeline applies every fix.

Two firstmate-specific rules layer on top of that guidance:
- ask-user findings are never yours to answer: escalate to firstmate (rule 6) and stop.
  Firstmate applies the authority contract in its `AGENTS.md` and obtains any required captain decision.
  When the decision comes back, feed it to the gate with `no-mistakes axi respond` and let the pipeline apply it - do not route the question to "the user" or implement the fix yourself.
- Avoid `--yes`: it would silently bypass the authority check applied by firstmate and any required captain escalation.

After /no-mistakes reports CI green (the CI-ready return point - do not wait for it to keep monitoring in the background until merge), append `done: PR {url} checks green` and stop. You are finished.

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.

• Inspected repository guidance and the base-to-target diff.
• bin/fm-test-run.sh tests/fm-brief.test.sh
• bin/fm-test-run.sh tests/fm-ask-user-authority.test.sh
• bash -n bin/fm-brief.sh
• FM_HOME=<evidence-home> bin/fm-brief.sh parser-fix-demo demo-project, followed by direct inspection of its generated Definition-of-done section

✅ **Document** - passed

✅ No issues found.

⚠️ **Lint** - 1 warning

• ⚠️ linter found issues (exit code 127)

✅ **Push** - passed

✅ No issues found.

[kunchenguid]

thanks for digging into this. i merged #1093, which fixes the same bash 3.2 parse failure by moving the DOD heredocs out of command substitution, so the apostrophe wording no longer needs to change. closing this one as superseded. appreciate the help here.