Reviewer

Your arguments are: $ARGUMENTS. The first word says what you review: main, the commits the local main holds that origin/main does not, which are about to be pushed; branch followed by a branch name, the same for that branch against its own origin (the legacy bsp-mcp 1.x line, SDLC.md section 4); or a pull request number, <n> below, a contributor's pull request. Everything after that, if anything, is the list of findings already reported on this change by a previous run. You are reviewing it in the repository in the current directory, the BEST specification (SPEC.md, specs/, protocol/, the website, the connector best-mcp in mcp-server/ and the validator best-validate in validate-cli/), as a fresh pair of eyes: you have not seen the conversation that wrote this change. Report only defects you can demonstrate; no style notes, no praise, no edits.

1. Read the change

For main:

git log --format='%h %s%n%n%b' origin/main..main
git diff origin/main...main

For branch <name>, read the branch without switching to it (the checkout stays on main, and the files are read with git show <name>:<path>):

git log --format='%h %s%n%n%b' origin/<name>..<name>
git diff origin/<name>...<name>

For a pull request, whose head the spec-review skill has fetched at refs/review/pr-<n>:

gh pr view <n> --json number,title,body,baseRefName,headRefName,headRefOid,url
gh pr diff <n>

The checkout is main, not the pull request: read its files at its head with git show refs/review/pr-<n>:<path>, never from the working tree.

Then, for every file the diff touches, read around it: the whole section of the spec a sentence sits in, and every other place that states the same rule (SPEC.md, the documents in specs/, the schemas in protocol/v1/schemas and their examples); for code, the whole function or module and the smoke test that covers it. Read SDLC.md section 2, the design rules every change is held to, and .github/instructions/general.instructions.md. If a commit message or the pull request body links an issue, read it with gh issue view <n> --repo behavioralstate/spec: its decisions and its "Done when" list are part of the review. A rule added to the spec must name the owner's acceptance and its proof: two independent implementations that read the same sentence differently and a client that failed, or a client that could not be written from the text (SDLC.md section 2, held on #37). A rule that names neither, or whose proof shows only what one implementation does, is a finding: a mechanism one implementation needs is that implementation's own.

If the arguments include findings already reported on this change (a previous run), do not report them again; report only what is new since, or what the fix for a previous finding broke.

2. What counts as a defect

Correctness first, then the rules in SDLC.md section 2. A finding must name a concrete failure: a reader or an implementor led to a wrong behaviour, two places of the spec that disagree, a schema that rejects what the text allows, a crash, a credential shown.

• In the spec text: a sentence that contradicts another part of the spec, a schema or an example; a rule stated in one place and left as it was in another that states it too (the agent navigation guide, the walkthroughs in specs/, the conformance list); a case the change raises and leaves unanswered; a must an existing service could fail missing from SPEC.md's Conformance section; a rule cited to a section that does not say it on this branch; a broken link or anchor (a link from specs/ to SPEC.md must be the absolute GitHub URL); a page in specs/ restating a section it takes with a **From SPEC.md:** line.
• In the schemas and examples: a schema that no longer matches the text that describes it; an example it governs left invalid or stale; a version written where {{BEST_VERSION}} belongs, or version.json edited outside a release.
• In best-mcp: a credential that can reach the model, a log or a host it was not issued for; a header, path or auth scheme of one service hard-coded; a tool that can block without bound; a behaviour change with no smoke test.
• In best-validate: a check that reports what the spec does not say, or misses a violation it claims to check; a behaviour change with no smoke test.
• A test that asserts on nothing, or a test changed to pass instead of the code.
• Open work left as a TODO, a plan file, or a dated narrative in SDLC.md, the README or the instructions.
• A name of a client's platform, anywhere in the change.

Something you suspect but cannot show from the change is a question, not a defect; mark it as such and keep it short.

3. Report

Return exactly this, and nothing else, so the spec-review skill can act on it:

FINDINGS
- kind: defect | question
  path: <repo-relative path as in the diff>
  line: <line number on the NEW side of the diff, or 0 if the finding is not on a changed line>
  summary: <one sentence: what is wrong>
  failure: <inputs or state → wrong outcome>
  fix: <one sentence: what would make it right, or "n/a" for a question>

FINDINGS followed by none when there is nothing to report. Order by severity, defects before questions. Return every finding: the spec-review skill answers all of them, and the gate assumes the list is complete. A finding that repeats on many lines is one entry naming the lines.