---
id: 10061
title: 'Agent protocol hardening: commit-format Pre-Flight gate, harness branch acceptance, and memory-file mapping'
state: CLOSED
labels:
  - documentation
  - enhancement
  - contributor-experience
  - ai
assignees:
  - tobiu
createdAt: '2026-04-18T14:22:17Z'
updatedAt: '2026-04-18T15:19:30Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10061'
author: tobiu
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-18T14:41:56Z'
---
# 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

## Timeline

- 2026-04-18T14:22:18Z @tobiu added the `documentation` label
- 2026-04-18T14:22:18Z @tobiu added the `enhancement` label
- 2026-04-18T14:22:19Z @tobiu added the `contributor-experience` label
- 2026-04-18T14:22:19Z @tobiu added the `ai` label
- 2026-04-18T14:35:20Z @tobiu referenced in commit `b0817d7` - "feat(agents): Pre-Flight Gate 3 + harness-aware branching + memory-file wiring (#10061)

- AGENTS.md §3: add Gate 3 (Commit Format) to the Pre-Flight Check,
  delegating to the pull-request skill for detailed rules
- pull-request-workflow.md §2: refactor into §2.1 worktree-isolated
  (Claude Code), §2.2 shared-checkout (Gemini CLI / Antigravity),
  §2.3 universal safety net — reflects mechanical harness differences
- pull-request-workflow.md §3: add §3.1 Type Selection (feat/fix/chore
  criteria + decision rule), §3.2 Commit Message Hygiene (forbid
  noreply co-authors, mandate (#N) in subject), §3.3 Steps
- AGENTS_STARTUP.md §5: add Harness Memory-File Wiring subsection
  listing Claude Code and Gemini CLI auto-load conventions"
- 2026-04-18T14:35:54Z @tobiu cross-referenced by PR #10062
- 2026-04-18T14:41:56Z @tobiu referenced in commit `a77926a` - "feat(agents): Pre-Flight Gate 3 + harness-aware branching + memory-file wiring (#10061) (#10062)

- AGENTS.md §3: add Gate 3 (Commit Format) to the Pre-Flight Check,
  delegating to the pull-request skill for detailed rules
- pull-request-workflow.md §2: refactor into §2.1 worktree-isolated
  (Claude Code), §2.2 shared-checkout (Gemini CLI / Antigravity),
  §2.3 universal safety net — reflects mechanical harness differences
- pull-request-workflow.md §3: add §3.1 Type Selection (feat/fix/chore
  criteria + decision rule), §3.2 Commit Message Hygiene (forbid
  noreply co-authors, mandate (#N) in subject), §3.3 Steps
- AGENTS_STARTUP.md §5: add Harness Memory-File Wiring subsection
  listing Claude Code and Gemini CLI auto-load conventions"
- 2026-04-18T14:41:56Z @tobiu closed this issue
- 2026-04-18T14:57:24Z @tobiu cross-referenced by #10063
- 2026-04-18T15:19:30Z @tobiu assigned to @tobiu

