Codetrial Conventions

CodeTrial conventions

The gate settles formatting and correctness. cargo fmt, Prettier, ESLint, ruff and shellcheck run in scripts/test.sh, so none of that is here. What is here is what a reviewer would otherwise have to say out loud, plus the rules the git hooks enforce, so an agent knows them before a hook refuses. Install them with make hooks.

Two tracked files carry the rest, and this one restates neither. README.md wins on what the project is and how it runs. CONTRIBUTING.md is the public half of the rules below, the commit message, the issue and pull request register, and the branch a pull request comes from, and it wins where the two disagree. Read it. What is left here is the agent's half: the calibration this tree's own log gives, which repository gh is pointed at, how drafted text reaches it, and what needs the user's approval first.

Commit messages

./scripts/git-commit-msg.sh --rules prints what the hook enforces, and CONTRIBUTING.md says what the body has to carry. Neither gives the calibration, so run this when a subject is hard to fit:

git log --no-merges --format=%s | awk '{print length}' | sort -n

Prose register

Markdown files are exempt from the ASCII rule and use ordinary GitHub Markdown, so a backtick belongs in docs/ and not in a commit subject.

Chinese, and CJK generally, stays out of src/, web/ and tests/ even when the conversation that produced the change was in Chinese. The product's surfaces are English. A test that genuinely needs multi-byte input to pin a character-boundary rule should use characters that read as a fixture rather than as prose in any language: Greek letters, accented Latin, an emoji. Say in the comment that the byte width is the point.

Comments

Every line of a comment says something the code cannot, and this tree carries long ones where the reasoning is long. Delete anything restating the statement below it.

• Bad: let deadline = start + duration; // add the duration
• Good: let deadline = start + duration; // truncated to whole minutes above, so the page and the interviewer end at the same number

Never point a comment, a docstring or a docs/ page at TODO.md. It is untracked and per-developer, so the reference dangles for everyone else. Code may name the path where it genuinely reads the file, and a runtime diagnostic may print it so the reader can navigate.

Working docs at the repo root

TODO.md, DONE.md and CLAUDE.md are excluded through .git/info/exclude, not through .gitignore, because the exclusion is one person's habit and .gitignore would push it onto everybody. Never git add, stage, commit or delete them, and never assume a clone has them. Reports and analyses stay out of the tree the same way: a scratch directory, not a new tracked file.

Contracts that refuse a change

CONTRIBUTING.md names the owning documents and the rule that a document refusing your change is the answer rather than an oversight. Two things it does not say.

Never restate one of these rules from memory or from this file: a paraphrase drifts, and the document is what binds.

And what being refused looks like. "Persist the finished session and regenerate the report later" reads as an obvious improvement, and the caching rule in docs/provider-cost-and-degradation.md refuses it. The move is to propose changing that document on purpose, with the reason, or to leave it alone.

Deleting a surface

In CONTRIBUTING.md, together with the compatibility promise it answers to.

GitHub issues and pull requests

CONTRIBUTING.md has the register, the titles, the bodies, the redaction rule and the branch rules. What follows is only what an agent needs on top of them.

Conversation may use the contributor's language; everything posted to GitHub is clear English, with identifiers and error messages kept verbatim. The target is sysprog21/codetrial; pass --repo sysprog21/codetrial to gh, because on a fork or a copy the checkout's default resolves elsewhere.

A vulnerability report goes to the user to hand to a maintainer, never into a public issue. A public thread may carry a request for a private contact and nothing else.

Nothing is written to GitHub until the user has approved the exact text, by saying yes to it or by dictating it and asking for it to be posted. The approval covers the writes shown. Approving a PR submission also covers later fix pushes to that branch and the review replies gh-submit makes while getting its checks green; any other comment, edit, close or merge needs its own.

Never paste drafted text into shell source, where backticks and $() in a quoted error would run. Write the body to a UTF-8 file in a scratch directory with a file tool and pass --body-file; put the title in a file too and pass --title "$(cat "$SCRATCH/title.txt")". Read the result back, and after a timeout check whether the write landed before retrying.

Drafting an issue or PR body, or planning a first contribution, is codetrial-contribute. Reviewing the backlog for duplicates and incomplete reports, and sweeping the open pull requests, is codetrial-triage. Approving a held workflow run, resolving an outdated review thread, hiding a superseded review and posting its fixed rebase request need no per-thread approval of text; that skill says when a sweep applies them without a separate confirmation.