Contract: Spar input formats

한국어 · English

This is a translation of the Korean original. Where the two differ, the Korean original decides.

The table and standpoint rules below define the input fields that spar accepts from reviewer results, reviewer runs, configuration files, command arguments and records it reads back. For each field, the table states the accepted format and its normalization, the result for input outside the format, and where the rule is used (consumers). Input outside the accepted format ends with the result given in the table; it is never read as another value or silently accepted. All consumers of a row use the same rule. Review round, Review gate and Spar configuration point to the rows of this table for the format of each field. The paths and names in the examples below are synthetic.

1. Result names#

2. Input format table#

Standpoint arguments#

Pass --standpoint NAME=TEXT to spar run. The first = separates the reviewer name from the text; the option may be repeated. Refused (65): a name outside this run's configured reviewers and --reviewers, more than one standpoint for a reviewer, text empty after trimming whitespace, or invalid UTF-8. Names are compared exactly and case-sensitively, as in G20. A missing = or an empty name is a usage error (64). Both refusals happen before any reviewer starts or any round folder is created; the message names the offending name or value. Other text is kept unchanged.

The accepted names are the union of the configured reviewers and the names selected by --reviewers. A configured reviewer omitted from this run may still have a standpoint in the packet; when rerunning a subset, pass the full earlier list of standpoints in the same order. Standpoints are run arguments only, with no user or project configuration key; spar config is unchanged.

Standpoint delivery#

The shared packet's ## Standpoints for this round section contains all standpoints and their reviewer assignments. Each reviewer also receives an instruction identifying its own standpoint and asking it to attack that risk while still checking every angle; an unassigned reviewer is told to review the whole change.

• claude and codex receive the instruction and packet on standard input.
• agy receives the command note, instruction and packet in -p; for a large packet, PACKET.md holds the packet and -p holds the command note, instruction and file reference.
• command receives the reviewer's input.md through {prompt}; native receives the instruction after its fixed instructions in prompt.md.

For a round with standpoints, both a real run and --dry-run leave in <round>/<reviewer>/input.md exactly the input that reviewer receives. For agy with a large packet, input.md holds its -p text and the packet is in PACKET.md.

Standpoint text and assignments are in the packet, so packet_sha256 identifies them as part of the same input; changing either makes a new input. A rerun of only unfinished reviewers is not counted when stage, base, head and packet_sha256 are unchanged, including the same standpoints.

Standpoints do not change angles, classification, dispositions, caps or the gate's state and reasons.

Standpoint reports and records#

standpoint_report is an object with two fields. checked is a boolean and detail is nonblank text: what was checked when true, or why it could not be checked when false. For an assigned reviewer, a missing, null or malformed report is invalid_output, with standpoint_report in the reason; an unassigned reviewer need not report one. An unassigned reviewer's standpoint_report is not checked and is recorded as null. Every preset uses the same check in spar run and spar record --result or --transcript.

In a round with standpoints, schema.json adds standpoint_report with type ["object","null"] and includes it in required for CLIs that enforce a strict schema. The object has exactly checked and detail; the runtime check allows an unassigned reviewer to omit the key or use null. The claude preset's --json-schema argument is this round's schema. In a round without standpoints the key remains unknown and the earlier schema is unchanged. A valid checked: false report explains a limit; it does not by itself prevent completed.

round.json keeps standpoints as reviewer/text pairs, standpoints_uncovered as reviewer names without a completed reviewer, and each reviewer's standpoint and standpoint_report as text/report or null. summary.md shows each reviewer's standpoint and report, and standpoints without a completed reviewer, including waived reviewers. The schema remains review-round/v1; records without standpoint fields mean no standpoints.

Without standpoints, reviewer inputs, schema.json, packet_sha256 and summary.md remain byte for byte unchanged; no standpoint instruction or input.md is added. Only standpoints: [] is added to round.json.

3. Location and link grammar#

G7 and G8 use the same grammar. Only the removed prefixes and the targets differ.

참조   = 앞뒤 공백을 뗀 글
       = 접두? 경로 (":" 줄 (대시 줄)?)? (끝 나머지)?
접두   = G7: "head/" | "base/" | "./"      G8: "head/" | "./"     (앞에 있는 하나만, 한 번)
줄     = ASCII 숫자 하나 이상
대시   = "-" | "–"
끝     = 공백 | "," | ";"                    (줄 뒤에만. 줄 뒤의 그 밖의 문자는 문법 밖)
나머지 = 아무 글

• Whitespace is Unicode whitespace.
• In a reference with a line, the path runs up to the first place where :줄 or :줄대시줄 is followed by an end or by the end of the text. The path may contain whitespace, and another location in the rest leaves the path as it is.
• When there is no such place, the reference has no line. If the whole reference is a target, it is the path; otherwise the first word is the path.
• The prefix is removed from the front of the path only once. head/base/x is base/x in G7, and head/head/x is head/x.
• Lines are checked after the path is settled. A line of 0, or a range whose end line is less than its start line, is an unreadable location in G7 and an unconfirmed link in G8. How the path is read does not depend on the line values.
• The files and folders of a copy are the blob entries of that commit's tree (regular and executable files and symbolic links) and the folders above them. A submodule (gitlink) is not in the copies, so it is neither a location target nor a contract link target.
• Order of location targets: with no prefix, the head copy, the base copy, then the round documents; with head/ or ./, the head copy, then the round documents; with base/, only the base copy is looked at. A round document matches by its G26 name and its real absolute path, and by its file name only when one round document has that file name.

4. Classifying an unreadable location#

When a location is outside the G7 grammar or has no target, that finding's location cannot be read. The reviewer result is not discarded. That reviewer's status is set by the other checks (the location never makes it invalid_output), and only that finding is handled as follows.

• path is empty, in_check_paths is false, location_unreadable is true, and (unreadable location) is added to the location column of the summary. class_reason starts with unreadable location (<이유>).
• Of the seven classification rules in Review round section 6, classification does not use 3 (requirement-question and hardening in check paths) and 6 (note for a proposed defect whose link is not confirmed), and uses 1 and 2 without the check-path condition. The first match from the top:
  1. defect if check_impact is false_pass or meaning_inverted
  2. defect if check_impact is contract_violation and the link is confirmed
  3. requirement-question if proposed_class is requirement-question
  4. defect if introduced_by_change and regression are both yes
  5. Otherwise proposed_class. A proposed defect whose link is not confirmed is also defect
• No automatic deferral ledger entry is written. When the reviewer proposed hardening, the finding remains hardening with no disposition. It does not block the gate and is not counted in auto_deferred, and its disposition column in the summary is -.
• Direction of failure: a misread location can leave more defect findings for a person to handle, but it never hides a defect as hardening or note. A finding that would have been defect however its location was read (inside or outside the check paths) is defect.

5. Refusal phrases#

spar looks for the phrases below, ignoring case, in the reviewer's standard error and in the error messages of its output. A message outside this list is not a refusal (G13).

6. Representative forms#

The table and grammar above define the accepted formats completely. Below are representative examples that show their properties, and all consumers of each row give the same result. Go tests and checks read the same examples from internal/spar/testdata/input-forms.json.

G7 locations (check path checks/**)#

Classifying an unreadable location (location head/checks/t.py:10:5)#

G8 links (rule documents: a two-line AGENTS.md, a five-line rules/API rules.md, base/api.md under the repository root; head file contracts/x.md)#

G11 agy shell commands#

The G11 row of section 2 decides the accepted forms in full. These are representative examples; agy_commands holds the same lines.

• Accepted (lines that join read-only commands): ls -la && ls -la head base, ls -la && ls -la head/ && ls -la base/, pwd && ls -la, diff -u base/a.md head/a.md; diff -u base/b.md head/b.md, diff -u base/plugins/seal/ head/plugins/seal/ ; diff -u base/plugins/spar/ head/plugins/spar/, ls -la head/tools/goal-checks 2>&1 || true, grep -rn x head | head -20 && wc -l head/a.go, grep -n "a && b; c" head/a.go, grep -c '|' head/a.go || true, sed -n '1,20p' head/a.go && sed -n '/func/,/^}/p' head/b.go, ls head;ls base
• Accepted (lines accepted before): ls -la head, grep -rn foo head | head -20, sed -n '1,40p' head/a.go, find head -name '*.go', grep -o foo head/a, grep -rn greet head 2>/dev/null, cat head/app/main.go 2>&1, sed -n -e '1p' -e '/x/,/y/p' head/a, grep -n '$HOME' head/a, grep -n "\$x" head/a, grep -n "foo$" head/a.go, grep -c x$ head/a.go, sed -n -- '1p' head/a, /bin/ls -la head, /usr/bin/grep -rn x head
• Violations (the first problem the reason names in parentheses): cd head && go test ./... (cd), ls; touch x (touch), grep x head/a 2>/dev/null; touch pwn (touch), git diff --no-index --stat base head (git), diff -r -u base head | diffstat (diffstat), python3 head/tools/check.py head (python3), PYTHONDONTWRITEBYTECODE=1 python3 -c 'print(1)' (PYTHONDONTWRITEBYTECODE=1), git --git-dir=/dev/null grep -n x head/ || grep -rn x head/ (git), (cd head && go test ./...) ((), (ls) ((), for f in head/*.json; do cat "$f"; done (for), ls & (&), ls |& cat (|&), && ls (&&), ls && (&&), ls ;; ls (;;), ls ; ; ls (;), cat a > b (>), ls 2> x (>), echo $(id) ($(), cat <(ls) (<(), ls `id` (`), ls head && find head -delete (-delete), ls && sort --compress-program=sh head/a (--compress-program=sh), find head $'-exec' sh -c id {} + ($), find head ${X:--exec} sh -c id {} + ($), find head {-exec,} sh -c id {} + ({), cat "$HOME/.netrc" ($), ls head/{a,b} ({), sed -n -e '1p' -e 'e python3 -V' head/a (e python3 -V), sed -n --expression='e id' head/a (e id), sed -n '1p' -f x.sed head/a (-f), sed -n -i '1p' head/a (-i), sed '1,2p' head/a (sed), head/bin/ls -la (head/bin/ls), ./ls head (./ls), /tmp/x/cat head/a (/tmp/x/cat), ls x$y ($), sed -n 'w pwn' -e '1p' head/go.mod (-e), rg --hyperlink-format=default --hostname-bin=python3 x head (--hostname-bin=python3), ls $[1+1] ($)
• A line with a newline (for example ls with rm -rf head on the next line) is a violation, and the first problem in its reason is the newline.