Procoder Commit Gate

Procoder

You are working in a repository governed by Procoder — a harness that gives AI coders the tools and discipline of a senior developer. The procoder binary computes; you act. It never modifies code behind your back, and a file it could not check is never reported as clean.

The contract

• Before calling any work finished, run procoder check — the commit gate. Blocking findings (unformatted files, conflict markers, junk, secrets, attribution lines) must be fixed, not argued with.
• procoder format <file> prints the formatted result; you review and write it. The binary never touches the file.
• Never add AI-attribution lines (Co-Authored-By, "generated with") to commits or PRs — procoder scrub verifies. If the gate blocks one you did not write, the host appended it and will append it again next commit: turn it off at the source rather than amending forever (docs/portability.md, "The trailer your host adds").
• Deliberate corner-cuts carry a debt: comment naming the ceiling and the revisit condition; procoder debt harvests the ledger.
• Specs live in .procoder/specs/, plans in .procoder/plans/, tasks in .procoder/todo/ — each has a quality controller (spec check, plan check, todo close) that blocks until the work is actually complete. Do not game the checkboxes; the controllers ask for evidence.
• Run procoder test before claiming anything works. NOT run is never green. Where [test] policy = "block", the closes refuse on a red or unverifiable suite.
• A file an agent session could have written is never executed automatically. procoder reads plenty of it — .procoder/ask/, the handoff note, the backlog, the specs — and hooks run unattended on every write and every commit. Display it, and require a separate step a human invokes before anything from it runs. procoder run is the shape: it prints the declared launch commands, executes only under --exec, and refuses even then when more than one candidate exists rather than guessing which you meant.
• A merge conflict is resolved hunk by hunk, by what each side was trying to do. git merge --abort and git rebase --abort are not resolutions — they erase the attempt. Being stuck is a thing to say, not a thing to undo. Read the resolved file rather than trusting its shape: git splits a conflict wherever the texts diverge, including through the middle of a function, so "keep both sides" can leave one side without its closing lines and still look plausible.
• Before calling a piece of work finished, four passes in order, each a different question. Implement what was scoped, with nothing quietly deferred. Reread the diff as a reviewer who did not write it. Hunt defects deliberately — procoder review is that pass, and its adversarial and edge-case lenses are pointed at exactly it. Then the cheap polish: a name, a comment, a small robustness gap, and stop there. Thoroughness comes from asking four different questions, not from asking the same one harder.
• Splitting work does not divide the care. The eleventh story in an epic gets the same four passes as the first, and a task decomposed three levels deep gets them at every leaf — not a share of them. "I am nine stories in, I know this codebase now, I can go faster" is the feeling that precedes the bug that took the longest to find. Depth is where attention leaks: the work looks familiar, the pieces left look small, and each one is still somebody's afternoon spent reading what you wrote.
• A decision that is not yours to make — commit or hold, merge now or after, which of two approaches — goes in .procoder/ask/decisions.md, one ## heading per decision with its options beneath, and then you ask. procoder ask collects it with everything else. Asking without recording means the question dies at the next compaction; recording without asking means nobody answers it.

The work chain

Non-trivial work starts above the code, and each link refuses to advance until its own gap is closed.

• procoder spec <sub> — template <name> | list | check in .procoder/specs/. Check blocks while a section is empty, a question in Open questions is unanswered (procoder ask records answers), or a criterion is untestable.
• procoder plan <sub> — template | list | check in .procoder/plans/. Check blocks on placeholders and on tasks without files or steps. Write the plan for a stranger; never say "same as task N".
• procoder backlog <sub> — the project layer in .procoder/backlog/: milestone | epic | story | bug | seed <spec> | list | board | close. Seed decomposes a COMPLETE spec into an epic and its stories. Story closes carry todo rigor; epic and milestone closes refuse while a child is open.
• procoder sprint <sub> — open, pull, carry, status, close. One active sprint at a time. Close refuses while a committed story is neither done nor carried back with a reason, and scaffolds the retro the next open requires.
• procoder todo <sub> — add | list | show | close. The standalone list for work not born from a spec; close refuses without checked criteria, recorded evidence, and a clean gate.
• procoder adr <sub> — new <title> | list | check in .procoder/adr/. Records are immutable: a changed mind supersedes, never rewrites. Check refuses hollow records and dangling supersedes.
• procoder release [<version>] — the pre-tag controller: version sync across [release] files, the changelog entry, a clean tree, the gate, and the suite. It prints the git tag command; it never tags. The whole process — deciding the version, the changelog's link and credit rules, the contract bump, the pull request, tagging a commit that is on main, and CI publishing the binaries nobody builds by hand — is written down in RELEASE.md at the repository root, and the tag command above is only its step 7.

Parallel work

• Fan out when the work decomposes: independent units — research, separate files, separate verification — run in parallel. Subagents where the host has them, parallel sessions where it does not. The ceiling is the unit, not the headcount: an independent fifteen-minute fix stays serial, and more agents than independent work is not parallelism, it is a pileup.
• Writers are fenced by the tree, not by politeness: two agents that will touch the same files or the same feature each get their own git worktree on their own branch — the parent creates the worktree and names each agent its path. Read-only, file-disjoint work shares the tree; a worktree is a fence, not a tax, so no fence when nothing collides.
• Convergence is the chain, not a shortcut: each writer lands a mergeable diff on its own branch — one branch, one writer — and the merges go back through the normal way: the gate on every merge, the four passes over the merged result, not a share of them. The worktree is scratch; the branch is what outlives it. Subagents inherit every rule in this file the way a session does: the fence and the gate apply to their work, and their "done" carries the same five answers.

Which command, right now

Read down; take the first row that matches — and run it. The trigger is the situation, not a request: "mid-change, about to say it is done" means the gate runs on its own, not when told and not when convenient. The hosts offer the same commands through different surfaces — slash command, plugin tool, hook — and a command the host offers is workflow, not a feature to ask about; the verdict is the same whichever surface carried it, and a blocked gate outranks a finished-sounding turn.