계약: Spar 입력 형식

spar가 리뷰어 결과, 리뷰어 실행, 설정 파일, 명령 인자, 다시 읽는 기록에서 받는 입력 필드는 아래 표와 관점 규칙이 정한다. 표는 필드마다 받는 형식과 정규화, 형식 밖 입력의 결과, 그 규칙을 쓰는 곳(소비처)을 적는다. 받는 형식 밖의 입력은 표에 적은 결과로 끝나고, 다른 값으로 읽히거나 조용히 받아들여지지 않는다. 한 행의 소비처는 모두 같은 규칙을 쓴다. 검토 라운드, 검토 gate, Spar 설정은 각 필드의 형식을 이 표의 행으로 가리킨다. 아래 예시의 경로·이름은 합성이다.

1. 결과 이름#

2. 입력 형식 표#

관점 인자#

spar run에 --standpoint NAME=TEXT로 준다. 첫 =가 리뷰어 이름과 글을 나누며, 옵션을 여러 번 쓸 수 있다. 거부(65): 이번 실행의 설정과 --reviewers에 없는 이름, 한 리뷰어에 관점 둘 이상, 앞뒤 공백을 뗀 뒤 빈 글, 올바른 UTF-8이 아닌 글. 이름은 G20처럼 대소문자를 구분해 정확히 비교한다. =가 없거나 이름이 비면 사용법 오류(64)다. 두 거부 모두 리뷰어를 띄우거나 라운드 폴더를 만들기 전에 일어나며, 메시지에 문제의 이름이나 값을 보인다. 그 밖의 글은 받은 그대로 쓴다.

받는 이름은 설정된 리뷰어와 --reviewers로 고른 이름의 합집합이다. 이번 실행에서 빠진 설정된 리뷰어의 관점도 패킷에 남길 수 있으므로, 일부만 재실행할 때도 앞선 관점 목록 전체를 같은 순서로 넘긴다. 관점은 실행 인자로만 받고 사용자·프로젝트 설정 키는 없으며, spar config는 그대로다.

관점 전달#

공유 패킷의 ## Standpoints for this round 절에는 모든 관점과 리뷰어 배정이 들어간다. 리뷰어마다 자기 관점을 알리고 모든 각도를 확인하면서 그 위험을 공격하라는 지시도 받으며, 관점이 없는 리뷰어는 변경 전체를 검토하라는 지시를 받는다.

• claude와 codex는 지시와 패킷을 표준 입력으로 받는다.
• agy는 명령 안내, 지시, 패킷을 -p로 받으며, 큰 패킷이면 PACKET.md에 패킷을 두고 -p에는 명령 안내, 지시, 파일 안내를 둔다.
• command는 {prompt}로 리뷰어의 input.md를 받고, native는 prompt.md의 고정 지시 뒤에 관점 지시를 받는다.

관점이 있는 라운드는 실제 실행과 --dry-run 모두 리뷰어마다 그 리뷰어가 받는 입력을 그대로 <round>/<reviewer>/input.md에 남긴다. 큰 패킷을 받는 agy의 input.md는 -p 글이고, 패킷은 PACKET.md에 있다.

관점의 글과 배정은 패킷 안에 있으므로 packet_sha256이 같은 입력의 일부로 식별하며, 어느 하나라도 바꾸면 새 입력이다. 끝내지 못한 리뷰어만 다시 돌리고 단계, base, head와 packet_sha256이 같은 관점을 포함해 그대로이면 상한에 세지 않는다.

관점은 각도, 분류, 처리, 상한, gate의 상태와 사유를 바꾸지 않는다.

관점 보고와 기록#

standpoint_report는 관점 보고 객체다. checked는 불리언이고 detail은 공백뿐이 아닌 글이다. 참이면 확인한 것, 거짓이면 확인하지 못한 이유다. 관점을 받은 리뷰어의 보고가 없거나 null이거나 형식이 틀리면 invalid_output이고 이유에 standpoint_report가 들어가며, 관점이 없는 리뷰어에게는 보고를 요구하지 않는다. 관점이 없는 리뷰어의 standpoint_report는 확인하지 않고 null로 기록한다. 모든 preset에 spar run과 spar record --result 또는 --transcript가 같은 확인을 한다.

관점이 있는 라운드의 schema.json은 standpoint_report를 ["object","null"] 형식으로 더하고, 엄격한 schema를 쓰는 CLI를 위해 required에 넣는다. 객체의 키는 정확히 checked와 detail이며, 실행 시 확인은 관점 없는 리뷰어가 키를 빼거나 null을 쓰는 것도 받는다. claude preset의 --json-schema 인자도 그 라운드의 schema다. 관점이 없는 라운드에서는 이 키가 여전히 모르는 키이고 이전 schema가 그대로다. 형식에 맞는 checked: false 보고는 한계를 설명하며, 그 자체로 completed를 막지 않는다.

round.json은 standpoints에 reviewer/text 쌍, standpoints_uncovered에 완료한 리뷰어가 없는 관점의 리뷰어 이름, 리뷰어마다 standpoint와 standpoint_report에 글과 보고 또는 null을 남긴다. summary.md는 리뷰어마다 관점과 보고를 보이고, waive된 리뷰어를 포함해 완료한 리뷰어가 없는 관점을 보인다. 형식은 review-round/v1 그대로이며, 관점 필드가 없는 기록은 관점 없음으로 읽는다.

관점이 없으면 리뷰어 입력, schema.json, packet_sha256, summary.md는 바이트까지 그대로이고, 관점 지시와 input.md는 생기지 않는다. round.json에는 standpoints: []만 더해진다.

3. 위치·연결 문법#

G7과 G8이 같은 문법을 쓴다. 다른 것은 떼는 접두와 대상뿐이다.

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

• 공백은 유니코드 공백이다.
• 줄이 있는 참조의 경로는, 처음으로 :줄 또는 :줄대시줄 뒤에 끝이나 글의 끝이 오는 곳 앞까지다. 경로에 공백이 있어도 되고, 나머지에 다른 위치가 와도 경로는 그대로다.
• 그런 곳이 없으면 줄이 없는 참조다. 참조 전체가 대상이면 그것이 경로이고, 아니면 첫 단어가 경로다.
• 접두는 경로 앞에서 한 번만 뗀다. head/base/x는 G7에서 base/x, head/head/x는 head/x다.
• 경로를 정한 뒤 줄을 본다. 줄이 0이거나 범위의 뒤 줄이 앞 줄보다 작으면 G7에서는 읽을 수 없는 위치, G8에서는 확인되지 않은 연결이다. 경로를 읽는 방법은 줄 값과 관계없다.
• 사본의 파일과 폴더는 그 커밋 tree의 blob 항목(일반·실행 파일과 심볼릭 링크)과 그 위 폴더다. submodule(gitlink)은 사본에 없어서 위치 대상도 contract 연결 대상도 아니다.
• 위치 대상의 순서: 접두 없음은 head 사본, base 사본, 라운드 문서 순서이고, head/·./는 head 사본, 라운드 문서 순서이며, base/는 base 사본만 본다. 라운드 문서는 G26의 이름과 실제 절대 경로로 맞고, 파일 이름은 그 파일 이름의 라운드 문서가 하나일 때만 맞는다.

4. 읽을 수 없는 위치의 분류#

위치가 G7의 문법 밖이거나 대상이 없으면 그 지적의 위치를 읽을 수 없다. 리뷰어 결과는 버리지 않는다. 그 리뷰어의 상태는 다른 확인대로 정해지고(위치 때문에 invalid_output이 되지 않는다), 그 지적만 다음처럼 다룬다.

• path는 빈 값, in_check_paths는 false, location_unreadable은 true이고, 요약의 위치 칸에 (unreadable location)이 붙는다. class_reason은 unreadable location (<이유>)로 시작한다.
• 분류는 검토 라운드 6절의 분류 규칙 일곱 개 가운데 3(검사 경로의 requirement-question·hardening)과 6(연결이 확인되지 않은 defect 제안의 note)을 쓰지 않고, 1·2는 검사 경로 조건 없이 쓴다. 위에서 처음 맞는 것:
  1. check_impact가 false_pass나 meaning_inverted이면 defect
  2. check_impact가 contract_violation이고 연결이 확인되면 defect
  3. proposed_class가 requirement-question이면 requirement-question
  4. introduced_by_change와 regression이 모두 yes이면 defect
  5. 그 밖에는 proposed_class. 연결이 확인되지 않은 defect 제안도 defect다
• 자동 보류 원장 항목을 쓰지 않는다. 리뷰어가 hardening을 제안했으면 hardening으로 남되 처리가 없는 상태다. gate를 막지 않고 auto_deferred에 세지 않으며, 요약의 처리 칸은 -다.
• 실패의 방향: 잘못 읽힌 위치는 사람이 처리할 defect를 더 남길 수는 있지만, defect를 hardening이나 note로 숨기지 않는다. 위치가 어떻게 읽혔더라도(검사 경로 안이든 밖이든) defect가 됐을 지적은 defect다.

5. 거절 문구#

spar는 리뷰어의 표준 오류와 출력의 오류 메시지에서 아래 문구를 대소문자 없이 찾는다. 이 목록 밖의 메시지는 거절이 아니다(G13).

6. 대표 형식#

받는 형식은 위 표와 문법이 빠짐없이 정한다. 아래는 그 성질을 보이는 대표 예이고, 각 행의 소비처가 모두 같은 결과를 낸다. Go 테스트와 검사가 같은 예를 internal/spar/testdata/input-forms.json에서 읽는다.

G7 위치 (검사 경로 checks/**)#

읽을 수 없는 위치의 분류 (위치 head/checks/t.py:10:5)#

G8 연결 (규칙 문서: 두 줄짜리 AGENTS.md, 다섯 줄짜리 rules/API rules.md, 저장소 최상위 base/api.md; head 파일 contracts/x.md)#

G11 agy 셸 명령#

받는 형식은 2절의 G11 행이 빠짐없이 정한다. 아래는 그 대표 예이고 agy_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
• 받음(이전부터 받던 줄): 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
• 위반(괄호 안은 이유가 보이는 첫 문제): 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]($)
• 줄바꿈이 든 줄(예: ls 다음 줄에 rm -rf head)은 위반이고, 이유의 첫 문제는 줄바꿈이다.