Make agent commit-type selection ordered and locally enforced

Context

The pull-request workflow's Conventional Commit guidance has now produced the same classification correction twice.

• #10061 added the current Type Selection rule after an agent initially chose chore for a capability-bearing harness change that required feat.
• PR #16110 initially published exact head cc7090f85d04c7aa6e49609b2b785be039d5bea5 as fix(memory-core): make summary receipts replayable (#16105). The patch adds a durable replay capability, so the operator challenged the type and the branch was corrected to feat before review.

The rule currently says both "fix restores broken behavior" and "new capability → feat; ambiguous → feat". A bug repaired by introducing a new recovery path satisfies both sentences. The agent can therefore obey one sentence while violating the intended precedence.

Friction record:

• Task: finalize an agent-authored PR.
• Rule: select feat, fix, or chore in .agents/skills/pull-request/references/pull-request-workflow.md §3.1.
• Cost: metadata correction, history rewrite, force-push, and a full CI restart after the implementation was already green except for its final unit job.
• Safer alternative: one ordered semantic contract plus a local preflight that checks the declared change class against both intended subjects before commit or PR creation.

The Problem

The existing rule describes three categories but does not resolve their overlap. "Restores broken behavior" is about the reason work started; "enables a new capability" is about the delivered delta. Many resilience, recovery, migration, and tooling changes are bug-motivated but introduce a capability that did not previously exist.

buildScripts/util/agent-preflight.mjs already validates source gates and PR-body anchors, but its CLI accepts neither an intended commit subject nor a semantic change class. It can therefore report a complete preflight while the commit and PR title use the wrong Conventional Commit type.

This is not the general commit-safety problem tracked by #9844, and it is not the syntax-only Conventional Commits RFC from #3191. The failure is the semantic mapping from delivered delta to type.

The Architectural Reality

• .agents/skills/pull-request/references/pull-request-workflow.md §3.1 owns the agent-facing type-selection contract.
• buildScripts/util/agent-preflight.mjs is the existing local repair/check entry point before commit and PR creation.
• test/playwright/unit/ai/buildScripts/util/agent-preflight.spec.mjs is the existing focused test surface.
• ADR 0008 applies because the workflow is skill substrate. This ticket is a rewrite of an existing conditional payload section plus mechanical enforcement; it adds no new skill, router, or always-loaded rule body.
• npm run --silent ai:structure-map -- --files --loc was run before creation. No new .mjs placement is proposed: the implementation stays in the existing buildScripts/util/ helper and its existing unit-spec sibling.

The Fix

1. Replace the overlapping bullets with one ordered change-class contract:
   • capability → feat: the system gains a reusable, operable, or separately testable behavior/path that did not exist before, even when a bug motivated it;
   • restoration → fix: an already-defined capability is corrected without adding a new capability surface;
   • zero delta → chore: no behavioral or capability change.
2. Extend agent-preflight with explicit inputs for the declared change class, intended commit subject, and intended PR title. Fail locally when either subject's type does not match the declared class.
3. Keep semantic judgment visible and honest: the tool validates the author's explicit classification; it must not infer type from issue labels, filenames, or diff size.
4. Add regression fixtures for the #10061 (chore → feat) and PR #16110 (fix → feat) failure shapes, plus valid fix and chore controls.
5. Update the pull-request workflow's pre-commit example to invoke the guard before the first commit and again against the final PR title. Do not add a generic PR-body section or new always-loaded substrate.

Contract Ledger Matrix

Decision Record impact

aligned-with ADR 0008 — the change rewrites an existing conditional skill payload and adds enforcement in the existing build helper. No router growth, new skill, or Map/World-Atlas relocation is needed.

Acceptance Criteria

• Type selection is an ordered decision with an explicit outcome when bug motivation and new capability overlap.
• agent-preflight rejects fix for a declared capability delta and rejects chore for capability or restoration deltas.
• The same declared class is checked against both the intended commit subject and PR title.
• Valid feat, fix, and chore controls pass.
• Regression fixtures cover the exact #10061 and PR #16110 misclassification shapes.
• The guard never derives semantic type from GitHub issue labels, filenames, or changed-line counts.
• The pull-request workflow and CLI help describe one matching contract without duplicating a large rule body.
• The PR carries the required source-ticket Contract Ledger comment and /turn-memory-pre-flight load-effect audit for skill-substrate changes.

Out of Scope

• Reclassifying historical commits or PRs.
• Changing issue-label taxonomy or mapping bug directly to fix.
• Adding an LLM classifier to commit hooks.
• Replacing Conventional Commits or changing release-version semantics.
• Implementing the broader autonomous CommitGate from #9844.
• Further changes to PR #16110, which is already corrected.

Avoided Traps

• Infer from the ticket label. PR #16110 is a bug ticket whose delivered delta is still a new replay capability.
• Add prose only. #10061 already added prose; the recurrence proves a forcing function is needed.
• Syntax-only commitlint. It can validate fix(scope): ... as well-formed while the semantic type remains wrong.
• Infer from file additions or diff size. A small new helper can be a fix; a large rewrite can preserve behavior. Those signals are not the contract.
• Add PR-body ceremony. The decision belongs in the preflight invocation and existing conditional workflow payload, not a new universal body section.

Duplicate / Claim Sweep

Live latest-open sweep: checked the latest 20 open GitHub issues immediately before creation; no equivalent found.

A2A in-flight sweep: checked the latest 30 messages across read states immediately before creation; no competing commit-type-classification claim found.

Targeted GitHub, repository, and Knowledge Base sweeps found #10061, #3191, and #9844 as adjacent prior art, not active duplicates.

Related

Related: #10061 Related: #3191 Related: #9844 Related: #16105

PR evidence: #16110

Origin Session ID: 019fa530-53d6-7271-bf05-51497720b29c

Handoff Retrieval Hints:

• query_raw_memories("PR #16110 fix feat commit type correction friction")
• Original misclassified head: cc7090f85d04c7aa6e49609b2b785be039d5bea5
• Corrected head at ticket creation: d658b8f5235052de175d8c4dc9704e42d434c32a

Authored by Euclid (GPT-5 Codex, Codex Desktop). Session 019fa530-53d6-7271-bf05-51497720b29c.