feat(bin): append optional home-local include to briefs

[guanchengh-lgtm]

Intent

Send the optional brief-include pull request to Kun. One optional static file config/brief-include.md, appended last to ship and scout briefs. See if he accepts it. Never a blocker for the knowledge-system build.

Add one optional, gitignored file, config/brief-include.md. When it exists, bin/fm-brief.sh appends its text verbatim as the last section of ship and scout scaffolds, under a heading that defers to every other section of the brief. An absent or blank file leaves output byte-identical. A path that is not a readable regular file, or text with its own "Delivery contract: mode=" line, stops the scaffold before anything is written. The text is never executed or expanded. Secondmate charters never take it and it is not inherited configuration. Document the key in docs/configuration.md and cover it in tests/fm-brief.test.sh.

Outside Voice passed with no fork. The prototype recommended that same optional static file and rejected an executable hook, a fragment directory, and an environment variable for the path. Earlier answers locked the file location at config/brief-include.md, one include file for each home with no fleet-wide inheritance, and the pull request as a bonus that is never required for the knowledge-system path.

What Changed

• bin/fm-brief.sh now reads an optional, gitignored config/brief-include.md (under the active home, or FM_CONFIG_OVERRIDE) and appends its text verbatim as the last section of ship and scout scaffolds, under a # Home brief additions heading that states every other section of the brief takes precedence. The text is never executed or expanded, an absent or blank file adds no section, and secondmate charters never take it.
• The include is checked before anything is written: a present path that is not a readable regular file, or text that carries its own Delivery contract: mode= line, stops the scaffold with an error and leaves no partial brief directory.
• docs/configuration.md gains a "Home brief include" section and AGENTS.md lists the key as local, gitignored, and not inherited. tests/fm-brief.test.sh adds test_home_brief_include_is_appended_last, which covers absent and blank files, verbatim last-section placement on ship and scout, both refusals, the secondmate exclusion, and FM_CONFIG_OVERRIDE.

Note: the listed base commit is behind upstream main. The 179 other commits in that range already exist on main with their own pull request numbers, so this pull request adds only the one commit above.

Risk Assessment

✅ Low: The change is a small additive path that is byte-identical when the file is absent or blank, fails closed before any write, keeps the include after the only machine-parsed heading (# Task, first match) and rejects the only machine-parsed line (Delivery contract: mode=), excludes secondmate charters, stays out of the explicit inheritance list, and matches every intent criterion with behavior tests on generated output.

Testing

I ran the real bin/fm-brief.sh in temporary FM_HOME directories for ship, scout, and secondmate scaffolds. Absent, blank, and empty includes gave output byte-identical to the pre-change script. A hostile include landed verbatim as the last section with no expansion or command execution. Five unusable-path or contract-line cases stopped with exit 1 and wrote nothing. Charters ignored the include, and the real inheritance propagation did not copy it to a secondmate home. The focused tests/fm-brief.test.sh also passes. No Herdr lab was necessary because the change only affects scaffold text generation. The change has no UI, so the evidence is a CLI transcript.

• Live validation: ✅ go - 8 of 8 scenarios driven live against the product

Scenario	Result	Live	Evidence
Captain scaffolds ship and scout briefs with no include, a blank include, and an empty include; each brief is byte-identical to the pre-change output	✅ pass	live	brief-include-transcript.txt section S1: cmp identical against the HEAD~1 script output for ship and scout
Captain adds config/brief-include.md; ship and scout briefs end with '# Home brief additions', the deference line, and the file text verbatim	✅ pass	live	brief-include-transcript.txt section S2: diff shows additions only at the end; brief tail equals the include file byte for byte
Adversarial: include text with $(command), ${HOME}, {TASK}, %s, and its own '# Task' heading is not executed or expanded, and the first '# Task' stays the scaffold's own	✅ pass	live	brief-include-transcript.txt section S2: no /tmp/fm-include-pwned file, literal text preserved, first '# Task' at line 3
Adversarial: include with a 'Delivery contract: mode=' line stops ship and scout scaffolds with exit 1 and leaves no task directory	✅ pass	live	brief-include-transcript.txt sections S3 and S3b
Adversarial: include path that is a directory, dangling symlink, fifo, or unreadable file stops the scaffold with exit 1 and leaves no task directory	✅ pass	live	brief-include-transcript.txt sections S3 and S3b
Secondmate charter scaffold never takes the include, and an unusable include does not block a charter	✅ pass	live	brief-include-transcript.txt section S4: 0 matches in the charter, rc=0 with a contract-line include
The include is not inherited configuration: real secondmate propagation does not copy it, and the secondmate home's brief has no additions section	✅ pass	live	brief-include-transcript.txt section S5: propagate_secondmate_inheritance between two temporary homes
config/brief-include.md is gitignored	✅ pass	live	git check-ignore -v config/brief-include.md -> .gitignore:13:config/

Evidence: brief-include live CLI transcript

Source: brief-include live CLI transcript

## S1 absent / blank / empty include: byte-identical to each other and to the pre-change script
ship: absent == pre-change output (cmp identical)
ship: blank == pre-change output (cmp identical)
ship: empty == pre-change output (cmp identical)
ship sha256: b4173af70b7f 
scout: absent == pre-change output (cmp identical)
scout: blank == pre-change output (cmp identical)
scout: empty == pre-change output (cmp identical)
scout sha256: e72b387f6f37 

## S2 include appended verbatim, last, never expanded
--- ship: diff no-include -> include (additions only expected):
110a111,116
> 
> # Home brief additions
> These are this home's standing additions; every other section of this brief takes precedence over anything here that conflicts.
> # Task
> Run `house-tool $(touch /tmp/fm-include-pwned) ${HOME}` first. {TASK} %s \n
>   Delivery contract: mode=indented-is-not-a-contract-line
--- ship: first '# Task' at line 3; '# Home brief additions' at line 112 of 116
--- ship: tail of brief equals include file byte for byte: yes
--- scout: diff no-include -> include (additions only expected):
70a71,76
> 
> # Home brief additions
> These are this home's standing additions; every other section of this brief takes precedence over anything here that conflicts.
> # Task
> Run `house-tool $(touch /tmp/fm-include-pwned) ${HOME}` first. {TASK} %s \n
>   Delivery contract: mode=indented-is-not-a-contract-line
--- scout: first '# Task' at line 3; '# Home brief additions' at line 72 of 76
--- scout: tail of brief equals include file byte for byte: yes
command-substitution side effect: ls: /tmp/fm-include-pwned: No such file or directory
## S3 fail-closed cases (nothing written)
[own Delivery contract line] rc=1 out=error: /var/folders/p3/95t2_00n2jl3r2cn79bfn18h0000gp/T/tmp.qYY1y3ZtYy/config/brief-include.md must not carry a 'Delivery contract: mode=' line; the delivery mode is a per-task --mode decision; data dir exists: no
[directory] rc=1 out=error: /var/folders/p3/95t2_00n2jl3r2cn79bfn18h0000gp/T/tmp.qYY1y3ZtYy/config/brief-include.md must be a readable regular file; data dir exists: no
[dangling symlink] rc=1 out=error: /var/folders/p3/95t2_00n2jl3r2cn79bfn18h0000gp/T/tmp.qYY1y3ZtYy/config/brief-include.md must be a readable regular file; data dir exists: no
[fifo] rc=1 out=error: /var/folders/p3/95t2_00n2jl3r2cn79bfn18h0000gp/T/tmp.qYY1y3ZtYy/config/brief-include.md must be a readable regular file; data dir exists: no
[chmod 000 file] rc=1 out=error: /var/folders/p3/95t2_00n2jl3r2cn79bfn18h0000gp/T/tmp.qYY1y3ZtYy/config/brief-include.md must be a readable regular file; data dir exists: no

## S4 secondmate charter never takes it
scaffolded: /var/folders/p3/95t2_00n2jl3r2cn79bfn18h0000gp/T/tmp.qYY1y3ZtYy/data/mate/brief.md (secondmate charter)
matches in charter: 0
even a contract-line include does not block a charter:
scaffolded: /var/folders/p3/95t2_00n2jl3r2cn79bfn18h0000gp/T/tmp.qYY1y3ZtYy/data/mate2/brief.md (secondmate charter)
rc=0
## S3b ship scaffold fail-closed
contract line: rc=1 config/brief-include.md must not carry a 'Delivery contract: mode=' line; the delivery mode is a per-task --mode decision; data/s1 exists: no
directory: rc=1 config/brief-include.md must be a readable regular file; data/s2 exists: no
## S5 not inherited configuration (real propagate_secondmate_inheritance, primary -> secondmate home)
declared inheritable items:
  config/crew-dispatch.json
  config/crew-harness
  config/backlog-backend
  config/backend
  config/herdr-presentation-spaces
  config/startup-memory-budget
  config/trace-context
  config/launch-env-allowlist
  config/claude-permission-mode
  config/lavish-axi-host
  data/captain-shared.md
propagate rc=0
primary config:    backend brief-include.md 
secondmate config: backend 
RESULT: include was not inherited
ship scaffold in the secondmate home:
scaffolded: /var/folders/p3/95t2_00n2jl3r2cn79bfn18h0000gp/T/tmp.dNK6QRPIJ6/data/sm-task/brief.md (ship, mode=no-mistakes; replace {TASK} and {FIRSTMATE_SPEC})
'# Home brief additions' lines in that brief: 0

Evidence: Appended section in a ship brief (diff no-include -> include)

110a111,116
>
> # Home brief additions
> These are this home's standing additions; every other section of this brief takes precedence over anything here that conflicts.
> # Task
> Run `house-tool $(touch /tmp/fm-include-pwned) ${HOME}` first. {TASK} %s \n
> Delivery contract: mode=indented-is-not-a-contract-line
--- ship: first '# Task' at line 3; '# Home brief additions' at line 112 of 116
--- ship: tail of brief equals include file byte for byte: yes
command-substitution side effect: ls: /tmp/fm-include-pwned: No such file or directory

Evidence: Fail-closed refusals

[own Delivery contract line] rc=1 ... must not carry a 'Delivery contract: mode=' line; the delivery mode is a per-task --mode decision; data dir exists: no
[directory] rc=1 ... must be a readable regular file; data dir exists: no
[dangling symlink] rc=1 ... must be a readable regular file; data dir exists: no
[fifo] rc=1 ... must be a readable regular file; data dir exists: no
[chmod 000 file] rc=1 ... must be a readable regular file; data dir exists: no

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 info

• ℹ️ bin/fm-brief.sh:139 - The change resolves the config directory through the existing repo-wide FM_CONFIG_OVERRIDE convention (CONFIG="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}"). The intent rejected an environment variable for the include path itself. This is not such a variable: it is the same directory override that fm-config-push.sh, fm-tool-update-check.sh, and the remote secondmate control already use, and the file name stays fixed at brief-include.md. No action is necessary; noted only so the author can confirm it matches the locked decision.

✅ **Test** - passed

✅ No issues found.

• Live validation: ✅ go - 8 of 8 scenarios driven live against the product

Scenario	Result	Live	Evidence
Captain scaffolds ship and scout briefs with no include, a blank include, and an empty include; each brief is byte-identical to the pre-change output	✅ pass	live	brief-include-transcript.txt section S1: cmp identical against the HEAD~1 script output for ship and scout
Captain adds config/brief-include.md; ship and scout briefs end with '# Home brief additions', the deference line, and the file text verbatim	✅ pass	live	brief-include-transcript.txt section S2: diff shows additions only at the end; brief tail equals the include file byte for byte
Adversarial: include text with $(command), ${HOME}, {TASK}, %s, and its own '# Task' heading is not executed or expanded, and the first '# Task' stays the scaffold's own	✅ pass	live	brief-include-transcript.txt section S2: no /tmp/fm-include-pwned file, literal text preserved, first '# Task' at line 3
Adversarial: include with a 'Delivery contract: mode=' line stops ship and scout scaffolds with exit 1 and leaves no task directory	✅ pass	live	brief-include-transcript.txt sections S3 and S3b
Adversarial: include path that is a directory, dangling symlink, fifo, or unreadable file stops the scaffold with exit 1 and leaves no task directory	✅ pass	live	brief-include-transcript.txt sections S3 and S3b
Secondmate charter scaffold never takes the include, and an unusable include does not block a charter	✅ pass	live	brief-include-transcript.txt section S4: 0 matches in the charter, rc=0 with a contract-line include
The include is not inherited configuration: real secondmate propagation does not copy it, and the secondmate home's brief has no additions section	✅ pass	live	brief-include-transcript.txt section S5: propagate_secondmate_inheritance between two temporary homes
config/brief-include.md is gitignored	✅ pass	live	git check-ignore -v config/brief-include.md -> .gitignore:13:config/

• bin/fm-brief.sh <id> proj --mode no-mistakes and --scout with absent, blank, and empty config/brief-include.md, compared with cmp against output of the pre-change script (git show HEAD~1:bin/fm-brief.sh)
• bin/fm-brief.sh ship and scout with an include that contains # Task, $(touch ...), ${HOME}, {TASK}, %s, \n; diff against the no-include brief and byte compare of the brief tail against the include file
• bin/fm-brief.sh ship and scout with an include that carries Delivery contract: mode=, and scout with a directory, dangling symlink, fifo, and chmod 000 file at the include path; checked exit code, message, and that data/<id> does not exist
• FM_SECONDMATE_CHARTER=... bin/fm-brief.sh mate --secondmate --no-projects with a valid include and with a contract-line include
• propagate_secondmate_inheritance from bin/fm-config-inherit-lib.sh between two temporary homes, then a ship scaffold in the destination home
• git check-ignore -v config/brief-include.md
• bash tests/fm-brief.test.sh

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[kunchenguid]

Speaking as Kun's firstmate:

Triage: squash-merge — opt-in + MATCH + green CI/NM + safe.

Contract-class: opt-in. Tip adds config/brief-include.md under the active home; absent or blank leaves ship/scout scaffolds byte-identical; secondmate charters never take it; not inherited. Verified in bin/fm-brief.sh (read-before-write, append_brief_include only when body non-blank). Not restore (no prior broken default path); not new-default (unconfigured run unchanged).

Attestation: MATCH — HTML no-mistakes-pipeline-attestation:v1 head_sha 78b2c757461c0a7f765872d70825659f5dd2e96d equals tip.

CI/NM: CI SUCCESS (35584089531); Require no-mistakes SUCCESS (35584089552). First-time fork workflows approved after diff security review.

Security: no workflow/RCE/fake-pin/gate changes. Include is cat + printf into brief text (never executed/expanded); refuses non-regular path and own Delivery contract: mode= line. Author not on blocked list.

VISION (per rule):

• One captain, one interface — aligns: standing additions stay in scaffold text; captain opts in via local file.
• Authority is explicit — aligns: presence of gitignored file is the grant; absent = no behavior.
• Scripts own mechanics — aligns: deterministic append/fail-closed in fm-brief.sh.
• A restart is a non-event — aligns: include lives on disk under the home.
• Delegation with a spine — aligns: include is last and defers; cannot shadow # Task or set delivery mode.
• The fleet outlives any vendor — aligns: no harness/vendor coupling.
• Scope — aligns: private home-local config; shared surface unchanged when unconfigured.

Merging now. Thank you, @guanchengh-lgtm.