ci: enforce contributor guardrails

[kunchenguid]

Intent

The captain wants firstmate to have the same contributor guardrails as his other repos (lavish-axi, gh-axi, trial-by-combat, etc.): a CONTRIBUTING.md guide plus GitHub Actions enforcement for PRs. Adapted from the standard set: (1) CONTRIBUTING.md documenting the mandatory git-push-no-mistakes flow and firstmate-specific repo conventions (template repo, AGENTS.md is the contract, CLAUDE.md/.claude/skills symlinks, tracked-vs-local split, bash + shellcheck, one sentence per line in Markdown); (2) no-mistakes-required.yml copied from lavish-axi minus the release-please bot exemption since this repo has no releases; (3) ci.yml that shellchecks bin/*.sh and checks repo invariants (symlinks intact, personal fleet paths like data/ state/ config/ projects/ untracked). guard-generated-files.yml was deliberately NOT ported because firstmate has no release-please or generated files. The SC2016 shellcheck directive added in bin/fm-spawn.sh is deliberate: the single-quoted launch templates defer expansion to the crewmate tmux pane, and the directive makes shellcheck pass clean so CI can enforce it. All CI steps were verified to pass locally before commit.

What Changed

• Added GitHub Actions checks for shell scripts, repository invariants, and PR bodies signed by the no-mistakes flow.
• Added a CONTRIBUTING.md guide covering the required no-mistakes workflow and firstmate repository conventions.
• Updated firstmate docs and spawn script shellcheck annotations so the new CI guardrails match the repo layout and launch-template behavior.

Risk Assessment

⚠️ Medium: The change is small and mostly documentation/CI guardrails, but the central enforcement workflow can be trivially bypassed if treated as a mandatory policy gate.

Testing

Bootstrap was clean; I exercised the PR enforcement script end-to-end for signed and unsigned human PR bodies, exercised the CI repo invariant checks, confirmed the omitted generated-file guard and lack of release-please exemption, and left the worktree clean. I did not run the shellcheck CI step because this testing prompt explicitly forbids linters/static analysis.

Evidence: PR signature enforcement transcript

Scenario: human PR created by no-mistakes with signature Found no-mistakes signature in PR #42 body. Result: accepted Scenario: human PR without no-mistakes signature ::error::This PR was not raised through no-mistakes. Contributions to this repository must be submitted via 'git push no-mistakes'. That pipeline runs the required review/test/lint/CI steps and writes a deterministic '## Pipeline' section into the PR body containing: Updates from git push no-mistakes See CONTRIBUTING.md for setup and the full workflow. PR author: octocat Result: rejected

Scenario: human PR created by no-mistakes with signature
Found no-mistakes signature in PR #42 body.
Result: accepted

Scenario: human PR without no-mistakes signature
::error::This PR was not raised through no-mistakes.

Contributions to this repository must be submitted via 'git push no-mistakes'.
That pipeline runs the required review/test/lint/CI steps and writes a
deterministic '## Pipeline' section into the PR body containing:

    Updates from [git push no-mistakes](https://github.com/kunchenguid/no-mistakes)

See CONTRIBUTING.md for setup and the full workflow.

PR author: octocat
Result: rejected

Evidence: Repo invariant transcript

Scenario: CI symlink invariants CLAUDE.md -> AGENTS.md .claude/skills -> ../.agents/skills Scenario: CI personal fleet path invariant No tracked files under data/, state/, config/, projects/, or .no-mistakes/. Scenario: generated-file guard deliberately absent No .github/workflows/guard-generated-files.yml tracked.

Scenario: CI symlink invariants
CLAUDE.md -> AGENTS.md
.claude/skills -> ../.agents/skills

Scenario: CI personal fleet path invariant
No tracked files under data/, state/, config/, projects/, or .no-mistakes/.

Scenario: generated-file guard deliberately absent
No .github/workflows/guard-generated-files.yml tracked.

- Outcome: ⚠️ 1 warning across 1 run (2m8s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 warning

• ⚠️ .github/workflows/no-mistakes-required.yml:31 - The required check accepts any PR body containing this public marker, so a manually opened PR can paste the string and pass without ever going through no-mistakes. If this is meant to enforce the gate rather than serve as an advisory convention, validate a non-forgeable signal from the no-mistakes run or document the limitation explicitly.

⚠️ **Test** - 1 warning

• ⚠️ .github/workflows/ci.yml:18 - I did not run shellcheck bin/*.sh, so I could not directly demonstrate the new CI lint job passes. This validation prompt explicitly forbids linters/static analysis, and shellcheck is a linter.
• bin/fm-bootstrap.sh
• Simulated .github/workflows/no-mistakes-required.yml PR-body check with a no-mistakes-signed human PR body and a manual human PR body, recording /var/folders/5x/4nqprlbx0518k3ybcb1sz6gr0000gn/T/no-mistakes-evidence/01KTX6NK7HKCCY4H1Y4NF0X775/no-mistakes-required-transcript.txt
• Executed .github/workflows/ci.yml repo invariant commands for CLAUDE.md, .claude/skills, and personal fleet paths, plus verified guard-generated-files.yml is not tracked, recording /var/folders/5x/4nqprlbx0518k3ybcb1sz6gr0000gn/T/no-mistakes-evidence/01KTX6NK7HKCCY4H1Y4NF0X775/repo-invariants-transcript.txt
• Searched workflows for release-please, github-actions[bot], dependabot[bot], and guard-generated-files to confirm only the intended bot exemptions are present and the generated-file guard was not ported
• Searched bin/*.sh for the deliberate SC2016 directive documenting deferred crewmate-pane expansion
• git status --short

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.