hmc-mcp AGENTS.md

AGENTS.md

Non-interactive shell discipline

All shell commands must be non-interactive. A command that opens an editor, a pager, or a prompt will stall the agent with no recovery path.

git

• Always set GIT_EDITOR=true when a git command may open an editor:

  GIT_EDITOR=true git rebase --continue
  GIT_EDITOR=true git commit --amend
  GIT_EDITOR=true git merge --continue
  

• Prefer --no-edit on commit --amend and merge when the message is unchanged.
• Never run git rebase --continue without GIT_EDITOR=true — the continue step opens the editor to confirm the commit message even when there are no remaining conflicts.
• Suppress the pager: git --no-pager <subcommand> or set GIT_PAGER=cat.
• Never squash-merge (gh pr merge --squash / git merge --squash) unless the PR is documentation-only. Squash merges collapse commit history and break git bisect. Use --merge (merge commit) for all code, test, config, and script changes.
  • Documentation-only means no changed file's content is asserted by a test or a static gate. Content, specifically: repo-wide scans like just secrets read every tracked file, and counting those would make the exception dead.
  • Decide it by reading, not by a pattern or a grep. Both have been tried here and both are unsound, because the guards reach their files three different ways: by literal path, by basename (tests/test_project_metadata.py opens ROOT / "docs" / "hmc-cli-cheatsheet.md"), and by directory — scripts/gen_tool_reference.py writes _REPO_ROOT / "docs" / "tools" and scripts/check_adr_numbering.py globs docs/adr/*.md, so no search for a path or a filename can see those at all. Work from this floor instead:
    • Content-asserted: docs/tools/ (diffed by just tool-docs-check), every page carrying a generation banner (regenerated and diffed by just doc-freshness), docs/environment-variables.md (checked field by field by just env-vars), docs/hmc-cli-cheatsheet.md and docs/authorization-audit.md (opened by tests/), ADR 0029's inventory block (parsed by tests/unit/test_public_api.py), and CHANGELOG.md, CONTRIBUTING.md, README.md, SECURITY.md.
    • Name-asserted only: just adr-numbering checks an ADR's filename and H1, never its body — so editing an ADR's prose is not caught by that gate. Most ADRs are in this class, which is why a prose-only ADR edit is one of the few real documentation-only changes here.
    • Content-unasserted today: the docs/plan-*, docs/spec-*, docs/scorecard-*, docs/workflow/ and docs/superpowers/ pages. Test modules cite some of those specs in module docstrings, which asserts nothing about the file. just doc-freshness does read every tracked Markdown file's first line, looking for a generation banner — so a page here can still redden it by opening with something banner-shaped, but its body is unchecked.
  • When the answer is not obvious, use --merge. It costs one merge commit. A wrong --squash is not reversible once it is on main.
  • Two shell mechanics, for whatever check you do write over gh pr diff <PR> --name-only: grep -Ev exits 1 when it filters every line out, so a naive … | grep -Ev '…' reports failure on exactly the empty-result case and is fatal under set -e or inside an && chain; and a failed gh pr diff — wrong number, expired auth — prints nothing, which looks identical to a clean pass. Check its exit status before reading its output, and treat an unanswered query as "not documentation-only".
  • The policy is prose, not a gate: nothing in the repo enforces it — rg -ni squash over .github/, tests/, scripts/, justfile, and .pre-commit-config.yaml returns nothing. Your own reading before the merge is the only control.
  • A single-parent commit on main is not evidence of a squash. This repo has also landed PRs with --rebase, which replays each commit onto main and preserves the per-commit history the policy protects — PR #455's seven commits landed that way as aec6125^..f528e94. To tell a squash from a rebase, compare the commit's own diff with the PR's: on a squash they are equal, on a rebase the commit carries only its own slice. This paragraph is forensic — how to read history after the fact. It is not a second blessed strategy: the rule above still says --merge, and whether --rebase should join it is open in #530.