Chapter 10 · Project Modes and Merge Permissions: no-mistakes / direct-PR / local-only

Chapter goals: Master the semantics and适用场景 of three explicit project delivery modes (no-mistakes / direct-PR / local-only), understand the +yolo merge autonomy flag and its relationship with Hard Rule 2, and learn to select the right delivery path for different risk levels.

10.1 Why Delivery Mode Must Be "Explicit"

In Chapter 8 we learned the two task shapes: ship changes the project, scout produces a report. But after a ship task改完代码, how the成果 lands is同样 a question that must be clarified upfront — full验证 pipeline then open a PR? Directly open a PR? Or merge locally only?

If this decision is left to on-the-fly judgment, two types of事故 occur:低风险改动被迫走重流程拖慢节奏; 高风险改动却悄悄绕过了验证直接上线. So FirstMate规定: each task determines its delivery mode and merge posture at intake (受理), and once written into the brief, the mode cannot drift.

The架构文档原话:

Delivery modes are explicit per task:

no-mistakes tasks run the full validation pipeline,
direct-PR tasks open PRs without that pipeline,
local-only tasks stay local until firstmate performs
an approved fast-forward merge.

Each task's mode and yolo merge posture are
firstmate's decision at intake.

10.2 Three Project Modes拆解

Mode 1: no-mistakes (full validation pipeline)

This is the heaviest delivery path. After the ship task completes, the full validation pipeline must pass before entering the merge flow. It适合核心业务仓库, 生产相关代码, CI纪律要求高的团队仓库. Two工程细节 to note:

• The validation evidence留存在 an orphan evidence branch — a branch with no shared history with the code branch, so evidence never混进 the crew branch or default branch;
• The .no-mistakes/ directory is local state, kept gitignored; if误提交, CI rejects it. disable_project_settings: true in .no-mistakes.yaml only生效 from a trusted default-branch checkout, preventing a pushed branch from偷偷启用自己的项目指令 during validation.

Mode 2: direct-PR (open PR directly)

Skip the no-mistakes pipeline; the task opens a PR directly upon completion. It适合有自己 CI的开源风格仓库 — GitHub/GitLab's check mechanism itself is a gate.日常功能开发, 文档改进多走这条路.

Mode 3: local-only (local landing only)

The task stays本地 until the firstmate performs an approved fast-forward merge. It does not走 the remote PR path, so这类项目始终留在主第一副手身边管理; fleet sync同步舰队时也会把 local-only 项目视为 benign skip. It适合个人实验项目, 还没有远程仓库的克隆.

Three modes delivery paths:

ship task complete
   │
   ├─ no-mistakes ──→ full validation pipeline → orphan evidence branch → PR merge
   │
   ├─ direct-PR ────→ open PR directly (rely on repo's own CI gate)
   │
   └─ local-only ───→ stay local → captain-approved fast-forward merge into主 local checkout

10.3 How Modes Flow: Brief Fixed, Spawn Validates

The mode is not a口头约定. Its flow链路 is刻意 designed to be "drift-proof":

1. Each project's standing posture and optional +yolo flag are recorded in the data/projects.md registry, as the captain's default decision with context, including the conditional no-mistakes-prod-only strategy;
2. At intake, the firstmate决定 the mode and yolo posture for this task;
3. The mode is explicitly passed to bin/fm-brief.sh; both mode and posture are explicitly passed to bin/fm-spawn.sh and bin/fm-promote.sh — these commands all refuse to guess the values they consume;
4. The ship brief writes the mode as one fixed machine-readable line; if spawn发现要启动的模式与记录不一致, it拒绝启动, guaranteeing "the指令给工人的" and "记录在案的交付方式" never diverge.

data/projects.md registry示意 (structure示意, not verbatim format):

project: github.com/captain/payments-core
posture: no-mistakes          ← standing posture
merge:   captain-approval     ← no yolo; default requires captain word

project: github.com/captain/blog
posture: direct-PR
merge:   +yolo                ← standing merge autonomy flag

Additionally, a "降级告警" guard protects against under-delivery: if a ship spawn's actual严谨度 is below the registered level (e.g., registered as no-mistakes but试图按更轻的模式交付), the system prints a deviation notice and continues — keeping you informed without擅自中断.

And bin/fm-project-mode.sh is the唯一解析器 for the registry, serving机械 consumers that "have no具体任务 at hand": fleet sync's local-only skip judgment, home seeding refusal, no-mistakes initialization etc.

10.4 Hard Rule 2: No Merge Without the Captain's Explicit Word

We learned the second of the five hard rules in Chapter 4:

Hard rule 2 — Never merge a PR without the captain's explicit word.

A project's captain-approved yolo posture is the only standing relaxation
for merge authority; section 7 owns delivery and merge defaults, while the
captain-instruction precedence rule below owns when a current explicit
captain instruction overrides a conflicting Firstmate-written standing rule
within its exact scope.

Three层次要分清:

1. 默认态: merging a PR requires the captain's explicit word ("merge it");
2. 常设放宽: only the captain-approved +yolo posture for a project can standing-relax merge authority — this is the only例外通道;
3. 指令优先级: AGENTS.md Section 7 owns delivery and merge defaults; but when the captain's current explicit instruction conflicts with a firstmate-written standing rule, "the current instruction takes precedence within its exact scope" is裁定 by a dedicated precedence rule.

In other words, even if you开 a project to +yolo, you can always当场下达相反的明确指示 to收回 this time's decision权; conversely, without +yolo, any "顺手合了" is a违规.

10.5 Technical Safeguards for Merge: fm-pr-merge.sh

The actual PR merge is executed by bin/fm-pr-merge.sh, which records pr= and available pr_head= via bin/fm-pr-check.sh before calling the forge CLI. Several hard constraints:

fm-pr-merge.sh input and validation:

Input requirements:
- Must be a完整规范 URL; reject malformed URLs and repo override flags

URL dispatch:
- https://github.com/<owner>/<repo>/pull/<n>
    → gh-axi pr merge <n> --repo <owner>/<repo> (default --squash,
      preserving explicit merge-method flags)
- https://<host>/<path>/-/merge_requests/<n> (GitLab MR)
    → glab mr merge <n> -R https://<host>/<path>
      (no merge-method flag; uses the project's own merge method)

More importantly, the real-time validation before merge. Merge only executes after these five conditions are confirmed via a live read:

Pre-merge conditions (live read,实时读取, no trusting cached metadata):

1. MR is in open状态
2. Mergeable
3. Conflict-free
4. All blocking discussions resolved
5. Pipeline on the current head succeeded

Once met, bind this merge to the verified head.
Recorded metadata is never the basis for these conditions —
because one rebase makes them stale.

This design translates "the captain said merge it" into a set of machine-verifiable safety premises, avoiding人肉确认造成的遗漏.

10.6 How to Select a Mode for a Project

Reference decision table:

Project Type	Recommended Mode	Rationale
Core生产代码仓库	no-mistakes	Full validation管线 prevents regressions
开源项目 / 有CI的仓库	direct-PR	Leverage existing CI as the gate
个人实验项目 / 无远程仓库	local-only	Stay local until approved; no remote风险
文档/配置变更	direct-PR or local-only	Low risk; skip heavy validation

10.7 Chapter Summary

• Three explicit modes: no-mistakes (full validation), direct-PR (skip to PR), local-only (stay local);
• +yolo is the only standing relaxation for merge authority; the captain can always override on-the-spot;
• Mode is locked at intake, passed显式 through brief → spawn → promote; commands refuse to guess;
• Merge requires five live-read conditions; cached metadata is not trusted;
• Select mode by project risk: core → no-mistakes, OSS → direct-PR, personal → local-only.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the purpose of the "orphan evidence branch" in no-mistakes mode?

2. What does the +yolo flag do?

3. Why does fm-pr-merge.sh refuse to trust cached metadata?

4. Which mode is recommended for a personal experiment project without a remote repo?

🛠️ Hands-On Exercises

1. Register a test project in data/projects.md with no-mistakes posture; dispatch a ship task and verify the orphan evidence branch is created.
2. Set +yolo on a project; dispatch a ship task; verify the merge proceeds without explicit captain word; thenoverride with an explicit "do not merge" instruction and verify it is respected.
3. Dispatch a local-only task; verify the work stays本地 and the merge requires explicit captain approval via fm-project-mode.sh.

Project modes understood. Next, zero-token event-driven supervision: watcher and turn-end guard.