Agent protocol hardening: commit-format Pre-Flight gate, harness branch acceptance, and memory-file mapping

Intent / The Why

PR #10060 (Claude Code harness wiring) surfaced four distinct collaboration-protocol gaps during its execution. Each caused friction that blocked or required redoing work in the session; left unpatched, they will cause the same friction for every new harness-based contributor.

1. The agent's first commit attempt was rejected for using chore(claude) (should be feat), placing the ticket ID in a trailing Refs #10059 paragraph (should be (#10059) appended to subject), and emitting a Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> footer (project-forbidden).

2. The repo's AGENTS.md §3 Pre-Flight Check enumerates Gate 1 (Ticket) + Gate 2 (Contextual Completeness) — making it possible to satisfy the documented gates while still violating the pull-request skill's commit protocol.

3. The §2 branching mandate assumes a single harness model. pull-request-workflow.md §2 prescribes agent/<ticket-id>-<descriptor> branches as if all harnesses operate identically, but this rule's intent (never commit to main/dev) is satisfied by two mechanically different means depending on harness:

   • Worktree-isolated harnesses (Claude Code): each session runs inside .claude/worktrees/<name>/ on an auto-generated branch; git mechanically refuses to share a branch across worktrees, so accidental dev-commit is blocked by the harness itself.
   • Shared-checkout harnesses (Gemini CLI, Antigravity): operate directly inside the main checkout; first git commit without an explicit branch lands on dev.

   The current §2 text only addresses the second case, making it read as harness-agnostic when it is not. A harness-aware refactor preserves intent and removes the false "rename your branch" pressure on worktree-based harnesses.

4. AGENTS_STARTUP.md §5 lists .agent/skills/ as the canonical skill discovery root but makes no mention of how each harness's auto-load memory file (.claude/CLAUDE.md, .gemini/settings.json, etc.) relates to AGENTS.md — forcing future harness-spawned agents to re-research the same question.

The Architectural Reality

• AGENTS.md §3 defines two gates; silent on commit format. The pull-request skill document exists but is only invoked via §7's PR Mandate — making it easy to satisfy §3 while committing in a format that violates the skill.
• .agent/skills/pull-request/references/pull-request-workflow.md §3 shows feat/fix/chore: message (#ID) but offers no criterion for selecting among the three types. Claude Code's harness-default co-author footer is not addressed.
• pull-request-workflow.md §2 treats agent/<ticket-id>-<descriptor> as a universal mandate. It is not — it is the correct safety rule for shared-checkout harnesses only. Worktree-isolated harnesses satisfy the same intent via a different mechanism (git worktree branch-exclusivity). Mandating a rename on worktree harnesses wastes turns and fights the tooling.
• AGENTS_STARTUP.md §5 discusses skill discovery but not harness→memory-file wiring. Claude Code auto-loads ./CLAUDE.md or ./.claude/CLAUDE.md; Gemini CLI uses .gemini/settings.json + .gemini/GEMINI.md. Each should symlink to AGENTS.md (as PR #10060 did for Claude Code) to preserve single-source-of-truth.

Scope (Single Atomic Commit — Standard Request, not Epic)

Four documentation edits in one PR:

1. .agent/skills/pull-request/references/pull-request-workflow.md §3 — add:

   • Type Selection block: feat for changes that unlock new capability (harness integrations, new workflows, new tooling surfaces). fix for restoring broken behavior. chore only when there is zero behavioral/capability delta (dependency bumps, auto-generated syncs, typo fixes). Decision rule: "Does this enable a new capability that did not exist before?" → feat.
   • Commit Message Hygiene block: FORBID Co-Authored-By: <name> <noreply@*> footers; specifically call out the Claude Code harness default that must be overridden. MANDATE (#TICKET_ID) appended to subject line — Refs #N or trailing paragraph is non-compliant.

2. AGENTS.md §3 Pre-Flight Check — add Gate 3:

   "I have consulted .agent/skills/pull-request/references/pull-request-workflow.md §3 and will emit a Conventional Commits subject of form type(scope): message (#TICKET_ID) with no <noreply@*> Co-Authored-By footers."

   Makes it structurally impossible to satisfy the Pre-Flight Check while violating commit format.

3. .agent/skills/pull-request/references/pull-request-workflow.md §2 — refactor into harness-aware subsections:

   • §2.1 Worktree-isolated harnesses (Claude Code-style): any non-main/dev branch name is acceptable, including harness-generated defaults (e.g., claude/goofy-tu-f83d87). Git worktree branch-exclusivity mechanically satisfies the mandate — no additional branching action required.
   • §2.2 Shared-checkout harnesses (Gemini CLI, Antigravity): MUST git checkout -b agent/<ticket-id>-<descriptor> before any code change. Without this, the first git commit will land on dev — a protocol violation.
   • §2.3 Safety net (universal): before the first commit, verify git branch --show-current returns something other than main/dev. If not, stop and branch.

   This preserves §2's gate intent while making the mechanism harness-explicit.

4. AGENTS_STARTUP.md §5 — add a subsection "Harness Memory-File Wiring" documenting:

   • Claude Code: auto-loads ./CLAUDE.md or ./.claude/CLAUDE.md (identical precedence)
   • Gemini CLI: .gemini/settings.json + .gemini/GEMINI.md
   • (extend as new harnesses are added)
   • Convention: symlink each harness memory file to AGENTS.md (pattern established by PR #10060).

Avoided Gold Standards / Traps

• Rejected: split into four separate tickets. All four edits touch the same agent-protocol surface area. One coherent PR preserves review efficiency and lets the gates-vs-skill cross-reference (Gate 3 ↔ §3 of pull-request-workflow) stay consistent across the change.
• Rejected: a single universal agent/<ticket>-<desc> branch mandate. Works only for shared-checkout harnesses where the agent physically can commit to dev. For worktree-isolated harnesses (Claude Code), the mandate fights the harness without adding safety — the intent is already mechanically enforced. The harness-aware §2.1 / §2.2 / §2.3 split is the correct framing.
• Rejected: add Gate 3 content directly in AGENTS.md rather than cross-referencing the skill. Would duplicate documentation and create drift. Gate 3 stays thin in AGENTS.md and delegates to the skill doc.
• Rejected: file get_context_frontier / sandman_handoff.md absence as a bug ticket. Per project state: these are expected during active graph enhancement work in #9999 and #10030 and will self-resolve on their merge.

Interaction with #10051

#10051 (Enhance Ticket-Intake Skill: Branch-Before-Code Mandate) is inherently a shared-checkout concern by the same logic as §2.2 above — the "branch before code" mandate is a safety rule for harnesses that can otherwise write directly into the main checkout's working tree. Claude Code worktrees mechanically satisfy it.

When #10051 is implemented, it should either:

• adopt the same §2.1 / §2.2 / §2.3 harness-aware framing explicitly, OR
• delegate to pull-request-workflow.md §2 to avoid double-documentation of the same rule under two skills.

Flagged for #10051's author / implementing agent.

Verification

1. Grep AGENTS.md post-merge: Gate 3 should appear in §3.
2. Grep pull-request-workflow.md post-merge: "Type Selection" and "Commit Message Hygiene" section headers should be present in §3; §2 should have explicit §2.1 / §2.2 / §2.3 subsections naming "worktree-isolated" and "shared-checkout" harnesses.
3. Grep AGENTS_STARTUP.md post-merge: "Harness Memory-File Wiring" subsection in §5 should list at least Claude Code and Gemini CLI.
4. Agent self-check: in a fresh Claude Code session after merge, trigger a mock commit scenario. The Pre-Flight Check recital should now include Gate 3 verbatim.
5. Cross-harness self-check: in a Gemini CLI session, verify §2.2 renders as a hard gate; the agent should branch before first code edit.

Follow-ups (Referenced for Graph Connectivity, Out of Scope)

• Optimize AGENTS.md + AGENTS_STARTUP.md startup-cache footprint (already tracked elsewhere per user — not filing a duplicate).

Origin Session ID: f018be49-cbf9-4f99-9119-2510fc5bb8d8 Discovered during: #10059 / PR #10060